@sienklogic/plan-build-run 2.0.0 → 2.0.1

package/plugins/pbr/scripts/validate-plugin-structure.js

@@ -1,172 +1,183 @@
-#!/usr/bin/env node
-
-/**
- * Validates the Plan-Build-Run plugin structure:
- * - Every skill directory has SKILL.md
- * - Every agent file has valid YAML frontmatter (name, description)
- * - hooks.json references existing scripts
- * - No broken relative links in markdown files
- */
-
-const fs = require('fs');
-const path = require('path');
-
-const ROOT = path.resolve(__dirname, '..');
-let errors = 0;
-let warnings = 0;
-
-function error(msg) {
-  console.error(`ERROR: ${msg}`);
-  errors++;
-}
-
-function warn(msg) {
-  console.warn(`WARN: ${msg}`);
-  warnings++;
-}
-
-function info(msg) {
-  console.log(`OK: ${msg}`);
-}
-
-// 1. Check plugin.json exists
-const pluginJsonPath = path.join(ROOT, '.claude-plugin', 'plugin.json');
-if (!fs.existsSync(pluginJsonPath)) {
-  error('.claude-plugin/plugin.json missing');
-} else {
-  try {
-    const plugin = JSON.parse(fs.readFileSync(pluginJsonPath, 'utf8'));
-    if (!plugin.name) error('plugin.json missing "name" field');
-    if (!plugin.version) error('plugin.json missing "version" field');
-    if (!plugin.description) error('plugin.json missing "description" field');
-    info(`Plugin: ${plugin.name} v${plugin.version}`);
-  } catch (e) {
-    error(`plugin.json is not valid JSON: ${e.message}`);
-  }
-}
-
-// 2. Check every skill directory has SKILL.md
-const skillsDir = path.join(ROOT, 'skills');
-if (fs.existsSync(skillsDir)) {
-  const skillDirs = fs.readdirSync(skillsDir, { withFileTypes: true })
-    .filter(d => d.isDirectory() && d.name !== 'shared');
-
-  for (const dir of skillDirs) {
-    const skillMd = path.join(skillsDir, dir.name, 'SKILL.md');
-    if (!fs.existsSync(skillMd)) {
-      error(`skills/${dir.name}/ missing SKILL.md`);
-    } else {
-      const content = fs.readFileSync(skillMd, 'utf8');
-      if (!content.startsWith('---')) {
-        error(`skills/${dir.name}/SKILL.md missing YAML frontmatter`);
-      } else {
-        const frontmatter = content.split('---')[1];
-        if (!frontmatter.includes('name:')) {
-          error(`skills/${dir.name}/SKILL.md frontmatter missing "name" field`);
-        }
-        if (!frontmatter.includes('description:')) {
-          error(`skills/${dir.name}/SKILL.md frontmatter missing "description" field`);
-        }
-      }
-      // Check: skills with Task in allowed-tools must have Context Budget section
-      const frontmatterBlock = content.split('---')[1] || '';
-      const hasTaskTool = /allowed-tools:.*Task/.test(frontmatterBlock);
-      if (hasTaskTool && !content.includes('## Context Budget')) {
-        warn(`skills/${dir.name}/SKILL.md has Task in allowed-tools but no "## Context Budget" section`);
-      }
-
-      info(`Skill: /pbr:${dir.name}`);
-    }
-  }
-} else {
-  error('skills/ directory missing');
-}
-
-// 3. Check every agent file has valid frontmatter
-const agentsDir = path.join(ROOT, 'agents');
-if (fs.existsSync(agentsDir)) {
-  const agentFiles = fs.readdirSync(agentsDir)
-    .filter(f => f.endsWith('.md'));
-
-  for (const file of agentFiles) {
-    const content = fs.readFileSync(path.join(agentsDir, file), 'utf8');
-    if (!content.startsWith('---')) {
-      error(`agents/${file} missing YAML frontmatter`);
-    } else {
-      const frontmatter = content.split('---')[1];
-      if (!frontmatter.includes('name:')) {
-        error(`agents/${file} frontmatter missing "name" field`);
-      }
-      if (!frontmatter.includes('description:')) {
-        error(`agents/${file} frontmatter missing "description" field`);
-      }
-      const nameMatch = frontmatter.match(/name:\s*(.+)/);
-      info(`Agent: ${nameMatch ? nameMatch[1].trim() : file}`);
-    }
-  }
-} else {
-  error('agents/ directory missing');
-}
-
-// 4. Check context files have valid structure
-const contextsDir = path.join(ROOT, 'contexts');
-if (fs.existsSync(contextsDir)) {
-  const contextFiles = fs.readdirSync(contextsDir)
-    .filter(f => f.endsWith('.md'));
-
-  for (const file of contextFiles) {
-    const content = fs.readFileSync(path.join(contextsDir, file), 'utf8');
-    if (!content.startsWith('#')) {
-      warn(`contexts/${file} should start with a heading`);
-    }
-    const name = file.replace('.md', '');
-    info(`Context: ${name}`);
-  }
-} else {
-  warn('contexts/ directory not found (contexts are optional)');
-}
-
-// 5. Check hooks.json references existing scripts
-const hooksJsonPath = path.join(ROOT, 'hooks', 'hooks.json');
-if (fs.existsSync(hooksJsonPath)) {
-  try {
-    const hooksFile = JSON.parse(fs.readFileSync(hooksJsonPath, 'utf8'));
-
-    // Plugin hooks format: { hooks: { EventName: [ { matcher?, hooks: [ { type, command } ] } ] } }
-    const hooksObj = hooksFile.hooks || {};
-    for (const eventName of Object.keys(hooksObj)) {
-      const matcherGroups = hooksObj[eventName];
-      if (!Array.isArray(matcherGroups)) continue;
-      for (const group of matcherGroups) {
-        const handlers = group.hooks || [];
-        for (const handler of handlers) {
-          if (handler.command) {
-            const cmd = handler.command.replace(/\$\{CLAUDE_PLUGIN_ROOT\}/g, ROOT);
-            const parts = cmd.split(' ');
-            const scriptPart = parts.find(p => p.endsWith('.js'));
-            if (scriptPart) {
-              const scriptPath = scriptPart.replace(/\$\{CLAUDE_PLUGIN_ROOT\}/g, ROOT);
-              const resolvedPath = path.isAbsolute(scriptPath) ? scriptPath : path.join(ROOT, scriptPath);
-              if (!fs.existsSync(resolvedPath)) {
-                error(`hooks.json references missing script: ${scriptPart}`);
-              }
-            }
-          }
-        }
-      }
-    }
-    info('hooks.json validated');
-  } catch (e) {
-    error(`hooks.json is not valid JSON: ${e.message}`);
-  }
-} else {
-  warn('hooks/hooks.json not found (hooks are optional)');
-}
-
-// 6. Summary
-console.log('\n---');
-console.log(`Validation complete: ${errors} errors, ${warnings} warnings`);
-
-if (errors > 0) {
-  process.exit(1);
-}
+#!/usr/bin/env node
+
+/**
+ * Validates the Plan-Build-Run plugin structure:
+ * - Every skill directory has SKILL.md
+ * - Every agent file has valid YAML frontmatter (name, description)
+ * - hooks.json references existing scripts
+ * - No broken relative links in markdown files
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const ROOT = path.resolve(__dirname, '..');
+let errors = 0;
+let warnings = 0;
+
+function error(msg) {
+  console.error(`ERROR: ${msg}`);
+  errors++;
+}
+
+function warn(msg) {
+  console.warn(`WARN: ${msg}`);
+  warnings++;
+}
+
+function info(msg) {
+  console.log(`OK: ${msg}`);
+}
+
+// 1. Check plugin.json exists
+const pluginJsonPath = path.join(ROOT, '.claude-plugin', 'plugin.json');
+if (!fs.existsSync(pluginJsonPath)) {
+  error('.claude-plugin/plugin.json missing');
+} else {
+  try {
+    const plugin = JSON.parse(fs.readFileSync(pluginJsonPath, 'utf8'));
+    if (!plugin.name) error('plugin.json missing "name" field');
+    if (!plugin.version) error('plugin.json missing "version" field');
+    if (!plugin.description) error('plugin.json missing "description" field');
+    info(`Plugin: ${plugin.name} v${plugin.version}`);
+  } catch (e) {
+    error(`plugin.json is not valid JSON: ${e.message}`);
+  }
+}
+
+// 2. Check every skill directory has SKILL.md
+const skillsDir = path.join(ROOT, 'skills');
+if (fs.existsSync(skillsDir)) {
+  const skillDirs = fs.readdirSync(skillsDir, { withFileTypes: true })
+    .filter(d => d.isDirectory() && d.name !== 'shared');
+
+  for (const dir of skillDirs) {
+    const skillMd = path.join(skillsDir, dir.name, 'SKILL.md');
+    if (!fs.existsSync(skillMd)) {
+      error(`skills/${dir.name}/ missing SKILL.md`);
+    } else {
+      const content = fs.readFileSync(skillMd, 'utf8');
+      if (!content.startsWith('---')) {
+        error(`skills/${dir.name}/SKILL.md missing YAML frontmatter`);
+      } else {
+        const frontmatter = content.split('---')[1];
+        if (!frontmatter.includes('name:')) {
+          error(`skills/${dir.name}/SKILL.md frontmatter missing "name" field`);
+        }
+        if (!frontmatter.includes('description:')) {
+          error(`skills/${dir.name}/SKILL.md frontmatter missing "description" field`);
+        }
+      }
+      // Check: skills with Task in allowed-tools must have Context Budget section
+      const frontmatterBlock = content.split('---')[1] || '';
+      const hasTaskTool = /allowed-tools:.*Task/.test(frontmatterBlock);
+      if (hasTaskTool && !content.includes('## Context Budget')) {
+        warn(`skills/${dir.name}/SKILL.md has Task in allowed-tools but no "## Context Budget" section`);
+      }
+
+      info(`Skill: /pbr:${dir.name}`);
+    }
+  }
+} else {
+  error('skills/ directory missing');
+}
+
+// 3. Check every agent file has valid frontmatter
+const agentsDir = path.join(ROOT, 'agents');
+if (fs.existsSync(agentsDir)) {
+  const agentFiles = fs.readdirSync(agentsDir)
+    .filter(f => f.endsWith('.md'));
+
+  for (const file of agentFiles) {
+    const content = fs.readFileSync(path.join(agentsDir, file), 'utf8');
+    if (!content.startsWith('---')) {
+      error(`agents/${file} missing YAML frontmatter`);
+    } else {
+      const frontmatter = content.split('---')[1];
+      if (!frontmatter.includes('name:')) {
+        error(`agents/${file} frontmatter missing "name" field`);
+      }
+      if (!frontmatter.includes('description:')) {
+        error(`agents/${file} frontmatter missing "description" field`);
+      }
+      const nameMatch = frontmatter.match(/name:\s*(.+)/);
+      info(`Agent: ${nameMatch ? nameMatch[1].trim() : file}`);
+    }
+  }
+} else {
+  error('agents/ directory missing');
+}
+
+// 4. Check context files have valid structure
+const contextsDir = path.join(ROOT, 'contexts');
+if (fs.existsSync(contextsDir)) {
+  const contextFiles = fs.readdirSync(contextsDir)
+    .filter(f => f.endsWith('.md'));
+
+  for (const file of contextFiles) {
+    const content = fs.readFileSync(path.join(contextsDir, file), 'utf8');
+    if (!content.startsWith('#')) {
+      warn(`contexts/${file} should start with a heading`);
+    }
+    const name = file.replace('.md', '');
+    info(`Context: ${name}`);
+  }
+} else {
+  warn('contexts/ directory not found (contexts are optional)');
+}
+
+// 5. Check hooks.json references existing scripts
+const hooksJsonPath = path.join(ROOT, 'hooks', 'hooks.json');
+if (fs.existsSync(hooksJsonPath)) {
+  try {
+    const hooksFile = JSON.parse(fs.readFileSync(hooksJsonPath, 'utf8'));
+
+    // Plugin hooks format: { hooks: { EventName: [ { matcher?, hooks: [ { type, command } ] } ] } }
+    const hooksObj = hooksFile.hooks || {};
+    for (const eventName of Object.keys(hooksObj)) {
+      const matcherGroups = hooksObj[eventName];
+      if (!Array.isArray(matcherGroups)) continue;
+      for (const group of matcherGroups) {
+        const handlers = group.hooks || [];
+        for (const handler of handlers) {
+          if (handler.command) {
+            const cmd = handler.command.replace(/\$\{CLAUDE_PLUGIN_ROOT\}/g, ROOT);
+            // Handle run-hook.js bootstrap pattern: command ends with "run-hook.js\" scriptName.js"
+            const runHookMatch = cmd.match(/run-hook\.js[^"]*\)?\)?"?\s+(\S+\.js)/);
+            if (runHookMatch) {
+              // Script is dispatched via run-hook.js — look in scripts/ dir
+              const scriptName = runHookMatch[1];
+              const resolvedPath = path.join(ROOT, 'scripts', scriptName);
+              if (!fs.existsSync(resolvedPath)) {
+                error(`hooks.json references missing script: ${scriptName}`);
+              }
+            } else {
+              const parts = cmd.split(' ');
+              const scriptPart = parts.find(p => p.endsWith('.js'));
+              if (scriptPart) {
+                const scriptPath = scriptPart.replace(/\$\{CLAUDE_PLUGIN_ROOT\}/g, ROOT);
+                const resolvedPath = path.isAbsolute(scriptPath) ? scriptPath : path.join(ROOT, scriptPath);
+                if (!fs.existsSync(resolvedPath)) {
+                  error(`hooks.json references missing script: ${scriptPart}`);
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+    info('hooks.json validated');
+  } catch (e) {
+    error(`hooks.json is not valid JSON: ${e.message}`);
+  }
+} else {
+  warn('hooks/hooks.json not found (hooks are optional)');
+}
+
+// 6. Summary
+console.log('\n---');
+console.log(`Validation complete: ${errors} errors, ${warnings} warnings`);
+
+if (errors > 0) {
+  process.exit(1);
+}

package/plugins/pbr/scripts/validate-task.js

@@ -0,0 +1,106 @@
+#!/usr/bin/env node
+
+/**
+ * PreToolUse hook: Validates Task() calls before execution.
+ *
+ * Advisory checks (exit 0 always, logs warnings):
+ *   - description exists and is non-empty
+ *   - description is reasonably short (<=100 chars)
+ *   - subagent_type is a known pbr: agent type when applicable
+ *
+ * Exit codes:
+ *   0 = always (advisory only, never blocks)
+ */
+
+const { logHook } = require('./hook-logger');
+
+const KNOWN_AGENTS = [
+  'researcher',
+  'planner',
+  'plan-checker',
+  'executor',
+  'verifier',
+  'integration-checker',
+  'debugger',
+  'codebase-mapper',
+  'synthesizer',
+  'general'
+];
+
+const MAX_DESCRIPTION_LENGTH = 100;
+
+/**
+ * Check a parsed hook data object for Task() validation issues.
+ * Returns an array of warning strings (empty if all good).
+ */
+function checkTask(data) {
+  const warnings = [];
+  const toolInput = data.tool_input || {};
+
+  const description = toolInput.description;
+  const subagentType = toolInput.subagent_type;
+
+  // Check description exists and is non-empty
+  if (!description || (typeof description === 'string' && !description.trim())) {
+    warnings.push('Task() called without a description. Descriptions help track agent purpose.');
+  } else if (typeof description === 'string') {
+    // Check description length
+    if (description.length > MAX_DESCRIPTION_LENGTH) {
+      warnings.push(
+        `Task() description is ${description.length} chars (recommended <=100). ` +
+        'Keep descriptions to 3-5 words.'
+      );
+    }
+
+    // If description mentions pbr: patterns but no subagent_type is set
+    if (/\bpbr:/.test(description) && !subagentType) {
+      warnings.push(
+        'Task() description contains "pbr:" but no subagent_type is set. ' +
+        'Use subagent_type: "pbr:{name}" for automatic agent loading.'
+      );
+    }
+  }
+
+  // Validate subagent_type if it starts with pbr:
+  if (typeof subagentType === 'string' && subagentType.startsWith('pbr:')) {
+    const agentName = subagentType.slice(4);
+    if (!KNOWN_AGENTS.includes(agentName)) {
+      warnings.push(
+        `Unknown pbr agent type: "${subagentType}". ` +
+        `Known types: ${KNOWN_AGENTS.map(a => 'pbr:' + a).join(', ')}`
+      );
+    }
+  }
+
+  return warnings;
+}
+
+function main() {
+  let input = '';
+
+  process.stdin.setEncoding('utf8');
+  process.stdin.on('data', (chunk) => { input += chunk; });
+  process.stdin.on('end', () => {
+    try {
+      const data = JSON.parse(input);
+      const warnings = checkTask(data);
+
+      if (warnings.length > 0) {
+        for (const warning of warnings) {
+          logHook('validate-task', 'PreToolUse', 'warn', { warning });
+        }
+        process.stdout.write(JSON.stringify({
+          additionalContext: 'Task() validation warnings:\n' + warnings.map(w => '- ' + w).join('\n')
+        }));
+      }
+
+      process.exit(0);
+    } catch (_e) {
+      // Parse error — don't block
+      process.exit(0);
+    }
+  });
+}
+
+module.exports = { checkTask, KNOWN_AGENTS, MAX_DESCRIPTION_LENGTH };
+if (require.main === module) { main(); }