epic

<objective>
Orchestrate multi-sprint epic delivery through **isolated phase agents spawned via Task()** with parallel sprint execution and comprehensive quality gates.

**Command**: `/epic [epic description | slug | continue | next]`

**Runtime ownership note**: Epic workflow semantics and state belong to the
shared canon. This command is currently a Claude adapter surface while epic
runtime behavior converges on the same shared ownership model as the rest of
Spec-Flow.

**CRITICAL ARCHITECTURE** (v7.0 - Domain Memory v2):

This orchestrator is **ultra-lightweight**. You MUST:
1. Read state from disk (state.yaml, interaction-state.yaml, domain-memory.yaml)
2. Spawn isolated phase agents via **Task tool** - NEVER execute phases inline
3. Handle user Q&A when agents return questions
4. Update state.yaml after each phase
5. NEVER carry implementation details in your context

**Key Difference from /feature**:
- Epic creates sprint-level domain-memory.yaml files for parallel execution
- Implementation spawns multiple workers across sprints simultaneously
- More sophisticated dependency tracking between sprints

**Benefits**: Unlimited epic complexity, 3-5x faster delivery via parallelism, observable progress, resumable at any point.
</objective>

<context>
**User Input**: $ARGUMENTS

**Project State**: !`test -d docs/project && echo "initialized" || echo "missing"`

**Git Configuration**:
- Remote: !`git remote -v 2>/dev/null | head -1 | grep -q origin && echo "configured" || echo "none"`
- Current branch: !`git branch --show-current 2>/dev/null || echo "none"`
- Staging workflow: !`test -f .github/workflows/deploy-staging.yml && echo "present" || echo "missing"`

**Epic Workspace**: !`ls -d epics/*/ 2>/dev/null | head -3 || echo "none"`

**Workflow State**: @epics/*/state.yaml

**Planning Depth Preference**: !`bash .spec-flow/scripts/utils/load-preferences.sh --key "planning.auto_deep_mode" --default "false" 2>/dev/null || echo "false"`

**Epic Trigger for Deep Planning**: !`bash .spec-flow/scripts/utils/load-preferences.sh --key "planning.deep_planning_triggers.epic_features" --default "true" 2>/dev/null || echo "true"`

**Auto-ship preference**: !`bash .spec-flow/scripts/utils/load-preferences.sh --key "deployment.auto_ship" --default "false" 2>/dev/null || echo "false"`

**Auto-merge preference**: !`bash .spec-flow/scripts/utils/load-preferences.sh --key "deployment.auto_merge" --default "false" 2>/dev/null || echo "false"`

**Auto-finalize preference**: !`bash .spec-flow/scripts/utils/load-preferences.sh --key "deployment.auto_finalize" --default "true" 2>/dev/null || echo "true"`

**Studio context (multi-agent isolation)**: !`bash .spec-flow/scripts/bash/worktree-context.sh studio-detect 2>/dev/null || echo ""`

**Worktree context**: !`bash .spec-flow/scripts/bash/worktree-context.sh info 2>/dev/null || echo '{"is_worktree": false}'`
</context>

<planning_depth>
## Planning Depth Mode for Epics

**NOTE**: Epics automatically trigger ultrathink/deep planning by default via `deep_planning_triggers.epic_features: true`.

**Flags in $ARGUMENTS**:
- `--deep` → Explicitly force ultrathink (redundant for epics, but explicit)
- `--auto` → Use preferences AND continue through ship→finalize without stopping
- Neither → Interactive mode, still uses deep planning for epics

**Epic-specific benefits of ultrathink**:
- Assumption questioning across multiple sprints
- Codebase soul analysis informs sprint boundaries
- Minimum viable architecture prevents over-engineering
- Design alternatives help sprint prioritization

**State tracking**:
```yaml
# In epics/NNN-slug/state.yaml
planning:
  mode: deep
  ultrathink_enabled: true
  triggered_by: epic_features  # or explicit_flag
```
</planning_depth>

<auto_mode>
## Auto Mode (--auto flag) for Epics

When `--auto` flag is present, the epic workflow runs end-to-end without stopping:

**Full auto-mode behavior** (when `--auto` flag is set):
1. **Planning**: Use deep planning (epics always trigger ultrathink)
2. **Implementation**: Execute all sprints in parallel per dependency layers
3. **Ship**: Check CI, auto-merge when passing (if `deployment.auto_merge: true`)
4. **Finalize**: Run /finalize automatically with epic walkthrough generation

**Preference-controlled auto-ship** (v11.7):
- `deployment.auto_ship: true` → Continue from optimize → ship → finalize without stopping
- `deployment.auto_merge: true` → Auto-merge PR when CI passes (no production approval prompt)
- `deployment.auto_finalize: true` → Run /finalize automatically after successful deployment

**Parse --auto flag at start**:
```bash
AUTO_MODE="false"
if [[ "$ARGUMENTS" == *"--auto"* ]]; then
  AUTO_MODE="true"
  AUTO_SHIP=$(bash .spec-flow/scripts/utils/load-preferences.sh --key "deployment.auto_ship" --default "false" 2>/dev/null || echo "false")
  AUTO_MERGE=$(bash .spec-flow/scripts/utils/load-preferences.sh --key "deployment.auto_merge" --default "false" 2>/dev/null || echo "false")
  AUTO_FINALIZE=$(bash .spec-flow/scripts/utils/load-preferences.sh --key "deployment.auto_finalize" --default "true" 2>/dev/null || echo "true")
fi
```

**State tracking**:
```yaml
# In epics/NNN-slug/state.yaml
auto_mode:
  enabled: true
  auto_ship: true   # Continue optimize → ship → finalize
  auto_merge: true  # Auto-merge when CI passes
  auto_finalize: true
```
</auto_mode>

<studio_mode>
## Studio Mode (Multi-Agent Isolation) (v11.8)

When running in a studio worktree (`worktrees/studio/agent-N/`), the epic workflow automatically:

1. **Detects studio context** - Auto-detected from working directory
2. **Namespaces branches** - `studio/agent-N/epic/XXX-slug` instead of `epic/XXX-slug`
3. **Creates PRs for merging** - Studio agents always create PRs (like a real dev team)
4. **Prevents git conflicts** - Each agent has isolated branches

**Detection (automatic, no user action needed):**
```bash
STUDIO_AGENT=$(bash .spec-flow/scripts/bash/worktree-context.sh studio-detect 2>/dev/null || echo "")
IS_S