Mark a shipped version (v1.0, v1.1, v2.0) as complete. Creates historical record in MILESTONES.md, performs full PROJECT.md evolution review, reorganizes ROADMAP.md with milestone groupings, and tags the release in git.
1. templates/milestone.md
2. templates/milestone-archive.md
3. `.planning/ROADMAP.md`
4. `.planning/REQUIREMENTS.md`
5. `.planning/PROJECT.md`
When a milestone completes:
1. Extract full milestone details to `.planning/milestones/v[X.Y]-ROADMAP.md`
2. Archive requirements to `.planning/milestones/v[X.Y]-REQUIREMENTS.md`
3. Update ROADMAP.md — replace milestone details with one-line summary
4. Delete REQUIREMENTS.md (fresh one for next milestone)
5. Perform full PROJECT.md evolution review
6. Offer to create next milestone inline
**Context Efficiency:** Archives keep ROADMAP.md constant-size and REQUIREMENTS.md milestone-scoped.
**ROADMAP archive** uses `templates/milestone-archive.md` — includes milestone header (status, phases, date), full phase details, milestone summary (decisions, issues, tech debt).
**REQUIREMENTS archive** contains all requirements marked complete with outcomes, traceability table with final status, notes on changed requirements.
Check milestone completion:
```bash
cat .planning/ROADMAP.md
ls .planning/phases/*/SUMMARY.md 2>/dev/null | wc -l
```
Verify:
- Which phases belong to this milestone?
- All phases complete (all plans have summaries)?
- Work tested/validated?
- Ready to ship/tag?
Present:
```
Milestone: [Name, e.g., "v1.0 MVP"]
Includes:
- Phase 1: Foundation (2/2 plans complete)
- Phase 2: Authentication (2/2 plans complete)
- Phase 3: Core Features (3/3 plans complete)
- Phase 4: Polish (1/1 plan complete)
Total: 4 phases, 8 plans, all complete
```
```bash
cat .planning/config.json 2>/dev/null
```
```
⚡ Auto-approved: Milestone scope verification
[Show breakdown summary without prompting]
Proceeding to stats gathering...
```
Proceed to gather_stats.
```
Ready to mark this milestone as shipped?
(yes / wait / adjust scope)
```
Wait for confirmation.
- "adjust scope": Ask which phases to include.
- "wait": Stop, user returns when ready.
Calculate milestone statistics:
```bash
git log --oneline --grep="feat(" | head -20
git diff --stat FIRST_COMMIT..LAST_COMMIT | tail -1
find . -name "*.swift" -o -name "*.ts" -o -name "*.py" | xargs wc -l 2>/dev/null
git log --format="%ai" FIRST_COMMIT | tail -1
git log --format="%ai" LAST_COMMIT | head -1
```
Present:
```
Milestone Stats:
- Phases: [X-Y]
- Plans: [Z] total
- Tasks: [N] total (from phase summaries)
- Files modified: [M]
- Lines of code: [LOC] [language]
- Timeline: [Days] days ([Start] → [End])
- Git range: feat(XX-XX) → feat(YY-YY)
```
Read all phase SUMMARY.md files in milestone range:
```bash
cat .planning/phases/01-*/01-*-SUMMARY.md
cat .planning/phases/02-*/02-*-SUMMARY.md
# ... for each phase in milestone
```
Extract 4-6 key accomplishments. Present:
```
Key accomplishments for this milestone:
1. [Achievement from phase 1]
2. [Achievement from phase 2]
3. [Achievement from phase 3]
4. [Achievement from phase 4]
5. [Achievement from phase 5]
```
Create or update `.planning/MILESTONES.md`.
If file doesn't exist, create with project name header. If exists, prepend new entry (reverse chronological).
Use template from `templates/milestone.md`:
```markdown
## v[Version] [Name] (Shipped: YYYY-MM-DD)
**Delivered:** [One sentence from user]
**Phases completed:** [X-Y] ([Z] plans total)
**Key accomplishments:**
- [List from previous step]
**Stats:**
- [Files] files created/modified
- [LOC] lines of [language]
- [Phases] phases, [Plans] plans, [Tasks] tasks
- [Days] days from [start] to ship
**Git range:** `feat(XX-XX)` → `feat(YY-YY)`
**What's next:** [Ask user: what's the next goal?]
---
```
Full PROJECT.md evolution review at milestone completion.
Read all phase summaries:
```bash
cat .planning/phases/*-*/*-SUMMARY.md
```
**Full review checklist:**
1. **"What This Is" accuracy:**
- Compare current description to what was built
- Update if product has meaningfully changed
2. **Core Value check:**
- Still the right priority? Did shipping reveal a different core value?
- Update if the ONE thing has shifted
3. **Requirements audit:**
**Validated section:**
- All Active requirements shipped this milestone → Move to Validated
- Format: `- ✓ [Requirement] — v[X.Y]`
**Active section:**
- Remove requirements moved to Validated
- Add new requirements for next milestone
- Keep unaddressed requirements
**Out of Scope audit:**
- Review each item — reasoning still valid?
- Remove irrelevant items
- Add requirements invalidated during milestone
4. **Context update:**
- Current codebase state (LOC, tech stack)
- User feedback themes (if any)
- Known issues or technical debt
5. **Key Decisions audit:**
- Extract all decisions from milestone phase summaries
- Add to Key Decisions table with outcomes
- Mark ✓ Good, ⚠️ Revisit, or — Pending
6. **Constraints check:**
- Any constraints changed during development? Update as needed
Update PROJECT.md inline. Update "Last updated" footer:
```markdown
---
*Last updated: [date] after v[X.Y] milestone*
```
**Example full evolution (v1.0 → v1.1 prep):**
Before:
```markdown
## What This Is
A real-time collaborative whiteboard for remote teams.
## Core Value
Real-time sync that feels instant.
## Requirements
### Validated
(None yet — ship to validate)
### Active
- [ ] Canvas drawing tools
- [ ] Real-time sync < 500ms
- [ ] User authentication
- [ ] Export to PNG
### Out of Scope
- Mobile app — web-first approach
- Video chat — use external tools
```
After v1.0:
```markdown
## What This Is
A real-time collaborative whiteboard for remote teams with instant sync and drawing tools.
## Core Value
Real-time sync that feels instant.
## Requirements
### Validated
- ✓ Canvas drawing tools — v1.0
- ✓ Real-time sync < 500ms — v1.0 (achieved 200ms avg)
- ✓ User authentication — v1.0
### Active
- [ ] Export to PNG
- [ ] Undo/redo history
- [ ] Shape tools (rectangles, circles)
### Out of Scope
- Mobile app — web-first approach, PWA works well
- Video chat — use external tools
- Offline mode — real-time is core value
## Context
Shipped v1.0 with 2,400 LOC TypeScript.
Tech stack: Next.js, Supabase, Canvas API.
Initial user testing showed demand for shape tools.
```
**Step complete when:**
- [ ] "What This Is" reviewed and updated if needed
- [ ] Core Value verified as still correct
- [ ] All shipped requirements moved to Validated
- [ ] New requirements added to Active for next milestone
- [ ] Out of Scope reasoning audited
- [ ] Context updated with current state
- [ ] All milestone decisions added to Key Decisions
- [ ] "Last updated" footer reflects milestone completion
Update `.planning/ROADMAP.md` — group completed milestone phases:
```markdown
# Roadmap: [Project Name]
## Milestones
- ✅ **v1.0 MVP** — Phases 1-4 (shipped YYYY-MM-DD)
- 🚧 **v1.1 Security** — Phases 5-6 (in progress)
- 📋 **v2.0 Redesign** — Phases 7-10 (planned)
## Phases
✅ v1.0 MVP (Phases 1-4) — SHIPPED YYYY-MM-DD
- [x] Phase 1: Foundation (2/2 plans) — completed YYYY-MM-DD
- [x] Phase 2: Authentication (2/2 plans) — completed YYYY-MM-DD
- [x] Phase 3: Core Features (3/3 plans) — completed YYYY-MM-DD
- [x] Phase 4: Polish (1/1 plan) — completed YYYY-MM-DD
### 🚧 v[Next] [Name] (In Progress / Planned)
- [ ] Phase 5: [Name] ([N] plans)
- [ ] Phase 6: [Name] ([N] plans)
## Progress
| Phase | Milestone | Plans Complete | Status | Completed |
| ----------------- | --------- | -------------- | ----------- | ---------- |
| 1. Foundation | v1.0 | 2/2 | Complete | YYYY-MM-DD |
| 2. Authentication | v1.0 | 2/2 | Complete | YYYY-MM-DD |
| 3. Core Features | v1.0 | 3/3 | Complete | YYYY-MM-DD |
| 4. Polish | v1.0 | 1/1 | Complete | YYYY-MM-DD |
| 5. Security Audit | v1.1 | 0/1 | Not started | - |
| 6. Hardening | v1.1 | 0/2 | Not started | - |
```
Extract completed milestone details to archive.
1. Create `.planning/milestones/v[X.Y]-ROADMAP.md`
2. Read `~/.claude/get-shit-done/templates/milestone-archive.md` template
3. Extract from ROADMAP.md: all phases in milestone (by number range), full phase details, plan lists with checkmarks
4. Extract from PROJECT.md: key decisions, validated requirements
5. Fill template placeholders: {{VERSION}}, {{MILESTONE_NAME}}, {{DATE}}, {{PHASE_START}}, {{PHASE_END}}, {{TOTAL_PLANS}}, {{MILESTONE_DESCRIPTION}}, {{PHASES_SECTION}}, {{DECISIONS_FROM_PROJECT}}, {{ISSUES_RESOLVED_DURING_MILESTONE}}
6. Write to `.planning/milestones/v[X.Y]-ROADMAP.md`
7. Delete ROADMAP.md:
```bash
rm .planning/ROADMAP.md
```
8. Verify:
```bash
ls .planning/milestones/v[X.Y]-ROADMAP.md
```
9. Confirm:
```
✅ v[X.Y] roadmap archived to milestones/v[X.Y]-ROADMAP.md
✅ ROADMAP.md deleted (fresh one for next milestone)
```
**Note:** Phase directories (`.planning/phases/`) are NOT deleted — they accumulate across milestones as raw execution history. Phase numbering continues (v1.0 phases 1-4, v1.1 phases 5-8, etc.).
Archive requirements for next milestone.
1. Read REQUIREMENTS.md:
```bash
cat .planning/REQUIREMENTS.md
```
2. Create `.planning/milestones/v[X.Y]-REQUIREMENTS.md`
3. Transform: mark all requirements `[x]` complete, add outcome notes, update traceability table to "Complete", add milestone summary (total shipped, scope changes, drops)
4. Write archive with header:
```markdown
# Requirements Archive: v[X.Y] [Milestone Name]
**Archived:** [DATE]
**Status:** ✅ SHIPPED
For current requirements, see `.planning/REQUIREMENTS.md`.
---
[Full REQUIREMENTS.md content with checkboxes marked complete]
---
## Milestone Summary
**Shipped:** [X] of [Y] requirements
**Adjusted:** [list any that changed]
**Dropped:** [list any removed and why]
---
*Archived: [DATE] as part of v[X.Y] milestone completion*
```
5. Delete original:
```bash
rm .planning/REQUIREMENTS.md
```
6. Confirm:
```
✅ Requirements archived to milestones/v[X.Y]-REQUIREMENTS.md
✅ REQUIREMENTS.md deleted (fresh one for next milestone)
```
**Note:** Next milestone starts with `/gsd:new-milestone` which includes requirements definition. PROJECT.md's Validated section carries cumulative record across milestones.
Move audit file to archive (if exists):
```bash
AUDIT_EXISTS=$(node ~/.claude/get-shit-done/bin/gsd-tools.js verify-path-exists .planning/v[X.Y]-MILESTONE-AUDIT.md --raw)
[ "$AUDIT_EXISTS" = "true" ] && mv .planning/v[X.Y]-MILESTONE-AUDIT.md .planning/milestones/
```
Confirm: `✅ Audit archived to milestones/v[X.Y]-MILESTONE-AUDIT.md`
Skip silently if no audit file — audit is optional.
Update STATE.md for milestone completion.
**Project Reference:**
```markdown
## Project Reference
See: .planning/PROJECT.md (updated [today])
**Core value:** [Current core value from PROJECT.md]
**Current focus:** [Next milestone or "Planning next milestone"]
```
**Current Position:**
```markdown
Phase: [Next phase] of [Total] ([Phase name])
Plan: Not started
Status: Ready to plan
Last activity: [today] — v[X.Y] milestone complete
Progress: [updated progress bar]
```
**Accumulated Context:**
- Clear decisions summary (full log in PROJECT.md)
- Clear resolved blockers
- Keep open blockers for next milestone
Check branching strategy and offer merge options.
```bash
GSD_CONFIG=$(node ~/.claude/get-shit-done/bin/gsd-tools.js state load --raw)
BRANCHING_STRATEGY=$(echo "$GSD_CONFIG" | grep '^branching_strategy=' | cut -d= -f2)
PHASE_BRANCH_TEMPLATE=$(echo "$GSD_CONFIG" | grep '^phase_branch_template=' | cut -d= -f2)
MILESTONE_BRANCH_TEMPLATE=$(echo "$GSD_CONFIG" | grep '^milestone_branch_template=' | cut -d= -f2)
```
**If "none":** Skip to git_tag.
**For "phase" strategy:**
```bash
BRANCH_PREFIX=$(echo "$PHASE_BRANCH_TEMPLATE" | sed 's/{.*//')
PHASE_BRANCHES=$(git branch --list "${BRANCH_PREFIX}*" 2>/dev/null | sed 's/^\*//' | tr -d ' ')
```
**For "milestone" strategy:**
```bash
BRANCH_PREFIX=$(echo "$MILESTONE_BRANCH_TEMPLATE" | sed 's/{.*//')
MILESTONE_BRANCH=$(git branch --list "${BRANCH_PREFIX}*" 2>/dev/null | sed 's/^\*//' | tr -d ' ' | head -1)
```
**If no branches found:** Skip to git_tag.
**If branches exist:**
```
## Git Branches Detected
Branching strategy: {phase/milestone}
Branches: {list}
Options:
1. **Merge to main** — Merge branch(es) to main
2. **Delete without merging** — Already merged or not needed
3. **Keep branches** — Leave for manual handling
```
AskUserQuestion with options: Squash merge (Recommended), Merge with history, Delete without merging, Keep branches.
**Squash merge:**
```bash
CURRENT_BRANCH=$(git branch --show-current)
git checkout main
if [ "$BRANCHING_STRATEGY" = "phase" ]; then
for branch in $PHASE_BRANCHES; do
git merge --squash "$branch"
git commit -m "feat: $branch for v[X.Y]"
done
fi
if [ "$BRANCHING_STRATEGY" = "milestone" ]; then
git merge --squash "$MILESTONE_BRANCH"
git commit -m "feat: $MILESTONE_BRANCH for v[X.Y]"
fi
git checkout "$CURRENT_BRANCH"
```
**Merge with history:**
```bash
CURRENT_BRANCH=$(git branch --show-current)
git checkout main
if [ "$BRANCHING_STRATEGY" = "phase" ]; then
for branch in $PHASE_BRANCHES; do
git merge --no-ff "$branch" -m "Merge branch '$branch' for v[X.Y]"
done
fi
if [ "$BRANCHING_STRATEGY" = "milestone" ]; then
git merge --no-ff "$MILESTONE_BRANCH" -m "Merge branch '$MILESTONE_BRANCH' for v[X.Y]"
fi
git checkout "$CURRENT_BRANCH"
```
**Delete without merging:**
```bash
if [ "$BRANCHING_STRATEGY" = "phase" ]; then
for branch in $PHASE_BRANCHES; do
git branch -d "$branch" 2>/dev/null || git branch -D "$branch"
done
fi
if [ "$BRANCHING_STRATEGY" = "milestone" ]; then
git branch -d "$MILESTONE_BRANCH" 2>/dev/null || git branch -D "$MILESTONE_BRANCH"
fi
```
**Keep branches:** Report "Branches preserved for manual handling"
Create git tag:
```bash
git tag -a v[X.Y] -m "$(cat <<'EOF'
v[X.Y] [Name]
Delivered: [One sentence]
Key accomplishments:
- [Item 1]
- [Item 2]
- [Item 3]
See .planning/MILESTONES.md for full details.
EOF
)"
```
Confirm: "Tagged: v[X.Y]"
Ask: "Push tag to remote? (y/n)"
If yes:
```bash
git push origin v[X.Y]
```
Commit milestone completion.
```bash
node ~/.claude/get-shit-done/bin/gsd-tools.js commit "chore: complete v[X.Y] milestone" --files .planning/milestones/v[X.Y]-ROADMAP.md .planning/milestones/v[X.Y]-REQUIREMENTS.md .planning/milestones/v[X.Y]-MILESTONE-AUDIT.md .planning/MILESTONES.md .planning/PROJECT.md .planning/STATE.md
```
```
Confirm: "Committed: chore: complete v[X.Y] milestone"
```
✅ Milestone v[X.Y] [Name] complete
Shipped:
- [N] phases ([M] plans, [P] tasks)
- [One sentence of what shipped]
Archived:
- milestones/v[X.Y]-ROADMAP.md
- milestones/v[X.Y]-REQUIREMENTS.md
Summary: .planning/MILESTONES.md
Tag: v[X.Y]
---
## ▶ Next Up
**Start Next Milestone** — questioning → research → requirements → roadmap
`/gsd:new-milestone`
`/clear` first → fresh context window
---
```
**Version conventions:**
- **v1.0** — Initial MVP
- **v1.1, v1.2** — Minor updates, new features, fixes
- **v2.0, v3.0** — Major rewrites, breaking changes, new direction
**Names:** Short 1-2 words (v1.0 MVP, v1.1 Security, v1.2 Performance, v2.0 Redesign).
**Create milestones for:** Initial release, public releases, major feature sets shipped, before archiving planning.
**Don't create milestones for:** Every phase completion (too granular), work in progress, internal dev iterations (unless truly shipped).
Heuristic: "Is this deployed/usable/shipped?" If yes → milestone. If no → keep working.
Milestone completion is successful when:
- [ ] MILESTONES.md entry created with stats and accomplishments
- [ ] PROJECT.md full evolution review completed
- [ ] All shipped requirements moved to Validated in PROJECT.md
- [ ] Key Decisions updated with outcomes
- [ ] ROADMAP.md reorganized with milestone grouping
- [ ] Roadmap archive created (milestones/v[X.Y]-ROADMAP.md)
- [ ] Requirements archive created (milestones/v[X.Y]-REQUIREMENTS.md)
- [ ] REQUIREMENTS.md deleted (fresh for next milestone)
- [ ] STATE.md updated with fresh project reference
- [ ] Git tag created (v[X.Y])
- [ ] Milestone commit made (includes archive files and deletion)
- [ ] User knows next step (/gsd:new-milestone)