Create a new milestone for an existing project. Defines phases, updates roadmap, and resets state tracking for the new milestone. This is used after completing a milestone when ready to define the next chunk of work. **Read these files NOW:** 1. ~/.claude/get-shit-done/templates/roadmap.md (milestone-grouped format) 2. `.planning/ROADMAP.md` 3. `.planning/STATE.md` 4. `.planning/MILESTONES.md` (if exists) Load project context: ```bash cat .planning/ROADMAP.md cat .planning/STATE.md cat .planning/MILESTONES.md 2>/dev/null || echo "No milestones file yet" cat .planning/MILESTONE-CONTEXT.md 2>/dev/null || echo "No milestone context file" ``` Extract: - Previous milestone version (e.g., v1.0) - Last phase number used - Pending todos from STATE.md - Project context from PROJECT.md (What This Is, Core Value) **Check for milestone context from discuss-milestone:** If `.planning/MILESTONE-CONTEXT.md` exists: - This contains context from `/gsd:discuss-milestone` - Extract: features, suggested name, phase mapping, constraints - Use this to pre-populate milestone details (skip prompting for info already gathered) **Calculate next milestone version:** - If previous was v1.0 → suggest v1.1 (minor) or v2.0 (major) - If previous was v1.3 → suggest v1.4 or v2.0 - Parse from ROADMAP.md "Completed Milestones" section **If MILESTONE-CONTEXT.md exists (from /gsd:discuss-milestone):** Use the features, scope, and constraints from the context file. Use the suggested milestone name from `` section. Use the phase mapping from `` section. **If called directly (no MILESTONE-CONTEXT.md):** Ask for milestone details: header: "Milestone Name" question: "What should we call this milestone?" options: - "v[X.Y] Features" - Adding new functionality - "v[X.Y] Improvements" - Enhancing existing features - "v[X.Y] Fixes" - Bug fixes and stability - "v[X.Y] Refactor" - Code quality and architecture - "v[X.Y+1].0 [Major]" - Major version bump - "Other" - Custom name Get milestone name in format: "v[X.Y] [Name]" **Calculate starting phase number:** ```bash # Find highest phase number from roadmap grep -E "^### Phase [0-9]+" .planning/ROADMAP.md | tail -1 # Extract number, add 1 ``` Next phase starts at: [last_phase + 1] **Check depth setting and gather phases accordingly:** ```bash cat .planning/config.json 2>/dev/null | grep depth ``` | Depth | Phases/Milestone | |-------|------------------| | Quick | 3-5 | | Standard | 5-8 | | Comprehensive | 8-12 | If context from discuss-milestone provided, use that scope. Otherwise, ask: ``` What phases should this milestone include? Starting at Phase [N]: - Phase [N]: [name] - [one-line goal] - Phase [N+1]: [name] - [one-line goal] ... Describe the phases, or say "help me break this down" for guidance. ``` For each phase, capture: - Phase number (continuing sequence) - Phase name (kebab-case for directory) - One-line goal - Research flag (Likely/Unlikely based on triggers) **For each phase, determine if research is likely needed.** Apply research triggers from create-roadmap.md: **Likely (flag the phase):** | Trigger Pattern | Why Research Needed | | ----------------------------------------------------- | --------------------------------------- | | "integrate [service]", "connect to [API]" | External API - need current docs | | "authentication", "auth", "login", "JWT" | Architectural decision + library choice | | "payment", "billing", "Stripe", "subscription" | External API + compliance patterns | | "email", "SMS", "notifications", "SendGrid", "Twilio" | External service integration | | "database", "Postgres", "MongoDB", "Supabase" | If new to project - setup patterns | | "real-time", "websocket", "sync", "live updates" | Architectural decision | | "deploy", "Vercel", "Railway", "hosting" | If first deployment - config patterns | | "choose between", "select", "evaluate", "which" | Explicit decision needed | | "AI", "OpenAI", "Claude", "LLM", "embeddings" | Fast-moving APIs - need current docs | | Any technology not already in codebase | New integration | **Unlikely (no flag needed):** | Pattern | Why No Research | | ------------------------------------------- | ----------------------- | | "add button", "create form", "update UI" | Internal patterns | | "CRUD operations", "list/detail views" | Standard patterns | | "refactor", "reorganize", "clean up" | Internal work | | "following existing patterns" | Conventions established | | Technology already in package.json/codebase | Patterns exist | Present research assessment: ``` Research needs detected: Phase [N]: [Name] Research: Unlikely (internal patterns) Phase [N+1]: [Name] Research: Likely (new API integration) Topics: [What to investigate] Does this look right? (yes / adjust) ``` ```bash cat .planning/config.json 2>/dev/null ``` ``` ⚡ Auto-approved: Milestone phases ([N] phases) 1. Phase [X]: [Name] - [goal] 2. Phase [X+1]: [Name] - [goal] ... Proceeding to create milestone structure... ``` Proceed directly to update_roadmap step. Present the phase breakdown: ``` Milestone: v[X.Y] [Name] Phases: 1. Phase [X]: [Name] - [goal] 2. Phase [X+1]: [Name] - [goal] 3. Phase [X+2]: [Name] - [goal] Does this feel right? (yes / adjust) ``` If "adjust": Ask what to change, revise, present again. Write new milestone details to `.planning/ROADMAP.md`. **File to update:** `.planning/ROADMAP.md` The main ROADMAP.md file holds full phase details for the active milestone. Archive files in `milestones/` are created only when a milestone ships (via `/gsd:complete-milestone`). **Process:** **1. Update Milestones section:** Add the new milestone to the milestones list. Completed milestones show as links to their archive files, new milestone shows as in-progress. ```markdown ## Milestones - ✅ **v1.0 [Previous]** - [link to milestones/v1.0-ROADMAP.md] (Phases 1-9, shipped YYYY-MM-DD) - 🚧 **v[X.Y] [Name]** - Phases [N]-[M] (in progress) ``` **2. Add full phase details:** Write complete phase sections for all phases in this milestone. Each phase gets full details including goal, dependencies, research assessment, and plan placeholders. ```markdown ### 🚧 v[X.Y] [Name] (In Progress) **Milestone Goal:** [One sentence describing what this milestone delivers] #### Phase [N]: [Name] **Goal**: [What this phase delivers] **Depends on**: Phase [N-1] (or "Previous milestone complete") **Research**: [Likely/Unlikely] ([reason]) **Research topics**: [If Likely, what to investigate] **Plans**: TBD Plans: - [ ] [N]-01: TBD (run /gsd:plan-phase [N] to break down) #### Phase [N+1]: [Name] **Goal**: [What this phase delivers] **Depends on**: Phase [N] **Research**: [Likely/Unlikely] ([reason]) **Plans**: TBD Plans: - [ ] [N+1]-01: TBD [... continue for all phases in this milestone ...] ``` **3. Update Progress table:** Add rows for all new phases with milestone attribution. ```markdown | Phase | Milestone | Plans | Status | Completed | | ------------- | --------- | ----- | ----------- | --------- | | [N]. [Name] | v[X.Y] | 0/? | Not started | - | | [N+1]. [Name] | v[X.Y] | 0/? | Not started | - | ``` Create directories for new phases: ```bash mkdir -p .planning/phases/[NN]-[slug] mkdir -p .planning/phases/[NN+1]-[slug] # ... for each phase ``` Use two-digit padding: `10-name`, `11-name`, etc. Update `.planning/STATE.md` for new milestone: **Update Current Position:** ```markdown ## Current Position Phase: [N] of [M] ([First phase name]) Plan: Not started Status: Ready to plan Last activity: [today's date] - Milestone v[X.Y] created Progress: ░░░░░░░░░░ 0% ``` **Update Accumulated Context:** Keep decisions from previous milestone (they're historical record). Clear "Blockers/Concerns Carried Forward" section. **Add to Roadmap Evolution:** ```markdown ### Roadmap Evolution - Milestone v[X.Y] created: [theme/focus], [N] phases (Phase [start]-[end]) ``` **Update Session Continuity:** ```markdown ## Session Continuity Last session: [today's date and time] Stopped at: Milestone v[X.Y] initialization Resume file: None ``` Commit milestone creation: ```bash git add .planning/ROADMAP.md .planning/STATE.md git add .planning/phases/ git commit -m "$(cat <<'EOF' docs: create milestone v[X.Y] [Name] ([N] phases) Phases: - [N]. [name]: [goal] - [N+1]. [name]: [goal] - [N+2]. [name]: [goal] EOF )" ``` Confirm: "Committed: docs: create milestone v[X.Y] [Name]" Delete the temporary milestone context file if it exists: ```bash rm -f .planning/MILESTONE-CONTEXT.md ``` This file was a handoff artifact from `/gsd:discuss-milestone`. Now that the milestone is created, the context is persisted in ROADMAP.md and the temporary file is no longer needed. ``` Milestone v[X.Y] [Name] created: - Phases: [N]-[M] ([count] phases) - Directories created - ROADMAP.md updated - STATE.md reset for new milestone --- ## ▶ Next Up **Phase [N]: [Name]** — [Goal from ROADMAP.md] `/gsd:plan-phase [N]` `/clear` first → fresh context window --- **Also available:** - `/gsd:discuss-phase [N]` — gather context first - `/gsd:research-phase [N]` — investigate unknowns - Review roadmap --- ``` Use `XX-kebab-case-name` format with continuous numbering: - `10-user-profiles` - `11-notifications` - `12-analytics` Numbers continue from previous milestone. Names describe content. - Don't restart phase numbering at 01 (continue sequence) - Don't add time estimates - Don't create Gantt charts - Respect depth setting for phase count (quick: 3-5, standard: 5-8, comprehensive: 8-12) - Don't modify completed milestone sections Milestones are coherent chunks of work, not project management artifacts. Milestone creation is complete when: - [ ] Next phase number calculated correctly (continues from previous) - [ ] Phases defined per depth setting (quick: 3-5, standard: 5-8, comprehensive: 8-12) - [ ] Research flags assigned for each phase - [ ] ROADMAP.md updated with new milestone section - [ ] Phase directories created - [ ] STATE.md reset for new milestone - [ ] Git commit made - [ ] User knows next steps ```