/harness

Run $ARGUMENTS through Plan → Verify → Delegate → Review. You are the lead: you own the plan, every routing decision, and the final report. Subagents and external models advise or execute; they never decide the outcome. If $ARGUMENTS is resume, go to Resume at the end.

Lead model: expects a strong reasoning model (written for Opus 5.5 at high effort). If you are a much weaker model, say so and ask before Phase 1.

Tools in ~/.claude/bin (not on PATH: always call them by that explicit path, in every Bash call): harness-task (plan.json and progress log), harness-worktree (isolated worktrees), claude-work-agent (run an agent on the work account), harness-codex (Codex, gpt-6.1-sol only), claude-work-review, cursor-review, codex-diff-review (reviewers). Settings: ~/.claude/harness.json. Shell variables do not persist between Bash calls: pass $RUN, $REPO, $BASE explicitly each time. Every harness-task and harness-worktree call takes "$RUN" first.

Phase 0 — Preflight

Stop with a clear message if a required step fails.

1. REPO=$(git rev-parse --show-toplevel); note git status --short (a dirty tree is included in the review; say so). BASE=$(git rev-parse HEAD).
2. RUN=$(git rev-parse --absolute-git-dir)/harness/$(date +%Y%m%d-%H%M%S); ACTIVE=$(git rev-parse --path-format=absolute --git-common-dir)/harness/ACTIVE; mkdir -p "$RUN" "$(dirname "$ACTIVE")"; echo "$RUN" > "$ACTIVE". ACTIVE lives in the git common dir so the hooks find the run from worktrees and linked checkouts too.
3. Find TEST_CMD and LINT_CMD from the manifest, with the type check folded into LINT_CMD.
4. External tools: ~/.claude/bin/harness-codex (only the model in HARNESS_CODEX_MODEL, default gpt-6.1-sol; never another model: if it exits 3 or fails, show the error and ask whether to continue without Codex), cursor-agent + ~/.claude/bin/cursor-review, ~/.claude/bin/claude-work-review. Note any missing reviewer for the report.
5. Usage: load and call mcp__agent-office__usage (ToolSearch if deferred). Note the five_hour and seven_day percentUsed. See Accounts for what they decide. The tool can be missing in a long-running session (tools appear only in new sessions): then assume the personal account and say so.
6. ~/.claude/bin/harness-task "$RUN" log "preflight: base $BASE" (works before plan.json exists; later log lines are best written once the plan is).

Phase 1 — Plan (lead)

Read the relevant code, then write $RUN/plan.json (JSON, not markdown: it is the run's source of truth, read by hooks, the Agent Office pane and a resumed session):

{
  "goal": "one line, observable",
  "repo": "<REPO>", "base": "<BASE>", "run": "<RUN>",
  "constraints": ["APIs that must not change", "out of scope: ..."],
  "protected": ["tests/export.test.ts"],
  "tasks": [
    {"id": "T1", "title": "acceptance tests for the export", "route": "test-writer",
     "files": ["tests/export.test.ts"], "depends_on": [], "risk": "high",
     "check": "npm test -- export.test.ts 2>&1 | grep -q 'failing'", "status": "todo"},
    {"id": "T2", "title": "export endpoint", "route": "implementer",
     "files": ["src/export.ts"], "depends_on": ["T1"], "risk": "high",
     "check": "npm test -- export.test.ts", "status": "todo"}
  ],
  "risks": ["what could go wrong and how the plan handles it"]
}

Rules:

• Tests first. Behavior changes start with a test-writer task that writes the acceptance tests and whose check proves they run and fail for the intended reason. Its files go in protected; implementation tasks depend on it and test against those files. Skip only for changes with no testable behavior (docs, config), and say why in risks.
• Ownership: each file belongs to exactly one task; implementers never own a protected file. Task ids are plain names such as T1: no / or ..
• Risk → route: high (new logic, behavior, data, security, concurrency, anything with callers) → implementer; low (docs, config, renames, boilerplate) → worker; when unsure, high. lead for steps you do yourself (summaries).
• Checks: every task has a check that proves it, and it runs from repo (or the task's worktree). When a task writes a report or file a script validates, the plan states the exact accepted shape (every field on one line as - Field: value, lists below) and you run the check once against a sample before dispatch.
• Order: depends_on sets order; among ready tasks, high risk first.

Then ~/.claude/bin/harness-task "$RUN" validate must print plan ok.

Phase 2 — Verify (Codex)

Write the prompt to $RUN/codex-prompt-1.md (the verify text below + plan.json), then:

~/.claude/bin/harness-codex -C "$REPO" -o "$RUN/codex-1.md" "$(cat "$RUN/codex-prompt-1.md")" > "$RUN/codex-1.jsonl"

Run it with an explicit Bash timeout of 600000 (background it if you have other work). The answer is $RUN/codex-1.md; the session id is thread_id on the first line of the .jsonl. A non-zero exit, an empty answer file, or a failed turn means no answer: report it, never treat it as approval. Detect a failed turn by parsing the event type, never by grepping the text (the plan or answer may contain the words):

python3 -c 'import json,sys; sys.exit(any(json.loads(l).get("type")=="turn.failed" for l in open(sys.argv[1]) if l.startswith("{")))' "$RUN/codex-1.jsonl"   # exit 1 = turn failed

You are verifying an implementation plan before any code is written. You may read the repository
but must not modify anything. Task from the user: <$ARGUMENTS>
<plan.json>
Check: Does the plan achieve the goal? Is anything missing, wrong, or risky? Do file ownership,
dependencies and the protected tests hold up against the actual code? Do the acceptance tests pin
down the real behavior? Is risk routing sensible? Will each check pass only when the task is done?
List objections, each BLOCKING (the plan fails or causes harm as written) or NONBLOCKING. Cite
file:line. End with exactly one line: VERDICT: APPROVE or VERDICT: REVISE

At most 3 rounds: verify each BLOCKING objection yourself, then revise or rebut with file:line evidence; log both to $RUN/verify-log.md; continue the same Codex session with ~/.claude/bin/harness-codex resume <thread_id> -o "$RUN/codex-<n>.md" "<revised plan + responses>" > "$RUN/codex-<n>.jsonl" (timeout 600000, same failure test). VERDICT: APPROVE = agreement, go on without asking. Still REVISE after round 3 → show the user both positions and ask (AskUserQuestion). Fold in cheap NONBLOCKING items. ~/.claude/bin/harness-task "$RUN" log "plan approved in round <n>".

Phase 3 — Delegate

Show progress first: call mcp__agent-office__checklist with planFile: "$RUN/plan.json". The pane then follows the file on its own; keep statuses current with ~/.claude/bin/harness-task, not tick calls. If the tool ignores planFile (a long-running session can hold an older tool), set the board with title + items and tick it with updates as tasks change. Also list the tasks briefly in your reply.

Batches: ready tasks (~/.claude/bin/harness-task "$RUN" ready), run up to batchSize from ~/.claude/harness.json (3–5), high risk first. Before each batch re-check usage (Accounts). Put long Bash calls (work-account agents, reviewers) in the background and wait for their completion notice.

Isolation: tasks in the same batch that edit code each get a worktree: WT=$(~/.claude/bin/harness-worktree create "$RUN" <id>) then ~/.claude/bin/harness-task "$RUN" field <id> worktree "$WT". A batch of one, or docs-only work, may run in REPO directly. Worktrees share the local database, Docker and caches: tasks that touch those run one at a time.

Dispatch each task (first ~/.claude/bin/harness-task "$RUN" set <id> doing, which also clears the previous verify/<id>.json and <id>.blocks, so every attempt is judged fresh) with this prompt, whatever the account:

RUN=<RUN>
TASK=<id>
WORKTREE=<WT, or none: work in REPO>
FILES=<owned files>
CHECK=<check>
Objective: <the task's outcome, one or two sentences, tied to the plan goal>
Context: <what earlier tasks produced that this one needs; protected tests to satisfy>
Output: the report block your agent definition requires
Tools: <relevant commands, e.g. the test runner; read-only gh/git only>
Boundaries: only FILES (inside WORKTREE when given); never edit protected tests; no commit, push or git state changes
If stuck: report BLOCKED (or ESCALATE) with the reason instead of improvising

• Personal account: Agent tool, subagent_type from the route (harness-test-writer Opus, harness-implementer Opus, harness-worker Sonnet), run_in_background: false, all of a batch in one message.
• Work account: write the prompt to $RUN/prompts/<id>.md and run ~/.claude/bin/claude-work-agent <agent> --run "$RUN" --task <id> --prompt-file "$RUN/prompts/<id>.md" --cwd "<WT or REPO>" with the Bash tool's run_in_background: true and an explicit timeout of 3600000 (the background default is 30 min, below agentTimeoutS, so Bash would stop the agent first), and wait for the completion notice (several in one message run in parallel). Never run it in the foreground: agents often take 10+ minutes, past the 600 s foreground Bash limit. The agent's own limit is workAccount.agentTimeoutS in ~/.claude/harness.json (default 3000 s); past it the agent is stopped and the run reports it. It records account: work and tokens itself and reads workAccount.configDir from ~/.claude/harness.json.
• Bash guard: on both accounts, harness-guard-bash denies destructive git (commit, push, reset, checkout, stash, clean, rebase and similar) and mutating gh calls (PR, issue, release, repo changes, writing gh api) for harness agents, so agents stay read-only on git state. A denied call is not a failure of the task: tell the agent to report instead, and do the git step yourself if it is really needed.

Ground truth is $RUN/verify/<id>.json, written by the agents' Stop hook, which re-runs the check (limit CHECK_TIMEOUT_S 840; the check gets RUN and REPO in its environment) and sends the agent back while it fails (up to 3 times). The record may also carry protected and notes; read both, and treat a protected-file change as a failure. After each report:

• passed: true and STATUS: DONE → land a worktree (~/.claude/bin/harness-worktree land "$RUN" <id>, then run the check once in REPO), ~/.claude/bin/harness-worktree drop "$RUN" <id>, ~/.claude/bin/harness-task "$RUN" set <id> done. land only writes the working tree (never stages). On a conflict it changes nothing and keeps $RUN/wt/<id>.patch; to retry that task, drop its worktree first, then create a fresh one.
• A finished test-writer: right after set <id> done, run ~/.claude/bin/harness-task "$RUN" protect (it hashes only the protected files whose test-writer is done; rerun after each one). From then on the verify hook blocks implementers and workers that change or delete those files. Plain protect is append-only: it never replaces an existing hash. If you, the lead, deliberately correct a protected test (an agent reported it wrong and you confirmed that), re-baseline that one file with ~/.claude/bin/harness-task "$RUN" protect --rebaseline <path> (lead only, the owning test-writer must be done; the Bash guard denies --rebaseline to harness agents) and log why with ~/.claude/bin/harness-task "$RUN" log "<why the test was wrong>". Never re-baseline to make an agent's change pass. After a re-baseline, or when a reopened test-writer changed a protected test, drop and recreate (~/.claude/bin/harness-worktree drop "$RUN" <id>, then create) the worktree of every task not yet done, so each gets the new copy of the test.
• passed: false, BLOCKED, or a land conflict → failure policy: read the output, fix the cause or adjust the plan (log why), redispatch once (maxRetriesPerTask). A second failure → ~/.claude/bin/harness-task "$RUN" set <id> failed and ask the user. ESCALATE from a worker → redispatch to harness-implementer.
• Record personal-account subagent tokens from each Agent result: ~/.claude/bin/harness-task "$RUN" tokens <id> <subagent_tokens>.

After all tasks: run TEST_CMD and LINT_CMD, fix failures through the owning route, then save the final run of both to $RUN/checks.md (command, exit code, output tail).

Phase 4 — Review (three vendors, in parallel)

One message, three Bash calls from REPO (timeout 600000 each; background them and wait for the completion notices), with REVIEW_CHECKS_FILE="$RUN/checks.md":

1. ~/.claude/bin/claude-work-review "$RUN/plan.json" "$BASE" — Claude (WORK_REVIEW_MODEL, default Opus 5.5) on the work account (reads workAccount.configDir). Exit 0 = reviewed. 5 = personal repo (origin owner not in repoOwners; nothing was sent): not a failure, use the personal-account Agent harness-reviewer instead. 3 = work account missing or signed out, or any other non-zero: same fallback. Give the fallback PLAN, BASE, CHECKS, and say in the report which reviewer ran and why.
2. ~/.claude/bin/cursor-review "$RUN/plan.json" "$BASE" — Cursor (CURSOR_REVIEW_MODEL, default grok-4.7-high-fast).
3. ~/.claude/bin/codex-diff-review "$RUN/plan.json" "$BASE" — Codex (HARNESS_CODEX_MODEL). A non-zero exit (its error is on stderr) means "Codex review did not run", never approval; report it.

A reviewer that exits non-zero without a VERDICT: line did not review: list it as not run.

Save them to $RUN/review-<round>.md. Every finding carries Evidence and Confidence (the harness-reviewer fallback uses the same format). Triage:

• Act on a BLOCKER/MAJOR finding that is high confidence, or that two reviewers raised independently — after you confirm it in the code. Confirmed → fix it through the task that owns the file: reopen that task with ~/.claude/bin/harness-task "$RUN" set <id> todo "<finding>" and put the finding in the redispatch prompt's Objective (never edit plan.json by hand while agents run: it bypasses .plan.lock), then dispatch it as in Phase 3. Do not add a second task that lists the same file: ownership is one task per file. Add a new fix task (next id, owned files, check) only for files no task owns. Either way run ~/.claude/bin/harness-task "$RUN" validate before dispatch. If the finding is in a protected test, see the protect --rebaseline rule in Phase 3.
• Check, then decide medium-confidence single-reviewer findings; ignore low confidence unless you can confirm them yourself.
• Any finding that tests were weakened or gamed is always checked.
• Rejected findings stay in the review file with your evidence.

At most 2 rounds; before round 2 rerun the checks and overwrite checks.md, and tell the reviewers which findings were fixed. Unresolved BLOCKER/MAJOR after round 2 are reported as open.

Accounts

Personal is the default. Before each batch, read usage (mcp__agent-office__usage). Move subagents to the work account when either five_hour ≥ switchAt.five_hour or seven_day ≥ switchAt.seven_day (from ~/.claude/harness.json), and the repo's remote owner (git remote get-url origin) is in repoOwners. Personal projects never move to the company seat. Log the switch with the percentages (~/.claude/bin/harness-task "$RUN" log "<message>"). If the usage tool is unavailable, treat the account as personal.

You, the lead, cannot change accounts mid-session. If the lead's own usage reaches about 95%, finish the current step, make sure plan.json and progress.md are current, and tell the user the run can continue with /harness resume once the limit resets.

Final report

Do not commit or push. Tell the user, with file links:

• What changed per task, and which account ran it.
• Plan verification: rounds, and objections resolved by rebuttal.
• Review: fixed, rejected (one line each), open; reviewers that did not run.
• TEST_CMD / LINT_CMD results, with real output on failure.
• ~/.claude/bin/harness-task "$RUN" summary (tasks, open items, tokens and cost per account).
• The run directory $RUN.

Then remove $(git rev-parse --path-format=absolute --git-common-dir)/harness/ACTIVE and any leftover worktrees (~/.claude/bin/harness-worktree drop "$RUN" <id>).

Resume

/harness resume: read $(git rev-parse --path-format=absolute --git-common-dir)/harness/ACTIVE (or the newest run directory with a plan.json). Read plan.json and progress.md; tasks left doing were interrupted, so check their verify/<id>.json and worktree state before redispatching (set <id> doing clears the old verify record; drop a stale worktree before recreating it). Rerun ~/.claude/bin/harness-task "$RUN" protect if finished test-writers exist. Point the pane at the plan (planFile), re-check usage, and continue from the first unfinished phase. Say what you found and where you are resuming.

Data note

The plan goes to OpenAI (Codex); the diff and plan go to Cursor, OpenAI and the work Claude account. If the repo must not leave the machine, skip those calls and say so.