Completing Milestones

/kata:complete-milestone

Purpose: Create historical record of shipped version, archive milestone artifacts (roadmap + requirements), and prepare for next milestone. Output: Milestone archived (roadmap + requirements), PROJECT.md evolved, git tagged.

• @./references/milestone-complete.md (main workflow)
• @./references/milestone-archive-template.md (archive template)

User input:

• Version: {{version}} (e.g., "1.0", "1.1", "2.0")

Follow milestone-complete.md workflow:

0. Pre-flight: Release artifacts

   Before archiving, ensure release artifacts are ready:

   ## Pre-flight: Release Artifacts
   
   ☐ CHANGELOG.md updated with v{{version}} entry
   ☐ package.json version set to {{version}}
   
   These should be committed BEFORE running this command.
   

   If either is missing, prompt:

   ⚠ Release artifacts not ready. Please update:
   - CHANGELOG.md — add v{{version}} entry
   - package.json — set version to {{version}}
   
   Then re-run /kata:complete-milestone
   

   Use AskUserQuestion:

   • header: "Release artifacts"
   • question: "Have you updated CHANGELOG.md and package.json for v{{version}}?"
   • options:
     • "Yes, continue" — Proceed with completion
     • "No, let me update them" — Exit to update

   If "No", exit command.

1. Check for audit:

   • Look for .planning/v{{version}}-MILESTONE-AUDIT.md
   • If missing or stale: recommend /kata:audit-milestone first
   • If audit status is gaps_found: recommend /kata:plan-milestone-gaps first
   • If audit status is passed: proceed to step 1

   ## Pre-flight Check
   
   {If no v{{version}}-MILESTONE-AUDIT.md:}
   ⚠ No milestone audit found. Run `/kata:audit-milestone` first to verify
   requirements coverage, cross-phase integration, and E2E flows.
   
   {If audit has gaps:}
   ⚠ Milestone audit found gaps. Run `/kata:plan-milestone-gaps` to create
   phases that close the gaps, or proceed anyway to accept as tech debt.
   
   {If audit passed:}
   ✓ Milestone audit passed. Proceeding with completion.
   

2. Verify readiness:

   • Check all phases in milestone have completed plans (SUMMARY.md exists)
   • Present milestone scope and stats
   • Wait for confirmation

3. Gather stats:

   • Count phases, plans, tasks
   • Calculate git range, file changes, LOC
   • Extract timeline from git log
   • Present summary, confirm

4. Extract accomplishments:

   • Read all phase SUMMARY.md files in milestone range
   • Extract 4-6 key accomplishments
   • Present for approval

5. Archive milestone:

   • Create .planning/milestones/v{{version}}-ROADMAP.md
   • Extract full phase details from ROADMAP.md
   • Fill milestone-archive.md template
   • Update ROADMAP.md to one-line summary with link

6. Archive requirements:

   • Create .planning/milestones/v{{version}}-REQUIREMENTS.md
   • Mark all v1 requirements as complete (checkboxes checked)
   • Note requirement outcomes (validated, adjusted, dropped)
   • Delete .planning/REQUIREMENTS.md (fresh one created for next milestone)

7. Update PROJECT.md:

   • Add "Current State" section with shipped version
   • Add "Next Milestone Goals" section
   • Archive previous content in <details> (if v1.1+)

6.5. Review Documentation (Non-blocking):

Before committing, offer final README review:

Use AskUserQuestion:

• header: "Final README Review"
• question: "Review README.md before completing milestone v{{version}}?"
• options:
  • "Yes, I'll review now" — Pause for user review, wait for "continue"
  • "Skip for now" — Proceed directly to commit
  • "Show README" — Display content, ask if accurate

If "Yes, I'll review now":

Review README.md for the complete v{{version}} milestone.
Ensure all shipped features are documented.
Say "continue" when ready to proceed.

If "Show README": Display README.md, then use AskUserQuestion:

• header: "README Accuracy"
• question: "Does this look accurate for v{{version}}?"
• options:
  • "Yes, looks good" — Proceed to Step 7
  • "Needs updates" — Pause for user edits, wait for "continue"

If "Skip" or review complete: Proceed to Step 7.

Non-blocking: milestone completion continues regardless of choice.

7. Commit and tag:

   • Stage: MILESTONES.md, PROJECT.md, ROADMAP.md, STATE.md, archive files
   • Commit: chore: complete v{{version}} milestone

   Check PR workflow mode:

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

   If PR_WORKFLOW=true:

   Skip git tag creation. Offer to create PR:

   Use AskUserQuestion:

   • header: "Create PR"
   • question: "Would you like me to create a PR for this milestone?"
   • options:
     • "Yes, create PR" — Create PR to merge to main
     • "No, I'll do it manually" — Show instructions only

   If "Yes, create PR":

   # Get current branch
   CURRENT_BRANCH=$(git branch --show-current)
   
   # Push branch if not already pushed
   git push -u origin "$CURRENT_BRANCH" 2>/dev/null || true
   
   # Create PR
   gh pr create \
     --title "v{{version}}: [Milestone Name]" \
     --body "$(cat <<'EOF'
   ## Summary
   
   Completes milestone v{{version}}.
   
   **Key accomplishments:**
   - [accomplishment 1]
   - [accomplishment 2]
   - [accomplishment 3]
   
   ## After Merge
   
   Create GitHub Release with tag `v{{version}}` to trigger npm publish (if configured).
   EOF
   )"
   

   Display PR URL and next steps:

   ✓ PR created: [PR URL]
   
   After merge:
   → Create GitHub Release with tag v{{version}}
   → GitHub Actions will publish to npm (if configured)
   

   If "No, I'll do it manually":

   Display:

   ⚡ PR workflow mode — tag will be created via GitHub Release after merge
   
   Next steps:
   1. Create PR to merge this branch to main
   2. After merge, create GitHub Release with tag v{{version}}
   3. GitHub Actions will publish to npm (if configured)
   

   If PR_WORKFLOW=false (default):

   Create tag locally:

   • Tag: git tag -a v{{version}} -m "[milestone summary]"
   • Ask about pushing tag

8. Offer next steps:

   • /kata:new-milestone — start next milestone (questioning → research → requirements → roadmap)

• Milestone archived to .planning/milestones/v{{version}}-ROADMAP.md
• Requirements archived to .planning/milestones/v{{version}}-REQUIREMENTS.md
• .planning/REQUIREMENTS.md deleted (fresh for next milestone)
• ROADMAP.md collapsed to one-line entry
• PROJECT.md updated with current state
• Git tag v{{version}} created (if pr_workflow=false) OR PR created/instructions given (if pr_workflow=true)
• Commit successful
• User knows next steps (including need for fresh requirements)

• Load workflow first: Read milestone-complete.md before executing
• Verify completion: All phases must have SUMMARY.md files
• User confirmation: Wait for approval at verification gates
• Archive before deleting: Always create archive files before updating/deleting originals
• One-line summary: Collapsed milestone in ROADMAP.md should be single line with link
• Context efficiency: Archive keeps ROADMAP.md and REQUIREMENTS.md constant size per milestone
• Fresh requirements: Next milestone starts with /kata:new-milestone which includes requirements definition