harness

Claude Code Orchestration Layer

An autonomous software-delivery system built on Claude Code. You describe a feature; it plans, builds, reviews, tests, ships, and deploys it — then learns from the run so the next one goes better.

Rolling this out to a team? See ROLLOUT.md for plugin install and enterprise config.

---

The one-paragraph mental model

A single orchestrator drives the work but never writes code itself. It hands each phase to a specialised agent (architect, software-engineer, reviewer, …), each running in an isolated git worktree. Every phase ends in a verdict — APPROVED, CHANGES_REQUESTED, etc. — and a failing verdict sends the work back, not forward. A set of hooks mechanically enforce the rules (no code without a failing test, orchestrator can't edit source, HEAD stays on main). Everything the system learns — what's fragile, what patterns work — is captured and fed back into future runs.

That's the whole thing. The rest of this README expands those five ideas.

---

The pipeline

One request flows through these phases. No phase is skipped; no gate is bypassed.

Intake ─▶ Plan ─▶ Build ─▶ Review ─▶ Final Gate ─▶ Ship ─▶ Deploy ─▶ Reflect
   │        │       │         │           │           │        │         │
classify  design  TDD     code +      verify +     open    deploy +   capture
 + route  slices  loop   security      test +       PR     rollback  learnings
                         (parallel)   accept

Phase	What happens	Who	Verdict
Intake	Classify the request, score its complexity, choose the route	orchestrator	—
Plan	Design vertical slices, API contracts, data models; validate the plan	architect	PLAN_APPROVED
Build	Incremental TDD, then a self-review pass	software / frontend / db engineers	—
Review	SOLID/DRY audit and OWASP security audit, run in parallel	code-reviewer + security-engineer	APPROVE / CHANGES_REQUESTED
Final Gate	Contract/smoke/mutation verify, coverage check, acceptance, patch critique	qa / product-reviewer / patch-critic	APPROVED / REJECTED
Ship	Open a PR behind a quality gate	orchestrator	PR_CREATED / PR_BLOCKED
Deploy	Deploy, verify, auto-rollback on failure	orchestrator	DEPLOYED / ROLLED_BACK
Reflect	Record an observation for the learning loop	orchestrator	—

Trivial work (a question, a doc tweak, a config change) is detected at Intake and skips the heavy pipeline. Full phase contract: rules/core.md and protocols/pipeline-protocol.md.

---

The four iron laws

These are absolute — enforced by hooks, not by good intentions.

1. No production code without a failing test first. (TDD is mandatory.)
2. No "done" without fresh verification. Stale test output from earlier doesn't count — re-run.
3. The orchestrator never writes source code. It coordinates agents; only agents edit code.
4. main stays on main. Every code change happens in an isolated worktree, never on the repo's HEAD.

Full set and rationale: rules/core.md.

---

The agents

The orchestrator delegates each phase to a specialist. Write-capable agents work in an isolated worktree and commit before finishing; read-only agents review a diff.

Agent	Job	Worktree
architect	System design, API contracts, slice decomposition	read-only
software-engineer	Backend implementation, business logic	yes
frontend-engineer	UI, accessibility, design system	yes
database-engineer	Schema, migrations, query optimisation	yes
infrastructure-engineer	Docker, CI/CD, IaC, deploy config	yes
qa-engineer	Test strategy, coverage gaps, integration/E2E tests	yes
code-reviewer	SOLID/DRY and design review	read-only
security-engineer	OWASP Top 10, dependency + secrets scanning	read-only
product-reviewer	Acceptance criteria, UX evaluation	read-only
patch-critic	Final-Gate check of the diff against test results	read-only

There are 19 agents in total (the rest are recon/validation helpers). Each is defined in agents/ with its full checklist and the model it runs on. The authoritative model/worktree table lives in CLAUDE.md § Agent Team.

---

What the system learns

Three feedback loops, at three different timescales, make the pipeline self-improving.