---
name: kata-plan-phase
description: Plan detailed roadmap phases. Triggers include "plan phase n", "create phase plan", "create a plan" "roadmap planning", and "roadmap phase creation".
metadata:
  version: "1.6.1"
---
<execution_context>
@./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 kata-planner agent, verify plans with kata-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>

## 0. Pre-flight: Check roadmap format (auto-migration)

If ROADMAP.md exists, check format and auto-migrate if old:

```bash
if [ -f .planning/ROADMAP.md ]; then
  bash ../kata-doctor/scripts/check-roadmap-format.sh 2>/dev/null
  FORMAT_EXIT=$?
  
  if [ $FORMAT_EXIT -eq 1 ]; then
    echo "Old roadmap format detected. Running auto-migration..."
  fi
fi
```

**If exit code 1 (old format):**

Invoke kata-doctor in auto mode:

```
Skill("kata-doctor", "--auto")
```

Continue after migration completes.

**If exit code 0 or 2:** Continue silently.

```bash
# Validate config and template overrides
bash ../kata-doctor/scripts/check-config.sh 2>/dev/null || true
bash ../kata-doctor/scripts/check-template-drift.sh 2>/dev/null || true
```

## 1. Validate Environment and Resolve Model Profile

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

**If not found:** Error - user should run `/kata-new-project` first.

**Resolve model profile for agent spawning:**

```bash
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 |
| --------------------- | ------- | -------- | ------ |
| kata-phase-researcher | opus    | sonnet   | haiku  |
| kata-planner          | opus    | opus     | sonnet |
| kata-plan-checker     | sonnet  | sonnet   | haiku  |

Store resolved models for use in Task calls below.

## 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:**

```bash
# 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 (uses universal phase discovery):**

```bash
# Find phase directory across state subdirectories
PADDED=$(printf "%02d" "$PHASE" 2>/dev/null || echo "$PHASE")
PHASE_DIR=""
for state in active pending completed; do
  PHASE_DIR=$(find .planning/phases/${state} -maxdepth 1 -type d -name "${PADDED}-*" 2>/dev/null | head -1)
  [ -z "$PHASE_DIR" ] && PHASE_DIR=$(find .planning/phases/${state} -maxdepth 1 -type d -name "${PHASE}-*" 2>/dev/null | head -1)
  [ -n "$PHASE_DIR" ] && break
done
# Fallback: flat directory (backward compatibility for unmigrated projects)
if [ -z "$PHASE_DIR" ]; then
  PHASE_DIR=$(find .planning/phases -maxdepth 1 -type d -name "${PADDED}-*" 2>/dev/null | head -1)
  [ -z "$PHASE_DIR" ] && PHASE_DIR=$(find .planning/phases -maxdepth 1 -type d -name "${PHASE}-*" 2>/dev/null | head -1)
fi

# Collision check: detect duplicate phase numbering that requires migration
MATCH_COUNT=0
for state in active pending completed; do
  MATCH_COUNT=$((MATCH_COUNT + $(find .planning/phases/${state} -maxdepth 1 -type d -name "${PADDED}-*" 2>/dev/null | wc -l)))
done
# Include flat fallback matches
MATCH_COUNT=$((MATCH_COUNT + $(find .planning/phases -maxdepth 1 -type d -name "${PADDED}-*" 2>/dev/null | wc -l)))

if [ "$MATCH_COUNT" -gt 1 ]; then
  echo "COLLISION: ${MATCH_COUNT} directories match prefix '${PADDED}-*' across phase states."
  echo "This project uses old per-milestone phase numbering that must be migrated first."
fi
```

**If COLLISION detected (MATCH_COUNT > 1):** STOP planning. Invoke `/kata-doctor` to renumber phases to globally sequential numbering. After migration completes, re-invoke `/kata-plan-phase` with the migrated phase number. Do NOT continue with ambiguous phase directories.

```bash
find "${PHASE_DIR}" -maxdepth 1 -name "*-RESEARCH.md" 2>/dev/null
find "${PHASE_DIR}" -maxdepth 1 -name "*-PLAN.md" 2>/dev/null
```

## 3. Validate Phase

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

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

## 3.5. Check-or-Ask Model Profile

Check if model_profile has been set in config:

```bash
KATA_SCRIPTS="../kata-configure-settings/scripts"
MODEL_PROFILE_SET=$(cat .planning/config.json 2>/dev/null | grep -o '"model_profile"' | head -1)
```

**If model_profile is absent (empty MODEL_PROFILE_SET):**

This is the first plan-phase run. Ask the user for model_profile.

Use AskUserQuestion:
- header: "Model Profile"
- question: "Which AI models for planning agents?"
- options:
  - "Balanced (Recommended)" — Sonnet for most agents — good quality/cost ratio
  - "Quality" — Opus for research/roadmap — higher cost, deeper analysis
  - "Budget" — Haiku where possible — fastest, lowest cost

After user responds, write to config:

```bash
# Map selection to value
# Balanced -> balanced, Quality -> quality, Budget -> budget
bash "${KATA_SCRIPTS}/set-config.sh" "model_profile" "$CHOSEN_PROFILE"
```

Display first-run agent defaults notice:

```
+--------------------------------------------------+
| Agent defaults active: Research, Plan Check,     |
| Verification. Run /kata-configure-settings to    |
| customize agent preferences.                     |
+--------------------------------------------------+
```

**If model_profile exists:** No-op. Continue to step 4.

## 4. Ensure Phase Directory Exists

```bash
# PHASE is already normalized (08, 02.1, etc.) from step 2
# Use universal phase discovery: search active/pending/completed with flat fallback
PADDED=$(printf "%02d" "$PHASE" 2>/dev/null || echo "$PHASE")
PHASE_DIR=""
for state in active pending completed; do
  PHASE_DIR=$(find .planning/phases/${state} -maxdepth 1 -type d -name "${PADDED}-*" 2>/dev/null | head -1)
  [ -z "$PHASE_DIR" ] && PHASE_DIR=$(find .planning/phases/${state} -maxdepth 1 -type d -name "${PHASE}-*" 2>/dev/null | head -1)
  [ -n "$PHASE_DIR" ] && break
done
# Fallback: flat directory (backward compatibility for unmigrated projects)
if [ -z "$PHASE_DIR" ]; then
  PHASE_DIR=$(find .planning/phases -maxdepth 1 -type d -name "${PADDED}-*" 2>/dev/null | head -1)
  [ -z "$PHASE_DIR" ] && PHASE_DIR=$(find .planning/phases -maxdepth 1 -type d -name "${PHASE}-*" 2>/dev/null | head -1)
fi

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

```bash
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:

```bash
find "${PHASE_DIR}" -maxdepth 1 -name "*-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 stage banner:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 Kata ► RESEARCHING PHASE {X}
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

◆ Spawning researcher...


Proceed to spawn researcher

### Spawn kata-phase-researcher

Gather context for research prompt:

```bash
# 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:

```markdown
<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="<agent-instructions>\n{phase_researcher_instructions_content}\n</agent-instructions>\n\n" + research_prompt,
  subagent_type="general-purpose",
  model="{researcher_model}",
  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

```bash
find "${PHASE_DIR}" -maxdepth 1 -name "*-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. Read Context Files

Read and store context file contents for the planner agent. The `@` syntax does not work across Task() boundaries - content must be inlined.

**Read these files using the Read tool:**
- `.planning/STATE.md` (required)
- `.planning/ROADMAP.md` (required)
- `.planning/REQUIREMENTS.md` (if exists)
- `${PHASE_DIR}/*-CONTEXT.md` (if exists)
- `${PHASE_DIR}/*-RESEARCH.md` (if exists)
- `${PHASE_DIR}/*-VERIFICATION.md` (if --gaps mode)
- `${PHASE_DIR}/*-UAT.md` (if --gaps mode)
- `references/planner-instructions.md` (relative to skill base directory) — store as `planner_instructions_content`
- `references/phase-researcher-instructions.md` (relative to skill base directory) — store as `phase_researcher_instructions_content`
- `references/plan-checker-instructions.md` (relative to skill base directory) — store as `plan_checker_instructions_content`

**Resolve plan template (project override -> plugin default):**

```bash
RESOLVE_SCRIPT="../kata-execute-phase/scripts/resolve-template.sh"
PLAN_TEMPLATE_PATH=$(bash "$RESOLVE_SCRIPT" "plan-template.md")
PLAN_TEMPLATE_CONTENT=$(cat "$PLAN_TEMPLATE_PATH")
```

Store `PLAN_TEMPLATE_CONTENT` for use in the Step 8 planner prompt.

**Read latest brainstorm SUMMARY.md (if exists):**

```bash
LATEST_BRAINSTORM=$(ls -dt .planning/brainstorms/*/SUMMARY.md 2>/dev/null | head -1)
if [ -n "$LATEST_BRAINSTORM" ]; then
  BRAINSTORM_CONTEXT=$(cat "$LATEST_BRAINSTORM")
fi
```

Store `BRAINSTORM_CONTEXT` for use in Step 8 prompt. If no brainstorm exists, this variable is empty (no error).

Store all content for use in the Task prompt below.

### Extract Linked Issues from STATE.md

After reading the base context files, extract any issues linked to this phase from STATE.md:

```bash
# Normalize phase identifier
PHASE_DIR_NAME=$(basename "$PHASE_DIR")
PHASE_NUM=$(echo "$PHASE_DIR_NAME" | grep -oE '^[0-9.]+')

# Extract linked issues from both sections
LINKED_ISSUES=""

# Check Pending Issues (from check-issues "Link to existing phase")
if grep -q "^### Pending Issues" .planning/STATE.md 2>/dev/null; then
  PENDING=$(awk '
    /^### Pending Issues/{found=1; next}
    /^### |^## /{if(found) exit}
    found && /→ Phase/ {
      # Match phase number or full phase dir name
      if ($0 ~ /→ Phase '"${PHASE_NUM}"'-/ || $0 ~ /→ Phase '"${PHASE_DIR_NAME}"'/) {
        print
      }
    }
  ' .planning/STATE.md)
  [ -n "$PENDING" ] && LINKED_ISSUES="${PENDING}"
fi

# Check Milestone Scope Issues (from add-milestone issue selection)
if grep -q "^### Milestone Scope Issues" .planning/STATE.md 2>/dev/null; then
  SCOPE=$(awk '
    /^### Milestone Scope Issues/{found=1; next}
    /^### |^## /{if(found) exit}
    found && /→ Phase/ {
      if ($0 ~ /→ Phase '"${PHASE_NUM}"'-/ || $0 ~ /→ Phase '"${PHASE_DIR_NAME}"'/) {
        print
      }
    }
  ' .planning/STATE.md)
  [ -n "$SCOPE" ] && LINKED_ISSUES="${LINKED_ISSUES}${SCOPE}"
fi
```

Build the issue context section for the prompt (only if issues are linked):

```bash
ISSUE_CONTEXT_SECTION=""
if [ -n "$LINKED_ISSUES" ]; then
  ISSUE_CONTEXT_SECTION="
**Linked Issues:**
${LINKED_ISSUES}

Note: Set \`source_issue:\` in plan frontmatter for traceability:
- GitHub issues: \`source_issue: github:#N\` (extract from provenance field)
- Local issues: \`source_issue: [file path]\`
"
fi
```

Store ISSUE_CONTEXT_SECTION for use in Step 8 prompt.

## 8. Spawn kata-planner Agent

Display stage banner:

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 Kata ► PLANNING PHASE {X}
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

◆ Spawning planner...


Fill prompt with inlined content and spawn:

```markdown
<planning_context>

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

**Project State:**
{state_content}

**Roadmap:**
{roadmap_content}

**Requirements (if exists):**
{requirements_content}

**Phase Context (if exists):**
{context_content}

**Research (if exists):**
{research_content}

**Linked Issues (from STATE.md):**
{issue_context_section}

**Brainstorm Context (if exists):**
{brainstorm_context}

**Gap Closure (if --gaps mode):**
{verification_content}
{uat_content}

</planning_context>

<plan_template>
{plan_template_content}
</plan_template>

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

- Frontmatter (wave, depends_on, files_modified, autonomous)
- Tasks in XML format
- Verification criteria
- must_haves for goal-backward verification
</downstream_consumer>

<quality_gate>
Before returning PLANNING COMPLETE:

- [ ] PLAN.md files created in phase directory
- [ ] Each plan has valid frontmatter
- [ ] Tasks are specific and actionable
- [ ] Dependencies correctly identified
- [ ] Waves assigned for parallel execution
- [ ] must_haves derived from phase goal
</quality_gate>
```

```
Task(
  prompt="<agent-instructions>\n{planner_instructions_content}\n</agent-instructions>\n\n" + filled_prompt,
  subagent_type="general-purpose",
  model="{planner_model}",
  description="Plan Phase {phase}"
)
```

## 9. Handle Planner Return

Parse planner output:

**`## PLANNING COMPLETE`:**
- Display: `Planner created {N} plan(s). Files on disk.`
- If `--skip-verify`: Skip to step 13
- Check config: `WORKFLOW_PLAN_CHECK=$(cat .planning/config.json 2>/dev/null | grep -o '"plan_check"[[:space:]]*:[[:space:]]*[^,}]*' | grep -o 'true\|false' || echo "true")`
- If `workflow.plan_check` is `false`: Skip to step 13
- Otherwise: Proceed to step 10

**`## CHECKPOINT REACHED`:**
- Present to user, get response, spawn continuation (see step 12)

**`## PLANNING INCONCLUSIVE`:**
- Show what was attempted
- Offer: Add context, Retry, Manual
- Wait for user response

## 10. Spawn kata-plan-checker Agent

Display:
`
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 Kata ► VERIFYING PLANS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

◆ Spawning plan checker...


Read plans and requirements for the checker:

```bash
# Read all plans in phase directory
PLANS_CONTENT=$(cat "${PHASE_DIR}"/*-PLAN.md 2>/dev/null)

# Read requirements (reuse from step 7 if available)
REQUIREMENTS_CONTENT=$(cat .planning/REQUIREMENTS.md 2>/dev/null)
```

Fill checker prompt with inlined content and spawn:

```markdown
<verification_context>

**Phase:** {phase_number}
**Phase Goal:** {goal from ROADMAP}

**Plans to verify:**
{plans_content}

**Requirements (if exists):**
{requirements_content}

</verification_context>

<expected_output>
Return one of:
- ## VERIFICATION PASSED — all checks pass
- ## ISSUES FOUND — structured issue list
</expected_output>
```

```
Task(
  prompt="<agent-instructions>\n{plan_checker_instructions_content}\n</agent-instructions>\n\n" + checker_prompt,
  subagent_type="general-purpose",
  model="{checker_model}",
  description="Verify Phase {phase} plans"
)
```

## 11. Handle Checker Return

**If `## VERIFICATION PASSED`:**
- Display: `Plans verified. Checking GitHub integration...`
- **Execute Step 13 now** — run the GitHub config check and issue update

**If `## ISSUES FOUND`:**
- Display: `Checker found issues:`
- List issues from checker output
- Check iteration count
- Proceed to step 12

## 12. Revision Loop (Max 3 Iterations)

Track: `iteration_count` (starts at 1 after initial plan + check)

**If iteration_count < 3:**

Display: `Sending back to planner for revision... (iteration {N}/3)`

Read current plans for revision context:

```bash
PLANS_CONTENT=$(cat "${PHASE_DIR}"/*-PLAN.md 2>/dev/null)
```

Spawn kata-planner with revision prompt:

```markdown
<revision_context>

**Phase:** {phase_number}
**Mode:** revision

**Existing plans:**
{plans_content}

**Checker issues:**
{structured_issues_from_checker}

</revision_context>

<instructions>
Make targeted updates to address checker issues.
Do NOT replan from scratch unless issues are fundamental.
Return what changed.
</instructions>
```

```
Task(
  prompt="<agent-instructions>\n{planner_instructions_content}\n</agent-instructions>\n\n" + revision_prompt,
  subagent_type="general-purpose",
  model="{planner_model}",
  description="Revise Phase {phase} plans"
)
```

- After planner returns → spawn checker again (step 10)
- Increment iteration_count

**If iteration_count >= 3:**

Display: `Max iterations reached. {N} issues remain:`
- List remaining issues

Offer options:
1. Force proceed (execute despite issues)
2. Provide guidance (user gives direction, retry)
3. Abandon (exit planning)

Wait for user response.

## 13. GitHub Integration Check

**Check config guards:**

```bash
GITHUB_ENABLED=$(cat .planning/config.json 2>/dev/null | grep -o '"enabled"[[:space:]]*:[[:space:]]*[^,}]*' | grep -o 'true\|false' || echo "false")
ISSUE_MODE=$(cat .planning/config.json 2>/dev/null | grep -o '"issueMode"[[:space:]]*:[[:space:]]*"[^"]*"' | grep -o '"[^"]*"$' | tr -d '"' || echo "never")
```

**If `GITHUB_ENABLED != true` OR `ISSUE_MODE = never`:**
- Log: `Skipping GitHub issue update (github.enabled=${GITHUB_ENABLED}, issueMode=${ISSUE_MODE})`
- Skip to `<offer_next>`

**If enabled, find phase issue:**

```bash
# Get milestone version from ROADMAP.md (the one marked current/in-progress)
VERSION=$(grep -E "Current Milestone:|🔄" .planning/ROADMAP.md | grep -oE 'v[0-9]+\.[0-9]+(\.[0-9]+)?' | head -1 | tr -d 'v' || echo "")

if [ -z "$VERSION" ]; then
  echo "Warning: Could not determine milestone version. Skipping GitHub issue update."
  # Continue to offer_next (non-blocking)
fi

# Find phase issue number
# gh issue list --milestone only searches open milestones; use API to include closed
REPO_SLUG=$(gh repo view --json nameWithOwner --jq '.nameWithOwner' 2>/dev/null)
MS_NUM=$(gh api "repos/${REPO_SLUG}/milestones?state=all" --jq ".[] | select(.title==\"v${VERSION}\") | .number" 2>/dev/null)
ISSUE_NUMBER=""
if [ -n "$MS_NUM" ]; then
  ISSUE_NUMBER=$(gh api "repos/${REPO_SLUG}/issues?milestone=${MS_NUM}&state=open&labels=phase&per_page=100" \
    --jq "[.[] | select(.title | startswith(\"Phase ${PHASE}:\"))][0].number" 2>/dev/null)
fi

if [ -z "$ISSUE_NUMBER" ]; then
  echo "Warning: Could not find GitHub Issue for Phase ${PHASE}. Skipping checklist update."
  # Continue to offer_next (non-blocking)
fi
```

**Build plan checklist from PLAN.md files:**

```bash
PLAN_CHECKLIST=""
PLAN_COUNT=0
for plan_file in $(find "${PHASE_DIR}" -maxdepth 1 -name "*-PLAN.md" 2>/dev/null | sort); do
  PLAN_NUM=$(basename "$plan_file" | sed -E 's/.*-([0-9]+)-PLAN\.md/\1/')
  # Extract brief objective from plan (first line after <objective>)
  PLAN_OBJECTIVE=$(grep -A2 "<objective>" "$plan_file" | head -2 | tail -1 | sed 's/^ *//' | head -c 60)
  # Fallback if objective extraction fails
  if [ -z "$PLAN_OBJECTIVE" ]; then
    PLAN_OBJECTIVE=$(basename "$plan_file" .md | sed 's/-PLAN$//' | sed 's/-/ /g')
  fi
  PLAN_CHECKLIST="${PLAN_CHECKLIST}- [ ] Plan ${PLAN_NUM}: ${PLAN_OBJECTIVE}
"
  PLAN_COUNT=$((PLAN_COUNT + 1))
done
```

**Update issue body with plan checklist:**

Use the script at `./scripts/update-issue-plans.py` relative to this skill's base directory.

Construct the full path from the "Base directory for this skill" shown at invocation, then run:

```bash
# Write checklist to temp file
printf '%s\n' "$PLAN_CHECKLIST" > /tmp/phase-plan-checklist.md

# SKILL_BASE_DIR should be set to the base directory from skill invocation header
# e.g., SKILL_BASE_DIR="/path/to/skills/plan-phase"
python3 ./scripts/update-issue-plans.py "$ISSUE_NUMBER" /tmp/phase-plan-checklist.md \
  && GITHUB_UPDATE_SUCCESS=true \
  || echo "Warning: Script failed, but continuing (non-blocking)"

# Clean up
rm -f /tmp/phase-plan-checklist.md
```

**Track result for display:**

Store `ISSUE_NUMBER` and `PLAN_COUNT` for display in `<offer_next>` if update succeeded.

**After GitHub check completes (success or skip), proceed to Step 14.**

**Error handling principle:** All GitHub operations are non-blocking. Missing issue, auth issues, or update failures warn but do not stop the planning workflow.

## 14. Present Final Status

Display the planning summary and route to `<offer_next>`.

</process>

<offer_next>
Output this markdown directly (not as a code block):

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
 Kata ► PHASE {X} PLANNED ✓
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

**Phase {X}: {Name}** — {N} plan(s) in {M} wave(s)

| Wave | Plans  | What it builds |
| ---- | ------ | -------------- |
| 1    | 01, 02 | [objectives]   |
| 2    | 03     | [objective]    |

Research: {Completed | Used existing | Skipped}
Verification: {Passed | Passed with override | Skipped}

{If GITHUB_UPDATE_SUCCESS=true:}
GitHub Issue: #{ISSUE_NUMBER} updated with {PLAN_COUNT} plan checklist items

───────────────────────────────────────────────────────────────

## ▶ Next Up

**Execute Phase {X}** — run all {N} plans

/kata-execute-phase {X}

<sub>/clear first → fresh context window</sub>

───────────────────────────────────────────────────────────────

**Also available:**
- cat .planning/phases/{phase-dir}/*-PLAN.md — review plans
- /kata-plan-phase {X} --research — re-research first
- /kata-brainstorm — brainstorm ideas before executing

───────────────────────────────────────────────────────────────
</offer_next>

<success_criteria>
- [ ] .planning/ directory validated
- [ ] Phase validated against roadmap
- [ ] Phase directory created if needed
- [ ] Research completed (unless --skip-research or --gaps or exists)
- [ ] kata-phase-researcher spawned if research needed
- [ ] Existing plans checked
- [ ] kata-planner spawned with context (including RESEARCH.md if available)
- [ ] Plans created (PLANNING COMPLETE or CHECKPOINT handled)
- [ ] kata-plan-checker spawned (unless --skip-verify)
- [ ] Verification passed OR user override OR max iterations with user decision
- [ ] GitHub issue updated with plan checklist (if github.enabled and issueMode != never)
- [ ] User sees status between agent spawns
- [ ] User knows next steps (execute or review)
</success_criteria>