plan

# /plan — Implementation Plan Generator (Thin Wrapper)

> **v11.0 Architecture**: This command spawns the isolated `plan-phase-agent` via Task(). All planning logic runs in isolated context with question batching.

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

**Active Feature**: !`ls -td specs/[0-9]*-* 2>/dev/null | head -1 || echo "none"`

**Active Epic**: !`ls -td epics/[0-9]*-* 2>/dev/null | head -1 || echo "none"`

**Interaction State**: !`cat specs/*/interaction-state.yaml 2>/dev/null | head -10 || echo "none"`

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

**Is Epic Context**: !`[ -d "$(ls -td epics/[0-9]*-* 2>/dev/null | head -1)" ] && echo "true" || echo "false"`
</context>

<planning_depth>
## Planning Depth Mode (--deep / --quick)

**Detect flags from arguments**:
- `--deep` → Force ultrathink/craftsman mode
- `--quick` → Force standard mode (skip ultrathink)
- Neither → Check preference hierarchy

**Preference hierarchy** (when no flags):
1. `planning.auto_deep_mode: true` → ultrathink by default
2. Epic context → ultrathink (via `deep_planning_triggers.epic_features`)
3. Complexity threshold exceeded → ultrathink
4. Default → standard planning

**When ultrathink is active**:
1. Load skill: `Skill("ultrathink")`
2. Add assumption-questioning step after research
3. Add simplification review before finalizing
4. Generate `craftsman-decision.md` artifact alongside plan.md

**Determine mode**:
```bash
# Check if --deep or --quick flag present in arguments
ARGS="$ARGUMENTS"
DEEP_FLAG=$(echo "$ARGS" | grep -q "\-\-deep" && echo "true" || echo "false")
QUICK_FLAG=$(echo "$ARGS" | grep -q "\-\-quick" && echo "true" || echo "false")

# Load preference
AUTO_DEEP=$(bash .spec-flow/scripts/utils/load-preferences.sh --key "planning.auto_deep_mode" --default "false")

# Detect epic context
IS_EPIC=$([ -d "$(ls -td epics/[0-9]*-* 2>/dev/null | head -1)" ] && echo "true" || echo "false")

# Determine final mode
if [ "$DEEP_FLAG" = "true" ]; then
    PLANNING_MODE="deep"
elif [ "$QUICK_FLAG" = "true" ]; then
    PLANNING_MODE="standard"
elif [ "$AUTO_DEEP" = "true" ]; then
    PLANNING_MODE="deep"
elif [ "$IS_EPIC" = "true" ]; then
    PLANNING_MODE="deep"
else
    PLANNING_MODE="standard"
fi

echo "Planning mode: $PLANNING_MODE"
```
</planning_depth>

<objective>
Spawn isolated plan-phase-agent to generate implementation plan from spec.

**Architecture (v11.1 - Phase Isolation + Ultrathink):**
```
/plan → Detect Mode → [standard] → Task(plan-phase-agent) → plan.md + research.md
                   └→ [deep]    → Skill(ultrathink) → Task(plan-phase-agent) → plan.md + research.md + craftsman-decision.md
```

**Standard mode responsibilities:**
- Read spec.md and project documentation
- Search codebase for reuse opportunities
- Generate architectural decisions
- Return questions for major design choices
- Create plan.md with components and estimates

**Deep mode (ultrathink) additions:**
- Assumption inventory and challenge
- Codebase soul analysis
- Minimum viable architecture exploration
- Design alternatives comparison
- Generate craftsman-decision.md artifact

**Workflow position**: `spec → clarify → plan → tasks → implement → optimize → ship`
</objective>

## Legacy Context (for agent reference)

<legacy_context>
**Feature Classification** (from state.yaml if exists):
!`cat specs/*/state.yaml 2>/dev/null | grep -E "HAS_UI|IS_IMPROVEMENT|recommended_workflow" | head -5 || echo "No classification available"`

**Tech Stack Context** (prevents hallucination):
!`head -30 docs/project/tech-stack.md 2>/dev/null || echo "Not available - will analyze codebase"`

**Data Architecture Context** (prevents duplicate entities):
!`head -20 docs/project/data-architecture.md 2>/dev/null || echo "Not available - will analyze codebase"`
</legacy_context>

<research_instructions>
## REQUIRED RESEARCH STEPS (Claude Code Must Execute)

**Before generating plan.md, you MUST perform this research:**

### Step R1: Read Feature Spec
```
Read the spec.md file completely. Extract:
- All functional requirements (FR-XXX)
- All non-functional requirements (NFR-XXX)
- Success criteria (measurable outcomes)
- Classification flags (HAS_UI, IS_IMPROVEMENT, etc.)
```

### Step R2: Search for Reusable Components

**PRIMARY: Semantic search (mgrep) for pattern discovery:**
```bash
# Use mgrep to find similar implementations by meaning
mgrep "services that handle user authentication"
mgrep "API endpoints for data retrieval"
mgrep "form components with validation"
mgrep "database models with timestamps"
```

mgrep finds similar code even when naming conventions differ (e.g., finds UserService, AuthenticationHandler, LoginManager when searching for "authentication services").

**SECONDARY: Literal searches (when mgrep insufficient):**

**Backend patterns** (execute these Grep/Glob searches):
```bash
# Find existing service patterns
Glob("api/src/services/*.py")       # or api/app/services/
Glob("api/src/modules/*/service.py")

# Find existing repository patterns
Grep("class.*Repository", path="api/", type="py")

# Find existing schemas/validators
Glob("api/src/**/schemas.py")
```

**Frontend patterns** (execute these Grep/Glob searches):
```bash
# Find existing UI components
Glob("apps/*/components/**/*.tsx")
Glob("src/components/**/*.tsx")

# Find existing hooks
Grep("export function use", path="apps/", glob="*.ts*")
Grep("export const use", path="apps/", glob="*.ts*")

# Find existing layouts
Glob("apps/*/app/**/layout.tsx")
```

**Database patterns** (if HAS_MIGRATIONS detected):
```bash
# Find existing migrations to understand naming/style
Glob("api/migrations/versions/*.py")   # Alembic
Glob("prisma/migrations/**/*.sql")     # Prisma

# Find existing models
Grep("class.*Model|Table\\(", path="api/", type="py")
```

### Step R3: Analyze Similar Implementations

For each major component needed:
1. Search codebase for sim