mindsystem-cc 3.0.0

package/commands/ms/discuss-phase.md

@@ -0,0 +1,60 @@
+---
+name: ms:discuss-phase
+description: Gather phase context through adaptive questioning before planning
+argument-hint: "[phase]"
+---
+
+<objective>
+Help the user articulate their vision for a phase through collaborative thinking.
+
+Purpose: Understand HOW the user imagines this phase working — what it looks like, what's essential. You're a thinking partner helping them crystallize their vision, not an interviewer gathering technical requirements.
+
+Output: {phase}-CONTEXT.md capturing the user's vision for the phase
+</objective>
+
+<execution_context>
+@~/.claude/mindsystem/references/principles.md
+@~/.claude/mindsystem/workflows/discuss-phase.md
+@~/.claude/mindsystem/templates/context.md
+</execution_context>
+
+<context>
+Phase number: $ARGUMENTS (required)
+
+**Load project state first:**
+@.planning/STATE.md
+
+**Load roadmap:**
+@.planning/ROADMAP.md
+</context>
+
+<process>
+1. Validate phase number argument (error if missing or invalid)
+2. Check if phase exists in roadmap
+3. Check if CONTEXT.md already exists (offer to update if yes)
+4. Follow discuss-phase.md workflow with **ALL questions using AskUserQuestion**:
+   - Present phase from roadmap
+   - Use AskUserQuestion: "How do you imagine this working?" with interpretation options
+   - Use AskUserQuestion to follow their thread — probe what excites them
+   - Use AskUserQuestion to sharpen the core — what's essential for THIS phase
+   - Use AskUserQuestion for decision gate (ready / ask more / let me add context)
+   - Create CONTEXT.md capturing their vision
+5. Offer next steps (research or plan the phase)
+
+**CRITICAL: ALL questions use AskUserQuestion. Never ask inline text questions.**
+
+User is the visionary, you are the builder:
+- Ask about vision, feel, essential outcomes
+- DON'T ask about technical risks (you figure those out)
+- DON'T ask about codebase patterns (you read the code)
+- DON'T ask about success metrics (too corporate)
+- DON'T interrogate about constraints they didn't mention
+</process>
+
+<success_criteria>
+
+- Phase validated against roadmap
+- Vision gathered through collaborative thinking (not interrogation)
+- CONTEXT.md captures: how it works, what's essential
+- User knows next steps (research or plan the phase)
+</success_criteria>

package/commands/ms/do-work.md

@@ -0,0 +1,90 @@
+---
+name: ms:do-work
+description: Execute small discovered work without phase overhead (max 2 tasks)
+argument-hint: <description>
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Bash
+  - Glob
+  - Grep
+  - Task
+  - AskUserQuestion
+---
+
+<objective>
+Execute small work items discovered during verification or debugging without the overhead of phase insertion or todos.
+
+Bridges the gap between "capture for later" (/ms:add-todo) and "full phase workflow" (/ms:insert-phase).
+
+Use when:
+- Work is small (1-2 tasks maximum)
+- Work is discovered mid-session (not pre-planned)
+- Work can be completed quickly
+- Work doesn't require architectural changes
+</objective>
+
+<execution_context>
+@~/.claude/mindsystem/workflows/do-work.md
+@.planning/STATE.md
+</execution_context>
+
+<process>
+
+<step name="parse_and_validate">
+Parse the work description from $ARGUMENTS.
+Validate project has .planning/STATE.md (active Mindsystem project required).
+</step>
+
+<step name="analyze_scope">
+Quick analysis of what tasks are needed.
+If >2 tasks or architectural changes required: REFUSE with suggestion to use /ms:insert-phase.
+</step>
+
+<step name="create_lightweight_plan">
+Create .planning/adhoc/{timestamp}-{slug}-PLAN.md with minimal structure.
+</step>
+
+<step name="execute_tasks">
+Execute tasks inline (no subagent for small work).
+Apply deviation rules 1-3 (auto-fix bugs, critical, blocking).
+If Rule 4 triggered (architectural): STOP, suggest /ms:insert-phase.
+</step>
+
+<step name="verify_and_summarize">
+Run verify commands from tasks.
+Create .planning/adhoc/{timestamp}-{slug}-SUMMARY.md.
+</step>
+
+<step name="update_state_and_commit">
+Add entry to STATE.md "Recent Adhoc Work" section.
+Single git commit with all changes (code + PLAN.md + SUMMARY.md + STATE.md).
+</step>
+
+<step name="completion">
+Report what was done, show commit hash and file paths.
+</step>
+
+</process>
+
+<anti_patterns>
+- Don't use for work requiring >2 tasks (use /ms:insert-phase)
+- Don't use for work requiring architectural changes
+- Don't use outside active Mindsystem projects (needs STATE.md)
+- Don't create elaborate plans — this is for quick fixes
+- Don't run full goal-backward verification — lightweight checks only
+</anti_patterns>
+
+<success_criteria>
+Adhoc work is complete when:
+
+- [ ] Work analyzed and confirmed ≤2 tasks
+- [ ] .planning/adhoc/ directory exists
+- [ ] PLAN.md created with tasks
+- [ ] All tasks executed and verified
+- [ ] SUMMARY.md created with outcomes
+- [ ] STATE.md updated with adhoc entry
+- [ ] Single git commit with all changes
+- [ ] User informed of completion and commit hash
+</success_criteria>

package/commands/ms/execute-phase.md

@@ -0,0 +1,289 @@
+---
+name: ms:execute-phase
+description: Execute all plans in a phase with wave-based parallelization
+argument-hint: "<phase-number>"
+allowed-tools:
+  - Read
+  - Write
+  - Edit
+  - Glob
+  - Grep
+  - Bash
+  - Task
+  - TodoWrite
+  - AskUserQuestion
+---
+
+<objective>
+Execute all plans in a phase using wave-based parallel execution.
+
+Orchestrator stays lean: discover plans, analyze dependencies, group into waves, spawn subagents, collect results. Each subagent loads the full execute-plan context and handles its own plan.
+
+Context budget: ~15% orchestrator, 100% fresh per subagent.
+</objective>
+
+<execution_context>
+@~/.claude/mindsystem/references/principles.md
+@~/.claude/mindsystem/workflows/execute-phase.md
+</execution_context>
+
+<context>
+Phase: $ARGUMENTS
+
+@.planning/ROADMAP.md
+@.planning/STATE.md
+</context>
+
+<process>
+1. **Validate phase exists**
+   - Find phase directory matching argument
+   - Count PLAN.md files
+   - Error if no plans found
+
+2. **Discover plans**
+   - List all *-PLAN.md files in phase directory
+   - Check which have *-SUMMARY.md (already complete)
+   - Build list of incomplete plans
+
+3. **Group by wave**
+   - Read `wave` from each plan's frontmatter
+   - Group plans by wave number
+   - Report wave structure to user
+
+4. **Execute waves**
+   For each wave in order:
+   - Spawn `ms-executor` for each plan in wave (parallel Task calls)
+   - Wait for completion (Task blocks)
+   - Verify SUMMARYs created
+   - Proceed to next wave
+
+5. **Aggregate results**
+   - Collect summaries from all plans
+   - Report phase completion status
+
+6. **Verify phase goal**
+   - Spawn `ms-verifier` subagent with phase directory and goal
+   - Verifier checks must_haves against actual codebase (not SUMMARY claims)
+   - Creates VERIFICATION.md with detailed report
+   - Route by status:
+     - `passed` → continue to step 7
+     - `human_needed` → present items, get approval or feedback
+     - `gaps_found` → present gaps, offer `/ms:plan-phase {X} --gaps`
+
+7. **Generate phase patch**
+   - Run: `~/.claude/mindsystem/scripts/generate-phase-patch.sh ${PHASE_NUMBER}`
+   - Outputs to `.planning/phases/{phase_dir}/{phase}-changes.patch`
+   - Verify: patch file exists OR skip message logged
+
+8. **Update roadmap and state**
+   - Update ROADMAP.md, STATE.md
+
+9. **Update requirements**
+   Mark phase requirements as Complete:
+   - Read ROADMAP.md, find this phase's `Requirements:` line (e.g., "AUTH-01, AUTH-02")
+   - Read REQUIREMENTS.md traceability table
+   - For each REQ-ID in this phase: change Status from "Pending" to "Complete"
+   - Write updated REQUIREMENTS.md
+   - Skip if: REQUIREMENTS.md doesn't exist, or phase has no Requirements line
+
+10. **Commit phase completion**
+    Bundle all phase metadata updates in one commit:
+    - Stage: `git add .planning/ROADMAP.md .planning/STATE.md`
+    - Stage REQUIREMENTS.md if updated: `git add .planning/REQUIREMENTS.md`
+    - Commit: `docs({phase}): complete {phase-name} phase`
+
+11. **Offer next steps**
+    - Route to next action (see `<offer_next>`)
+</process>
+
+<offer_next>
+**MANDATORY: Present copy/paste-ready next command.**
+
+After verification completes, route based on status:
+
+| Status | Route |
+|--------|-------|
+| `gaps_found` | Route C (gap closure) |
+| `human_needed` | Present checklist, then re-route based on approval |
+| `passed` + more phases | Route A (next phase) |
+| `passed` + last phase | Route B (milestone complete) |
+
+---
+
+**Route A: Phase verified, more phases remain**
+
+```
+## ✓ Phase {Z}: {Name} Complete
+
+All {Y} plans finished. Phase goal verified.
+
+---
+
+## ▶ Next Up
+
+**Phase {Z+1}: {Name}** — {Goal from ROADMAP.md}
+
+`/ms:plan-phase {Z+1}`
+
+<sub>`/clear` first → fresh context window</sub>
+
+---
+
+**Also available:**
+- `/ms:verify-work {Z}` — manual acceptance testing before continuing
+- `/ms:discuss-phase {Z+1}` — gather context first
+- `/ms:research-phase {Z+1}` — investigate unknowns
+
+---
+```
+
+---
+
+**Route B: Phase verified, milestone complete**
+
+```
+🎉 ALL PHASES COMPLETE!
+
+## ✓ Phase {Z}: {Name} Complete
+
+All {N} phases finished. Phase goals verified.
+
+---
+
+## ▶ Next Up
+
+**Audit milestone** — verify requirements, cross-phase integration, E2E flows
+
+`/ms:audit-milestone`
+
+<sub>`/clear` first → fresh context window</sub>
+
+---
+
+**Also available:**
+- `/ms:verify-work` — manual acceptance testing
+- `/ms:complete-milestone` — skip audit, archive directly
+- `/ms:add-phase <description>` — add another phase first
+
+---
+```
+
+---
+
+**Route C: Gaps found — need additional planning**
+
+```
+## ⚠ Phase {Z}: {Name} — Gaps Found
+
+**Score:** {N}/{M} must-haves verified
+**Report:** .planning/phases/{phase_dir}/{phase}-VERIFICATION.md
+
+### What's Missing
+
+{Extract gap summaries from VERIFICATION.md}
+
+---
+
+## ▶ Next Up
+
+**Plan gap closure** — create additional plans to complete the phase
+
+`/ms:plan-phase {Z} --gaps`
+
+<sub>`/clear` first → fresh context window</sub>
+
+---
+
+**Also available:**
+- `cat .planning/phases/{phase_dir}/{phase}-VERIFICATION.md` — see full report
+- `/ms:verify-work {Z}` — manual testing before planning
+
+---
+```
+
+After user runs `/ms:plan-phase {Z} --gaps`:
+1. Planner reads VERIFICATION.md gaps
+2. Creates plans 04, 05, etc. to close gaps
+3. User runs `/ms:execute-phase {Z}` again
+4. Execute-phase runs incomplete plans (04, 05...)
+5. Verifier runs again → loop until passed
+</offer_next>
+
+<wave_execution>
+**Parallel spawning:**
+
+Spawn all plans in a wave with a single message containing multiple Task calls:
+
+```
+Task(prompt="Execute plan at {plan_01_path}\n\nPlan: @{plan_01_path}\nProject state: @.planning/STATE.md", subagent_type="ms-executor")
+Task(prompt="Execute plan at {plan_02_path}\n\nPlan: @{plan_02_path}\nProject state: @.planning/STATE.md", subagent_type="ms-executor")
+Task(prompt="Execute plan at {plan_03_path}\n\nPlan: @{plan_03_path}\nProject state: @.planning/STATE.md", subagent_type="ms-executor")
+```
+
+All three run in parallel. Task tool blocks until all complete.
+
+**No polling.** No background agents. No TaskOutput loops.
+</wave_execution>
+
+<checkpoint_handling>
+Plans with `autonomous: false` have checkpoints. The execute-phase.md workflow handles the full checkpoint flow:
+- Subagent pauses at checkpoint, returns structured state
+- Orchestrator presents to user, collects response
+- Spawns fresh continuation agent (not resume)
+
+See `@~/.claude/mindsystem/workflows/execute-phase.md` step `checkpoint_handling` for complete details.
+</checkpoint_handling>
+
+<deviation_rules>
+During execution, handle discoveries automatically:
+
+1. **Auto-fix bugs** - Fix immediately, document in Summary
+2. **Auto-add critical** - Security/correctness gaps, add and document
+3. **Auto-fix blockers** - Can't proceed without fix, do it and document
+4. **Ask about architectural** - Major structural changes, stop and ask user
+
+Only rule 4 requires user intervention.
+</deviation_rules>
+
+<commit_rules>
+**Per-Task Commits:**
+
+After each task completes:
+1. Stage only files modified by that task
+2. Commit with format: `{type}({phase}-{plan}): {task-name}`
+3. Types: feat, fix, test, refactor, perf, chore
+4. Record commit hash for SUMMARY.md
+
+**Plan Metadata Commit:**
+
+After all tasks in a plan complete:
+1. Stage plan artifacts only: PLAN.md, SUMMARY.md
+2. Commit with format: `docs({phase}-{plan}): complete [plan-name] plan`
+3. NO code files (already committed per-task)
+
+**Phase Completion Commit:**
+
+After all plans in phase complete (step 7):
+1. Stage: ROADMAP.md, STATE.md, REQUIREMENTS.md (if updated), VERIFICATION.md
+2. Commit with format: `docs({phase}): complete {phase-name} phase`
+3. Bundles all phase-level state updates in one commit
+
+**NEVER use:**
+- `git add .`
+- `git add -A`
+- `git add src/` or any broad directory
+
+**Always stage files individually.**
+</commit_rules>
+
+<success_criteria>
+- [ ] All incomplete plans in phase executed
+- [ ] Each plan has SUMMARY.md
+- [ ] Phase goal verified (must_haves checked against codebase)
+- [ ] VERIFICATION.md created in phase directory
+- [ ] Patch file generated OR explicitly skipped with message
+- [ ] STATE.md reflects phase completion
+- [ ] ROADMAP.md updated
+- [ ] REQUIREMENTS.md updated (phase requirements marked Complete)
+- [ ] User informed of next steps
+</success_criteria>