Kata Plan Phase

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.

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=$(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:

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-migrate-phases 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 "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:

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:

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)
• 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

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}

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

</planning_context>

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

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

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:

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:

# Get milestone version from ROADMAP.md (the one marked "In Progress")
VERSION=$(grep -E "^### v[0-9]+\.[0-9]+.*\(In Progress\)" .planning/ROADMAP.md | grep -oE "v[0-9]+\.[0-9]+(\.[0-9]+)?" | head -1 | tr -d 'v' || echo "")
# Fallback: try to find any version if no "In Progress" found
[ -z "$VERSION" ] && VERSION=$(grep -oE 'v[0-9]+\.[0-9]+(\.[0-9]+)?' .planning/ROADMAP.md | 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
ISSUE_NUMBER=$(gh issue list \
  --label "phase" \
  --milestone "v${VERSION}" \
  --json number,title \
  --jq ".[] | select(.title | startswith(\"Phase ${PHASE}:\")) | .number" \
  2>/dev/null)

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 "${SKILL_BASE_DIR}/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>.

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

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

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

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