mindsystem-cc 3.0.0

package/commands/ms/insert-phase.md

@@ -0,0 +1,227 @@
+---
+name: ms:insert-phase
+description: Insert urgent work as decimal phase (e.g., 72.1) between existing phases
+argument-hint: <after> <description>
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+---
+
+<objective>
+Insert a decimal phase for urgent work discovered mid-milestone that must be completed between existing integer phases.
+
+Uses decimal numbering (72.1, 72.2, etc.) to preserve the logical sequence of planned phases while accommodating urgent insertions.
+
+Purpose: Handle urgent work discovered during execution without renumbering entire roadmap.
+</objective>
+
+<execution_context>
+@.planning/ROADMAP.md
+@.planning/STATE.md
+</execution_context>
+
+<process>
+
+<step name="parse_arguments">
+Parse the command arguments:
+- First argument: integer phase number to insert after
+- Remaining arguments: phase description
+
+Example: `/ms:insert-phase 72 Fix critical auth bug`
+→ after = 72
+→ description = "Fix critical auth bug"
+
+Validation:
+
+```bash
+if [ $# -lt 2 ]; then
+  echo "ERROR: Both phase number and description required"
+  echo "Usage: /ms:insert-phase <after> <description>"
+  echo "Example: /ms:insert-phase 72 Fix critical auth bug"
+  exit 1
+fi
+```
+
+Parse first argument as integer:
+
+```bash
+after_phase=$1
+shift
+description="$*"
+
+# Validate after_phase is an integer
+if ! [[ "$after_phase" =~ ^[0-9]+$ ]]; then
+  echo "ERROR: Phase number must be an integer"
+  exit 1
+fi
+```
+
+</step>
+
+<step name="load_roadmap">
+Load the roadmap file:
+
+```bash
+if [ -f .planning/ROADMAP.md ]; then
+  ROADMAP=".planning/ROADMAP.md"
+else
+  echo "ERROR: No roadmap found (.planning/ROADMAP.md)"
+  exit 1
+fi
+```
+
+Read roadmap content for parsing.
+</step>
+
+<step name="verify_target_phase">
+Verify that the target phase exists in the roadmap:
+
+1. Search for "### Phase {after_phase}:" heading
+2. If not found:
+
+   ```
+   ERROR: Phase {after_phase} not found in roadmap
+   Available phases: [list phase numbers]
+   ```
+
+   Exit.
+
+3. Verify phase is in current milestone (not completed/archived)
+   </step>
+
+<step name="find_existing_decimals">
+Find existing decimal phases after the target phase:
+
+1. Search for all "### Phase {after_phase}.N:" headings
+2. Extract decimal suffixes (e.g., for Phase 72: find 72.1, 72.2, 72.3)
+3. Find the highest decimal suffix
+4. Calculate next decimal: max + 1
+
+Examples:
+
+- Phase 72 with no decimals → next is 72.1
+- Phase 72 with 72.1 → next is 72.2
+- Phase 72 with 72.1, 72.2 → next is 72.3
+
+Store as: `decimal_phase="$(printf "%02d" $after_phase).${next_decimal}"`
+</step>
+
+<step name="generate_slug">
+Convert the phase description to a kebab-case slug:
+
+```bash
+slug=$(echo "$description" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g' | sed 's/--*/-/g' | sed 's/^-//;s/-$//')
+```
+
+Phase directory name: `{decimal-phase}-{slug}`
+Example: `06.1-fix-critical-auth-bug` (phase 6 insertion)
+</step>
+
+<step name="create_phase_directory">
+Create the phase directory structure:
+
+```bash
+phase_dir=".planning/phases/${decimal_phase}-${slug}"
+mkdir -p "$phase_dir"
+```
+
+Confirm: "Created directory: $phase_dir"
+</step>
+
+<step name="update_roadmap">
+Insert the new phase entry into the roadmap:
+
+1. Find insertion point: immediately after Phase {after_phase}'s content (before next phase heading or "---")
+2. Insert new phase heading with (INSERTED) marker:
+
+   ```
+   ### Phase {decimal_phase}: {Description} (INSERTED)
+
+   **Goal:** [Urgent work - to be planned]
+   **Depends on:** Phase {after_phase}
+   **Plans:** 0 plans
+
+   Plans:
+   - [ ] TBD (run /ms:plan-phase {decimal_phase} to break down)
+
+   **Details:**
+   [To be added during planning]
+   ```
+
+3. Write updated roadmap back to file
+
+The "(INSERTED)" marker helps identify decimal phases as urgent insertions.
+
+Preserve all other content exactly (formatting, spacing, other phases).
+</step>
+
+<step name="update_project_state">
+Update STATE.md to reflect the inserted phase:
+
+1. Read `.planning/STATE.md`
+2. Under "## Accumulated Context" → "### Roadmap Evolution" add entry:
+   ```
+   - Phase {decimal_phase} inserted after Phase {after_phase}: {description} (URGENT)
+   ```
+
+If "Roadmap Evolution" section doesn't exist, create it.
+
+Add note about insertion reason if appropriate.
+</step>
+
+<step name="completion">
+Present completion summary:
+
+```
+Phase {decimal_phase} inserted after Phase {after_phase}:
+- Description: {description}
+- Directory: .planning/phases/{decimal-phase}-{slug}/
+- Status: Not planned yet
+- Marker: (INSERTED) - indicates urgent work
+
+Roadmap updated: {roadmap-path}
+Project state updated: .planning/STATE.md
+
+---
+
+## ▶ Next Up
+
+**Phase {decimal_phase}: {description}** — urgent insertion
+
+`/ms:plan-phase {decimal_phase}`
+
+<sub>`/clear` first → fresh context window</sub>
+
+---
+
+**Also available:**
+- Review insertion impact: Check if Phase {next_integer} dependencies still make sense
+- Review roadmap
+
+---
+```
+</step>
+
+</process>
+
+<anti_patterns>
+
+- Don't use this for planned work at end of milestone (use /ms:add-phase)
+- Don't insert before Phase 1 (decimal 0.1 makes no sense)
+- Don't renumber existing phases
+- Don't modify the target phase content
+- Don't create plans yet (that's /ms:plan-phase)
+- Don't commit changes (user decides when to commit)
+  </anti_patterns>
+
+<success_criteria>
+Phase insertion is complete when:
+
+- [ ] Phase directory created: `.planning/phases/{N.M}-{slug}/`
+- [ ] Roadmap updated with new phase entry (includes "(INSERTED)" marker)
+- [ ] Phase inserted in correct position (after target phase, before next integer phase)
+- [ ] STATE.md updated with roadmap evolution note
+- [ ] Decimal number calculated correctly (based on existing decimals)
+- [ ] User informed of next steps and dependency implications
+      </success_criteria>

package/commands/ms/list-phase-assumptions.md

@@ -0,0 +1,50 @@
+---
+name: ms:list-phase-assumptions
+description: Surface Claude's assumptions about a phase approach before planning
+argument-hint: "[phase]"
+allowed-tools:
+  - Read
+  - Bash
+  - Grep
+  - Glob
+---
+
+<objective>
+Analyze a phase and present Claude's assumptions about technical approach, implementation order, scope boundaries, risk areas, and dependencies.
+
+Purpose: Help users see what Claude thinks BEFORE planning begins - enabling course correction early when assumptions are wrong.
+Output: Conversational output only (no file creation) - ends with "What do you think?" prompt
+</objective>
+
+<execution_context>
+@~/.claude/mindsystem/workflows/list-phase-assumptions.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. Follow list-phase-assumptions.md workflow:
+   - Analyze roadmap description
+   - Surface assumptions about: technical approach, implementation order, scope, risks, dependencies
+   - Present assumptions clearly
+   - Prompt "What do you think?"
+4. Gather feedback and offer next steps
+</process>
+
+<success_criteria>
+
+- Phase validated against roadmap
+- Assumptions surfaced across five areas
+- User prompted for feedback
+- User knows next steps (discuss context, plan phase, or correct assumptions)
+  </success_criteria>

package/commands/ms/map-codebase.md

@@ -0,0 +1,71 @@
+---
+name: ms:map-codebase
+description: Analyze codebase with parallel mapper agents to produce .planning/codebase/ documents
+argument-hint: "[optional: specific area to map, e.g., 'api' or 'auth']"
+allowed-tools:
+  - Read
+  - Bash
+  - Glob
+  - Grep
+  - Write
+  - Task
+---
+
+<objective>
+Analyze existing codebase using parallel ms-codebase-mapper agents to produce structured codebase documents.
+
+Each mapper agent explores a focus area and **writes documents directly** to `.planning/codebase/`. The orchestrator only receives confirmations, keeping context usage minimal.
+
+Output: .planning/codebase/ folder with 7 structured documents about the codebase state.
+</objective>
+
+<execution_context>
+@~/.claude/mindsystem/workflows/map-codebase.md
+</execution_context>
+
+<context>
+Focus area: $ARGUMENTS (optional - if provided, tells agents to focus on specific subsystem)
+
+**Load project state if exists:**
+Check for .planning/STATE.md - loads context if project already initialized
+
+**This command can run:**
+- Before /ms:new-project (brownfield codebases) - creates codebase map first
+- After /ms:new-project (greenfield codebases) - updates codebase map as code evolves
+- Anytime to refresh codebase understanding
+</context>
+
+<when_to_use>
+**Use map-codebase for:**
+- Brownfield projects before initialization (understand existing code first)
+- Refreshing codebase map after significant changes
+- Onboarding to an unfamiliar codebase
+- Before major refactoring (understand current state)
+- When STATE.md references outdated codebase info
+
+**Skip map-codebase for:**
+- Greenfield projects with no code yet (nothing to map)
+- Trivial codebases (<5 files)
+</when_to_use>
+
+<process>
+1. Check if .planning/codebase/ already exists (offer to refresh or skip)
+2. Create .planning/codebase/ directory structure
+3. Spawn 4 parallel ms-codebase-mapper agents:
+   - Agent 1: tech focus → writes STACK.md, INTEGRATIONS.md
+   - Agent 2: arch focus → writes ARCHITECTURE.md, STRUCTURE.md
+   - Agent 3: quality focus → writes CONVENTIONS.md, TESTING.md
+   - Agent 4: concerns focus → writes CONCERNS.md
+4. Wait for agents to complete, collect confirmations (NOT document contents)
+5. Verify all 7 documents exist with line counts
+6. Commit codebase map
+7. Offer next steps (typically: /ms:new-project or /ms:plan-phase)
+</process>
+
+<success_criteria>
+- [ ] .planning/codebase/ directory created
+- [ ] All 7 codebase documents written by mapper agents
+- [ ] Documents follow template structure
+- [ ] Parallel agents completed without errors
+- [ ] User knows next steps
+</success_criteria>

package/commands/ms/new-milestone.md

@@ -0,0 +1,193 @@
+---
+name: ms:new-milestone
+description: Start a new milestone cycle — update PROJECT.md and route to requirements
+argument-hint: "[milestone name, e.g., 'v1.1 Notifications']"
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+  - AskUserQuestion
+---
+
+<objective>
+Start a new milestone by updating PROJECT.md with new goals, then routing to the requirements → roadmap cycle.
+
+This is the brownfield equivalent of new-project. The project exists, PROJECT.md has history. This command gathers "what's next" and updates PROJECT.md to reflect the new milestone's goals.
+
+Output: Updated PROJECT.md, routes to research-project or define-requirements
+</objective>
+
+<execution_context>
+@~/.claude/mindsystem/references/questioning.md
+@~/.claude/mindsystem/templates/project.md
+</execution_context>
+
+<context>
+Milestone name: $ARGUMENTS (optional - will prompt if not provided)
+
+**Load project context:**
+@.planning/PROJECT.md
+@.planning/STATE.md
+@.planning/MILESTONES.md
+@.planning/config.json
+
+**Load milestone context (if exists, from /ms:discuss-milestone):**
+@.planning/MILESTONE-CONTEXT.md
+</context>
+
+<process>
+
+1. **Load context:**
+   - Read PROJECT.md (existing project, Validated requirements, decisions)
+   - Read MILESTONES.md (what shipped previously)
+   - Read STATE.md (pending todos, blockers)
+   - Check for MILESTONE-CONTEXT.md (from /ms:discuss-milestone)
+
+2. **Present what shipped (if MILESTONES.md exists):**
+
+   ```bash
+   cat .planning/MILESTONES.md 2>/dev/null
+   # Also check for assumptions from last audit
+   cat .planning/v*-MILESTONE-AUDIT.md 2>/dev/null | grep -A 100 "assumptions:" | head -50
+   ```
+
+   Format the presentation:
+
+   ```
+   ---
+
+   ## Previous Milestone
+
+   **Last milestone:** v[X.Y] [Name] (shipped [DATE])
+
+   **Key accomplishments:**
+   - [From MILESTONES.md accomplishments]
+   - [From MILESTONES.md accomplishments]
+   - [From MILESTONES.md accomplishments]
+
+   **Validated requirements:**
+   - [From PROJECT.md Validated section]
+
+   **Pending todos (if any):**
+   - [From STATE.md accumulated context]
+
+   **Untested assumptions (if any):**
+   - [From MILESTONE-AUDIT.md assumptions section]
+   - Error state displays (04-comments, 05-auth)
+   - Empty state handling (04-comments)
+   - Session timeout behavior (05-auth)
+
+   *These were skipped during UAT because required states couldn't be mocked.*
+
+   ---
+   ```
+
+   This gives users context before asking what they want to build next.
+
+3. **Gather milestone goals:**
+
+   **If MILESTONE-CONTEXT.md exists:**
+   - Use features and scope from discuss-milestone
+   - Present summary for confirmation
+
+   **If no context file:**
+   - Present what shipped in last milestone
+   - Ask: "What do you want to build next?"
+   - Use AskUserQuestion to explore features
+   - Probe for priorities, constraints, scope
+
+4. **Determine milestone version:**
+   - Parse last version from MILESTONES.md
+   - Suggest next version (v1.0 → v1.1, or v2.0 for major)
+   - Confirm with user
+
+5. **Update PROJECT.md:**
+
+   Add/update these sections:
+
+   ```markdown
+   ## Current Milestone: v[X.Y] [Name]
+
+   **Goal:** [One sentence describing milestone focus]
+
+   **Target features:**
+   - [Feature 1]
+   - [Feature 2]
+   - [Feature 3]
+   ```
+
+   Update Active requirements section with new goals.
+
+   Update "Last updated" footer.
+
+6. **Update STATE.md:**
+
+   ```markdown
+   ## Current Position
+
+   Phase: Not started (run /ms:create-roadmap)
+   Plan: —
+   Status: Defining requirements
+   Last activity: [today] — Milestone v[X.Y] started
+   ```
+
+7. **Cleanup:**
+   - Delete MILESTONE-CONTEXT.md if exists (consumed)
+
+8. **Git commit:**
+   ```bash
+   git add .planning/PROJECT.md .planning/STATE.md
+   git commit -m "docs: start milestone v[X.Y] [Name]"
+   ```
+
+9. **Calculate next phase for context:**
+
+   ```bash
+   LAST_PHASE=$(ls -d .planning/phases/[0-9]*-* 2>/dev/null | sort -V | tail -1 | grep -oE '[0-9]+' | head -1)
+   if [ -n "$LAST_PHASE" ]; then
+     NEXT_PHASE=$((10#$LAST_PHASE + 1))
+   else
+     NEXT_PHASE=1
+   fi
+   echo "Next milestone phases will start at: Phase $NEXT_PHASE"
+   ```
+
+10. **Route to next step:**
+
+   ```
+   Milestone v[X.Y] [Name] initialized.
+
+   PROJECT.md updated with new goals.
+   Phases will start at: Phase $NEXT_PHASE
+
+   ---
+
+   ## ▶ Next Up
+
+   Choose your path:
+
+   **Option A: Research first** (new domains/capabilities)
+   Research ecosystem before scoping. Discovers patterns, expected features, architecture approaches.
+
+   `/ms:research-project`
+
+   **Option B: Define requirements directly** (familiar territory)
+   Skip research, define requirements from what you know.
+
+   `/ms:define-requirements`
+
+   <sub>`/clear` first → fresh context window</sub>
+
+   ---
+   ```
+
+</process>
+
+<success_criteria>
+- PROJECT.md updated with Current Milestone section
+- Active requirements reflect new milestone goals
+- STATE.md reset for new milestone
+- MILESTONE-CONTEXT.md consumed and deleted (if existed)
+- Git commit made
+- User routed to define-requirements (or research-project)
+</success_criteria>