Manage Milestones

Complete milestones, archive work, and start new development cycles

Overview

Milestones mark significant releases in your project. GSD provides commands to complete current work and start the next development cycle.

Complete Milestone

Archive completed work and tag a release

New Milestone

Start the next version with fresh roadmap

Complete Milestone

The /gsd:complete-milestone command marks your current milestone complete, archives artifacts, and prepares for the next cycle.

Command Usage

/gsd:complete-milestone <version>

First Release

/gsd:complete-milestone 1.0

Completes your v1.0 milestone.

Minor Version

/gsd:complete-milestone 1.1

Completes v1.1 features.

Major Version

/gsd:complete-milestone 2.0

Completes v2.0 overhaul.

Pre-Flight Checks

Before completion, GSD checks for milestone audit:

1. Check for Audit

   Looks for .planning/v{version}-MILESTONE-AUDIT.md

2. Audit Status

   No Audit

   ⚠ No milestone audit found.
   
   Run `/gsd:audit-milestone` first to verify:
   - Requirements coverage
   - Cross-phase integration
   - End-to-end flows
   
   Proceed anyway? (yes/no)
   

   Gaps Found

   ⚠ Milestone audit found gaps:
   
   - REQ-008: Email notifications not implemented
   - Integration: Dashboard doesn't load user data
   
   Options:
   1. /gsd:plan-milestone-gaps - Create phases to close gaps
   2. Proceed anyway - Accept as tech debt
   
   What would you like to do?
   

   Passed

   ✓ Milestone audit passed
   
   All requirements covered:
   - REQ-001 through REQ-010 ✓
   - Cross-phase integration verified ✓
   - E2E flows working ✓
   
   Proceeding with completion...
   

What It Does

1. Verify Readiness

   📋 Milestone v1.0 Completion Check
   
   Phases:
   - Phase 1: Database Schema ✓
   - Phase 2: User Authentication ✓
   - Phase 3: Activity Dashboard ✓
   - Phase 4: Settings & Profile ✓
   
   All phases have SUMMARY.md files.
   Ready to complete milestone? (yes/no)
   
2. Gather Statistics

   📊 Milestone Statistics
   
   Scope:
   - 4 phases completed
   - 12 plans executed
   - 47 tasks delivered
   
   Changes:
   - 156 files changed
   - 8,432 lines added
   - 1,203 lines removed
   
   Timeline:
   - Started: 2024-02-15
   - Completed: 2024-03-06
   - Duration: 20 days
   
   Confirm these stats? (yes/no)
   
3. Extract Accomplishments

   Reads all SUMMARY.md files and extracts key deliverables:

   🎯 Key Accomplishments
   
   1. User authentication with email/password
   2. Activity dashboard with filtering and search
   3. Real-time updates via WebSocket
   4. Settings page with profile customization
   5. Dark mode support
   6. Comprehensive test coverage (94%)
   
   Approve these accomplishments? (yes/edit)
   
4. Archive Roadmap

   Creates .planning/milestones/v1.0-ROADMAP.md with full phase details:

   # Milestone v1.0: Initial Release
   
   **Status:** COMPLETE
   **Completed:** 2024-03-06
   
   ## Scope
   4 phases, 12 plans, 47 tasks
   
   ## Phases
   
   ### Phase 1: Database Schema
   **Goal:** Set up data models and migrations
   **Requirements:** REQ-001, REQ-002
   **Status:** ✓ Complete
   
   [Full details for all phases...]
   

   Updates ROADMAP.md to one-line summary:

   ## Completed Milestones
   
   - [v1.0: Initial Release](.planning/milestones/v1.0-ROADMAP.md) - 4 phases, completed 2024-03-06
   
5. Archive Requirements

   Creates .planning/milestones/v1.0-REQUIREMENTS.md with final status:

   # v1.0 Requirements
   
   ## v1 Requirements (Delivered)
   - [x] REQ-001: User registration and login
   - [x] REQ-002: Activity tracking and display
   - [x] REQ-003: User settings and preferences
   ...
   
   ## v2 Requirements (Deferred)
   - [ ] REQ-011: OAuth social login
   - [ ] REQ-012: Email notifications
   ...
   
   ## Outcomes
   - All v1 requirements delivered
   - 2 requirements adjusted during development
   - 3 v2 requirements moved to next milestone
   

   Deletes .planning/REQUIREMENTS.md (will be recreated for next milestone)

6. Update PROJECT.md

   Adds “Current State” section:

   ## Current State
   
   **Version:** 1.0 (Shipped 2024-03-06)
   
   Delivered:
   - User authentication system
   - Activity dashboard with real-time updates
   - User profile and settings
   - Dark mode support
   
   ## Next Milestone Goals
   
   v1.1 will focus on:
   - Email notifications
   - Team collaboration features
   - Advanced filtering and analytics
   

   If v1.1+, archives previous content in <details> tags.

7. Commit and Tag

   git add .planning/milestones/ .planning/PROJECT.md .planning/ROADMAP.md .planning/STATE.md
   git commit -m "chore: archive v1.0 milestone"
   git tag -a v1.0 -m "v1.0: Initial Release
   
   - User authentication
   - Activity dashboard
   - Settings and profile
   - Dark mode support"
   

   ✓ Milestone v1.0 complete
   ✓ Tagged as v1.0
   
   Push tag to remote? (yes/no)
   

Files Created

Milestone Archive

.planning/milestones/v1.0-ROADMAP.md - Full phase details

Requirements Archive

.planning/milestones/v1.0-REQUIREMENTS.md - Final requirement status

Files Updated

• ROADMAP.md - Collapsed to one-line summary
• PROJECT.md - Added current state section
• STATE.md - Reset for next milestone

Files Deleted

• REQUIREMENTS.md - Will be recreated by /gsd:new-milestone

Archiving keeps ROADMAP.md and REQUIREMENTS.md at constant size regardless of project age. Old details move to /milestones/.

Next Steps After Completion

✓ Milestone v1.0 archived

Next steps:
- /gsd:new-milestone - Start next development cycle
- Take a break - You shipped something!

New Milestone

The /gsd:new-milestone command starts a fresh development cycle for your existing project.

Command Usage

/gsd:new-milestone [name]

With Name

/gsd:new-milestone "v1.1 Notifications"

Starts milestone with provided name.

Interactive

/gsd:new-milestone

Prompts for milestone name and description.

What It Does

New milestone follows the same flow as new-project, but for existing codebases:

1. Questioning

   Deep conversation about what you want to build next:

   🎯 New Milestone: v1.1
   
   Your project currently has:
   - User authentication
   - Activity dashboard
   - Settings and profile
   
   What do you want to add in v1.1?
   
   > I want to add email notifications for important events
   
   What types of events should trigger notifications?
   
   > When someone mentions you, when your post gets liked, when you get a new follower
   
   How should users control notification preferences?
   
   > In settings - they can enable/disable each type, plus set digest frequency
   
   [Conversation continues until complete understanding...]
   
2. Research (Optional)

   Would you like domain research for this milestone?
   
   Research will investigate:
   - Email service providers (SendGrid, Mailgun, etc.)
   - Notification patterns and best practices
   - Queue systems for reliable delivery
   - Anti-spam and delivery optimization
   
   Run research? (yes/no)
   
   > yes
   
   Spawning research agents...
   

   Research is especially valuable when adding unfamiliar features to an existing project.

3. Requirements

   📋 v1.1 Requirements
   
   ## v1 Requirements (This Milestone)
   - [ ] REQ-011: Users can enable/disable notification types
   - [ ] REQ-012: Email sent when user is mentioned
   - [ ] REQ-013: Email sent when post is liked
   - [ ] REQ-014: Email sent for new followers
   - [ ] REQ-015: Digest mode (daily/weekly summaries)
   - [ ] REQ-016: One-click unsubscribe from emails
   
   ## v2 Requirements (Future)
   - [ ] REQ-017: In-app notification center
   - [ ] REQ-018: Push notifications (mobile)
   - [ ] REQ-019: SMS notifications
   
   Approve these requirements? (yes/edit)
   
4. Roadmap

   🗺 v1.1 Roadmap
   
   ### Phase 5: Notification System Core
   **Goal:** Database schema and notification service
   **Requirements:** REQ-011, REQ-015
   
   ### Phase 6: Email Delivery
   **Goal:** Email sending with templates
   **Requirements:** REQ-012, REQ-013, REQ-014, REQ-016
   
   ### Phase 7: Settings Integration
   **Goal:** User controls in settings page
   **Requirements:** REQ-011, REQ-015
   
   Note: Phase numbering continues from previous milestone
   
   Approve roadmap? (yes/edit)
   

   Phase numbers continue sequentially across milestones. v1.1 starts where v1.0 ended.

5. Update PROJECT.md

   ✓ PROJECT.md updated
   
   Added:
   - v1.1 milestone goals
   - Notification feature description
   
   Archived:
   - Previous "Next Milestone" section
   
6. Create Files

   ✓ Files created:
   - .planning/research/ (if research enabled)
   - .planning/REQUIREMENTS.md (v1.1 requirements)
   - .planning/ROADMAP.md (updated with v1.1 phases)
   - .planning/STATE.md (reset for new work)
   
   ✓ Committed changes
   
   Ready to start building:
   - /gsd:discuss-phase 5 - Capture implementation preferences
   - /gsd:plan-phase 5 - Research and plan first phase
   

Files Created/Updated

Created

• REQUIREMENTS.md - Fresh requirements for v1.1
• research/ - Domain investigation (if enabled)

Updated

• PROJECT.md - New milestone goals
• ROADMAP.md - New phases added (continues numbering)
• STATE.md - Reset for new milestone

Continuous Phase Numbering

Phase numbers never reset:

v1.0:
- Phase 1: Database Schema
- Phase 2: User Authentication
- Phase 3: Activity Dashboard
- Phase 4: Settings

v1.1:
- Phase 5: Notification System    ← Continues from 4
- Phase 6: Email Delivery
- Phase 7: Settings Integration

v2.0:
- Phase 8: Team Collaboration     ← Continues from 7
...

This provides:

• Unique identifiers across entire project history
• Clean git history (“feat(08-02): …”)
• Easy reference (“the bug from Phase 5”)

Milestone Workflow

The complete milestone cycle:

1. Build

   /gsd:discuss-phase N
   /gsd:plan-phase N
   /gsd:execute-phase N
   /gsd:verify-work N
   

   Repeat for each phase in the milestone.

2. Audit (Optional)

   /gsd:audit-milestone
   

   Verify requirements coverage and integration.

3. Close Gaps (If Needed)

   /gsd:plan-milestone-gaps
   

   Create phases for any missing requirements.

4. Complete

   /gsd:complete-milestone 1.0
   

   Archive work and tag release.

5. Start Next Cycle

   /gsd:new-milestone "v1.1 Feature Set"
   

   Begin next development milestone.

Milestone Audit

Before completing a milestone, audit verifies quality:

/gsd:audit-milestone

1. Requirements Coverage

   Checks that all v1 requirements have associated phases.

2. Cross-Phase Integration

   Verifies that phases work together correctly.

3. End-to-End Flows

   Confirms complete user workflows function.

Output: v{version}-MILESTONE-AUDIT.md with findings and recommendations.

Planning Gaps

If audit finds issues:

/gsd:plan-milestone-gaps

Creates new phases to close gaps before completion:

🔍 Gaps Found:
- REQ-008: Email notifications not implemented
- Integration: Dashboard missing user data

📋 Gap Closure Phases:

### Phase 8: Email Notification System
**Goal:** Deliver REQ-008
**Requirements:** REQ-008

### Phase 9: Dashboard Data Integration
**Goal:** Connect dashboard to user service
**Requirements:** [Integration fix]

Add these phases to roadmap? (yes/no)

Tips

Run audit before completion. Catching missing requirements before archiving is easier than retrofitting later.

Use semantic versioning. v1.0 for initial release, v1.1 for features, v2.0 for breaking changes.

Celebrate milestones. Each completion is a real achievement. Ship it, tag it, share it.

Don’t skip requirements definition in new-milestone. Starting a milestone without clear scope leads to scope creep and delays.

Next Steps

After completing a milestone:

New Milestone

Start the next development cycle

Check Progress

Review overall project status