msd-core/get-shit-done/workflows/complete-milestone.md

<purpose>
Mark a shipped version (v1.0, v1.1, v2.0) as complete. This creates a historical record in MILESTONES.md, updates PROJECT.md with current state, reorganizes ROADMAP.md with milestone groupings, and tags the release in git.

This is the ritual that separates "development" from "shipped."
</purpose>

<required_reading>
**Read these files NOW:**

1. templates/milestone.md
2. templates/milestone-archive.md
3. `.planning/ROADMAP.md`
4. `.planning/PROJECT.md`
   </required_reading>

<archival_behavior>
When a milestone completes, this workflow:

1. Extracts full milestone details to `.planning/milestones/v[X.Y]-ROADMAP.md`
2. Updates ROADMAP.md to replace milestone details with one-line summary
3. Links to archive file for historical reference
4. Offers to create next milestone inline

**Context Efficiency:**

- Completed milestones: One line each (~50 tokens)
- Full details: In archive files (loaded only when needed)
- Result: ROADMAP.md stays constant size (~1-2k lines) forever

**Archive Format:**
Uses `templates/milestone-archive.md` template with:

- Milestone header (status, phases, date)
- Full phase details from roadmap
- Milestone summary (decisions, issues, technical debt)
  </archival_behavior>

<process>

<step name="verify_readiness">
Check if milestone is truly complete:

```bash
cat .planning/ROADMAP.md
ls .planning/phases/*/SUMMARY.md 2>/dev/null | wc -l
```

**Questions to ask:**

- Which phases belong to this milestone?
- Are all those phases complete (all plans have summaries)?
- Has the work been tested/validated?
- Is this ready to ship/tag?

Present:

```
Milestone: [Name from user, e.g., "v1.0 MVP"]

Appears to include:
- 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
```

**Check workflow config for gate behavior:**

```bash
cat .planning/config.json 2>/dev/null
```

Parse the config:

- If `mode: "yolo"` → auto-approve
- If `mode: "interactive"` → prompt user
- If `mode: "custom"` → check `gates.confirm_milestone_scope` (if exists)

**If auto-approved:**

```
⚡ Auto-approved: Milestone scope verification

[Show breakdown summary without prompting]

Proceeding to stats gathering...
```

**If prompting (interactive mode):**

```
Ready to mark this milestone as shipped?
(yes / wait / adjust scope)
```

Wait for confirmation.

If "adjust scope": Ask which phases should be included.
If "wait": Stop, user will return when ready.
</step>

<step name="gather_stats">
Calculate milestone statistics:

```bash
# Count phases and plans in milestone
# (user specified or detected from roadmap)

# Find git range
git log --oneline --grep="feat(" | head -20

# Count files modified in range
git diff --stat FIRST_COMMIT..LAST_COMMIT | tail -1

# Count LOC (adapt to language)
find . -name "*.swift" -o -name "*.ts" -o -name "*.py" | xargs wc -l 2>/dev/null

# Calculate timeline
git log --format="%ai" FIRST_COMMIT | tail -1  # Start date
git log --format="%ai" LAST_COMMIT | head -1   # End date
```

Present summary:

```
Milestone Stats:
- Phases: [X-Y]
- Plans: [Z] total
- Tasks: [N] total (estimated from phase summaries)
- Files modified: [M]
- Lines of code: [LOC] [language]
- Timeline: [Days] days ([Start] → [End])
- Git range: feat(XX-XX) → feat(YY-YY)
```

</step>

<step name="extract_accomplishments">
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
```

From summaries, 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]
```

</step>

<step name="create_milestone_entry">
Create or update `.planning/MILESTONES.md`.

If file doesn't exist:

```markdown
# Project Milestones: [Project Name from PROJECT.md]

[New entry]
```

If exists, prepend new entry (reverse chronological order).

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 milestone or start project] to ship

**Git range:** `feat(XX-XX)` → `feat(YY-YY)`

**What's next:** [Ask user: what's the next goal?]

---
```

</step>

<step name="update_project">
Update `.planning/PROJECT.md` to reflect current state.

Add/update "Current State" section at top (after YAML if present):

```markdown
# Project: [Name]

## Current State (Updated: YYYY-MM-DD)

**Shipped:** v[X.Y] [Name] (YYYY-MM-DD)
**Status:** [Production / Beta / Internal]
**Users:** [If known, e.g., "~500 downloads, 50 DAU" or "Internal use only"]
**Feedback:** [Key themes from users, or "Initial release, gathering feedback"]
**Codebase:** [LOC] [language], [key tech stack], [platform/deployment target]

## [Next Milestone] Goals

**Vision:** [What's the goal for next version?]

**Motivation:**

- [Why this next work matters]
- [User feedback driving it]
- [Technical debt or improvements needed]

**Scope (v[X.Y]):**

- [Feature/improvement 1]
- [Feature/improvement 2]
- [Feature/improvement 3]

---

<details>
<summary>Original Vision (v1.0 - Archived for reference)</summary>

[Move original project content here]

</details>
```

**If this is v1.0 (first milestone):**
Just add "Current State" section, no need to archive original vision yet.

**If this is v1.1+:**
Collapse previous version's content into `<details>` section.

Show diff of changes:
</step>

<step name="reorganize_roadmap">
Update `.planning/ROADMAP.md` to group completed milestone phases.

Add milestone headers and collapse completed work:

```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

<details>
<summary>✅ v1.0 MVP (Phases 1-4) - SHIPPED YYYY-MM-DD</summary>

- [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

</details>

### 🚧 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 | -          |
```

</step>

<step name="archive_milestone">
Extract completed milestone details and create archive file.

**Process:**

1. Create archive file path: `.planning/milestones/v[X.Y]-ROADMAP.md`

2. Read `~/.claude/get-shit-done/templates/milestone-archive.md` template

3. Extract data from current ROADMAP.md:

   - All phases belonging to this milestone (by phase number range)
   - Full phase details (goals, plans, dependencies, status)
   - Phase plan lists with completion checkmarks

4. Extract data from STATE.md:

   - All decisions made during this milestone (filter by Phase column)
   - Issues that were resolved
   - Issues that were deferred

5. Fill template {{PLACEHOLDERS}}:

   - {{VERSION}} - Milestone version (e.g., "1.0")
   - {{MILESTONE_NAME}} - From ROADMAP.md milestone header
   - {{DATE}} - Today's date
   - {{PHASE_START}} - First phase number in milestone
   - {{PHASE_END}} - Last phase number in milestone
   - {{TOTAL_PLANS}} - Count of all plans in milestone
   - {{MILESTONE_DESCRIPTION}} - From ROADMAP.md overview
   - {{PHASES_SECTION}} - Full phase details extracted
   - {{DECISIONS_FROM_PROJECT_STATE}} - Filtered decisions
   - {{ISSUES_RESOLVED_DURING_MILESTONE}} - From summaries
   - {{ISSUES_DEFERRED_TO_LATER}} - From ISSUES.md

6. Write filled template to `.planning/milestones/v[X.Y]-ROADMAP.md`

7. Update ROADMAP.md:

   - Create/update "## Completed Milestones" section if not exists
   - Add one-line entry: `- ✅ [v[X.Y] [Name]](milestones/v[X.Y]-ROADMAP.md) (Phases [N]-[M]) - SHIPPED [DATE]`
   - Remove full milestone details from "Current Milestone" section
   - Move next planned milestone to "Current Milestone" position

8. Verify files:

   - Check archive file exists: `ls .planning/milestones/v[X.Y]-ROADMAP.md`
   - Validate ROADMAP.md still parseable

9. Confirm archive complete:

   ```
   ✅ v[X.Y] archived to milestones/v[X.Y]-ROADMAP.md
   ```

   Continue to git_tag step. Milestone creation happens in offer_next step.
   </step>

<step name="git_tag">
Create git tag for milestone:

```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]
```

</step>

<step name="git_commit_milestone">
Commit milestone completion including archive file.

```bash
# Stage all milestone-related files
git add .planning/MILESTONES.md
git add .planning/PROJECT.md
git add .planning/ROADMAP.md
git add .planning/milestones/v[X.Y]-ROADMAP.md

# Commit with descriptive message
git commit -m "$(cat <<'EOF'
chore: archive v[X.Y] milestone

- Added MILESTONES.md entry
- Updated PROJECT.md current state
- Reorganized ROADMAP.md with milestone grouping
- Created milestone archive: milestones/v[X.Y]-ROADMAP.md
- Tagged v[X.Y]
EOF
)"
```

Confirm: "Committed: chore: archive v[X.Y] milestone"

Then proceed to git tag step.
</step>

<step name="offer_next">
```
✅ Milestone v[X.Y] [Name] complete

Shipped:

- [N] phases ([M] plans, [P] tasks)
- [One sentence of what shipped]

Summary: .planning/MILESTONES.md
Tag: v[X.Y]

Next steps:

1. Discuss next milestone scope (/gsd:discuss-milestone)
2. Create next milestone directly (/gsd:new-milestone)
3. Done for now

```

Wait for user decision.

If "1": Invoke SlashCommand("/gsd:discuss-milestone")
If "2": Invoke SlashCommand("/gsd:new-milestone")

Note: Commands are shown in options above so user can see what will run.
</step>

</process>

<milestone_naming>
**Version conventions:**
- **v1.0** - Initial MVP
- **v1.1, v1.2, v1.3** - Minor updates, new features, fixes
- **v2.0, v3.0** - Major rewrites, breaking changes, significant new direction

**Name conventions:**
- v1.0 MVP
- v1.1 Security
- v1.2 Performance
- v2.0 Redesign
- v2.0 iOS Launch

Keep names short (1-2 words describing the focus).
</milestone_naming>

<what_qualifies>
**Create milestones for:**
- Initial release (v1.0)
- Public releases
- Major feature sets shipped
- Before archiving planning

**Don't create milestones for:**
- Every phase completion (too granular)
- Work in progress (wait until shipped)
- Internal dev iterations (unless truly shipped internally)

If uncertain, ask: "Is this deployed/usable/shipped in some form?"
If yes → milestone. If no → keep working.
</what_qualifies>

<success_criteria>
Milestone completion is successful when:
- [ ] MILESTONES.md entry created with stats and accomplishments
- [ ] PROJECT.md updated with current state
- [ ] ROADMAP.md reorganized with milestone grouping
- [ ] Git tag created (v[X.Y])
- [ ] Milestone commit made
- [ ] User knows next steps
</success_criteria>
```