harness-init

Stand up the local coding harness for a project, step by step, as a guided expert session. The developer should finish understanding exactly what was created and why, with every artifact reviewed and tweakable.

Scope: this sets up the local harness (Claude Code /loop outer runtime). Server / Claude Agent SDK / OpenSWE modes are future iterations — the artifacts here are built so they don't have to be torn out to move there.

How to run this skill

You are a guide, not a script runner. For every step that writes to disk or runs a git operation: explain what you're about to do and why → confirm with the user → do it → show the result → take feedback and adjust. You have rich context in references/ so you never have to guess — read the relevant reference before each step and narrate from it in plain language.

Two kinds of artifact:

• Canonical (drop in verbatim from assets/): the dispatcher, the shim skill, REVIEW.md, the env template, the AGENTS.md template skeleton, the review workflow. Show them, explain them, invite tweaks — but they're the same everywhere.
• Software 3.0 (generated by reading the repo): AGENTS.md's filled-in parts, scripts/local-checks.sh, and scripts/bootstrap-worktree.sh. Scan, propose, let the user correct. Never invent a command you didn't see evidence for — ask instead.

Read first, before talking to the user:

• references/mental-model.md — so you can explain what the harness is.
• references/invariants-to-preserve.md — the rules nothing you generate may break.

Then load other references as each step needs them.

Preconditions

The skill runs in the human's checkout (their normal working copy), on main, with a clean tree and an origin remote. The harness will operate in sibling worktrees, never here (Invariant 6) — but setup writes/commits happen here because the human is present and consenting.

The guided flow

Step 0 — Preflight

Run scripts/preflight.sh from the repo root and walk the user through the report together. It checks the environment, detects the toolchain, inventories which inner skills are installed, and flags any harness artifacts that already exist (re-run detection).

• [MISS] on environment (no git repo, no gh) → resolve before continuing.
• [MISS] on inner skills → see "Inner skill dependency" below; note them, don't block.
• [warn] on existing artifacts → this is a re-run; diff against what's there rather than clobbering.

Summarize what you found in plain language and confirm the project is ready.

Step 1 — Config (.harness/env)

Read references/config-options.md. Derive the author-slug from git config user.email. Explain MAX_WORKTREES (default 1) and WATCH_PATTERN (per-dev default) and their tradeoffs; recommend the defaults and only change on a concrete reason. Write .harness/env from assets/harness-env.template with the chosen values. Add the runtime counter files to .gitignore:

.harness/feedback-rounds-*
.harness/local-check-attempts-*
.harness/implement-attempts-*
.harness/planning-attempts-*
.harness/validate-attempts-*
.harness/stuck-*
.harness/human-review-*
.harness/sessions-*.tsv
.harness/learn-review-body-*

(The memory loop keeps no local watermark file — the refs/harness/last-learned ref on the remote is the watermark — so there is no last-main-sha to ignore.)

(Commit .harness/env itself; ignore only the counters.)

Step 2 — The dispatcher, the shared lib, and the two tick wrappers

Read references/dispatcher-explained.md. Copy these from assets/ into scripts/ and chmod +x the shell scripts:

• poll-and-dispatch.sh — the build-loop dispatcher (features).
• harness-tick.sh — the build-loop wrapper.
• harness-lib.sh — shared helpers (run_claude, render_sessions_table, worktree_for, bootstrap_worktree), sourced by both loops. No chmod +x — it's sourced, never executed.
• learn-tick.sh — the memory-loop wrapper (the post-merge /learn driver).

Then walk the user through them — the load-bearing properties of the dispatcher (including the HUMAN_REVIEW convergence exit — the reviewer's REVIEW_CLEAN_MARKER comment hands the PR to the human for /evaluate-pr), the section map, the bootstrap hook (the project-owned worktree provisioning; explain why it's there), and the harness-tick.sh wrapper: the build loop targets the wrapper, which force-syncs the host worktree to a clean origin/main and then execs the (HEAD-agnostic) dispatcher. Explain why the sync lives in the wrapper, not the dispatcher: the dispatcher must never reset its own running file, and this is how loop-infrastructure updates merged to main (dispatcher, .harness/env) reach the loop — feature pipeline skills ride the PRD branch and need no sync.

Then explain the memory loop is a separate loop (references/dispatcher-explained.md → "The memory loop"): /learn is NOT a dispatcher step. learn-tick.sh runs it under its own /loop … /learn-loop, in its own dedicated ../<repo>-harness-learn worktree, gated by the refs/harness/last-learned watermark ref and paused while a learn/<sha> PR is open. The two loops never block each other and coordinate only through git. Offer the common tweaks (PRD-runner stuck cap, feedback round cap, extra pipeline steps, the memory-loop interval). Do not let them break the "what NOT to do" list.

Step 3 — The shim skills

Copy both shims: assets/poll-and-dispatch-SKILL.md → .claude/skills/poll-and-dispatch/SKILL.md and assets/learn-loop-SKILL.md → .claude/skills/learn-loop/SKILL.md. Explain the /loop gotcha: an outer session must never do real work — each shim only calls its tick script (harness-tick.sh / learn-tick.sh), and all real work happens in fresh claude -p subprocesses. One paragraph; then move on.

Step 4 — AGENTS.md (Software 3.0)

Read references/agents-md-guidance.md and references/project-discovery.md. Scan the repo, fill assets/AGENTS.md.template's bracketed parts (project name, the verification-layer tooling), keep the rest verbatim. AGENTS.md is the neutral, eagerly-loaded contract — a map that points into the Expert, not an encyclopedia; keep it tight (the freshness lint caps the root at ~150 lines). Present it as a diff against the template, citing the scan finding behind each filled-in line. Let the user edit before committing. Tell them the Expert section is intentional even though the Expert is empty until their first merge.

Step 5 — scripts/local-checks.sh (optional, Software 3.0)

The deterministic gate the dispatcher runs before opening a PR (two-strike retry: local-checks.sh fix → /fix-local-checks → STUCK). It's the cheapest place to catch correctness issues — left of the reviewer and CI. Read references/local-checks-design.md first and narrate the why to the user; they own and tune this script. Detect commands via references/project-discovery.md.

It has two responsibilities (the reference details both):

• Wire the project's deterministic checks — lint/format (with a fix subcommand), typecheck, the fast unit suite (slow/integration → CI), a skip-detection check, and everything in scripts/lints/. Prefer commands the project already defines; call existing pre-commit hooks rather than duplicating.
• Propose custom correctness lints from the codebase as-is (snapshot discovery) — observed existing invariants + surface-scoped best-practice lints, behind the five guards in the reference. Propose; the user disposes.

The gate proves correctness, not coverage — block only correctness/structural, warn on legibility/observability, and don't add checks for volume (mutation testing is a sensor, not here). The skip rule is load-bearing: an agent may never add a test-skip marker; a legitimate skip is the human's call at STUCK.

If the user doesn't want this gate, skip it — the dispatcher treats the script as absent and works fine. If you do generate it, mind the Step 6 dependency: because it runs typecheck and tests, the worktree must be fully runnable, so bootstrap-worktree.sh has to be solid or these legs fail for the wrong reason.

Step 6 — scripts/bootstrap-worktree.sh (Software 3.0)

Read references/worktree-bootstrap.md. This makes a fresh worktree runnable: copy gitignored runtime files (.env, secrets) from the human's checkout, install dependencies, run codegen. Discover the setup from README/CI/manifests (project-discovery.md); if discovery is thin, ask the user how they set the project up on a fresh machine.

Flag the secret-copying loudly. This is the one place the harness touches sensitive files: name exactly which files get copied and from where, confirm the destination is a same-machine *-harness* worktree, confirm copy direction is always source→worktree and nothing is deleted, and get explicit consent. If the project has no gitignored secrets, skip that part and say so. Generate an idempotent, non-interactive, well-commented script.

Step 7 — Reviewer (optional)

Read references/reviewer-options.md. Present the three paths (self-hosted via claude-code-action = recommended default; managed Code Review; none). Explain the tradeoffs and that switching later is cheap (one workflow file). Then:

• Self-hosted: copy assets/REVIEW.md to repo root + assets/workflows/claude-review.yml to .github/workflows/, and:
  1. Pick auth with the user. The template ships with claude_code_oauth_token active and anthropic_api_key commented. Ask which they want: subscription (CLAUDE_CODE_OAUTH_TOKEN from claude setup-token — uses their Max/Pro plan, shares its usage limits) vs metered API (ANTHROPIC_API_KEY from console.anthropic.com — separate billing, better for teams/CI). Uncomment the chosen line, comment the other, and have them add the matching repo secret. (Max and the API are separate billing products.)
  2. Pin the action. Look up the current anthropics/claude-code-action release (e.g. gh release view --repo anthropics/claude-code-action) and replace @v1 with that tag (e.g. @v1.2.3).
  3. Tell them the v1 same-content rule: the workflow must be byte-identical on the PR branch and the default branch, so it only takes effect once merged to main and can't be tested from a feature branch. Note the template is the v1 API (prompt + track_progress + claude_args + id-token: write); it does NOT use the pre-v1 mode/review_instructions_path inputs. The reviewer is PR-triggered and one-way; if the user also wants an interactive @claude agent, that's the stock examples/claude.yml added separately (see reviewer-options.md) — not bundled here.
• Managed: copy REVIEW.md; give the GitHub App install instructions.
• None: create nothing; set REVIEW_CLEAN_MARKER= (empty) in .harness/env so the dispatcher converges at PR-open and hands straight to /evaluate-pr; note a reviewer is addable later.

Convergence marker (both reviewer paths). REVIEW.md instructs the reviewer to post a PR comment containing HARNESS_REVIEW_CLEAN once it has no Important findings left. That marker is how the dispatcher knows the review loop converged and hands the PR to the human for /evaluate-pr — it's a single deterministic signal, the same for managed and self-hosted. The token is configurable via REVIEW_CLEAN_MARKER in .harness/env (must match what REVIEW.md tells the reviewer to post). If the reviewer never posts it, the feedback loop reaches FEEDBACK_CAP and STUCKs instead — a clean PR the human merges.

Step 8 — Host worktree + provision

Explain the three-checkout model (see references/mental-model.md): the human's checkout stays on main; the harness host worktree is a sibling that stays detached at origin/main (re-synced every tick by harness-tick.sh); per-feature work happens in ephemeral ../<repo>-harness-<feature> worktrees the dispatcher creates and tears down. Create the host worktree detached — git won't let two worktrees check out main at once, and the human's checkout already holds it:

git worktree add --detach ../<repo>-harness origin/main

Then run scripts/bootstrap-worktree.sh ../<repo>-harness to provision it. This doubles as validation of the bootstrap script — if the host worktree is runnable afterward, the script works. Fix and re-run if not.

Step 9 — Dry-run the tick

From the harness host worktree (../<repo>-harness), run ./scripts/harness-tick.sh once. It force-syncs the worktree to origin/main and then runs the dispatcher; with no PRDs filed it should be a clean no-op (fetch, sync, find nothing, exit 0). This proves the build-loop wiring — sync wrapper + dispatcher — without doing any work.

Then run ./scripts/learn-tick.sh once. On a fresh repo (Expert not yet built, no merges since the watermark) it creates and bootstraps the ../<repo>-harness-learn worktree, finds no new range, and exits — proving the memory-loop wiring. Walk through both outputs with the user. If anything errors, debug before starting the loops. (Note: with no origin yet, the fetch fails fast — that's expected until the remote exists.)

Step 10 — Commit, then start the loop

Commit the setup artifacts on main (or on a setup branch for the user to merge — ask). Then explain how to start the harness. It runs as two independent loops, each in its own long-lived Claude Code session pinned to the harness worktree — the build loop (features) and the memory loop (/learn). They never block each other:

cd ../<repo>-harness

# session 1 — the build loop (features):
claude
/loop 5m /poll-and-dispatch

# session 2 — the memory loop (/learn), in a SEPARATE session:
claude
/loop 10m /learn-loop

The memory loop can tick lazily (10m is fine) — it only acts when main has advanced past the refs/harness/last-learned watermark and no learn PR is already open. Offer to start them if they're ready. Finish with the daily flow recap:

1. /intent in their normal checkout → confirm a PRD → walk away.
2. Harness picks it up, runs the chain, opens a PR.
3. Either:
   • Normal path: when the reviewer converges, the harness posts a "Ready for your review" comment with the build-session trail and halts. Run /evaluate-pr <feature> to walk the change, run it locally, and build a firm understanding — then merge it (or fix-and-push, or close). Then review and merge the /learn PR that follows (memory updates).
   • STUCK path: if any step hits its retry cap, the dispatcher posts a STUCK PR (or comment) with the session log + a diagnosis-first checklist. Your first job is the context defect, not the code — figure out which AGENTS.md / Expert / spec / PRD content misled the agent, correct it on the branch, then fix the code and merge. /learn picks up the context correction at merge.

Inner skill dependency

The dispatcher calls /spec-planning, /spec-validate, /implement-mainspec, /fix-local-checks, and /address-feedback. /learn is driven by the separate memory loop (learn-tick.sh), not the dispatcher. Two more are human-invoked, not dispatched: /intent (front of the chain) and /evaluate-pr (the Evaluate phase — run after the harness posts its "Ready for your review" handoff). harness-init wires both outer loops; it does not author these. Preflight reports which are installed. If some are missing, set up the harness anyway and tell the user clearly which skills must be installed from the catalog before the chain runs end to end — the harness will dispatch to them the moment they exist. (/learn is the memory skill under .claude/skills/memory/; the project's Expert is born from the first /learn.)

Re-running

Safe to re-run. Preflight flags existing artifacts. For canonical files, diff and offer to update. For generated files (AGENTS.md, local-checks.sh, bootstrap-worktree.sh), re-scan and show a diff rather than overwriting blind. Never delete the human's host worktree or secrets on a re-run.

Hard rules (from invariants-to-preserve.md)

• Never run the dispatch loop in the human's checkout (Invariant 6).
• Never put an LLM call in the dispatcher's decision path (Invariant 5).
• Never replace the atomic-rename claim with a marker/lock file (Invariant 2/7).
• Never generate a "go backward" / sentinel-deleting step (Invariant 9).
• bootstrap-worktree.sh copies secrets source→worktree only, never deletes, never the reverse (Invariant 6).