---

name: project-toolchain description: Work out which commands actually lint, test, build and format THIS project before running any of them - by reading its manifests and configs, never by assuming. Use whenever a command or agent needs to "run the project's lint/test/build", when a check fails with "command not found", or when onboarding the AI-SDLC harness into an unfamiliar repo. allowed-tools: Read, Grep, Glob, Bash

project-toolchain

Several parts of this harness say "run the project's lint and test commands" without saying what they are — /review, /pr, /skill-approve, and the reviewer and security agents all defer that decision to the project. This skill is how that decision gets made, so a framework-agnostic harness can run real checks in a repo it has never seen.

Never assume npm test or flutter analyze. Guessing produces one of two bad outcomes: a "command not found" that looks like a broken harness, or — worse — a check that appears to pass because it silently did nothing.

Steps

1. Find the manifest, nearest to the working directory, checking in this order and stopping at the first hit:

   | File | Ecosystem | Where the commands are | |---|---|---| | package.json | Node | its scripts object | | pubspec.yaml | Dart/Flutter | conventional flutter/dart commands | | Cargo.toml | Rust | cargo fmt/clippy/test/build | | go.mod | Go | gofmt, go vet, go test ./..., go build ./... | | pyproject.toml / setup.cfg | Python | tool sections (ruff, black, pytest) | | Makefile / Justfile | any | its targets — these override the above when present | | build.gradle(.kts) / pom.xml | JVM | gradle/mvn tasks |

2. Read the scripts, do not infer them. For Node, print package.json's scripts and use those exact names. A repo with "test": "turbo run test" is run with the package manager's test script, not with vitest or jest directly, even when those are the underlying runners — the script may set env, ordering, or workspace scope that matters.

3. Identify the package manager from the lockfile, not from habit: pnpm-lock.yaml → pnpm, yarn.lock → yarn, bun.lockb → bun, package-lock.json → npm. Running npm test in a pnpm workspace is a common way to get confusing failures.

4. Detect a monorepo and respect its scoping. pnpm-workspace.yaml, turbo.json, nx.json, lerna.json, or a workspaces field mean a root-level command fans out to every package. When the change is scoped to one package, prefer that tool's filter (turbo run test --filter=<pkg>, pnpm --filter <pkg> test) so a five-minute full run does not hide a ten-second answer.

5. Verify before relying on it. Run the resolved lint or test command once. If it fails with a missing-binary error rather than a real finding, dependencies are not installed — say so and stop, rather than reporting the check as failed on its merits. There is a real difference between "the tests fail" and "the tests did not run", and only one of them is the author's problem.

6. Report the resolved toolchain explicitly before using it, so the human can correct a wrong guess cheaply:

   Toolchain for <repo>:
     package manager: pnpm (pnpm-lock.yaml)
     monorepo:        turbo (turbo.json) — filter with --filter=<pkg>
     lint:            pnpm lint
     test:            pnpm test
     build:           pnpm build
     format check:    pnpm format:check
   

7. Record it so the next session does not re-derive it: write the resolved commands into the project's CLAUDE.md, or a toolchain: block in .claude/settings.json. Prefer reading that record on later runs, but re-verify it if a command starts failing — records go stale when a repo migrates package managers.

Anti-patterns to refuse

• Running npm test / yarn test / flutter test without having read a manifest that says so.
• Reporting "lint passed" when the command was not found or exited non-zero for a setup reason.
• Running a full monorepo test suite when the diff touches one package and the tool supports filtering — unless the change is cross-cutting.
• Installing dependencies unasked as a way to make a check run. Report the missing setup; installing can rewrite a lockfile the team owns.
• Writing a resolved toolchain into a shared file when it was only inferred, not verified by running it.