<!-- source: openspec/current/forge/README.md -->

---
title: Forge — Overview
status: stable
owner: pavel
audience: [pavel, ai, engineer]
tldr: Routing surface for the forge capability — project-agnostic CLI engine for Linear-driven autonomous code pipelines.
---
# Forge — overview

> Part of openspec/current/forge/ — split from forge.md on 2026-05-12

Project-agnostic CLI engine for Linear-driven autonomous code pipelines. Eighteen commands shipped (the `cli.ts:37-56` whitelist). Wraps Anthropic Messages API + Anthropic Agent SDK + Linear + Supabase + Mirror render pipeline.

## Files in this capability

| File | What's inside | Read when |
|---|---|---|
| `narrative.md` | Status, Where Forge lives, Distribution, Related capabilities, Maestro cross-references | You want positioning context before reading the spec |
| `spec.md` | Architecture, Configuration, forge.config.mjs shape, Multi-project routing, Required env vars, Operator shell environment, Dependencies, Boundaries, Conventions, Extension, Open questions | You're implementing against or configuring Forge |
| `commands.md` | All 18 command definitions (Legacy six + Builder mode + Epic conductor + utility commands), Review orchestration (agents, finding schema, verifier, CLI semantics, cost guard, report output) | You want per-command reference: plan, build, epic, audit, spec, review, estimate, render, mirror-export, inbox, inspect, cancel, status, resume, archive, conductor, install-skills, mcp-server |
| `verifier.md` | Checkpoint model (5 verification gates), Build outcome enum, Failure modes (stop-write-comment-exit), Retry policy, Test coverage, Known gaps, Per-role model tiering amendment | You're debugging a failed build or understanding the verification / retry contract |
| `entities.md` | Builder mode (identity model, programmatic API, post-subprocess steps, lessons-learned, cancel runtime, per-issue worktree isolation, builder prompt), Module registry, Persistence, Convention adapters, Reports, Cost tracking, Anthropic/GitHub/Linear API integration, openspec/ relationship, UI surface (Five Forge entities: forge-run, forge-step, forge-finding, forge-tool-call, forge-output) | You're looking at data structures: BuildState, Lock, Dispatch, ForgeRun, Plan, PersistenceAdapter, OpenSpecConventionAdapter |
| `README.md` | This routing surface | You're deciding which file to read |

## Status

Stable. Builder mode shipped end-to-end 2026-05-09 (RAP-48). Eighteen commands available. Orchestrated review (`forge review --orchestrate`) is **specified but not yet shipped** — `--orchestrate`, `--pr`, and `--post` fail until the implementation lands; tracked RAP-AI-111, see `verifier.md § Known gaps` item 8. Single-mode `forge review` (no flag) works today. `tail` (RAP-405) is the one specified-but-unshipped command: it appears in the `forge --help` usage text but is not in the cli.ts whitelist.

## Original monolith

This capability was previously a single `openspec/current/forge.md` file (1417 lines), split in change `split-monolithic-capability-specs` on 2026-05-12. Git history of the original file is preserved via `git log --follow openspec/current/forge.md`.
