forge-dev

Forge

Turn a feature request into an implementation-ready spec — stress-tested before any code is written. Then run autonomous improvement loops with blind scoring.

The problem

AI-generated specs hallucinate decisions. They fill in blanks with plausible-sounding answers instead of flagging them as open questions. The implementer — human or agent — hits gaps, invents answers on the fly, and ships something that doesn't match what anyone intended.

Nobody stress-tests the spec before handoff. By the time contradictions and missing edge cases surface, they're already bugs.

What Forge does differently

• Everything starts as evidence. Code, docs, transcripts, screenshots — classified and tracked, not summarized away.
• One reducer writes canon. Sub-agents explore and review. Only the lead agent merges findings into the spec. No conflicting rewrites.
• Provenance is required. Every canonical claim traces back to the evidence that supports it. Unsupported claims get flagged, not shipped.
• Readiness is a state machine. Not a score threshold — a formal model with blocker rules, planning states, and handoff gates.
• Adversarial review before handoff. Dynamic agent teams probe for ambiguity, contradictions, and untestable claims. The spec doesn't ship until they find nothing.
• Design tree walks. Clarification and research sub-agents walk the codebase's design tree (directory structure, module boundaries, naming conventions) to ground questions in what actually exists.
• Learning artifacts feed forward. Per-bead learnings from .ralph-tui/progress.md are consumed by the planning pipeline, so each spec benefits from patterns discovered in prior implementations.
• Autoresearch loops. Autonomous iterative improvement with blind scoring — doer/judge/arbiter/strategist cycles that self-replicate until convergence.

What you get

A subject spec — a specification document named after its subject (e.g. auth-session-system.md) — with sidecar artifacts:

• The spec itself with provenance-linked claims
• An evidence ledger (JSONL) of every input processed
• Readiness metadata (scores, blocker reasons, planning/handoff state)
• An implementation plan with acceptance criteria
• A ubiquitous language glossary (UBIQUITOUS-LANGUAGE.md) for consistent domain terminology
• Optional beads — discrete implementation work units with dependency wiring, including epilogue beads for post-implementation learning

See a finished example: specs/feature-flags-system.md with full artifacts in specs/_artifacts/feature-flags-system/.

Quick start

Prerequisites

• Claude Code (claude) or Codex (codex)
• bash, git, python3 (for manual/shell install only)

Install

Claude Code (recommended):

/plugin marketplace add mwarger/forge
/plugin install forge@forge-dev

All 10 skills are available immediately. Update with /plugin update forge.

Codex:

Fetch and follow instructions from https://raw.githubusercontent.com/mwarger/forge/main/.codex/INSTALL.md

Your first spec

Start a new session after install and just describe what you want. Forge triggers automatically — no special syntax needed:

Forge a feature to add real-time notifications
Forge a fix for the auth token refresh bug
Forge a migration from REST to GraphQL
Forge a refactor of the payment processing module
Reverse engineer this repo into a spec

Or be more explicit if you prefer:

Create a subject-named spec for this feature request using Forge.
Use the forge-orchestrator skill on this codebase.

Works in both Claude Code (claude) and Codex (codex). The orchestrator skill triggers and routes into the focused sub-skills automatically.

./install.sh

FORGE_INSTALL_MODE=copy ./install.sh
FORGE_SKILLS_DIR="$HOME/.claude/skills" ./install.sh
FORGE_SKILLS_DIR="$HOME/.codex/skills" ./install.sh

curl -fsSL "https://raw.githubusercontent.com/mwarger/forge/main/install.sh?$(date +%s)" | bash

How it works