auto-harness

Auto-Harness

English | Chinese

Auto-Harness is a Claude Code plugin for longer software tasks that need planning, implementation, QA, fixes, retests, and a final report.

Give it a product brief. It turns the work into a durable project workflow, asks clarification questions when needed, drafts a spec for your approval, implements sprint by sprint, evaluates the result, and keeps the trail on disk.

It is inspired by Anthropic's article Harness design for long-running application development.

Which Command Should I Use?

If you are not sure, use the normal serial workflow:

/auto-harness:harness <your product brief>

Use the parallel workflow only when the project is a Git repository and the sprint can be split into independent workstreams:

/auto-harness:harness-parallel <your product brief>

Serial state lives in .harness/. Parallel state lives in .harness-parallel/. The two workflows do not share status files, so you can keep them separate in the same project.

Workflow

brief
  -> clarification
  -> spec draft
  -> user approval
  -> sprint contract
  -> contract review
  -> implementation
  -> QA
  -> fix and retest when needed
  -> final report

Generator agents implement. Evaluator agents review contracts, run QA, retest fixes, and write the final assessment.

Install

Open Claude Code in the project you want Auto-Harness to work on.

/plugin marketplace add redker56/auto-harness
/plugin install auto-harness@auto-harness-marketplace

Restart Claude Code after installing the plugin.

Commands

Command	Use it for
/auto-harness:plan <brief-or-reply>	Run only serial planning: intake, clarification, spec, and design direction
/auto-harness:plan-parallel <brief-or-reply>	Run only parallel planning in .harness-parallel/
/auto-harness:harness <brief-or-reply>	Run or resume the serial end-to-end workflow
/auto-harness:harness-parallel <brief-or-reply>	Run or resume the parallel end-to-end workflow
/auto-harness:build [sprint]	Advance serial Generator work
/auto-harness:build-parallel [sprint]	Advance parallel Generator work
/auto-harness:qa [sprint]	Advance serial Evaluator work: review, QA, retest, or final report
/auto-harness:qa-parallel [sprint]	Advance parallel Evaluator work

Most users can stay with /auto-harness:harness. Use /auto-harness:harness-parallel when you specifically want git worktree based parallel implementation.

What It Creates

Serial workflow files:

.harness/
|-- intake.md
|-- spec.md
|-- design-direction.md
|-- status.md
|-- runtime.md
|-- checkpoints/
|   `-- latest.md
|-- contracts/
|   |-- sprint-01-contract.md
|   `-- sprint-01-review.md
|-- qa/
|   |-- sprint-01-self-check.md
|   |-- sprint-01-qa-report.md
|   |-- sprint-01-fix-log.md
|   `-- sprint-01-retest.md
`-- final/
    `-- qa-final-report.md

Parallel workflow files use the same structure under .harness-parallel/.

Useful files:

File	What it contains
intake.md	Clarified requirements and constraints
spec.md	Approved product plan and sprint breakdown
design-direction.md	UI, UX, and product direction
contracts/sprint-XX-contract.md	What the current sprint must implement
contracts/sprint-XX-review.md	Whether the sprint contract is ready for implementation
runtime.md	How Evaluator should install, start, and check the app
qa/sprint-XX-qa-report.md	QA findings for a sprint
qa/sprint-XX-fix-log.md	Fixes applied after failed QA
qa/sprint-XX-retest.md	Retest results after fixes
final/qa-final-report.md	Final project assessment

Parallel Mode

Parallel mode uses git worktrees for Generator build and fix work.

For build work:

• the sprint contract includes a machine-readable dependency graph
• ready graph nodes are assigned to worker agents
• each worker runs in a dedicated git worktree
• each worker commits its changes
• an integrator merges completed worker branches into the main worktree
• runtime and self-check artifacts are written after all build nodes are merged

For fix work:

• Auto-Harness reads bug IDs from the normal QA or retest report
• bugs are split into temporary fix batches
• workers fix assigned batches in separate worktrees
• an integrator merges completed branches and writes the fix log

Parallel mode can be faster when workstreams are independent. If the sprint is tightly coupled, use the serial workflow.

Resuming Work

Run the same workflow command again from the same project:

/auto-harness:harness

or:

/auto-harness:harness-parallel

Serial commands resume from .harness/status.md. Parallel commands resume from .harness-parallel/status.md.

Requirements

• Claude Code installed and authenticated
• Node.js available on PATH
• a project directory where Auto-Harness can write its state folder
• a Git repository for parallel mode
• Playwright MCP support when you want browser-based QA

The plugin includes .mcp.json configured to launch:

npx -y @playwright/mcp@latest

License

See LICENSE.