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.
- @~/.claude/gsd-core/workflows/complete-milestone.md (main workflow)
- @~/.claude/gsd-core/templates/milestone-archive.md (archive template)
User input:
- Version: {{version}} (e.g., "1.0", "1.1", "2.0")
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 closing the gaps inline
(the audit output already enumerates them — insert closure phases
via /gsd-phase --insert <N> plus the standard
discuss/plan/execute chain) before proceeding.
- 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. The audit output already enumerates the
unsatisfied requirements, cross-phase issues, and broken flows — insert
a closure phase per gap with `/gsd-phase --insert <N>` and run the
standard `/gsd-discuss-phase` → `/gsd-plan-phase` → `/gsd-execute-phase`
chain. Or proceed anyway to accept the gaps 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)
- 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
git.create_tag enabled)
- 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
1---2name: gsd-complete-milestone3description: Archive completed milestone and prepare for next version4---5
6
7<objective>
8Mark milestone {{version}} complete, archive to milestones/, and update ROADMAP.md and REQUIREMENTS.md.
9
10Purpose: Create historical record of shipped version, archive milestone artifacts (roadmap + requirements), and prepare for next milestone.
11Output: Milestone archived (roadmap + requirements), PROJECT.md evolved, git tagged.
12</objective>
13
14<execution_context>
15**Load these files NOW (before proceeding):**
16
17- @~/.claude/gsd-core/workflows/complete-milestone.md (main workflow)
18- @~/.claude/gsd-core/templates/milestone-archive.md (archive template)
19 </execution_context>
20
21<context>
22**Project files:**
23- `.planning/ROADMAP.md`
24- `.planning/REQUIREMENTS.md`
25- `.planning/STATE.md`
26- `.planning/PROJECT.md`
27
28**User input:**
29
30- Version: {{version}} (e.g., "1.0", "1.1", "2.0")
31 </context>
32
33<process>
34
35**Follow complete-milestone.md workflow:**
36
370. **Check for audit:**
38
39 - Look for `.planning/v{{version}}-MILESTONE-AUDIT.md`
40 - If missing or stale: recommend `/gsd-audit-milestone` first
41 - If audit status is `gaps_found`: recommend closing the gaps inline
42 (the audit output already enumerates them — insert closure phases
43 via `/gsd-phase --insert <N>` plus the standard
44 discuss/plan/execute chain) before proceeding.
45 - If audit status is `passed`: proceed to step 1
46
47 ```markdown
48 ## Pre-flight Check
49
50 {If no v{{version}}-MILESTONE-AUDIT.md:}
51 ⚠ No milestone audit found. Run `/gsd-audit-milestone` first to verify
52 requirements coverage, cross-phase integration, and E2E flows.
53
54 {If audit has gaps:}
55 ⚠ Milestone audit found gaps. The audit output already enumerates the
56 unsatisfied requirements, cross-phase issues, and broken flows — insert
57 a closure phase per gap with `/gsd-phase --insert <N>` and run the
58 standard `/gsd-discuss-phase` → `/gsd-plan-phase` → `/gsd-execute-phase`
59 chain. Or proceed anyway to accept the gaps as tech debt.
60
61 {If audit passed:}
62 ✓ Milestone audit passed. Proceeding with completion.
63 ```
64
651. **Verify readiness:**
66
67 - Check all phases in milestone have completed plans (SUMMARY.md exists)
68 - Present milestone scope and stats
69 - Wait for confirmation
70
712. **Gather stats:**
72
73 - Count phases, plans, tasks
74 - Calculate git range, file changes, LOC
75 - Extract timeline from git log
76 - Present summary, confirm
77
783. **Extract accomplishments:**
79
80 - Read all phase SUMMARY.md files in milestone range
81 - Extract 4-6 key accomplishments
82 - Present for approval
83
844. **Archive milestone:**
85
86 - Create `.planning/milestones/v{{version}}-ROADMAP.md`
87 - Extract full phase details from ROADMAP.md
88 - Fill milestone-archive.md template
89 - Update ROADMAP.md to one-line summary with link
90
915. **Archive requirements:**
92
93 - Create `.planning/milestones/v{{version}}-REQUIREMENTS.md`
94 - Mark all v1 requirements as complete (checkboxes checked)
95 - Note requirement outcomes (validated, adjusted, dropped)
96 - Delete `.planning/REQUIREMENTS.md` (fresh one created for next milestone)
97
986. **Update PROJECT.md:**
99
100 - Add "Current State" section with shipped version
101 - Add "Next Milestone Goals" section
102 - Archive previous content in `<details>` (if v1.1+)
103
1047. **Commit and tag:**
105
106 - Stage: MILESTONES.md, PROJECT.md, ROADMAP.md, STATE.md, archive files
107 - Commit: `chore: archive v{{version}} milestone`
108 - Tag: `git tag -a v{{version}} -m "[milestone summary]"`
109 - Ask about pushing tag
110
1118. **Offer next steps:**
112 - `/gsd-new-milestone` — start next milestone (questioning → research → requirements → roadmap)
113
114</process>
115
116<success_criteria>
117
118- Milestone archived to `.planning/milestones/v{{version}}-ROADMAP.md`
119- Requirements archived to `.planning/milestones/v{{version}}-REQUIREMENTS.md`
120- `.planning/REQUIREMENTS.md` deleted (fresh for next milestone)
121- ROADMAP.md collapsed to one-line entry
122- PROJECT.md updated with current state
123- Git tag v{{version}} created (if `git.create_tag` enabled)
124- Commit successful
125- User knows next steps (including need for fresh requirements)
126 </success_criteria>
127
128<critical_rules>
129
130- **Load workflow first:** Read complete-milestone.md before executing
131- **Verify completion:** All phases must have SUMMARY.md files
132- **User confirmation:** Wait for approval at verification gates
133- **Archive before deleting:** Always create archive files before updating/deleting originals
134- **One-line summary:** Collapsed milestone in ROADMAP.md should be single line with link
135- **Context efficiency:** Archive keeps ROADMAP.md and REQUIREMENTS.md constant size per milestone
136- **Fresh requirements:** Next milestone starts with `/gsd-new-milestone` which includes requirements definition
137 </critical_rules>
open-gsd