This PR:
- Add `.github/workflows/agent-substrate.yml` running `pnpm
validate:agent-skills` and `pnpm validate:skill-routing` on every push
and pull request; both validators previously ran in no CI workflow
- No path filters on the trigger: the stale-guidance walk scans every
text file in the repo, so any change can affect the result (PR runs
restore caches but only `next` pushes save them, per the
`setup-node-pnpm-bun` guidance)
- Skip `vendor/` directories in the `validate:agent-skills`
stale-guidance walk, which was failing on read-only third-party
snapshots mentioning other tools' rule conventions
- Extend the validator's command scan to `CONTRIBUTING.md` (with a `pnpm
dlx` exemption), so its documented commands are checked against
`package.json`, `python/Makefile`, and `python/noxfile.py` like the rest
of the guidance
- Point the routing-test header, root `AGENTS.md`, and
`skill-maintenance` reference docs at the new workflow, and add a
"Working with AI Coding Agents" section to `CONTRIBUTING.md` covering
the inherited agent setup, the two checks, and the routing-probe
requirement for skill edits
## Context
These two validators are the only checks keeping repo-level agent
guidance honest: command names mentioned in guidance are verified
against `package.json`, `python/Makefile`, and `python/noxfile.py`, and
routing probes assert each skill stays the unique top match for its
representative task. Until now nothing enforced either one, and the
stale-guidance walk was already red on vendored trees — a failure no
guidance owner could fix, which trains people to ignore the check. This
makes both checks blocking everywhere they can bite.
## Verification
- `pnpm validate:agent-skills` — 19 skills, green, now including
`CONTRIBUTING.md` commands
- `pnpm validate:skill-routing` — 19 probes over 19 skills, green
- Workflow YAML parsed; oxlint and prettier clean on touched files
- `Agent Substrate` workflow ran green on this PR (42s) before the
trigger change and re-runs on every push
This PR:
- replaces ESLint with oxlint across the pnpm workspace and the
Bun-based docs site, porting the rules to `.oxlintrc.json` /
`docs/.oxlintrc.json` with behavior parity (restricted-syntax selectors
kept via `oxlint-plugin-eslint`)
- migrates typecheck to TypeScript 7 (`typescript@^7.0.2` catalog) and
keeps a TS6 pin for JS compiler API consumers via a named `ts6` pnpm
catalog (`ts/scripts/validate-examples.ts`, the `@composio/cli` generate
pipeline). The CLI's `typescript` dependency rebinds only the
compiler-API import — its typecheck still runs the root TS7 `tsc`, since
the alias package only ships a `tsc6` bin (documented in
`ts/packages/cli/AGENTS.md`)
- removes the `paths` mappings that pointed `@composio/core` (and, in
`experimental`, `@composio/json-schema-to-zod` plus core-internal
`#`-imports) at sibling `src` directories: under TS7, tsdown's
tsgo-based dts step emitted stray `.d.ts` files next to those
out-of-root sources on every dependent package build. Workspace deps now
resolve through their built dist types, which turbo's `dependsOn:
^build` already guarantees exist — and which the deep-path exports
(`@composio/core/*`) always used anyway
- renames the cli boundary tooling `eslint-boundaries*` →
`lint-boundaries*` and hardens the scanner to reject `oxlint-disable`
spellings so the disable manifest cannot be bypassed
- rewrites inline `eslint-disable` comments to oxlint rule names
(comment-only; no runtime changes), and adds **one new** declared
boundary: `tool-file-uploads.ts` needs `no-restricted-imports` disabled
for `node:crypto` (MD5 for the presigned-upload checksum is not in Web
Crypto), because oxlint also catches dynamic `await import()` where
ESLint did not. The manifest grows 46 → 47 deliberately
- updates CI path filters, `turbo.jsonc` lint inputs, and the docs
typescript-check workflow (renamed to "Docs - Lint and TypeScript
Validation" since it now lints too); drops `eslint`,
`typescript-eslint`, `eslint-config-next`, and `globals` from the
dependency graphs
- ships no changeset: I built `@composio/core` and `@composio/anthropic`
on this branch and on the pre-migration base and diffed the emitted
`dist/**/*.d.mts`. The provider output is byte-identical. Core's output
is **semantically identical but not byte-identical**: TS7 changes quote
style (`"x"` → `'x'`), object-property and union-member ordering in
inferred types, and picks equivalent shorter re-export alias paths for
five signatures (e.g. `OpenAI.Beta.Threads.Runs.Run` →
`OpenAI.Beta.Threads.Run` — verified both names alias the same type in
the shipped typings). Chunk-name hashes shift as a consequence. No type
gains, losses, or shape changes; `attw` and `publint` pass on the TS7
build
## Context
First of a three-PR split of #3958. The type-safety refactors are
stacked on this branch and merge after it:
- docs: https://github.com/ComposioHQ/composio/pull/3967
- `@composio/core`: https://github.com/ComposioHQ/composio/pull/3968
## What
Adds a **report-only** `Dead Code` CI workflow that surfaces
likely-orphaned code on every PR, across all three surfaces —
TypeScript, Python, and GitHub Actions. Follow-up to the root
`Dockerfile` cleanup (#3783) and the dead-code sweep in #3786: instead
of finding this stuff by hand, catch it automatically.
| Surface | Tool | Wiring |
|---|---|---|
| TypeScript | [**knip**](https://knip.dev) | `knip.json`; runs via
`pnpm dlx knip@5`. Finds unused files, exports, types, and dependencies.
|
| Python | [**vulture**](https://github.com/jendrikseipp/vulture) |
`dead_code` nox session + `make dead-code`; allowlist at
`python/config/vulture_allowlist.py`. Finds unused
functions/classes/variables (complements Ruff's F401/F841). |
| GitHub Actions | small bash script |
`.github/scripts/check-orphan-ci.sh` — flags reusable workflows and
composite actions with no callers. |
## Why report-only (not blocking)
Every job writes findings to the run's **Step Summary** and **never
fails the build**. These tools carry unavoidable false positives on a
library monorepo — public API surface, dynamic imports, import-map
targets (e.g. core's `#platform`), framework entry points. A red ❌ on
false positives would just train everyone to ignore the check. Once a
job's config is refined enough that a clean run is the steady state, it
can be flipped to blocking.
## Validation (ran each locally)
- **knip**: 0 unused *files* after scoping out the e2e-test workspaces
(knip crashes traversing `ts/e2e-tests/**` — pre-existing knip bug,
filed via `ignoreWorkspaces`) and build/docs artifacts. Export/dep
categories surface advisory items.
- **vulture**: clean run (report-only); allowlist suppresses the 3
`TYPE_CHECKING` re-exports in `custom_tool.py`; `build/`/`dist/`
excluded. Surfaces 4 genuine minor items (`bases`, `desc`×3).
- **orphan-CI script**: finds none — the repo has no orphaned CI
plumbing today.
- **Pinning**: `jk actions check` clean for this workflow;
`actions/checkout` is SHA-pinned, the two local composite actions need
no pin.
Local usage is documented under **Dead code detection** in
`CONTRIBUTING.md`.
## Note on scope
These cover TS/Python/GHA — they would *not* have caught the root
`Dockerfile` itself (an arbitrary root file no tool tracks). That class
stays a manual-review concern; the orphan-CI script is the closest
analogue for the CI surface.
This PR:
- supersedes https://github.com/ComposioHQ/composio/pull/3535 and
credits @eldar702 for the original `CONTRIBUTING.md` refresh
- closes https://github.com/ComposioHQ/composio/issues/3487
- refreshes the repo layout around `ts/`, `python/`, `docs/`, and root
release/install tests
- documents the current `mise.toml` toolchain and removes stale
Corepack, `.nvmrc`, `.bun-version`, and top-level `packages/` guidance
- replaces the strict file-header requirement with current
TypeScript/Python coding standards
- adds current TypeScript e2e, Python, docs-site, changeset, and
release-doc pointers
- verifies documented paths, package scripts, Python make targets,
Prettier, and whitespace checks locally
Co-authored-by: Eldar Shlomi <eldarshlomi7@gmail.com>
Alberto Schiabel