Add a milestone to an existing project, starting a new milestone cycle, creating the first milestone after project init, or defining what's next after completing work. Triggers include "add milestone", "new milestone", "start milestone", "create milestone", "first milestone", "next milestone", and "milestone cycle".
Add a milestone to an existing project, starting a new milestone cycle, creating the first milestone after project init, or defining what's next after completing work. Triggers include "add milestone", "new milestone", "start milestone", "create milestone", "first milestone", "next milestone", and "milestone cycle".
metadata
{"version":"0.1.0"}
Add a milestone to the project through unified flow: questioning → research (optional) → requirements → roadmap.
This works for both first milestone (after /kata-new-project) and subsequent milestones (after completing a milestone).
Creates/Updates:
.planning/PROJECT.md — updated with new milestone goals
.planning/research/ — domain research (optional, focuses on NEW features)
.planning/REQUIREMENTS.md — scoped requirements for this milestone
.planning/ROADMAP.md — phase structure (creates if first, continues if subsequent)
.planning/STATE.md — reset for new milestone (creates if first)
After this command: Run /kata-plan-phase [N] to start execution.
"Yes, create public repo" — Create public repository and push
"Skip for now" — Continue without GitHub integration
If "Yes, create private repo":
gh repo create --source=. --private --push
If successful, set HAS_GITHUB_REMOTE=true and continue to Step 2 (Check authentication).
If "Yes, create public repo":
gh repo create --source=. --public --push
If successful, set HAS_GITHUB_REMOTE=true and continue to Step 2 (Check authentication).
If "Skip for now":
Display brief note and continue with local milestone initialization:
Continuing without GitHub integration. Run `gh repo create` later to enable.
Do NOT set github.enabled=false in config - user may add remote later.
If HAS_GITHUB_REMOTE=true:
Step 2: Check authentication (non-blocking)
if ! gh auth status &>/dev/null; thenecho"Warning: GitHub CLI not authenticated. Run 'gh auth login' to enable GitHub integration."# Continue without GitHub operations - local milestone still createdelse# Proceed with milestone creationfi
Store resolved models for use in Task calls below.
Phase 7: Research Decision
Use AskUserQuestion:
header: "Research"
question: "Research the domain ecosystem for new features before defining requirements?"
options:
"Research first (Recommended)" — Discover patterns, expected features, architecture for NEW capabilities
"Skip research" — I know what I need, go straight to requirements
If "Research first":
Display stage banner:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Kata ► RESEARCHING
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Researching [new features] ecosystem...
Create research directory:
mkdir -p .planning/research
Display spawning indicator:
◆ Spawning 4 researchers in parallel...
→ Stack research (for new features)
→ Features research
→ Architecture research (integration)
→ Pitfalls research
Read agent instruction files for inlining into Task() prompts:
Spawn all 4 researchers in a single message containing 4 parallel Task tool calls. All 4 must be in the same response — do NOT wait for one to finish before spawning the next:
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")
After all 4 agents complete, spawn synthesizer to create SUMMARY.md:
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")
Display research complete banner and key findings:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Kata ► RESEARCH COMPLETE ✓
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Key Findings
Stack additions: [from SUMMARY.md]
New feature table stakes: [from SUMMARY.md]
Watch Out For: [from SUMMARY.md]
question: "Include any backlog issues in this milestone's scope?"
multiSelect: true
options: Build from issue list above, format as "[title]" — [area], [age]
Include final option: "None — Start fresh"
For each selected issue (if not "None — Start fresh"):
Store as SELECTED_ISSUES variable for use in Phase 8.
Update STATE.md with milestone scope issues:
Read STATE.md
Find or create "### Milestone Scope Issues" section
Add each selected issue:
### Milestone Scope Issues
Issues pulled into current milestone scope:
- "[issue-title]" (from: [issue-file-path], GitHub: #N if linked)
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.
Phase 8: Define Requirements
Display stage banner:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Kata ► DEFINING REQUIREMENTS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Load context:
Read PROJECT.md and extract:
Core value (the ONE thing that must work)
Current milestone goals
Validated requirements (what already exists)
If research exists: Read research/FEATURES.md and extract feature categories.
Present features by category:
Here are the features for [new capabilities]:
## [Category 1]
**Table stakes:**
- Feature A
- Feature B
**Differentiators:**
- Feature C
- Feature D
**Research notes:** [any relevant notes]
---
## [Next Category]
...
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)
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:
## Milestone v[X.Y] Requirements
### [Category 1]
- [ ] **CAT1-01**: User can do X
- [ ] **CAT1-02**: User can do Y
### [Category 2]
- [ ] **CAT2-01**: User can do Z
[... full list ...]
---
Does this capture what you're building? (yes / adjust)
If ALL_DUPES is empty: Continue silently to Phase 9.
If collisions found:
Display:
⚠ Duplicate phase prefixes detected: [list]
Phase directories share numeric prefixes across milestones. This causes
phase lookup commands to return wrong directories.
Use AskUserQuestion:
header: "Collisions"
question: "Duplicate phase prefixes found. Migrate to globally sequential numbering?"
options:
"Migrate now" — Run /kata-doctor to fix collisions, then recalculate NEXT_PHASE before continuing
"Skip" — Continue without fixing (phase lookups may return wrong results)
If "Migrate now":
Run /kata-doctor to perform migration:
Skill("kata-doctor")
After doctor completes, recalculate NEXT_PHASE from the newly renumbered directories.
If "Skip":
Display:
⚠ Skipping migration. Run `/kata-doctor` to fix collisions later.
Continue to Phase 9.
Phase 9: Create Roadmap
Display stage banner:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Kata ► CREATING ROADMAP
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
◆ Spawning roadmapper...
Determine starting phase number:
Phase numbers are globally sequential across milestones. Scan all existing phase directories to find the highest phase number, then start this milestone's phases at highest + 1:
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))
Pass NEXT_PHASE as the starting phase number to the roadmapper.
Spawn roadmapper agent with context:
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")
Handle roadmapper return:
If ## ROADMAP BLOCKED:
Present blocker information
Work with user to resolve
Re-spawn when resolved
If ## ROADMAP CREATED:
Read the created ROADMAP.md and present it nicely inline:
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:
Task(prompt="
<agent-instructions>
{roadmapper_instructions_content}
</agent-instructions>
<revision>
User feedback on roadmap:
[user's notes]
Current ROADMAP.md: @.planning/ROADMAP.md
Update the roadmap based on feedback. Edit files in place.
Return ROADMAP REVISED with changes made.
</revision>
", subagent_type="general-purpose", model="{roadmapper_model}", description="Revise roadmap")
Present revised roadmap
Loop until user approves
If "Review full file": Display raw cat .planning/ROADMAP.md, then re-ask.
# Extract VERSION from current milestone
VERSION=$(grep -E "Current Milestone:|🔄" .planning/ROADMAP.md | grep -oE 'v[0-9]+\.[0-9]+(\.[0-9]+)?' | head -1 | tr -d 'v')
if [ -z "$VERSION" ]; thenecho"Warning: Could not determine milestone version from ROADMAP.md. Skipping phase issue creation."exit 0
fi
MILESTONE_NUM=$(gh api /repos/:owner/:repo/milestones --jq ".[] | select(.title==\"v${VERSION}\") | .number" 2>/dev/null)
if [ -z "$MILESTONE_NUM" ]; thenecho"Warning: Could not find GitHub Milestone v${VERSION}. Skipping phase issue creation."# Continue without phase issues - skip to Phase 10fi
5. Parse phases from ROADMAP.md (for this milestone only):
Success criteria: **Success Criteria** (what must be TRUE): followed by numbered list
# Find the milestone section and extract phases
ROADMAP_FILE=".planning/ROADMAP.md"# Extract VERSION from current milestone
VERSION=$(grep -E "Current Milestone:|🔄""$ROADMAP_FILE" | grep -oE 'v[0-9]+\.[0-9]+(\.[0-9]+)?' | head -1 | tr -d 'v')
if [ -z "$VERSION" ]; thenecho"Warning: Could not determine milestone version. Skipping phase issue creation."exit 0
fi# Get line numbers for milestone section boundaries
MILESTONE_START=$(grep -n "^### v${VERSION}""$ROADMAP_FILE" | head -1 | cut -d: -f1)
NEXT_MILESTONE=$(awk -v start="$MILESTONE_START"'NR > start && /^### v[0-9]/ {print NR; exit}'"$ROADMAP_FILE")
# If no next milestone, use end of fileif [ -z "$NEXT_MILESTONE" ]; then
NEXT_MILESTONE=$(wc -l < "$ROADMAP_FILE")
fi# Extract phase blocks within this milestone section# Each phase starts with "### Phase N:" or "#### Phase N:" and ends at next phase or section boundary
PHASE_HEADERS=$(sed -n "${MILESTONE_START},${NEXT_MILESTONE}p""$ROADMAP_FILE" | grep -nE "^#{3,4} Phase [0-9]")
# Process each phaseecho"$PHASE_HEADERS" | while IFS= read -r phase_line; do# Extract phase number and name from "#### Phase N: Name"
PHASE_NUM=$(echo"$phase_line" | sed -E 's/.*Phase ([0-9.]+):.*/\1/')
PHASE_NAME=$(echo"$phase_line" | sed -E 's/.*Phase [0-9.]+: (.*)/\1/')
# Get relative line number within milestone section
PHASE_REL_LINE=$(echo"$phase_line" | cut -d: -f1)
PHASE_ABS_LINE=$((MILESTONE_START + PHASE_REL_LINE - 1))
# Find next phase or section end
NEXT_PHASE_LINE=$(sed -n "$((PHASE_ABS_LINE+1)),${NEXT_MILESTONE}p""$ROADMAP_FILE" | grep -nE "^#{2,4} (Phase |v[0-9])" | head -1 | cut -d: -f1)
if [ -z "$NEXT_PHASE_LINE" ]; then
PHASE_END=$NEXT_MILESTONEelse
PHASE_END=$((PHASE_ABS_LINE + NEXT_PHASE_LINE - 1))
fi# Extract phase block
PHASE_BLOCK=$(sed -n "${PHASE_ABS_LINE},${PHASE_END}p""$ROADMAP_FILE")
# Extract goal (line starting with **Goal**:)
PHASE_GOAL=$(echo"$PHASE_BLOCK" | grep "^\*\*Goal\*\*:" | sed 's/\*\*Goal\*\*: *//')
# Extract requirements (line starting with **Requirements**:) - may not exist
REQUIREMENT_IDS=$(echo"$PHASE_BLOCK" | grep "^\*\*Requirements\*\*:" | sed 's/\*\*Requirements\*\*: *//')
# Extract success criteria (numbered list after **Success Criteria**)# Convert to checklist format: " 1. item" -> "- [ ] item"
SUCCESS_CRITERIA_AS_CHECKLIST=$(echo"$PHASE_BLOCK" | \
awk '/^\*\*Success Criteria\*\*/{found=1; next} found && /^ [0-9]+\./{print} found && /^\*\*/{exit}' | \
sed -E 's/^ [0-9]+\. /- [ ] /')
# --- Issue creation code (step 6) ---# Check if issue already exists (idempotent)# 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)
EXISTING=""if [ -n "$MS_NUM" ]; then
EXISTING=$(gh api "repos/${REPO_SLUG}/issues?milestone=${MS_NUM}&state=all&labels=phase&per_page=100" \
--jq "[.[] | select(.title | startswith(\"Phase ${PHASE_NUM}:\"))][0].number" 2>/dev/null)
fiif [ -n "$EXISTING" ]; thenecho"Phase ${PHASE_NUM} issue already exists: #${EXISTING}"else# Build issue body using temp file (handles special characters safely)cat > /tmp/phase-issue-body.md << PHASE_EOF
## Goal
${PHASE_GOAL}
## Success Criteria
${SUCCESS_CRITERIA_AS_CHECKLIST}
$([ -n "$REQUIREMENT_IDS" ] && echo "
## Requirements
${REQUIREMENT_IDS}")
## Plans
<!-- Checklist added by /kata-plan-phase (Phase 4) -->
_Plans will be added after phase planning completes._
---
<sub>Created by Kata | Phase ${PHASE_NUM} of milestone v${VERSION}</sub>
PHASE_EOF# 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}"fidone
6. Display summary (after loop):
◆ GitHub Phase Issues: [N] created for milestone v${VERSION}
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.
Phase 10: Done
Present completion with next steps:
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
Kata ► MILESTONE INITIALIZED ✓
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
