mindsystem-cc 3.5.0 → 3.6.0

package/agents/ms-flutter-code-quality.md

@@ -0,0 +1,168 @@
+---
+name: ms-flutter-code-quality
+description: Refactors Flutter/Dart code to follow quality guidelines. Applies code patterns, widget organization, folder structure, and simplification. Spawned by execute-phase/do-work.
+model: sonnet
+tools: Read, Write, Edit, Bash, Grep, Glob, WebFetch
+color: cyan
+skills:
+  - flutter-code-quality
+  - flutter-code-simplification
+---
+
+You are an expert Flutter/Dart code quality specialist. Your job is to refactor code so it's clean, scalable, and maintainable by applying established guidelines.
+
+**Core principle:** Apply the guidelines. Verify with tests. Report what was fixed.
+
+<input_contract>
+You receive:
+- A list of files to refactor (via git diff or explicit list)
+- Files are Flutter/Dart code (.dart extension)
+
+You return:
+- Refactored files that follow guidelines
+- Verification results (analyze + test)
+- Report of what was changed
+</input_contract>
+
+## Key Principles
+
+### 1. Preserve Behavior (Non-negotiable)
+Functionality comes before code quality. Only improve code quality if you can maintain functionality. Refactor structure, not logic — the code must do the same thing in a cleaner way.
+
+### 2. Apply Guidelines
+If code doesn't follow the guidelines, refactor it so it does. The guidelines exist to be applied, not considered.
+
+### 3. Verify with Tests
+Run `flutter analyze` and `flutter test` after changes. If verification fails, revert that specific change and continue with others.
+
+### 4. Comprehensive Coverage
+Apply four lenses:
+1. Code quality patterns (anti-patterns, idioms, type safety)
+2. Widget organization (build structure, consistent ordering)
+3. Folder structure (flat, feature-based)
+4. Simplification (clarity, DRY, remove unnecessary complexity)
+
+## Four-Pass Refactoring
+
+### Pass 1: Code Quality Patterns
+
+Fetch guidelines first:
+```
+WebFetch: https://gist.githubusercontent.com/rolandtolnay/edf9ea7d5adf218f45accb3411f0627c/raw/flutter-code-quality-guidelines.md
+```
+
+Replace anti-patterns:
+- `useState<bool>` for loading → provider state
+- Manual try-catch in providers → `AsyncValue.guard()`
+- `.toList()..sort()` → `.sorted()`
+- Functions with 4+ params → define inside build()
+- Hardcoded hex colors → `context.color.*`
+- `.asData?.value` → `.value`
+- Inline filtering → computed property on entity
+
+Apply positive patterns:
+- Sealed classes for complex state
+- Records for multiple return values
+- Computed properties on entities/enums
+- `firstWhereOrNull` with fallbacks
+- Immutable collection methods
+
+### Pass 2: Widget Organization
+
+Enforce build() structure:
+- Order: providers → hooks → derived values → widget tree
+- Local variables for unconditional widgets
+- Builder functions for conditional rendering
+- Extract file-private widgets to own file
+- Move functions with 4+ params inside build()
+
+Enforce async UX:
+- Loading from provider state, not useState
+- Error handling via `ref.listen` + toast
+- First-load errors with retry button
+
+### Pass 3: Folder Structure
+
+Enforce organization:
+- Feature-based folders
+- Screens at feature root
+- `widgets/` only when 2+ widgets
+- `providers/` only when 2+ providers
+- `domain/` for models and repositories
+- Flatten deep `lib/features/x/presentation/` paths
+
+### Pass 4: Simplification
+
+Apply `flutter-code-simplification` skill principles:
+
+- Repeated null-checks → extract to local variable
+- Duplicated logic → extract to shared method
+- Scattered boolean flags → consolidate to sealed class or enum
+- Large build() methods → extract to builder methods
+- Unnecessary indirection → simplify to direct calls
+
+## Process
+
+1. **Identify targets** - Parse scope to find modified .dart files
+2. **Fetch guidelines** - WebFetch flutter-code-quality-guidelines.md from gist
+3. **Refactor Pass 1** - Apply code quality patterns
+4. **Refactor Pass 2** - Apply widget organization rules
+5. **Refactor Pass 3** - Apply folder structure conventions
+6. **Refactor Pass 4** - Apply simplification principles
+7. **Verify** - Run `fvm flutter analyze` and `fvm flutter test`
+8. **If verification fails** - Revert the failing change, continue with others
+9. **Report** - Document what was refactored
+
+<output_format>
+
+**If changes were made:**
+```
+## Refactoring Complete
+
+**Files:** [count] analyzed, [count] modified
+
+### Code Quality
+- `path/file.dart:42` - useState → provider state
+- `path/file.dart:67` - .toList()..sort() → .sorted()
+
+### Widget Organization
+- `path/file.dart:120` - Reordered build(): providers → hooks → derived → tree
+
+### Folder Structure
+- Moved `path/nested/widget.dart` → `path/widget.dart`
+
+### Simplification
+- `path/file.dart:150` - Extracted repeated logic to `_buildHeader()`
+
+### Verification
+- flutter analyze: pass
+- flutter test: pass
+
+### Modified Files
+[list of file paths]
+```
+
+**If no changes needed:**
+```
+## Refactoring Complete
+
+**Files:** [count] analyzed, 0 modified
+
+Code already follows guidelines.
+
+### Verification
+- flutter analyze: pass
+- flutter test: pass
+```
+
+</output_format>
+
+<success_criteria>
+- All functionality preserved — no behavior changes
+- Guidelines fetched from gist
+- All target .dart files refactored through four passes
+- Code follows guidelines after refactoring
+- `flutter analyze` passes
+- `flutter test` passes
+- Report documents what was changed
+</success_criteria>

package/agents/ms-flutter-simplifier.md

@@ -4,11 +4,13 @@ description: Simplifies Flutter/Dart code for clarity, consistency, and maintain
 model: sonnet
 tools: Read, Write, Edit, Bash, Grep, Glob
 color: cyan
+skills:
+  - flutter-code-simplification
 ---
 
 You are an expert Flutter/Dart code simplification specialist. Your expertise lies in making code easier to read, understand, and maintain without changing what it does. You prioritize readable, explicit code over overly compact solutions.
 
-**Core principle:** Simplification means making code easier to reason about — not making it shorter at the cost of clarity.
+Apply simplification principles and Flutter patterns from the `flutter-code-simplification` skill.
 
 <input_contract>
 You receive:
@@ -21,55 +23,6 @@ You return:
 - If no changes needed: clear statement that code already follows good patterns
 </input_contract>
 
-## Key Principles
-
-### 1. Preserve Functionality
-Never change what the code does—only how it does it. All original features, outputs, and behaviors must remain intact.
-
-### 2. Enhance Clarity
-- Reduce unnecessary complexity and nesting
-- Eliminate redundant code and abstractions
-- Improve readability through clear naming
-- Consolidate related logic and duplicates (DRY)
-- Choose clarity over brevity—explicit code is often better than compact code
-
-### 3. Maintain Balance
-Avoid over-simplification that could:
-- Create overly clever solutions that are hard to understand
-- Combine too many concerns into single functions/components
-- Remove helpful abstractions that improve code organization
-- Prioritize "fewer lines" over readability
-- Make code harder to debug or extend
-
-### 4. Apply Judgment
-Use your expertise to determine what improves the code. These principles guide your decisions—they are not a checklist. If a change doesn't clearly improve clarity while preserving behavior, don't make it.
-
-## Flutter Patterns to Consider
-
-These are common opportunities in Flutter/Dart code. Apply when they genuinely improve clarity.
-
-**State & Data:**
-- Scattered boolean flags → sealed class variants with switch expressions (when it consolidates and clarifies)
-- Same parameters repeated across functions → records or typed classes
-- Manual try-catch in providers → `AsyncValue.guard()` with centralized error handling
-- Check `ref.mounted` after async operations
-
-**Widget Structure:**
-- Large `build()` methods → extract into local variables or builder methods
-- Widgets with many boolean parameters → consider composition or typed mode objects
-- Keep build() order: providers → hooks → derived values → widget tree
-
-**Collections:**
-- Mutation patterns → immutable methods (`.sorted()`, `.where()`, etc.)
-- Null-unsafe access → `firstWhereOrNull` with fallbacks
-- Repeated enum switches → computed properties on the enum itself
-
-**Code Organization:**
-- Duplicated logic across files → extract to shared location
-- Related methods scattered in class → group by concern
-- Unnecessary indirection (factories creating one type, wrappers adding no behavior) → use concrete types directly
-- **Exception:** API layer interfaces with implementation in same file are intentional (interface provides at-a-glance documentation)
-
 ## Process
 
 1. **Identify targets** - Parse scope to find modified .dart files

package/bin/install.js

@@ -4,6 +4,7 @@ const fs = require('fs');
 const path = require('path');
 const os = require('os');
 const readline = require('readline');
+const crypto = require('crypto');
 
 // Colors (using 256-color mode for better terminal compatibility)
 const cyan = '\x1b[38;5;37m'; // Closest to #2FA7A0 in 256-color palette
@@ -54,6 +55,7 @@ function parseConfigDirArg() {
   return null;
 }
 const explicitConfigDir = parseConfigDirArg();
+const hasForce = args.includes('--force') || args.includes('-f');
 const hasHelp = args.includes('--help') || args.includes('-h');
 
 console.log(banner);
@@ -66,6 +68,7 @@ if (hasHelp) {
     ${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}-f, --force${reset}               Overwrite modified files without prompting
     ${cyan}-h, --help${reset}                Show this help message
 
   ${yellow}Examples:${reset}
@@ -99,6 +102,308 @@ function expandTilde(filePath) {
   return filePath;
 }
 
+/**
+ * Compute SHA-256 checksum truncated to 16 chars
+ */
+function computeChecksum(content) {
+  return crypto.createHash('sha256').update(content).digest('hex').slice(0, 16);
+}
+
+/**
+ * Read and parse manifest file, return null if missing/corrupted
+ */
+function readManifest(claudeDir) {
+  const manifestPath = path.join(claudeDir, 'mindsystem', '.manifest.json');
+  try {
+    if (!fs.existsSync(manifestPath)) {
+      return null;
+    }
+    const content = fs.readFileSync(manifestPath, 'utf8');
+    return JSON.parse(content);
+  } catch (e) {
+    console.log(`  ${yellow}⚠${reset} Manifest corrupted, treating as fresh install`);
+    return null;
+  }
+}
+
+/**
+ * Write manifest JSON file
+ */
+function writeManifest(claudeDir, manifest) {
+  const manifestDir = path.join(claudeDir, 'mindsystem');
+  fs.mkdirSync(manifestDir, { recursive: true });
+  const manifestPath = path.join(manifestDir, '.manifest.json');
+  fs.writeFileSync(manifestPath, JSON.stringify(manifest, null, 2));
+}
+
+/**
+ * Check if running in interactive TTY
+ */
+function isInteractive() {
+  return process.stdin.isTTY && process.stdout.isTTY;
+}
+
+/**
+ * Recursively collect files with relative paths
+ * @param {string} baseDir - The base directory for relative path calculation
+ * @param {string} currentDir - The current directory being scanned
+ * @param {string} destPrefix - The destination prefix (e.g., 'commands/ms', 'agents')
+ * @returns {Array<{relativePath: string, absolutePath: string}>}
+ */
+function collectFiles(baseDir, currentDir, destPrefix) {
+  const files = [];
+  if (!fs.existsSync(currentDir)) {
+    return files;
+  }
+
+  const entries = fs.readdirSync(currentDir, { withFileTypes: true });
+  for (const entry of entries) {
+    const absolutePath = path.join(currentDir, entry.name);
+    const relativeToCurrent = path.relative(baseDir, absolutePath);
+    const relativePath = path.join(destPrefix, relativeToCurrent);
+
+    if (entry.isDirectory()) {
+      files.push(...collectFiles(baseDir, absolutePath, destPrefix));
+    } else {
+      files.push({ relativePath, absolutePath });
+    }
+  }
+  return files;
+}
+
+/**
+ * Build complete list of files to install from all source directories
+ * @param {string} src - The source directory (mindsystem package root)
+ * @returns {Array<{relativePath: string, absolutePath: string}>}
+ */
+function buildInstallManifest(src) {
+  const files = [];
+
+  // commands/ms
+  const commandsSrc = path.join(src, 'commands', 'ms');
+  files.push(...collectFiles(commandsSrc, commandsSrc, 'commands/ms'));
+
+  // mindsystem
+  const mindsystemSrc = path.join(src, 'mindsystem');
+  files.push(...collectFiles(mindsystemSrc, mindsystemSrc, 'mindsystem'));
+
+  // agents
+  const agentsSrc = path.join(src, 'agents');
+  files.push(...collectFiles(agentsSrc, agentsSrc, 'agents'));
+
+  // scripts -> mindsystem/scripts
+  const scriptsSrc = path.join(src, 'scripts');
+  files.push(...collectFiles(scriptsSrc, scriptsSrc, 'mindsystem/scripts'));
+
+  // skills
+  const skillsSrc = path.join(src, 'skills');
+  files.push(...collectFiles(skillsSrc, skillsSrc, 'skills'));
+
+  // CHANGELOG.md -> mindsystem/CHANGELOG.md
+  const changelogSrc = path.join(src, 'CHANGELOG.md');
+  if (fs.existsSync(changelogSrc)) {
+    files.push({ relativePath: 'mindsystem/CHANGELOG.md', absolutePath: changelogSrc });
+  }
+
+  return files;
+}
+
+/**
+ * Compare manifests to detect orphans and conflicts
+ * @param {Object|null} oldManifest - Previous manifest or null for fresh install
+ * @param {string} claudeDir - Target directory
+ * @param {Array} newFiles - Files to install
+ * @param {string} pathPrefix - Path prefix for content replacement
+ * @returns {{orphans: string[], conflicts: Array<{relativePath: string, reason: string}>}}
+ */
+function compareManifests(oldManifest, claudeDir, newFiles, pathPrefix) {
+  const orphans = [];
+  const conflicts = [];
+
+  // Build set of new file paths
+  const newFilePaths = new Set(newFiles.map(f => f.relativePath));
+
+  // Find orphans (files in old manifest but not in new)
+  if (oldManifest && oldManifest.files) {
+    for (const oldPath of Object.keys(oldManifest.files)) {
+      if (!newFilePaths.has(oldPath)) {
+        const fullPath = path.join(claudeDir, oldPath);
+        if (fs.existsSync(fullPath)) {
+          orphans.push(oldPath);
+        }
+      }
+    }
+  }
+
+  // Find conflicts (installed files modified by user)
+  if (oldManifest && oldManifest.files) {
+    for (const fileInfo of newFiles) {
+      const destPath = path.join(claudeDir, fileInfo.relativePath);
+      if (!fs.existsSync(destPath)) {
+        continue; // New file, no conflict
+      }
+
+      const oldChecksum = oldManifest.files[fileInfo.relativePath];
+      if (!oldChecksum) {
+        continue; // File not in old manifest, treat as new
+      }
+
+      // Read current installed content
+      const installedContent = fs.readFileSync(destPath, 'utf8');
+      const installedChecksum = computeChecksum(installedContent);
+
+      // If installed file differs from what we last installed, it's been modified
+      if (installedChecksum !== oldChecksum) {
+        // Read source content with path replacement to compare
+        let sourceContent = fs.readFileSync(fileInfo.absolutePath, 'utf8');
+        if (fileInfo.absolutePath.endsWith('.md')) {
+          sourceContent = sourceContent.replace(/~\/\.claude\//g, pathPrefix);
+        }
+        const sourceChecksum = computeChecksum(sourceContent);
+
+        // Only conflict if source is also different (user modified AND we have changes)
+        if (sourceChecksum !== installedChecksum) {
+          conflicts.push({
+            relativePath: fileInfo.relativePath,
+            reason: 'locally modified'
+          });
+        }
+      }
+    }
+  }
+
+  return { orphans, conflicts };
+}
+
+/**
+ * Interactive conflict resolution
+ * @param {Array} conflicts - List of conflicting files
+ * @param {boolean} forceOverwrite - Skip prompts and overwrite all
+ * @returns {Promise<{overwrite: Set<string>, keep: Set<string>}>}
+ */
+async function resolveConflicts(conflicts, forceOverwrite) {
+  const overwrite = new Set();
+  const keep = new Set();
+
+  if (conflicts.length === 0) {
+    return { overwrite, keep };
+  }
+
+  if (forceOverwrite) {
+    for (const c of conflicts) {
+      overwrite.add(c.relativePath);
+    }
+    console.log(`  ${yellow}⚠${reset} Force overwriting ${conflicts.length} modified file(s)`);
+    return { overwrite, keep };
+  }
+
+  if (!isInteractive()) {
+    for (const c of conflicts) {
+      overwrite.add(c.relativePath);
+    }
+    console.log(`  ${yellow}⚠${reset} Non-interactive mode: overwriting ${conflicts.length} modified file(s)`);
+    return { overwrite, keep };
+  }
+
+  const rl = readline.createInterface({
+    input: process.stdin,
+    output: process.stdout
+  });
+
+  const question = (prompt) => new Promise((resolve) => rl.question(prompt, resolve));
+
+  console.log(`\n  ${yellow}${conflicts.length} file(s) have local modifications:${reset}\n`);
+
+  let overwriteAll = false;
+  let keepAll = false;
+
+  for (const conflict of conflicts) {
+    if (overwriteAll) {
+      overwrite.add(conflict.relativePath);
+      continue;
+    }
+    if (keepAll) {
+      keep.add(conflict.relativePath);
+      continue;
+    }
+
+    console.log(`  ${dim}${conflict.relativePath}${reset}`);
+    const answer = await question(`  [O]verwrite, [K]eep, [A]ll overwrite, [N]one keep? `);
+
+    switch (answer.toLowerCase().trim()) {
+      case 'o':
+      case 'overwrite':
+        overwrite.add(conflict.relativePath);
+        break;
+      case 'k':
+      case 'keep':
+        keep.add(conflict.relativePath);
+        break;
+      case 'a':
+      case 'all':
+        overwriteAll = true;
+        overwrite.add(conflict.relativePath);
+        break;
+      case 'n':
+      case 'none':
+        keepAll = true;
+        keep.add(conflict.relativePath);
+        break;
+      default:
+        // Default to overwrite
+        overwrite.add(conflict.relativePath);
+    }
+  }
+
+  rl.close();
+  console.log('');
+  return { overwrite, keep };
+}
+
+/**
+ * Remove orphaned files and empty directories
+ * @param {string} claudeDir - Target directory
+ * @param {string[]} filesToRemove - Relative paths of files to remove
+ */
+function cleanupOrphanedFiles(claudeDir, filesToRemove) {
+  if (filesToRemove.length === 0) {
+    return;
+  }
+
+  const dirsToCheck = new Set();
+
+  for (const relativePath of filesToRemove) {
+    const fullPath = path.join(claudeDir, relativePath);
+    try {
+      if (fs.existsSync(fullPath)) {
+        fs.unlinkSync(fullPath);
+        console.log(`  ${yellow}✗${reset} Removed ${relativePath}`);
+        // Track parent directories for cleanup
+        dirsToCheck.add(path.dirname(fullPath));
+      }
+    } catch (e) {
+      console.log(`  ${yellow}⚠${reset} Failed to remove ${relativePath}: ${e.message}`);
+    }
+  }
+
+  // Remove empty directories (deepest first)
+  const sortedDirs = Array.from(dirsToCheck).sort((a, b) => b.length - a.length);
+  for (const dir of sortedDirs) {
+    try {
+      // Don't remove the claudeDir itself or its immediate children (commands, agents, etc.)
+      if (dir === claudeDir || path.dirname(dir) === claudeDir) {
+        continue;
+      }
+      const entries = fs.readdirSync(dir);
+      if (entries.length === 0) {
+        fs.rmdirSync(dir);
+      }
+    } catch (e) {
+      // Ignore errors (directory not empty or doesn't exist)
+    }
+  }
+}
+
 /**
  * Recursively copy directory, replacing paths in .md files
  */
@@ -144,10 +449,33 @@ function copyDir(srcDir, destDir) {
   }
 }
 
+/**
+ * Install a single file with path replacement
+ * @param {string} srcPath - Source file path
+ * @param {string} destPath - Destination file path
+ * @param {string} pathPrefix - Path prefix for .md file replacement
+ */
+function installFile(srcPath, destPath, pathPrefix) {
+  fs.mkdirSync(path.dirname(destPath), { recursive: true });
+
+  if (srcPath.endsWith('.md')) {
+    let content = fs.readFileSync(srcPath, 'utf8');
+    content = content.replace(/~\/\.claude\//g, pathPrefix);
+    fs.writeFileSync(destPath, content);
+  } else {
+    fs.copyFileSync(srcPath, destPath);
+  }
+
+  // Make shell scripts executable
+  if (srcPath.endsWith('.sh')) {
+    fs.chmodSync(destPath, '755');
+  }
+}
+
 /**
  * Install to the specified directory
  */
-function install(isGlobal) {
+async 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);
@@ -168,93 +496,106 @@ function install(isGlobal) {
 
   console.log(`  Installing to ${cyan}${locationLabel}${reset}\n`);
 
-  // Create commands directory
-  const commandsDir = path.join(claudeDir, 'commands');
-  fs.mkdirSync(commandsDir, { recursive: true });
+  // Phase 1: Read old manifest
+  const oldManifest = readManifest(claudeDir);
+
+  // Phase 2: Build list of files to install
+  const filesToInstall = buildInstallManifest(src);
+
+  // Phase 3: Compare and detect conflicts
+  const { orphans, conflicts } = compareManifests(oldManifest, claudeDir, filesToInstall, pathPrefix);
+
+  // Phase 4: Resolve conflicts interactively
+  const { overwrite, keep } = await resolveConflicts(conflicts, hasForce);
+
+  // Phase 5: Install files (skipping kept files)
+  const newManifestFiles = {};
+  const categories = {
+    'commands/ms': { count: 0, label: 'commands/ms' },
+    'mindsystem': { count: 0, label: 'mindsystem' },
+    'agents': { count: 0, label: 'agents' },
+    'mindsystem/scripts': { count: 0, label: 'scripts' },
+    'skills': { count: 0, label: 'skills' }
+  };
+
+  for (const fileInfo of filesToInstall) {
+    const destPath = path.join(claudeDir, fileInfo.relativePath);
+
+    // Skip files user wants to keep
+    if (keep.has(fileInfo.relativePath)) {
+      // Still need to track in manifest with current checksum
+      const installedContent = fs.readFileSync(destPath, 'utf8');
+      newManifestFiles[fileInfo.relativePath] = computeChecksum(installedContent);
+      continue;
+    }
 
-  // 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`);
+    // Install the file
+    installFile(fileInfo.absolutePath, destPath, pathPrefix);
 
-  // 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`);
+    // Compute checksum of installed content (after path replacement)
+    let installedContent;
+    if (fileInfo.absolutePath.endsWith('.md')) {
+      installedContent = fs.readFileSync(fileInfo.absolutePath, 'utf8');
+      installedContent = installedContent.replace(/~\/\.claude\//g, pathPrefix);
+    } else {
+      installedContent = fs.readFileSync(destPath, 'utf8');
+    }
+    newManifestFiles[fileInfo.relativePath] = computeChecksum(installedContent);
 
-  // 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`);
+    // Track category counts
+    for (const prefix of Object.keys(categories)) {
+      if (fileInfo.relativePath.startsWith(prefix)) {
+        categories[prefix].count++;
+        break;
+      }
+    }
   }
 
-  // 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');
-        }
-      }
+  // Print install summaries
+  for (const [prefix, info] of Object.entries(categories)) {
+    if (info.count > 0) {
+      console.log(`  ${green}✓${reset} Installed ${info.label}`);
     }
-    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})`);
-          }
+  }
+
+  // Phase 6: Write VERSION file
+  const versionDest = path.join(claudeDir, 'mindsystem', 'VERSION');
+  fs.writeFileSync(versionDest, pkg.version);
+  console.log(`  ${green}✓${reset} Wrote VERSION (${pkg.version})`);
+
+  // Phase 7: Check Python for ms-lookup
+  const msLookupPath = path.join(claudeDir, 'mindsystem', 'scripts', '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+`);
       }
+    } catch (e) {
+      console.log(`  ${yellow}⚠${reset} Python not found - ms-lookup CLI requires Python 3.9+`);
     }
   }
 
-  // Copy skills
-  const skillsSrc = path.join(src, 'skills');
-  if (fs.existsSync(skillsSrc)) {
-    const skillsDest = path.join(claudeDir, 'skills');
-    copyWithPathReplacement(skillsSrc, skillsDest, pathPrefix);
-    console.log(`  ${green}✓${reset} Installed skills`);
-  }
-
-  // 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`);
+  // Phase 8: Cleanup orphaned files
+  if (orphans.length > 0) {
+    console.log('');
+    cleanupOrphanedFiles(claudeDir, orphans);
   }
 
-  // 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})`);
+  // Phase 9: Write new manifest
+  const newManifest = {
+    version: pkg.version,
+    installedAt: new Date().toISOString(),
+    files: newManifestFiles
+  };
+  writeManifest(claudeDir, newManifest);
 
   console.log(`
   ${green}Done!${reset} Launch Claude Code and run ${cyan}/ms:help${reset}.
@@ -264,7 +605,7 @@ function install(isGlobal) {
 /**
  * Prompt for install location
  */
-function promptLocation() {
+async function promptLocation() {
   const rl = readline.createInterface({
     input: process.stdin,
     output: process.stdout
@@ -280,25 +621,35 @@ function promptLocation() {
   ${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);
+  return new Promise((resolve) => {
+    rl.question(`  Choice ${dim}[1]${reset}: `, async (answer) => {
+      rl.close();
+      const choice = answer.trim() || '1';
+      const isGlobal = choice !== '2';
+      await install(isGlobal);
+      resolve();
+    });
   });
 }
 
 // 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();
+async function 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) {
+    await install(true);
+  } else if (hasLocal) {
+    await install(false);
+  } else {
+    await promptLocation();
+  }
 }
+
+main().catch((err) => {
+  console.error(`  ${yellow}Error: ${err.message}${reset}`);
+  process.exit(1);
+});

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mindsystem-cc",
-  "version": "3.5.0",
+  "version": "3.6.0",
   "description": "A meta-prompting, context engineering and spec-driven development system for Claude Code by TÂCHES.",
   "bin": {
     "mindsystem-cc": "bin/install.js"

package/skills/flutter-code-quality/SKILL.md

@@ -0,0 +1,142 @@
+---
+name: flutter-code-quality
+description: Flutter/Dart code quality, widget organization, and folder structure guidelines. Use when reviewing, refactoring, or cleaning up Flutter code after implementation.
+license: MIT
+metadata:
+  author: forgeblast
+  version: "1.0.0"
+  date: January 2026
+  argument-hint: <file-or-pattern>
+---
+
+# Flutter Code Quality
+
+Comprehensive guidelines for Flutter/Dart code quality, widget organization, and folder structure. Combines pattern-level rules (anti-patterns, idioms) with structural guidance (build method organization, folder conventions).
+
+## How It Works
+
+1. Fetch flutter-code-quality-guidelines.md from the gist URL below (always fresh)
+2. Apply embedded widget organization and folder structure rules
+3. Check files against all guidelines
+4. Output findings in terse `file:line` format
+
+## Code Quality Guidelines (Remote)
+
+Fetch fresh guidelines before each review:
+
+```
+https://gist.githubusercontent.com/rolandtolnay/edf9ea7d5adf218f45accb3411f0627c/raw/flutter-code-quality-guidelines.md
+```
+
+Use WebFetch to retrieve. Contains: anti-patterns, widget patterns, state management, collections, hooks, theme/styling, etc.
+
+## Widget Organization Guidelines (Embedded)
+
+### Build Method Structure
+
+Order inside `build()`:
+1. Providers (reads/watches)
+2. Hooks (if using flutter_hooks)
+3. Derived variables needed for rendering
+4. Widget variables (in render order)
+
+### When to Use What
+
+| Scenario | Pattern |
+|----------|---------|
+| Widget always shown, no conditions | Local variable: `final header = Container(...);` |
+| Widget depends on condition/null check | Builder function: `Widget? _buildContent() { if (data == null) return null; ... }` |
+| Subtree is large, reusable, or has own state | Extract to standalone widget in own file |
+| Function needs 3 or fewer params | Define outside `build()` as class method |
+| Function needs 4+ params (esp. hooks) | Define inside `build()` to capture scope |
+
+### Rules
+
+- **No file-private widgets** - If big enough to be a widget, it gets its own file
+- **Define local variables in render order** - Top-to-bottom matches screen layout
+- **Extract non-trivial conditions** - `final canSubmit = isValid && !isLoading && selectedId != null;`
+- **Pass `WidgetRef` only** when function needs both ref and context - Use `ref.context` inside
+
+### Async UX Conventions
+
+- **Button loading** - Watch provider state, not separate `useState<bool>`
+- **Retriable errors** - Listen to provider, show toast on error, user retries by tapping again
+- **First-load errors** - Render error view with retry button that invalidates provider
+
+### Sorting/Filtering
+
+- Simple options: Use enum with computed properties
+- Options with behavior: Use sealed class
+- Complex multi-field filtering: Dedicated `Filter` class
+
+## Folder Structure Guidelines (Embedded)
+
+### Core Rules
+
+1. **Organize by feature** - Each feature gets its own folder
+2. **Screens at feature root** - `account_screen.dart`, `edit_account_screen.dart`
+3. **Create subfolders only when justified:**
+   - `widgets/` when 2+ reusable widgets exist
+   - `providers/` when 2+ provider files exist
+   - `domain/` usually always (models, repositories)
+4. **Split large features into subfeatures** - Each subfeature follows same rules
+
+### Example
+
+```
+lib/features/
+  account/
+    account_screen.dart
+    edit_account_screen.dart
+    widgets/
+      account_avatar.dart
+      account_form.dart
+    providers/
+      account_provider.dart
+    domain/
+      account.dart
+      account_repository.dart
+```
+
+## Application Priority
+
+When reviewing code, apply in this order:
+
+1. **Code Quality Patterns** (from fetched gist) - Anti-patterns, idioms, provider patterns
+2. **Widget Organization** (above) - Build structure, extraction rules, async UX
+3. **Folder Structure** (above) - File placement, feature boundaries
+
+## Anti-Patterns Quick Reference
+
+Flag these patterns (details in fetched guidelines):
+
+- `useState<bool>` for loading states
+- Manual try-catch in provider actions
+- `.toList()..sort()` instead of `.sorted()`
+- `_handleAction(ref, controller, user, state)` with 4+ params
+- Hardcoded hex colors
+- Deep `lib/features/x/presentation/` directories
+- Barrel files that only re-export
+- Boolean flags instead of sealed classes
+- Magic numbers scattered across widgets
+- `where((e) => e.status == Status.active)` instead of computed property
+- Generic provider names like `expansionVisibilityProvider`
+- `.asData?.value` instead of `.value`
+
+## Output Format
+
+Group by file. Use `file:line` format. Terse findings.
+
+```text
+## lib/home/home_screen.dart
+
+lib/home/home_screen.dart:42 - useState for loading state -> use provider
+lib/home/home_screen.dart:67 - .toList()..sort() -> .sorted()
+lib/home/home_screen.dart:89 - hardcoded Color(0xFF...) -> context.color.*
+
+## lib/models/user.dart
+
+pass
+```
+
+State issue + location. Skip explanation unless fix non-obvious. No preamble.

package/skills/flutter-code-simplification/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: flutter-code-simplification
+description: Flutter/Dart code simplification principles. Use when simplifying, refactoring, or cleaning up Flutter code for clarity and maintainability.
+license: MIT
+metadata:
+  author: forgeblast
+  version: "1.0.0"
+  date: January 2026
+  argument-hint: <file-or-pattern>
+---
+
+# Flutter Code Simplification
+
+Principles and patterns for simplifying Flutter/Dart code. Simplification means making code easier to reason about — not making it shorter at the cost of clarity.
+
+## Core Philosophy
+
+**Clarity over brevity.** Explicit code is often better than compact code. The goal is code that's easy to read, understand, and maintain without changing what it does.
+
+## Principles
+
+### 1. Preserve Functionality
+
+Never change what the code does — only how it does it. All original features, outputs, and behaviors must remain intact.
+
+### 2. Enhance Clarity
+
+- Reduce unnecessary complexity and nesting
+- Eliminate redundant code and abstractions
+- Improve readability through clear naming
+- Consolidate related logic and duplicates (DRY)
+- Choose clarity over brevity — explicit code is often better than compact code
+
+### 3. Maintain Balance
+
+Avoid over-simplification that could:
+- Create overly clever solutions that are hard to understand
+- Combine too many concerns into single functions/components
+- Remove helpful abstractions that improve code organization
+- Prioritize "fewer lines" over readability
+- Make code harder to debug or extend
+
+### 4. Apply Judgment
+
+Use expertise to determine what improves the code. These principles guide decisions — they are not a checklist. If a change doesn't clearly improve clarity while preserving behavior, don't make it.
+
+## Flutter Patterns
+
+Common opportunities in Flutter/Dart code. Apply when they genuinely improve clarity.
+
+### State & Data
+
+| Pattern | Simplification |
+|---------|----------------|
+| Scattered boolean flags | Sealed class variants with switch expressions (when it consolidates and clarifies) |
+| Same parameters repeated across functions | Records or typed classes |
+| Manual try-catch in providers | `AsyncValue.guard()` with centralized error handling |
+| Async operations without mount check | Check `ref.mounted` after async operations |
+
+### Widget Structure
+
+| Pattern | Simplification |
+|---------|----------------|
+| Large `build()` methods | Extract into local variables or builder methods |
+| Widgets with many boolean parameters | Consider composition or typed mode objects |
+| Unordered build() | Keep order: providers → hooks → derived values → widget tree |
+
+### Collections
+
+| Pattern | Simplification |
+|---------|----------------|
+| Mutation patterns | Immutable methods (`.sorted()`, `.where()`, etc.) |
+| Null-unsafe access | `firstWhereOrNull` with fallbacks |
+| Repeated enum switches | Computed properties on the enum itself |
+
+### Code Organization
+
+| Pattern | Simplification |
+|---------|----------------|
+| Duplicated logic across files | Extract to shared location |
+| Related methods scattered in class | Group by concern |
+| Unnecessary indirection (factories creating one type, wrappers adding no behavior) | Use concrete types directly |
+
+**Exception:** API layer interfaces with implementation in same file are intentional — interface provides at-a-glance documentation.
+
+## Output Format
+
+Group by file. Use `file:line` format. Terse findings.
+
+```text
+## lib/home/home_screen.dart
+
+lib/home/home_screen.dart:42 - scattered booleans -> sealed class
+lib/home/home_screen.dart:67 - .toList()..sort() -> .sorted()
+lib/home/home_screen.dart:120 - large build() -> extract builder methods
+
+## lib/models/user.dart
+
+pass
+```
+
+State issue + location. Skip explanation unless fix non-obvious. No preamble.