forge

Forge

A structured build-and-repair harness for long-running coding work.

Forge gives coding agents phase discipline, ownership, and continuable state — so work that spans sessions, days, or interruptions doesn't fall apart.

The problem

Coding agents are fast but forgetful. On long-running tasks they lose track of what was decided, who owns what, and where things broke. When a session ends, context disappears. When it resumes, you re-explain everything.

Forge fixes this by writing project state to files — not chat history — and structuring work into phases with explicit gates, so every session picks up exactly where the last one stopped.

Who this is for

• Multi-session projects where context loss is the bottleneck
• Teams that need an audit trail of specs, designs, and decisions
• Build or repair work that benefits from phase gates instead of open-ended prompting
• Parallel development where lane ownership and merge order matter

Core UX

forge info — see where you are

Shows current phase, what's blocking, and what to do next. One glance, not a wall of fields.

Forge: my-saas-app (build)
Phase 3/8 — develop
████████████░░░░ 55%

Active: auth-api, payment-ui. Blocked: db-schema (waiting on contract review)

Lanes: 2/5 done, 1 blocked
Issues: 1 blocker, 0 major, 2 minor
Tag: forge/v1-design

forge continue — restore saved state and keep going

Restores saved workflow state from .forge/ — phase, lane ownership, blockers, handoff notes — and routes to the most actionable point. No re-prompting, no re-explaining what you were doing.

Forge: my-saas-app
Phase 3/8 — develop
3 lanes active, 1 blocked (auth waiting on DB schema)

Next: Continue auth-api lane after resolving DB contract

It picks the right entry point automatically:

• Blocker that needs your input? Surfaces that first.
• Internal blocker? Routes to the owning team.
• Active lane with handoff notes? Loads that lane's worktree and task context.
• None of the above? Falls back to the current phase skill.

forge — start a new project or fix an existing one

Forge detects whether you're building something new or fixing something broken, and routes accordingly.

Build and repair workflows

Forge runs two structured pipelines. Each phase has a defined input, output, and gate — work doesn't advance until prerequisites are met.

Build mode — new projects

graph LR
    A[Intake] --> B[Discovery]
    B --> C[Design]
    C --> D[Develop]
    D --> E[QA]
    E --> F[Security]
    F --> G{Blockers?}
    G -- yes --> H[Fix]
    H --> E
    G -- no --> I[Delivery]

Phase	What happens	Output
Intake	Evaluate scope, route to build mode	.forge/state.json
Discovery	Gather requirements, eliminate ambiguity	.forge/spec.md
Design	Architecture, contracts, code rules, UI spec	.forge/design/, contracts/, code-rules.md
Develop	Split into lanes, parallel work in git worktrees	Merged code, runtime.json
QA	Functional, regression, edge-case testing	.forge/holes/
Security	OWASP Top 10, secrets scan, auth review	.forge/holes/
Fix	Resolve blockers (max 3 attempts per issue)	Fixes merged
Delivery	Docs, delivery report, client review	.forge/delivery-report/

Repair mode — existing codebases

graph LR
    A[Intake] --> B[Reproduce]
    B --> C[Isolate]
    C --> D[Fix]
    D --> E[Regress]
    E --> F{Clean?}
    F -- no --> C
    F -- yes --> G[Verify]
    G --> H[Delivery]

Phase	What happens	Output
Intake	Read existing code, generate baseline artifacts	spec.md, code-rules.md, contracts/
Reproduce	Confirm the bug exists and capture reproduction steps	.forge/evidence/
Isolate	Root cause analysis — narrow to the responsible module	.forge/evidence/rca-*.md
Fix	Implement targeted fix in isolated worktree	Fix branch
Regress	Verify fix doesn't break adjacent functionality	.forge/holes/
Verify	Full QA pass on the fix	.forge/holes/
Delivery	Update docs, delivery report	.forge/delivery-report/

Repair is not "just fix it." It's reproduce → isolate root cause → fix → prove no regressions → verify.

State lives in files, not chat