kata-plan-phase by gannonh/kata-skills

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

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.

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.

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

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

if [ -f .planning/ROADMAP.md ]; then
  node scripts/kata-lib.cjs check-roadmap 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.

# Validate config and template overrides
node scripts/kata-lib.cjs check-config 2>/dev/null || true
node scripts/kata-lib.cjs check-template-drift 2>/dev/null || true

1. Validate Environment and Resolve Model Profile

ls .planning/ 2>/dev/null

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

Resolve model profile for agent spawning:

MODEL_PROFILE=$(node scripts/kata-lib.cjs read-config "model_profile" "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:

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

# 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.

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

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
# 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 -E "^#{3,4} Phase ${PHASE}:" .planning/ROADMAP.md | head -1 | sed 's/.*Phase [0-9]*: //' | sed 's/ *(.*//' | tr '[:upper:]' '[:lower:]' | tr ' ' '-' | tr -cd 'a-z0-9-')
  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:

WORKFLOW_RESEARCH=$(node scripts/kata-lib.cjs read-config "workflow.research" "true")

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

Otherwise:

Check for existing research:

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:

# 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="<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

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)
.planning/intel/summary.md (if exists) — store as intel_summary_content
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):

PLAN_TEMPLATE_PATH=$(node scripts/kata-lib.cjs resolve-template "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):

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:

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

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:

<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}

**Codebase Intelligence (if exists):**
{intel_summary_content}

**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=$(node scripts/kata-lib.cjs read-config "workflow.plan_check" "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:

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

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

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

Spawn kata-planner with revision prompt:

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

Force proceed (execute despite issues)
Provide guidance (user gives direction, retry)
Abandon (exit planning)

Wait for user response.

13. GitHub Integration Check

Check config guards:

GITHUB_ENABLED=$(node scripts/kata-lib.cjs read-config "github.enabled" "false")
ISSUE_MODE=$(node scripts/kata-lib.cjs read-config "github.issue_mode" "never")

If GITHUB_ENABLED != true OR ISSUE_MODE = never:

Log: Skipping GitHub issue update (github.enabled=${GITHUB_ENABLED}, issue_mode=${ISSUE_MODE})
Skip to <offer_next>

If enabled, find phase issue:

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

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:

# 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>.

<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}

/clear first → fresh context window

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

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>