Forge

The Forge (Claude Code runbook)

This skill runs The Forge methodology. The canonical, tool-agnostic spec is FORGE.md, bundled alongside this file in the skill directory (with the handoff template HANDOFF.md). Read FORGE.md for the full rationale, roles, pattern toolbox, exit statuses, and scaling. This file is the Claude Code adaptation: how to run it here.

When to use

• Medium-to-large, high-stakes, or long-running work where correctness, coverage, or craft matter: features, redesigns, refactors, research reports, audits, reviews.
• Skip it for trivial or already-verified work - just do the task and verify.

The model

A generation is one verified delta. Generations chain, unbounded, until a stop status. Each generation improves two things: the product AND the loop itself (prompts, roles, gates, batch sizing, failure handling). State moves between generations ONLY through a clean handoff - a fresh agent must be able to continue from it with no chat history. Prefer ending a generation at a clean handoff boundary (fresh-context resumption) over compacting a full window mid-run; compaction risks dropping subtle context the handoff is built to preserve.

How to run it in Claude Code

Running the Forge is explicit opt-in to multi-agent orchestration (the user saying "the Forge" counts). Implement it with the Workflow tool (deterministic JS: agent(), parallel(), pipeline(), phase(), structured-output schemas, loops).

Map the phases (one generation):

1. Frame (you, the lead). Restate the goal, hard constraints, and measurable acceptance criteria. Ground first: read the real files AND the prior handoff; apply its process lessons. Honor project rules (local-only / no push, brand tokens, conventions). Triage before spinning the machine: a full multi-agent run costs ~10-15x a single pass, so first ask "would one direct pass + one adversarial verify meet the criteria?" - if yes, do that and stop. Add divergence/critics/generations only when stakes or uncertainty justify the cost (smallest viable Forge first). Pick the next batch - small enough to finish and verify this generation.
2. Diverge - parallel() of N agents, each a different direction (competing) or a non-overlapping slice (decomposition). Independent; structured output via schema. Give each a self-contained brief (objective / output format / tools+sources / explicit non-overlap boundaries - vague briefs cause duplicate work). Return contract: each agent returns a distilled summary (proposal + rationale), NOT its raw trace; the lead never concatenates full worker transcripts upward.
3. Synthesize - one agent() merges proposals into a build-ready plan + acceptance checklist.
4. Build - ONE integrator agent() per shared file (writes stay single-threaded; extra agents add intelligence, not actions - Cognition/Devin). No parallel edits on the same file; use isolation: 'worktree' only if parallel writers are unavoidable. Preserve contracts (tests, APIs, asserted strings/testIds).
5. Critique <-> Fix - parallel() of 3-5 adversarial critics, each a distinct lens (correctness/integration, design/taste, brand/tokens, a11y, security, perf) and each given only the spec + artifact/diff, NOT the builder's context. Each defaults to "needs-work" and tries to refute. One fixer agent() applies confirmed findings. Wrap in a while loop; exit on convergence - machine-checkable, not a feeling: open-finding set empty AND criteria met AND the cheap new gate green. A non-converging round means re-frame or mark blocked.
6. Verify - a separate agent() that does NOT inherit the builder's context (writer != checker; it gets only the handoff/spec + the diff) runs the real gates (targeted tests, typecheck, build) PLUS the cumulative regression gate - every prior generation's gate still green (the suite only grows). Then YOU verify on the ground (run / screenshot). No generation claims an unverified delta, and none that regresses an earlier one may continue.
7. Retrospect - one agent() (or you) extracts process lessons and decides the exit status. A lesson that generalizes graduates into FORGE.md.
8. Handoff - write/refresh the handoff doc from HANDOFF.md (goal, current state, changes, verification evidence, gate set (cumulative), skipped checks, risks, parked ideas, next batch, process lessons; + the full header: status, generation #, date, owner, circuit-breaker cap, progress-log path). Persist it to a file in the working area (e.g. FORGE_HANDOFF.md).
9. Next Loop - only on status continue.

Unbounded generations

Drive generations with a budget-bounded while loop: continue while budget.remaining() allows AND the prior status is continue; each iteration reads the handoff file, runs a generation, rewrites the handoff. Exit statuses: continue (spin next), pause-with-handoff (clean stop, resumable), blocked (needs an external unblock - the unblock is the next batch), complete-for-now (goal met + verified, no valuable next batch). No arbitrary cap; stop on value, not on a count.

Deterministic rails (the backstop, normative). Value-based stopping needs a mechanical floor so the loop cannot run away or thrash: a no-progress detector (N rounds with the open-finding set unchanged, or N generations with no new verified delta -> stop), an oscillation detector (same finding/surface recurs across ~2 rounds = the infinite correction loop -> re-frame or blocked), and a sanity circuit-breaker (a derived hard cap, ~10x expected, recorded in the handoff header). Keep a .forge/progress.log heartbeat the detectors read, and checkpoint each verified delta to local version control (never auto-push). See FORGE.md Guardrails.

Bounded depth (no sprawl)

Two levels max: Lead (the Workflow script) -> Primary (agent() calls; a primary MAY run its own Mini-Forge via the Agent/Task tool on its slice) -> Helper (the primary's sub-agents, spawned WITHOUT further spawn capability). Helpers are leaves - no agent three levels deep, no helper breeding helpers.

Scaling

• Smallest viable Forge first. Start simplest (often one agent, sequential); add agents/divergence/critics only when a gap shows they pay for themselves. Scale up to the stakes, never above. Rough fan-out calibration: ~1 worker for simple fact-finding, 2-4 for comparisons/a few directions, 5+ only for genuinely complex or high-stakes decomposition.
• Small: little/no divergence, single build, 1-2 critics, verify, one-line retrospect. Often one generation.
• Medium: 3 divergers, judge, single integrator, 3-4 lens critics, Critique<->Fix to convergence, verify, retrospect, handoff.
• Large/long-running: bigger fans, decomposition + isolation + Mini-Forges, 3-5 vote adversarial verify, loop-until-dry, many generations across fresh contexts resumed purely from the handoff.
• Skip divergence when the problem has one right answer ("match this convention"): go straight to build + adversarial verify.

Discipline

Ground before building (incl. the prior handoff); one owner per shared file; critics refute (not rubber-stamp); no "done" without a gate (verified delta or blocked); bounded depth; clean handoffs for a fresh agent; value-based stopping; improve the loop every generation; honest reporting; the lead reads each phase and decides the next (no fire-and-forget).

Reference

Full methodology, exit statuses, the pattern toolbox (adversarial verify, perspective-diverse verify, judge panel, loop-until-dry, multi-modal sweep, completeness critic, Mini-Forge, handoff-as-contract, no silent caps), and platform-agnostic guidance: FORGE.md (bundled in this skill directory). Handoff template: HANDOFF.md.