diff --git a/commands/gsd/complete-milestone.md b/commands/gsd/complete-milestone.md
index bdf4b32d6..0a6c81d24 100644
--- a/commands/gsd/complete-milestone.md
+++ b/commands/gsd/complete-milestone.md
@@ -10,10 +10,10 @@ allowed-tools:
---
-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.
@@ -26,6 +26,7 @@ Output: Milestone archived, roadmap reorganized, git tagged.
**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 `` (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
- 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)
@@ -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
diff --git a/commands/gsd/discuss-milestone.md b/commands/gsd/discuss-milestone.md
index 2295eb73a..096beb85d 100644
--- a/commands/gsd/discuss-milestone.md
+++ b/commands/gsd/discuss-milestone.md
@@ -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
diff --git a/commands/gsd/new-milestone.md b/commands/gsd/new-milestone.md
index dd8c8f619..6c491a01a 100644
--- a/commands/gsd/new-milestone.md
+++ b/commands/gsd/new-milestone.md
@@ -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
---
-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
-@~/.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
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
-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`
+
+ `/clear` first → fresh context window
+
+ ---
+
+ **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
+
+ ---
+ ```
+
-
-- 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
-
+- User routed to define-requirements (or research-project)
+
diff --git a/get-shit-done/workflows/complete-milestone.md b/get-shit-done/workflows/complete-milestone.md
index 5ef439769..629376246 100644
--- a/get-shit-done/workflows/complete-milestone.md
+++ b/get-shit-done/workflows/complete-milestone.md
@@ -13,7 +13,8 @@ This is the ritual that separates "development" from "shipped."
1. templates/milestone.md
2. templates/milestone-archive.md
3. `.planning/ROADMAP.md`
-4. `.planning/PROJECT.md`
+4. `.planning/REQUIREMENTS.md`
+5. `.planning/PROJECT.md`
@@ -22,24 +23,31 @@ This is the ritual that separates "development" from "shipped."
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. Performs full PROJECT.md evolution review
-5. Offers to create next milestone inline
+2. Archives requirements to `.planning/milestones/v[X.Y]-REQUIREMENTS.md`
+3. Updates ROADMAP.md to replace milestone details with one-line summary
+4. Deletes REQUIREMENTS.md (fresh one created for next milestone)
+5. Performs full PROJECT.md evolution review
+6. 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
+- Result: ROADMAP.md stays constant size forever
+- Result: REQUIREMENTS.md is always milestone-scoped (not cumulative)
**Archive Format:**
-Uses `templates/milestone-archive.md` template with:
+**ROADMAP archive** uses `templates/milestone-archive.md` template with:
- Milestone header (status, phases, date)
- Full phase details from roadmap
- Milestone summary (decisions, issues, technical debt)
+**REQUIREMENTS archive** contains:
+- All v1 requirements marked complete with outcomes
+- Traceability table with final status
+- Notes on any requirements that changed during milestone
+
@@ -440,22 +448,88 @@ Extract completed milestone details and create archive file.
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
+7. Delete ROADMAP.md (fresh one created for next milestone):
+ ```bash
+ rm .planning/ROADMAP.md
+ ```
-8. Verify files:
- - Check archive file exists: `ls .planning/milestones/v[X.Y]-ROADMAP.md`
- - Validate ROADMAP.md still parseable
+8. Verify archive exists:
+ ```bash
+ ls .planning/milestones/v[X.Y]-ROADMAP.md
+ ```
-9. Confirm archive complete:
+9. Confirm roadmap archive complete:
```
- ✅ v[X.Y] archived to milestones/v[X.Y]-ROADMAP.md
+ ✅ v[X.Y] roadmap archived to milestones/v[X.Y]-ROADMAP.md
+ ✅ ROADMAP.md deleted (fresh one for next milestone)
```
+**Note:** Phase directories (`.planning/phases/`) are NOT deleted. They accumulate across milestones as the raw execution history. Phase numbering continues (v1.0 phases 1-4, v1.1 phases 5-8, etc.).
+
+
+
+
+
+Archive requirements and prepare for fresh requirements in next milestone.
+
+**Process:**
+
+1. Read current REQUIREMENTS.md:
+ ```bash
+ cat .planning/REQUIREMENTS.md
+ ```
+
+2. Create archive file: `.planning/milestones/v[X.Y]-REQUIREMENTS.md`
+
+3. Transform requirements for archive:
+ - Mark all v1 requirements as `[x]` complete
+ - Add outcome notes where relevant (validated, adjusted, dropped)
+ - Update traceability table status to "Complete" for all shipped requirements
+ - Add "Milestone Summary" section with:
+ - Total requirements shipped
+ - Any requirements that changed scope during milestone
+ - Any requirements dropped and why
+
+4. Write archive file with header:
+ ```markdown
+ # Requirements Archive: v[X.Y] [Milestone Name]
+
+ **Archived:** [DATE]
+ **Status:** ✅ SHIPPED
+
+ This is the archived requirements specification for v[X.Y].
+ For current requirements, see `.planning/REQUIREMENTS.md` (created for next milestone).
+
+ ---
+
+ [Full REQUIREMENTS.md content with checkboxes marked complete]
+
+ ---
+
+ ## Milestone Summary
+
+ **Shipped:** [X] of [Y] v1 requirements
+ **Adjusted:** [list any requirements that changed during implementation]
+ **Dropped:** [list any requirements removed and why]
+
+ ---
+ *Archived: [DATE] as part of v[X.Y] milestone completion*
+ ```
+
+5. Delete original REQUIREMENTS.md:
+ ```bash
+ rm .planning/REQUIREMENTS.md
+ ```
+
+6. Confirm:
+ ```
+ ✅ Requirements archived to milestones/v[X.Y]-REQUIREMENTS.md
+ ✅ REQUIREMENTS.md deleted (fresh one needed for next milestone)
+ ```
+
+**Important:** The next milestone workflow starts with `/gsd:define-requirements` to create a fresh REQUIREMENTS.md. PROJECT.md's Validated section carries the cumulative record across milestones.
+
@@ -526,26 +600,39 @@ git push origin v[X.Y]
-Commit milestone completion including archive file.
+Commit milestone completion including archive files and deletions.
```bash
-# Stage all milestone-related files
+# Stage archive files (new)
+git add .planning/milestones/v[X.Y]-ROADMAP.md
+git add .planning/milestones/v[X.Y]-REQUIREMENTS.md
+
+# Stage updated files
git add .planning/MILESTONES.md
git add .planning/PROJECT.md
-git add .planning/ROADMAP.md
git add .planning/STATE.md
-git add .planning/milestones/v[X.Y]-ROADMAP.md
+
+# Stage deletions
+git add -u .planning/
# Commit with descriptive message
git commit -m "$(cat <<'EOF'
chore: complete v[X.Y] milestone
-- Added MILESTONES.md entry
-- Evolved PROJECT.md with validated requirements
-- Reorganized ROADMAP.md with milestone grouping
-- Created milestone archive: milestones/v[X.Y]-ROADMAP.md
-- Updated STATE.md
-- Tagged v[X.Y]
+Archived:
+- milestones/v[X.Y]-ROADMAP.md
+- milestones/v[X.Y]-REQUIREMENTS.md
+
+Deleted (fresh for next milestone):
+- ROADMAP.md
+- REQUIREMENTS.md
+
+Updated:
+- MILESTONES.md (new entry)
+- PROJECT.md (requirements → Validated)
+- STATE.md (reset for next milestone)
+
+Tagged: v[X.Y]
EOF
)"
```
@@ -563,6 +650,10 @@ Shipped:
- [N] phases ([M] plans, [P] tasks)
- [One sentence of what shipped]
+Archived:
+- milestones/v[X.Y]-ROADMAP.md
+- milestones/v[X.Y]-REQUIREMENTS.md
+
Summary: .planning/MILESTONES.md
Tag: v[X.Y]
@@ -570,7 +661,7 @@ Tag: v[X.Y]
## ▶ Next Up
-**Plan Next Milestone** — define v[X.Y+1] features and scope
+**Discuss Next Milestone** — figure out what to build next
`/gsd:discuss-milestone`
@@ -578,8 +669,12 @@ Tag: v[X.Y]
---
-**Also available:**
-- `/gsd:new-milestone` — create directly if scope is clear
+**Next milestone flow:**
+1. `/gsd:discuss-milestone` — thinking partner, creates context file
+2. `/gsd:new-milestone` — update PROJECT.md with new goals
+3. `/gsd:research-project` — (optional) research ecosystem
+4. `/gsd:define-requirements` — scope what to build
+5. `/gsd:create-roadmap` — plan how to build it
---
```
@@ -630,13 +725,15 @@ Milestone completion is successful when:
- [ ] MILESTONES.md entry created with stats and accomplishments
- [ ] PROJECT.md full evolution review completed
-- [ ] All shipped requirements moved to Validated
+- [ ] All shipped requirements moved to Validated in PROJECT.md
- [ ] Key Decisions updated with outcomes
- [ ] ROADMAP.md reorganized with milestone grouping
-- [ ] Milestone archive created
+- [ ] Roadmap archive created (milestones/v[X.Y]-ROADMAP.md)
+- [ ] Requirements archive created (milestones/v[X.Y]-REQUIREMENTS.md)
+- [ ] REQUIREMENTS.md deleted (fresh for next milestone)
- [ ] STATE.md updated with fresh project reference
- [ ] Git tag created (v[X.Y])
-- [ ] Milestone commit made
-- [ ] User knows next steps
+- [ ] Milestone commit made (includes archive files and deletion)
+- [ ] User knows next steps (starting with /gsd:define-requirements)
diff --git a/get-shit-done/workflows/create-milestone.md b/get-shit-done/workflows/create-milestone.md
index 2f0ea8a5c..8a35ce711 100644
--- a/get-shit-done/workflows/create-milestone.md
+++ b/get-shit-done/workflows/create-milestone.md
@@ -1,17 +1,20 @@
-Create a new milestone for an existing project. Defines phases, updates roadmap, and resets state tracking for the new milestone.
+Start a new milestone cycle by updating PROJECT.md with new goals.
-This is used after completing a milestone when ready to define the next chunk of work.
+This is the brownfield equivalent of new-project. The project exists and has history.
+This workflow gathers "what's next" and updates PROJECT.md, then routes to the
+requirements → roadmap cycle.
**Read these files NOW:**
-1. ~/.claude/get-shit-done/templates/roadmap.md (milestone-grouped format)
-2. `.planning/ROADMAP.md`
-3. `.planning/STATE.md`
+1. ~/.claude/get-shit-done/references/questioning.md
+2. ~/.claude/get-shit-done/templates/project.md
+3. `.planning/PROJECT.md`
4. `.planning/MILESTONES.md` (if exists)
-
+5. `.planning/STATE.md`
+
@@ -19,363 +22,170 @@ This is used after completing a milestone when ready to define the next chunk of
Load project context:
```bash
-cat .planning/ROADMAP.md
-cat .planning/STATE.md
+cat .planning/PROJECT.md
cat .planning/MILESTONES.md 2>/dev/null || echo "No milestones file yet"
+cat .planning/STATE.md
cat .planning/MILESTONE-CONTEXT.md 2>/dev/null || echo "No milestone context file"
+cat .planning/config.json 2>/dev/null
```
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)
+- What shipped previously (from MILESTONES.md)
+- Current Validated requirements (from PROJECT.md)
+- Pending todos and blockers (from STATE.md)
+- Any context from discuss-milestone (MILESTONE-CONTEXT.md)
**Calculate next milestone version:**
+- Parse last version from MILESTONES.md
+- If v1.0 → suggest v1.1 (minor) or v2.0 (major)
+- If v1.3 → suggest v1.4 or v2.0
+
-- 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.
+- Use features and scope already gathered
+- Present summary for confirmation
+- Skip to confirm_goals step
-**If called directly (no MILESTONE-CONTEXT.md):**
-Ask for milestone details:
+**If no context file:**
-header: "Milestone Name"
-question: "What should we call this milestone?"
-options:
+Present what shipped:
+```
+Last milestone: v[X.Y] [Name]
+Key accomplishments:
+- [From MILESTONES.md]
-- "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
+Validated so far:
+- [From PROJECT.md Validated section]
-Get milestone name in format: "v[X.Y] [Name]"
+Pending todos:
+- [From STATE.md if any]
+```
+
+Ask (freeform, not AskUserQuestion):
+"What do you want to build in the next milestone?"
+
+Wait for response. Then use AskUserQuestion to explore:
+- Probe specific features mentioned
+- Ask about priorities
+- Surface constraints or dependencies
+- Clarify scope boundaries
+
+Continue until you have clear milestone goals.
-
-**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:
+
+Present gathered goals:
```
Milestone: v[X.Y] [Name]
-Phases:
-1. Phase [X]: [Name] - [goal]
-2. Phase [X+1]: [Name] - [goal]
-3. Phase [X+2]: [Name] - [goal]
+Goal: [One sentence focus]
-Does this feel right? (yes / adjust)
+Target features:
+- [Feature 1]
+- [Feature 2]
+- [Feature 3]
+
+Ready to update PROJECT.md? (yes / adjust)
```
-If "adjust": Ask what to change, revise, present again.
+If "adjust": return to gather_goals.
-
-Write new milestone details to `.planning/ROADMAP.md`.
+
+Update `.planning/PROJECT.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.
+**Add Current Milestone section** (after Core Value, before Requirements):
```markdown
-## Milestones
+## Current Milestone: v[X.Y] [Name]
-- ✅ **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)
+**Goal:** [One sentence describing milestone focus]
+
+**Target features:**
+- [Feature 1]
+- [Feature 2]
+- [Feature 3]
```
-**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.
+**Update Active requirements:**
+- Add new milestone goals to Active section
+- Keep existing Active items that weren't addressed
+- Don't remove anything from Validated
+**Update footer:**
```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 ...]
+---
+*Last updated: [date] after v[X.Y] milestone start*
```
-
-**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:**
+Update `.planning/STATE.md`:
```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
+Phase: Not started (run /gsd:create-roadmap)
+Plan: —
+Status: Defining requirements
+Last activity: [today] — Milestone v[X.Y] started
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
-```
-
+Keep Accumulated Context (decisions, blockers) from previous milestone.
-
-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:
+
+Delete temporary 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.
+
+```bash
+git add .planning/PROJECT.md .planning/STATE.md
+git commit -m "$(cat <<'EOF'
+docs: start milestone v[X.Y] [Name]
+
+Goal: [One sentence]
+Target features: [count] features
+EOF
+)"
+```
```
-Milestone v[X.Y] [Name] created:
-- Phases: [N]-[M] ([count] phases)
-- Directories created
-- ROADMAP.md updated
-- STATE.md reset for new milestone
+Milestone v[X.Y] [Name] initialized.
+
+PROJECT.md updated with:
+- Current Milestone section
+- Target features in Active requirements
---
## ▶ Next Up
-**Phase [N]: [Name]** — [Goal from ROADMAP.md]
+**Define Requirements** — scope v[X.Y] features into REQUIREMENTS.md
-`/gsd:plan-phase [N]`
+`/gsd:define-requirements`
`/clear` first → fresh context window
---
-**Also available:**
-- `/gsd:discuss-phase [N]` — gather context first
-- `/gsd:research-phase [N]` — investigate unknowns
-- Review roadmap
+**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
---
```
@@ -383,34 +193,11 @@ Milestone v[X.Y] [Name] created:
-
-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
+- PROJECT.md updated with Current Milestone section
+- Active requirements reflect new milestone goals
+- STATE.md reset for new milestone (keeps accumulated context)
+- MILESTONE-CONTEXT.md consumed and deleted (if existed)
+- Git commit made
+- User routed to define-requirements (or research-project)
-```
diff --git a/get-shit-done/workflows/create-roadmap.md b/get-shit-done/workflows/create-roadmap.md
index 08b80405e..be767795a 100644
--- a/get-shit-done/workflows/create-roadmap.md
+++ b/get-shit-done/workflows/create-roadmap.md
@@ -154,6 +154,17 @@ For quick depth:
**Phase Numbering System:**
+**Calculate starting phase number:**
+
+```bash
+# Find highest existing phase number from phases/ directory
+ls -d .planning/phases/[0-9]*-* 2>/dev/null | sort -V | tail -1 | grep -oE '[0-9]+' | head -1
+```
+
+- If phases/ is empty or doesn't exist: start at Phase 1
+- If phases exist from previous milestone: continue from last + 1
+- Example: v1.0 had phases 1-4, v1.1 starts at Phase 5
+
Use integer phases (1, 2, 3) for planned milestone work.
Use decimal phases (2.1, 2.2) for urgent insertions:
@@ -517,9 +528,14 @@ Write updated REQUIREMENTS.md.
-Create STATE.md — the project's living memory.
+Create or update STATE.md — the project's living memory.
-Use template from `~/.claude/get-shit-done/templates/state.md`.
+```bash
+[ -f .planning/STATE.md ] && echo "STATE_EXISTS" || echo "NEW_STATE"
+```
+
+**If STATE_EXISTS:** Update Current Position and keep Accumulated Context.
+**If NEW_STATE:** Create fresh using template from `~/.claude/get-shit-done/templates/state.md`.
Write to `.planning/STATE.md`:
diff --git a/get-shit-done/workflows/discuss-milestone.md b/get-shit-done/workflows/discuss-milestone.md
index 107def92b..3fb00e658 100644
--- a/get-shit-done/workflows/discuss-milestone.md
+++ b/get-shit-done/workflows/discuss-milestone.md
@@ -162,14 +162,6 @@ cat > .planning/MILESTONE-CONTEXT.md << 'EOF'
-
-## Phase Mapping
-
-- Phase [N]: [Feature/goal]
-- Phase [N+1]: [Feature/goal]
-- Phase [N+2]: [Feature/goal]
-
-
## Constraints
@@ -204,7 +196,6 @@ Milestone scope defined:
- [Feature 3]: [description]
**Suggested milestone:** v[X.Y] [Theme Name]
-**Estimated phases:** [N]
Context saved to `.planning/MILESTONE-CONTEXT.md`
@@ -226,11 +217,11 @@ Context saved to `.planning/MILESTONE-CONTEXT.md`
-- Project state loaded (STATE.md, ROADMAP.md)
+- Project state loaded (STATE.md, MILESTONES.md)
- Previous milestone context presented
- **Features identified** - What to build/add/fix (the substance)
- Features explored with clarifying questions
- Scope synthesized from features (not asked abstractly)
-- **MILESTONE-CONTEXT.md created** with features, scope, and phase mapping
+- **MILESTONE-CONTEXT.md created** with features and scope
- Context handed off to /gsd:new-milestone
diff --git a/get-shit-done/workflows/research-project.md b/get-shit-done/workflows/research-project.md
index 763ee4a6f..0a34d0b1f 100644
--- a/get-shit-done/workflows/research-project.md
+++ b/get-shit-done/workflows/research-project.md
@@ -49,11 +49,32 @@ Read PROJECT.md and extract:
3. **Core value**: What's the one thing that must work?
-4. **Requirements**: What did user explicitly request?
+4. **Milestone context**: Is this a subsequent milestone?
+ - Check for "Current Milestone" section → this is v1.1+, not greenfield
+ - Check for "Validated" requirements → these are DONE, don't research them
+ - Focus on "Current Milestone target features" and "Active" requirements
-5. **Constraints**: Any limitations on choices?
+5. **Requirements to research**:
+ - **If greenfield (no Validated):** Research all Active requirements
+ - **If subsequent milestone:** Research ONLY Current Milestone target features
-Present analysis:
+6. **Constraints**: Any limitations on choices?
+
+**For subsequent milestones, present:**
+```
+Milestone research context:
+
+- Project: [name]
+- Current milestone: v[X.Y] [Name]
+- Already built (Validated): [count] requirements
+- Researching (this milestone): [list target features]
+
+This research focuses on the NEW features for v[X.Y], not the existing system.
+
+Does this look right? (yes / adjust)
+```
+
+**For greenfield, present:**
```
Domain analysis:
@@ -67,7 +88,9 @@ Does this look right? (yes / adjust)
-Based on domain, generate 4 research questions:
+Generate research questions based on context:
+
+**For greenfield (v1.0):**
| Dimension | Question Template |
|-----------|-------------------|
@@ -76,11 +99,20 @@ Based on domain, generate 4 research questions:
| Architecture | "How are [domain] systems typically structured? What are the major components?" |
| Pitfalls | "What do [domain] projects commonly get wrong? What are the critical mistakes?" |
+**For subsequent milestones (v1.1+):**
+
+| Dimension | Question Template |
+|-----------|-------------------|
+| Stack | "What libraries/tools are needed to add [target features] to an existing [domain] app?" |
+| Features | "How do [target features] typically work in [domain]? What's expected behavior?" |
+| Architecture | "How do [target features] integrate with existing [domain] architecture?" |
+| Pitfalls | "What are common mistakes when adding [target features] to [domain]?" |
+
**Customize questions based on project specifics:**
-- If stack is stated: "How do you build [domain] with [stack]? What supporting libraries?"
+- If stack is stated: "How do you build [feature] with [stack]? What supporting libraries?"
- If specific features mentioned: "How do experts implement [feature] in [domain]?"
-- If constraints exist: "What's the best approach for [domain] given [constraint]?"
+- If constraints exist: "What's the best approach for [feature] given [constraint]?"
Present questions for approval:
```