refactor(milestone): rework milestone cycle for proper requirements flow

- complete-milestone: archive + delete ROADMAP.md and REQUIREMENTS.md
- new-milestone: brownfield new-project (updates PROJECT.md, routes to requirements)
- discuss-milestone: now required before new-milestone (creates context file)
- research-project: milestone-aware (focuses on new features, not validated ones)
- create-roadmap: continues phase numbering from previous milestone

Flow: complete → discuss → new-milestone → research → requirements → roadmap

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
This commit is contained in:
Lex Christopherson
2026-01-15 12:57:33 -06:00
parent c986eae851
commit 2d3a1eadda
8 changed files with 441 additions and 430 deletions

View File

@@ -10,10 +10,10 @@ allowed-tools:
---
<objective>
Mark milestone {{version}} complete, archive to milestones/, and update ROADMAP.md.
Mark milestone {{version}} complete, archive to milestones/, and update ROADMAP.md and REQUIREMENTS.md.
Purpose: Create historical record of shipped version, collapse completed work in roadmap, and prepare for next milestone.
Output: Milestone archived, roadmap reorganized, git tagged.
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.
</objective>
<execution_context>
@@ -26,6 +26,7 @@ Output: Milestone archived, roadmap reorganized, git tagged.
<context>
**Project files:**
- `.planning/ROADMAP.md`
- `.planning/REQUIREMENTS.md`
- `.planning/STATE.md`
- `.planning/PROJECT.md`
@@ -85,36 +86,43 @@ Output: Milestone archived, roadmap reorganized, git tagged.
- Extract full phase details from ROADMAP.md
- Fill milestone-archive.md template
- Update ROADMAP.md to one-line summary with link
- Offer to create next milestone
5. **Update PROJECT.md:**
5. **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)
6. **Update PROJECT.md:**
- Add "Current State" section with shipped version
- Add "Next Milestone Goals" section
- Archive previous content in `<details>` (if v1.1+)
6. **Commit and tag:**
7. **Commit and tag:**
- Stage: MILESTONES.md, PROJECT.md, ROADMAP.md, STATE.md, archive file
- 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
7. **Offer next steps:**
- Plan next milestone
- Archive planning
- Done for now
8. **Offer next steps:**
- `/gsd:discuss-milestone` — thinking partner, creates context file
- Then `/gsd:new-milestone` — update PROJECT.md with new goals
</process>
<success_criteria>
- 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
- Commit successful
- User knows next steps
- User knows next steps (including need for fresh requirements)
</success_criteria>
<critical_rules>
@@ -122,7 +130,8 @@ Output: Milestone archived, roadmap reorganized, git tagged.
- **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 collapsing:** Always create archive file before updating ROADMAP.md
- **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 constant size
- **Context efficiency:** Archive keeps ROADMAP.md and REQUIREMENTS.md constant size per milestone
- **Fresh requirements:** Next milestone starts with `/gsd:define-requirements`, not reusing old file
</critical_rules>

View File

@@ -19,8 +19,8 @@ Output: Context gathered, then routes to /gsd:new-milestone
**Load project state first:**
@.planning/STATE.md
**Load roadmap:**
@.planning/ROADMAP.md
**Load project:**
@.planning/PROJECT.md
**Load milestones (if exists):**
@.planning/MILESTONES.md

View File

@@ -1,59 +1,138 @@
---
name: gsd:new-milestone
description: Create a new milestone with phases for an existing project
argument-hint: "[milestone name, e.g., 'v2.0 Features']"
description: Start a new milestone cycle — update PROJECT.md and route to requirements
argument-hint: "[milestone name, e.g., 'v1.1 Notifications']"
allowed-tools:
- Read
- Write
- Bash
- AskUserQuestion
---
<objective>
Create a new milestone for an existing project with defined phases.
Start a new milestone by updating PROJECT.md with new goals, then routing to the requirements → roadmap cycle.
Purpose: After completing a milestone (or when ready to define next chunk of work), creates the milestone structure in ROADMAP.md with phases, updates STATE.md, and creates phase directories.
Output: New milestone in ROADMAP.md, updated STATE.md, phase directories created
This is the brownfield equivalent of new-project. The project exists, PROJECT.md has history. This command gathers "what's next" and updates PROJECT.md to reflect the new milestone's goals.
Output: Updated PROJECT.md, routes to research-project or define-requirements
</objective>
<execution_context>
@~/.claude/get-shit-done/workflows/create-milestone.md
@~/.claude/get-shit-done/templates/roadmap.md
@~/.claude/get-shit-done/references/questioning.md
@~/.claude/get-shit-done/templates/project.md
</execution_context>
<context>
Milestone name: $ARGUMENTS (optional - will prompt if not provided)
**Load project state first:**
**Load project context:**
@.planning/PROJECT.md
@.planning/STATE.md
**Load roadmap:**
@.planning/ROADMAP.md
**Load milestones (if exists):**
@.planning/MILESTONES.md
@.planning/config.json
</context>
<process>
1. Load project context (STATE.md, ROADMAP.md, MILESTONES.md)
2. Calculate next milestone version and starting phase number
3. If milestone name provided in arguments, use it; otherwise prompt
4. Gather phases (per depth setting: quick 3-5, standard 5-8, comprehensive 8-12):
- If called from /gsd:discuss-milestone, use provided context
- Otherwise, prompt for phase breakdown
5. Detect research needs for each phase
6. Confirm phases (respect config.json gate settings)
7. Follow create-milestone.md workflow:
- Update ROADMAP.md with new milestone section
- Create phase directories
- Update STATE.md for new milestone
- Git commit milestone creation
8. Offer next steps (discuss first phase, plan first phase, review)
1. **Load context:**
- Read PROJECT.md (existing project, Validated requirements, decisions)
- Read MILESTONES.md (what shipped previously)
- Read STATE.md (pending todos, blockers)
- Check for MILESTONE-CONTEXT.md (from /gsd:discuss-milestone)
2. **Gather milestone goals:**
**If MILESTONE-CONTEXT.md exists:**
- Use features and scope from discuss-milestone
- Present summary for confirmation
**If no context file:**
- Present what shipped in last milestone
- Ask: "What do you want to build next?"
- Use AskUserQuestion to explore features
- Probe for priorities, constraints, scope
3. **Determine milestone version:**
- Parse last version from MILESTONES.md
- Suggest next version (v1.0 → v1.1, or v2.0 for major)
- Confirm with user
4. **Update PROJECT.md:**
Add/update these sections:
```markdown
## Current Milestone: v[X.Y] [Name]
**Goal:** [One sentence describing milestone focus]
**Target features:**
- [Feature 1]
- [Feature 2]
- [Feature 3]
```
Update Active requirements section with new goals.
Update "Last updated" footer.
5. **Update STATE.md:**
```markdown
## Current Position
Phase: Not started (run /gsd:create-roadmap)
Plan: —
Status: Defining requirements
Last activity: [today] — Milestone v[X.Y] started
```
6. **Cleanup:**
- Delete MILESTONE-CONTEXT.md if exists (consumed)
7. **Git commit:**
```bash
git add .planning/PROJECT.md .planning/STATE.md
git commit -m "docs: start milestone v[X.Y] [Name]"
```
8. **Route to next step:**
```
Milestone v[X.Y] [Name] initialized.
PROJECT.md updated with new goals.
---
## ▶ Next Up
**Define Requirements** — scope v[X.Y] features
`/gsd:define-requirements`
<sub>`/clear` first → fresh context window</sub>
---
**Or research first:**
- `/gsd:research-project` — investigate ecosystem before scoping
**Full flow:**
1. `/gsd:define-requirements` — create REQUIREMENTS.md
2. `/gsd:create-roadmap` — create ROADMAP.md with phases
3. `/gsd:plan-phase [N]` — start execution
---
```
</process>
<success_criteria>
- Next phase number calculated correctly (continues from previous milestone)
- 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
- PROJECT.md updated with Current Milestone section
- Active requirements reflect new milestone goals
- STATE.md reset for new milestone
- MILESTONE-CONTEXT.md consumed and deleted (if existed)
- Git commit made
- User knows next steps
</success_criteria>
- User routed to define-requirements (or research-project)
</success_criteria>