Dev Harness
Self-driving development pipeline for Claude Code & Cursor.
Why dev-harness
AI coders write code fast, but the process still falls back to humans — code review, test execution, audit, documentation. The result is "fast typing, slow shipping."
dev-harness applies Harness Engineering — agent scaffolding as load-bearing infrastructure that compensates for what models can't do alone (Anthropic, Effective harnesses for long-running agents). One /dev command takes a task through research → plan → implement → audit + docs + test → review → remember, with stop-hook defenses that resume the agent when it tries to halt mid-pipeline.
What you get out of the box:
- One command, full pipeline:
/dev resolves the right skill at each stage automatically.
- Multi-model code review (v4): three Claude reviewers (sonnet × 2 + opus) plus optional cross-vendor adversarial review via Codex CLI.
- Six stop-hook defenses: rate limit, context overflow, timeout, retry storms — never silently dies.
Quick start
# Claude Code
/plugin marketplace add brothelmdzz/dev-harness
/plugin install dev-harness && /reload-plugins
bash "${CLAUDE_PLUGIN_ROOT}/scripts/setup.sh"
# Then in any project
/dev
How it works
/dev → skills/dev/SKILL.md (orchestrator)
→ detect-stack.sh + skill-resolver.py + harness.py init
→ Pipeline loop (defaults/pipeline.yml):
research → prd → plan → implement → [audit | docs | test] → review → remember
parallel group three-way
Each stage completion → harness.py update
Claude tries to stop → stop-hook.py defenses → blocks if pipeline incomplete
Three-layer skill resolution — same /dev, different projects pick different skills automatically:
L1: .claude/skills/{name}/SKILL.md → project-specific (highest priority)
L2: ~/.claude/skills/{name}/SKILL.md → user-level overrides
L3: skills/generic-{name}/ → built-in fallback
Core concepts
| Term | One-liner |
|---|
| Skill | A markdown playbook that drives one pipeline stage. Resolved via L1/L2/L3. |
| Agent | A specialized sub-agent (12 total) with its own model and tool access. |
| Hook | A shell hook into Claude Code's lifecycle (Stop / PostToolUse / SessionStart). |
| Pipeline | YAML-defined ordered stages with optional parallel_group and depends_on DAG. |
| Route | Pre-defined pipeline subsets (B = full, C = skip research+prd, C-lite = quick fix). |
Multi-agent parallel
dev-harness coordinates agents on two levels:
Layer 1 — Stage-level (parallel_group): after implement completes, three background agents run audit, docs, and test simultaneously. Each reports to harness-state.json independently. Declared in pipeline.yml:
- name: audit
parallel_group: post-implement
- name: docs
parallel_group: post-implement
- name: test
parallel_group: post-implement
Layer 2 — Phase-level (Orchestrator): when a plan has > 3 phases, dev-harness automatically switches to orchestrator mode:
harness.py analyze-deps reads file-level dependencies and groups independent phases into batches- Each worker runs in an isolated
git worktree (scripts/worktree.sh) — no merge races
- Workers report through
.claude/workers/worker-*.json; the main agent waits for all before advancing
Concurrency safety uses filelock on harness-state.json. The orchestrator refuses to start if filelock is missing (no silent fallback to broken state).
Multi-model code review (v4)
Layer 1 — Claude internal heterogeneous (always runs)
├─ code-reviewer (sonnet) ← code quality, bugs, edge cases
├─ security-reviewer (sonnet) ← OWASP top 10, secrets, auth
└─ architect (opus) ← architecture, module boundaries
Layer 2 — Cross-vendor adversarial (optional, auto-detect)
└─ codex exec (your config) ← GPT / GLM / o3 / etc. via Codex CLI
Aggregation:
≥ 2 channels hit same issue → high confidence, must fix
cross-vendor only → "heterogeneous perspective" section
Layer 2 enables itself when bash scripts/detect-codex.sh exits 0 and dev-config.yml has review.cross_vendor.enabled: auto (default). No codex installed? It silently skips.
Pitfall journal & continuous learning (v4)
When build / test / audit / review fails, the stop-hook captures the root cause to .claude/pitfall-journal.jsonl. On the next resume, recent failures are injected into the prompt as ground truth — the agent sees what just broke and avoids repeating it.
