${\color{#d97706}\textsf{⚒ Forge}}$ ${\color{#d97706}\textsf{—}}$ ${\color{#d97706}\textit{You\ bring\ the\ ingot.\ The\ smith\ does\ the\ rest.}}$
$${\color{#d97706}\textbf{Autonomous\ Next.js\ development\ powered\ by\ Claude\ Code.}}$$
$${\color{#d97706}\textbf{Describe\ your\ app\ in\ plain\ English\ —\ Forge\ plans,\ builds,\ and\ deploys\ it\ through\ GitHub\ and\ Vercel.}}$$
Requirements
Quick Start
# Install Forge (one-time)
curl -fsSL https://raw.githubusercontent.com/allan-mobley-jr/forge/main/install.sh | bash
# Start a new project
mkdir my-app && cd my-app
forge init
Note: The installer also sets up the Vercel plugin for Claude Code and agent-browser for browser automation. The Vercel plugin requires OAuth authentication — it will prompt on first use. agent-browser runs locally and needs no auth.
Then start building:
forge smelt # describe your app — the Smelter plans and creates issues
forge stoke # autonomously implement, review, and merge each issue
forge cast # full autonomous cycle: smelt → stoke → hone
How It Works
Forge uses a medieval forge metaphor. Three core craftsmen — each a Claude Code agent — handle the development pipeline. One post-cycle craftsman handles auditing. You invoke them one at a time, or let them run autonomously.
┌───────────────┐ ┌──────────┐
│ forge init │──────▶│ GitHub │
│ (bootstrap) │ │ repo │
└───────────────┘ └──────────┘
Core: forge smelt → forge hammer ⇄ forge temper (per issue)
↑─── forge stoke ───↑
Post-cycle: forge hone
forge cast = smelt → stoke → hone (full cycle)
The Craftsmen
| Craftsman | Command | What it does |
|---|
| Smelter | forge smelt | Researches, plans, and creates sequenced implementation issues. On first run, scaffolds the project and produces INGOT.md. |
| Blacksmith | forge hammer | Implements the lowest open issue on a feature branch. Reads INGOT.md for architectural context. |
| Temperer | forge temper | Evaluates the Blacksmith's work against acceptance criteria and quality bar. Approves and merges, or sends back for rework. Manages releases. |
| Honer | forge hone | Triages bugs or audits the codebase. Files implementation issues for the Blacksmith. |
Each command has an auto- variant for autonomous operation (e.g., forge auto-smelt). In auto mode, the agent runs headless via -p without human interaction.
Interactive vs Auto
Every agent exists in two variants:
- Interactive (
forge smelt): launches a Claude Code session where you confer with the agent — describe what you want, answer questions, approve the plan before it acts.
- Auto (
forge auto-smelt): runs headless with -p. The agent makes decisions autonomously and documents assumptions.
Single-track pipeline: Forge processes one issue at a time, in the order they were created. Do not run multiple forge stoke or forge cast sessions concurrently — they will conflict on the same issue.
Agent Architecture
The three core agents follow a structured pattern:
- Smelter: research (parallel Explore agents) → plan (mandatory Plan agent) → confer/decide → create issues → record
- Blacksmith: read INGOT.md → research → plan → implement → test → self-review (proportional) → record
- Temperer: read INGOT.md → lean review (diff + ledger + E2E tests) → verdict → PR/merge → record
Agents check for user-defined domain agents at ~/.claude/agents/ and spawn them as subagents when relevant.
Session Management
Named sessions persist across issues within a milestone. The CLI resumes sessions on crash or relaunch, preserving the agent's full context. Sessions clear at milestone boundaries. Session state is stored in ~/.forge/config.json per project.
Artifacts
