/execute

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: 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" \
  ${RECORD_BASELINES:+--record-baselines}

This sets phase: executing in state.md and creates the loop file that activates the Stop hook. When --record-baselines is passed from /forge:execute, setup-state stamps record_baselines: true into state.md frontmatter; T020's visual verifier reads that flag to switch from compare-mode to record-mode on the first passing visual AC.

Auto-Attach TUI (full autonomy only)

When the resolved autonomy is full, the executor spawns a detached TUI session so a long unattended run has live visibility without blocking stdout. This is a no-op for gated and supervised modes, so the manual /forge:watch path is preserved.

Invoke the helper after setup-state runs and before handing off to forge:executing:

node "${CLAUDE_PLUGIN_ROOT}/scripts/forge-tui-attach.cjs" \
  --autonomy "{resolved-autonomy}" \
  --forge-dir .forge

The helper decides what to do based on the environment (spec R003):

Condition	Action
autonomy !== "full"	Silent no-op. Manual flow unchanged.
.forge/config.json has tui.auto_attach: false	Silent no-op. Opt-out flag respected. Default when absent is true.
process.platform === "win32"	Print Monitor progress with: /forge:watch to stdout and continue headless. No fork attempt.
tmux not on $PATH (non-Windows)	Print Monitor progress with: /forge:watch to stdout and continue headless.
Unix + tmux available	Start a detached session named forge-tui-<pid> running the TUI command, print Attach: tmux attach -t forge-tui-<pid> to stdout. Does not block.

The helper always exits 0; /forge:execute never stalls waiting on it. If tmux spawn itself fails, the helper writes a diagnostic to stderr and falls back to the headless message so the loop keeps moving.

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.

Router Hint Dispatch (R003)

Before each Agent tool invocation during execution, the orchestrator MUST resolve the per-phase model + effort hint via scripts/forge-router.cjs::writeHandoff and pass the resulting model to the Agent tool.

For every Agent dispatch (executor, researcher, reviewer, verifier, complexity, planner sub-tasks), do this immediately before the call:

1. Call writeHandoff(forgeDir, taskId, role, complexityOrTask). Pass either a pre-classified object (from classifyTask) or the raw task object — writeHandoff accepts both. This writes .forge/handoff.{task_id}.json containing { model, effort, max_tokens, role, task_id } (or the legacy 3-field shape { model, role, task_id } when FORGE_TOKEN_OPT=0).
2. Read the returned object's model field and pass it to the Agent tool's model parameter where the harness supports it.
3. The effort and max_tokens hints are recorded in the handoff file for forward-compat. If the Agent tool does not currently accept an effort parameter, behavior is unchanged from today — when the harness adds support, downstream tooling picks the hint up automatically by reading the handoff file.
4. The handoff file is idempotent: re-dispatching the same task overwrites cleanly. Do not delete handoff files between iterations; they are the audit trail for what hint was sent.

Do NOT modify agents/forge-*.md, skills/*/SKILL.md, or CLAUDE.md to surface the hint — the handoff JSON is the only plumbing point for this spec. The R003 acceptance criteria explicitly forbid touching those files.

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.