/resume

description: "Continue Forge execution after context reset or interruption"
allowed-tools: ["Bash(node ${CLAUDE_PLUGIN_ROOT}/scripts/forge-tools.cjs:*)", "Read(*)", "Write(*)", "Edit(*)", "Glob(*)", "Grep(*)", "Bash(*)", "Agent(*)"]

Forge Resume

Continue an in-progress Forge execution from where it left off after a context reset, session close, or manual pause.

Step 1: Verify Forge project exists

Check if `.forge/` exists. If it does not, stop and tell the user:

> No Forge project found. Run `/forge brainstorm` to get started.

Step 1.5: Forensic recovery (T020, R007/R008)

Before loading any state, run forensic recovery. This handles crashed sessions, stale locks, budget exhaustion, and orphan worktrees. The forensic recovery scan is always safe to run -- on a clean state it is a no-op.

node "${CLAUDE_PLUGIN_ROOT}/scripts/forge-tools.cjs" forensic-recover --forge-dir .forge

The command:

1. Sets phase to `recovering` while it runs 2. Inspects `.forge/.forge-loop.lock` -- takes over stale locks (heartbeat older than 5 minutes) 3. Reads checkpoints from `.forge/progress/` to find in-flight tasks 4. Cross-references git log + `task-status.json` to identify committed tasks 5. Lists worktrees and flags any orphans (worktrees for tasks not in any frontier or already committed) 6. If `phase: budget_exhausted`, reads `.forge/resume.md` and surfaces the reason 7. Writes a caveman-form summary to `.forge/state.md` notes 8. Sets final phase to `idle` (clean) or `needs_human` (warnings present) 9. Exits 0 on clean recovery, exit 2 if `needs_human`

**Show the recovery report to the user.** Read it carefully:

• If the report lists **orphan worktrees**, do NOT delete them automatically. Tell the user which paths are orphan and that they need to run `git worktree remove <path>` manually after reviewing the contents.
• If the report says `Needs human: YES`, stop and ask the user how to proceed. Common cases: budget exhausted (raise the cap in `.forge/config.json`), live lock from another session (verify no other forge instance is running).
• If `Resume point` is present, that is the task you will continue from in Step 6.
• In **full autonomy mode**, auto-continue if `Needs human: no` and there are no warnings. Otherwise pause and prompt.

Add `--json` for machine-readable output if you need to parse the report programmatically.

Step 2: Load handoff context

Check if `.forge/.forge-resume.md` exists:

• **If it exists:** Read it. This file contains a natural-language handoff summary generated by the stop hook when the previous session ended. It describes your exact position — current phase, spec, task, what was completed, and what to do next.
• **If it does not exist:** That is fine — the user may be resuming manually after a pause or after a supervised-mode gate. Proceed to Step 3 to load state directly.

Step 3: Read state files

Read the following files to fully restore execution context:

1. **`.forge/state.md`** — Current position in the execution:

• `phase` — which phase you are in (executing, verifying, idle)
• `spec` — which specification you are implementing
• `current_task` — which task you are working on (e.g., T1, T2)
• `task_status` — status of the current task (pending, implementing, testing, reviewing, debugging, blocked)
• `autonomy` — autonomy level (full, gated, supervised)
• `depth` — depth level (quick, standard, thorough)
• The body sections: What's Done, In-Flight Work, What's Next, Key Decisions

2. **`.forge/token-ledger.json`** — Token budget tracking:

• `total` — tokens consumed so far
• Compare against `tokens_budget` from state.md to know remaining budget
• If budget usage is above 70%, operate at `quick` depth (skip reviews)
• If budget is exhausted, report this to the user and stop

3. **`.forge/capabilities.json`** — Available MCP servers, skills, and plugins that can enhance execution.

4. **`.forge/task-status.json`** — Programmatic task completion registry. This is the authoritative source for which tasks are complete — more reliable than parsing the markdown in state.md.

5. **The relevant frontier file from `.forge/plans/`** — Find the frontier file matching the current spec (e.g., `.forge/plans/{spec-domain}-frontier.md`). This contains the task DAG with tiers, dependencies, estimates, and completion status.

6. **The current spec from `.forge/specs/`** — Read `spec-{domain}.md` for the acceptance criteria of what you are implementing.

Step 4: Re-activate the execution loop

Run the setup-state command to create a fresh loop state file (`.forge/.forge-loop.json`), which re-enables the stop hook loop engine:

node "${CLAUDE_PLUGIN_ROOT}/scripts/forge-tools.cjs" setup-state \
  --forge-dir .forge \
  --spec "{SPEC}" \
  --autonomy "{AUTONOMY}" \
  --depth "{DEPTH}"

Replace `{SPEC}`, `{AUTONOMY}`, and `{DEPTH}` with the values read from `.forge/state.md`.

**Important:** After running setup-state, also clear the `handoff_requested` flag in `.forge/state.md` by setting it to `false`. This prevents the stop hook from immediately triggering another handoff.

Step 5: Clean up resume file

If `.forge/.forge-resume.md` exists, delete it — it has been consumed:

rm -f .forge/.forge-resume.md

Step 6: Resume execution

You are now back in the Forge execution loop. Pick up exactly where you left off:

• **Do NOT re-plan.** The plan already exists in `.forge/plans/`.
• **Do NOT re-read completed tasks.** Trust the state — only focus on the current and upcoming work.
• **If a task was in progress** (`task_status` is `implementing`, `testing`, `reviewing`, or `debugging`), continue from that exact point. Run any failing tests first to re-establish context, then continue.
• **If a task was pending**, start implementing it following the depth protocol (TDD for thorough, implement+test for standard, implement-only for quick).
• **If all tasks are done** and phase is `verifyin