Repo Context

Write down how this repo is built, run and tested — from the repo, not from memory — into the ## This repo section that canon installs into CLAUDE.md, AGENTS.md and every other runtime instruction file.

Why this exists

canon guarantees every wired repo has an instruction file. It cannot guarantee anybody wrote the repo-specific half, and the default state of that half is empty.

So every agent that lands in the repo re-derives the same five facts — the build command, the test command, the port, the one env var with no default, the service you have to start first — and none of them writes it down, because none of them was asked to. The cost is invisible per session and enormous in aggregate.

The output of this skill is the part of the file that stops that.

The failure mode to avoid

A confidently wrong command is worse than a blank section. A blank section makes an agent look; a wrong one makes it try, fail, and start debugging the wrong thing.

So the rule for this whole skill is: cite where each command is defined, and do not write a command you have not seen declared somewhere. "pnpm test — defined in package.json:12" is a fact a reader can check. "pnpm test" is a guess wearing a fact's clothes. If a manifest declares nothing, write that: "no test script is defined in this repo" is true, useful, and immediately actionable.

Where it is safe and fast, run the command and say that you did. Where it is not — anything that starts a long-running server, touches a database, deploys, installs into a shared environment, or costs money — do not run it. Say it is undeclared-but-unverified instead.

Procedure

1. Find the instruction file and confirm the section is empty

The body is identical in CLAUDE.md, AGENTS.md, GEMINI.md, .github/copilot-instructions.md, .windsurf/rules/knowledge-vault.md and .clinerules/knowledge-vault.md, because install.sh generates all of them from one template. Whatever you write must go into every one of those that exists in this repo — that is the whole reason they are generated rather than hand-written, and the drift starts the first time somebody updates only CLAUDE.md.

If the section already has content, do not overwrite it. Read it, check it against the repo, and propose corrections for the lines that are now wrong. Someone chose those words.

2. Read the repo, in this order

Cheapest and most authoritative first:

1. Manifests and task runners — package.json scripts, pyproject.toml, Makefile, justfile, Cargo.toml, go.mod, composer.json, mise.toml. These are declarations, so they are evidence.
2. The CI workflow — .github/workflows/, .gitlab-ci.yml, azure-pipelines.yml. This is the best source in the repo and the most commonly skipped. CI is the one place the commands are known to work, on a clean machine, in order, including the setup steps a human has long since forgotten they did once.
3. Container and compose files — Dockerfile, docker-compose.yml for ports, entrypoints and the services that must be up first.
4. Env templates — .env.example, .env.sample, settings modules. Every variable with no default is a gotcha candidate. Never copy a value, only a name — the vault and these files are git-tracked, and a real secret in either is permanent.
5. The entry point — whatever main, app, index or the console-script points at. One file, to name the boundaries honestly.
6. Test config — pytest.ini, [tool.pytest], jest.config.*, vitest.config.*, and where the coverage report is written to.

3. Write the four subsections

Keep the whole instruction file under ~200 lines; it loads in full on every request. If something needs more room, write a vault note and link it.

• Build and run — exact commands, each with the file that defines it, plus the local port.
• Test — the whole suite, a single test, and how coverage is produced.
• Architecture in three sentences — entry point, the one or two boundaries that matter, where the data lives. Three sentences. Not a diagram.
• Gotchas — the highest-value part. The things that are not visible from the code: a migration that must be applied by hand, an env var with no default, a test that only passes from the repo root, a service that must be started first. Write what surprised you while reading. If nothing surprised you, say the section is empty rather than padding it — a padded gotchas list trains people to stop reading it.

4. Emit the testing-canon rows

This is the step that makes the skill worth more than a docs chore. You have just read the test config and the CI workflow, which is exactly what the vault's testing canon needs — so produce it now rather than making it a separate task nobody does.

Print, for the user to paste into Reference/Testing/<Name> — Current State.md in the vault (see the Test Canon template for the full contract):

- suite: <kebab-slug>
  repo: <this-repo-name>
  command: <the command you verified>
  report: <path the suite writes its coverage report to>
  format: cobertura
  metric: lines
  status: advisory

- gate: <kebab-slug>
  repo: <this-repo-name>
  workflow: .github/workflows/ci.yml
  job: <the job name>
  branches: [<EXACTLY as the workflow spells them>]
  required: false

Four rules for these rows, each of which the audit will otherwise catch later:

• branches: verbatim and case-sensitive. Copy from the workflow's on: filter, character for character. Then compare it to what git actually calls the branch — git branch -r. A filter on dev against a branch named Dev runs on nothing at all and looks green. If they differ, you have found a live bug; report it to the user as a finding, do not quietly write the working one.
• Omit floor:. You are reading config, not measuring. The floor is the coverage that already exists, and canon-test-audit --ratchet prints it once a report exists. Inventing one sets a target instead of a ratchet.
• required: false unless a human has confirmed otherwise. Branch protection is server-side and not knowable from a checkout. Never infer it.
• report: is the summary file, not the raw dump. istanbul writes both; coverage-final.json has no totals in it.

If this repo has no test suite at all, that is a row too — status: absent with a note. Recorded absence is worth more than silence.

5. Hand it back as a proposal

Say what you verified by running, what you took from a declaration without running, and what you could not determine. Then let the user correct it. The point of this file is that it is trusted, and trust comes from a teammate having read it — not from an agent having generated it.

Do not add a verified: entry anywhere on your own behalf. That field means a human confirmed it.