Adoption Guide

There are two ways a repo gets the harness: scaffold (a fresh repo) and adopt (an existing repo with its own history and config). The rules differ.

Scaffold vs adopt

• Scaffold — a new or nearly-empty repo. The harness skill writes the full set of files (Makefile, AGENTS.md, /health, hooks, .claude/settings.json, docs/references/) from the templates.
• Adopt — an existing repo. The skill merges and extends rather than writing over what you have.

Non-destructive rules

Adoption never destroys existing work:

• .claude/settings.json is merged, never overwritten. New permission-allowlist entries and the Stop-hook wiring are added; your existing entries stay.
• AGENTS.md content is preserved. If you already have agent instructions, they are folded into the required section structure — not replaced.
• Existing Makefile targets win. The harness provides Makefile.core; your overrides via *_CMD variables take precedence.
• Nothing destructive is ever allowlisted — no force-push, no wrangler delete, no rm.

Baselining

A large existing repo will not be green on day one. Rather than block adoption, baseline the checks that fail on legacy code:

1. Record the relaxed/excluded check under ## Baselines in AGENTS.md.
2. Give each baseline a TODO(deferred): note explaining why and what unblocks it.
3. File a follow-up OpenSpec change to burn the baseline down, and reference it.

An empty ## Baselines section is the goal. A non-empty one is an honest ledger of debt, not a place to hide it.

Confirming convergence

Once adopted, make harness-check reports every invariant that still fails, each with a To fix: line. Work the list until make check is green. Before the repo is registered in status.shwrk.com's projects.json, set HARNESS_CHECK_SKIP_REGISTRY=1; remove it once listed.