mindsystem-cc 3.0.0

package/agents/ms-verify-fixer.md

@@ -0,0 +1,124 @@
+---
+name: ms-verify-fixer
+description: Investigates and fixes single UAT issues. Spawned by verify-work when lightweight investigation fails.
+tools: Read, Write, Edit, Bash, Grep, Glob
+color: orange
+---
+
+<role>
+You are a Mindsystem verify-fixer. You investigate a single UAT issue that the main orchestrator couldn't resolve with lightweight investigation, find the root cause, implement a fix, and commit it.
+
+You are spawned by `/ms:verify-work` when an issue requires deeper investigation (failed 2-3 quick checks).
+
+Your job: Find root cause, implement minimal fix, commit with proper message, return result for re-testing.
+</role>
+
+<context_you_receive>
+Your prompt will include:
+
+- **Issue details**: test name, expected behavior, actual behavior, severity
+- **Phase info**: phase name, current mock state (if any)
+- **Relevant files**: suspected files from initial investigation
+- **What was checked**: results of lightweight investigation already done
+</context_you_receive>
+
+<investigation_approach>
+You have fresh 200k context. Use it to investigate thoroughly.
+
+**1. Start from what's known**
+- Read the files already identified as suspicious
+- Review what was already checked (don't repeat)
+- Look for adjacent code that might be involved
+
+**2. Form specific hypothesis**
+- Be precise: "useEffect missing dependency" not "something with state"
+- Make it falsifiable: you can prove it wrong with a test
+
+**3. Test one thing at a time**
+- Add logging if needed
+- Run the code to observe
+- Don't change multiple things at once
+
+**4. When you find it**
+- Verify with evidence (log output, test result)
+- Implement minimal fix
+- Test that fix resolves the issue
+</investigation_approach>
+
+<fix_protocol>
+**Mocks are currently stashed** - your working tree is clean.
+
+**1. Implement fix**
+- Make the smallest change that addresses root cause
+- Don't refactor surrounding code
+- Don't add "improvements" beyond the fix
+
+**2. Commit with proper message**
+```bash
+git add [specific files]
+git commit -m "fix({phase}-uat): {description}"
+```
+
+Use the `{phase}-uat` scope so patches can find UAT fixes later.
+
+**3. Document what you did**
+- Which file(s) changed
+- What the fix actually does
+- Why this addresses the root cause
+</fix_protocol>
+
+<return_formats>
+
+**When fix applied successfully:**
+
+```markdown
+## FIX COMPLETE
+
+**Root cause:** {specific cause with evidence}
+
+**Fix applied:** {what was changed and why}
+
+**Commit:** {hash}
+
+**Files changed:**
+- {file}: {change description}
+
+**Re-test instruction:** {specific step for user to verify}
+```
+
+**When investigation is inconclusive:**
+
+```markdown
+## INVESTIGATION INCONCLUSIVE
+
+**What was checked:**
+- {area}: {finding}
+- {area}: {finding}
+
+**Hypotheses eliminated:**
+- {hypothesis}: {why ruled out}
+
+**Remaining possibilities:**
+- {possibility 1}
+- {possibility 2}
+
+**Recommendation:** {suggested next steps}
+```
+
+</return_formats>
+
+<constraints>
+- Do NOT modify mock code (it's stashed)
+- Do NOT make architectural changes (return checkpoint instead)
+- Do NOT fix unrelated issues you discover (note them for later)
+- Do commit your fix before returning
+- Do use `fix({phase}-uat):` commit message format
+</constraints>
+
+<success_criteria>
+- [ ] Root cause identified with evidence
+- [ ] Minimal fix implemented
+- [ ] Fix committed with proper message format
+- [ ] Clear re-test instruction provided
+- [ ] Return uses correct format (FIX COMPLETE or INVESTIGATION INCONCLUSIVE)
+</success_criteria>

package/bin/install.js

@@ -0,0 +1,296 @@
+#!/usr/bin/env node
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const readline = require('readline');
+
+// Colors
+const cyan = '\x1b[38;2;47;167;160m'; // #2FA7A0
+const green = '\x1b[32m';
+const yellow = '\x1b[33m';
+const dim = '\x1b[2m';
+const reset = '\x1b[0m';
+
+// Get version from package.json
+const pkg = require('../package.json');
+
+const banner = `
+${cyan}   ███╗   ███╗██╗███╗   ██╗██████╗ ███████╗██╗   ██╗███████╗████████╗███████╗███╗   ███╗
+   ████╗ ████║██║████╗  ██║██╔══██╗██╔════╝╚██╗ ██╔╝██╔════╝╚══██╔══╝██╔════╝████╗ ████║
+   ██╔████╔██║██║██╔██╗ ██║██║  ██║███████╗ ╚████╔╝ ███████╗   ██║   █████╗  ██╔████╔██║
+   ██║╚██╔╝██║██║██║╚██╗██║██║  ██║╚════██║  ╚██╔╝  ╚════██║   ██║   ██╔══╝  ██║╚██╔╝██║
+   ██║ ╚═╝ ██║██║██║ ╚████║██████╔╝███████║   ██║   ███████║   ██║   ███████╗██║ ╚═╝ ██║
+   ╚═╝     ╚═╝╚═╝╚═╝  ╚═══╝╚═════╝ ╚══════╝   ╚═╝   ╚══════╝   ╚═╝   ╚══════╝╚═╝     ╚═╝${reset}
+
+  Mindsystem ${dim}v${pkg.version}${reset}
+  A meta-prompting, context engineering and spec-driven
+  development system for Claude Code by Roland Tolnay.
+  Based on GSD by TÂCHES.
+`;
+
+// Parse args
+const args = process.argv.slice(2);
+const hasGlobal = args.includes('--global') || args.includes('-g');
+const hasLocal = args.includes('--local') || args.includes('-l');
+
+// Parse --config-dir argument
+function parseConfigDirArg() {
+  const configDirIndex = args.findIndex(arg => arg === '--config-dir' || arg === '-c');
+  if (configDirIndex !== -1) {
+    const nextArg = args[configDirIndex + 1];
+    // Error if --config-dir is provided without a value or next arg is another flag
+    if (!nextArg || nextArg.startsWith('-')) {
+      console.error(`  ${yellow}--config-dir requires a path argument${reset}`);
+      process.exit(1);
+    }
+    return nextArg;
+  }
+  // Also handle --config-dir=value format
+  const configDirArg = args.find(arg => arg.startsWith('--config-dir=') || arg.startsWith('-c='));
+  if (configDirArg) {
+    return configDirArg.split('=')[1];
+  }
+  return null;
+}
+const explicitConfigDir = parseConfigDirArg();
+const hasHelp = args.includes('--help') || args.includes('-h');
+
+console.log(banner);
+
+// Show help if requested
+if (hasHelp) {
+  console.log(`  ${yellow}Usage:${reset} npx mindsystem-cc [options]
+
+  ${yellow}Options:${reset}
+    ${cyan}-g, --global${reset}              Install globally (to Claude config directory)
+    ${cyan}-l, --local${reset}               Install locally (to ./.claude in current directory)
+    ${cyan}-c, --config-dir <path>${reset}   Specify custom Claude config directory
+    ${cyan}-h, --help${reset}                Show this help message
+
+  ${yellow}Examples:${reset}
+    ${dim}# Install to default ~/.claude directory${reset}
+    npx mindsystem-cc --global
+
+    ${dim}# Install to custom config directory (for multiple Claude accounts)${reset}
+    npx mindsystem-cc --global --config-dir ~/.claude-bc
+
+    ${dim}# Using environment variable${reset}
+    CLAUDE_CONFIG_DIR=~/.claude-bc npx mindsystem-cc --global
+
+    ${dim}# Install to current project only${reset}
+    npx mindsystem-cc --local
+
+  ${yellow}Notes:${reset}
+    The --config-dir option is useful when you have multiple Claude Code
+    configurations (e.g., for different subscriptions). It takes priority
+    over the CLAUDE_CONFIG_DIR environment variable.
+`);
+  process.exit(0);
+}
+
+/**
+ * Expand ~ to home directory (shell doesn't expand in env vars passed to node)
+ */
+function expandTilde(filePath) {
+  if (filePath && filePath.startsWith('~/')) {
+    return path.join(os.homedir(), filePath.slice(2));
+  }
+  return filePath;
+}
+
+/**
+ * Recursively copy directory, replacing paths in .md files
+ */
+function copyWithPathReplacement(srcDir, destDir, pathPrefix) {
+  fs.mkdirSync(destDir, { recursive: true });
+
+  const entries = fs.readdirSync(srcDir, { withFileTypes: true });
+
+  for (const entry of entries) {
+    const srcPath = path.join(srcDir, entry.name);
+    const destPath = path.join(destDir, entry.name);
+
+    if (entry.isDirectory()) {
+      copyWithPathReplacement(srcPath, destPath, pathPrefix);
+    } else if (entry.name.endsWith('.md')) {
+      // Replace ~/.claude/ with the appropriate prefix in markdown files
+      let content = fs.readFileSync(srcPath, 'utf8');
+      content = content.replace(/~\/\.claude\//g, pathPrefix);
+      fs.writeFileSync(destPath, content);
+    } else {
+      fs.copyFileSync(srcPath, destPath);
+    }
+  }
+}
+
+/**
+ * Recursively copy directory without path replacement
+ */
+function copyDir(srcDir, destDir) {
+  fs.mkdirSync(destDir, { recursive: true });
+
+  const entries = fs.readdirSync(srcDir, { withFileTypes: true });
+
+  for (const entry of entries) {
+    const srcPath = path.join(srcDir, entry.name);
+    const destPath = path.join(destDir, entry.name);
+
+    if (entry.isDirectory()) {
+      copyDir(srcPath, destPath);
+    } else {
+      fs.copyFileSync(srcPath, destPath);
+    }
+  }
+}
+
+/**
+ * Install to the specified directory
+ */
+function install(isGlobal) {
+  const src = path.join(__dirname, '..');
+  // Priority: explicit --config-dir arg > CLAUDE_CONFIG_DIR env var > default ~/.claude
+  const configDir = expandTilde(explicitConfigDir) || expandTilde(process.env.CLAUDE_CONFIG_DIR);
+  const defaultGlobalDir = configDir || path.join(os.homedir(), '.claude');
+  const claudeDir = isGlobal
+    ? defaultGlobalDir
+    : path.join(process.cwd(), '.claude');
+
+  const locationLabel = isGlobal
+    ? claudeDir.replace(os.homedir(), '~')
+    : claudeDir.replace(process.cwd(), '.');
+
+  // Path prefix for file references
+  // Use actual path when CLAUDE_CONFIG_DIR is set, otherwise use ~ shorthand
+  const pathPrefix = isGlobal
+    ? (configDir ? `${claudeDir}/` : '~/.claude/')
+    : './.claude/';
+
+  console.log(`  Installing to ${cyan}${locationLabel}${reset}\n`);
+
+  // Create commands directory
+  const commandsDir = path.join(claudeDir, 'commands');
+  fs.mkdirSync(commandsDir, { recursive: true });
+
+  // Copy commands/ms with path replacement
+  const msSrc = path.join(src, 'commands', 'ms');
+  const msDest = path.join(commandsDir, 'ms');
+  copyWithPathReplacement(msSrc, msDest, pathPrefix);
+  console.log(`  ${green}✓${reset} Installed commands/ms`);
+
+  // Copy mindsystem skill with path replacement
+  const skillSrc = path.join(src, 'mindsystem');
+  const skillDest = path.join(claudeDir, 'mindsystem');
+  copyWithPathReplacement(skillSrc, skillDest, pathPrefix);
+  console.log(`  ${green}✓${reset} Installed mindsystem`);
+
+  // Copy agents to ~/.claude/agents (subagents must be at root level)
+  const agentsSrc = path.join(src, 'agents');
+  if (fs.existsSync(agentsSrc)) {
+    const agentsDest = path.join(claudeDir, 'agents');
+    copyWithPathReplacement(agentsSrc, agentsDest, pathPrefix);
+    console.log(`  ${green}✓${reset} Installed agents`);
+  }
+
+  // Copy scripts to ~/.claude/mindsystem/scripts/
+  const scriptsSrc = path.join(src, 'scripts');
+  if (fs.existsSync(scriptsSrc)) {
+    const scriptsDest = path.join(claudeDir, 'mindsystem', 'scripts');
+    fs.mkdirSync(scriptsDest, { recursive: true });
+    const scriptEntries = fs.readdirSync(scriptsSrc, { withFileTypes: true });
+    for (const entry of scriptEntries) {
+      const srcPath = path.join(scriptsSrc, entry.name);
+      const destPath = path.join(scriptsDest, entry.name);
+      if (entry.isDirectory()) {
+        // Recursively copy directories (like ms-lookup/)
+        copyDir(srcPath, destPath);
+      } else {
+        fs.copyFileSync(srcPath, destPath);
+        // Make shell scripts executable
+        if (entry.name.endsWith('.sh')) {
+          fs.chmodSync(destPath, '755');
+        }
+      }
+    }
+    console.log(`  ${green}✓${reset} Installed scripts`);
+
+    // Check Python availability for ms-lookup
+    const msLookupPath = path.join(scriptsDest, 'ms-lookup');
+    if (fs.existsSync(msLookupPath)) {
+      try {
+        const { execSync } = require('child_process');
+        const pyVersion = execSync('python3 --version 2>&1', { encoding: 'utf8' });
+        const versionMatch = pyVersion.match(/(\d+)\.(\d+)/);
+        if (versionMatch) {
+          const [, major, minor] = versionMatch;
+          if (parseInt(major) < 3 || (parseInt(major) === 3 && parseInt(minor) < 9)) {
+            console.log(`  ${yellow}⚠${reset} Python 3.9+ required for ms-lookup (found ${major}.${minor})`);
+          } else {
+            console.log(`  ${green}✓${reset} Installed ms-lookup CLI (Python ${major}.${minor})`);
+          }
+        }
+      } catch (e) {
+        console.log(`  ${yellow}⚠${reset} Python not found - ms-lookup CLI requires Python 3.9+`);
+      }
+    }
+  }
+
+  // Copy CHANGELOG.md
+  const changelogSrc = path.join(src, 'CHANGELOG.md');
+  const changelogDest = path.join(claudeDir, 'mindsystem', 'CHANGELOG.md');
+  if (fs.existsSync(changelogSrc)) {
+    fs.copyFileSync(changelogSrc, changelogDest);
+    console.log(`  ${green}✓${reset} Installed CHANGELOG.md`);
+  }
+
+  // Write VERSION file for whats-new command
+  const versionDest = path.join(claudeDir, 'mindsystem', 'VERSION');
+  fs.writeFileSync(versionDest, pkg.version);
+  console.log(`  ${green}✓${reset} Wrote VERSION (${pkg.version})`);
+
+  console.log(`
+  ${green}Done!${reset} Launch Claude Code and run ${cyan}/ms:help${reset}.
+`);
+}
+
+/**
+ * Prompt for install location
+ */
+function promptLocation() {
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout
+  });
+
+  const configDir = expandTilde(explicitConfigDir) || expandTilde(process.env.CLAUDE_CONFIG_DIR);
+  const globalPath = configDir || path.join(os.homedir(), '.claude');
+  const globalLabel = globalPath.replace(os.homedir(), '~');
+
+  console.log(`  ${yellow}Where would you like to install?${reset}
+
+  ${cyan}1${reset}) Global ${dim}(${globalLabel})${reset} - available in all projects
+  ${cyan}2${reset}) Local  ${dim}(./.claude)${reset} - this project only
+`);
+
+  rl.question(`  Choice ${dim}[1]${reset}: `, (answer) => {
+    rl.close();
+    const choice = answer.trim() || '1';
+    const isGlobal = choice !== '2';
+    install(isGlobal);
+  });
+}
+
+// Main
+if (hasGlobal && hasLocal) {
+  console.error(`  ${yellow}Cannot specify both --global and --local${reset}`);
+  process.exit(1);
+} else if (explicitConfigDir && hasLocal) {
+  console.error(`  ${yellow}Cannot use --config-dir with --local${reset}`);
+  process.exit(1);
+} else if (hasGlobal) {
+  install(true);
+} else if (hasLocal) {
+  install(false);
+} else {
+  promptLocation();
+}

package/commands/ms/add-phase.md

@@ -0,0 +1,207 @@
+---
+name: ms:add-phase
+description: Add phase to end of current milestone in roadmap
+argument-hint: <description>
+allowed-tools:
+  - Read
+  - Write
+  - Bash
+---
+
+<objective>
+Add a new integer phase to the end of the current milestone in the roadmap.
+
+This command appends sequential phases to the current milestone's phase list, automatically calculating the next phase number based on existing phases.
+
+Purpose: Add planned work discovered during execution that belongs at the end of current milestone.
+</objective>
+
+<execution_context>
+@.planning/ROADMAP.md
+@.planning/STATE.md
+</execution_context>
+
+<process>
+
+<step name="parse_arguments">
+Parse the command arguments:
+- All arguments become the phase description
+- Example: `/ms:add-phase Add authentication` → description = "Add authentication"
+- Example: `/ms:add-phase Fix critical performance issues` → description = "Fix critical performance issues"
+
+If no arguments provided:
+
+```
+ERROR: Phase description required
+Usage: /ms:add-phase <description>
+Example: /ms:add-phase Add authentication system
+```
+
+Exit.
+</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="find_current_milestone">
+Parse the roadmap to find the current milestone section:
+
+1. Locate the "## Current Milestone:" heading
+2. Extract milestone name and version
+3. Identify all phases under this milestone (before next "---" separator or next milestone heading)
+4. Parse existing phase numbers (including decimals if present)
+
+Example structure:
+
+```
+## Current Milestone: v1.0 Foundation
+
+### Phase 4: Focused Command System
+### Phase 5: Path Routing & Validation
+### Phase 6: Documentation & Distribution
+```
+
+</step>
+
+<step name="calculate_next_phase">
+Find the highest integer phase number in the current milestone:
+
+1. Extract all phase numbers from phase headings (### Phase N:)
+2. Filter to integer phases only (ignore decimals like 4.1, 4.2)
+3. Find the maximum integer value
+4. Add 1 to get the next phase number
+
+Example: If phases are 4, 5, 5.1, 6 → next is 7
+
+Format as two-digit: `printf "%02d" $next_phase`
+</step>
+
+<step name="generate_slug">
+Convert the phase description to a kebab-case slug:
+
+```bash
+# Example transformation:
+# "Add authentication" → "add-authentication"
+# "Fix critical performance issues" → "fix-critical-performance-issues"
+
+slug=$(echo "$description" | tr '[:upper:]' '[:lower:]' | sed 's/[^a-z0-9]/-/g' | sed 's/--*/-/g' | sed 's/^-//;s/-$//')
+```
+
+Phase directory name: `{two-digit-phase}-{slug}`
+Example: `07-add-authentication`
+</step>
+
+<step name="create_phase_directory">
+Create the phase directory structure:
+
+```bash
+phase_dir=".planning/phases/${phase_num}-${slug}"
+mkdir -p "$phase_dir"
+```
+
+Confirm: "Created directory: $phase_dir"
+</step>
+
+<step name="update_roadmap">
+Add the new phase entry to the roadmap:
+
+1. Find the insertion point (after last phase in current milestone, before "---" separator)
+2. Insert new phase heading:
+
+   ```
+   ### Phase {N}: {Description}
+
+   **Goal:** [To be planned]
+   **Depends on:** Phase {N-1}
+   **Plans:** 0 plans
+
+   Plans:
+   - [ ] TBD (run /ms:plan-phase {N} to break down)
+
+   **Details:**
+   [To be added during planning]
+   ```
+
+3. Write updated roadmap back to file
+
+Preserve all other content exactly (formatting, spacing, other phases).
+</step>
+
+<step name="update_project_state">
+Update STATE.md to reflect the new phase:
+
+1. Read `.planning/STATE.md`
+2. Under "## Current Position" → "**Next Phase:**" add reference to new phase
+3. Under "## Accumulated Context" → "### Roadmap Evolution" add entry:
+   ```
+   - Phase {N} added: {description}
+   ```
+
+If "Roadmap Evolution" section doesn't exist, create it.
+</step>
+
+<step name="completion">
+Present completion summary:
+
+```
+Phase {N} added to current milestone:
+- Description: {description}
+- Directory: .planning/phases/{phase-num}-{slug}/
+- Status: Not planned yet
+
+Roadmap updated: {roadmap-path}
+Project state updated: .planning/STATE.md
+
+---
+
+## ▶ Next Up
+
+**Phase {N}: {description}**
+
+`/ms:plan-phase {N}`
+
+<sub>`/clear` first → fresh context window</sub>
+
+---
+
+**Also available:**
+- `/ms:add-phase <description>` — add another phase
+- Review roadmap
+
+---
+```
+</step>
+
+</process>
+
+<anti_patterns>
+
+- Don't modify phases outside current milestone
+- Don't renumber existing phases
+- Don't use decimal numbering (that's /ms:insert-phase)
+- Don't create plans yet (that's /ms:plan-phase)
+- Don't commit changes (user decides when to commit)
+  </anti_patterns>
+
+<success_criteria>
+Phase addition is complete when:
+
+- [ ] Phase directory created: `.planning/phases/{NN}-{slug}/`
+- [ ] Roadmap updated with new phase entry
+- [ ] STATE.md updated with roadmap evolution note
+- [ ] New phase appears at end of current milestone
+- [ ] Next phase number calculated correctly (ignoring decimals)
+- [ ] User informed of next steps
+      </success_criteria>