Init harness

init-harness

Edition: CLI (Claude Code). scripts/*.sh and templates/kit/harness/{create,land}-agent-branch are POSIX shell (macOS / Linux / Git Bash on Windows); every Python entry point is invoked as <python>, the verified absolute interpreter from toolchain.python, never a bare python and never py -3. There is no Cowork/Linux-sandbox edition: this skill scaffolds a project's own .claude/ control plane, which a sandbox session does not own.

Seven steps: preflight -> context -> intake -> scaffold -> content -> derive -> verify.

The one thing to understand first

This skill is ~80% a config generator. Do not write a new generator: write a good harness.config.json, run the scripts that exist, prove the result blocks. And never mkdir/copy through tool calls - scaffolding ~40 directories one at a time is ~40 round trips of ceremony for zero judgment. Your tokens go to content.

Layer	Who	What
Structure	scripts/scaffold.sh	dirs, kit copy, git init + root commit, .worktrees/tN, merge driver, sqlite shards
Content	you	config, agent prompts, commands, CLAUDE.md/AGENTS.md, context packs, .bld/*/phases.md, memory/INDEX.md
Derivation	sync_harness.py, harness_status.py --write	.agents/, stamped frontmatter, indexes, status
Proof	scripts/verify_init.py	guards actually deny

token-efficiency is mandatory here and auto-loads in generated projects: RTK for command output, grep before read, offset/limit, summarize.

The interpreter rule - stated once, applies everywhere below

Every <python> below means the verified absolute path preflight returned. Never a bare python, never py -3, never a venv.

A missing interpreter does not fail open, it fails absent. py -3 on a machine with no py launcher exits 127: the hook process never starts, so there is no block, no log row and no audit trail. The harness looks installed and enforces nothing. This is the failure this skill exists to prevent, and it is why step 0 is not optional.

Flow

0. Preflight - always first

<python> "$SKILL_DIR/scripts/preflight.py" --json

Script paths are relative to this skill's directory, not the project - resolve $SKILL_DIR before you run anything. If preflight fails, stop and report. Generate nothing.

Tools the harness shells out to (python, bash, git, sqlite3, rtk) belong to the global/user toolchain - uv python install 3.11, scoop install git sqlite rtk. Never vendored in-project, never a foreign venv. Project libraries are unaffected.

0.5 Context bootstrap - context/ is a PREREQUISITE, not an output

Do not scaffold a folder you have not read. harness.config.json is derived from what the project is - domains, gates, sensitive paths. Scaffolding first bakes a wrong terminals{} into the files the harness treats as truth, and gate_guard.py then blocks legitimate work on boundaries nobody agreed to.

Classify first (ls -la, find . -maxdepth 2 -type f | head -40):

State	Do
Empty / only .git	greenfield - interview, write context/ from the answers
Loose docs, no source tree	unorganized - triage into context/ FIRST, see references/context-bootstrap.md
Real source tree	brownfield - never move source; derive context/ from the code
context/ populated	ready - read it, confirm it is current

Ask before moving anything - one confirmation, then git mv in one shell call. Never move source. Never move secrets; flag them.

1. Intake

If project-context.yml exists, read it. Else offer templates/project-context.yml or interview directly.

Infer mechanically (never ask): project, readGuard, gateGuard, logging, the core four skills, docRouting (from architecture/*.md that actually exist).

ASK - never guess. Two AskUserQuestion rounds, at most 4 options each, every option carries a Recommended marker.

Round A - shape

1. Terminal split - options from directories that exist, plus "Single terminal (t1)" (Recommended when unstated). Two terminals are justified only if they can make progress simultaneously without writing the same files.
2. Gate topology - "scaffold-complete only" (Recommended) / "+ security-pass on the sensitive domain" / custom. A gate earns its place only when work on Y is actively wrong before X lands - not merely harder.
3. Sensitive paths - kit defaults, filtered to real dirs.
4. Model tiers - kit defaults (Recommended) / custom.

Round B - permissions and rules (option text: references/permissions-and-rules.md; do not improvise these)

1. Permission profile - Balanced (Recommended) / Strict / Permissive / Custom.
2. Network + installers - Ask each time (Recommended) / Allow / Deny.
3. Git attribution - No attribution (Recommended, DEFAULT) / Yes.
4. Production-grade bar - Solid small tool (Recommended) / Multi-user product / High-scale. Read references/architecture-decay.md Sec. 1 only; the rest of that file is review-time, not init-time.

A hallucinated terminal split or gate topology is worse than a question: gates are the concurrency contract, and a wrong one silently unblocks work that should be blocked.

Same for permissions. This kit's ancestor shipped Bash(*) with an empty deny - root access as a default. deny beats ask beats allow, and the non-negotiable deny list (force-push, hard reset, secret reads, .agents/ writes, git tag -d) is re-stamped into every profile including Permissive. git tag -d is denied on purpose: revoking a gate is a human action - an agent may propose, never withdraw.

2. Scaffold

bash "$SKILL_DIR/scripts/scaffold.sh" PROJECT_ROOT "$SKILL_DIR" t1 t2 t3

The terminal arguments are optional. With none, the set is read from terminals{} in the config being installed - not from a default inside the script, because a default that disagrees with the shipped config produces a tree that fails its own verification.

Creates the tree, copies the kit (including the eight .claude/agents/*.md prompt templates), makes the root commit, then cuts one worktree + branch harness/tN per terminal from HEAD at .worktrees/tN, drops an untracked .harness-id identity marker in each, and creates one .agents/logs/tN.db shard per terminal. It also appends .gitattributes and registers the harnessjson JSON merge driver in .git/config - both halves, because a driver named in .gitattributes but unregistered is silently ignored by git.

.worktrees/, not .claude/worktrees/: that namespace belongs to the platform's own isolation: "worktree" isolator (agent-<hex>), and minting tN alongside it left "whose worktree is this" with no answer. .worktrees/ is also where the merge protocol puts agent/<tN>/<packet>.<hex> and queue/wave-NN; leases.key() normalises all of them to the same repo-relative key.

It also copies templates/docs/*.md into the project's setup/. Do not read those docs out of this skill - after this step they are already on disk in the project.

3. Content (you)

1. harness/harness.config.json - the one file that matters. toolchain.python = the verified absolute path. sessionDefault = Opus latest (the interactive default - deliberately not models.workhorse, which pins the coder). Rankings follow token-efficiency: expensive thinks, cheap types, cheapest logs (thinker/workhorse/utility). maxEffort: "high". Never "max" - max is a per-task escalation the user asks for, not a standing default.
2. Agent prompts - already installed. scaffold.sh copies eight templates into .claude/agents/: architect, planner, coder, reviewer, security-reviewer, designer, verifier (runs harness/verify_goal_packet.py against the goal packet - a mechanical check, not the coder's self-report), logger. Tailor the bodies to the project; add or remove slots by editing agents{} in the config and adding/deleting the matching file. Leave model:/effort: out of the frontmatter - sync stamps them, and that stamp is the only real enforcement point for the pin. The roster is the measured one (config _agentsPolicy): domain-reviewer and orchestrator were spawned 0 times in 199 and are deliberately absent.
3. Commands (/plan, /code-review, /security) + .claude/output-styles/default.md.
4. CLAUDE.md and AGENTS.md - session ritual, agents table referencing the config (never restate model IDs), effort ceiling, skills triggers, an explicit "Do NOT" list, and the note that the real write sandbox is the terminal's git worktree on branch harness/tN (spawn its agents with isolation: "worktree"). gate_guard.py's matcher is Write|Edit|MultiEdit|NotebookEdit and never sees Bash, so a cd out of the worktree escapes both the hook and the worktree boundary.
5. Context packs - context/agents/tN-context.md, one per terminal. Env-var names only, never a credential value.
6. .bld/README.md + .bld/tN/phases.md - GATE lines must carry the exact tag names from gates{}. Checkbox states: - [ ] open, - [x] done, - [~] superseded, - [!] blocked.
7. memory/INDEX.md - hub. Leave the Active Context block to harness_status.py --write; a hand-written status block is the second bookkeeping system the rules forbid.

4. Derive

<python> harness/sync_harness.py            # .agents/, stamped pins, indexes, stubs
<python> harness/sync_harness.py --check    # must print OK
<python> harness/harness_status.py --write  # Active Context + REALITY.md

--check is a local command. It executes the pinned absolute interpreter, which by definition does not exist on a CI runner, so it is deliberately not a CI job.

5. Verify - prove it, do not assume it

<python> "$SKILL_DIR/scripts/verify_init.py" PROJECT_ROOT

Asserts guards deny in a form the runtime honours, gates gate, the logger logs, and every harness/tN branch shares history with HEAD. "Files exist" is not verification. Fix anything that fails before the user builds on the harness - a harness that does not block is decorative.

A stock scaffold - no terminal arguments, the shipped 4-terminal config, the 8 shipped agent templates, nothing hand-authored - prints 49 passed, 0 failed followed by Harness PROVEN. The gate is 0 failed, never a fixed total. The total is a function of the tree you asked for: one check per agent file, two per configured agent, one shard check per terminal. A 2-agent 2-terminal project legitimately prints a smaller number. Any doc quoting a total as the pass condition is quoting one particular project.

The model pin - the least discoverable rule here

The pin binds only if you do NOT pass model: at spawn. The Agent tool's model: takes a tier alias (sonnet/opus/haiku), not a model ID; it resolves to latest-of-tier and silently overrides the ID sync_harness.py stamped into the frontmatter. So: spawn by subagent_type alone. Pass model: only for ad-hoc general-purpose/Explore agents, which carry no stamped pin because they are platform built-ins rather than files in .claude/agents/. Say this in the generated CLAUDE.md and AGENTS.md. Nothing errors when it is done wrong - the pin is simply not what runs, and no output ever says so.

Verify by probe: config, settings.json and frontmatter agreeing is not proof; none of them is the runtime. Spawn with no model:, have the agent report its model via /debug, assert it matches models[role].

Reference routing (load only what you need)

Need	Read
Unorganized/brownfield folder; what goes where in context/	references/context-bootstrap.md
Permission MCQ text, profiles, deny list, agent rules	references/permissions-and-rules.md
Context-file fields; ask-vs-infer table	references/context-file-schema.md
Terminal split, gate topology, model tiers, sensitive paths	references/decision-guide.md
What verification proves and why	references/verification.md
Code-quality checks, arch doc format (review-time, not init)	references/architecture-decay.md
Goal packets, bounded retries, blocked/ambiguity routing	templates/docs/12_graph_of_loops.md
Which merge mechanism a shared file gets (merge=harnessjson / union / codegen / intents)	templates/docs/13_hub_files.md

The doctrine set is deliberately not routed here: scaffold.sh already copies templates/docs/*.md into the project's setup/, so reading them out of this skill re-reads ~65 KB the project already has on disk.

Hard rules not stated above

• Never hand-edit .agents/ - it is generated.
• Never hand-add a hook to the project's .claude/settings.json. sync_harness.py assigns settings["hooks"] wholesale, so every run erases hand-added hooks silently - no warning, the hook just stops firing. Add them to the generator. Scope is the project tree only; sync never reads or writes ~/.claude/settings.json.
• Never duplicate a user-tier hook. Hooks from all tiers merge and all fire. A harness hook on PreToolUse/Bash would fight token-efficiency's rtk-rewrite.sh - two rewriters mangling each other. The harness claims Read and Write|Edit, and leaves Bash to the user tier.
• Never put a credential in a tracked file - env-var names only.
• Never hand-write a status block - harness_status.py --write generates it.

Interop

<!-- interop-contract: v1 -->

Edition: CLI (Claude Code). No Cowork edition exists. Precedence:

• Yields to playwright-tester on browser and e2e testing (an e2e gate shells out to npx playwright test, never reimplements triage).
• Yields to production-grade-scaffold on application structure (src/, six layers, security, DB, root manifests, infra/).
• Yields to token-efficiency on RTK, the SoT grammar and PreToolUse:Bash (this skill never claims that matcher).
• Wins over graphify on the control plane (sole installer of .claude/, harness/, hooks).
• Wins over playwright-tester on run isolation under a harness (each context pack exports PW_RUN_DIR).
• Wins over ponytail on harness scaffolding (required, not bloat).
• Wins over production-grade-scaffold on the control plane and parallel-agent writes (terminal domains + worktrees are the write protocol under a harness).
• Wins over token-efficiency on agent memory and model IDs under a harness (sharded schema + models{} are authoritative in a harnessed project).
• Wins over ui-standout on parallel-agent writes (under a harness).
• Disjoint from agent-reach, install-skill, scrapling, skill-creator. Owns: .claude/, harness/, .agents/, .bld/*/phases.md, memory/INDEX.md Active Context, context/architecture/REALITY.md, worktrees on harness/tN. Never writes: src/, root manifests, infra/ (production-grade-scaffold) * ~/.claude/settings.json, ~/.claude/CLAUDE.md (token-efficiency) * tests/, playwright.config.ts, .tests/** (playwright-tester) Matchers claimed: PreToolUse:Read, PreToolUse:Write|Edit|MultiEdit|NotebookEdit, PostToolUse:.*, Stop, SessionStart - project tier, sole claimant. Deliberately not PreToolUse:Bash (ceded to token-efficiency). Model policy: roles, not versions (session/thinker/workhorse/utility); every ID lives in templates/kit/harness.config.json -> models{} with a reason and review date - the project's sole ID home. No relative-pricing claim. Shared-resource protocol: .agents/** - generate-do-not-edit: Edit/Write denied; sole writer is sqlite3 into this terminal's own .agents/logs/<terminal>.db, and .agents/master.db is derived by build_master.py. No sharedWritePaths; shard paths stay out of terminals[].paths on purpose - claiming them would gate a terminal's own logging (_agentsWritePolicy). harness.config.json / .claude/settings.json - single-writer, stamped by sync_harness.py.

Matrix and rulings: ../INTEROP.md.