← Contract Hero · WorkLearnPlugins
multi-agent build system Claude Code plugin TDD as a phase

Code Forge

Turn a lazy prompt into a shippable PoC. The /forge skill drives the run in your Claude Code session — Phase 0 (claudex) → Phase 1 (planner authors spec.md) → cycle loop. Each cycle spawns one claude -p /goal child that runs best-of-N implementer workers, configurable dimensional reviewers, and a consolidator. One hook keeps test files read-only during green so the cycle's /goal can't talk a worker into weakening the suite.

View on GitHub Quick start Architecture

01What it does

Code Forge solves the three failure modes of multi-agent code generation — protocol drift, reviewer blind spots, and tautological tests — by making each one a structural property of the run rather than a prompt-level hope.

TDD as a phase

A dedicated test-author writes tests before any implementer touches code. cycle-tests-pass.sh red inverts exit codes so tautological tests fail the gate.

Best-of-N implementer

6 Sonnet workers dispatched in a single turn produce independent candidates; the cycle child scores them by LOC + files + complexity and applies the simplest passer.

Dimensional review

N reviewers (count, model, dimensions all picked in spec.md) cover a curated lens menu — correctness, design, simplicity, security, more. A consolidator clusters, verifies, ships review.md.

Goal-driven cycles

The /forge skill drives the run in your interactive session and spawns one claude -p /goal per cycle for the autonomous bits — each child loops until its result.json shows status: pass.

Anti-weakening hook

Test files (plus the state.json/tests.json anchors) are read-only during green. Without it /goal "tests pass" would mutate tests instead of the implementation.

Codex cross-checks

G2.a (spec ↔ plan) and G2.b (spec ↔ e2e) gates round-trip through Codex via codex-bridge as independent second-opinion judges.

02How a run flows

The /forge skill is the orchestrator. It runs in your interactive Claude Code session and drives Phase 0/1 + the cycle loop directly — no separate outer process. For each cycle in spec.md ## Cycle Plan, it spawns one claude -p /goal child; each child has its own Haiku evaluator that judges the cycle's goal condition after every turn.

User invocation /forge "task description" (from Claude Code) /forge SKILL — your Claude Code session drives Phase 0/1 directly, then loops over cycles (no separate outer process) Phase 0/1 claudex + dispatch planner → spec.md + state.json Pick next cycle read state.json — status:pending read goal_condition from state Spawn cycle child Bash: claude -p /goal ... wait for exit + result.json loop until every cycle is pass skill halts on a failure so you can investigate and re-invoke /forge --resume cycle child #1 claude -p /goal (cycle C1) see per-cycle detail ↓ cycle child #2 claude -p /goal (cycle C2) sequential, after C1 cycle child #3 claude -p /goal (cycle C3) (final cycle has e2e) cycle child #N claude -p /goal (cycle CN) N from spec.md
The /forge skill (your Claude Code session) reads spec.md, picks the next pending cycle, spawns a claude -p /goal child, narrates the result. Repeat until every cycle status is pass.

03Inside a cycle child

Each cycle is one claude -p /goal session whose condition is "result.json exists with status: pass AND review.md has 0 critical clusters". The child runs a linear sequence of dispatches + gates inline; the cycle's /goal handles re-prompting on failure until done or capped at K turns.

Legend

Phase / subagentStep in the cycle. Some are inline, some are Agent dispatches.
Best-of-N / fan-outParallel Agent dispatches in a single turn.
forge-guard rule 5The one hook. Test files + anchors read-only during green.
Script gatecycle-tests-pass.sh red/green truth gate.
CYCLE CHILD ENTRY claude -p "/goal cycles/<id>/result.json status:pass AND review.md has 0 critical clusters, or stop after 30 turns" 1. test-author (subagent) writes tests.json + actual test files covers cycle's acceptance criteria + e2e (final cycle) 2. red gate cycle-tests-pass.sh red (inverted exit) tests must FAIL → tautology detector ▼ forge-guard rule 5 active — tests + anchors read-only ▼ 3. 6 implementer-workers (parallel, single turn) W1candidate W2candidate W3candidate W4candidate W5candidate W6candidate 4. score (LOC + files + complexity proxy), pick simplest passer, apply cycle-tests-pass.sh green must exit 0 for the winner 5. N reviewers (parallel, single turn) N = len(spec.md ## Reviewer Config.dimensions) · model = opus | sonnet R1correctness ★ R2simplicity ★ R3security ★ R4..RN (configurable)any Tier 1/2 dim, duplicates OK ★ default trio (PoC-tuned). Pick from 12 dimensions in planner Phase 1.5. 6. consolidator (subagent) cluster · verify critical/high · write review.md step 0: count reviewer dropouts; flag if any missing 7. write result.json { status: pass | fail, summary, review_clusters } THE gate — the skill reads status to decide pass/halt Cycle child exits. /goal evaluator clears if status:pass + 0 critical; re-prompts cycle child if not (built-in retry behavior). The skill reads result.json, narrates "cycle <id> status=pass", and moves to the next pending cycle (or halts on fail).
One cycle child. Test-author + consolidator are subagents (focused prompts own schema discipline + cluster verification). Workers + reviewers are inline Agent dispatches — count, model, and per-reviewer dimension all read from spec.md.

04Configurable dimensional review

Each cycle's reviewer fan-out is parameterized at spec-authoring time. The planner runs an interactive Phase 1.5 sub-step asking for the model + dimensions and writes the result into spec.md ## Reviewer Config: 

## Reviewer Config
model: opus            # or sonnet
dimensions:
  - correctness        # ★ default trio
  - simplicity         # ★ default trio
  - security           # ★ default trio

The length of the dimensions list IS the reviewer count — no separate count: field, no validation mismatch. Want two security reviewers? List security twice.

Curated dimension menu

TierDimensionWhat it covers
1 ★correctnessDoes the code do what spec says? Off-by-one, type confusions, hidden behaviors.
1designModule boundaries, separation of concerns, naming clarity.
1error-handlingSilent failures, swallowed exceptions, missing error paths.
1 ★simplicityAccidental complexity, premature abstraction, dead code.
1tests-vs-implTautology hunting — do tests actually exercise the impl?
1 ★securityReal vuln classes — auth gaps, input validation, capability leaks.
2performanceAlgorithmic complexity, obvious bottlenecks.
2naming-readabilityNames communicate intent; code reads top-to-bottom.
2dependency-hygieneUnused / outdated / vulnerable deps.
2type-safetyType contracts at boundaries; no any escape hatches.
2concurrencyRace conditions, shared mutable state.
2observabilityLogging, error surfacing, debuggability.
3sui-move-idiomsMove 2024 conventions, ability usage, object capability patterns.
3frontend-a11yARIA, semantic markup, keyboard nav, contrast.
3api-contract-stabilityBackwards compatibility, deprecation, breaking-change risk.

★ = the default trio shown selected when the planner first opens the picker. Tier 3 dimensions are declared per-project (not in the default menu).

05The one hook

Code Forge ships exactly one PreToolUse hook: the test-immutability rule. Without it, /goal "tests pass" would happily mutate the tests instead of the implementation — the evaluator can only see what's in the transcript and cannot diff against a baseline.

Worker candidate-staging is also covered

Best-of-N workers stage candidates under .forge/cycles/<id>/green/candidates/worker-K/files/<repo-relative-path>. The hook peels that prefix so a write to a staged copy of a test file still trips.

06spec.md — the single artifact

Everything per-project lives in one file. The planner emits it during Phase 1; the skill and every cycle child read it.

Example ## Cycle Plan entry 
- id: C1
  goal: implement the user storage layer
  files_affected:
    - src/storage/users.ts
    - src/storage/types.ts
  acceptance: [AC-001]
  goal_condition: |
    cycles/C1/result.json exists with status: pass AND
    cycles/C1/review.md has 0 critical clusters,
    or stop after 30 turns
Example result.json from a passing cycle 
{
  "cycle_id": "C1",
  "status": "pass",
  "summary": "all tests pass; 0 critical findings",
  "winner_worker": "W3",
  "review_clusters": {
    "critical": 0,
    "high": 2,
    "medium": 5,
    "low": 3,
    "info": 0
  },
  "started_at": "2026-05-19T10:00:00Z",
  "ended_at":   "2026-05-19T10:24:00Z"
}

07Quick start

Code Forge is a Claude Code plugin. There's one entry point:

/forge "Build a CLI that counts source lines"

# Skip Phase 0 (Codex-mediated planning refinement) for trivial tasks:
/forge "Add a --json flag to my CLI" --quick

# Skip the optional G2.5 Codex gate (cost savings):
/forge "<description>" --light

# Resume a run that left a partial .forge/ behind:
/forge "<description>" --resume

The code-forge skill drives the whole run in your interactive session (Phase 0 → Phase 1 → cycle loop), spawning one claude -p /goal child per cycle for the autonomous bits.

Requirements

08Further reading