mindsystem-cc 3.0.0

package/commands/ms/plan-milestone-gaps.md

@@ -0,0 +1,285 @@
+---
+name: ms:plan-milestone-gaps
+description: Create phases to close all gaps identified by milestone audit
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Glob
+  - Grep
+  - AskUserQuestion
+---
+
+<objective>
+Create all phases necessary to close gaps identified by `/ms:audit-milestone`.
+
+Reads MILESTONE-AUDIT.md, groups gaps into logical phases, creates phase entries in ROADMAP.md, and offers to plan each phase.
+
+One command creates all fix phases — no manual `/ms:add-phase` per gap.
+</objective>
+
+<execution_context>
+@~/.claude/mindsystem/references/principles.md
+@~/.claude/mindsystem/workflows/plan-phase.md
+</execution_context>
+
+<context>
+**Audit results:**
+Glob: .planning/v*-MILESTONE-AUDIT.md (use most recent)
+
+**Original intent (for prioritization):**
+@.planning/PROJECT.md
+@.planning/REQUIREMENTS.md
+
+**Current state:**
+@.planning/ROADMAP.md
+@.planning/STATE.md
+</context>
+
+<process>
+
+## 1. Load Audit Results
+
+```bash
+# Find the most recent audit file
+ls -t .planning/v*-MILESTONE-AUDIT.md 2>/dev/null | head -1
+```
+
+Parse YAML frontmatter to extract structured gaps:
+- `gaps.requirements` — unsatisfied requirements
+- `gaps.integration` — missing cross-phase connections
+- `gaps.flows` — broken E2E flows
+
+If no audit file exists or has no gaps, error:
+```
+No audit gaps found. Run `/ms:audit-milestone` first.
+```
+
+## 2. Prioritize Gaps
+
+Group gaps by priority from REQUIREMENTS.md:
+
+| Priority | Action |
+|----------|--------|
+| `must` | Create phase, blocks milestone |
+| `should` | Create phase, recommended |
+| `nice` | Ask user: include or defer? |
+
+For integration/flow gaps, infer priority from affected requirements.
+
+## 3. Group Gaps into Phases
+
+Cluster related gaps into logical phases:
+
+**Grouping rules:**
+- Same affected phase → combine into one fix phase
+- Same subsystem (auth, API, UI) → combine
+- Dependency order (fix stubs before wiring)
+- Keep phases focused: 2-4 tasks each
+
+**Example grouping:**
+```
+Gap: DASH-01 unsatisfied (Dashboard doesn't fetch)
+Gap: Integration Phase 1→3 (Auth not passed to API calls)
+Gap: Flow "View dashboard" broken at data fetch
+
+→ Phase 6: "Wire Dashboard to API"
+  - Add fetch to Dashboard.tsx
+  - Include auth header in fetch
+  - Handle response, update state
+  - Render user data
+```
+
+## 4. Determine Phase Numbers
+
+Find highest existing phase:
+```bash
+ls -d .planning/phases/*/ | sort -V | tail -1
+```
+
+New phases continue from there:
+- If Phase 5 is highest, gaps become Phase 6, 7, 8...
+
+## 5. Present Gap Closure Plan
+
+```markdown
+## Gap Closure Plan
+
+**Milestone:** {version}
+**Gaps to close:** {N} requirements, {M} integration, {K} flows
+
+### Proposed Phases
+
+**Phase {N}: {Name}**
+Closes:
+- {REQ-ID}: {description}
+- Integration: {from} → {to}
+Tasks: {count}
+
+**Phase {N+1}: {Name}**
+Closes:
+- {REQ-ID}: {description}
+- Flow: {flow name}
+Tasks: {count}
+
+{If nice-to-have gaps exist:}
+
+### Deferred (nice-to-have)
+
+These gaps are optional. Include them?
+- {gap description}
+- {gap description}
+
+---
+
+Create these {X} phases? (yes / adjust / defer all optional)
+```
+
+Wait for user confirmation.
+
+## 6. Update ROADMAP.md
+
+Add new phases to current milestone:
+
+```markdown
+### Phase {N}: {Name}
+**Goal:** {derived from gaps being closed}
+**Requirements:** {REQ-IDs being satisfied}
+**Gap Closure:** Closes gaps from audit
+
+### Phase {N+1}: {Name}
+...
+```
+
+## 7. Create Phase Directories
+
+```bash
+mkdir -p ".planning/phases/{NN}-{name}"
+```
+
+## 8. Commit Roadmap Update
+
+```bash
+git add .planning/ROADMAP.md
+git commit -m "docs(roadmap): add gap closure phases {N}-{M}"
+```
+
+## 9. Offer Next Steps
+
+```markdown
+## ✓ Gap Closure Phases Created
+
+**Phases added:** {N} - {M}
+**Gaps addressed:** {count} requirements, {count} integration, {count} flows
+
+---
+
+## ▶ Next Up
+
+**Plan first gap closure phase**
+
+`/ms:plan-phase {N}`
+
+<sub>`/clear` first → fresh context window</sub>
+
+---
+
+**Also available:**
+- `/ms:execute-phase {N}` — if plans already exist
+- `cat .planning/ROADMAP.md` — see updated roadmap
+
+---
+
+**After all gap phases complete:**
+
+`/ms:audit-milestone` — re-audit to verify gaps closed
+`/ms:complete-milestone {version}` — archive when audit passes
+```
+
+</process>
+
+<gap_to_phase_mapping>
+
+## How Gaps Become Tasks
+
+**Requirement gap → Tasks:**
+```yaml
+gap:
+  id: DASH-01
+  description: "User sees their data"
+  reason: "Dashboard exists but doesn't fetch from API"
+  missing:
+    - "useEffect with fetch to /api/user/data"
+    - "State for user data"
+    - "Render user data in JSX"
+
+becomes:
+
+phase: "Wire Dashboard Data"
+tasks:
+  - name: "Add data fetching"
+    files: [src/components/Dashboard.tsx]
+    action: "Add useEffect that fetches /api/user/data on mount"
+
+  - name: "Add state management"
+    files: [src/components/Dashboard.tsx]
+    action: "Add useState for userData, loading, error states"
+
+  - name: "Render user data"
+    files: [src/components/Dashboard.tsx]
+    action: "Replace placeholder with userData.map rendering"
+```
+
+**Integration gap → Tasks:**
+```yaml
+gap:
+  from_phase: 1
+  to_phase: 3
+  connection: "Auth token → API calls"
+  reason: "Dashboard API calls don't include auth header"
+  missing:
+    - "Auth header in fetch calls"
+    - "Token refresh on 401"
+
+becomes:
+
+phase: "Add Auth to Dashboard API Calls"
+tasks:
+  - name: "Add auth header to fetches"
+    files: [src/components/Dashboard.tsx, src/lib/api.ts]
+    action: "Include Authorization header with token in all API calls"
+
+  - name: "Handle 401 responses"
+    files: [src/lib/api.ts]
+    action: "Add interceptor to refresh token or redirect to login on 401"
+```
+
+**Flow gap → Tasks:**
+```yaml
+gap:
+  name: "User views dashboard after login"
+  broken_at: "Dashboard data load"
+  reason: "No fetch call"
+  missing:
+    - "Fetch user data on mount"
+    - "Display loading state"
+    - "Render user data"
+
+becomes:
+
+# Usually same phase as requirement/integration gap
+# Flow gaps often overlap with other gap types
+```
+
+</gap_to_phase_mapping>
+
+<success_criteria>
+- [ ] MILESTONE-AUDIT.md loaded and gaps parsed
+- [ ] Gaps prioritized (must/should/nice)
+- [ ] Gaps grouped into logical phases
+- [ ] User confirmed phase plan
+- [ ] ROADMAP.md updated with new phases
+- [ ] Phase directories created
+- [ ] Changes committed
+- [ ] User knows to run `/ms:plan-phase` next
+</success_criteria>

package/commands/ms/plan-phase.md

@@ -0,0 +1,105 @@
+---
+name: ms:plan-phase
+description: Create detailed execution plan for a phase (PLAN.md)
+argument-hint: "[phase] [--gaps]"
+allowed-tools:
+  - Read
+  - Bash
+  - Write
+  - Glob
+  - Grep
+  - AskUserQuestion
+  - WebFetch
+  - mcp__context7__*
+---
+
+<objective>
+Create executable phase prompt with discovery, context injection, and task breakdown.
+
+Purpose: Break down roadmap phases into concrete, executable PLAN.md files that Claude can execute.
+Output: One or more PLAN.md files in the phase directory (.planning/phases/XX-name/{phase}-{plan}-PLAN.md)
+
+**Gap closure mode (`--gaps` flag):**
+When invoked with `--gaps`, plans address gaps identified by the verifier. Load VERIFICATION.md, create plans to close specific gaps.
+</objective>
+
+<execution_context>
+@~/.claude/mindsystem/references/principles.md
+@~/.claude/mindsystem/workflows/plan-phase.md
+@~/.claude/mindsystem/templates/phase-prompt.md
+@~/.claude/mindsystem/references/plan-format.md
+@~/.claude/mindsystem/references/scope-estimation.md
+@~/.claude/mindsystem/references/checkpoints.md
+@~/.claude/mindsystem/references/tdd.md
+@~/.claude/mindsystem/references/goal-backward.md
+</execution_context>
+
+<context>
+Phase number: $ARGUMENTS (optional - auto-detects next unplanned phase if not provided)
+Gap closure mode: `--gaps` flag triggers gap closure workflow
+
+**Load project state first:**
+@.planning/STATE.md
+
+**Load roadmap:**
+@.planning/ROADMAP.md
+
+**Load requirements:**
+@.planning/REQUIREMENTS.md
+
+After loading, extract the requirements for the current phase:
+1. Find the phase in ROADMAP.md, get its `Requirements:` list (e.g., "PROF-01, PROF-02, PROF-03")
+2. Look up each REQ-ID in REQUIREMENTS.md to get the full description
+3. Present the requirements this phase must satisfy:
+   ```
+   Phase [N] Requirements:
+   - PROF-01: User can create profile with display name
+   - PROF-02: User can upload avatar image
+   - PROF-03: User can write bio (max 500 chars)
+   ```
+
+**Load phase context if exists (created by /ms:discuss-phase):**
+Check for and read `.planning/phases/XX-name/{phase}-CONTEXT.md` - contains research findings, clarifications, and decisions from phase discussion.
+
+**Load design specs if exists (created by /ms:design-phase):**
+Check for and read `.planning/phases/XX-name/{phase}-DESIGN.md` - contains visual/UX specifications including layouts, components, flows, and verification criteria.
+
+**Load codebase context if exists:**
+Check for `.planning/codebase/` and load relevant documents based on phase type.
+
+**If --gaps flag present, also load:**
+@.planning/phases/XX-name/{phase}-VERIFICATION.md — contains structured gaps in YAML frontmatter
+</context>
+
+<process>
+1. Check .planning/ directory exists (error if not - user should run /ms:new-project)
+2. Parse arguments: extract phase number and check for `--gaps` flag
+3. If phase number provided, validate it exists in roadmap
+4. If no phase number, detect next unplanned phase from roadmap
+
+**Standard mode (no --gaps flag):**
+5. Follow plan-phase.md workflow:
+   - Load project state and accumulated decisions
+   - Perform mandatory discovery (Level 0-3 as appropriate)
+   - Read project history (prior decisions, issues, concerns)
+   - Break phase into tasks
+   - Estimate scope and split into multiple plans if needed
+   - Create PLAN.md file(s) with executable structure
+
+**Gap closure mode (--gaps flag):**
+5. Follow plan-phase.md workflow with gap_closure_mode:
+   - Load VERIFICATION.md and parse `gaps:` YAML from frontmatter
+   - Read existing SUMMARYs to understand what's already built
+   - Create tasks from gaps (each gap.missing item → task candidates)
+   - Number plans sequentially after existing (if 01-03 exist, create 04, 05...)
+   - Create PLAN.md file(s) focused on closing specific gaps
+</process>
+
+<success_criteria>
+
+- One or more PLAN.md files created in .planning/phases/XX-name/
+- Each plan has: objective, execution_context, context, tasks, verification, success_criteria, output
+- must_haves derived from phase goal and documented in frontmatter (truths, artifacts, key_links)
+- Tasks are specific enough for Claude to execute
+- User knows next steps (execute plan or review/adjust)
+  </success_criteria>