Gsd:complete Milestone Agent Skill

<objective>

Mark milestone {{version}} complete, archive to milestones/, and update ROADMAP.md and REQUIREMENTS.md.

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.

</objective>

<execution_context>

Load these files NOW (before proceeding):

• @${CLAUDE_PLUGIN_ROOT}/workflows/complete-milestone.md (main workflow)
• @${CLAUDE_PLUGIN_ROOT}/templates/milestone-archive.md (archive template)

</execution_context>

<context>

Project files:

• .planning/ROADMAP.md
• .planning/REQUIREMENTS.md
• .planning/STATE.md
• .planning/PROJECT.md

User input:

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

</context>

<process>

Follow complete-milestone.md workflow:

• Check for audit:

• Look for .planning/v{{version}}-MILESTONE-AUDIT.md
• If missing or stale: recommend /gsd:audit-milestone first
• If audit status is gaps_found: recommend /gsd: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 `/gsd:audit-milestone` first to verify
   requirements coverage, cross-phase integration, and E2E flows.

   {If audit has gaps:}
   ⚠ Milestone audit found gaps. Run `/gsd: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.

• Verify readiness:

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

• Gather stats:

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

• Extract accomplishments:

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

• 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

• 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)

• Update PROJECT.md:

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

• Commit and tag:

• Stage: MILESTONES.md, PROJECT.md, ROADMAP.md, STATE.md, archive files
• Commit: chore: archive v{{version}} milestone
• Tag: git tag -a v{{version}} -m "[milestone summary]"
• Ask about pushing tag

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

</process>

<output_format>

After the milestone is archived and tagged, emit a Milestone Complete continuation block following the pattern in references/continuation-format.md (§ Milestone Complete variant):

• ## 🎉 Milestone v{{version}} Complete with phase/plan/task summary
• Brief one-paragraph "what shipped" recap
• ## ▶ Next Up heading
• Use /clear then: before /gsd:new-milestone
• Parenthetical: *(/clear is safe — /gsd:resume-work restores position from HANDOFF.json if you change your mind)*
• Optional "Also available:" with /gsd:audit-milestone (retrospective audit) or /gsd:review-backlog (deferred items review)

Milestone close is the single biggest context-shed point in the workflow. The just-shipped milestone's plan/execute conversation is finished; the next milestone wants a clean slate. Always suggest /clear.

</output_format>

<success_criteria>

• 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
• Commit successful
• User knows next steps (including need for fresh requirements)

</success_criteria>

<critical_rules>

• Load workflow first: Read complete-milestone.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 /gsd:new-milestone which includes requirements definition

</critical_rules>