mindsystem-cc 3.0.0

package/commands/ms/add-todo.md

@@ -0,0 +1,182 @@
+---
+name: ms:add-todo
+description: Capture idea or task as todo from current conversation context
+argument-hint: [optional description]
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - Glob
+---
+
+<objective>
+Capture an idea, task, or issue that surfaces during a Mindsystem session as a structured todo for later work.
+
+Enables "thought → capture → continue" flow without losing context or derailing current work.
+</objective>
+
+<context>
+@.planning/STATE.md
+</context>
+
+<process>
+
+<step name="ensure_directory">
+```bash
+mkdir -p .planning/todos/pending .planning/todos/done
+```
+</step>
+
+<step name="check_existing_areas">
+```bash
+ls .planning/todos/pending/*.md 2>/dev/null | xargs -I {} grep "^area:" {} 2>/dev/null | cut -d' ' -f2 | sort -u
+```
+
+Note existing areas for consistency in infer_area step.
+</step>
+
+<step name="extract_content">
+**With arguments:** Use as the title/focus.
+- `/ms:add-todo Add auth token refresh` → title = "Add auth token refresh"
+
+**Without arguments:** Analyze recent conversation to extract:
+- The specific problem, idea, or task discussed
+- Relevant file paths mentioned
+- Technical details (error messages, line numbers, constraints)
+
+Formulate:
+- `title`: 3-10 word descriptive title (action verb preferred)
+- `problem`: What's wrong or why this is needed
+- `solution`: Approach hints or "TBD" if just an idea
+- `files`: Relevant paths with line numbers from conversation
+</step>
+
+<step name="infer_area">
+Infer area from file paths:
+
+| Path pattern | Area |
+|--------------|------|
+| `src/api/*`, `api/*` | `api` |
+| `src/components/*`, `src/ui/*` | `ui` |
+| `src/auth/*`, `auth/*` | `auth` |
+| `src/db/*`, `database/*` | `database` |
+| `tests/*`, `__tests__/*` | `testing` |
+| `docs/*` | `docs` |
+| `.planning/*` | `planning` |
+| `scripts/*`, `bin/*` | `tooling` |
+| No files or unclear | `general` |
+
+Use existing area from step 2 if similar match exists.
+</step>
+
+<step name="check_duplicates">
+```bash
+grep -l -i "[key words from title]" .planning/todos/pending/*.md 2>/dev/null
+```
+
+If potential duplicate found:
+1. Read the existing todo
+2. Compare scope
+
+If overlapping, use AskUserQuestion:
+- header: "Duplicate?"
+- question: "Similar todo exists: [title]. What would you like to do?"
+- options:
+  - "Skip" — keep existing todo
+  - "Replace" — update existing with new context
+  - "Add anyway" — create as separate todo
+</step>
+
+<step name="create_file">
+```bash
+timestamp=$(date "+%Y-%m-%dT%H:%M")
+date_prefix=$(date "+%Y-%m-%d")
+```
+
+Generate slug from title (lowercase, hyphens, no special chars).
+
+Write to `.planning/todos/pending/${date_prefix}-${slug}.md`:
+
+```markdown
+---
+created: [timestamp]
+title: [title]
+area: [area]
+files:
+  - [file:lines]
+---
+
+## Problem
+
+[problem description - enough context for future Claude to understand weeks later]
+
+## Solution
+
+[approach hints or "TBD"]
+```
+</step>
+
+<step name="update_state">
+If `.planning/STATE.md` exists:
+
+1. Count todos: `ls .planning/todos/pending/*.md 2>/dev/null | wc -l`
+2. Update "### Pending Todos" under "## Accumulated Context"
+</step>
+
+<step name="git_commit">
+Commit the todo and any updated state:
+
+```bash
+git add .planning/todos/pending/[filename]
+[ -f .planning/STATE.md ] && git add .planning/STATE.md
+git commit -m "$(cat <<'EOF'
+docs: capture todo - [title]
+
+Area: [area]
+EOF
+)"
+```
+
+Confirm: "Committed: docs: capture todo - [title]"
+</step>
+
+<step name="confirm">
+```
+Todo saved: .planning/todos/pending/[filename]
+
+  [title]
+  Area: [area]
+  Files: [count] referenced
+
+---
+
+Would you like to:
+
+1. Continue with current work
+2. Add another todo
+3. View all todos (/ms:check-todos)
+```
+</step>
+
+</process>
+
+<output>
+- `.planning/todos/pending/[date]-[slug].md`
+- Updated `.planning/STATE.md` (if exists)
+</output>
+
+<anti_patterns>
+- Don't create todos for work in current plan (that's deviation rule territory)
+- Don't create elaborate solution sections — captures ideas, not plans
+- Don't block on missing information — "TBD" is fine
+</anti_patterns>
+
+<success_criteria>
+- [ ] Directory structure exists
+- [ ] Todo file created with valid frontmatter
+- [ ] Problem section has enough context for future Claude
+- [ ] No duplicates (checked and resolved)
+- [ ] Area consistent with existing todos
+- [ ] STATE.md updated if exists
+- [ ] Todo and state committed to git
+</success_criteria>

package/commands/ms/audit-milestone.md

@@ -0,0 +1,318 @@
+---
+name: ms:audit-milestone
+description: Audit milestone completion against original intent before archiving
+argument-hint: "[version]"
+allowed-tools:
+  - Read
+  - Glob
+  - Grep
+  - Bash
+  - Task
+  - Write
+---
+
+<objective>
+Verify milestone achieved its definition of done. Check requirements coverage, cross-phase integration, and end-to-end flows.
+
+**This command IS the orchestrator.** Reads existing VERIFICATION.md files (phases already verified during execute-phase), aggregates tech debt and deferred gaps, then spawns integration checker for cross-phase wiring.
+</objective>
+
+<execution_context>
+@~/.claude/mindsystem/references/principles.md
+</execution_context>
+
+<context>
+Version: $ARGUMENTS (optional — defaults to current milestone)
+
+**Original Intent:**
+@.planning/PROJECT.md
+@.planning/REQUIREMENTS.md
+
+**Planned Work:**
+@.planning/ROADMAP.md
+@.planning/config.json (if exists)
+
+**Completed Work:**
+Glob: .planning/phases/*/*-SUMMARY.md
+Glob: .planning/phases/*/*-VERIFICATION.md
+</context>
+
+<process>
+
+## 1. Determine Milestone Scope
+
+```bash
+# Get phases in milestone
+ls -d .planning/phases/*/ | sort -V
+```
+
+- Parse version from arguments or detect current from ROADMAP.md
+- Identify all phase directories in scope
+- Extract milestone definition of done from ROADMAP.md
+- Extract requirements mapped to this milestone from REQUIREMENTS.md
+
+## 2. Read All Phase Verifications
+
+For each phase directory, read the VERIFICATION.md:
+
+```bash
+cat .planning/phases/01-*/*-VERIFICATION.md
+cat .planning/phases/02-*/*-VERIFICATION.md
+# etc.
+```
+
+From each VERIFICATION.md, extract:
+- **Status:** passed | gaps_found
+- **Critical gaps:** (if any — these are blockers)
+- **Non-critical gaps:** tech debt, deferred items, warnings
+- **Anti-patterns found:** TODOs, stubs, placeholders
+- **Requirements coverage:** which requirements satisfied/blocked
+
+If a phase is missing VERIFICATION.md, flag it as "unverified phase" — this is a blocker.
+
+## 2.5. Read UAT Files and Aggregate Assumptions
+
+```bash
+# Find all UAT files
+find .planning/phases -name "*-UAT.md" -type f 2>/dev/null
+```
+
+For each UAT file, extract:
+- **Assumptions section:** Tests skipped because required state couldn't be mocked
+
+Aggregate assumptions by phase:
+```yaml
+assumptions:
+  count: [N]
+  by_phase:
+    - phase: 04-comments
+      items:
+        - name: "Error state display"
+          expected: "Shows error message when API fails"
+          reason: "Can't mock API error responses"
+    - phase: 05-auth
+      items:
+        - name: "Session timeout"
+          expected: "User redirected to login after 30min"
+          reason: "Can't manipulate time in tests"
+```
+
+## 3. Spawn Integration Checker
+
+With phase context collected:
+
+```
+Task(
+  prompt="Check cross-phase integration and E2E flows.
+
+Phases: {phase_dirs}
+Phase exports: {from SUMMARYs}
+API routes: {routes created}
+
+Verify cross-phase wiring and E2E user flows.",
+  subagent_type="ms-integration-checker"
+)
+```
+
+## 4. Collect Results
+
+Combine:
+- Phase-level gaps and tech debt (from step 2)
+- Integration checker's report (wiring gaps, broken flows)
+
+## 5. Check Requirements Coverage
+
+For each requirement in REQUIREMENTS.md mapped to this milestone:
+- Find owning phase
+- Check phase verification status
+- Determine: satisfied | partial | unsatisfied
+
+## 6. Aggregate into v{version}-MILESTONE-AUDIT.md
+
+Create `.planning/v{version}-v{version}-MILESTONE-AUDIT.md` with:
+
+```yaml
+---
+milestone: {version}
+audited: {timestamp}
+status: passed | gaps_found | tech_debt
+scores:
+  requirements: N/M
+  phases: N/M
+  integration: N/M
+  flows: N/M
+gaps:  # Critical blockers
+  requirements: [...]
+  integration: [...]
+  flows: [...]
+tech_debt:  # Non-critical, deferred
+  - phase: 01-auth
+    items:
+      - "TODO: add rate limiting"
+      - "Warning: no password strength validation"
+  - phase: 03-dashboard
+    items:
+      - "Deferred: mobile responsive layout"
+assumptions:  # Tests skipped during UAT
+  count: [N]
+  by_phase:
+    - phase: 04-comments
+      items:
+        - name: "Error state display"
+          expected: "Shows error message when API fails"
+---
+```
+
+Plus full markdown report with tables for requirements, phases, integration, tech debt, and assumptions.
+
+**Assumptions section in markdown report:**
+
+```markdown
+## Untested Assumptions
+
+{N} tests were skipped because required states couldn't be mocked:
+
+| Phase | Test | Expected Behavior | Reason |
+|-------|------|-------------------|--------|
+| 04-comments | Error state display | Shows error message when API fails | Can't mock API errors |
+| 04-comments | Empty state | Shows placeholder when no comments | Can't clear test data |
+| 05-auth | Session timeout | Redirects to login after 30min | Can't manipulate time |
+
+**Consider:** Plan test infrastructure work in next milestone to verify these assumptions.
+```
+
+**Status values:**
+- `passed` — all requirements met, no critical gaps, minimal tech debt
+- `gaps_found` — critical blockers exist
+- `tech_debt` — no blockers but accumulated deferred items need review
+
+## 7. Present Results
+
+Route by status (see `<offer_next>`).
+
+</process>
+
+<offer_next>
+**If passed:**
+
+```markdown
+## ✓ Milestone {version} — Audit Passed
+
+**Score:** {N}/{M} requirements satisfied
+**Report:** .planning/v{version}-MILESTONE-AUDIT.md
+
+All requirements covered. Cross-phase integration verified. E2E flows complete.
+
+[If assumptions > 0:]
+### Untested Assumptions: {N} items
+
+These tests were skipped because required states couldn't be mocked.
+See full list in MILESTONE-AUDIT.md. Consider addressing in next milestone.
+
+---
+
+## ▶ Next Up
+
+**Complete milestone** — archive and tag
+
+`/ms:complete-milestone {version}`
+
+<sub>`/clear` first → fresh context window</sub>
+```
+
+---
+
+**If gaps_found:**
+
+```markdown
+## ⚠ Milestone {version} — Gaps Found
+
+**Score:** {N}/{M} requirements satisfied
+**Report:** .planning/v{version}-MILESTONE-AUDIT.md
+
+### Unsatisfied Requirements
+
+{For each unsatisfied requirement:}
+- **{REQ-ID}: {description}** (Phase {X})
+  - {reason}
+
+### Cross-Phase Issues
+
+{For each integration gap:}
+- **{from} → {to}:** {issue}
+
+### Broken Flows
+
+{For each flow gap:}
+- **{flow name}:** breaks at {step}
+
+---
+
+## ▶ Next Up
+
+**Plan gap closure** — create phases to complete milestone
+
+`/ms:plan-milestone-gaps`
+
+<sub>`/clear` first → fresh context window</sub>
+
+---
+
+**Also available:**
+- `cat .planning/v{version}-MILESTONE-AUDIT.md` — see full report
+- `/ms:complete-milestone {version}` — proceed anyway (accept tech debt)
+```
+
+---
+
+**If tech_debt (no blockers but accumulated debt):**
+
+```markdown
+## ⚡ Milestone {version} — Tech Debt Review
+
+**Score:** {N}/{M} requirements satisfied
+**Report:** .planning/v{version}-MILESTONE-AUDIT.md
+
+All requirements met. No critical blockers. Accumulated tech debt needs review.
+
+### Tech Debt by Phase
+
+{For each phase with debt:}
+**Phase {X}: {name}**
+- {item 1}
+- {item 2}
+
+### Total: {N} items across {M} phases
+
+[If assumptions > 0:]
+### Untested Assumptions: {N} items
+
+These tests were skipped because required states couldn't be mocked.
+See full list in MILESTONE-AUDIT.md. Consider addressing in next milestone.
+
+---
+
+## ▶ Options
+
+**A. Complete milestone** — accept debt, track in backlog
+
+`/ms:complete-milestone {version}`
+
+**B. Plan cleanup phase** — address debt before completing
+
+`/ms:plan-milestone-gaps`
+
+<sub>`/clear` first → fresh context window</sub>
+```
+</offer_next>
+
+<success_criteria>
+- [ ] Milestone scope identified
+- [ ] All phase VERIFICATION.md files read
+- [ ] All phase UAT.md files read for assumptions
+- [ ] Tech debt and deferred gaps aggregated
+- [ ] Assumptions aggregated by phase
+- [ ] Integration checker spawned for cross-phase wiring
+- [ ] v{version}-MILESTONE-AUDIT.md created with assumptions section
+- [ ] Results presented with actionable next steps
+</success_criteria>

package/commands/ms/check-phase.md

@@ -0,0 +1,162 @@
+---
+name: ms:check-phase
+description: Verify phase plans before execution (optional quality gate)
+arguments: phase
+allowed-tools:
+  - Read
+  - Bash
+  - Glob
+  - Grep
+  - Task
+---
+
+<purpose>
+On-demand plan verification. Use when a plan seems large or complex and you want a structured review before executing.
+
+This spawns ms-plan-checker to analyze your PLAN.md files against the phase goal.
+</purpose>
+
+<what_it_checks>
+1. **Requirement Coverage** — Does every phase requirement have tasks addressing it?
+2. **Task Completeness** — Does every task have files, action, verify, done?
+3. **Dependency Correctness** — Are plan dependencies valid and acyclic?
+4. **Key Links Planned** — Are artifacts wired together, not just created in isolation?
+5. **Scope Sanity** — Will plans complete within context budget (2-3 tasks per plan)?
+6. **Verification Derivation** — Are must_haves user-observable, not implementation-focused?
+</what_it_checks>
+
+<process>
+
+<step name="validate_phase">
+Phase number from $ARGUMENTS (required).
+
+```bash
+PHASE=$ARGUMENTS
+PADDED=$(printf "%02d" $PHASE 2>/dev/null || echo "$PHASE")
+PHASE_DIR=$(ls -d .planning/phases/${PADDED}-* .planning/phases/${PHASE}-* 2>/dev/null | head -1)
+
+if [ -z "$PHASE_DIR" ]; then
+  echo "Error: Phase $PHASE not found in .planning/phases/"
+  exit 1
+fi
+
+echo "Phase directory: $PHASE_DIR"
+ls "$PHASE_DIR"/*-PLAN.md 2>/dev/null
+```
+
+If no PLAN.md files found, remind user to run `/ms:plan-phase` first.
+</step>
+
+<step name="load_context">
+Read the phase goal from ROADMAP.md:
+
+```bash
+grep -A 15 "Phase ${PHASE}:" .planning/ROADMAP.md | head -20
+```
+
+Count plans and tasks:
+
+```bash
+for plan in "$PHASE_DIR"/*-PLAN.md; do
+  echo "=== $(basename $plan) ==="
+  grep -c "<task" "$plan" 2>/dev/null || echo "0 tasks"
+done
+```
+</step>
+
+<step name="spawn_checker">
+Spawn the plan checker agent:
+
+```
+Task(
+  subagent_type="ms-plan-checker",
+  prompt="""
+Verify plans for phase $ARGUMENTS.
+
+1. Read .planning/ROADMAP.md to get the phase goal
+2. Read all *-PLAN.md files in the phase directory
+3. Run all 6 verification dimensions
+4. Return structured result
+
+Phase directory: $PHASE_DIR
+""",
+  description="Verify phase $ARGUMENTS plans"
+)
+```
+</step>
+
+<step name="present_results">
+Present the checker's findings clearly.
+
+**Format for VERIFICATION PASSED:**
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ PLAN VERIFICATION: PASSED
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Phase: [name]
+Plans: [count]
+Tasks: [total count]
+
+All checks passed:
+✓ Requirement coverage complete
+✓ All tasks have required fields
+✓ Dependency graph valid
+✓ Key links planned
+✓ Scope within budget
+✓ Verification criteria derived
+
+Ready to execute: /ms:execute-phase $ARGUMENTS
+```
+
+**Format for ISSUES FOUND:**
+
+```
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+ PLAN VERIFICATION: ISSUES FOUND
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+Phase: [name]
+Plans: [count]
+Issues: [X blockers, Y warnings]
+
+BLOCKERS (must fix):
+
+1. [dimension] [description]
+   Plan: [which plan]
+   Fix: [specific fix hint]
+
+2. [dimension] [description]
+   Plan: [which plan]
+   Fix: [specific fix hint]
+
+WARNINGS (should fix):
+
+1. [dimension] [description]
+   Fix: [hint]
+
+---
+
+Options:
+- Fix the issues and run /ms:check-phase $ARGUMENTS again
+- Proceed anyway: /ms:execute-phase $ARGUMENTS (not recommended if blockers exist)
+```
+</step>
+
+</process>
+
+<examples>
+**Check before executing a complex phase:**
+```
+/ms:check-phase 5
+```
+
+**Typical workflow:**
+```
+/ms:plan-phase 5      # Interactive planning in main context
+# ... review and iterate ...
+/ms:check-phase 5      # Optional verification for complex plans
+/ms:execute-phase 5   # Execute
+```
+</examples>