agent-harness

The saved excerpt is a snapshot from review. The external source remains the complete and most current version.

---
name: agent-harness
description: "Turn any domain folder of skills into a bounded agentic loop: compile a goal into a verifiable task plan, execute tasks with the domain's own tools, verify every task with machine-run checks, retry with caps, escalate to a human when budgets exhaust, and refuse to close until everything is verified or explicitly waived. Use when you want an agent or subagent to pick up a goal and drive it to a verified close across one of this repo's 18 domains ('run this goal through the engineering harness', 'set up an agentic loop for marketing work', 'make the finance domain self-verifying'). NOT for authoring Claude Code Workflow-tool .js scripts (workflow-builder), N-agent tournaments on one task (agenthub), single-file metric optimization (autoresearch-agent), or discovering published loop recipes (loop-library)."
---

# Agent Harness

You are a harness operator, not a hero. The loop — not your optimism — decides when work
is done. Your job: compile the goal into tasks with checks, execute one task at a time,
let the controller adjudicate verification, and stop when the state machine says stop.

## The contract

```
GOAL → goal_compiler → PLAN → loop_controller: [execute → verify]* → CLOSE
                                     ↑______retry (≤ max_attempts, changed approach)
                                     └── ESCALATE on exhausted budgets — never fake success
```

Three layers, all JSON: a committed per-domain **manifest** (what skills/tools/checks
exist), a per-goal **plan** (which tasks, which verifications, what "done" means), and a
per-run **state file** (the single source of truth; a fresh session resumes from it alone).

## Quick start

```bash
# 0. Pick the domain manifest (18 committed under assets/harnesses/, e.g. engineering-team.json)
ls assets/harnesses/

# 1. Compile the goal (refuses vague goals with exit 3 + forcing questions)
python3 scripts/goal_compiler.py \
  --goal "audit the payments service and design an SLO with an error budget" \
  --manifest assets/harnesses/engineering.json --out plan.json

# 2. Initialize the loop state
python3 scripts/loop_controller.py init --plan plan.json --state .agent-harness/state.json

# 3. Drive the loop — repeat until directive is "close" or "escalate"
python3 scripts/loop_controller.py next --state .agent-harness/state.json
#    → {"action": "execute", "task": "T1", ...}: open the task's skill (SKILL.md at
#      skill_path), do the work with its tools, then:
python3 scripts/loop_controller.py record --state .agent-harness/state.json \
  --task T1 --phase execute --exit-code 0
#    → the controller runs the task's checks ITSELF (subprocess, timeout, evidence log):
python3 scripts/loop_controller.py verify --state .agent-harness/state.json --task T1 --cwd <repo-root>

# 4. Close — refused (exit 4) while any task is unverified and unwaived
python3 scripts/loop_controller.py close --state .agent-harness/state.json
```

Regenerate a manifest after skills change (diff-stable, CI-checkable):

```bash
python3 scripts/harness_manifest_builder.py --domain engineering-team \
  --repo-root <repo-root> --out-dir assets/harnesses --no-timestamp
```

## Hard rules

1. **Never adjudicate your own verification.** `verify` runs the checks via subprocess;
   a passing `record --phase verify` without `--evidence` is rejected (exit 6). You do not
   get to declare a task verified.
2. **Never modify a gate you are judged by.** Check commands come from the manifest/plan.
   Editing a check to make it pass is the reward-hacking failure mode
   (see [references/verification_discipline.md](references/verification_discipline.md)) — same
   invariant as autoresearch-agent's locked evaluator.
3. **One task at a time, writes serialized.** Parallelize reading and judging, never two
   tasks writing the same artifact ([references/agentic_loop_canon.md](references/agentic_loop_canon.md)).
4. **Retry means a changed approach.** Same command + same input = same failure. The