Keystone — Level 2 Project Harness

The harness stack has five levels. Keystone generates a Level 2 (Project) harness — codebase-scoped scaffolding the agent reads on every task. It blurs into Level 3 (Organization) because the upper corpus layers — principles, process, adapters — are not codebase-specific and naturally travel across an organization's projects, even though the install target is a single repository.

Why the blur? Keystone's corpus/principles/, guides/principles/, guides/process/, and sensors/ are universal; adapters/ are per-agent, not per-project. Cherry-pick those into every repo in your org and you have de facto Level 3 coverage — without a separate Level 3 mechanism. Only corpus/idioms/, corpus/domain/, guides/idioms/, guides/domain/, and corpus/state/ are genuinely project-scoped.

Four components. Three are content (corpus, guides, sensors); one is the dynamics that keep the content current (the flywheels). Each has a distinct activation — when and how the agent picks it up.

The corpus/guides split is the central move in 0.3.0. Rules are short and high-value-per-token, so they live always-loaded in guides/. Long-form reasoning sits in corpus/ and is reached only when an agent needs the why behind a rule — see Context Budgeting below.

There is no enforcement mechanism — the loading order is a discipline encoded in the menu file, the lifecycle actions, and the adapter activation docs. The agent follows it because the rules tell it to, and because each step earns its way into context.

1. 01 → Session start — menu file auto-loads.

   The agent reads its menu (CLAUDE.md, AGENTS.md, .continuerules, etc.) — a short pointer at harness/ with the four components and the iron laws inline.

2. 02 → Guides become ambient.

   Per-agent activation projects harness/guides/ into the agent's rules surface — Cursor's .cursor/rules/*.mdc, Claude Code's directive block, Cline's custom-instructions field. The agent is now under every IRON LAW and GOLDEN RULE.

3. 03 → Orient reads state.

   The orient action reads corpus/state/CODEBASE_STATE.md and active migrations affecting the touched region. State is the only corpus file pulled into context at task start.

4. 04 → Stack-specific guides lazy-load by region.

   guides/idioms/<stack>/ for the touched paths comes into context. Other stacks don't.

5. 05 → Sensors fire at phase boundaries.

   No ambient cost. check-drift at implementation exit; verify at the verification gate runs lint, type-check, test, build, drift, commit-message. Output flows back as a transient turn artifact.

6. 06 → Corpus on demand — forward-link only.

   Each guide ends with a forward-link to its paired corpus file. The agent reads that corpus only when the rule isn't enough — to recall the reasoning, the citation, or an anti-pattern the team called out.

Steps 1, 2, and 5 are mechanical (adapter and process layer enforce them). Steps 3, 4, 6 are model behavior under the rules — the rule "reach for the paired corpus only when needed" is what keeps context low. See Context Budgeting next.

A different lens on the same dynamic. Loading order is the how; context budgeting is the why. The harness assumes context is the scarce resource and spends it accordingly.

The asymmetry is deliberate. Always-loading the corpus would crowd context with reasoning the situation often doesn't need. Always-loading the guides keeps the agent honest at all times without paying for that reasoning. The agent reaches for corpus when — and only when — the rule alone is not sufficient.

Every guide is built from two kinds of rule. The drift sensor enforces both — IRON LAW violations fail; GOLDEN RULE violations surface as warnings.

The five process iron laws apply across every phase:

• SPEC   No proceeding without explicit acceptance criteria.
• VERIFY   No completion claims without fresh sensor evidence from this turn.
• COMMIT   No commits with failing sensors. Never --no-verify.
• ATTRIBUTION   No AI attribution in commits, PRs, or tracker comments.
• STATE   No silent overwrites of state files. Propose a diff, confirm before applying.

The harness is most useful when the surrounding tooling looks like this. None of these are hard requirements — install runs regardless. Missing one degrades the corresponding phase to "ask the user / surface the gap"; it does not break the harness.

# Scaffold harness/ and the agent's menu file into <dir>.
# Prompts interactively (huh) for any unset options when stdin is a TTY;
# fails fast with a useful error when stdin is not a TTY and --agent is unset.
$ keystone init [<dir>] [flags]

# Print the catalog of allowed labels for every option flag
$ keystone options

# Print the binary version
$ keystone version

# Print usage
$ keystone help

init is interactive in a terminal, scriptable in CI. In a TTY, every unset option becomes a prompt; outside a TTY, options must be supplied as flags. Multi-select flags accept comma-separated values (e.g. --architecture hexagonal,continuous-delivery).

These are the questions only a human can answer — declared intent, not facts a script could infer from the codebase. In a TTY the installer prompts for each; in CI you pass them as flags. Selections land in harness/corpus/state/INSTALL_PROFILE.md; the bootstrap action reads them as the starting hint when it audits the codebase.

Each --architecture and --compliance label installs a paired corpus + guide — the explanatory file under corpus/principles/ and the rule-bearing file under guides/principles/. Some labels also seed concern-specific files (e.g., --architecture mvc drops corpus/idioms/mvc/{models,controllers,views}.md and paired guides/idioms/mvc/ files).

Run keystone options for the full catalog of allowed labels per flag.

How each action is actually invoked in your agent (slash command, rules-file trigger, natural language) lives in harness/adapters/<your-agent>/lifecycle.md.

Set with the mode action: mode <paired|solo|autopilot>. Agents without a notion of autonomy levels collapse to a single mode; the phases still run.

Every adapter ships lifecycle.md, activation.md, and sensors.md. Adapters with capability gaps (no slash commands, no sub-agent parallelism, etc.) get an install-time warning — see below.

full — adapter covers every harness feature natively. real · gaps — adapter covers the lifecycle but the agent lacks one or more native features (slash commands, sub-agent parallelism, autonomous tracker integration, etc.). keystone init prints the specific gaps after install with actionable remedies.

When an agent does not natively cover a harness feature, keystone init prints a ⚠ <agent> adapter — capability gaps to address section before the success message. Each gap names two paths the user can take:

# Example: keystone init --agent aider

⚠ aider adapter — capability gaps to address

  • sub-agent parallelism (review)
      Impact: review runs each concern sequentially in one chat.
      Or document: add harness/adapters/aider/review-strategy.md.

  • commit-message sensor gate
      Impact: Aider's default auto-commits fire before the sensor can run.
      Configure: set `auto-commits: false` in `.aider.conf.yml`.

  • native tracker integration
      Impact: tracker-card-fetcher falls back to shell or paste.
      Configure: use `/run gh issue view <id>` or paste card content.
      Or document: add harness/adapters/aider/tracker-workflow.md.

✓ keystone installed for aider.

Fully-supported adapters (claude-code, codex, pi, cursor) print no warning. The warning content is per-agent in the binary's warnings.go; if a gap closes upstream, the warning drops in the next keystone release.