-
Notifications
You must be signed in to change notification settings - Fork 0
Tiers
The reference harness this skill distills was grown over months on a high-stakes, parallel-agent project — and its own governance docs warn that installing that mass up front is the same scope-sink disease the harness prevents. Mechanisms were added in response to named, dated incidents, not speculatively. So: install the smallest tier the answers justify, and let the audit's retro step grow it when pain is felt.
Folded into the setup interview (not run as a separate questionnaire):
- Expected duration — days, weeks, or open-ended?
- Who works on it — one human, human + agent, or multiple agents in parallel?
- Stakes — throwaway/exploratory, internal tool, or production with real users/money?
- Is there a vendored, pinned, or generated codebase that must not be hand-edited? (→ the upstream trait, below)
- Will work ever proceed unattended (agent-driven runs, CI-triggered work)?
Mapping: days + throwaway → S (even when Claude does the work). Weeks, or
unattended/CI-triggered agent work, or production stakes → M. Open-ended +
parallel agents + high stakes → start at M and grow toward L via retro.
Don't install L machinery on day one unless the user explicitly insists — and
then record the override in DECISIONS.md.
Bootstrap CLAUDE.md (≤40 lines, a pointer not a copy, with a hash-pinned
core-rules block), docs/PRD.md (requirements carry stable clause IDs like
R3.c2; the out-of-scope list is load-bearing), docs/HARNESS.md (how we work,
plus a named anti-goal), docs/UNKNOWNS.md (the quadrant register),
docs/PLAN.md (volatility-sorted, every step with a → verify:),
docs/DECISIONS.md (dated, with a falsifiable revisit_when), docs/ACTIVE.md
(session handoff), one honest check command, the self-test copied into
the project, and the .claude/harness.json manifest.
Every document must have a writer, an update trigger, and a consumer. If you can't name all three, don't install the doc — it will rot and then lie.
Everything in S, plus executable enforcement: a protected-paths hook (blocks
edits under configured paths, realpath-resolved), a status-guard hook (blocks
hand-editing a work item into a gated status without real evidence), a
secret-scan hook (blocks credential-shaped literals, skips test fixtures),
work items (one file per story with id / status / prd_refs / evidence
frontmatter — the status field on disk is the state machine), an extended
self-test (now plants a fake violation per hook and verifies wiring both ways),
failing-test discipline (strict expected-fail tests bound to acceptance
clauses), and a generated docs/STATUS.md with a freshness gate.
Hooks are thin and fail open — a broken hook must never brick the session, which is exactly why the self-test must prove they fire when healthy.
For long-running, high-stakes, parallel-agent projects. Never installed at setup; added as retro-justified backlog items with the incident named. The catalog: driver + firing map, append-only transition ledger (JSONL), fresh-agent verification, merge lock + serialized merge queue, invariant registry with owners, failure attribution by revert-and-retest, preamble fingerprinting, and upstream-trait machinery.
Orthogonal to tier — install whenever the project wraps a codebase it must not
fork: a protected-paths hook over the upstream directory (worth installing
even at tier S — cheapest, highest-value guard), SEAMS.md (one row per
contact point with the upstream), and PATCHES.md (a ledger for the escape
hatch; zero data rows is the designed default — every bypass lands a row in
the same commit with a machine-evaluable retirement condition).
Both go through DECISIONS.md as proposals, never silent applications.
Graduate (add machinery) when the same failure appears twice since the last
review, or a named incident occurred — record the incident. Retire (remove
machinery) when a component guards against nothing this project does; removing a
guard removes its hook file, its settings entry, its manifest entry, and its
self-test expectations in the same change.
Canonical detail: references/tiers.md.
Concepts