forge

Forge turns Claude Code from a smart coding assistant into a disciplined engineering partner. Claude already remembers — what it doesn't enforce is process. Forge does: gated stages, requirement traceability, and learning that compounds across projects.

---

What is Forge?

A Claude Code plugin that adds the one thing a coding assistant lacks — enforced sequencing. Forge gives you:

• A gated 12-stage pipeline — requirements → design → build → ship. Each stage blocks until its gate passes, and every artifact traces back to a numbered requirement: REQ-NNN → gate → code → test.
• Learning that compounds — tagged, filterable lessons and auto-mined skills that carry from one repo to the next, so your mistake rate drops over time.
• A dynamic workflow engine — run arbitrary parallel agent DAGs beyond the fixed pipeline, opt-in (new in v0.4.0).

Nothing advances silently and nothing is untraceable. When you do need to skip a gate, /forge:force-advance records why — the override is explicit and audited.

---

The pipeline at a glance

flowchart LR
    subgraph DEFINE["📐 Define — what & how"]
        direction LR
        S1[1 · Requirements] --> S2[2 · Product / UX] --> S3[3 · Architecture] --> S4[4 · Spec] --> S5[5 · Plan]
    end
    subgraph BUILD["🔨 Build"]
        direction LR
        S6[6 · Implement] --> S7[7 · Evaluate]
    end
    subgraph SHIP["🚀 Ship & iterate"]
        direction LR
        S8[8 · Deploy] --> S9[9 · Monitor] --> S10[10 · Feedback] --> S11[11 · Resolve] --> S12[12 · Release]
    end
    S5 --> S6
    S7 --> S8
    S12 -. retrospective · next cycle .-> S1

Every arrow is a gate — work advances only when the previous stage's exit criteria pass.

Stage	Command	Output
1 — Requirements	/forge:srs	SRS with REQ-IDs
2 — Product & UX	/forge:product	PRD, design system, user flows
3 — Architecture	/forge:arch	Architecture doc, ADRs, data model
4 — Technical Spec	/forge:spec	Tech spec, interface contracts, test strategy
5 — Planning	/forge:plan	Task DAG, milestones, risk register
6 — Implementation	/forge:build	Code, decisions log, progress tracker
7 — Evaluation	/forge:eval	Test results, security review, eval report
8 — Deployment	/forge:deploy	Deploy plan, runbook, deploy log
9 — Monitoring	/forge:monitor	Observability config, incident log
10 — Feedback	/forge:feedback	Feedback log, triage
11 — Resolution	/forge:resolve	Hotfixes, regression tests, backlog
12 — Release	/forge:release	Changelog, release notes, checklist

---

Install

In Claude Code:

/plugin marketplace add tonmoy007/forge-plugins
/plugin install forge@forge-plugins

Prerequisites: Claude Code ≥ 2.1.0 · Python ≥ 3.11 on PATH · pip install pyyaml.

---

Quickstart (< 5 minutes)

/forge:init      # detect project type, scaffold pipeline/, write state.md
/forge:srs       # Claude interviews you → requirements with REQ-IDs
/forge:status    # "where am I?" — Forge tells you at every session start

Then run each /forge:<stage> in turn. You never track where you are — Forge injects the current stage, task, and blockers into every session and always names the next step.

---

How Forge works

Forge runs as silent lifecycle hooks around your normal Claude Code session. They inject state at the start, enforce gates as you work, and quietly learn from what succeeds:

flowchart TD
    B["SessionStart hook injects state<br/>stage · task · blockers · lessons · rules"]
    C["You + Claude work the current stage"]
    D{"Gate passes?"}
    E["Advance · REQ-ID traceability recorded"]
    F["Hooks capture tool-use traces"]
    G["Lessons + skills mined<br/>semantic · success-gated · cross-project"]
    B --> C --> D
    D -- "no · blocker" --> C
    D -- "yes" --> E
    C --> F --> G
    G -. feeds the next session .-> B
    E -. next stage .-> B

Three tiers of memory feed that loop:

1. Session context — injected at every SessionStart (≤ 2 000 tokens).
2. Project memory — pipeline/ accumulates decisions, reflections, and stage history.
3. Cross-project lessons — ~/.forge/global-lessons.yaml promotes high-frequency patterns across all your repos.

When a successful workflow recurs in your own traces, Forge mines it and proposes a reusable skill for you to approve, modify, or reject. See references/skill-mining.md.