| name | run-epic |
| description | Execute an epic plan phase-by-phase, inline by default with opt-in worker spawns per task annotation |
| argument-hint | [--status] [--skip-tests] [--phase N] |
| when_to_use | Running a multi-phase epic created by /devloop:epic |
| allowed-tools | ["Read","Write","Edit","Grep","Glob","Bash","Bash(${CLAUDE_PLUGIN_ROOT}/scripts/*.sh:*)","Monitor","Agent","AskUserQuestion","Skill"] |
Devloop Run Epic
Execute an epic phase-by-phase. Tasks run inline by default; subagents are spawned per task [model:X] annotation (same pattern as /devloop:run). You are the orchestrator -- execute the phase, validate tests, commit, promote the next phase.
Step 1: Load State
Read .devloop/epic.json.
- No file: "No epic found. Use
/devloop:epic <topic> to create one." STOP.
--status: Display phase tracker and STOP.status: "complete": "Epic already complete." STOP.--phase N: Override current phase and re-promote.
Step 2: Validate Plan
Read .devloop/plan.md. Verify **Phase**: matches epic.json.current_phase.
- Mismatch or missing: run
${CLAUDE_PLUGIN_ROOT}/scripts/promote-phase.sh --force.
- All tasks
[x]: skip to Step 5 (already completed).
Step 3: Execute Phase
Read epic.json for context (user_stories, invariants, negative_cases, test_command). Keep this context in working memory while executing the phase.
Execute plan.md tasks inline, following the same model-annotation pattern as /devloop:run:
[model:haiku] tasks: spawn devloop:haiku-worker.[model:sonnet] tasks: spawn devloop:swarm-worker (sonnet).- No annotation: execute inline (no subagent). This is the default — most tasks should be inline.
- Respect
[depends:N.M] constraints and [parallel:X] groupings.
- Do NOT commit or modify epic.json/epic.md during execution (that's Step 5).
Use the epic context to guide your work:
- User stories anchor WHY the tasks exist.
- Invariants / negative cases are testable constraints that must hold.
- Run
test_command after implementation tasks.
Fallback (opt-in only): If the phase is very large (>15 tasks) and session context is already heavy, you MAY delegate the whole phase to a single sonnet subagent in a fresh context. This is a last-resort fresh-context reset, not the default path.
Step 4: Validate Completion
-
Run ${CLAUDE_PLUGIN_ROOT}/scripts/check-plan-complete.sh .devloop/plan.md.
- Incomplete: AskUserQuestion: "Retry" or "Skip remaining".
-
Run tests (unless --skip-tests or test_command is null).
Use Monitor for real-time streaming when test_command matches a known long-running pattern
(test suites: npm test, pytest, go test, cargo test, etc.; builds; full-codebase linting).
Example:
Monitor({ description: "epic phase tests", command: "<test_command> 2>&1 | grep --line-buffered -E 'PASS|FAIL|Error|ok|error|passed|failed'", timeout_ms: 300000, persistent: false })
Fallback: if Monitor errors, run test_command with Bash directly.
- Fail: AskUserQuestion: "Fix and retry" or "Skip tests".
Step 5: Commit & Advance
- Commit:
git add changed files, commit with feat: phase N -- phase-name.
- Update
epic.json: mark phase "complete", record commit hash, increment current_phase.
- Update
epic.md Phase Tracker table.
- If all phases complete: Report done. AskUserQuestion: "Ship it" or "Review". STOP.
- Promote next phase: run
${CLAUDE_PLUGIN_ROOT}/scripts/promote-phase.sh --force.
Report:
Phase N complete and committed.
Phase M loaded: "Phase Name" (X tasks)
Step 6: Pause Point
The next phase is already loaded in plan.md. AskUserQuestion:
- Continue now: Loop to Step 3 in the same session.
- Clear and run: "Run
/clear, then /devloop:run-epic to execute Phase M." STOP.
Recovery
run-epic is resumable. epic.json is the source of truth:
- Mid-phase: plan.md has partial progress, execution picks up remaining tasks.
- Post-phase: detects plan complete, skips to validation.
- After
/clear: reads epic.json, resumes from correct phase.
If the repo is in a broken state (e.g. orphaned changes, mismatched plan), run-epic will detect the mismatch in Step 2 and re-promote the correct phase. Tests in Step 4 catch implementation issues before committing.
Now: Load epic state and begin.
