From 2d3a1eaddae394f9d5114a2233d93ae7b27ec051 Mon Sep 17 00:00:00 2001 From: Lex Christopherson Date: Thu, 15 Jan 2026 12:57:33 -0600 Subject: [PATCH] refactor(milestone): rework milestone cycle for proper requirements flow MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit - 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 --- commands/gsd/complete-milestone.md | 37 +- commands/gsd/discuss-milestone.md | 4 +- commands/gsd/new-milestone.md | 149 ++++-- get-shit-done/workflows/complete-milestone.md | 165 +++++-- get-shit-done/workflows/create-milestone.md | 439 +++++------------- get-shit-done/workflows/create-roadmap.md | 20 +- get-shit-done/workflows/discuss-milestone.md | 13 +- get-shit-done/workflows/research-project.md | 44 +- 8 files changed, 441 insertions(+), 430 deletions(-) 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: ```