/epic

Orchestrator for multi-session epic. Invoke the bundled run-sessions.sh from the installed plugin, which spawns a fresh Claude per session (clean context), plans, executes, commits.

DAG: Sessions declare YAML frontmatter (depends_on, touches, parallel_safe) for a DAG. Runner schedules Kahn-style waves, fans out per-session worktrees (concurrent), merges to trunk. No frontmatter = linear chain.

Isolation: Trunk worktree .epic-worktrees/<repo>/epic--<name>/, per-session siblings .epic-worktrees/<repo>/epic--<name>--sNN-<slug>/. --no-worktree = sequential.

Sessions dir: docs/claude-sessions/<name>/

Per-session frontmatter overrides:

session: 02
title: "Analysis task"
depends_on: [01]
model: "opus"
cli: "claude"
touches: ["analysis/**"]
parallel_safe: true

Multi-epic: For problems spanning multiple independent subsystems, use /epic-toolkit:epic.generate to split into separate epic directories under docs/claude-sessions/. Prefer /epic-toolkit:sprint — it runs them back-to-back on a shared trunk branch and opens a single PR for the whole sprint:

/epic-toolkit:sprint docs/claude-sessions/<sprint-name>.sprint.json

Or run each epic sequentially with manual invocations — each must complete and merge to trunk before the next starts (one PR per epic):

/epic-toolkit:epic epic-1-name
/epic-toolkit:epic epic-2-name

Defaults: name (required), --start 1, --end all, --max-parallel 4, --strict false, --sequential false, --show-dag false, --model sonnet, --cli auto, --branch epic/<name>, --base <repo-default>, --dry-run false, --no-worktree false, --timeout 0, --retry 0, --keep-worktree false, --keep-session-worktrees false, --keep-session-docs false, --no-pr false, --no-rebase false, --no-commit false, --skip-plan false, --wave-timeout 0 (auto), --fresh false.

Validate

1. Confirm docs/claude-sessions/<name>/ exists. If not, list available under docs/claude-sessions/ and ask user to pick.

Execute

bash "${CLAUDE_PLUGIN_ROOT}/scripts/run-sessions.sh" docs/claude-sessions/<name>/ \
  [--start N] [--end N] [--timeout MINS] [--retry N] [--max-parallel N] [--wave-timeout MINS] \
  [--strict] [--sequential] [--skip-plan] [--no-worktree] [--no-rebase] \
  [--no-commit] [--no-pr] [--keep-worktree] [--keep-session-worktrees] \
  [--keep-session-docs] [--fresh] [--show-dag] \
  [--model M] [--cli opencode|claude] [--branch B] [--base B] [--dry-run]

Run via Bash tool with run_in_background: true (long-running). For --show-dag only, no background needed.

After launch

Tell the user:

• Epic branch (e.g., epic/<name>, or explicit --branch — never "main")
• Will report back when complete

Example: "Running epic '' — all sessions will commit to branch epic/<name>. I'll report back when it completes."

After completion

1. Parse [EPIC_RESULT_START] / [EPIC_RESULT_END] block from output.
2. If STATUS=failed: read the JSON at the path emitted as RESULT_FILE= inside the result block (lives under ${TMPDIR}/epic-toolkit/, retained on both success and failure). Report failed session ID(s), error type, exit code, log path, and ERROR_DETAIL if present. Provide resume command.
3. If STATUS=success: report waves, sessions completed, runtime.
4. Report trunk worktree location (if applicable).
5. Report session logs and plans location.