fix: persist milestone discussion context across /clear (#11)

- Add MILESTONE-CONTEXT.md template for handoff between commands
- discuss-milestone now writes context to .planning/MILESTONE-CONTEXT.md
- create-milestone reads context file and deletes after use

Fixes #11

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

get-shit-done/templates/milestone-context.md

@@ -0,0 +1,93 @@
+# Milestone Context Template
+
+Template for `.planning/MILESTONE-CONTEXT.md` - temporary handoff file from discuss-milestone to create-milestone.
+
+**Purpose:** Persist milestone discussion context so `/clear` can be used between commands. This file is consumed by `/gsd:new-milestone` and deleted after the milestone is created.
+
+---
+
+## File Template
+
+```markdown
+# Milestone Context
+
+**Generated:** [date]
+**Status:** Ready for /gsd:new-milestone
+
+<features>
+## Features to Build
+
+[Features identified during discussion - the substance of this milestone]
+
+- **[Feature 1]**: [description]
+- **[Feature 2]**: [description]
+- **[Feature 3]**: [description]
+
+</features>
+
+<scope>
+## Scope
+
+**Suggested name:** v[X.Y] [Theme Name]
+**Estimated phases:** [N]
+**Focus:** [One sentence theme/focus]
+
+</scope>
+
+<phase_mapping>
+## Phase Mapping
+
+[How features map to phases - rough breakdown]
+
+- Phase [N]: [Feature/goal]
+- Phase [N+1]: [Feature/goal]
+- Phase [N+2]: [Feature/goal]
+
+</phase_mapping>
+
+<constraints>
+## Constraints
+
+[Any constraints or boundaries mentioned during discussion]
+
+- [Constraint 1]
+- [Constraint 2]
+
+</constraints>
+
+<notes>
+## Additional Context
+
+[Anything else captured during discussion that informs the milestone]
+
+</notes>
+
+---
+
+*This file is temporary. It will be deleted after /gsd:new-milestone creates the milestone.*
+```
+
+<guidelines>
+**This is a handoff artifact, not permanent documentation.**
+
+The file exists only to pass context from `discuss-milestone` to `create-milestone` across a `/clear` boundary.
+
+**Lifecycle:**
+1. `/gsd:discuss-milestone` creates this file at end of discussion
+2. User runs `/clear` (safe now - context is persisted)
+3. `/gsd:new-milestone` reads this file
+4. `/gsd:new-milestone` uses context to populate milestone
+5. `/gsd:new-milestone` deletes this file after successful creation
+
+**Content should include:**
+- Features identified (the core of what to build)
+- Suggested milestone name/theme
+- Rough phase mapping
+- Any constraints or scope boundaries
+- Notes from discussion
+
+**Content should NOT include:**
+- Technical analysis (that comes during phase research)
+- Detailed phase specifications (create-milestone handles that)
+- Implementation details
+</guidelines>

get-shit-done/workflows/create-milestone.md

@@ -22,6 +22,7 @@ Load project context:
 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:
@@ -31,6 +32,13 @@ Extract:
 - Deferred issues 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)
@@ -39,11 +47,12 @@ Extract:
   </step>
 
 <step name="get_milestone_info">
-**If called from /gsd:discuss-milestone (context provided):**
-Use the theme, scope, and constraints from discussion.
-Suggest milestone name based on theme.
+**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 `<scope>` section.
+Use the phase mapping from `<phase_mapping>` section.
 
-**If called directly (no prior context):**
+**If called directly (no MILESTONE-CONTEXT.md):**
 Ask for milestone details:
 
 header: "Milestone Name"
@@ -333,6 +342,16 @@ EOF
 Confirm: "Committed: docs: create milestone v[X.Y] [Name]"
 </step>
 
+<step name="cleanup_context">
+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.
+</step>
+
 <step name="offer_next">
 ```
 Milestone v[X.Y] [Name] created:

get-shit-done/workflows/discuss-milestone.md

@@ -122,6 +122,76 @@ If "Let me add context" → receive input → return to step 2.
 Loop until "Create milestone" selected.
 </step>
 
+<step name="write_context">
+Write milestone context to file for handoff.
+
+**File:** `.planning/MILESTONE-CONTEXT.md`
+
+Use template from ~/.claude/get-shit-done/templates/milestone-context.md
+
+Populate with:
+- Features identified during discussion
+- Suggested milestone name and theme
+- Estimated phase count
+- How features map to phases
+- Any constraints or scope boundaries mentioned
+
+```bash
+# Write the context file
+cat > .planning/MILESTONE-CONTEXT.md << 'EOF'
+# Milestone Context
+
+**Generated:** [today's date]
+**Status:** Ready for /gsd:new-milestone
+
+<features>
+## Features to Build
+
+- **[Feature 1]**: [description]
+- **[Feature 2]**: [description]
+- **[Feature 3]**: [description]
+
+</features>
+
+<scope>
+## Scope
+
+**Suggested name:** v[X.Y] [Theme Name]
+**Estimated phases:** [N]
+**Focus:** [One sentence theme/focus]
+
+</scope>
+
+<phase_mapping>
+## Phase Mapping
+
+- Phase [N]: [Feature/goal]
+- Phase [N+1]: [Feature/goal]
+- Phase [N+2]: [Feature/goal]
+
+</phase_mapping>
+
+<constraints>
+## Constraints
+
+- [Any constraints mentioned]
+
+</constraints>
+
+<notes>
+## Additional Context
+
+[Anything else from discussion]
+
+</notes>
+
+---
+
+*This file is temporary. It will be deleted after /gsd:new-milestone creates the milestone.*
+EOF
+```
+</step>
+
 <step name="handoff">
 Present summary and hand off to create-milestone:
 
@@ -136,7 +206,7 @@ Milestone scope defined:
 **Suggested milestone:** v[X.Y] [Theme Name]
 **Estimated phases:** [N]
 
-Ready to create the milestone structure.
+Context saved to `.planning/MILESTONE-CONTEXT.md`
 
 ---
 
@@ -150,11 +220,6 @@ Ready to create the milestone structure.
 
 ---
 ```
-
-Pass context forward by summarizing:
-- Features to build (the substance)
-- Suggested milestone name
-- How features map to phases
 </step>
 
 </process>
@@ -166,5 +231,6 @@ Pass context forward by summarizing:
 - **Features identified** - What to build/add/fix (the substance)
 - Features explored with clarifying questions
 - Scope synthesized from features (not asked abstractly)
-- Context handed off to /gsd:new-milestone with feature list
+- **MILESTONE-CONTEXT.md created** with features, scope, and phase mapping
+- Context handed off to /gsd:new-milestone
 </success_criteria>