harness · v0.16.0 · 2026-05-09 · sha256 3d89a522af04f12f
harness v0.16.0A
Immutable. This exact content is served forever at /api/v1/blob/3d89a522af04f12f.
---
name: harness
version: 0.16.0
description: |
Cybernetics-based multi-agent orchestration for complex tasks. Coordinates a
Planner → Generator → Evaluator → Retro pipeline with clean-context sub-agents,
per-checkpoint drift prevention, and persistent retro learning.
Recommended workflow: Claude Code plans the spec (Session 1), Codex executes
autonomously (Session 2), Claude CLI reviews as cross-model peer.
Use when: "harness this task", "use harness", "orchestrate this",
"harness plan", "harness continue", "harness execute <task-id>",
"harness <spec-name>", or when a task requires structured multi-agent coordination.
---
# Harness — Multi-Agent Orchestration
Orchestrate complex tasks through Planning -> Generation -> Evaluation -> Retro.
Fresh sub-agents per checkpoint prevent drift. Retro accumulates learning across tasks.
## Recommended Workflow
```
Session 1 (Claude Code) → Brainstorm + Spec → Spec review with cross-model evaluator
↓ spec approved
Session 2 (Codex) → Execute checkpoints → Evaluate → E2E → Full-verify → PR → Retro
↕ Claude CLI as review-loop peer (cross-model quality gate)
```
- **Session 1**: Claude Code for interactive discovery — brainstorming + multi-turn Q&A to establish requirements. **After the user approves the brainstormed design, spec drafting and the Spec Evaluator review loop run autonomously** (agent-to-agent until consensus). See [references/planning-protocol.md](references/planning-protocol.md) "Post-Brainstorming Autonomy".
- **Session 2**: Codex for autonomous execution — implementation, evaluation, PR creation, retro. Claude CLI serves as cross-model reviewer via `review-loop`.
- Both hosts support both phases. The above is the **recommended** flow, not a hard constraint.
## Prerequisites
1. `superpowers` plugin installed (Claude Code): Generator preloads TDD, verification, debugging skills
2. Reviewer role definitions: `harness-convention-scout.md`, `harness-spec-evaluator.md`, `harness-generator.md`, `harness-evaluator.md`, `harness-retro.md` — ship with this plugin at `plugins/harness-engineering-skills/agents/`; user overrides may live at `~/.claude/agents/harness-*.md`
3. `python3` on PATH (engine JSON operations)
4. `git` repository initialized
5. For Codex-hosted execution: `claude` CLI on PATH for sub-agent dispatch and review-loop
Verify (Claude Code): `claude plugin list | grep superpowers`
Verify (review roles): `{ find ~/.claude/plugins -path '*/plugins/harness-engineering-skills/agents/harness-*.md' -type f 2>/dev/null; ls plugins/harness-engineering-skills/agents/harness-*.md 2>/dev/null; ls ~/.claude/agents/harness-*.md 2>/dev/null; } | sort -u`
Verify (Codex): `codex --version && claude --version`
## Engine Script
All deterministic state management is handled by `harness-engine.sh`. To locate it:
```bash
ENGINE="$(find ~/.claude/plugins/cache -path "*/harness/scripts/harness-engine.sh" -type f 2>/dev/null | head -1)"
```
If not found, try `find ~/.claude/skills -path "*/harness/scripts/harness-engine.sh"` or `find ~/.codex/skills -path "*/harness/scripts/harness-engine.sh"` as fallback. In a checked-out repo, `plugins/harness-engineering-skills/skills/harness/scripts/harness-engine.sh` is also valid.
Delegate ALL file-system and git bookkeeping to the engine.
## Configuration
| Setting | Default | Options |
|---------|---------|---------|
| `max_spec_rounds` | `3` | 1–5 |
| `max_eval_rounds` | `3` | 1–5 |
| `cross_model_review` | `true` | `true` → triggers `review-loop` after E2E, before PR |
| `cross_model_peer` | `codex` | `codex`, `claude`, `gemini` — use `claude` when Codex is the host |
| `cross_model_read_only` | `false` | `true` = report-only, `false` = iterative fix |
| `auto_retro` | `true` | `false` to skip retro |
| `claude_md_path` | `auto` | Path to CLAUDE.md. `auto` detects |
| `max_verify_rounds` | `3` | 1–5, max iterations for full-verify fix loop |
| `coverage_threshold` | `85` | Hard minimum — FAIL if below this % |
| `skip_full_verify` | `false` | `true` → skip full-verify phase |
| `autonomous_pr` | `true` | `false` → write `.harness/<task-id>/pr-handoff.md` instead of running `gh pr create` |
| `commit_lock_timeout_seconds` | `120` | 1-3600; 120s typical to absorb pre-commit hooks |
| `enable_parallel_cohorts` | `true` | `true`/`false`; false rejects multi-member cohorts |
| `max_parallel_cohort_size` | `4` | 1-16; 4 covers typical Agent-tool batch limits |
**Precedence**: defaults < `.harness/config.json` < invocation args
Read config: `$ENGINE read-config [--max-spec-rounds N] [--max-eval-rounds N] [--autonomous-pr true|false] ...`
## Architecture
```
Orchestrator (you, the Main Agent — Claude Code or Codex)
├── Planning Phase → YOU are the Planner (direct user interaction)
│ ├── harness-convention-scout → sub-agent, host-repo convention discovery + Card
│ ↕ spec-review/ → iterate with Spec Evaluator on checkpoint quality
├── Spec Evaluator → sub-agent, architecture + feasibility
├── Generator → sub-agent (or local in Codex), TDD skill preloaded
│ ↕ evaluation → iterate with Evaluator per checkpoint
├── Evaluator → sub-agent, composite sensor
└── Retro → sub-agent, produces retro.md
```
**Sub-agent dispatch:** In Claude Code use `Agent(subagent_type: "harness-*", prompt: <context>)`. In Codex use `claude-agent-invoke.sh` to dispatch via CLI. See [references/codex-mode.md](references/codex-mode.md) for Codex-specific details.
**Anti-drift mechanisms:**
- Fresh Generator + Evaluator per checkpoint (full eigenbehavior reset)
- SendMessage reuse within checkpoint iterations (bounded trade-off for efficiency)
- Two-session split: planning context discarded before execution
- Engine hard gates: `pass-checkpoint` requires latest `evaluation.md` verdict PASS plus fresh evaluator session proof (`evaluator-session-id.txt` not reused by prior checkpoints), `pass-e2e` requires latest `e2e-report.md` verdict PASS, and `pass-review-loop` requires a completed review-loop session.
## File System Layout
```
.harness/
|-- config.json # Project config (git-tracked)
|-- <task-id>/ # Per-task (gitignored)
| |-- spec.md
| |-- git-state.json
| |-- spec-review/
| | |-- round-N-spec-review.md
| | |-- round-N-planner-response.md
| | `-- status.md
| |-- checkpoints/
| | `-- NN/
| | |-- context.md
| | |-- iter-N/
| | | |-- output-summary.md
| | | |-- evaluation.md
| | | |-- evaluator-session-id.txt
| | | `-- evidence/
| | `-- status.md
| |-- e2e/
| | |-- iter-N/ {context.md, e2e-report.md, evidence/}
| | `-- status.md
| |-- full-verify/
| | |-- discovery.md
| | |-- iter-N/
| | | |-- verification-report.md
| | | `-- evidence/
| | `-- status.md
| `-- retro-input.md
`-- retro/ # Persistent (git-tracked)
|-- index.md
`-- <date>-<task-id>.md
```
Gitignore entries are auto-added by `$ENGINE init`.
## Protocol Loading
This skill splits into two protocol files to minimize context usage. **Read the one matching your intent before proceeding.**
| Intent | Trigger phrases | Action |
|--------|----------------|--------|
| **Planning** | "harness plan", "harness this task", "use harness", "harness spec" | Read [references/planning-protocol.md](references/planning-protocol.md) |
| **Execution** | "harness continue", "harness execute <task-id>", "harness <spec-name>" | Read [references/execution-protocol.md](references/execution-protocol.md) |
**After loading the protocol, follow it completely.** Do not proceed without reading the appropriate reference file.
## Reference Files
- [references/planning-protocol.md](references/planning-protocol.md) — Session 1: spec creation and review (Claude Code recommended)
- [references/execution-protocol.md](references/execution-protocol.md) — Session 2: checkpoint execution through retro (Codex recommended)
- [references/protocol-quick-ref.md](references/protocol-quick-ref.md) — All file format specs (passed to agents via prompt)
- [references/checkpoint-definition.md](references/checkpoint-definition.md) — Checkpoint definition, numbering, granularity, scope constraint, and Planner guidance
- [references/codex-mode.md](references/codex-mode.md) — Codex-hosted sub-agent dispatch details