supermind-claude 2.0.2 → 2.1.1

package/cli/commands/doctor.js

@@ -4,7 +4,7 @@ const fs = require('fs');
 const path = require('path');
 const { PATHS } = require('../lib/platform');
 const logger = require('../lib/logger');
-const { readSettings, SUPERMIND_PLUGINS } = require('../lib/settings');
+const { SUPERMIND_PLUGINS } = require('../lib/settings');
 const { getHookFiles } = require('../lib/hooks');
 const { getSkillDirs } = require('../lib/skills');
 const { version } = require('../../package.json');
@@ -46,27 +46,43 @@ module.exports = function doctor(flags) {
     try {
       settings = JSON.parse(fs.readFileSync(PATHS.settings, 'utf-8'));
       run('settings.json is valid JSON', true);
-    } catch {
-      run('settings.json is valid JSON', false, 'parse error');
+    } catch (err) {
+      run('settings.json is valid JSON', false, err.message);
     }
   }
 
   // Hooks present
-  const expectedHooks = getHookFiles();
+  let expectedHooks;
+  try {
+    expectedHooks = getHookFiles();
+  } catch (err) {
+    run('Hook enumeration', false, err.message);
+    expectedHooks = [];
+  }
   for (const file of expectedHooks) {
     run(`Hook: ${file}`, fs.existsSync(path.join(PATHS.hooksDir, file)));
   }
 
   // Skills present
-  const expectedSkills = getSkillDirs();
+  let expectedSkills;
+  try {
+    expectedSkills = getSkillDirs();
+  } catch (err) {
+    run('Skill enumeration', false, err.message);
+    expectedSkills = [];
+  }
   for (const dir of expectedSkills) {
     const skillPath = path.join(PATHS.skillsDir, dir);
     run(`Skill: ${dir}`, fs.existsSync(skillPath) && fs.existsSync(path.join(skillPath, 'SKILL.md')));
   }
 
   // Plugins
-  for (const id of SUPERMIND_PLUGINS) {
-    run(`Plugin: ${id.split('@')[0]}`, settings.enabledPlugins?.[id] === true);
+  if (SUPERMIND_PLUGINS.length === 0) {
+    logger.warn('Plugin list unavailable — plugin checks skipped');
+  } else {
+    for (const id of SUPERMIND_PLUGINS) {
+      run(`Plugin: ${id.split('@')[0]}`, settings.enabledPlugins?.[id] === true);
+    }
   }
 
   // Template
@@ -74,12 +90,14 @@ module.exports = function doctor(flags) {
 
   // Sessions directory
   run('Sessions directory writable', (() => {
+    const testFile = path.join(PATHS.sessionsDir, '.doctor-test');
     try {
-      const testFile = path.join(PATHS.sessionsDir, '.doctor-test');
       fs.writeFileSync(testFile, 'test');
-      fs.unlinkSync(testFile);
-      return true;
-    } catch { return false; }
+    } catch {
+      return false;
+    }
+    try { fs.unlinkSync(testFile); } catch { /* cleanup non-critical */ }
+    return true;
   })());
 
   // Docker (warn only, not required)
@@ -93,7 +111,13 @@ module.exports = function doctor(flags) {
 
   // Version
   let installedVersion = 'not found';
-  try { installedVersion = fs.readFileSync(PATHS.versionFile, 'utf-8').trim(); } catch {}
+  try {
+    installedVersion = fs.readFileSync(PATHS.versionFile, 'utf-8').trim();
+  } catch (err) {
+    if (err.code !== 'ENOENT') {
+      installedVersion = `error: ${err.message}`;
+    }
+  }
   run('Version marker', installedVersion === version, installedVersion !== version ? `installed: ${installedVersion}, package: ${version}` : undefined);
 
   console.log(`\n  ${passed} passed, ${failed} failed\n`);

package/cli/commands/install.js

@@ -58,7 +58,8 @@ module.exports = async function install(flags) {
 
   // Step 5: Plugins (data already merged in Step 2 via getPluginDefaults — this step is log-only)
   logger.step(5, TOTAL, 'Enabling plugins...');
-  logger.success('superpowers, frontend-design, claude-md-management, ui-ux-pro-max');
+  const pluginNames = Object.keys(pluginDefaults.enabledPlugins).map(k => k.split('@')[0]);
+  logger.success(pluginNames.join(', '));
 
   // Step 6: MCP servers
   logger.step(6, TOTAL, 'MCP server setup...');
@@ -71,7 +72,7 @@ module.exports = async function install(flags) {
 
   // Step 7: Templates
   logger.step(7, TOTAL, 'Installing templates...');
-  installTemplates();
+  installTemplates(mcpConfig.mode);
 
   // Write version marker
   fs.writeFileSync(PATHS.versionFile, version);

package/cli/commands/uninstall.js

@@ -4,7 +4,7 @@ const fs = require('fs');
 const readline = require('readline');
 const { PATHS } = require('../lib/platform');
 const logger = require('../lib/logger');
-const { readSettings, writeSettings, removeSupermindEntries } = require('../lib/settings');
+const { readSettings, writeSettings, removeSupermindEntries, backupSettings } = require('../lib/settings');
 const { removeHooks } = require('../lib/hooks');
 const { removeSkills } = require('../lib/skills');
 const { removeTemplates } = require('../lib/templates');
@@ -41,6 +41,7 @@ module.exports = async function uninstall(flags) {
 
   // Clean settings
   console.log('  Cleaning settings...');
+  backupSettings();
   const settings = readSettings();
   const cleaned = removeSupermindEntries(settings);
   writeSettings(cleaned);

package/cli/commands/update.js

@@ -3,10 +3,11 @@
 const fs = require('fs');
 const { PATHS } = require('../lib/platform');
 const logger = require('../lib/logger');
-const { readSettings, writeSettings, mergeSettings } = require('../lib/settings');
+const { readSettings, writeSettings, mergeSettings, backupSettings } = require('../lib/settings');
 const { installHooks, getHookSettings } = require('../lib/hooks');
 const { installSkills, removeLegacySkills } = require('../lib/skills');
 const { installTemplates } = require('../lib/templates');
+const { detectMcpMode } = require('../lib/mcp');
 const { version } = require('../../package.json');
 
 module.exports = function update(flags) {
@@ -30,6 +31,7 @@ module.exports = function update(flags) {
 
   // Step 2: Hook settings (re-merge to pick up any new hooks)
   logger.step(2, TOTAL, 'Updating settings...');
+  backupSettings();
   const existing = readSettings();
   const hookSettings = getHookSettings();
   const merged = mergeSettings(existing, hookSettings);
@@ -43,7 +45,7 @@ module.exports = function update(flags) {
 
   // Step 4: Templates
   logger.step(4, TOTAL, 'Updating templates...');
-  installTemplates();
+  installTemplates(detectMcpMode());
 
   // Write version marker
   fs.writeFileSync(PATHS.versionFile, version);

package/cli/lib/mcp.js

@@ -91,22 +91,42 @@ async function setupMcp(flags) {
   }
   if (!mode || mode === 'skip') {
     logger.info('Skipping MCP setup');
-    return {};
+    return { mode: 'skip' };
   }
 
   if (mode === 'docker') {
     await setupDocker();
-    return {}; // Docker mode uses AIRIS, not settings.json mcpServers
+    return { mode: 'docker' }; // Docker uses AIRIS gateway; mode drives template MCP section
   }
 
   if (mode === 'direct') {
     const apiKeys = await promptApiKeys(flags);
     const servers = setupDirect(apiKeys);
     logger.success(`Configured ${Object.keys(servers).length} MCP servers`);
-    return { mcpServers: servers };
+    return { mode: 'direct', mcpServers: servers };
   }
 
-  return {};
+  return { mode: 'skip' };
 }
 
-module.exports = { setupMcp };
+// Infer MCP mode from installed artifacts. Used by update to re-render the template MCP section.
+function detectMcpMode() {
+  if (fs.existsSync(path.join(PATHS.airisDir, 'docker-compose.yml'))) {
+    return 'docker';
+  }
+  // Any known direct-mode server in settings.json means direct install was used
+  try {
+    const settings = JSON.parse(fs.readFileSync(PATHS.settings, 'utf-8'));
+    const servers = settings.mcpServers || {};
+    if (servers.context7 || servers.playwright || servers.serena || servers.tavily) {
+      return 'direct';
+    }
+  } catch (err) {
+    if (err.code !== 'ENOENT') {
+      logger.warn(`Could not read settings.json to detect MCP mode: ${err.message}`);
+    }
+  }
+  return 'skip';
+}
+
+module.exports = { setupMcp, detectMcpMode };

package/cli/lib/plugins.js

@@ -7,11 +7,15 @@ function getPluginDefaults() {
       'claude-md-management@claude-plugins-official': true,
       'frontend-design@claude-plugins-official': true,
       'ui-ux-pro-max@ui-ux-pro-max-skill': true,
+      'pr-review-toolkit@claude-plugins-official': true,
+      'security-guidance@claude-plugins-official': true,
+      'elements-of-style@superpowers-marketplace': true,
     },
     extraKnownMarketplaces: {
       'ui-ux-pro-max-skill': {
         source: { source: 'github', repo: 'nextlevelbuilder/ui-ux-pro-max-skill' },
       },
+      // superpowers-marketplace is a built-in Claude Code marketplace — no source config needed
     },
   };
 }

package/cli/lib/settings.js

@@ -10,23 +10,42 @@ const SUPERMIND_HOOKS = [
   'cost-tracker.js', 'statusline-command.js',
 ];
 
-const SUPERMIND_PLUGINS = [
-  'superpowers@claude-plugins-official',
-  'claude-md-management@claude-plugins-official',
-  'frontend-design@claude-plugins-official',
-  'ui-ux-pro-max@ui-ux-pro-max-skill',
-];
+// Derived from plugins.js — single source of truth for plugin and marketplace IDs.
+// Wrapped in try-catch so a plugins.js error doesn't crash doctor/uninstall.
+function loadPluginIds() {
+  try {
+    const { getPluginDefaults } = require('./plugins');
+    const defaults = getPluginDefaults();
+    return {
+      plugins: Object.keys(defaults.enabledPlugins),
+      marketplaces: Object.keys(defaults.extraKnownMarketplaces),
+    };
+  } catch (err) {
+    logger.warn(`Could not load plugins.js — plugin checks/cleanup will be skipped (${err.message})`);
+    return { plugins: [], marketplaces: [] };
+  }
+}
+
+const { plugins: SUPERMIND_PLUGINS, marketplaces: SUPERMIND_MARKETPLACES } = loadPluginIds();
+// SUPERMIND_MARKETPLACES is used only within this module (for uninstall cleanup) — intentionally not exported
 
 function readSettings() {
   try {
     return JSON.parse(fs.readFileSync(PATHS.settings, 'utf-8'));
-  } catch {
+  } catch (err) {
+    if (err.code === 'ENOENT') return {};
+    logger.warn(`Failed to read settings.json: ${err.message}`);
     return {};
   }
 }
 
 function writeSettings(settings) {
-  fs.writeFileSync(PATHS.settings, JSON.stringify(settings, null, 2) + '\n');
+  try {
+    fs.writeFileSync(PATHS.settings, JSON.stringify(settings, null, 2) + '\n');
+  } catch (err) {
+    logger.error(`Could not write settings.json: ${err.message}`);
+    throw err;
+  }
 }
 
 function backupSettings() {
@@ -117,16 +136,21 @@ function removeSupermindEntries(settings) {
   // Remove statusLine
   delete result.statusLine;
 
-  // Remove Supermind plugins
-  if (result.enabledPlugins) {
-    for (const id of SUPERMIND_PLUGINS) {
-      delete result.enabledPlugins[id];
+  // Remove Supermind plugins and marketplace entries
+  if (SUPERMIND_PLUGINS.length === 0) {
+    logger.warn('Plugin/marketplace list unavailable — these entries were NOT removed from settings. ' +
+      'You may need to manually edit ~/.claude/settings.json');
+  } else {
+    if (result.enabledPlugins) {
+      for (const id of SUPERMIND_PLUGINS) {
+        delete result.enabledPlugins[id];
+      }
+    }
+    if (result.extraKnownMarketplaces) {
+      for (const id of SUPERMIND_MARKETPLACES) {
+        delete result.extraKnownMarketplaces[id];
+      }
     }
-  }
-
-  // Remove Supermind marketplace entries
-  if (result.extraKnownMarketplaces) {
-    delete result.extraKnownMarketplaces['ui-ux-pro-max-skill'];
   }
 
   // Remove Supermind hooks from each event

package/cli/lib/templates.js

@@ -5,11 +5,58 @@ const path = require('path');
 const { PATHS, ensureDir, getPackageRoot } = require('./platform');
 const logger = require('./logger');
 
-function installTemplates() {
+const MCP_SECTIONS = {
+  docker: `## MCP Servers
+Use these naturally when relevant — don't wait to be asked.
+
+- **Magic MCP** — \`component_builder\`, \`component_inspiration\`, \`component_refiner\`, \`logo_search\` — use when building/refining UI components
+- **Airis Gateway** (Docker, localhost:9400) — cold-start sub-servers:
+  - **context7** — Library docs lookup
+  - **playwright** — Browser automation/testing
+  - **serena** — Symbolic code navigation (run \`activate_project\` on first use)
+  - **tavily** — Web search/research
+  - **chrome-devtools** — Chrome debugging
+  - **shadcn** — shadcn/ui component search
+`,
+
+  direct: `## MCP Servers
+Use these naturally when relevant — don't wait to be asked.
+
+- **Magic MCP** — \`component_builder\`, \`component_inspiration\`, \`component_refiner\`, \`logo_search\` — use when building/refining UI components
+- **context7** — Library docs lookup (npx)
+- **playwright** — Browser automation/testing (npx)
+- **serena** — Symbolic code navigation; run \`activate_project\` on first use (uvx)
+- **tavily** — Web search/research (npx, requires TAVILY_API_KEY)
+- **chrome-devtools** — Chrome debugging (npx)
+- **shadcn** — shadcn/ui component search (npx)
+`,
+
+  skip: `## MCP Servers
+Use these naturally when relevant — don't wait to be asked.
+
+- **Magic MCP** — \`component_builder\`, \`component_inspiration\`, \`component_refiner\`, \`logo_search\` — use when building/refining UI components
+<!-- Add your MCP servers here. Run \`npx supermind-claude\` to set up context7, playwright, serena, tavily, and more. -->
+`,
+};
+
+// Matches MCP section up to next heading or end of file (with or without trailing newline)
+const MCP_SECTION_PATTERN = /## MCP Servers\nUse these naturally when relevant.*?(?=\n## |\n?$)/s;
+
+function installTemplates(mcpMode) {
   ensureDir(PATHS.templatesDir);
   const src = path.join(getPackageRoot(), 'templates', 'CLAUDE.md');
   const dest = path.join(PATHS.templatesDir, 'CLAUDE.md');
   fs.copyFileSync(src, dest);
+
+  if (mcpMode && MCP_SECTIONS[mcpMode]) {
+    const content = fs.readFileSync(dest, 'utf-8');
+    const updated = content.replace(MCP_SECTION_PATTERN, MCP_SECTIONS[mcpMode]);
+    if (updated === content && mcpMode !== 'docker') { // docker is the template default, so no-op is expected
+      logger.warn('MCP section pattern did not match template — using default MCP content');
+    }
+    fs.writeFileSync(dest, updated);
+  }
+
   logger.success('CLAUDE.md template');
 }
 

package/hooks/bash-permissions.js

@@ -17,13 +17,24 @@ function loadApprovedCommands() {
   try {
     const data = JSON.parse(fs.readFileSync(APPROVED_FILE, 'utf-8'));
     return Array.isArray(data) ? data : [];
-  } catch {
+  } catch (err) {
+    if (err.code !== 'ENOENT') {
+      process.stderr.write(`[bash-permissions] Could not load approved commands: ${err.message}\n`);
+    }
     return [];
   }
 }
 
+let _approvedCache;
+function getApprovedCommands() {
+  if (_approvedCache === undefined) {
+    _approvedCache = loadApprovedCommands();
+  }
+  return _approvedCache;
+}
+
 function isUserApproved(cmd) {
-  const approved = loadApprovedCommands();
+  const approved = getApprovedCommands();
   const trimmed = cmd.trim();
   for (const pattern of approved) {
     // Exact match
@@ -34,7 +45,9 @@ function isUserApproved(cmd) {
     if (pattern.startsWith('/') && pattern.endsWith('/')) {
       try {
         if (new RegExp(pattern.slice(1, -1)).test(trimmed)) return true;
-      } catch { /* invalid regex, skip */ }
+      } catch (e) {
+        process.stderr.write(`[bash-permissions] Invalid regex in approved commands: ${pattern} (${e.message})\n`);
+      }
     }
   }
   return false;
@@ -51,29 +64,32 @@ const SAFE_READ_COMMANDS = [
   "echo", "printf", "pwd", "true", "false", "set", "export",
   "cd", "pushd", "popd", "source", ".",
   // Text processing (read-only)
-  "grep", "rg", "awk", "sort", "uniq", "cut", "tr", "tee",
+  "grep", "rg", "awk", "sort", "uniq", "cut", "tr",
   "diff", "comm", "paste", "column", "fmt", "fold", "rev",
-  "jq", "yq", "xargs",
+  "jq", "yq",
   // System info
   "uname", "whoami", "hostname", "date", "env", "printenv",
   "nproc", "free", "uptime", "id",
+  // Encoding utilities
+  "base64",
+  // Claude CLI management (config, MCP, plugin operations)
+  "claude config", "claude mcp", "claude plugin",
+  "claude --version", "claude -v",
   // Node/npm/npx (two-word matches)
   "node -e", "node -p", "npm ls", "npm list", "npm view", "npm info",
   "npx which", "npx tsc", "npx eslint", "npx prettier", "npx vitest",
   "npx jest", "npx tsx", "npx ts-node",
 ];
 
-// Prefix-matched safe commands (not just first word)
+// Prefix-matched safe syntax (bash conditionals)
 const SAFE_PREFIXES = [
-  "sed -n",        // read-only sed
-  "sed -e",        // expression sed (read-only when no -i)
   "[[ ",           // bash conditional
   "[ ",            // test
 ];
 
 // Safe write commands (mkdir, touch, etc.) — still checked against DANGEROUS_PATTERNS
 const SAFE_WRITE_COMMANDS = [
-  "mkdir", "touch", "cp", "mv",
+  "mkdir", "touch", "cp", "mv", "tee", "xargs",
 ];
 
 // ─── Git classification lists ────────────────────────────────────────────────
@@ -136,6 +152,7 @@ const GH_DANGEROUS_PATTERNS = [
   /^gh\s+release\s+(create|delete|edit)/,
   /^gh\s+api\s+-X\s+(DELETE|PUT|PATCH|POST)/,
   /^gh\s+api\s+--method\s+(DELETE|PUT|PATCH|POST)/,
+  /^gh\s+api\s+(\S+\s+)*(-f[\s=]|-f\S|--field[\s=]|--raw-field[\s=]|-F[\s=]|-F\S|--typed-field[\s=]|--input[\s=])/,
 ];
 
 // ─── Git global flag stripping ───────────────────────────────────────────────
@@ -179,7 +196,7 @@ function classifyGitCommand(cmd, { inWorktree = false } = {}) {
   }
 
   // Bare "git stash" (no subcommand) is safe — equivalent to stash push
-  if (gitCmd === "stash" || /^stash\s*$/.test(gitCmd)) return "allow";
+  if (/^stash\s*$/.test(gitCmd)) return "allow";
 
   // Dangerous patterns (--force, --hard, rm, etc.)
   for (const p of DANGEROUS_PATTERNS) {
@@ -210,6 +227,7 @@ function classifyGitCommand(cmd, { inWorktree = false } = {}) {
 
 function isSedSafe(cmd) {
   // sed is safe only when it does NOT have -i (in-place edit)
+  // Note: conservative match — may flag -i in filenames/patterns, which errs on the side of asking
   return /^sed\s/.test(cmd) && !/-i/.test(cmd);
 }
 
@@ -233,7 +251,7 @@ function classifySegment(raw, { inWorktree = false } = {}) {
   // sed special handling (safe only without -i)
   if (withoutEnv.startsWith("sed ")) return isSedSafe(withoutEnv) ? "allow" : "ask";
 
-  // Safe prefixes (sed -n, [[ , etc.)
+  // Safe prefixes ([[ , [ conditionals)
   for (const p of SAFE_PREFIXES) {
     if (withoutEnv.startsWith(p)) return "allow";
   }
@@ -276,10 +294,6 @@ function detectWorktreeContext(segments) {
     if (/git\s+worktree\s+remove\s+.*\.worktrees?[/\\]/.test(trimmed)) {
       return true;
     }
-    // git worktree remove with a relative .worktrees path
-    if (/git\s+worktree\s+remove\s+\.worktrees?[/\\]/.test(trimmed)) {
-      return true;
-    }
   }
   return false;
 }
@@ -416,6 +430,9 @@ function main() {
       console.log(JSON.stringify(output));
     } catch (err) {
       // On parse error, don't block — let the normal permission system handle it
+      if (!(err instanceof SyntaxError)) {
+        process.stderr.write(`[bash-permissions] Unexpected error: ${err.stack || err.message}\n`);
+      }
       console.log(JSON.stringify({
         hookSpecificOutput: {
           hookEventName: "PreToolUse",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "supermind-claude",
-  "version": "2.0.2",
+  "version": "2.1.1",
   "description": "Complete, opinionated Claude Code setup — hooks, skills, status line, MCP servers, and living documentation",
   "bin": {
     "supermind-claude": "cli/index.js",

package/skills/supermind-init/SKILL.md

@@ -31,9 +31,9 @@ Section-level merging preserves your project-specific customizations while keepi
 
 ### Steps
 
-1. Read the template from `~/.claude/templates/CLAUDE.md`. If missing, tell the user to run `npx supermind-claude` first and stop.
+1. Read the template from `~/.claude/templates/CLAUDE.md`. If missing, tell the user to run `npx supermind-claude` first and stop. **Important:** The template is only a *source* to read from — all writes go to `./CLAUDE.md` in the project root. Never modify the template file at `~/.claude/templates/CLAUDE.md`.
 
-2. Check if `CLAUDE.md` exists in the project root.
+2. Check if `CLAUDE.md` exists in the project root (`./CLAUDE.md`).
 
 3. **No existing CLAUDE.md** — copy the template as-is, then proceed to step 5.
 
@@ -127,7 +127,13 @@ ARCHITECTURE.md uses tables-over-prose because it saves tokens — the AI reads
 
     Leave unfilled sections with `<!-- No [X] detected -->`.
 
-13. **Commit** generated or migrated docs:
+13. **Verify generated documentation**:
+    - Re-read the generated ARCHITECTURE.md (and DESIGN.md if created)
+    - Spot-check at least 5 claims (or 10% of all claims, whichever is larger) against actual source code: verify constant names, function signatures, dependency lists, and behavioral descriptions match the source
+    - If discrepancies are found, fix each one and tell the user what was wrong and what was corrected
+    - If more than 30% of checked claims are wrong, warn the user that generation quality was low and suggest reviewing the full document manually
+
+14. **Commit** generated or migrated docs:
     - New project: `git commit -m "Initialize project (CLAUDE.md, ARCHITECTURE.md[, DESIGN.md])"`
     - Migrated: `git commit -m "Migrate living documentation to AI-optimized format"`
 
@@ -139,29 +145,41 @@ Different projects benefit from different tools. A database-heavy project might
 
 ### Steps
 
-14. Ask the user: "Would you like me to check your Supermind setup and research additional tools for this project?"
+15. Ask the user: "Would you like me to check your Supermind setup and research additional tools for this project?"
 
-15. **If yes**:
+16. **If yes**:
 
     a. **Verify session hooks are firing**:
        - Check `~/.claude/sessions/` for recent session files
        - If no recent files found, warn that session persistence may not be configured
 
-    b. **Check Serena configuration**:
-       - Look for `.serena/` directory in the project root
-       - If missing, suggest setting up Serena for semantic code navigation
-
-    c. **Research relevant tools**:
-       - Spawn a subagent to research skills and MCPs relevant to the detected tech stack
-       - Consider the project's language, framework, database, deployment target, and testing approach
-       - Look at available MCP servers and Superpowers skills that match
-
-    d. **Present findings**:
-       - Show suggestions as a list with brief explanations of why each tool is relevant
+    b. **Set up Serena** (semantic code navigation):
+       - Check if `.serena/` directory exists in the project root
+       - If already present, tell the user: "Serena directory already configured."
+       - If missing, create it: `mkdir -p .serena/memories`
+       - Verify `.serena/` is in `.gitignore` — if not, add it and commit
+       - Tell the user: "Created `.serena/` for semantic code navigation."
+
+    c. **Research relevant tools** — dispatch **two parallel agents**:
+
+       **Agent 1: Skills research**
+       - Search for Superpowers skills and Claude plugins relevant to the detected tech stack
+       - Consider the project's language, framework, testing approach, and deployment target
+       - Check installed vs. available skills and identify gaps
+
+       **Agent 2: MCP servers research**
+       - Search for MCP servers relevant to the detected tech stack
+       - Consider database, API, deployment, and tooling needs
+       - Check installed vs. available MCPs and identify gaps
+       - **Exclusion:** Never recommend `sequential-thinking-mcp` — it is incompatible with Supermind's skill system
+
+    d. **Present findings** (after both agents complete):
+       - Combine results from both agents into a unified list
+       - Show suggestions grouped by category: code navigation, testing, deployment, UI, database, etc.
+       - Include a brief explanation of why each tool is relevant to this project
        - Do not auto-install anything — let the user decide
-       - Group by category: code navigation, testing, deployment, UI, database, etc.
 
-16. **If no**: skip this phase. Initialization is complete.
+17. **If no**: skip this phase. Initialization is complete.
 
 ---
 

package/skills/supermind-living-docs/SKILL.md

@@ -16,9 +16,11 @@ Surgical edits preserve your existing formatting and avoid unnecessary diffs. Th
    - Read `DESIGN.md` from the project root (only if it exists — its presence means this is a UI project)
 
 2. **Assess recent changes**:
-   - Run `git diff --name-only` to see which files changed
+   - Run `git diff --name-only` for unstaged changes
+   - Run `git diff --name-only --cached` for staged changes
+   - Run `git status --short` for untracked files
    - Run `git diff --stat` to understand the scope of changes
-   - If working on uncommitted changes, also check `git diff --name-only HEAD` and `git status`
+   - Combine all lists into the set of changed files for subsequent steps
 
 3. **Reason about what needs updating**:
    - Files added, removed, or renamed — update **File Index**
@@ -31,16 +33,24 @@ Surgical edits preserve your existing formatting and avoid unnecessary diffs. Th
      - Components added or modified — update **Component Patterns**
      - Layout or animation changes — update **Layout Conventions** or **Animation Patterns**
 
-4. **If nothing meaningful changed**, say so and stop. Do not make edits for the sake of making edits.
+4. **Validate existing claims against changed files**:
+   - Using the full list of changed files from step 2:
+     a. For each changed file, check if ARCHITECTURE.md (or DESIGN.md) makes specific claims about that file's behavior, constants, patterns, or dependencies
+     b. For deleted files: remove or update any documentation entries that reference them
+     c. For modified files: verify claims are still accurate by reading the actual source
+     d. Fix any stale or incorrect claims (e.g., renamed constants, changed function signatures, outdated behavioral descriptions)
+   - Report to the user what stale claims were found and corrected
 
-5. **Make surgical edits**:
+5. **If nothing meaningful changed**, say so and stop. Do not make edits for the sake of making edits.
+
+6. **Make surgical edits**:
    - Use the Edit tool to update only the sections that need changing
    - Do NOT rewrite entire files — change only the rows, entries, or paragraphs that are affected
    - Match the existing format and section structure exactly
    - Keep content factual — document what IS, not what should be
    - Always include file paths when referencing source files
 
-6. **Commit** with a descriptive message:
+7. **Commit** with a descriptive message:
    - Example: `git commit -m "Update ARCHITECTURE.md: add new API routes, update file index"`
    - If both files were updated: `git commit -m "Update living docs: [brief description of changes]"`
 

package/templates/CLAUDE.md

@@ -24,12 +24,13 @@ A PreToolUse hook (`bash-permissions.js`) handles all Bash permission classifica
 **Auto-approved** (standalone or in any compound):
 - **Read-only shell**: ls, cat, head, tail, find, sed (without -i), grep, echo, pwd, jq, etc.
 - **Safe writes**: mkdir, touch, cp, mv
-- **Read-only git**: status, diff, log, show, blame, rev-parse, check-ignore, branch listing, tag listing, config
-- **Non-destructive git writes**: add, commit, stash (push/save/list/show), worktree add, worktree list, branch create
-- **gh CLI**: read-only gh commands (pr list/view/diff, issue list/view, repo view, etc. — not merge, close, delete)
+- **Utilities**: base64, claude CLI (config/mcp/plugin subcommands)
+- **Read-only git**: status, diff, log, show, blame, rev-parse, check-ignore, branch listing, tag listing, config (read-only: --get, --list)
+- **Non-destructive git writes**: add, commit, stash (bare/push/save/list/show), worktree add, worktree list, branch create, branch rename
+- **gh CLI**: read-only gh commands (pr list/view/diff, issue list/view, repo view, gh api GET — not merge, close, delete, or mutating API calls)
 
 **Worktree-only** (auto-approved only when `cd` targets a `.worktrees/` path or CWD is inside one):
-- git merge, git worktree remove, git branch -d
+- git merge, git worktree remove, git worktree prune, git branch -d
 
 **Always requires approval**:
 - push, pull, fetch, reset, revert, rebase, clean, checkout (discarding), restore, branch -D
@@ -64,7 +65,8 @@ Use the superpowers `/using-git-worktrees` skill for worktree creation. It handl
 3. **Commit** all work in the worktree
 4. **Review** — run the superpowers `code-reviewer` agent against the changes
 5. **Fix everything** — address ALL issues found by the reviewer (critical, minor, style, naming — everything). Do not ask what to fix. Fix all of them. Then re-review until the reviewer passes clean.
-6. **Finish** — invoke `/finishing-a-development-branch` to merge back and clean up. The skill handles:
+6. **Living docs check** — before merging, check if the changes affect anything documented in ARCHITECTURE.md (or DESIGN.md). For each changed file, verify that any claims the docs make about that file's behavior, constants, or patterns are still accurate. If updates are needed, make them and commit in the worktree branch.
+7. **Finish** — invoke `/finishing-a-development-branch` to merge back and clean up. The skill handles:
    - Merging the worktree branch into the originating branch
    - Removing the worktree directory
    - Deleting the temporary branch
@@ -72,10 +74,11 @@ Use the superpowers `/using-git-worktrees` skill for worktree creation. It handl
 ### Rules
 
 - The worktree branch must always be created from and merged back into the **same branch** — the one you are currently on locally. Never merge into a different branch.
-- `git merge`, `git worktree remove`, and `git branch -d` are auto-approved **only** within this worktree workflow. In all other contexts, these still require user approval.
+- `git merge`, `git worktree remove`, `git worktree prune`, and `git branch -d` are auto-approved **only** within this worktree workflow. In all other contexts, these still require user approval.
 - The code reviewer must find zero remaining issues before merging. If it finds problems, fix them and run the reviewer again. Repeat until clean.
 - Never skip the review step. Never skip "minor" fixes. Every finding gets fixed.
 - This entire process — create, implement, review, fix, merge, clean up — executes without stopping to ask for permission.
+- **Branch safety:** If the current branch is `main` or `master` when a code change is requested, create a feature branch first (`feature/…`, `fix/…`, or `chore/…`) before making any changes. Never commit directly to `main` or `master`.
 
 ## MCP Servers
 Use these naturally when relevant — don't wait to be asked.