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

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

1. Read slicing principles:

   cat "$(dirname "$0")/references/slicing-principles.md"
   

2. Check phase description against red flags:

   Red Flag 1: Horizontal layer name

   • Does description mention "models", "APIs", "components", "frontend", "backend", "database" without feature context?
   • Examples: "Add database models", "Create API layer", "Build UI components"

   Red Flag 2: Setup-only phase

   • Is this pure infrastructure with no user-facing feature?
   • Examples: "Set up database", "Configure API", "Initialize framework"

   Red Flag 3: Continuation of previous phase

   • Does description suggest incomplete work from prior phase?
   • Examples: "Finish authentication", "Complete product catalog", "Add remaining endpoints"

3. If red flag detected, use AskUserQuestion:

   The phase description "{description}" may not follow vertical slicing principles.
   
   **Detected issue:** {red flag type}
   
   **Vertical slicing principle:** Each phase should deliver a complete, demo-able feature (DB + API + UI) rather than a horizontal layer or infrastructure setup.
   
   **Alternative structures:**
   
   Option 1: Feature-focused phase
   - Description: "{suggest feature-focused alternative}"
   - Structure: Complete capability from DB to UI
   - Demo-able: {what can be demonstrated}
   
   Option 2: Inline setup with feature
   - Description: "{suggest inlined alternative}"
   - Structure: Setup combined with first feature using it
   - Demo-able: {what can be demonstrated}
   
   Option 3: Proceed as-is
   - Use current description
   - Note: May result in non-demo-able phase
   

4. If no red flags, continue silently.

Purpose: Prevent horizontal layer phases and setup-only phases from entering the roadmap. Catch slicing issues at insertion time, not during planning.

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>