Forge

Delegate complex, multi-step development work to an autonomous agent that builds and verifies code.

When to Use Forge

• The task targets a different repo (-C ~/other-project)
• The work is complex enough to benefit from autonomous agent execution with verification
• You have spec files describing outcomes to implement
• You want to run multiple specs in parallel

Commands

forge run

forge run "add auth middleware"                          # Simple task
forge run --spec specs/auth.md "implement this"          # With spec file
forge run --spec-dir ./specs/ "implement all"             # Parallel specs (default)
forge run -C ~/other-repo "fix the login bug"            # Target different repo
forge run --rerun-failed "fix failures"                  # Rerun failed specs
forge run --pending "implement pending"                  # Run only pending specs
forge run --resume <session-id> "continue"               # Resume interrupted session
forge run --plan-only "design API for auth"              # Plan without implementing
forge "quick task"                                       # Shorthand (no 'run')

Important flags:

• -s, --spec <path> — Spec file (shorthand resolves via manifest). Prompt becomes additional context.
• -S, --spec-dir <path> — Directory of specs (shorthand resolves via known dirs). Runs each .md in parallel by default. Already-passed specs are skipped.
• --sequential — Run specs sequentially instead of parallel (default: parallel).
• -F, --force — Re-run all specs including already passed.
• -B, --branch <name> — Run in an isolated git worktree on the named branch. Auto-commits on success, cleans up after.
• --concurrency <n> — Override auto-detected parallelism (default: freeMem/2GB, capped at CPUs).
• --sequential-first <n> — Run first N specs sequentially, then parallelize.
• -C, --cwd <path> — Target repo directory.
• -t, --max-turns <n> — Max turns per spec (default: 250).
• -b, --max-budget <usd> — Max budget in USD per spec.
• --plan-only — Create tasks without implementing.
• --dry-run — Preview tasks and estimate cost without executing.
• -v, --verbose — Full output detail.
• -q, --quiet — Suppress progress output (for CI).
• -w, --watch — Auto-split tmux pane with live logs.

forge audit

Reviews codebase against specs. Produces new spec files for remaining work — feed them back into forge run --spec-dir.

forge audit specs/                              # Audit all specs in directory
forge audit specs/auth.md                       # Audit a single spec file
forge audit auth.md                             # Shorthand (resolves via manifest)
forge audit specs/ "focus on auth module"       # With additional context
forge audit specs/ -o ./remediation/            # Custom output dir
forge audit specs/ -C ~/target-repo             # Different repo
forge audit specs/ --watch                      # Auto-split tmux pane with live logs
forge audit specs/ --fix                        # Audit-fix loop (audit -> fix -> re-audit)
forge audit specs/ --fix --fix-rounds 5         # Custom max rounds (default: 3)

forge define

Analyzes codebase and generates outcome spec files from a high-level description. Closes the loop: forge define → forge specs → forge run --spec-dir.

forge define "build auth system"                # Generate specs in specs/
forge define "add rate limiting" -o specs/api/  # Custom output dir
forge define "refactor database" -C ~/project   # Different repo

forge review

Reviews recent git changes for bugs and quality issues.

forge review                                    # Review main...HEAD
forge review HEAD~5...HEAD                      # Specific range
forge review --dry-run -o findings.md           # Report only, write to file
forge review -C ~/other-repo                    # Different repo

forge watch

Live-tail session logs with colored output. Auto-follows to next session during batch runs; exits after final session or 60s timeout.

forge watch                                     # Watch latest session (auto-follows batch)
forge watch <session-id>                        # Watch specific session (no auto-follow)
forge watch -C ~/other-repo                     # Watch in different repo

forge status

forge status                                    # Latest run
forge status --all                              # All runs
forge status -n 5                               # Last 5 runs
forge status -C ~/other-repo                    # Different repo

forge specs

List tracked specs with lifecycle status. Specs are registered in .forge/specs.json as they’re run.

forge specs                                     # List all tracked specs
forge specs --pending                           # Show only pending
forge specs --failed                            # Show only failed
forge specs --passed                            # Show only passed
forge specs --orphaned                          # Manifest entries with missing files
forge specs --untracked                         # .md files not in manifest
forge specs --add                               # Register all untracked specs
forge specs --add specs/new.md                  # Register specific spec by path/glob
forge specs --resolve game.md                   # Mark spec as passed without running
forge specs --unresolve game.md                 # Reset a spec back to pending
forge specs --check                             # Triage pending specs: auto-resolve already-implemented ones via Sonnet agent
forge specs --reconcile                         # Backfill from .forge/results/ history
forge specs --prune                             # Remove orphaned entries from manifest

Important

Never manually orchestrate parallel forge runs (e.g. forge run spec1.md & forge run spec2.md & wait). Forge handles parallelism, dependency ordering, and skip-passed internally via --spec-dir. Manual orchestration bypasses the dependency graph, manifest tracking, and batch grouping.

Always prefer --spec-dir over running individual specs. It automatically:

• Skips already-passed specs (use --force to override)
• Resolves depends: frontmatter into a topological execution order
• Tracks all specs in a single batch with grouped cost reporting
• Auto-tunes concurrency based on available memory

--spec takes exactly one file. The prompt is always the last positional argument (a quoted string). Bare file paths without a flag are interpreted as the prompt, not as spec files. To run multiple specs, use --spec-dir.

Shorthand resolution: spec paths resolve automatically. forge run --spec login.md finds the spec via manifest lookup. forge run --spec-dir gtmeng-580 finds .bonfire/specs/gtmeng-580/. Full paths always work too.

Common Mistakes

# WRONG: bare paths without --spec are treated as the prompt string
forge run specs/auth.md specs/login.md

# WRONG: --spec only takes one file, not multiple
forge run --spec specs/auth.md specs/login.md "implement"

# WRONG: manually running specs one-by-one bypasses dependency ordering
forge run --spec specs/01-schema.md "implement" && forge run --spec specs/02-api.md "implement"

# RIGHT: put specs in a directory, use --spec-dir
forge run --spec-dir specs/ "implement all"

# RIGHT: single spec with --spec
forge run --spec specs/auth.md "implement this"

Recipes

Run all specs in a directory

forge run --spec-dir gtmeng-580 -C ~/dev/project "implement all"
# Shorthand paths resolve automatically (gtmeng-580 → .bonfire/specs/gtmeng-580/)
# Already-passed specs are skipped; deps on passed specs are treated as satisfied

Run a subset of specs from a directory

If specs use depends: frontmatter, --spec-dir automatically runs only the ready ones in topological order. Dependent specs wait for their deps to pass — no need to cherry-pick individual specs.

# Specs declare their dependencies:
#   03-api.md has "depends: [01-schema.md, 02-models.md]"
# Forge resolves the graph — 01 and 02 run in parallel, 03 waits for both
forge run --spec-dir specs/feature/ "implement all"

# Already-passed specs are skipped automatically; their dependents still run
# Use --force to re-run everything including passed specs
forge run --spec-dir specs/feature/ --force "re-verify all"

Spec-driven development

# 1. Write specs as .md files (see references/writing-specs.md)
# 2. Run them in parallel
forge run --spec-dir ./specs/ "implement all specs"
# 3. Rerun any failures
forge run --rerun-failed "fix failures"
# 4. Check results
forge status

Triage pending specs

# See what's pending
forge specs --pending
# Auto-resolve specs that are already implemented in the codebase
forge specs --check
# Run whatever is still pending
forge run --pending "implement remaining"

Dependency-aware execution

Specs can declare dependencies via YAML frontmatter. Independent specs run in parallel, dependent specs wait:

---
depends: [01-database-schema.md, 02-api-models.md]
---

forge run --spec-dir ./specs/ "implement all"
# Automatically runs in topological order based on depends: declarations

Foundation specs first, then parallelize

When not using depends:, number-prefix specs for ordering. Foundations run sequentially before the parallel phase:

forge run --spec-dir ./specs/ --sequential-first 2 "implement"
# Runs 01-*.md, 02-*.md sequentially, then 03+ in parallel

Audit-then-fix loop

# Manual: audit then run remediation specs
forge audit specs/ -C ~/project                 # Find gaps
forge run --spec-dir specs/audit/ -C ~/project "fix remaining"

# Automated: convergence loop (audit -> fix -> re-audit, up to 3 rounds)
forge audit specs/ --fix -C ~/project
forge audit specs/ --fix --fix-rounds 5         # More rounds if needed

Resume or fork after interruption

forge run --resume <session-id> "continue"               # Pick up where you left off
forge run --fork <session-id> "try different approach"    # Branch from that point

Deep-Dive References