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