kata-add-phase

This command appends sequential phases to the current milestone’s phase list, automatically calculating the next phase number based on existing phases.

Purpose: Add planned work discovered during execution that belongs at the end of current milestone.

IMPORTANT: When showing examples to users, always use /kata-add-phase (the command), not the skill name.

<execution_context> @.planning/ROADMAP.md @.planning/STATE.md </execution_context>

With --issue flag:

• /kata-add-phase --issue .planning/issues/open/2026-02-06-phase-lookup.md
• Read the issue file to extract title, provenance, and context
• description = issue title from frontmatter
• ISSUE_FILE = the path argument
• ISSUE_PROVENANCE = provenance field from frontmatter (e.g., github:owner/repo#102)
• ISSUE_NUMBER = extracted from provenance if GitHub-linked (e.g., 102)

if echo "$ARGUMENTS" | grep -q "^--issue "; then
  ISSUE_FILE=$(echo "$ARGUMENTS" | sed 's/^--issue //')
  if [ ! -f "$ISSUE_FILE" ]; then
    echo "ERROR: Issue file not found: $ISSUE_FILE"
    exit 1
  fi
  description=$(grep "^title:" "$ISSUE_FILE" | cut -d':' -f2- | xargs)
  ISSUE_PROVENANCE=$(grep "^provenance:" "$ISSUE_FILE" | cut -d' ' -f2)
  ISSUE_NUMBER=""
  if echo "$ISSUE_PROVENANCE" | grep -q "^github:"; then
    ISSUE_NUMBER=$(echo "$ISSUE_PROVENANCE" | grep -oE '#[0-9]+' | tr -d '#')
  fi
fi

Without --issue flag:

• All arguments become the phase description
• Example: /kata-add-phase Add authentication → description = “Add authentication”
• ISSUE_FILE, ISSUE_PROVENANCE, ISSUE_NUMBER are empty

If no arguments provided:

ERROR: Phase description required
Usage: /kata-add-phase <description>
       /kata-add-phase --issue <issue-file-path>
Example: /kata-add-phase Add authentication system

Exit.

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

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.

if [ -f .planning/ROADMAP.md ]; then
  ROADMAP=".planning/ROADMAP.md"
else
  echo "ERROR: No roadmap found (.planning/ROADMAP.md)"
  exit 1
fi

Read roadmap content for parsing.

1. Locate the “## Current Milestone:” heading
2. Extract milestone name and version
3. Identify all phases under this milestone (before next “—” separator or next milestone heading)
4. Parse existing phase numbers (including decimals if present)

Example structure:

## Current Milestone: v1.0 Foundation

### Phase 4: Focused Command System
### Phase 5: Path Routing & Validation
### Phase 6: Documentation & Distribution

1. Extract all phase numbers from phase headings (### Phase N:)
2. Filter to integer phases only (ignore decimals like 4.1, 4.2)
3. Find the maximum integer value
4. Add 1 to get the next phase number

Example: If phases are 4, 5, 5.1, 6 → next is 7

Format as two-digit: printf "%02d" $next_phase

# Example transformation:
# "Add authentication" → "add-authentication"
# "Fix critical performance issues" → "fix-critical-performance-issues"

slug=$(echo "$description" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g' | sed 's/--*/-/g' | sed 's/^-//;s/-$//')

Phase directory name: {two-digit-phase}-{slug} Example: 07-add-authentication

phase_dir=".planning/phases/pending/${phase_num}-${slug}"
mkdir -p "$phase_dir"

Confirm: “Created directory: $phase_dir”

1. Find the insertion point (after last phase in current milestone, before “—” separator)

2. Insert new phase heading:

   ### Phase {N}: {Description}
   
   **Goal:** [To be planned]
   **Depends on:** Phase {N-1}
   {if ISSUE_NUMBER: **Issue:** Closes #{ISSUE_NUMBER}}
   **Plans:** 0 plans
   
   Plans:
   - [ ] TBD (run /kata-plan-phase {N} to break down)
   
   **Details:**
   [To be added during planning]
   

   If ISSUE_NUMBER is set (from --issue flag), include the **Issue:** Closes #{N} line. This ensures PRs referencing this phase will auto-close the GitHub issue.

3. Write updated roadmap back to file

Preserve all other content exactly (formatting, spacing, other phases).

1. Read .planning/STATE.md
2. Under “## Current Position” → “Next Phase:” add reference to new phase
3. Under “## Accumulated Context” → “### Roadmap Evolution” add entry:

   - Phase {N} added: {description}
   

If “Roadmap Evolution” section doesn’t exist, create it.

Phase {N} added to current milestone:
- Description: {description}
- Directory: .planning/phases/{phase-num}-{slug}/
- Status: Not planned yet
{if ISSUE_NUMBER: - Issue: Closes #${ISSUE_NUMBER} (linked from ${ISSUE_FILE})}

Roadmap updated: {roadmap-path}
Project state updated: .planning/STATE.md

---

## ▶ Next Up

**Phase {N}: {description}**

`/kata-plan-phase {N}`

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

---

**Also available:**
- `/kata-add-phase <description>` — add another phase
- Review roadmap

---

<anti_patterns>

• Don’t modify phases outside current milestone
• Don’t renumber existing phases
• Don’t use decimal numbering (that’s /kata-insert-phase)
• Don’t create plans yet (that’s /kata-plan-phase)
• Don’t commit changes (user decides when to commit) </anti_patterns>

<success_criteria> Phase addition is complete when:

• Phase directory created: .planning/phases/pending/{NN}-{slug}/
• Roadmap updated with new phase entry
• STATE.md updated with roadmap evolution note
• New phase appears at end of current milestone
• Next phase number calculated correctly (ignoring decimals)
• User informed of next steps </success_criteria>