undefined

Update Active requirements section with new goals.

Update "Last updated" footer.

undefined

Keep Accumulated Context section (decisions, blockers) from previous milestone.

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

HAS_GITHUB_REMOTE=$(git remote -v 2>/dev/null | grep -q 'github\.com' && echo "true" || echo "false")

gh repo create --source=. --private --push

gh repo create --source=. --public --push

Continuing without GitHub integration. Run `gh repo create` later to enable.

if ! gh auth status &>/dev/null; then
  echo "Warning: GitHub CLI not authenticated. Run 'gh auth login' to enable GitHub integration."
  # Continue without GitHub operations - local milestone still created
else
  # Proceed with milestone creation
fi

MILESTONE_EXISTS=$(gh api /repos/:owner/:repo/milestones 2>/dev/null | jq -r ".[] | select(.title==\"v${VERSION}\") | .number" 2>/dev/null)

if [ -z "$MILESTONE_EXISTS" ]; then
  # Extract milestone description (first paragraph of goal, truncated to 500 chars)
  MILESTONE_DESC=$(echo "$MILESTONE_GOALS" | head -1 | cut -c1-500)

  gh api \
    --method POST \
    -H "Accept: application/vnd.github.v3+json" \
    /repos/:owner/:repo/milestones \
    -f title="v${VERSION}" \
    -f state='open' \
    -f description="${MILESTONE_DESC}" \
    2>/dev/null && echo "GitHub Milestone v${VERSION} created" || echo "Warning: Failed to create GitHub Milestone (continuing)"
else
  echo "GitHub Milestone v${VERSION} already exists (#${MILESTONE_EXISTS})"
fi

COMMIT_PLANNING_DOCS=$(cat .planning/config.json 2>/dev/null | grep -o '"commit_docs"[[:space:]]*:[[:space:]]*[^,}]*' | grep -o 'true\|false' || echo "true")
git check-ignore -q .planning 2>/dev/null && COMMIT_PLANNING_DOCS=false

git add .planning/PROJECT.md .planning/STATE.md
git commit -m "docs: start milestone v[X.Y] [Name]"

MODEL_PROFILE=$(cat .planning/config.json 2>/dev/null | grep -o '"model_profile"[[:space:]]*:[[:space:]]*"[^"]*"' | grep -o '"[^"]*"$' | tr -d '"' || echo "balanced")

mkdir -p .planning/research

◆ Spawning 4 researchers in parallel...
  → Stack research (for new features)
  → Features research
  → Architecture research (integration)
  → Pitfalls research

project_researcher_instructions_content=$(cat ${SKILL_BASE_DIR}/references/project-researcher-instructions.md)
research_synthesizer_instructions_content=$(cat ${SKILL_BASE_DIR}/references/research-synthesizer-instructions.md)
roadmapper_instructions_content=$(cat ${SKILL_BASE_DIR}/references/roadmapper-instructions.md)

Task(prompt="
<agent-instructions>
{project_researcher_instructions_content}
</agent-instructions>

<research_type>
Project Research — Stack dimension for [new features].
</research_type>

<milestone_context>
SUBSEQUENT MILESTONE — Adding [target features] to existing app.

Existing validated capabilities (DO NOT re-research):
[List from PROJECT.md Validated requirements]

Focus ONLY on what's needed for the NEW features.
</milestone_context>

<question>
What stack additions/changes are needed for [new features]?
</question>

<project_context>
[PROJECT.md summary - current state, new milestone goals]
</project_context>

<downstream_consumer>
Your STACK.md feeds into roadmap creation. Be prescriptive:
- Specific libraries with versions for NEW capabilities
- Integration points with existing stack
- What NOT to add and why
</downstream_consumer>

<quality_gate>
- [ ] Versions are current (verify with Context7/official docs, not training data)
- [ ] Rationale explains WHY, not just WHAT
- [ ] Integration with existing stack considered
</quality_gate>

<output>
Write to: .planning/research/STACK.md
Format: Standard research output forSTACK.md
</output>
", subagent_type="general-purpose", model="{researcher_model}", description="Stack research")

Task(prompt="
<agent-instructions>
{project_researcher_instructions_content}
</agent-instructions>

<research_type>
Project Research — Features dimension for [new features].
</research_type>

<milestone_context>
SUBSEQUENT MILESTONE — Adding [target features] to existing app.

Existing features (already built):
[List from PROJECT.md Validated requirements]

Focus on how [new features] typically work, expected behavior.
</milestone_context>

<question>
How do [target features] typically work? What's expected behavior?
</question>

<project_context>
[PROJECT.md summary - new milestone goals]
</project_context>

<downstream_consumer>
Your FEATURES.md feeds into requirements definition. Categorize clearly:
- Table stakes (must have for these features)
- Differentiators (competitive advantage)
- Anti-features (things to deliberately NOT build)
</downstream_consumer>

<quality_gate>
- [ ] Categories are clear (table stakes vs differentiators vs anti-features)
- [ ] Complexity noted for each feature
- [ ] Dependencies on existing features identified
</quality_gate>

<output>
Write to: .planning/research/FEATURES.md
Format: Standard research output forFEATURES.md
</output>
", subagent_type="general-purpose", model="{researcher_model}", description="Features research")

Task(prompt="
<agent-instructions>
{project_researcher_instructions_content}
</agent-instructions>

<research_type>
Project Research — Architecture dimension for [new features].
</research_type>

<milestone_context>
SUBSEQUENT MILESTONE — Adding [target features] to existing app.

Existing architecture:
[Summary from PROJECT.md or codebase map]

Focus on how [new features] integrate with existing architecture.
</milestone_context>

<question>
How do [target features] integrate with existing [domain] architecture?
</question>

<project_context>
[PROJECT.md summary - current architecture, new features]
</project_context>

<downstream_consumer>
Your ARCHITECTURE.md informs phase structure in roadmap. Include:
- Integration points with existing components
- New components needed
- Data flow changes
- Suggested build order
</downstream_consumer>

<quality_gate>
- [ ] Integration points clearly identified
- [ ] New vs modified components explicit
- [ ] Build order considers existing dependencies
</quality_gate>

<output>
Write to: .planning/research/ARCHITECTURE.md
Format: Standard research output forARCHITECTURE.md
</output>
", subagent_type="general-purpose", model="{researcher_model}", description="Architecture research")

Task(prompt="
<agent-instructions>
{project_researcher_instructions_content}
</agent-instructions>

<research_type>
Project Research — Pitfalls dimension for [new features].
</research_type>

<milestone_context>
SUBSEQUENT MILESTONE — Adding [target features] to existing app.

Focus on common mistakes when ADDING these features to an existing system.
</milestone_context>

<question>
What are common mistakes when adding [target features] to [domain]?
</question>

<project_context>
[PROJECT.md summary - current state, new features]
</project_context>

<downstream_consumer>
Your PITFALLS.md prevents mistakes in roadmap/planning. For each pitfall:
- Warning signs (how to detect early)
- Prevention strategy (how to avoid)
- Which phase should address it
</downstream_consumer>

<quality_gate>
- [ ] Pitfalls are specific to adding these features (not generic)
- [ ] Integration pitfalls with existing system covered
- [ ] Prevention strategies are actionable
</quality_gate>

<output>
Write to: .planning/research/PITFALLS.md
Format: Standard research output forPITFALLS.md
</output>
", subagent_type="general-purpose", model="{researcher_model}", description="Pitfalls research")

Task(prompt="
<agent-instructions>
{research_synthesizer_instructions_content}
</agent-instructions>

<task>
Synthesize research outputs into SUMMARY.md.
</task>

<research_files>
Read these files:
- .planning/research/STACK.md
- .planning/research/FEATURES.md
- .planning/research/ARCHITECTURE.md
- .planning/research/PITFALLS.md
</research_files>

<output>
Write to: .planning/research/SUMMARY.md
Format: Standard research output forSUMMARY.md
Commit after writing.
</output>
", subagent_type="general-purpose", model="{synthesizer_model}", description="Synthesize research")

BACKLOG_COUNT=$(find .planning/issues/open -maxdepth 1 -name "*.md" 2>/dev/null | wc -l | tr -d ' ')

ISSUE_OPTIONS=""
for file in .planning/issues/open/*.md; do
  [ -f "$file" ] || continue
  created=$(grep "^created:" "$file" | cut -d' ' -f2)
  title=$(grep "^title:" "$file" | cut -d':' -f2- | xargs)
  area=$(grep "^area:" "$file" | cut -d' ' -f2)
  provenance=$(grep "^provenance:" "$file" | cut -d' ' -f2)

  # Calculate age
  created_date=$(echo "$created" | cut -dT -f1)
  days_ago=$(( ($(date +%s) - $(date -j -f "%Y-%m-%d" "$created_date" +%s 2>/dev/null || echo $(date +%s))) / 86400 ))
  if [ "$days_ago" -eq 0 ]; then
    age="today"
  elif [ "$days_ago" -eq 1 ]; then
    age="1d ago"
  else
    age="${days_ago}d ago"
  fi

  # Extract GitHub issue number if linked
  github_ref=""
  if echo "$provenance" | grep -q "^github:"; then
    github_ref=" (GitHub $(echo "$provenance" | grep -oE '#[0-9]+')"
  fi

  echo "$file|$title|$area|$age$github_ref"
done

undefined

4. Write updated STATE.md

**Purpose of issue selection:**
- Selected issues become formally tracked as part of the milestone scope
- They appear in STATE.md under "### Milestone Scope Issues" for the current milestone
- They inform requirements generation in Phase 8 (planner should consider these issues when generating requirements)
- They will be visible in progress tracking commands like /kata-track-progress
- User still defines formal requirements through Phase 8, but selected issues provide explicit scope context

**If BACKLOG_COUNT = 0:**

Skip silently. Continue to Phase 8.

Here are the features for [new capabilities]:

**If no research:** Gather requirements through conversation instead.

Ask: "What are the main things users need to be able to do with [new features]?"

For each capability mentioned:
- Ask clarifying questions to make it specific
- Probe for related capabilities
- Group into categories

**Scope each category:**

For each category, use AskUserQuestion:

- header: "[Category name]"
- question: "Which [category] features are in this milestone?"
- multiSelect: true
- options:
  - "[Feature 1]" — [brief description]
  - "[Feature 2]" — [brief description]
  - "[Feature 3]" — [brief description]
  - "None for this milestone" — Defer entire category

Track responses:
- Selected features → this milestone's requirements
- Unselected table stakes → future milestone
- Unselected differentiators → out of scope

**Identify gaps:**

Use AskUserQuestion:
- header: "Additions"
- question: "Any requirements research missed? (Features specific to your vision)"
- options:
  - "No, research covered it" — Proceed
  - "Yes, let me add some" — Capture additions

**Generate REQUIREMENTS.md:**

Create `.planning/REQUIREMENTS.md` with:
- v1 Requirements for THIS milestone grouped by category (checkboxes, REQ-IDs)
- Future Requirements (deferred to later milestones)
- Out of Scope (explicit exclusions with reasoning)
- Traceability section (empty, filled by roadmap)

**REQ-ID format:** `[CATEGORY]-[NUMBER]` (AUTH-01, NOTIF-02)

Continue numbering from existing requirements if applicable.

**Requirement quality criteria:**

Good requirements are:
- **Specific and testable:** "User can reset password via email link" (not "Handle password reset")
- **User-centric:** "User can X" (not "System does Y")
- **Atomic:** One capability per requirement (not "User can login and manage profile")
- **Independent:** Minimal dependencies on other requirements

**Present full requirements list:**

Show every requirement (not counts) for user confirmation:

If "adjust": Return to scoping.

**Commit requirements:**

Check planning config (same pattern as Phase 6).

If committing:
```bash
git add .planning/REQUIREMENTS.md
git commit -m "$(cat <<'EOF'
docs: define milestone v[X.Y] requirements

[X] requirements across [N] categories
EOF
)"

DUPES=$(for state in active pending completed; do
  ls .planning/phases/${state}/ 2>/dev/null
done | grep -oE '^[0-9]+' | sort -n | uniq -d)

**If `ALL_DUPES` is empty:** Continue silently to Phase 9.

**If collisions found:**

Display:

Use AskUserQuestion:
- header: "Collisions"
- question: "Duplicate phase prefixes found. Migrate to globally sequential numbering?"
- options:
  - "Migrate now" — Run inline migration, then recalculate NEXT_PHASE before continuing
  - "Skip" — Continue without fixing (phase lookups may return wrong results)

**If "Migrate now":**

Run the migration logic from `/kata-migrate-phases` inline:
1. Build chronology from ROADMAP.md (completed milestone `<details>` blocks + current milestone phases)
2. Map directories to globally sequential numbers
3. Execute two-pass rename (tmp- prefix, then final)
4. Update ROADMAP.md current milestone phase numbers
5. Recalculate `NEXT_PHASE` from the newly renumbered directories

**If "Skip":**

Display:

Continue to Phase 9.

ALL_PHASE_DIRS=""
for state in active pending completed; do
  [ -d ".planning/phases/${state}" ] && ALL_PHASE_DIRS="${ALL_PHASE_DIRS} $(find .planning/phases/${state} -maxdepth 1 -type d -not -name "${state}" 2>/dev/null)"
done
HIGHEST=$(echo "$ALL_PHASE_DIRS" | tr ' ' '\n' | grep -oE '/[0-9]+' | grep -oE '[0-9]+' | sort -n | tail -1)
NEXT_PHASE=$((HIGHEST + 1))

Task(prompt="
<agent-instructions>
{roadmapper_instructions_content}
</agent-instructions>

<planning_context>

**Project:**
@.planning/PROJECT.md

**Requirements:**
@.planning/REQUIREMENTS.md

**Research (if exists):**
@.planning/research/SUMMARY.md

**Config:**
@.planning/config.json

**Previous milestones (shipped context):**
@.planning/MILESTONES.md

</planning_context>

<instructions>
Create roadmap for milestone v[X.Y]:
1. Continue phase numbering from the highest existing phase number + 1 (globally sequential across milestones). The starting phase number is provided as NEXT_PHASE.
2. Derive phases from THIS MILESTONE's requirements (don't include validated/existing)
3. Map every requirement to exactly one phase
4. Derive 2-5 success criteria per phase (observable user behaviors)
5. Validate 100% coverage of new requirements
6. Write files immediately (ROADMAP.md, STATE.md, update REQUIREMENTS.md traceability)
7. Include "Planned Milestones" section in ROADMAP.md if user mentioned future milestone ideas
8. Use ○ symbol for planned milestones in overview, 🔄 for current, ✅ for completed
9. Include planned milestones in Progress Summary table with "Planned" status
10. Return ROADMAP CREATED with summary

Write files first, then return. This ensures artifacts persist even if context is lost.
</instructions>

<format_conventions>
Milestones overview uses these symbols:
- ✅ for shipped milestones
- 🔄 for current/in-progress milestone
- ○ for planned milestones

Completed milestone details blocks MUST include:
- Summary line: ✅ v[X.Y] [Name] — SHIPPED [DATE]
- **Goal:** line
- Phase checkboxes with plan counts and dates
- [Full archive](milestones/v[X.Y]-ROADMAP.md) link

Progress Summary table includes planned milestones with "Planned" status and "—" for metrics.
</format_conventions>
", subagent_type="general-purpose", model="{roadmapper_model}", description="Create roadmap")

---

**CRITICAL: Ask for approval before committing:**

Use AskUserQuestion:
- header: "Roadmap"
- question: "Does this roadmap structure work for you?"
- options:
  - "Approve" — Commit and continue
  - "Adjust phases" — Tell me what to change
  - "Review full file" — Show raw ROADMAP.md

**If "Approve":** Continue to commit.

**If "Adjust phases":**
- Get user's adjustment notes
- Re-spawn roadmapper with revision context:

- Present revised roadmap
- Loop until user approves

**If "Review full file":** Display raw `cat .planning/ROADMAP.md`, then re-ask.

**Commit roadmap (after approval):**

Check planning config (same pattern as Phase 6).

If committing:
```bash
git add .planning/ROADMAP.md .planning/STATE.md .planning/REQUIREMENTS.md
git commit -m "$(cat <<'EOF'
docs: create milestone v[X.Y] roadmap ([N] phases)

Phases:
[N]. [phase-name]: [requirements covered]
[N+1]. [phase-name]: [requirements covered]
...

All milestone requirements mapped to phases.
EOF
)"

ISSUE_MODE=$(cat .planning/config.json 2>/dev/null | grep -o '"issueMode"[[:space:]]*:[[:space:]]*"[^"]*"' | grep -o '"[^"]*"$' | tr -d '"' || echo "auto")

gh label create "phase" --color "0E8A16" --description "Kata phase tracking" --force 2>/dev/null || true

undefined

**5. Parse phases from ROADMAP.md** (for this milestone only):

The ROADMAP.md structure uses:
- Milestone headers: `### v1.1.0 GitHub Integration (Planned)` or `### v{VERSION} {Name} (Status)`
- Phase headers: `#### Phase N: Phase Name`
- Goal line: `**Goal**: description text`
- Requirements line: `**Requirements**: REQ-01, REQ-02` (optional)
- Success criteria: `**Success Criteria** (what must be TRUE):` followed by numbered list

```bash

# Create issue
gh issue create \
  --title "Phase ${PHASE_NUM}: ${PHASE_NAME}" \
  --body-file /tmp/phase-issue-body.md \
  --label "phase" \
  --milestone "v${VERSION}" \
  2>/dev/null && echo "Created issue: Phase ${PHASE_NUM}: ${PHASE_NAME}" || echo "Warning: Failed to create issue for Phase ${PHASE_NUM}"

**6. Display summary** (after loop):

**Error handling principle:** All operations are non-blocking. Missing milestone, auth issues, or creation failures warn but do not stop the milestone flow.

**IMPORTANT:** Use temp file approach (--body-file) to handle special characters in phase goals. Direct --body strings break with quotes/backticks.