Plan Phase

---
name: vit:plan-phase
description: Create detailed execution plan for a phase (PLAN.md) with verification loop
argument-hint: "[phase] [--research] [--skip-research] [--gaps] [--skip-verify]"
agent: vit-planner
allowed-tools:
  - Read
  - Write
  - Bash
  - Glob
  - Grep
  - Task
  - WebFetch
  - mcp__context7__*
---

<execution_context>
@./.claude/vit/references/ui-brand.md
</execution_context>

<objective>
Create executable phase prompts (PLAN.md files) for a roadmap phase with integrated research and verification.

**Default flow:** Research (if needed) → Plan → Verify → Done

**Orchestrator role:** Parse arguments, validate phase, research domain (unless skipped or exists), spawn vit-planner agent, verify plans with vit-plan-checker, iterate until plans pass or max iterations reached, present results.

**Why subagents:** Research and planning burn context fast. Verification uses fresh context. User sees the flow between agents in main context.
</objective>

<context>
Phase number: $ARGUMENTS (optional - auto-detects next unplanned phase if not provided)

**Flags:**
- `--research` — Force re-research even if RESEARCH.md exists
- `--skip-research` — Skip research entirely, go straight to planning
- `--gaps` — Gap closure mode (reads VERIFICATION.md, skips research)
- `--skip-verify` — Skip planner → checker verification loop

Normalize phase input in step 2 before any directory lookups.
</context>

<process>

## 1. Validate Environment and Resolve Model Profile

```bash
ls .planning/ 2>/dev/null

If not found: Error - user should run /vit:new-project first.

Resolve model profile for agent spawning:

MODEL_PROFILE=$(cat .planning/config.json 2>/dev/null | grep -o '"model_profile"[[:space:]]*:[[:space:]]*"[^"]*"' | grep -o '"[^"]*"$' | tr -d '"' || echo "balanced")

Default to "balanced" if not set.

Model lookup table:

Agent	quality	balanced	budget
vit-phase-researcher	opus	sonnet	haiku
vit-planner	opus	opus	sonnet
vit-plan-checker	sonnet	sonnet	haiku

Store resolved models for use in Task calls below.

1.5. Determine WORK_DIR

PHASE_NUM=$(echo "$ARGUMENTS" | grep -o '^[0-9]*')
MILESTONE=$(grep "^Milestone:" .planning/STATE.md 2>/dev/null | sed 's/Milestone: //' | tr -d ' ')
if [ -z "$MILESTONE" ]; then
  MILESTONE=$(git branch --show-current | grep -o 'v[0-9]*\.[0-9]*\.[0-9]*' | head -1)
fi
# Try milestone-scoped key first, fall back to legacy global key
DESIGNATED_BRANCH=$(grep "| ${MILESTONE}/${PHASE_NUM} " .planning/STATE.md 2>/dev/null | grep -o 'feature/[^ |]*' | head -1)
if [ -z "$DESIGNATED_BRANCH" ]; then
  DESIGNATED_BRANCH=$(grep "| ${PHASE_NUM} " .planning/STATE.md 2>/dev/null | grep -o 'feature/[^ |]*' | head -1)
fi
MAIN_WORKTREE=$(git worktree list --porcelain | head -1 | sed 's/worktree //')
IN_MAIN_WORKTREE=$([ "$(pwd)" = "$MAIN_WORKTREE" ] && echo "yes" || echo "no")
WORK_DIR="$(pwd)"  # default

if [ -n "$DESIGNATED_BRANCH" ] && [ "$IN_MAIN_WORKTREE" = "yes" ]; then
  EXISTING=$(git worktree list --porcelain | grep -B2 "branch refs/heads/$DESIGNATED_BRANCH" | head -1 | sed 's/worktree //')
  if [ -n "$EXISTING" ]; then
    WORK_DIR="$EXISTING"
  else
    WORKTREE_PATH="../$(basename $(git rev-parse --show-toplevel))-${DESIGNATED_BRANCH//\//-}"
    git worktree add "$WORKTREE_PATH" "$DESIGNATED_BRANCH" 2>/dev/null
    WORK_DIR="$WORKTREE_PATH"
  fi
fi

All subsequent file reads and bash commands use $WORK_DIR as base. Pass WORK_DIR to all spawned subagents.

2. Parse and Normalize Arguments

Extract from $ARGUMENTS:

• Phase number (integer or decimal like 2.1)
• --research flag to force re-research
• --skip-research flag to skip research
• --gaps flag for gap closure mode
• --skip-verify flag to bypass verification loop

If no phase number: Detect next unplanned phase from roadmap.

Normalize phase to zero-padded format:

# Normalize phase number (8 → 08, but preserve decimals like 2.1 → 02.1)
if [[ "$PHASE" =~ ^[0-9]+$ ]]; then
  PHASE=$(printf "%02d" "$PHASE")
elif [[ "$PHASE" =~ ^([0-9]+)\.([0-9]+)$ ]]; then
  PHASE=$(printf "%02d.%s" "${BASH_REMATCH[1]}" "${BASH_REMATCH[2]}")
fi

Check for existing research and plans:

ls .planning/phases/${MILESTONE}/${PHASE}-*/*-RESEARCH.md 2>/dev/null
# Fallback for historical phases in root
ls .planning/phases/${PHASE}-*/*-RESEARCH.md 2>/dev/null
ls .planning/phases/${MILESTONE}/${PHASE}-*/*-PLAN.md 2>/dev/null
ls .planning/phases/${PHASE}-*/*-PLAN.md 2>/dev/null

3. Validate Phase

grep -A5 "Phase ${PHASE}:" .planning/ROADMAP.md 2>/dev/null

If not found: Error with available phases. If found: Extract phase number, name, description.

4. Ensure Phase Directory Exists

# PHASE is already normalized (08, 02.1, etc.) from step 2
# Try milestone-scoped path first, fall back to root for historical phases
PHASE_DIR=$(ls -d ".planning/phases/${MILESTONE}/${PHASE}-"* 2>/dev/null | head -1)
if [ -z "$PHASE_DIR" ]; then
  PHASE_DIR=$(ls -d ".planning/phases/${PHASE}-"* 2>/dev/null | head -1)
fi
if [ -z "$PHASE_DIR" ]; then
  # Create new phase directory under milestone namespace
  PHASE_NAME=$(grep "Phase ${PHASE}:" .planning/ROADMAP.md | sed 's/.*Phase [0-9]*: //' | tr '[:upper:]' '[:lower:]' | tr ' ' '-')
  mkdir -p ".planning/phases/${MILESTONE}/${PHASE}-${PHASE_NAME}"
  PHASE_DIR=".planning/phases/${MILESTONE}/${PHASE}-${PHASE_NAME}"
fi

5. Handle Research

If --gaps flag: Skip research (gap closure uses VERIFICATION.md instead).

If --skip-research flag: Skip to step 6.

Check config for research setting:

WORKFLOW_RESEARCH=$(cat .planning/config.json 2>/dev/null | grep -o '"research"[[:space:]]*:[[:space:]]*[^,}]*' | grep -o 'true\|false' || echo "true")

If workflow.research is false AND --research flag NOT set: Skip to step 6.

Otherwise:

Check for existing research: ```