Plan Phase

1. Validate Environment

ls .planning/ 2>/dev/null

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

2. Parse 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.

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_DIR=$(ls -d .planning/phases/${PHASE}-* 2>/dev/null | head -1)
if [ -z "$PHASE_DIR" ]; then
  # Create phase directory from roadmap name
  PHASE_NAME=$(grep "Phase ${PHASE}:" .planning/ROADMAP.md | sed 's/.*Phase [0-9]*: //' | tr '[:upper:]' '[:lower:]' | tr ' ' '-')
  mkdir -p ".planning/phases/${PHASE}-${PHASE_NAME}"
  PHASE_DIR=".planning/phases/${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.

Otherwise:

Check for existing research:

ls "${PHASE_DIR}"/*-RESEARCH.md 2>/dev/null

If RESEARCH.md exists AND --research flag NOT set:

• Display: Using existing research: ${PHASE_DIR}/${PHASE}-RESEARCH.md
• Skip to step 6

If RESEARCH.md missing OR --research flag set:

• Display: Phase {X}: {Name} — researching domain...
• Proceed to spawn researcher

Spawn gsd-phase-researcher

Gather context for research prompt:

# Get phase description from roadmap
PHASE_DESC=$(grep -A3 "Phase ${PHASE}:" .planning/ROADMAP.md)

# Get requirements if they exist
REQUIREMENTS=$(cat .planning/REQUIREMENTS.md 2>/dev/null | grep -A100 "## Requirements" | head -50)

# Get prior decisions from STATE.md
DECISIONS=$(grep -A20 "### Decisions Made" .planning/STATE.md 2>/dev/null)

# Get phase context if exists
PHASE_CONTEXT=$(cat "${PHASE_DIR}/${PHASE}-CONTEXT.md" 2>/dev/null)

Fill research prompt and spawn:

<objective>
Research how to implement Phase {phase_number}: {phase_name}

Answer: "What do I need to know to PLAN this phase well?"
</objective>

<context>
**Phase description:**
{phase_description}

**Requirements (if any):**
{requirements}

**Prior decisions:**
{decisions}

**Phase context (if any):**
{phase_context}
</context>

<output>
Write research findings to: {phase_dir}/{phase}-RESEARCH.md
</output>

Task(
  prompt=research_prompt,
  subagent_type="gsd-phase-researcher",
  description="Research Phase {phase}"
)

Handle Researcher Return

## RESEARCH COMPLETE:

• Display: Research complete. Proceeding to planning...
• Continue to step 6

## RESEARCH BLOCKED:

• Display blocker information
• Offer: 1) Provide more context, 2) Skip research and plan anyway, 3) Abort
• Wait for user response

6. Check Existing Plans

ls "${PHASE_DIR}"/*-PLAN.md 2>/dev/null

If exists: Offer: 1) Continue planning (add more plans), 2) View existing, 3) Replan from scratch. Wait for response.

7. Gather Context Paths

Identify context files for the planner agent:

# Required
STATE=.planning/STATE.md
ROADMAP=.planning/ROADMAP.md
REQUIREMENTS=.planning/REQUIREMENTS.md

# Optional (created by earlier steps or commands)
CONTEXT="${PHASE_DIR}/${PHASE}-CONTEXT.md"
RESEARCH="${PHASE_DIR}/${PHASE}-RESEARCH.md"
VERIFICATION="${PHASE_DIR}/${PHASE}-VERIFICATION.md"
UAT="${PHASE_DIR}/${PHASE}-UAT.md"

8. Spawn gsd-planner Agent

Display: Phase {X}: {Name} — launching planner...

Fill prompt and spawn:

<planning_context>

**Phase:** {phase_number}
**Mode:** {standard | gap_closure}

**Project State:**
@.planning/STATE.md

**Roadmap:**
@.planning/ROADMAP.md

**Requirements (if exists):**
@.planning/REQUIREMENTS.md

**Phase Context (if exists):**
@.planning/phases/{phase_dir}/{phase}-CONTEXT.md

**Research (if exists):**
@.planning/phases/{phase_dir}/{phase}-RESEARCH.md

**Gap Closure (if --gaps mode):**
@.planning/phases/{phase_dir}/{phase}-VERIFICATION.md
@.planning/phases/{phase_dir}/{phase}-UAT.md

</planning_context>

<downstream_consumer>
Output consumed by /gsd:execute-phase or /gsd:execute-plan
Plans must be executable prompts with:

- Frontmatter (wave, depends_on, files_modified, autonomous)
- Tasks in XML format
- Verificatio