Harness

---
name: harness
description: This skill should be used when the user asks to "/harness", "build an application with harness", "run the harness", "start a harness build", "multi-agent build", "planner evaluator build", "long-running application build", or wants to build a complete application using the planner-generator-evaluator architecture. Orchestrates a multi-agent loop inspired by Anthropic's harness design pattern for long-running AI application development.
argument-hint: <brief description of what to build>
allowed-tools: [Read, Write, Edit, Bash, Glob, Grep, Agent, TodoWrite, AskUserQuestion]
---

# Harness — Multi-Agent Build Orchestrator

## Overview

Orchestrate long-running application development using three specialized agents: Planner, Generator, and Evaluator. Based on Anthropic's harness design pattern where separating the agent doing the work from the agent judging it produces dramatically better results than solo generation.

The harness runs a Plan-Build-Evaluate loop. Each agent gets a fresh context with only file-based handoff artifacts — context reset is structural, not manual.

## Architecture

```
User brief → Planner → spec.md → Generator → app code → Evaluator → eval-report.md
                                       ↑                                    |
                                       └────── iterate/pivot ───────────────┘
```

Three agents, three distinct contexts, file-based communication:
- **Planner** (cyan): Expands brief into product spec. High-level only — no implementation details.
- **Generator** (magenta): Builds the application from spec. Runs in worktree isolation.
- **Evaluator** (yellow): Tests the running app like a real user. Skeptical by default.

## Execution Flow

### Phase 1: Initialize

Create the harness workspace in the current project:

```
.harness/
├── config.json          # Harness configuration
├── state.json           # Current phase, round, active components
├── spec.md              # Planner output (Phase 2)
├── build-summary-N.md   # Generator output per round
└── eval-report-N.md     # Evaluator output per round
```

Read `.harness/config.json` if it exists to check for disabled components (from `/harness-simplify`).

Initialize `.harness/state.json`:
```json
{
  "phase": "planning",
  "round": 0,
  "maxRounds": 5,
  "components": {
    "planner": true,
    "evaluator": true
  },
  "brief": "<user's brief>"
}
```

### Phase 2: Plan

Dispatch the `harness-planner` agent with the user's brief.

The planner writes `.harness/spec.md`. After it completes, present the spec summary to the user and ask for approval before proceeding. The user may request changes — re-dispatch the planner if needed.

If `config.json` has `"planner": false`, skip this phase and ask the user to provide a spec manually or write one from the brief directly.

### Phase 3: Build-Evaluate Loop

For each round (up to `maxRounds`):

**3a. Generate:**
Dispatch the `harness-generator` agent with:
- `.harness/spec.md`
- `.harness/eval-report-{N-1}.md` (if round > 1)
- Use `isolation: "worktree"` for clean workspace

The generator writes `.harness/build-summary-{N}.md` when done.

Update `state.json`: `"phase": "building", "round": N`

**3b. Evaluate:**
If evaluator is enabled in config, dispatch the `harness-evaluator` agent with:
- `.harness/spec.md`
- `.harness/build-summary-{N}.md`
- Access to the running application

The evaluator writes `.harness/eval-report-{N}.md` with verdict: PASS, ITERATE, or PIVOT.

Update `state.json`: `"phase": "evaluating", "round": N`

**3c. Decision:**
- **PASS**: Loop ends. Present final eval report to user. Proceed to finalization.
- **ITERATE**: Present eval report summary to user. Ask: "Continue with next round, or stop here?" If yes, loop back to 3a.
- **PIVOT**: Present eval report. Ask user whether to restart implementation or adjust spec. May re-dispatch planner.

If evaluator is disabled in config (`"evaluator": false`), skip 3b and ask the user to review the build output manually.

### Phase 4: Finalize

When the build passes evaluation (or user accepts current state):
1. Update `state.json`: `"phase": "complete"`
2. Present summary: rounds completed, total cost estimate, what was built
3. If using worktree isolation, inform user about merging the branch

## Key Design Decisions

**Context reset via subagents**: Each Agent dispatch starts a fresh context. The generator doesn't see the planner's reasoning — only its output file. This prevents context anxiety and keeps each agent focused.

**File-based handoffs**: All communication goes through `.harness/*.md` files. This survives session restarts and makes state inspectable.

**User checkpoints**: The harness pauses for user confirmation at three points:
1. After planning (approve spec)
2. After each eval round (continue/stop)
3. After pivot recommendation (restart/adjust)

Never auto-proceed past these checkpoints without user input.

**Evaluator is optional**: The evaluator adds cost and time. For simple tasks, the generator may be sufficient solo. The `/harness-simplify` skill tests this empirically.

## Configuration

`.harness/config.json` controls which components are active:

```json
{
  "planner": true,
  "evaluator": true,
  "maxRounds": 5,
  "generatorModel": "opus",
  "evaluatorModel": "opus"
}
```

All fields optional. Defaults: all components enabled, maxRounds=5, opus models.

## Resumption

If the harness is interrupted, read `.harness/state.json` to determine where to resume:
- `"phase": "planning"` → Re-dispatch planner or present existing spec
- `"phase": "building"` → Check if build summary exists for current round
- `"phase": "evaluating"` → Check if eval report exists for current round
- `"phase": "complete"` → Inform user the harness already finished

## Additional Resources

### Reference Files
- **`references/grading-criteria.md`** — Evaluator rubric details and tuning guidance
- **`references/simplification.md`** — How to stress-test and remove harness components

### Templates
- **`${CLAUDE_PLUGIN_ROOT}/templates/config.json`** — Default harness configuration
- **`${CLAUDE_PLUGIN_ROOT}/templates/spec.md`** — Spec template for planner
- **`${CLAUDE_PLUGIN_ROOT}/templates/eval-report.md`** — Eval report template