forge

${\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

• Claude Code with a Pro subscription, Max subscription, or API key
• GitHub account with the Vercel GitHub App installed
• Vercel account

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