diff --git a/commands/gsd/new-project.md b/commands/gsd/new-project.md index 04377986e..068c43b8c 100644 --- a/commands/gsd/new-project.md +++ b/commands/gsd/new-project.md @@ -8,24 +8,28 @@ allowed-tools: --- + Initialize a new project through comprehensive context gathering. This is the most leveraged moment in any project. Deep questioning here means better plans, better execution, better outcomes. Creates `.planning/` with PROJECT.md and config.json. + + @~/.claude/get-shit-done/references/principles.md @~/.claude/get-shit-done/references/questioning.md @~/.claude/get-shit-done/templates/project.md @~/.claude/get-shit-done/templates/config.json - + + **MANDATORY FIRST STEP — Execute these checks before ANY user interaction:** 1. **Abort if project exists:** @@ -53,9 +57,11 @@ Creates `.planning/` with PROJECT.md and config.json. ``` **You MUST run all bash commands above using the Bash tool before proceeding.** + + **If existing code detected and .planning/codebase/ doesn't exist:** Check the results from setup step: @@ -66,8 +72,8 @@ Use AskUserQuestion: - header: "Existing Code" - question: "I detected existing code in this directory. Would you like to map the codebase first?" - options: - - "Map codebase first" - Run /gsd:map-codebase to understand existing architecture (Recommended) - - "Skip mapping" - Proceed with project initialization + - "Map codebase first" — Run /gsd:map-codebase to understand existing architecture (Recommended) + - "Skip mapping" — Proceed with project initialization **If "Map codebase first":** ``` @@ -78,10 +84,12 @@ Exit command. **If "Skip mapping":** Continue to question step. **If no existing code detected OR codebase already mapped:** Continue to question step. + -**1. Open (FREEFORM - do NOT use AskUserQuestion):** + +**1. Open (FREEFORM — do NOT use AskUserQuestion):** Ask inline: "What do you want to build?" @@ -121,22 +129,97 @@ Use AskUserQuestion: - header: "Ready?" - question: "Ready to create PROJECT.md, or explore more?" - options (ALL THREE REQUIRED): - - "Create PROJECT.md" - Finalize and continue - - "Ask more questions" - I'll dig deeper - - "Let me add context" - You have more to share + - "Create PROJECT.md" — Finalize and continue + - "Ask more questions" — I'll dig deeper + - "Let me add context" — You have more to share If "Ask more questions" → check coverage gaps from `questioning.md` → return to step 2. If "Let me add context" → receive input via their response → return to step 2. Loop until "Create PROJECT.md" selected. + + Synthesize all context into `.planning/PROJECT.md` using the template from `templates/project.md`. +**For greenfield projects:** + +Initialize requirements as hypotheses: + +```markdown +## Requirements + +### Validated + +(None yet — ship to validate) + +### Active + +- [ ] [Requirement 1] +- [ ] [Requirement 2] +- [ ] [Requirement 3] + +### Out of Scope + +- [Exclusion 1] — [why] +- [Exclusion 2] — [why] +``` + +All Active requirements are hypotheses until shipped and validated. + +**For brownfield projects (codebase map exists):** + +Infer Validated requirements from existing code: + +1. Read `.planning/codebase/ARCHITECTURE.md` and `STACK.md` +2. Identify what the codebase already does +3. These become the initial Validated set + +```markdown +## Requirements + +### Validated + +- ✓ [Existing capability 1] — existing +- ✓ [Existing capability 2] — existing +- ✓ [Existing capability 3] — existing + +### Active + +- [ ] [New requirement 1] +- [ ] [New requirement 2] + +### Out of Scope + +- [Exclusion 1] — [why] +``` + +**Key Decisions:** + +Initialize with any decisions made during questioning: + +```markdown +## Key Decisions + +| Decision | Rationale | Outcome | +|----------|-----------|---------| +| [Choice from questioning] | [Why] | — Pending | +``` + +**Last updated footer:** + +```markdown +--- +*Last updated: [date] after initialization* +``` + Do not compress. Capture everything gathered. + + Ask workflow mode preference: Use AskUserQuestion: @@ -144,13 +227,15 @@ Use AskUserQuestion: - header: "Mode" - question: "How do you want to work?" - options: - - "Interactive" - Confirm at each step - - "YOLO" - Auto-approve, just execute + - "Interactive" — Confirm at each step + - "YOLO" — Auto-approve, just execute Create `.planning/config.json` with chosen mode using `templates/config.json` structure. + + ```bash git add .planning/PROJECT.md .planning/config.json git commit -m "$(cat <<'EOF' @@ -158,14 +243,15 @@ docs: initialize [project-name] [One-liner from PROJECT.md] -Creates PROJECT.md with vision and requirements. +Creates PROJECT.md with requirements and constraints. EOF )" - ``` + + Present completion with next steps (see ~/.claude/get-shit-done/references/continuation-format.md): ``` @@ -187,19 +273,25 @@ Project initialized: --- ``` + + - `.planning/PROJECT.md` - `.planning/config.json` + + - [ ] Deep questioning completed (not rushed) -- [ ] PROJECT.md captures full context +- [ ] PROJECT.md captures full context with evolutionary structure +- [ ] Requirements initialized as hypotheses (greenfield) or with inferred Validated (brownfield) +- [ ] Key Decisions table initialized - [ ] config.json has workflow mode - [ ] All committed to git + -``` diff --git a/commands/gsd/progress.md b/commands/gsd/progress.md index fa3a003d0..9b800f3ae 100644 --- a/commands/gsd/progress.md +++ b/commands/gsd/progress.md @@ -38,7 +38,7 @@ If missing STATE.md or ROADMAP.md: inform what's missing, suggest running `/gsd: - Read `.planning/STATE.md` for living memory (position, decisions, issues) - Read `.planning/ROADMAP.md` for phase structure and objectives -- Read `.planning/PROJECT.md` for project vision (brief summary only) +- Read `.planning/PROJECT.md` for current state (What This Is, Core Value, Requirements) diff --git a/get-shit-done/templates/project.md b/get-shit-done/templates/project.md index 50f60c4f8..8971f4528 100644 --- a/get-shit-done/templates/project.md +++ b/get-shit-done/templates/project.md @@ -1,207 +1,184 @@ # PROJECT.md Template -Template for `.planning/PROJECT.md` - the full project context captured during initialization. +Template for `.planning/PROJECT.md` — the living project context document. -## Greenfield Project (v1.0) + -**Greenfield:** -- Don't compress - capture everything from questioning -- Use user's words - preserve their language and framing -- Be specific - vague inputs create vague outputs -- Include rationale - "what" without "why" loses context -- Mark unknowns - open questions are valuable, not failures -**Brownfield:** -- Current State shows real-world context (shipped, users, feedback) -- v[Next] Goals focuses on the upcoming work -- Original Vision collapsed in `
` for reference -- Checkboxes marked [x] for achieved goals -- This makes all plans brownfield-aware automatically - +**What This Is:** +- Current accurate description of the product +- 2-3 sentences capturing what it does and who it's for +- Use the user's words and framing +- Update when the product evolves beyond this description - -When creating STATE.md, extract a summary from PROJECT.md: +**Core Value:** +- The single most important thing +- Everything else can fail; this cannot +- Drives prioritization when tradeoffs arise +- Rarely changes; if it does, it's a significant pivot -**Building:** [One-liner from Vision] +**Requirements — Validated:** +- Requirements that shipped and proved valuable +- Format: `- ✓ [Requirement] — [version/phase]` +- These are locked — changing them requires explicit discussion -**Core requirements:** -- [Top 3 from Success Criteria] +**Requirements — Active:** +- Current scope being built toward +- These are hypotheses until shipped and validated +- Move to Validated when shipped, Out of Scope if invalidated + +**Requirements — Out of Scope:** +- Explicit boundaries on what we're not building +- Always include reasoning (prevents re-adding later) +- Includes: considered and rejected, deferred to future, explicitly excluded + +**Context:** +- Background that informs implementation decisions +- Technical environment, prior work, user feedback +- Known issues or technical debt to address +- Update as new context emerges **Constraints:** -- [Key constraints] +- Hard limits on implementation choices +- Tech stack, timeline, budget, compatibility, dependencies +- Include the "why" — constraints without rationale get questioned -This goes in STATE.md's immutable "Project Summary" section. - +**Key Decisions:** +- Significant choices that affect future work +- Add decisions as they're made throughout the project +- Track outcome when known: + - ✓ Good — decision proved correct + - ⚠️ Revisit — decision may need reconsideration + - — Pending — too early to evaluate + +**Last Updated:** +- Always note when and why the document was updated +- Format: `after Phase 2` or `after v1.0 milestone` +- Triggers review of whether content is still accurate + + + + + +PROJECT.md evolves throughout the project lifecycle. + +**After each phase transition:** +1. Requirements invalidated? → Move to Out of Scope with reason +2. Requirements validated? → Move to Validated with phase reference +3. New requirements emerged? → Add to Active +4. Decisions to log? → Add to Key Decisions +5. "What This Is" still accurate? → Update if drifted + +**After each milestone:** +1. Full review of all sections +2. Core Value check — still the right priority? +3. Audit Out of Scope — reasons still valid? +4. Update Context with current state (users, feedback, metrics) + + + + + +For existing codebases: + +1. **Map codebase first** via `/gsd:map-codebase` + +2. **Infer Validated requirements** from existing code: + - What does the codebase actually do? + - What patterns are established? + - What's clearly working and relied upon? + +3. **Gather Active requirements** from user: + - Present inferred current state + - Ask what they want to build next + +4. **Initialize:** + - Validated = inferred from existing code + - Active = user's goals for this work + - Out of Scope = boundaries user specifies + - Context = includes current codebase state + + + + + +STATE.md references PROJECT.md: + +```markdown +## Project Reference + +See: .planning/PROJECT.md (updated [date]) + +**Core value:** [One-liner from Core Value section] +**Current focus:** [Current phase name] +``` + +This ensures Claude reads current PROJECT.md context. + + diff --git a/get-shit-done/templates/state.md b/get-shit-done/templates/state.md index 117eb7f89..3796cd1a2 100644 --- a/get-shit-done/templates/state.md +++ b/get-shit-done/templates/state.md @@ -1,6 +1,6 @@ # State Template -Template for `.planning/STATE.md` - the project's living memory. +Template for `.planning/STATE.md` — the project's living memory. --- @@ -9,26 +9,19 @@ Template for `.planning/STATE.md` - the project's living memory. ```markdown # Project State -## Project Summary -[IMMUTABLE - Copy verbatim from PROJECT.md on creation. Never edit this section.] +## Project Reference -**Building:** [One-liner from project vision] +See: .planning/PROJECT.md (updated [date]) -**Core requirements:** -- [Requirement 1] -- [Requirement 2] -- [Requirement 3] - -**Constraints:** -- [Key constraint 1] -- [Key constraint 2] +**Core value:** [One-liner from PROJECT.md Core Value section] +**Current focus:** [Current phase name] ## Current Position Phase: [X] of [Y] ([Phase name]) Plan: [A] of [B] in current phase Status: [Ready to plan / Planning / Ready to execute / In progress / Phase complete] -Last activity: [YYYY-MM-DD] - [What happened] +Last activity: [YYYY-MM-DD] — [What happened] Progress: [░░░░░░░░░░] 0% @@ -53,31 +46,26 @@ Progress: [░░░░░░░░░░] 0% ## Accumulated Context -### Decisions Made +### Decisions -| Phase | Decision | Rationale | -|-------|----------|-----------| -| - | - | - | +Decisions are logged in PROJECT.md Key Decisions table. +Recent decisions affecting current work: + +- [Phase X]: [Decision summary] +- [Phase Y]: [Decision summary] ### Deferred Issues -[From ISSUES.md - list open items with phase of origin] +[From ISSUES.md — list open items with phase of origin] None yet. -### Blockers/Concerns Carried Forward +### Blockers/Concerns -[From prior "Next Phase Readiness" sections - issues that affect future work] +[Issues that affect future work] None yet. -## Project Alignment - -Last checked: [Date or "Project start"] -Status: [✓ Aligned / ⚠️ Drift detected / ✗ Misaligned] -Assessment: [One line summary] -Drift notes: [Details if drift detected, otherwise "None"] - ## Session Continuity Last session: [YYYY-MM-DD HH:MM] @@ -86,25 +74,27 @@ Resume file: [Path to .continue-here*.md if exists, otherwise "None"] ``` -STATE.md is the project's "short-term memory" that spans all phases and sessions. -**Problem it solves:** Information is captured in summaries, issues, and decisions - but not systematically consumed. Each phase plans in isolation. Sessions start without knowing accumulated context. +STATE.md is the project's short-term memory spanning all phases and sessions. + +**Problem it solves:** Information is captured in summaries, issues, and decisions but not systematically consumed. Sessions start without context. **Solution:** A single, small file that's: -- Always read first (every workflow) -- Always updated after work (every execution) -- Contains digest of all accumulated wisdom -- Enables instant context restoration +- Read first in every workflow +- Updated after every significant action +- Contains digest of accumulated context +- Enables instant session restoration + **Creation:** After ROADMAP.md is created (during init) -- Copy Project Summary from PROJECT.md (immutable after this) +- Reference PROJECT.md (read it for current context) - Initialize empty accumulated context sections - Set position to "Phase 1 ready to plan" -**Reading:** First step of EVERY workflow +**Reading:** First step of every workflow - progress: Present status to user - plan: Inform planning decisions - execute: Know current position @@ -113,30 +103,33 @@ STATE.md is the project's "short-term memory" that spans all phases and sessions **Writing:** After every significant action - execute: After SUMMARY.md created - Update position (phase, plan, status) - - Extract decisions → add to table - - Extract new issues → update deferred list - - Extract concerns → add to blockers + - Note new decisions (detail in PROJECT.md) + - Update deferred issues list + - Add blockers/concerns - transition: After phase marked complete - Update progress bar - Clear resolved blockers -- alignment-check: After verification - - Update alignment status + - Refresh Project Reference date -### Project Summary (Immutable) -Copied from PROJECT.md on project initialization. Never edited afterward. -Provides constant reference to "what are we building" without re-reading full project doc. +### Project Reference +Points to PROJECT.md for full context. Includes: +- Core value (the ONE thing that matters) +- Current focus (which phase) +- Last update date (triggers re-read if stale) + +Claude reads PROJECT.md directly for requirements, constraints, and decisions. ### Current Position Where we are right now: -- Phase X of Y - which phase -- Plan A of B - which plan within phase -- Status - current state -- Last activity - what happened most recently -- Progress bar - visual indicator of overall completion +- Phase X of Y — which phase +- Plan A of B — which plan within phase +- Status — current state +- Last activity — what happened most recently +- Progress bar — visual indicator of overall completion Progress calculation: (completed plans) / (total plans across all phases) × 100% @@ -151,10 +144,7 @@ Updated after each plan completion. ### Accumulated Context -**Decisions Made:** Table of significant decisions with rationale. -- Extracted from SUMMARY.md "Decisions Made" sections -- Include phase number for traceability -- These constrain future phases (e.g., "use jose not jsonwebtoken") +**Decisions:** Reference to PROJECT.md Key Decisions table, plus recent decisions summary for quick access. Full decision log lives in PROJECT.md. **Deferred Issues:** Open items from ISSUES.md - Brief description with ISS-XXX number @@ -167,14 +157,6 @@ Updated after each plan completion. - Prefix with originating phase - Cleared when addressed -### Project Alignment -Tracks whether work matches original requirements: -- ✓ Aligned: On track -- ⚠️ Drift: Scope creeping or diverging -- ✗ Misaligned: Work doesn't serve project goals - -Updated after each phase completion. - ### Session Continuity Enables instant resumption: - When was last session @@ -184,43 +166,45 @@ Enables instant resumption: -Keep STATE.md under 150 lines. + +Keep STATE.md under 100 lines. It's a DIGEST, not an archive. If accumulated context grows too large: -- Summarize older phase decisions: "Phases 1-2: [key decisions]" -- Reference ISSUES.md instead of listing all: "12 open issues - see ISSUES.md" -- Keep only active blockers, archive resolved ones +- Keep only 3-5 recent decisions in summary (full log in PROJECT.md) +- Reference ISSUES.md instead of listing all: "12 open issues — see ISSUES.md" +- Keep only active blockers, remove resolved ones + +The goal is "read once, know where we are" — if it's too long, that fails. -The goal is "read once, know everything" - if it's too long, that fails. + **When created:** - During project initialization (after ROADMAP.md) -- Copy Project Summary from PROJECT.md (never edit this section after creation) +- Reference PROJECT.md (extract core value and current focus) - Initialize empty sections **When read:** -- EVERY workflow starts by reading STATE.md +- Every workflow starts by reading STATE.md +- Then read PROJECT.md for full context - Provides instant context restoration -- Shows current position and accumulated wisdom **When updated:** -- After each plan execution (update position, extract decisions/issues/blockers) -- After phase transitions (update progress bar, clear resolved blockers) -- After alignment checks (update alignment status) +- After each plan execution (update position, note decisions, update issues/blockers) +- After phase transitions (update progress bar, clear resolved blockers, refresh project reference) **Size management:** -- Keep under 150 lines total -- Summarize older decisions if table grows large +- Keep under 100 lines total +- Recent decisions only in STATE.md (full log in PROJECT.md) - Reference ISSUES.md instead of listing all issues -- Keep only active blockers, archive resolved ones +- Keep only active blockers **Sections:** -- Project Summary: Immutable project overview +- Project Reference: Pointer to PROJECT.md with core value - Current Position: Where we are now (phase, plan, status) - Performance Metrics: Velocity tracking -- Accumulated Context: Decisions, deferred issues, blockers -- Project Alignment: Are we on track with original vision? +- Accumulated Context: Recent decisions, deferred issues, blockers - Session Continuity: Resume information + diff --git a/get-shit-done/workflows/complete-milestone.md b/get-shit-done/workflows/complete-milestone.md index d15c1cf8e..ba569e8ea 100644 --- a/get-shit-done/workflows/complete-milestone.md +++ b/get-shit-done/workflows/complete-milestone.md @@ -1,25 +1,31 @@ -Mark a shipped version (v1.0, v1.1, v2.0) as complete. This creates a historical record in MILESTONES.md, updates PROJECT.md with current state, reorganizes ROADMAP.md with milestone groupings, and tags the release in git. + +Mark a shipped version (v1.0, v1.1, v2.0) as complete. This creates a historical record in MILESTONES.md, performs full PROJECT.md evolution review, reorganizes ROADMAP.md with milestone groupings, and tags the release in git. This is the ritual that separates "development" from "shipped." + + **Read these files NOW:** 1. templates/milestone.md 2. templates/milestone-archive.md 3. `.planning/ROADMAP.md` 4. `.planning/PROJECT.md` - + + + 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. Offers to create next milestone inline +4. Performs full PROJECT.md evolution review +5. Offers to create next milestone inline **Context Efficiency:** @@ -33,11 +39,13 @@ Uses `templates/milestone-archive.md` template with: - Milestone header (status, phases, date) - Full phase details from roadmap - Milestone summary (decisions, issues, technical debt) - + + + Check if milestone is truly complete: ```bash @@ -67,12 +75,15 @@ Total: 4 phases, 8 plans, all complete ``` + ```bash cat .planning/config.json 2>/dev/null ``` + + ``` ⚡ Auto-approved: Milestone scope verification @@ -82,9 +93,11 @@ Proceeding to stats gathering... ``` Proceed directly to gather_stats step. + + ``` Ready to mark this milestone as shipped? (yes / wait / adjust scope) @@ -94,10 +107,13 @@ Wait for confirmation. If "adjust scope": Ask which phases should be included. If "wait": Stop, user will return when ready. + + + Calculate milestone statistics: ```bash @@ -134,6 +150,7 @@ Milestone Stats: + Read all phase SUMMARY.md files in milestone range: ```bash @@ -158,6 +175,7 @@ Key accomplishments for this milestone: + Create or update `.planning/MILESTONES.md`. If file doesn't exist: @@ -199,58 +217,152 @@ Use template from `templates/milestone.md`: - -Update `.planning/PROJECT.md` to reflect current state. + -Add/update "Current State" section at top (after YAML if present): +Perform full PROJECT.md evolution review at milestone completion. -```markdown -# Project: [Name] +**Read all phase summaries in this milestone:** -## Current State (Updated: YYYY-MM-DD) - -**Shipped:** v[X.Y] [Name] (YYYY-MM-DD) -**Status:** [Production / Beta / Internal] -**Users:** [If known, e.g., "~500 downloads, 50 DAU" or "Internal use only"] -**Feedback:** [Key themes from users, or "Initial release, gathering feedback"] -**Codebase:** [LOC] [language], [key tech stack], [platform/deployment target] - -## [Next Milestone] Goals - -**Vision:** [What's the goal for next version?] - -**Motivation:** - -- [Why this next work matters] -- [User feedback driving it] -- [Technical debt or improvements needed] - -**Scope (v[X.Y]):** - -- [Feature/improvement 1] -- [Feature/improvement 2] -- [Feature/improvement 3] - ---- - -
-Original Vision (v1.0 - Archived for reference) - -[Move original project content here] - -
+```bash +cat .planning/phases/*-*/*-SUMMARY.md ``` -**If this is v1.0 (first milestone):** -Just add "Current State" section, no need to archive original vision yet. +**Full review checklist:** -**If this is v1.1+:** -Collapse previous version's content into `
` section. +1. **"What This Is" accuracy:** + - Read current description + - Compare to what was actually built + - Update if the product has meaningfully changed + +2. **Core Value check:** + - Is the stated core value still the right priority? + - Did shipping reveal a different core value? + - Update if the ONE thing has shifted + +3. **Requirements audit:** + + **Validated section:** + - All Active requirements shipped in this milestone → Move to Validated + - Format: `- ✓ [Requirement] — v[X.Y]` + + **Active section:** + - Remove requirements that moved to Validated + - Add any new requirements for next milestone + - Keep requirements that weren't addressed yet + + **Out of Scope audit:** + - Review each item — is the reasoning still valid? + - Remove items that are no longer relevant + - Add any requirements invalidated during this milestone + +4. **Context update:** + - Current codebase state (LOC, tech stack) + - User feedback themes (if any) + - Known issues or technical debt to address + +5. **Key Decisions audit:** + - Extract all decisions from milestone phase summaries + - Add to Key Decisions table with outcomes where known + - Mark ✓ Good, ⚠️ Revisit, or — Pending for each + +6. **Constraints check:** + - Any constraints that changed during development? + - Update as needed + +**Update PROJECT.md:** + +Make all edits inline. Update "Last updated" footer: + +```markdown +--- +*Last updated: [date] after v[X.Y] milestone* +``` + +**Example full evolution (v1.0 → v1.1 prep):** + +Before: + +```markdown +## What This Is + +A real-time collaborative whiteboard for remote teams. + +## Core Value + +Real-time sync that feels instant. + +## Requirements + +### Validated + +(None yet — ship to validate) + +### Active + +- [ ] Canvas drawing tools +- [ ] Real-time sync < 500ms +- [ ] User authentication +- [ ] Export to PNG + +### Out of Scope + +- Mobile app — web-first approach +- Video chat — use external tools +``` + +After v1.0: + +```markdown +## What This Is + +A real-time collaborative whiteboard for remote teams with instant sync and drawing tools. + +## Core Value + +Real-time sync that feels instant. + +## Requirements + +### Validated + +- ✓ Canvas drawing tools — v1.0 +- ✓ Real-time sync < 500ms — v1.0 (achieved 200ms avg) +- ✓ User authentication — v1.0 + +### Active + +- [ ] Export to PNG +- [ ] Undo/redo history +- [ ] Shape tools (rectangles, circles) + +### Out of Scope + +- Mobile app — web-first approach, PWA works well +- Video chat — use external tools +- Offline mode — real-time is core value + +## Context + +Shipped v1.0 with 2,400 LOC TypeScript. +Tech stack: Next.js, Supabase, Canvas API. +Initial user testing showed demand for shape tools. +``` + +**Step complete when:** + +- [ ] "What This Is" reviewed and updated if needed +- [ ] Core Value verified as still correct +- [ ] All shipped requirements moved to Validated +- [ ] New requirements added to Active for next milestone +- [ ] Out of Scope reasoning audited +- [ ] Context updated with current state +- [ ] All milestone decisions added to Key Decisions +- [ ] "Last updated" footer reflects milestone completion -Show diff of changes: + Update `.planning/ROADMAP.md` to group completed milestone phases. Add milestone headers and collapse completed work: @@ -260,19 +372,19 @@ Add milestone headers and collapse completed work: ## Milestones -- ✅ **v1.0 MVP** - Phases 1-4 (shipped YYYY-MM-DD) -- 🚧 **v1.1 Security** - Phases 5-6 (in progress) -- 📋 **v2.0 Redesign** - Phases 7-10 (planned) +- ✅ **v1.0 MVP** — Phases 1-4 (shipped YYYY-MM-DD) +- 🚧 **v1.1 Security** — Phases 5-6 (in progress) +- 📋 **v2.0 Redesign** — Phases 7-10 (planned) ## Phases
-✅ v1.0 MVP (Phases 1-4) - SHIPPED YYYY-MM-DD +✅ v1.0 MVP (Phases 1-4) — SHIPPED YYYY-MM-DD -- [x] Phase 1: Foundation (2/2 plans) - completed YYYY-MM-DD -- [x] Phase 2: Authentication (2/2 plans) - completed YYYY-MM-DD -- [x] Phase 3: Core Features (3/3 plans) - completed YYYY-MM-DD -- [x] Phase 4: Polish (1/1 plan) - completed YYYY-MM-DD +- [x] Phase 1: Foundation (2/2 plans) — completed YYYY-MM-DD +- [x] Phase 2: Authentication (2/2 plans) — completed YYYY-MM-DD +- [x] Phase 3: Core Features (3/3 plans) — completed YYYY-MM-DD +- [x] Phase 4: Polish (1/1 plan) — completed YYYY-MM-DD
@@ -296,6 +408,7 @@ Add milestone headers and collapse completed work: + Extract completed milestone details and create archive file. **Process:** @@ -305,42 +418,36 @@ Extract completed milestone details and create archive file. 2. Read `~/.claude/get-shit-done/templates/milestone-archive.md` template 3. Extract data from current ROADMAP.md: - - All phases belonging to this milestone (by phase number range) - Full phase details (goals, plans, dependencies, status) - Phase plan lists with completion checkmarks -4. Extract data from STATE.md: - - - All decisions made during this milestone (filter by Phase column) - - Issues that were resolved - - Issues that were deferred +4. Extract data from PROJECT.md: + - Key decisions made during this milestone + - Requirements that were validated 5. Fill template {{PLACEHOLDERS}}: - - - {{VERSION}} - Milestone version (e.g., "1.0") - - {{MILESTONE_NAME}} - From ROADMAP.md milestone header - - {{DATE}} - Today's date - - {{PHASE_START}} - First phase number in milestone - - {{PHASE_END}} - Last phase number in milestone - - {{TOTAL_PLANS}} - Count of all plans in milestone - - {{MILESTONE_DESCRIPTION}} - From ROADMAP.md overview - - {{PHASES_SECTION}} - Full phase details extracted - - {{DECISIONS_FROM_PROJECT_STATE}} - Filtered decisions - - {{ISSUES_RESOLVED_DURING_MILESTONE}} - From summaries - - {{ISSUES_DEFERRED_TO_LATER}} - From ISSUES.md + - {{VERSION}} — Milestone version (e.g., "1.0") + - {{MILESTONE_NAME}} — From ROADMAP.md milestone header + - {{DATE}} — Today's date + - {{PHASE_START}} — First phase number in milestone + - {{PHASE_END}} — Last phase number in milestone + - {{TOTAL_PLANS}} — Count of all plans in milestone + - {{MILESTONE_DESCRIPTION}} — From ROADMAP.md overview + - {{PHASES_SECTION}} — Full phase details extracted + - {{DECISIONS_FROM_PROJECT}} — Key decisions from PROJECT.md + - {{ISSUES_RESOLVED_DURING_MILESTONE}} — From summaries + - {{ISSUES_DEFERRED_TO_LATER}} — From ISSUES.md 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]` + - 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 8. Verify files: - - Check archive file exists: `ls .planning/milestones/v[X.Y]-ROADMAP.md` - Validate ROADMAP.md still parseable @@ -350,10 +457,44 @@ Extract completed milestone details and create archive file. ✅ v[X.Y] archived to milestones/v[X.Y]-ROADMAP.md ``` - Continue to git_tag step. Milestone creation happens in offer_next step. - + + + + +Update STATE.md to reflect milestone completion. + +**Project Reference:** + +```markdown +## Project Reference + +See: .planning/PROJECT.md (updated [today]) + +**Core value:** [Current core value from PROJECT.md] +**Current focus:** [Next milestone or "Planning next milestone"] +``` + +**Current Position:** + +```markdown +Phase: [Next phase] of [Total] ([Phase name]) +Plan: Not started +Status: Ready to plan +Last activity: [today] — v[X.Y] milestone complete + +Progress: [updated progress bar] +``` + +**Accumulated Context:** + +- Clear decisions summary (full log in PROJECT.md) +- Clear resolved blockers +- Keep open blockers for next milestone + + + Create git tag for milestone: ```bash @@ -385,6 +526,7 @@ git push origin v[X.Y] + Commit milestone completion including archive file. ```bash @@ -392,32 +534,33 @@ Commit milestone completion including archive file. 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 # Commit with descriptive message git commit -m "$(cat <<'EOF' -chore: archive v[X.Y] milestone +chore: complete v[X.Y] milestone - Added MILESTONES.md entry -- Updated PROJECT.md current state +- 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] EOF )" ``` -Confirm: "Committed: chore: archive v[X.Y] milestone" +Confirm: "Committed: chore: complete v[X.Y] milestone" -Then proceed to git tag step. + ``` ✅ Milestone v[X.Y] [Name] complete Shipped: - - [N] phases ([M] plans, [P] tasks) - [One sentence of what shipped] @@ -441,15 +584,17 @@ Tag: v[X.Y] --- ``` + + **Version conventions:** -- **v1.0** - Initial MVP -- **v1.1, v1.2, v1.3** - Minor updates, new features, fixes -- **v2.0, v3.0** - Major rewrites, breaking changes, significant new direction +- **v1.0** — Initial MVP +- **v1.1, v1.2, v1.3** — Minor updates, new features, fixes +- **v2.0, v3.0** — Major rewrites, breaking changes, significant new direction **Name conventions:** - v1.0 MVP @@ -459,9 +604,11 @@ Tag: v[X.Y] - v2.0 iOS Launch Keep names short (1-2 words describing the focus). + + **Create milestones for:** - Initial release (v1.0) - Public releases @@ -475,15 +622,22 @@ Keep names short (1-2 words describing the focus). If uncertain, ask: "Is this deployed/usable/shipped in some form?" If yes → milestone. If no → keep working. + + Milestone completion is successful when: + - [ ] MILESTONES.md entry created with stats and accomplishments -- [ ] PROJECT.md updated with current state +- [ ] PROJECT.md full evolution review completed +- [ ] All shipped requirements moved to Validated +- [ ] Key Decisions updated with outcomes - [ ] ROADMAP.md reorganized with milestone grouping +- [ ] Milestone archive created +- [ ] STATE.md updated with fresh project reference - [ ] Git tag created (v[X.Y]) - [ ] Milestone commit made - [ ] User knows next steps + -``` diff --git a/get-shit-done/workflows/create-milestone.md b/get-shit-done/workflows/create-milestone.md index f0fe04120..5f7d1bb43 100644 --- a/get-shit-done/workflows/create-milestone.md +++ b/get-shit-done/workflows/create-milestone.md @@ -29,7 +29,7 @@ Extract: - Previous milestone version (e.g., v1.0) - Last phase number used - Deferred issues from STATE.md -- Project brief summary from STATE.md +- Project context from PROJECT.md (What This Is, Core Value) **Calculate next milestone version:** diff --git a/get-shit-done/workflows/create-roadmap.md b/get-shit-done/workflows/create-roadmap.md index f3bb68f25..00bd95c71 100644 --- a/get-shit-done/workflows/create-roadmap.md +++ b/get-shit-done/workflows/create-roadmap.md @@ -285,7 +285,8 @@ mkdir -p .planning/phases/02-{phase-name} -Create STATE.md - the project's living memory. + +Create STATE.md — the project's living memory. Use template from `~/.claude/get-shit-done/templates/state.md`. @@ -294,47 +295,56 @@ Write to `.planning/STATE.md`: ```markdown # Project State -## Brief Summary +## Project Reference -**Building:** [Copy one-liner from PROJECT.md] +See: .planning/PROJECT.md (updated [today's date]) -**Core requirements:** -[Copy 3-5 key requirements from PROJECT.md] - -**Constraints:** -[Copy key constraints from PROJECT.md] +**Core value:** [Copy Core Value from PROJECT.md] +**Current focus:** Phase 1 — [First phase name] ## Current Position Phase: 1 of [N] ([First phase name]) Plan: Not started Status: Ready to plan -Last activity: [today's date] - Project initialized +Last activity: [today's date] — Project initialized Progress: ░░░░░░░░░░ 0% +## Performance Metrics + +**Velocity:** +- Total plans completed: 0 +- Average duration: — +- Total execution time: 0 hours + +**By Phase:** + +| Phase | Plans | Total | Avg/Plan | +|-------|-------|-------|----------| +| — | — | — | — | + +**Recent Trend:** +- Last 5 plans: — +- Trend: — + ## Accumulated Context -### Decisions Made +### Decisions -| Phase | Decision | Rationale | -| ----- | -------- | --------- | +Decisions are logged in PROJECT.md Key Decisions table. +Recent decisions affecting current work: + +(None yet) ### Deferred Issues None yet. -### Blockers/Concerns Carried Forward +### Blockers/Concerns None yet. -## Brief Alignment - -Last checked: Project start -Status: ✓ Aligned -Assessment: No work done yet - baseline alignment. -Drift notes: None - ## Session Continuity Last session: [today's date and time] @@ -344,11 +354,12 @@ Resume file: None **Key points:** -- Brief Summary section is IMMUTABLE after creation - never edit it -- Copy verbatim from PROJECT.md to ensure fidelity +- Project Reference points to PROJECT.md for full context +- Claude reads PROJECT.md directly for requirements, constraints, decisions - This file will be read first in every future operation - This file will be updated after every execution - + + Commit project initialization (brief + roadmap + state together): diff --git a/get-shit-done/workflows/resume-project.md b/get-shit-done/workflows/resume-project.md index bc0c829ec..3877875d9 100644 --- a/get-shit-done/workflows/resume-project.md +++ b/get-shit-done/workflows/resume-project.md @@ -30,23 +30,32 @@ ls .planning/PROJECT.md 2>/dev/null && echo "Project file exists" -Read and parse STATE.md: + +Read and parse STATE.md, then PROJECT.md: ```bash cat .planning/STATE.md +cat .planning/PROJECT.md ``` -Extract: +**From STATE.md extract:** -- **Brief Summary**: What we're building (immutable reminder) +- **Project Reference**: Core value and current focus - **Current Position**: Phase X of Y, Plan A of B, Status - **Progress**: Visual progress bar -- **Decisions Made**: Key decisions that constrain future work +- **Recent Decisions**: Key decisions affecting current work - **Deferred Issues**: Open items awaiting attention - **Blockers/Concerns**: Issues carried forward -- **Brief Alignment**: Are we on track? - **Session Continuity**: Where we left off, any resume files - + +**From PROJECT.md extract:** + +- **What This Is**: Current accurate description +- **Requirements**: Validated, Active, Out of Scope +- **Key Decisions**: Full decision log with outcomes +- **Constraints**: Hard limits on implementation + + Look for incomplete work that needs attention: @@ -81,7 +90,7 @@ Present complete project status to user: ╔══════════════════════════════════════════════════════════════╗ ║ PROJECT STATUS ║ ╠══════════════════════════════════════════════════════════════╣ -║ Building: [one-liner from Brief Summary] ║ +║ Building: [one-liner from PROJECT.md "What This Is"] ║ ║ ║ ║ Phase: [X] of [Y] - [Phase name] ║ ║ Plan: [A] of [B] - [Status] ║ @@ -237,7 +246,7 @@ If STATE.md is missing but other artifacts exist: "STATE.md missing. Reconstructing from artifacts..." -1. Read PROJECT.md → Extract Brief Summary +1. Read PROJECT.md → Extract "What This Is" and Core Value 2. Read ROADMAP.md → Determine phases, find current position 3. Scan \*-SUMMARY.md files → Extract decisions, issues, concerns 4. Read ISSUES.md → Count deferred issues diff --git a/get-shit-done/workflows/transition.md b/get-shit-done/workflows/transition.md index 4297b8e9c..50b735bd1 100644 --- a/get-shit-done/workflows/transition.md +++ b/get-shit-done/workflows/transition.md @@ -1,33 +1,41 @@ + **Read these files NOW:** 1. `.planning/STATE.md` -2. `.planning/ROADMAP.md` -3. Current phase's plan files (`*-PLAN.md`) -4. Current phase's summary files (`*-SUMMARY.md`) - +2. `.planning/PROJECT.md` +3. `.planning/ROADMAP.md` +4. Current phase's plan files (`*-PLAN.md`) +5. Current phase's summary files (`*-SUMMARY.md`) + + -Mark current phase complete and advance to next. This is the natural point -where progress tracking happens - implicit via forward motion. + +Mark current phase complete and advance to next. This is the natural point where progress tracking and PROJECT.md evolution happen. "Planning next phase" = "current phase is done" + + Before transition, read project state: ```bash cat .planning/STATE.md 2>/dev/null +cat .planning/PROJECT.md 2>/dev/null ``` Parse current position to verify we're transitioning the right phase. Note accumulated context that may need updating after transition. + + Check current phase has all plan summaries: ```bash @@ -43,34 +51,40 @@ ls .planning/phases/XX-current/*-SUMMARY.md 2>/dev/null | sort - If counts don't match: incomplete + ```bash cat .planning/config.json 2>/dev/null ``` + **If all plans complete:** + ``` ⚡ Auto-approved: Transition Phase [X] → Phase [X+1] -Phase [X] complete - all [Y] plans finished. +Phase [X] complete — all [Y] plans finished. Proceeding to mark done and advance... ``` Proceed directly to cleanup_handoff step. + -Ask: "Phase [X] complete - all [Y] plans finished. Ready to mark done and move to Phase [X+1]?" + +Ask: "Phase [X] complete — all [Y] plans finished. Ready to mark done and move to Phase [X+1]?" Wait for confirmation before proceeding. + **If plans incomplete:** **SAFETY RAIL: always_confirm_destructive applies here.** -Skipping incomplete plans is destructive - ALWAYS prompt regardless of mode. +Skipping incomplete plans is destructive — ALWAYS prompt regardless of mode. Present: @@ -89,19 +103,23 @@ Options: ``` Wait for user decision. + + Check for lingering handoffs: ```bash ls .planning/phases/XX-current/.continue-here*.md 2>/dev/null ``` -If found, delete them - phase is complete, handoffs are stale. - +If found, delete them — phase is complete, handoffs are stale. + + + Update the roadmap file: ```bash @@ -137,11 +155,101 @@ Update the file: + If prompts were generated for the phase, they stay in place. The `completed/` subfolder pattern from create-meta-prompts handles archival. + + + + + +Evolve PROJECT.md to reflect learnings from completed phase. + +**Read phase summaries:** + +```bash +cat .planning/phases/XX-current/*-SUMMARY.md +``` + +**Assess requirement changes:** + +1. **Requirements validated?** + - Any Active requirements shipped in this phase? + - Move to Validated with phase reference: `- ✓ [Requirement] — Phase X` + +2. **Requirements invalidated?** + - Any Active requirements discovered to be unnecessary or wrong? + - Move to Out of Scope with reason: `- [Requirement] — [why invalidated]` + +3. **Requirements emerged?** + - Any new requirements discovered during building? + - Add to Active: `- [ ] [New requirement]` + +4. **Decisions to log?** + - Extract decisions from SUMMARY.md files + - Add to Key Decisions table with outcome if known + +5. **"What This Is" still accurate?** + - If the product has meaningfully changed, update the description + - Keep it current and accurate + +**Update PROJECT.md:** + +Make the edits inline. Update "Last updated" footer: + +```markdown +--- +*Last updated: [date] after Phase [X]* +``` + +**Example evolution:** + +Before: + +```markdown +### Active + +- [ ] JWT authentication +- [ ] Real-time sync < 500ms +- [ ] Offline mode + +### Out of Scope + +- OAuth2 — complexity not needed for v1 +``` + +After (Phase 2 shipped JWT auth, discovered rate limiting needed): + +```markdown +### Validated + +- ✓ JWT authentication — Phase 2 + +### Active + +- [ ] Real-time sync < 500ms +- [ ] Offline mode +- [ ] Rate limiting on sync endpoint + +### Out of Scope + +- OAuth2 — complexity not needed for v1 +``` + +**Step complete when:** + +- [ ] Phase summaries reviewed for learnings +- [ ] Validated requirements moved from Active +- [ ] Invalidated requirements moved to Out of Scope with reason +- [ ] Emerged requirements added to Active +- [ ] New decisions logged with rationale +- [ ] "What This Is" updated if product changed +- [ ] "Last updated" footer reflects this transition + + Update Current Position section in STATE.md to reflect phase completion and transition. **Format:** @@ -150,7 +258,7 @@ Update Current Position section in STATE.md to reflect phase completion and tran Phase: [next] of [total] ([Next phase name]) Plan: Not started Status: Ready to plan -Last activity: [today] - Phase [X] complete, transitioned to Phase [X+1] +Last activity: [today] — Phase [X] complete, transitioned to Phase [X+1] Progress: [updated progress bar] ``` @@ -163,7 +271,7 @@ Progress: [updated progress bar] - Update last activity to describe transition - Recalculate progress bar based on completed plans -**Example - transitioning from Phase 2 to Phase 3:** +**Example — transitioning from Phase 2 to Phase 3:** Before: @@ -173,7 +281,7 @@ Before: Phase: 2 of 4 (Authentication) Plan: 2 of 2 in current phase Status: Phase complete -Last activity: 2025-01-20 - Completed 02-02-PLAN.md +Last activity: 2025-01-20 — Completed 02-02-PLAN.md Progress: ███████░░░ 60% ``` @@ -186,7 +294,7 @@ After: Phase: 3 of 4 (Core Features) Plan: Not started Status: Ready to plan -Last activity: 2025-01-20 - Phase 2 complete, transitioned to Phase 3 +Last activity: 2025-01-20 — Phase 2 complete, transitioned to Phase 3 Progress: ███████░░░ 60% ``` @@ -197,23 +305,47 @@ Progress: ███████░░░ 60% - [ ] Plan status reset to "Not started" - [ ] Status shows "Ready to plan" - [ ] Last activity describes the transition -- [ ] Progress bar still reflects total completed plans - +- [ ] Progress bar reflects total completed plans + + + + + +Update Project Reference section in STATE.md. + +```markdown +## Project Reference + +See: .planning/PROJECT.md (updated [today]) + +**Core value:** [Current core value from PROJECT.md] +**Current focus:** [Next phase name] +``` + +Update the date and current focus to reflect the transition. + + + Review and update Accumulated Context section in STATE.md. +**Decisions:** + +- Note recent decisions from this phase (3-5 max) +- Full log lives in PROJECT.md Key Decisions table + **Blockers/Concerns:** - Review blockers from completed phase - If addressed in this phase: Remove from list -- If still relevant for future: Keep with note "Carried from Phase X" +- If still relevant for future: Keep with "Phase X" prefix - Add any new concerns from completed phase's summaries **Deferred Issues:** - Count open issues in ISSUES.md -- Update count: "[N] open issues - see ISSUES.md" +- Update count: "[N] open issues — see ISSUES.md" - If many accumulated, note: "Consider addressing ISS-XXX, ISS-YYY in next phase" **Example:** @@ -221,109 +353,41 @@ Review and update Accumulated Context section in STATE.md. Before: ```markdown -### Blockers/Concerns Carried Forward +### Blockers/Concerns - ⚠️ [Phase 1] Database schema not indexed for common queries - ⚠️ [Phase 2] WebSocket reconnection behavior on flaky networks unknown ### Deferred Issues -- ISS-001: Rate limiting on sync endpoint (Phase 2) - Medium +- ISS-001: Rate limiting on sync endpoint (Phase 2) — Medium ``` After (if database indexing was addressed in Phase 2): ```markdown -### Blockers/Concerns Carried Forward +### Blockers/Concerns - ⚠️ [Phase 2] WebSocket reconnection behavior on flaky networks unknown ### Deferred Issues -- ISS-001: Rate limiting on sync endpoint (Phase 2) - Medium -- ISS-002: Better sync error messages (Phase 2) - Quick +- ISS-001: Rate limiting on sync endpoint (Phase 2) — Medium +- ISS-002: Better sync error messages (Phase 2) — Quick ``` **Step complete when:** +- [ ] Recent decisions noted (full log in PROJECT.md) - [ ] Resolved blockers removed from list - [ ] Unresolved blockers kept with phase prefix - [ ] New concerns from completed phase added - [ ] Deferred issues count updated - - -Perform brief alignment check after phase completion to verify work matches original vision. - -**Instructions:** - -1. Re-read PROJECT.md core requirements -2. Assess what was built in completed phase -3. Compare against project's problem statement and success criteria -4. Determine alignment status: - - ✓ Aligned: Work delivers on project goals, no scope drift - - ⚠️ Drift detected: Some divergence from original vision - - ✗ Misaligned: Work doesn't serve the project - -**Format:** - -```markdown -## Brief Alignment - -Last checked: [today] (Phase [X] completion) -Status: [✓ Aligned / ⚠️ Drift detected / ✗ Misaligned] -Assessment: [One sentence describing alignment state] -Drift notes: [Details if drift detected, otherwise "None"] -``` - -**Example - transitioning after Phase 2 completion:** - -Before: - -```markdown -## Brief Alignment - -Last checked: Project start -Status: ✓ Aligned -Assessment: No work done yet - baseline alignment. -Drift notes: None -``` - -After: - -```markdown -## Brief Alignment - -Last checked: 2025-01-20 (Phase 2 completion) -Status: ✓ Aligned -Assessment: Auth phase delivered JWT-based authentication as specified. Sync phase next aligns with project's real-time requirements. -Drift notes: None -``` - -**Alternative example - drift detected:** - -After (with drift): - -```markdown -## Brief Alignment - -Last checked: 2025-01-20 (Phase 2 completion) -Status: ⚠️ Drift detected -Assessment: Auth phase added OAuth2 support beyond project's JWT requirement. -Drift notes: OAuth2 adds complexity not in original scope. Consider if this serves user needs or gold-plating. -``` - -**Step complete when:** - -- [ ] PROJECT.md core requirements reviewed -- [ ] Completed phase work assessed against project goals -- [ ] Last checked updated to current date with phase reference -- [ ] Status reflects actual alignment (Aligned/Drift/Misaligned) -- [ ] Assessment explains the alignment state in one sentence -- [ ] Drift notes document any divergence from project goals - + + Update Session Continuity section in STATE.md to reflect transition completion. **Format:** @@ -334,36 +398,16 @@ Stopped at: Phase [X] complete, ready to plan Phase [X+1] Resume file: None ``` -**Example - after completing Phase 2 transition:** - -Before: - -```markdown -## Session Continuity - -Last session: 2025-01-20 -Stopped at: Completed 02-02-PLAN.md -Resume file: None -``` - -After: - -```markdown -## Session Continuity - -Last session: 2025-01-20 16:45 -Stopped at: Phase 2 complete, ready to plan Phase 3 -Resume file: None -``` - **Step complete when:** - [ ] Last session timestamp updated to current date and time - [ ] Stopped at describes phase completion and next phase - [ ] Resume file confirmed as None (transitions don't use resume files) - + + + **Check if there's a next phase in the current milestone:** Re-read the ROADMAP file: @@ -376,18 +420,21 @@ Re-read the ROADMAP file: **If next phase exists:** + ``` Phase [X] marked complete. -Next: Phase [X+1] - [Name] +Next: Phase [X+1] — [Name] ⚡ Auto-continuing: Plan Phase [X+1] in detail ``` Exit skill and invoke SlashCommand("/gsd:plan-phase [X+1]") + + ``` ## ✓ Phase [X] Complete @@ -410,27 +457,31 @@ Exit skill and invoke SlashCommand("/gsd:plan-phase [X+1]") --- ``` + **If no next phase (milestone 100% complete):** + ``` Phase [X] marked complete. -🎉 Milestone [version] is 100% complete - all phases finished! +🎉 Milestone [version] is 100% complete — all phases finished! ⚡ Auto-continuing: Complete milestone and archive ``` Exit skill and invoke SlashCommand("/gsd:complete-milestone [version]") + + ``` ## ✓ Phase [X] Complete -🎉 Milestone [version] is 100% complete - all phases finished! +🎉 Milestone [version] is 100% complete — all phases finished! --- @@ -449,6 +500,7 @@ Exit skill and invoke SlashCommand("/gsd:complete-milestone [version]") --- ``` + @@ -456,6 +508,7 @@ Exit skill and invoke SlashCommand("/gsd:complete-milestone [version]") + Progress tracking is IMPLICIT: - "Plan phase 2" → Phase 1 must be done (or ask) @@ -463,9 +516,11 @@ Progress tracking is IMPLICIT: - Transition workflow makes it explicit in ROADMAP.md No separate "update progress" step. Forward motion IS progress. + + If user wants to move on but phase isn't fully complete: ``` @@ -479,22 +534,25 @@ Options: 3. Stay and finish current phase ``` -Respect user judgment - they know if work matters. +Respect user judgment — they know if work matters. **If marking complete with incomplete plans:** - Update ROADMAP: "2/3 plans complete" (not "3/3") - Note in transition message which plans were skipped - + + + Transition is complete when: - [ ] Current phase plan summaries verified (all exist or user chose to skip) - [ ] Any stale handoffs deleted - [ ] ROADMAP.md updated with completion status and plan count -- [ ] STATE.md updated (position, blockers, alignment, session) -- [ ] Brief alignment check performed +- [ ] PROJECT.md evolved (requirements, decisions, description if needed) +- [ ] STATE.md updated (position, project reference, context, session) - [ ] Progress table updated - [ ] User knows next steps - + +