/execute

Forge Execute

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

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: Check if DESIGN.md, design.md, or docs/DESIGN.md exists in the project root. If found, read it and store the path in .forge/state.md frontmatter as design_system: {path}. All UI tasks will automatically receive design constraints during execution and review.

Knowledge graph: Check if graphify-out/graph.json exists. If not, check if graphify is installed and build a graph:

node "${CLAUDE_PLUGIN_ROOT}/scripts/forge-tools.cjs" graph-status
# If available and no graph exists:
node "${CLAUDE_PLUGIN_ROOT}/scripts/forge-tools.cjs" graph-build --project-dir .

If a graph exists (either pre-existing or just built), note it in .forge/state.md frontmatter as knowledge_graph: graphify-out/graph.json. The executor will query it for focused context, the reviewer for blast radius analysis, using the graph-query and graph-dependents CLI commands.

Neither is required. If absent, execution proceeds with standard behavior. If present, they enhance every task automatically without any user action.

Initialize Loop State

Run setup-state to create .forge/.forge-loop.json and prepare .forge/state.md for execution:

node "${CLAUDE_PLUGIN_ROOT}/scripts/forge-tools.cjs" setup-state \
  --forge-dir .forge \
  --spec "{first-spec-domain}" \
  --autonomy "{resolved-autonomy}" \
  --depth "{resolved-depth}" \
  --max-iterations "{resolved-max-iterations}" \
  --token-budget "{resolved-token-budget}" \
  --completion-promise "FORGE_COMPLETE"

This sets phase: executing in state.md and creates the loop file that activates the Stop hook.

Identify First Task

1. Read the frontier file for the first spec: .forge/plans/{spec-domain}-frontier.md
2. Parse the frontier to find the first unblocked task (Tier 1, first entry).
3. Update .forge/state.md with current_task: {task-id} and task_status: pending.
4. Update the "What's Next" section in state.md with all remaining tasks.

Begin Execution

Now invoke the forge:executing skill to begin working on the first task.

Pass to the skill:

• The current task ID and name from the frontier
• The spec file path for acceptance criteria
• The resolved depth level
• The capabilities map
• The repo configuration (if multi-repo)

The skill handles the per-task implementation cycle: read spec, implement, test, review, commit, update state.

From this point forward, the Stop hook takes over. After each Claude response, the Stop hook in hooks/stop-hook.sh:

1. Reads .forge/.forge-loop.json and .forge/state.md
2. Calls forge-tools.cjs route to determine the next action
3. Either blocks exit with a new prompt (driving the next iteration) or allows exit (done, paused, or budget exhausted)

The state machine handles all transitions: implementing, testing, reviewing, fixing, debugging, advancing to the next task, verifying specs, and completing the loop. See Section 5.3 and 6.2 in the design spec for the full state machine table.

Autonomy Modes

Mode	Behavior
full	Runs unattended until all tasks are complete, blocked, or budget exhausted. Never pauses between tasks or specs.
gated	Pauses between specs/phases for human review. Runs autonomously within a single spec.
supervised	Pauses after every task. Human must /forge resume to continue. Good for critical code or first runs.

Completion

When ALL tasks across ALL specs (or the filtered subset) are genuinely complete and verified:

Output the completion promise exactly as shown:

<promise>FORGE_COMPLETE</promise>

CRITICAL: Only output the completion promise when:

• Every task in every frontier has status complete in state.md
• Phase verification has passed (for standard and thorough depth)
• All acceptance criteria from the spec are satisfied
• Code is committed

Do NOT output the promise prematurely. If tasks remain, the stop hook will continue driving execution. If you are blocked or uncertain, update state.md with the blocker and let the stop hook handle it.

Output

After starting execution, present a brief launch summary:

Forge Execute — Starting
---
Spec: {domain}
Tasks: {N} total ({M} in first tier)
Depth: {quick|standard|thorough}
Autonomy: {full|gated|supervised}
Token budget: {N}
Max iterations: {N}

Starting task {T001}: {task name}...

Then immediately begin working on the first task. The stop hook handles everything after that.