dev-harness-cli

---

What is this?

AI coding agents are great at doing work and bad at knowing what work to do, in what order, and whether it's actually finished. Frontier models drift and rubber-stamp their own output; small local models get lost entirely.

Dev Harness fixes this by splitting the job:

The agent (any LLM)	The harness (this tool)
Writes the code, tests, docs	Decides what's next (dev-harness next)
Reads the brief and follows it	Enforces phase order (can't skip to SHIP)
Runs one command when done	Verifies with deterministic gates (lint/tests/criteria/placeholders)
—	Persists state across sessions (handoffs, lessons, retries)

The result: a weak model gets the trajectory of a strong one, and a strong model stops hallucinating scope. The agent never has to plan the process — only execute the current step well.

flowchart LR
    DEFINE[📐 DEFINE<br/>spec + contract] --> PLAN[📋 PLAN<br/>features + tasks]
    PLAN --> BUILD[🛠️ BUILD<br/>task by task, test-first]
    BUILD --> VERIFY[✅ VERIFY<br/>prove it works]
    VERIFY -.-> SIMPLIFY[🧹 SIMPLIFY<br/>refactor]
    VERIFY --> REVIEW[🔍 REVIEW<br/>two-axis review]
    SIMPLIFY --> REVIEW
    REVIEW --> SHIP[🚀 SHIP<br/>tag + release]

    style DEFINE fill:#4A90D9,color:#fff,stroke:none
    style PLAN fill:#50C878,color:#fff,stroke:none
    style BUILD fill:#FF8C42,color:#fff,stroke:none
    style VERIFY fill:#9B59B6,color:#fff,stroke:none
    style SIMPLIFY fill:#F1C40F,color:#333,stroke:none
    style REVIEW fill:#E74C3C,color:#fff,stroke:none
    style SHIP fill:#2ECC71,color:#fff,stroke:none

Every phase has gates — automated pass/fail checks (contract agreed? tests green? acceptance criteria met? no TODO stubs left?). The pipeline cannot advance until the current gate passes. No more "done!" that isn't.

The loop

The agent only ever needs this:

1. dev-harness next          ← complete brief: role, goal, task, criteria
2. do the work it describes
3. dev-harness validate      ← the gate is the referee
4. FAIL → fix the listed checks, validate again
5. PASS → dev-harness phase next → back to 1

next is the trajectory engine. It reads real pipeline state and emits a self-contained instruction brief — no planning required from the model:

═══ NEXT STEP · BUILD (3/6) · feature-001 · task-001 ═══
You are the GENERATOR. Focused and practical. Build exactly what the task specifies.

TASK
  Implement add(a,b) with tests
  (feature: User can add two numbers)

ACCEPTANCE CRITERIA — implement until all true
  1. add(2,3) === 5
  2. add(-1,1) === 0

READ FIRST
  harness/docs/phases/build.md — phase instructions
  harness/skills/tdd.md — craft skill — follow it while working

DO THIS
  1. dev-harness validate --feature feature-001 --task task-001
  2. dev-harness next

It handles every state: fresh scaffold → "start here"; mid-phase → live ✓/✗ gate checklist of remaining work; all gates green → "advance"; retries exhausted → "PAUSED, get a human". It is read-only and safe to call anytime.

Quick Start

# 0. (optional) install globally — or just use npx everywhere
npm install -g dev-harness-cli

# 1. Scaffold the harness into a project (new or existing)
npx dev-harness-cli init --stack node --agent-tool claude-code
#    --agent-tool: claude-code | codex | cursor | copilot | windsurf | gemini |
#                  cline | roo | kilo-code | amazon-q | aider | opencode |
#                  antigravity | openclaw | pi | all   (comma-separate for several)

# 2. Open your coding agent in the project and say:
#    "Continue the pipeline"  (or just: "run dev-harness next and follow it")

That's it. init generates everything your agent needs to find the harness:

Agent	What init generates	How it activates
Claude Code	.mcp.json + .claude/skills/dev-harness/ + CLAUDE.md (pointer) + AGENTS.md	MCP tools + skill auto-load
Codex CLI	AGENTS.md (read natively)	instructions; MCP via ~/.codex/config.toml (see adapter)
Cursor	.cursor/mcp.json + .cursorrules	MCP tools + rules
VS Code / Copilot	.vscode/mcp.json + .github/copilot-instructions.md	MCP tools + instructions
Gemini CLI	.gemini/settings.json + GEMINI.md (pointer)	MCP tools + instructions
OpenCode	opencode.json + AGENTS.md	MCP tools + instructions
Windsurf / Cline / Roo / Kilo / Amazon Q / aider	tool-specific rules file	instructions
Anything else	AGENTS.md	agent reads it and drives the CLI

MCP Server

dev-harness mcp runs a built-in, zero-dependency Model Context Protocol server on stdio. Agents that speak MCP get the harness as native tools instead of shell commands:

Tool	Purpose
harness_next	The trajectory brief — call first and after every validate
harness_validate	Run gates (whole phase, or one task with feature+task)
harness_advance	Advance phase when the gate passes
harness_status	Full state snapshot
harness_learn / harness_decision	Persist lessons / decisions
harness_contract	Sprint contract propose/review/status

Manual registration for any MCP client:

{ "mcpServers": { "dev-harness": { "command": "npx", "args": ["-y", "dev-harness-cli", "mcp"] } } }

Craft skills — how the work gets done well

Process alone doesn't make a junior model code like a senior team — craft does. init scaffolds a 28-skill library into harness/skills/ and next matches the right ones to your current task by content:

• Process skills (phase-mapped, adapted from mattpocock/skills, MIT Matt Pocock): grilling + domain-modeling + research (DEFINE) · planning-tasks + codebase-design (PLAN) · tdd + prototype (BUILD) · diagnosing-bugs (VERIFY) · code-review (REVIEW) · resolving-merge-conflicts (anytime)
• Domain skills (task-matched by tags): databases · http-apis · auth-security · frontend-ui · testing-infra · concurrency-async · performance · error-handling-logging · config-and-secrets · cli-design
• Frontier playbook (how a strong model operates, wired into every brief): self-review (part of DONE, every task) · stuck-protocol (fires on repeated retry failures) · context-hygiene · scope-discipline

A task mentioning postgres gets databases.md in its brief automatically; a JWT endpoint task gets auth-security + http-apis. In verbose brief style the top skill's checklist is inlined into DONE-WHEN — applying it becomes gate-visible, not optional reading.

The Capability Ladder — the library that grows itself

No fixed library covers all of software engineering, so the harness ships a resolution ladder instead, applied uniformly to skills (knowledge), MCP servers (system access), tools (executables), and facts (research):

Tier 0 — HAVE IT     dev-harness capability match "<task>"     (local index)
Tier 1 — ACQUIRE IT  dev-harness capability search "<query>"   (queries npm,
                     the MCP registry, GitHub, crates — live, zero setup)
Tier 2 — CREATE IT   dev-harness capability create skill|tool|mcp <name>
                     (mcp: scaffolds a WORKING zero-dep server + self-test)
Tier 3 — KEEP IT     dev-harness capability add ...  → indexed, matched,
                     injected into future briefs automatically

• Briefs trigger the ladder themselves: a task with thin capability coverage gets an ACQUIRE FIRST block (advisory — never blocks).
• Sources are user-extensible data (harness/capability/sources.json
  • your sources.local.json overlay): capability sources add|remove. 15+ shipped sources, 6 machine-queryable.
• Security tiers for MCP servers: official > curated > community; community requires --force; version pins enforced; secrets via env only.
• capability doctor health-checks everything (MCP handshakes, tool --help) and unhealthy entries drop out of briefs automatically.
• capability export / import sync your accumulated skills through a global library (~/.dev-harness/library) — every project run compounds. capability promote-lesson turns recorded lessons into skill stubs; capability gaps lists tasks with no coverage.

dev-harness run — days-long autonomy, any headless agent

The Ralph outer loop as a first-class command — fresh agent context per iteration, so no session ever lives long enough to drift:

dev-harness run --agent claude --max-hours 72        # or codex | gemini | opencode
dev-harness run --cmd "my-agent {promptfile}" ...    # any custom runner
dev-harness report                                    # what happened, human-readable

Each iteration: next computes the brief → the agent works it in a fresh headless session → gates validate → advance on pass → checkpoint commit on a run/* branch → journal. Built-in safety:

• Preflight proves the agent can actually execute commands before burning a multi-day budget (headless permission bootstrap is generated per runner — e.g. .claude/settings.json allowlist + MCP pre-approval)
• Stall + churn detection — no-change iterations AND failing-differently-every-time both stop the run
• Notify hooks (run.onPause/onStall/onComplete — shell command or webhook): you hear about a blocker at hour 5, not hour 72
• Blocked-task policy: retries exhausted → task marked blocked, lesson recorded, run continues with remaining work
• Maintenance beat: every N iterations one iteration works the top capability gap — the library grows during the run
• Budgets: --max-iterations, --max-hours, per-iteration timeout; the standing prompt tells the agent how much budget remains so late iterations bias toward leaving the tree green

Gates — what "done" means, mechanically

Three levels of criteria, all enforced before the pipeline moves:

Level	Criteria	Checked by
Task	acceptanceCriteria (non-empty, non-placeholder)	validate --feature X --task Y + lint + tests
Feature	definitionOfDone	auto-checked when the last task passes
Phase	phase-specific checks	validate

Phase gates include: sprint contract agreed · feature branch · git clean · lint · tests · coverage threshold · anti-placeholder scan (no TODO/FIXME/not implemented ships) · README/LICENSE/CHANGELOG real · HEAD tagged at SHIP. Failures are listed with exactly what to fix.

Retry & escalation (Ralph pattern)

Task retry (default 10×) → feature retry (resets the feature's tasks) → phase retry (re-runs the phase) → pause for human. Each level is independently toggleable (retry.*.enabled / retry.*.maxRetries). Autopilot mode enables the full cascade (3×2×2) automatically; copilot mode keeps a human in the loop between phases.

Roles: hats by default, walls when you want them

Planner / Generator / Evaluator / Simplifier personas guide each phase.

• Default (roles.strict=false) — built for single-session agents: roles are hats the agent switches itself; role gates print advisories ("judge this as if someone else wrote it").
• Strict (config set roles.strict true) — for multi-session choreography (one agent session per role): validate in BUILD/VERIFY physically requires the evaluator role, contract propose requires the planner, and the self-evaluation guard blocks a role from approving its own work.

(Prefer dev-harness run above — it is this loop with preflight, stall detection, checkpoints, and reporting built in. The scaffolded harness/scripts/run-*-session.sh wrappers and --json on every command remain for custom drivers.)

CLI Reference

dev-harness init        Scaffold harness (--stack, --agent-tool, --mode, --target)
dev-harness next        YOUR NEXT STEP — the trajectory brief (--no-check, --style, --json)
dev-harness mcp         Built-in MCP server on stdio (8 harness_* tools)
dev-harness run         Autonomous supervisor (--agent, --max-hours, --preflight, --cmd)
dev-harness report      Human summary of an autonomous run
dev-harness capability  match | search | add | create | index | doctor | gaps |
                        sources | promote-lesson | export | import
dev-harness status      Full state: phase, feature, task, gates, lessons
dev-harness validate    Run gates (--feature X --task Y for one task; --session-exit)
dev-harness phase       <name|next> — invoke or advance (gate-checked)
dev-harness contract    propose | review | status | escalate
dev-harness role        planner | generator | evaluator | simplifier
dev-harness learn       Append a lesson       decision   Record a decision
dev-harness config      list | get | set (dot-notation, --json-value)
dev-harness set-mode    copilot | autopilot   pause / resume
dev-harness checkpoint  create <label>        rollback   list | to | branch
dev-harness worktree    create | list | prune | remove
dev-harness cleanup     Stale-artifact scan (--auto-fix)   audit   Gate/retry report

Key config knobs: briefStyle (minimal|standard|verbose — verbose for small models) · capability.acquireThreshold · roles.strict · run.onPause/onStall/onComplete · run.agents.<name>.cmd (runner overrides) · retry.* — full list: dev-harness config list.

Exit codes: 0 success · 1 gate failure · 2 usage error · 3 internal. Full configuration reference: docs/CONFIGURATION.md · Integration details: docs/TOOL_INTEGRATION.md

What init scaffolds

your-project/
├── AGENTS.md                     ← the workflow (canonical, ~110 lines)
├── CLAUDE.md / .cursorrules / …  ← tool-specific instruction files
├── .mcp.json / .cursor/mcp.json / .vscode/mcp.json  ← MCP registration
├── .claude/skills/dev-harness/   ← Claude Code workflow skill
└── harness/
    ├── config.json               ← pipeline state (harness-managed)
    ├── features/feature-list.json← features + tasks + acceptance criteria
    ├── sprint-contract.md        ← scope agreed before building
    ├── skills/                   ← craft skills library (10 skills)
    ├── docs/phases/              ← per-phase instructions
    ├── docs/agents/              ← role personas
    ├── docs/DOMAIN.md            ← domain glossary
    ├── progress.md               ← append-only history + lessons
    ├── session-handoff.md        ← clock-in/out snapshot between sessions
    ├── evaluator-rubric.md       ← quality scorecard
    ├── ci/                       ← GitHub Actions / GitLab CI templates
    └── scripts/                  ← init.sh + session-enforcement wrappers

31+ built-in stacks (node, python, go, rust, java, kotlin, c, cpp, dotnet, ruby, php, swift, elixir, …) + unlimited custom stacks via stackMeta.

Dependencies

Four runtime deps, each for a concrete robustness win: ajv (schema validation) · picocolors (terminal color) · simple-git (git plumbing) · string-width (layout). The MCP server is hand-rolled JSON-RPC — zero additional deps.

Acknowledgements & Influences

Source	What we took
mattpocock/skills (MIT Matt Pocock)	The craft skills library (harness/skills/) — adapted for the pipeline
ghuntley.com/ralph + snarktank/ralph	Iterative loop, fresh context per task, progress files, retry escalation
addyosmani/agent-skills	Phase pipeline, anti-rationalization tables, committee review
Anthropic — Effective Harnesses	Generator/evaluator split, sprint contracts, feature lists
OpenAI — Harness Engineering	Progressive disclosure, agent legibility, worktree isolation
walkinglabs/learn-harness-engineering	Clock-in/clock-out, clean-state gate, entropy management
morphllm IMPACT framework	Intent / Memory / Planning / Authority / Control-flow / Tools layering

License

MIT Bakr Bagaber. Vendored skill content adapted from mattpocock/skills (MIT Matt Pocock) — attribution headers preserved in each file.