Skip to main content
Generaldavepoon

gsd:complete-milestone

Archive completed milestone and prepare for next version

Stars
2,987
Source
davepoon/buildwithclaude
Updated
2026-05-26
Slug
davepoon--buildwithclaude--complete-milestone
View on GitHubRaw SKILL.md

// install — copy + paste into any project

mkdir -p .claude/skills && curl -fsSL https://raw.githubusercontent.com/davepoon/buildwithclaude/HEAD/plugins/gsd/skills/complete-milestone/SKILL.md -o .claude/skills/complete-milestone.md

Drops the SKILL.md into .claude/skills/complete-milestone.md. Works with Claude Code, Cursor, and any agent that loads SKILL.md files from .claude/skills/.

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.

**Load these files NOW (before proceeding):**
  • @${CLAUDE_PLUGIN_ROOT}/workflows/complete-milestone.md (main workflow)
  • @${CLAUDE_PLUGIN_ROOT}/templates/milestone-archive.md (archive template)
**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")

Follow complete-milestone.md workflow:

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

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

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

  9. Offer next steps:

    • /gsd:new-milestone — start next milestone (questioning → research → requirements → roadmap)
 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.

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