mindsystem-cc 3.19.0 → 3.21.0

package/mindsystem/workflows/complete-milestone.md

@@ -1,6 +1,6 @@
 <purpose>
 
-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, archives ROADMAP.md and REQUIREMENTS.md, and tags the release in git.
+Mark a shipped milestone as complete. This creates a historical record in MILESTONES.md, performs full PROJECT.md evolution review, and archives ROADMAP.md and REQUIREMENTS.md.
 
 </purpose>
 
@@ -20,9 +20,9 @@ Mark a shipped version (v1.0, v1.1, v2.0) as complete. This creates a historical
 
 When a milestone completes, this workflow:
 
-1. Creates `.planning/milestones/v[X.Y]/` directory for all archive files
-2. Extracts full milestone details to `.planning/milestones/v[X.Y]/ROADMAP.md`
-3. Archives requirements to `.planning/milestones/v[X.Y]/REQUIREMENTS.md`
+1. Creates `.planning/milestones/{slug}/` directory for all archive files
+2. Extracts full milestone details to `.planning/milestones/{slug}/ROADMAP.md`
+3. Archives requirements to `.planning/milestones/{slug}/REQUIREMENTS.md`
 4. Archives milestone files via script (audit, context, research — whichever exist)
 5. Consolidates phase summaries, deletes artifacts, moves phase dirs via script
 6. Deletes REQUIREMENTS.md (fresh one created for next milestone)
@@ -68,7 +68,7 @@ cat .planning/config.json 2>/dev/null
 Run the stats script to get readiness status and git statistics:
 
 ```bash
-~/.claude/mindsystem/scripts/gather-milestone-stats.sh $PHASE_START $PHASE_END
+ms-tools gather-milestone-stats $PHASE_START $PHASE_END
 ```
 
 The script outputs:
@@ -133,7 +133,7 @@ If exists, prepend new entry (reverse chronological order).
 Use template from `templates/milestone.md`:
 
 ```markdown
-## v[Version] [Name] (Shipped: YYYY-MM-DD)
+## [Name] (Shipped: YYYY-MM-DD)
 
 **Delivered:** [One sentence from user]
 
@@ -184,30 +184,31 @@ cat .planning/phases/*-*/*-SUMMARY.md
 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
+   - All requirements shipped in this milestone → Add to Validated
+   - Format: `- ✓ [Requirement] — [Name]`
 
    **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:**
+4. **Business context review:**
+   - Who It's For — has understanding of audience evolved?
+   - Core Problem — still the right framing?
+   - How It's Different — new competitors or differentiators?
+   - Key User Flows — validated against what users actually do?
+
+5. **Technical Context update:**
    - Current codebase state (LOC, tech stack)
    - User feedback themes (if any)
    - Known issues or technical debt to address
 
-5. **Key Decisions audit:**
+6. **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:**
+7. **Constraints check:**
    - Any constraints that changed during development?
    - Update as needed
 
@@ -217,10 +218,10 @@ Make all edits inline. Update "Last updated" footer:
 
 ```markdown
 ---
-*Last updated: [date] after v[X.Y] milestone*
+*Last updated: [date] after [Name] milestone*
 ```
 
-**Example full evolution (v1.0 → v1.1 prep):**
+**Example full evolution (MVP → Security & Polish prep):**
 
 Before:
 
@@ -233,26 +234,22 @@ A real-time collaborative whiteboard for remote teams.
 
 Real-time sync that feels instant.
 
-## Requirements
+## Who It's For
 
-### Validated
-
-(None yet — ship to validate)
+Remote teams who need to brainstorm visually during meetings.
+Currently using Miro or physical whiteboards.
 
-### Active
+## Validated
 
-- [ ] Canvas drawing tools
-- [ ] Real-time sync < 500ms
-- [ ] User authentication
-- [ ] Export to PNG
+(None yet — ship to validate)
 
-### Out of Scope
+## Out of Scope
 
 - Mobile app — web-first approach
 - Video chat — use external tools
 ```
 
-After v1.0:
+After MVP:
 
 ```markdown
 ## What This Is
@@ -263,29 +260,26 @@ A real-time collaborative whiteboard for remote teams with instant sync and draw
 
 Real-time sync that feels instant.
 
-## Requirements
-
-### Validated
+## Who It's For
 
-- ✓ Canvas drawing tools — v1.0
-- ✓ Real-time sync < 500ms — v1.0 (achieved 200ms avg)
-- ✓ User authentication — v1.0
+Remote teams (2-8 people) who brainstorm visually during meetings.
+Currently using Miro but frustrated by complexity and latency.
 
-### Active
+## Validated
 
-- [ ] Export to PNG
-- [ ] Undo/redo history
-- [ ] Shape tools (rectangles, circles)
+- ✓ Canvas drawing tools — MVP
+- ✓ Real-time sync < 500ms — MVP (achieved 200ms avg)
+- ✓ User authentication — MVP
 
-### Out of Scope
+## Out of Scope
 
 - Mobile app — web-first approach, PWA works well
 - Video chat — use external tools
 - Offline mode — real-time is core value
 
-## Context
+## Technical Context
 
-Shipped v1.0 with 2,400 LOC TypeScript.
+Shipped MVP with 2,400 LOC TypeScript.
 Tech stack: Next.js, Supabase, Canvas API.
 Initial user testing showed demand for shape tools.
 ```
@@ -294,10 +288,10 @@ Initial user testing showed demand for shape tools.
 
 - [ ] "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
+- [ ] All shipped requirements added to Validated
+- [ ] Business context reviewed (Who It's For, Core Problem, How It's Different, Key User Flows)
 - [ ] Out of Scope reasoning audited
-- [ ] Context updated with current state
+- [ ] Technical Context updated with current state
 - [ ] All milestone decisions added to Key Decisions
 - [ ] "Last updated" footer reflects milestone completion
 
@@ -311,9 +305,9 @@ Extract completed milestone details and create archive file.
 
 1. Create milestone directory and archive file:
    ```bash
-   mkdir -p .planning/milestones/v[X.Y]
+   mkdir -p .planning/milestones/{slug}
    ```
-   Archive file path: `.planning/milestones/v[X.Y]/ROADMAP.md`
+   Archive file path: `.planning/milestones/{slug}/ROADMAP.md`
 
 2. Read `~/.claude/mindsystem/templates/milestone-archive.md` template
 
@@ -338,7 +332,7 @@ Extract completed milestone details and create archive file.
    - {{DECISIONS_FROM_PROJECT}} — Key decisions from PROJECT.md
    - {{ISSUES_RESOLVED_DURING_MILESTONE}} — From summaries
 
-6. Write filled template to `.planning/milestones/v[X.Y]/ROADMAP.md`
+6. Write filled template to `.planning/milestones/{slug}/ROADMAP.md`
 
 7. Delete ROADMAP.md (fresh one created for next milestone):
    ```bash
@@ -347,17 +341,17 @@ Extract completed milestone details and create archive file.
 
 8. Verify archive exists:
    ```bash
-   ls .planning/milestones/v[X.Y]/ROADMAP.md
+   ls .planning/milestones/{slug}/ROADMAP.md
    ```
 
 9. Confirm roadmap archive complete:
 
    ```
-   ✅ v[X.Y] roadmap archived to milestones/v[X.Y]/ROADMAP.md
+   ✅ Roadmap archived to milestones/{slug}/ROADMAP.md
    ✅ ROADMAP.md deleted (fresh one for next milestone)
    ```
 
-**Note:** Phase directories are moved to `milestones/v[X.Y]/phases/` by the archive_and_cleanup_phases step. After milestone completion, `.planning/phases/` contains only the next milestone's work. Phase numbering continues (v1.0 phases 1-4, v1.1 phases 5-8, etc.).
+**Note:** Phase directories are moved to `milestones/{slug}/phases/` by the archive_and_cleanup_phases step. After milestone completion, `.planning/phases/` contains only the next milestone's work. Phase numbering continues (MVP phases 1-4, next milestone phases 5-8, etc.).
 
 </step>
 
@@ -372,7 +366,7 @@ Archive requirements and prepare for fresh requirements in next milestone.
    cat .planning/REQUIREMENTS.md
    ```
 
-2. Create archive file: `.planning/milestones/v[X.Y]/REQUIREMENTS.md`
+2. Create archive file: `.planning/milestones/{slug}/REQUIREMENTS.md`
 
 3. Transform requirements for archive:
    - Mark all v1 requirements as `[x]` complete
@@ -385,12 +379,12 @@ Archive requirements and prepare for fresh requirements in next milestone.
 
 4. Write archive file with header:
    ```markdown
-   # Requirements Archive: v[X.Y] [Milestone Name]
+   # Requirements Archive: [Milestone Name]
 
    **Archived:** [DATE]
    **Status:** ✅ SHIPPED
 
-   This is the archived requirements specification for v[X.Y].
+   This is the archived requirements specification for [Milestone Name].
    For current requirements, see `.planning/REQUIREMENTS.md` (created for next milestone).
 
    ---
@@ -406,7 +400,7 @@ Archive requirements and prepare for fresh requirements in next milestone.
    **Dropped:** [list any requirements removed and why]
 
    ---
-   *Archived: [DATE] as part of v[X.Y] milestone completion*
+   *Archived: [DATE] as part of [Milestone Name] milestone completion*
    ```
 
 5. Delete original REQUIREMENTS.md:
@@ -416,7 +410,7 @@ Archive requirements and prepare for fresh requirements in next milestone.
 
 6. Confirm:
    ```
-   ✅ Requirements archived to milestones/v[X.Y]/REQUIREMENTS.md
+   ✅ Requirements archived to milestones/{slug}/REQUIREMENTS.md
    ✅ REQUIREMENTS.md deleted (fresh one needed for next milestone)
    ```
 
@@ -429,7 +423,7 @@ Archive requirements and prepare for fresh requirements in next milestone.
 Archive optional milestone files (audit, context, research) to the milestone directory:
 
 ```bash
-~/.claude/mindsystem/scripts/archive-milestone-files.sh v[X.Y]
+ms-tools archive-milestone-files {slug}
 ```
 
 The script moves whichever files exist and reports what was archived. Files that don't exist are skipped silently.
@@ -441,22 +435,22 @@ The script moves whichever files exist and reports what was archived. Files that
 Consolidate phase summaries, delete raw artifacts, and move phase directories to the milestone archive. This runs after all steps that read summaries (extract_accomplishments, evolve_project_full_review) and after archive_milestone creates the milestone directory.
 
 ```bash
-~/.claude/mindsystem/scripts/archive-milestone-phases.sh $PHASE_START $PHASE_END v[X.Y]
+ms-tools archive-milestone-phases $PHASE_START $PHASE_END {slug}
 ```
 
 Verify archive:
 
 ```bash
-ls .planning/milestones/v[X.Y]/PHASE-SUMMARIES.md
-ls .planning/milestones/v[X.Y]/phases/
+ls .planning/milestones/{slug}/PHASE-SUMMARIES.md
+ls .planning/milestones/{slug}/phases/
 ```
 
 Present:
 
 ```
-✅ Phase summaries consolidated to milestones/v[X.Y]/PHASE-SUMMARIES.md
+✅ Phase summaries consolidated to milestones/{slug}/PHASE-SUMMARIES.md
 ✅ Raw artifacts deleted from phase directories
-✅ Phase directories moved to milestones/v[X.Y]/phases/
+✅ Phase directories moved to milestones/{slug}/phases/
 ✅ .planning/phases/ clean for next milestone
 ```
 
@@ -485,7 +479,7 @@ See: .planning/PROJECT.md (updated [today])
 Phase: [Next phase] of [Total] ([Phase name])
 Plan: Not started
 Status: Ready to plan
-Last activity: [today] — v[X.Y] milestone complete
+Last activity: [today] — [Name] milestone complete
 
 Progress: [updated progress bar]
 ```
@@ -498,45 +492,13 @@ Progress: [updated progress bar]
 
 </step>
 
-<step name="git_tag">
-
-Create git tag for milestone:
-
-```bash
-git tag -a v[X.Y] -m "$(cat <<'EOF'
-v[X.Y] [Name]
-
-Delivered: [One sentence]
-
-Key accomplishments:
-- [Item 1]
-- [Item 2]
-- [Item 3]
-
-See .planning/MILESTONES.md for full details.
-EOF
-)"
-```
-
-Confirm: "Tagged: v[X.Y]"
-
-Ask: "Push tag to remote? (y/n)"
-
-If yes:
-
-```bash
-git push origin v[X.Y]
-```
-
-</step>
-
 <step name="git_commit_milestone">
 
 Commit milestone completion including archive files and deletions.
 
 ```bash
 # Stage archive directory (covers ROADMAP, REQUIREMENTS, AUDIT, CONTEXT, research)
-git add .planning/milestones/v[X.Y]/
+git add .planning/milestones/{slug}/
 
 # Stage updated files
 git add .planning/MILESTONES.md
@@ -548,9 +510,9 @@ git add -u .planning/
 
 # Commit with descriptive message
 git commit -m "$(cat <<'EOF'
-chore: complete v[X.Y] milestone
+chore: complete [Name] milestone
 
-Archived to milestones/v[X.Y]/:
+Archived to milestones/{slug}/:
 - ROADMAP.md
 - REQUIREMENTS.md
 - PHASE-SUMMARIES.md (consolidated from phase directories)
@@ -573,32 +535,29 @@ Updated:
 - MILESTONES.md (new entry)
 - PROJECT.md (requirements → Validated)
 - STATE.md (reset for next milestone)
-
-Tagged: v[X.Y]
 EOF
 )"
 ```
 
-Confirm: "Committed: chore: complete v[X.Y] milestone"
+Confirm: "Committed: chore: complete [Name] milestone"
 
 </step>
 
 <step name="offer_next">
 
 ```
-✅ Milestone v[X.Y] [Name] complete
+✅ Milestone [Name] complete
 
 Shipped:
 - [N] phases ([M] plans, [P] tasks)
 - [One sentence of what shipped]
 
-Archived to milestones/v[X.Y]/:
+Archived to milestones/{slug}/:
 - ROADMAP.md
 - REQUIREMENTS.md
 - research/ (if existed)
 
 Summary: .planning/MILESTONES.md
-Tag: v[X.Y]
 
 ---
 
@@ -626,12 +585,12 @@ Tag: v[X.Y]
 
 Milestone completion is successful when (ordered by skip risk):
 
-- [ ] PROJECT.md full evolution review completed (What This Is, Core Value, Requirements, Key Decisions, Context)
+- [ ] PROJECT.md full evolution review completed (What This Is, Core Value, business context, Validated, Key Decisions, Technical Context)
 - [ ] All shipped requirements moved to Validated in PROJECT.md
 - [ ] Key Decisions updated with outcomes
 - [ ] MILESTONES.md entry created with stats and accomplishments
-- [ ] Roadmap archive created (milestones/v[X.Y]/ROADMAP.md)
-- [ ] Requirements archive created (milestones/v[X.Y]/REQUIREMENTS.md)
+- [ ] Roadmap archive created (milestones/{slug}/ROADMAP.md)
+- [ ] Requirements archive created (milestones/{slug}/REQUIREMENTS.md)
 - [ ] REQUIREMENTS.md deleted (fresh for next milestone)
 - [ ] STATE.md updated with fresh project reference