Init

init — Install the harness into a project

Runs inside the target project. It interviews the repository first and the user second, because most of what varies is discoverable and asking about it wastes the one resource the user actually spends: attention.

Migration is the common case. Treat a greenfield repo as the special case, not the default.

Step 1 — Detect, don't ask

Read before asking anything:

Run each candidate validator before adopting it. A command copied from a README that fails on a clean checkout will make the quality gate block every turn from day one, and the user will disable the gate rather than debug it. If a validator fails on a clean tree, say so and ask whether to fix it, omit it, or record it as known-failing.

Step 2 — Ask only what is left

At most five questions, highest consequence first, each with a recommended answer:

1. What quality property does this project own? Correctness, latency, safety, accessibility, cost — the one a defect would most damage. This anchors every severity in the reviewer, so it is the question worth spending the most on. There is no good default; ask.
2. Is there a source of truth above this repo — a design hub, an ADR set, a shared contract — and how are its documents referenced?
3. Which validators are gating (block a turn) versus advisory (report only)?
4. Confirm the detected commit convention and branch naming.
5. Anything the reviewer must never flag — a deliberate deviation it would otherwise read as a violation.

Step 3 — Write

Scaffold the mandatory set; offer the rest. Six documents and three templates are required — PRD, design doc, backlog, Issue templates, spec, work log — and northstar, epics, contract, and archive are opt-in. Setting up thirteen documents in a project that needed six is how a harness gets abandoned in week two, so name the optional ones and let the user choose rather than creating them by default.

• .steering/product.md — what this project is, who uses it, what it deliberately is not, and a - Owns: <quality property> line the reviewer and the digest both read.

• .steering/tech.md — the stack, and the exact commands, with these machine-read lines:

  - Validators: <the gating commands, comma-separated>
  - Reviewer: <reviewer name>
  - Source globs: <git pathspecs for reviewable source, space separated, e.g. :(glob)**/*.ts :(glob)**/*.py>
  - Docs: <where inception documents live — `docs/` by default, or the path/URL of a shared documentation repo in a multi-repo product>
  

  The gates parse these, so a project changes its enforcement by editing steering rather than by editing hooks. Two consequences worth stating, because both fail silently:

  • Each value must stay on one physical line. The gates read them with sed ... | head -1, so a wrapped value is truncated at the first newline and the rest is lost without complaint.
  • Source globs is a git pathspec, and :(glob) earns its place. The value is interpolated unquoted, so a bare *.py is expanded by the shell against the repository root before git ever sees it — which in a src/ layout matches nothing. :(glob) matches no file on disk, so the shell leaves the word alone and git receives the pattern intact.

• .steering/structure.md — where code belongs, and where tests mirror it.

• The anchor check — copy assets/check-steering-anchors.sh to the project's scripts/ directory and add it to the - Validators: line. The machine-read lines above are read with exact expressions, and a value written in a form the reader cannot see produces nothing and no complaint: the file looks right, the gate runs on a default, and nobody finds out. This harness lost its own quality anchor that way for a week by writing - **Owns: ...** instead of - Owns: ....

• .specs/README.md, .specs/_archive/README.md, .work_logs/README.md — each stating its contract.

• .github/ISSUE_TEMPLATE/ — copy feature.md, bug.md, chore.md, and config.yml from the plugin's assets/issue-templates/, adapting labels to the ones this project already uses. The issue is the entry point to the whole flow: backlog creates typed issues, spec reads the type to choose its shape, and one issue becomes one spec, one branch, one PR. Leaving the entry point undefined leaves a hole in the middle of the process. config.yml sets blank_issues_enabled: false on purpose — an untyped issue makes spec guess, and it guesses feature, which is the wrong shape for a bug and for a chore. If the project has a reason to allow blank issues, say so and change it deliberately. If templates already exist, merge rather than replace: keep their wording and their labels, and add only the missing types. An existing template encodes decisions the team already made.

• The reviewer — from the closest reference implementation (ts-reviewer, python-reviewer, dart-flutter-reviewer), or from agents/_template/ for an unrecognised stack. Copy _shared/reviewer-contract.md next to it, and copy the plugin's assets/check-locks.py into the project's own scripts directory — the project has to be able to re-pin its rulebook, and telling it to run a script it was never given is how the lock quietly stops being checked. Then re-pin with check-locks.py --update after any edit, and add it to the project's CI beside its other validators.

• The hooks — render hooks/templates/ for whichever harnesses the project uses, and copy gate-lib.sh, quality-gate.sh, review-gate.sh, and steering-digest.sh into the project's hooks directory. Only {{FAST_CHECK}} and {{HOOKS_DIR}} are substituted; the blocking quality gate ships as a script and reads the - Validators: line, so do not inline the validator commands into the settings file.

• AGENTS.md, with CLAUDE.md pointing at it, so one file is canonical.

Populate every file. Never leave a TODO in a steering file. An unpopulated steering file is worse than none: it teaches the agent that steering files are noise, and that lesson generalises to the ones you did fill in.

Step 4 — Prove it works before declaring success

Do not report completion on files written. Verify:

1. Every gating validator runs clean on the current tree, and quality-gate.sh exits 0. Arm the gate on a green tree — otherwise the user's first turn is blocked by a failure that predates them, and their first act is to disable it.
2. review-gate.sh exits silently on the current branch — if it fires immediately, the scoping is wrong and the user's first experience of the harness is a false block.
3. Both gates actually block when they should: introduce a trivial lint violation, confirm quality-gate.sh fires, revert it.
4. The reviewer is spawnable. You just wrote it into the project's agents directory, and a subagent registered mid-session is usually not available until the harness restarts. Check whether it can actually be invoked — if it cannot, say so and tell the user to restart before their first implement. This is not tidiness. implement step 2 falls back to running the reviewer's procedure inline when it is not spawnable, which means the author of the diff reviews their own work. That fallback exists for good reasons and it still finds real defects, but it is not the independence the judgment layer is sold on — and on a fresh install it is not the exception, it is guaranteed. A restart costs seconds; a project whose every early review was a self-review does not find that out until someone reads the receipts.
5. Report what you verified, and anything you could not.

Rules

• Never overwrite an existing .steering/, .specs/, or AGENTS.md without showing a diff and getting agreement. Merge into what is there.
• The directory names .specs/, .steering/, and .work_logs/ are fixed. They are not configurable, because every skill body references them literally, and that is precisely what lets one copy of a skill serve every project without templating.
• If the project already has a harness from an earlier version, diff and upgrade rather than reinstalling.
• Stop before adding configuration for its own sake. If you find yourself designing a file that describes how to describe a language, the harness has drifted from its purpose: three concrete reviewers people copy beat one abstraction people configure.