/execute

description: "Run the autonomous implementation loop"
argument-hint: "[--autonomy full|gated|supervised] [--max-iterations N] [--token-budget N] [--depth quick|standard|thorough] [--filter NAME] [--record-baselines]"
allowed-tools: ["Bash(node ${CLAUDE_PLUGIN_ROOT}/scripts/forge-tools.cjs:*)", "Bash(node ${CLAUDE_PLUGIN_ROOT}/scripts/forge-tui-attach.cjs:*)", "Bash(node ${CLAUDE_PLUGIN_ROOT}/scripts/forge-wizard.cjs:*)", "Read(*)", "Write(*)", "Edit(*)", "Glob(*)", "Grep(*)", "Bash(*)", "Agent(*)"]

Forge Execute

First-Run Wizard (R004.AC3)

Before anything else, fire the one-shot token-reduction wizard. Idempotent — prints once on first install, then no-ops forever. Suppressed when `/forge:watch` is rendering its own banner (R004.AC6).

node "${CLAUDE_PLUGIN_ROOT}/scripts/forge-wizard.cjs" --forge-dir .forge

Launch the autonomous implementation loop. Reads the frontier, implements tasks one by one, and relies on the Stop hook state machine to drive iteration until all tasks are complete.

**Live status header.** Every iteration of `/forge:execute` is automatically prefixed with a compact dashboard-style status block (phase, current task + step, agent, progress bar, tokens, per-task budget, lock status). You see what forge is doing without leaving Claude Code or running a separate command. The block is generated by `scripts/forge-status-block.cjs`, called from the Stop hook on every iteration. Opt out by setting `execute.status_header: false` in `.forge/config.json`. For a fullscreen ANSI dashboard in a separate terminal window, use `/forge:watch` instead.

New in v2.1

• **Token budgets** are now enforced as hard ceilings, not warnings. Exhaustion transitions to `budget_exhausted` phase with a handoff doc at `.forge/resume.md`.
• **Git worktree isolation** per task: each task runs in `.forge/worktrees/{task-id}/` and is squash-merged on success.
• **Lock file acquisition** at session start: refuses to run if another valid lock is held (unless stale >5min).
• **Per-task checkpoints** at each step: resume picks up exactly where the last checkpoint was written.
• **Headless mode** for CI: see `node scripts/forge-tools.cjs headless execute --help` for non-interactive usage with exit codes.

Pre-flight Check

**The Forge workflow is strictly sequential: brainstorm -> plan -> execute.** These pre-flight checks enforce that the prior phases completed correctly. If any check fails, stop and tell the user what to run first.

1. Verify `.forge/` exists. If it does not, stop and tell the user: > `.forge/` not found. Run `/forge brainstorm` first to generate specifications, then `/forge plan` to create task frontiers.

2. Verify `.forge/specs/` contains at least one spec file. If not, stop and tell the user: > No specs found. Run `/forge brainstorm` first.

3. **Verify ALL spec files have `status: approved` in their YAML frontmatter.** Read each `spec-*.md` file and parse its frontmatter. If ANY spec does not have `status: approved`, stop and tell the user: > Unapproved specs found: {list}. The brainstorm workflow must complete with explicit user approval before execution. Run `/forge brainstorm` and approve an approach.

This is the critical gate that prevents skipping the interactive brainstorm Q&A. A spec only gets `status: approved` when the brainstorming skill writes it after the user explicitly approves an approach.

4. Verify `.forge/plans/` contains at least one `*-frontier.md` file. If not, stop and tell the user: > No task frontiers found. Run `/forge plan` first to decompose specs into tasks.

5. **Verify each approved spec has a corresponding frontier file.** For each `spec-{domain}.md`, check that `.forge/plans/{domain}-frontier.md` exists. If any spec is missing a frontier, stop: > Spec "{domain}" has no task frontier. Run `/forge plan` to decompose it into tasks.

6. Check for Ralph Loop conflict: if `.claude/ralph-loop.local.md` exists, stop and tell the user: > Ralph Loop is active. Run `/cancel-ralph` first — only one loop plugin should be active at a time.

7. **Run programmatic validation** as a final safety check:

   node "${CLAUDE_PLUGIN_ROOT}/scripts/forge-tools.cjs" validate-workflow --forge-dir .forge

If this returns errors, stop and report them. This validates the same checks in code, preventing agent-level bypasses.

Parse Arguments

Parse flags from `$ARGUMENTS`:

| Flag | Default | Description | |------|---------|-------------| | `--autonomy full\|gated\|supervised` | Value from `.forge/config.json` (default: `gated`) | When to pause for human review | | `--max-iterations N` | Value from config (default: `100`) | Maximum stop-hook iterations before forced exit | | `--token-budget N` | Value from config (default: `500000`) | Total token budget for execution | | `--depth quick\|standard\|thorough` | Value from config (default: `standard`) | Quality/ceremony level | | `--filter NAME` | *(all specs)* | Only execute tasks for specs whose domain matches NAME | | `--record-baselines` | `false` | Mark this run as the first-successful-visual-AC path: visual verifier will save baselines instead of comparing. Consumed by T020 (visual verification gate, R007). When present, `setup-state` sets `record_baselines: true` in `.forge/state.md` frontmatter. |

If a flag is not provided, fall back to `.forge/config.json`, then to the built-in default.

Read Configuration and Capabilities

1. Read `.forge/config.json` for project settings (repos, loop circuit breakers, review settings, etc.). 2. Read `.forge/capabilities.json` if it exists, to know which MCP servers and skills are available for execution. 3. Read all frontier files from `.forge/plans/` (filtered by `--filter` if provided). 4. Identify the first spec to execute: use `--filter` domain if given, otherwise the first frontier file alphabetically.

Auto-Detect Project Context

These checks run automatically. Do not skip them.

**Design system:** C