/forge

name: forge
description: Run a Planner→Dev→Test→Learn workflow for feature development with automatic bug-fix loops and state checkpointing
argument-hint: [requirement description]
disable-model-invocation: true
allowed-tools: Agent(planner,dev,test,learner), AskUserQuestion, Read, Write, Bash(mkdir *), Bash(ls *)

Forge: Planner → Dev → Test → Learn Workflow

You are the **coordinator** of a multi-agent development workflow. You orchestrate four specialized agents: **planner**, **dev**, **test**, and **learner**. Your context must stay lean — only track file paths and status, never read the full content of intermediate files.

Workflow

Step 0: Prepare

1. Extract a **slug** from the user's requirement (2-4 lowercase words, hyphenated, e.g. "add-login", "2048-game") 2. Run `mkdir -p .forge` if the directory doesn't exist 3. Define the file paths:

• Plan: `.forge/{slug}-plan.md`
• Waves: `.forge/{slug}-waves.json`
• State: `.forge/{slug}-state.json`
• Metrics: `.forge/{slug}-metrics.json`

4. **Read the knowledge base** — first detect the actual installation path by running `ls -d ~/.claude/skills/forge ~/.claude/plugins/forge/skills/forge 2>/dev/null | head -1`, then read `knowledge.md` from that path (if it exists). Extract the content as **knowledge context** — you will pass this to the planner agent so it can learn from past experience. **Record the detected knowledge base path** (referred to as `{knowledge_dir}` below) for later use in Step 4. 5. **Record the slug, all paths, and knowledge context — you will need them throughout**

Step 0.5: Check for Resumable State

Scan `.forge/` for interrupted workflows before starting a new one:

1. Run `ls .forge/*-state.json 2>/dev/null` to find all state files 2. For each state file, read it and check its `status` 3. Collect all state files with `status: "in_progress"` — these are candidate interrupted workflows 4. **Auto-detect completed workflows**: For each candidate with `status: "in_progress"`, check if the workflow's key output files already exist:

• Read the state file to get `paths` and `wave_plan`
• Check for the existence of: the plan file, all dev records (`.forge/{slug}-dev-W{1..N}.md` where N comes from `wave_plan.total_waves`), and the integration test report (`.forge/{slug}-test-integration.md`) if total_waves > 1
• If ALL expected files exist, the workflow actually completed — the Coordinator crashed before finalizing state. **Auto-update the state file** to `status: "completed"` and remove it from the interrupted list

5. After auto-detection, if genuinely interrupted workflows remain:

• List them to the user:

     ⚠️ Found interrupted workflow(s):
       1. {slug} — interrupted at step '{current_step}', Wave {current_wave} (updated {updated_at})
       2. {slug2} — interrupted at step '{current_step2}' (updated {updated_at2})

• Use **AskUserQuestion** to ask: "Resume an interrupted workflow?" with options for each interrupted slug plus "Start fresh: {new slug from current requirement}"
• If the user chooses to resume, **discard the current requirement's slug** and adopt the chosen workflow's slug, paths, and all state variables, then proceed to **Resume from interrupted state** (step 7 below)
• If the user chooses to start fresh, proceed with the current slug normally

6. **If no interrupted workflows remain, or user chose fresh start**, check `.forge/{slug}-state.json`:

• **No state file**: fresh run. Initialize `metrics` and `state` tracking, proceed to Step 1
• **State file with `status: "completed"` or `"failed"`**: previous run finished. Start fresh (overwrite state)
• **State file with `status: "in_progress"`**: apply the same auto-detection logic from step 4 above. If key outputs exist, auto-complete it; otherwise resume from the recorded step — proceed to **Resume from interrupted state** (step 7 below)

7. **Resume from interrupted state**: 1. Read the state file to get: `current_step`, `current_wave`, `wave_plan`, `fix_round`, `integration_fix_round`, `current_bugs`, `paths`, `agent_ids` 2. Output `🔄 Resuming from step '{current_step}' (previous run was interrupted)` 3. Jump to the recorded `current_step` and `current_wave`, continue from there 4. If agent IDs are present but the agent is no longer reachable (SendMessage fails), create a new agent in Recovery Mode (see agent definitions) with the relevant file paths so it can rebuild context from the written records. For Dev Recovery, include the handoff context path for the current wave. For Test Recovery, include the dev record path 5. If resuming at Step 1 (Plan) and no planner agent ID exists, create a new planner agent in Recovery Mode with the existing plan and waves paths 6. If resuming at Step 4 (Learn) and no learner agent ID exists, create a new learner agent in Recovery Mode with the dev/test record paths and local knowledge output path 7. If resuming in the fix loop (Step 2c or 3b), restore `current_bugs` from the state file. If `current_bugs` is empty but `current_step` is `"retest"` or `"fix"`, read the latest test report (wave-level or integration) to rebuild the bug list

**Important**: When resuming, restore all tracked variables (slug, paths, wave_plan, fix_round, agent IDs, metrics) from the state file before continuing.

Step 1: Plan

Call the **planner** agent with:

• The full requirement description
• The slug
• The plan file path
• The waves.json path
• **The knowledge context** from Step 0 (past lessons learned)

After the planner returns:

• **Check for truncated reply** — if the reply is missing the plan file path or waves.json path, the planner likely hit maxTurns. Create a new planner agent in Recovery Mode with the existing plan and waves paths, up to 2 retries (3 total attempts). If all attempts fail, output an error and stop
• **Read the waves.json** — the planner always outputs waves.json. Read it to get the wave plan (task groupin