@codihaus/claude-skills 1.5.1 → 1.6.1

package/src/commands/init.js

@@ -15,7 +15,9 @@ import {
   checkProjectDeps,
   printDepsReport,
   installProjectDeps,
-  installPythonDeps
+  installProjectDepsWithPM,
+  installPythonDeps,
+  installOptionalTools
 } from '../utils/deps.js';
 import {
   getAvailableSkills,
@@ -33,11 +35,13 @@ import {
 import {
   runProjectSetup,
   detectEnvExample,
-  hasEnvFile
+  hasEnvFile,
+  detectPackageManager
 } from '../utils/project-setup.js';
 
 export async function init(options) {
   const projectPath = process.cwd();
+  let globalDeps = null; // Declare at function level for later use
 
   console.log(chalk.bold('\n🚀 Claude Skills Initialization\n'));
   console.log(chalk.gray(`Project: ${projectPath}\n`));
@@ -45,7 +49,7 @@ export async function init(options) {
   // Step 1: Check global dependencies
   if (!options.noDeps) {
     const spinner = ora('Checking system dependencies...').start();
-    const globalDeps = await checkGlobalDeps();
+    globalDeps = await checkGlobalDeps();
     spinner.stop();
 
     printDepsReport(globalDeps);
@@ -69,19 +73,26 @@ export async function init(options) {
       }
     }
 
-    // Offer to install missing Python packages
+    // Check if Python is available before offering to install packages
+    const hasPython = globalDeps.recommended.find(d => d.name === 'python3')?.found;
+    const hasPip = globalDeps.recommended.find(d => d.name === 'pip3')?.found;
+
+    // Offer to install missing Python packages (only if Python is installed)
     const missingPython = globalDeps.python?.filter(p => !p.installed) || [];
-    if (missingPython.length > 0 && !options.yes) {
+    if (hasPython && hasPip && missingPython.length > 0 && !options.yes) {
       const { installPython } = await inquirer.prompt([{
         type: 'confirm',
         name: 'installPython',
-        message: `Install missing Python packages (${missingPython.map(p => p.name).join(', ')})?`,
+        message: `Install missing Python packages (${missingPython.map(p => p.name).join(', ')})? (will try --user first, then sudo if needed)`,
         default: true
       }]);
 
       if (installPython) {
         await installPythonDeps(missingPython);
       }
+    } else if (missingPython.length > 0 && (!hasPython || !hasPip)) {
+      console.log(chalk.yellow('\n⚠️  Python packages are needed but Python/pip is not available.'));
+      console.log(chalk.gray('Install Python first, then run: pip3 install --user ' + missingPython.map(p => p.name).join(' ')));
     }
   }
 
@@ -216,12 +227,15 @@ export async function init(options) {
     try {
       const result = await setupHooks(projectPath);
       if (result) {
-        hooksSpinner.succeed('Hooks configured');
+        hooksSpinner.succeed('Hooks configured (with retry limits & graceful failure)');
+        console.log(chalk.gray('   → Auto-updates docs graph when editing plans/'));
+        console.log(chalk.gray('   → Max 3 retries, 5s timeout, non-blocking failures'));
       } else {
         hooksSpinner.info('Hooks skipped');
       }
     } catch (e) {
       hooksSpinner.warn('Failed to set up hooks');
+      console.log(chalk.yellow('   → You can configure hooks manually later'));
     }
   }
 
@@ -245,13 +259,42 @@ export async function init(options) {
     gitSpinner.warn('Failed to update .gitignore');
   }
 
-  // Step 11: Project setup (package manager, .env, node version)
+  // Step 11: Offer to install optional tools
+  if (!options.noDeps && globalDeps.optional) {
+    const missingOptional = globalDeps.optional.filter(d => !d.found);
+
+    if (missingOptional.length > 0 && !options.yes) {
+      console.log(chalk.cyan('\n📦 Optional Tools\n'));
+      console.log(chalk.gray('These tools enhance skills but are not required. Select which ones to install:\n'));
+
+      const { selectedTools } = await inquirer.prompt([{
+        type: 'checkbox',
+        name: 'selectedTools',
+        message: 'Select optional tools to install:',
+        choices: missingOptional.map(tool => ({
+          name: `${tool.name.padEnd(8)} - ${tool.purpose} ${chalk.gray(`(${tool.usedBy.join(', ')})`)}`,
+          value: tool.name,
+          // Check all by default except 'gh' (GitHub CLI)
+          checked: tool.name !== 'gh'
+        }))
+      }]);
+
+      if (selectedTools.length > 0) {
+        const toolsToInstall = missingOptional.filter(t => selectedTools.includes(t.name));
+        await installOptionalTools(toolsToInstall, globalDeps.os);
+      } else {
+        console.log(chalk.gray('No optional tools selected. Skipping...\n'));
+      }
+    }
+  }
+
+  // Step 12: Project setup (package manager, .env, node version)
   console.log('\n' + chalk.cyan('─'.repeat(40)));
   console.log(chalk.bold('📦 Project Setup\n'));
 
   const setupResult = await runProjectSetup(projectPath, { yes: options.yes });
 
-  // Step 12: Check skill-specific project dependencies
+  // Step 13: Check skill-specific project dependencies
   if (!options.noDeps) {
     console.log('');
     const projectSpinner = ora('Checking skill dependencies...').start();
@@ -262,9 +305,25 @@ export async function init(options) {
       console.log(chalk.yellow('\n⚠️  Some optional dependencies for skills are missing:\n'));
 
       for (const dep of projectDeps.missing) {
-        const cmd = dep.type === 'pip'
-          ? chalk.cyan(`pip install ${dep.name}`)
-          : chalk.cyan(`npm install -D ${dep.name}`);
+        const pm = setupResult.packageManager?.name || 'npm';
+        let cmd;
+        if (dep.type === 'pip') {
+          cmd = chalk.cyan(`pip install ${dep.name}`);
+        } else {
+          switch (pm) {
+            case 'pnpm':
+              cmd = chalk.cyan(`pnpm add -D ${dep.name}`);
+              break;
+            case 'yarn':
+              cmd = chalk.cyan(`yarn add -D ${dep.name}`);
+              break;
+            case 'bun':
+              cmd = chalk.cyan(`bun add -D ${dep.name}`);
+              break;
+            default:
+              cmd = chalk.cyan(`npm install -D ${dep.name}`);
+          }
+        }
         console.log(`  ${dep.name} - ${dep.purpose}`);
         console.log(`    ${cmd}\n`);
       }
@@ -278,7 +337,12 @@ export async function init(options) {
         }]);
 
         if (install) {
-          await installProjectDeps(projectPath, projectDeps.missing);
+          // Use package manager-aware installation if we have one
+          if (setupResult.packageManager) {
+            await installProjectDepsWithPM(projectPath, projectDeps.missing, setupResult.packageManager);
+          } else {
+            await installProjectDeps(projectPath, projectDeps.missing);
+          }
         }
       }
     }
@@ -323,6 +387,14 @@ export async function init(options) {
   stepNum++;
   console.log(`  ${stepNum}. See all skills: ${chalk.cyan('/help')}`);
   console.log('');
-  console.log(chalk.gray('Docs: .claude/skills/_registry.md'));
+  console.log(chalk.gray('Docs:'));
+  console.log(chalk.gray('  • Skills: .claude/skills/_registry.md'));
+  console.log(chalk.gray('  • Hooks: .claude/hooks-guide.md (troubleshooting hook failures)'));
   console.log('');
+
+  // Add note about hooks if they were set up
+  if (!options.noHooks) {
+    console.log(chalk.dim('💡 Tip: If hooks fail repeatedly, see .claude/hooks-guide.md for troubleshooting'));
+    console.log('');
+  }
 }

package/src/utils/config.js

@@ -46,15 +46,27 @@ const DEFAULT_SETTINGS = {
 
 /**
  * Hooks for automatic graph updates
+ *
+ * IMPORTANT: Hooks should be resilient and fail gracefully.
+ * - Use `|| true` to prevent hook failures from blocking Claude
+ * - Add retry limits to prevent infinite loops
+ * - Keep hooks fast (< 2 seconds) to avoid slowing down workflow
  */
 const DEFAULT_HOOKS = {
   postToolUse: [
     {
       matcher: {
         toolName: "Write|Edit",
-        path: "plans/**/*"
+        path: "plans/**/*.md"     // Only trigger on .md files in plans/
+      },
+      command: "bash .claude/scripts/safe-graph-update.sh $PATH",
+      // Retry configuration (Claude Code built-in support)
+      retries: {
+        maxAttempts: 3,           // Max 3 attempts total
+        backoff: "exponential",    // Wait longer between retries
+        failureAction: "warn"      // Show warning but don't block
       },
-      command: "python3 scripts/graph.py --check-path $PATH || true"
+      timeout: 5000  // 5 second timeout per attempt
     }
   ]
 };
@@ -93,8 +105,24 @@ export async function setupHooks(projectPath, options = {}) {
 
   const claudePath = path.join(projectPath, '.claude');
   const hooksPath = path.join(claudePath, 'hooks.json');
+  const claudeScriptsPath = path.join(claudePath, 'scripts');
 
   await fs.ensureDir(claudePath);
+  await fs.ensureDir(claudeScriptsPath);
+
+  // Copy safe-graph-update.sh wrapper script to .claude/scripts/
+  const wrapperSource = path.join(TEMPLATES_PATH, 'scripts', 'safe-graph-update.sh');
+  const wrapperDest = path.join(claudeScriptsPath, 'safe-graph-update.sh');
+
+  if (await fs.pathExists(wrapperSource)) {
+    await fs.copy(wrapperSource, wrapperDest);
+    // Make executable
+    try {
+      await fs.chmod(wrapperDest, 0o755);
+    } catch (e) {
+      // chmod might fail on Windows, that's ok
+    }
+  }
 
   let hooks = DEFAULT_HOOKS;
 
@@ -108,8 +136,23 @@ export async function setupHooks(projectPath, options = {}) {
     }
   }
 
+  // Update command to use safe wrapper if it exists
+  if (hooks.postToolUse && hooks.postToolUse[0]) {
+    if (await fs.pathExists(wrapperDest)) {
+      hooks.postToolUse[0].command = "bash .claude/scripts/safe-graph-update.sh $PATH";
+    }
+  }
+
   await fs.writeJson(hooksPath, hooks, { spaces: 2 });
 
+  // Copy hooks guide documentation
+  const hooksGuideSource = path.join(TEMPLATES_PATH, 'hooks-guide.md');
+  const hooksGuideDest = path.join(claudePath, 'hooks-guide.md');
+
+  if (await fs.pathExists(hooksGuideSource)) {
+    await fs.copy(hooksGuideSource, hooksGuideDest);
+  }
+
   return { path: hooksPath, hooks };
 }
 
@@ -218,8 +261,16 @@ export async function updateGitignore(projectPath) {
 
   const entriesToAdd = [
     '',
-    '# Claude Code',
+    '# Claude Code - Settings and local configuration',
     '.claude/settings.local.json',
+    '',
+    '# Claude Code - Installed skills, knowledge, and scripts',
+    '# These are managed by @codihaus/claude-skills package',
+    '.claude/skills/',
+    '.claude/knowledge/',
+    '.claude/scripts/',
+    '',
+    '# Environment files',
     '.env',
     '*.env.local',
     ''

package/src/utils/deps.js

@@ -39,7 +39,7 @@ function getInstallHint(tool, osType) {
   const hints = {
     node: {
       macos: 'brew install node  OR  https://nodejs.org/',
-      debian: 'sudo apt install nodejs npm  OR  https://nodejs.org/',
+      debian: 'sudo apt update && sudo apt install nodejs npm  OR  https://nodejs.org/',
       redhat: 'sudo dnf install nodejs npm  OR  https://nodejs.org/',
       arch: 'sudo pacman -S nodejs npm',
       linux: 'https://nodejs.org/ (use official installer)',
@@ -47,7 +47,7 @@ function getInstallHint(tool, osType) {
     },
     git: {
       macos: 'xcode-select --install  OR  brew install git',
-      debian: 'sudo apt install git',
+      debian: 'sudo apt update && sudo apt install git',
       redhat: 'sudo dnf install git',
       arch: 'sudo pacman -S git',
       linux: 'sudo apt install git  OR  sudo dnf install git',
@@ -55,19 +55,19 @@ function getInstallHint(tool, osType) {
     },
     python3: {
       macos: 'brew install python3  OR  https://python.org/',
-      debian: 'sudo apt install python3 python3-pip',
+      debian: 'sudo apt update && sudo apt install python3 python3-pip',
       redhat: 'sudo dnf install python3 python3-pip',
       arch: 'sudo pacman -S python python-pip',
-      linux: 'sudo apt install python3 python3-pip',
+      linux: 'sudo apt install python3 python3-pip  OR  sudo dnf install python3 python3-pip',
       unknown: 'https://python.org/'
     },
     pip3: {
-      macos: 'python3 -m ensurepip  OR  brew install python3',
-      debian: 'sudo apt install python3-pip',
+      macos: 'python3 -m ensurepip --upgrade  OR  brew install python3',
+      debian: 'sudo apt update && sudo apt install python3-pip',
       redhat: 'sudo dnf install python3-pip',
       arch: 'sudo pacman -S python-pip',
-      linux: 'sudo apt install python3-pip',
-      unknown: 'python3 -m ensurepip'
+      linux: 'sudo apt install python3-pip  OR  python3 -m ensurepip --upgrade',
+      unknown: 'python3 -m ensurepip --upgrade'
     },
     jq: {
       macos: 'brew install jq',
@@ -236,6 +236,7 @@ export const PROJECT_DEPS = {
   forTesting: [
     {
       name: '@playwright/test',
+      type: 'npm',
       purpose: 'UI testing with /dev-test',
       usedBy: ['/dev-test', '/dev-coding-frontend']
     }
@@ -243,6 +244,7 @@ export const PROJECT_DEPS = {
   optional: [
     {
       name: '@mermaid-js/mermaid-cli',
+      type: 'npm',
       purpose: 'Diagram rendering (optional)',
       usedBy: ['/utils/diagram'],
       global: true
@@ -539,9 +541,18 @@ export async function installPythonDeps(packages) {
   for (const pkg of packages) {
     try {
       console.log(`  Installing ${pkg.name}...`);
-      execSync(pkg.installCmd, { stdio: 'inherit' });
+
+      // Try without sudo first (user install)
+      try {
+        execSync(`pip3 install --user ${pkg.name}`, { stdio: 'inherit' });
+      } catch (userError) {
+        // If user install fails, try with sudo (system-wide)
+        console.log(chalk.yellow(`  User install failed, trying with sudo...`));
+        execSync(`sudo pip3 install ${pkg.name}`, { stdio: 'inherit' });
+      }
     } catch (e) {
       console.log(chalk.red(`  Failed to install ${pkg.name}`));
+      console.log(chalk.gray(`  Try manually: pip3 install --user ${pkg.name}`));
       return false;
     }
   }
@@ -549,6 +560,150 @@ export async function installPythonDeps(packages) {
   return true;
 }
 
+/**
+ * Install missing optional tools
+ */
+export async function installOptionalTools(tools, osType) {
+  if (tools.length === 0) return true;
+
+  console.log(chalk.cyan('\nInstalling optional tools...\n'));
+
+  const installCommands = {
+    gh: {
+      macos: 'brew install gh',
+      debian: 'curl -fsSL https://cli.github.com/packages/githubcli-archive-keyring.gpg | sudo dd of=/usr/share/keyrings/githubcli-archive-keyring.gpg && sudo chmod go+r /usr/share/keyrings/githubcli-archive-keyring.gpg && echo "deb [arch=$(dpkg --print-architecture) signed-by=/usr/share/keyrings/githubcli-archive-keyring.gpg] https://cli.github.com/packages stable main" | sudo tee /etc/apt/sources.list.d/github-cli.list > /dev/null && sudo apt update && sudo apt install gh -y',
+      redhat: 'sudo dnf install gh -y',
+      arch: 'sudo pacman -S github-cli --noconfirm',
+      fallback: 'npm install -g gh'
+    },
+    mmdc: {
+      all: 'npm install -g @mermaid-js/mermaid-cli'
+    },
+    tree: {
+      macos: 'brew install tree',
+      debian: 'sudo apt install tree -y',
+      redhat: 'sudo dnf install tree -y',
+      arch: 'sudo pacman -S tree --noconfirm'
+    },
+    scc: {
+      macos: 'brew install scc',
+      debian: 'go install github.com/boyter/scc/v3@latest',
+      redhat: 'go install github.com/boyter/scc/v3@latest',
+      arch: 'yay -S scc --noconfirm || go install github.com/boyter/scc/v3@latest',
+      fallback: 'go install github.com/boyter/scc/v3@latest'
+    },
+    rg: {
+      macos: 'brew install ripgrep',
+      debian: 'sudo apt install ripgrep -y',
+      redhat: 'sudo dnf install ripgrep -y',
+      arch: 'sudo pacman -S ripgrep --noconfirm'
+    }
+  };
+
+  let successCount = 0;
+  let failCount = 0;
+
+  for (const tool of tools) {
+    const commands = installCommands[tool.name];
+    if (!commands) {
+      console.log(chalk.gray(`  ○ ${tool.name} - no auto-install available`));
+      console.log(chalk.gray(`    → ${tool.installHint}\n`));
+      continue;
+    }
+
+    let command = commands.all || commands[osType] || commands.fallback;
+
+    if (!command) {
+      console.log(chalk.gray(`  ○ ${tool.name} - no auto-install available for ${osType}`));
+      console.log(chalk.gray(`    → ${tool.installHint}\n`));
+      continue;
+    }
+
+    console.log(`  Installing ${chalk.cyan(tool.name)}...`);
+
+    try {
+      execSync(command, {
+        stdio: ['pipe', 'pipe', 'pipe'],
+        encoding: 'utf-8'
+      });
+      console.log(chalk.green(`  ✓ ${tool.name} installed successfully\n`));
+      successCount++;
+    } catch (e) {
+      // Try fallback if available
+      if (commands.fallback && command !== commands.fallback) {
+        console.log(chalk.yellow(`  Primary method failed, trying fallback...`));
+        try {
+          execSync(commands.fallback, {
+            stdio: ['pipe', 'pipe', 'pipe'],
+            encoding: 'utf-8'
+          });
+          console.log(chalk.green(`  ✓ ${tool.name} installed successfully\n`));
+          successCount++;
+          continue;
+        } catch (fallbackError) {
+          // Fallback also failed
+        }
+      }
+
+      console.log(chalk.red(`  ✗ Failed to install ${tool.name}`));
+      console.log(chalk.gray(`    Try manually: ${tool.installHint}\n`));
+      failCount++;
+    }
+  }
+
+  if (successCount > 0) {
+    console.log(chalk.green(`\n✓ Installed ${successCount} optional tools`));
+  }
+  if (failCount > 0) {
+    console.log(chalk.yellow(`⚠ Failed to install ${failCount} optional tools`));
+  }
+
+  return failCount === 0;
+}
+
+/**
+ * Install project dependencies with package manager detection
+ */
+export async function installProjectDepsWithPM(projectPath, deps, packageManager) {
+  const npmDeps = deps.filter(d => !d.global && d.type !== 'pip');
+
+  if (npmDeps.length === 0) {
+    return true;
+  }
+
+  console.log(chalk.cyan(`\nInstalling npm dependencies with ${packageManager.name}...`));
+  const names = npmDeps.map(d => d.name).join(' ');
+
+  // Build install command based on package manager
+  let installCmd;
+  switch (packageManager.name) {
+    case 'pnpm':
+      installCmd = `pnpm add -D ${names}`;
+      break;
+    case 'yarn':
+      installCmd = `yarn add -D ${names}`;
+      break;
+    case 'bun':
+      installCmd = `bun add -D ${names}`;
+      break;
+    case 'npm':
+    default:
+      installCmd = `npm install -D ${names}`;
+      break;
+  }
+
+  try {
+    execSync(installCmd, {
+      cwd: projectPath,
+      stdio: 'inherit'
+    });
+    return true;
+  } catch (e) {
+    console.log(chalk.red(`Failed to install npm dependencies with ${packageManager.name}`));
+    return false;
+  }
+}
+
 /**
  * Get summary of what's missing
  */

package/src/utils/skills.js

@@ -198,6 +198,22 @@ export async function copySkillsToProject(projectPath, skillNames = null) {
       } else {
         // Copy directory
         await fs.copy(skill.path, targetSkillPath);
+
+        // Make scripts within skill folder executable
+        const skillScriptsPath = path.join(targetSkillPath, 'scripts');
+        if (await fs.pathExists(skillScriptsPath)) {
+          const scriptFiles = await fs.readdir(skillScriptsPath);
+          for (const scriptFile of scriptFiles) {
+            const scriptPath = path.join(skillScriptsPath, scriptFile);
+            const stat = await fs.stat(scriptPath);
+            if (stat.isFile()) {
+              const isScript = scriptFile.endsWith('.py') || scriptFile.endsWith('.sh') || scriptFile.endsWith('.js');
+              if (isScript) {
+                await fs.chmod(scriptPath, 0o755);
+              }
+            }
+          }
+        }
       }
 
       copied.push(skill.name);
@@ -326,6 +342,17 @@ export async function copyScriptsToProject(projectPath) {
 
       try {
         await fs.copy(sourcePath, targetItemPath);
+
+        // Make scripts executable (chmod +x)
+        const stat = await fs.stat(targetItemPath);
+        if (stat.isFile()) {
+          // Check if it's a script file
+          const isScript = item.endsWith('.py') || item.endsWith('.sh') || item.endsWith('.js');
+          if (isScript) {
+            await fs.chmod(targetItemPath, 0o755);
+          }
+        }
+
         copied.push(item);
       } catch (e) {
         errors.push({ name: item, error: e.message });

package/templates/HOOK_TRIGGER_TEST.md

@@ -0,0 +1,143 @@
+# Hook Trigger Test Cases
+
+Test cases for `path: "plans/**/*.md"` matcher.
+
+## ✅ WILL Trigger (Correct)
+
+These files SHOULD trigger the docs-graph update hook:
+
+```
+plans/brd/README.md                                    ✓
+plans/brd/context.md                                   ✓
+plans/brd/use-cases/auth/UC-AUTH-001-login.md         ✓
+plans/brd/changes/CR-001-add-sso.md                    ✓
+plans/features/auth/README.md                          ✓
+plans/features/auth/scout.md                           ✓
+plans/features/auth/specs/README.md                    ✓
+plans/features/auth/specs/UC-AUTH-001/README.md        ✓
+plans/scout/README.md                                  ✓
+plans/scout/structure.md                               ✓
+plans/scout/stack.md                                   ✓
+plans/docs-graph.md                                    ✓
+```
+
+## ❌ Will NOT Trigger (Correct - Performance Optimization)
+
+These files should NOT trigger the hook (saves resources):
+
+```
+plans/features/auth/questionnaire-2024-01-20.xlsx     ✗ (Excel file)
+plans/scout/screenshots/home.png                      ✗ (Image file)
+plans/scout/screenshots/dashboard.png                 ✗ (Image file)
+plans/docs-graph.json                                 ✗ (JSON file, processed separately)
+plans/features/billing/architecture.json              ✗ (JSON file)
+plans/.gitkeep                                        ✗ (No extension)
+plans/brd/references.txt                              ✗ (Text file)
+```
+
+## Pattern Explanation
+
+**Pattern:** `plans/**/*.md`
+
+- `plans/` - Must be in plans directory
+- `**/` - Can be at any depth (0 or more subdirectories)
+- `*.md` - Must end with .md extension
+
+**Double Protection:**
+
+1. **Hook matcher** (Claude Code level):
+   ```json
+   {
+     "matcher": {
+       "toolName": "Write|Edit",
+       "path": "plans/**/*.md"
+     }
+   }
+   ```
+
+2. **Script validation** (Bash level):
+   ```bash
+   if [[ ! "$FILE_PATH" =~ ^plans/.*\.md$ ]]; then
+     exit 0
+   fi
+   ```
+
+## Testing
+
+To test if a file will trigger the hook:
+
+```bash
+# Test pattern matching
+echo "plans/brd/README.md" | grep -E '^plans/.*\.md$'
+# Output: plans/brd/README.md ← Matches!
+
+echo "plans/scout/screenshots/home.png" | grep -E '^plans/.*\.md$'
+# No output ← Doesn't match
+```
+
+## Performance Impact
+
+**Before** (with `plans/**/*`):
+- 100 files changed in plans/
+- Hook runs 100 times
+- Includes: 70 .md, 20 .png, 5 .xlsx, 5 .json
+- Wastes 30% of hook runs
+
+**After** (with `plans/**/*.md`):
+- 100 files changed in plans/
+- Hook runs 70 times
+- Includes: 70 .md only
+- Saves 30% of hook runs
+
+## Common Gotchas
+
+❌ **Don't match root .md files:**
+```json
+{
+  "matcher": {
+    "path": "*.md"  // ← Bad: matches README.md in root
+  }
+}
+```
+
+❌ **Don't match all .md everywhere:**
+```json
+{
+  "matcher": {
+    "path": "**/*.md"  // ← Bad: matches node_modules/**/*.md
+  }
+}
+```
+
+✅ **Do scope to specific directories:**
+```json
+{
+  "matcher": {
+    "path": "plans/**/*.md"  // ← Good: only plans/
+  }
+}
+```
+
+## Verification After Init
+
+After running `npx @codihaus/claude-skills init`, verify:
+
+```bash
+# Check hook configuration
+cat .claude/hooks.json | jq '.postToolUse[0].matcher.path'
+# Should output: "plans/**/*.md"
+
+cat .claude/hooks.json | jq '.postToolUse[0].command'
+# Should output: "bash .claude/scripts/safe-graph-update.sh $PATH"
+
+# Test the safe wrapper script
+bash .claude/scripts/safe-graph-update.sh plans/brd/README.md
+# Should run graph.py
+
+bash .claude/scripts/safe-graph-update.sh plans/screenshot.png
+# Should exit early (not run graph.py)
+
+# Check that script exists in .claude/scripts/
+ls -la .claude/scripts/safe-graph-update.sh
+# Should show the file with executable permissions
+```