cc-dev-template 0.1.73 → 0.1.75

package/src/skills/creating-sub-agents/scripts/validate-subagent.js

@@ -0,0 +1,336 @@
+#!/usr/bin/env node
+
+/**
+ * validate-subagent.js
+ *
+ * Validates a Claude Code sub-agent definition against best practices.
+ * Returns detailed findings with severity levels.
+ *
+ * Usage: node validate-subagent.js <agent-file-path> [--json]
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const args = process.argv.slice(2);
+const agentPath = args.find(a => !a.startsWith('--'));
+const jsonOutput = args.includes('--json');
+
+if (!agentPath) {
+  console.error('Usage: node validate-subagent.js <agent-file-path> [--json]');
+  process.exit(1);
+}
+
+const resolvedPath = path.resolve(agentPath);
+
+if (!fs.existsSync(resolvedPath)) {
+  console.error(`Error: File not found at ${resolvedPath}`);
+  process.exit(1);
+}
+
+if (!resolvedPath.endsWith('.md')) {
+  console.error(`Error: Sub-agent file must be a .md file`);
+  process.exit(1);
+}
+
+const findings = [];
+
+function addFinding(category, severity, message, line = null, suggestion = null) {
+  findings.push({ category, severity, message, line, suggestion });
+}
+
+function parseFrontmatter(content) {
+  const match = content.match(/^---\n([\s\S]*?)\n---/);
+  if (!match) return { valid: false, data: null, raw: null };
+
+  const raw = match[1];
+  const data = {};
+  const lines = raw.split('\n');
+
+  for (const line of lines) {
+    const colonIndex = line.indexOf(':');
+    if (colonIndex > 0 && !line.startsWith(' ') && !line.startsWith('\t')) {
+      const key = line.slice(0, colonIndex).trim();
+      let value = line.slice(colonIndex + 1).trim();
+
+      if (value === '' || value === '|' || value === '>') continue;
+
+      if ((value.startsWith('"') && value.endsWith('"')) ||
+          (value.startsWith("'") && value.endsWith("'"))) {
+        value = value.slice(1, -1);
+      }
+
+      data[key] = value;
+    }
+  }
+
+  return { valid: true, data, raw };
+}
+
+function getBody(content) {
+  const match = content.match(/^---\n[\s\S]*?\n---\n([\s\S]*)$/);
+  return match ? match[1] : content;
+}
+
+const content = fs.readFileSync(resolvedPath, 'utf-8');
+const frontmatter = parseFrontmatter(content);
+const body = getBody(content);
+const lines = content.split('\n');
+
+// === VALIDATION CHECKS ===
+
+// Check 1: Frontmatter exists
+if (!frontmatter.valid) {
+  addFinding('STRUCTURE', 'error', 'Missing or invalid YAML frontmatter');
+} else {
+  // Check 2: Required fields
+  if (!frontmatter.data.name) {
+    addFinding('STRUCTURE', 'error', 'Missing required field: name');
+  } else {
+    const namePattern = /^[a-z0-9]+(-[a-z0-9]+)*$/;
+    if (!namePattern.test(frontmatter.data.name)) {
+      addFinding('STRUCTURE', 'error',
+        `Invalid name format: "${frontmatter.data.name}" - must be hyphen-case`);
+    }
+
+    if (frontmatter.data.name.length > 64) {
+      addFinding('STRUCTURE', 'error',
+        `Name exceeds 64 characters (${frontmatter.data.name.length})`);
+    }
+
+    // Check name matches filename
+    const fileName = path.basename(resolvedPath, '.md');
+    if (frontmatter.data.name !== fileName) {
+      addFinding('STRUCTURE', 'warning',
+        `Name "${frontmatter.data.name}" doesn't match filename "${fileName}.md"`);
+    }
+  }
+
+  if (!frontmatter.data.description) {
+    addFinding('STRUCTURE', 'error', 'Missing required field: description');
+  } else {
+    if (frontmatter.data.description.length < 10) {
+      addFinding('DESCRIPTION', 'warning',
+        'Description is very short — may not provide enough context for delegation');
+    }
+
+    const desc = frontmatter.data.description.toLowerCase();
+    if (desc.startsWith('a ') || desc.startsWith('an ') || desc.startsWith('the ')) {
+      addFinding('DESCRIPTION', 'info',
+        'Description could be more actionable — consider starting with a verb or role');
+    }
+  }
+
+  // Check model validity
+  if (frontmatter.data.model) {
+    const validModels = ['haiku', 'sonnet', 'opus', 'inherit'];
+    if (!validModels.includes(frontmatter.data.model)) {
+      addFinding('STRUCTURE', 'warning',
+        `Model "${frontmatter.data.model}" may not be valid. Expected: ${validModels.join(', ')}`);
+    }
+  }
+
+  // Check permission mode validity
+  if (frontmatter.data.permissionMode) {
+    const validModes = ['default', 'acceptEdits', 'dontAsk', 'delegate', 'bypassPermissions', 'plan'];
+    if (!validModes.includes(frontmatter.data.permissionMode)) {
+      addFinding('STRUCTURE', 'error',
+        `Invalid permissionMode: "${frontmatter.data.permissionMode}". Valid: ${validModes.join(', ')}`);
+    }
+
+    if (frontmatter.data.permissionMode === 'bypassPermissions') {
+      addFinding('SECURITY', 'warning',
+        'Using bypassPermissions — ensure tools are restricted to limit risk');
+    }
+  }
+
+  // Check for both tools and disallowedTools
+  if (frontmatter.data.tools && frontmatter.data.disallowedTools) {
+    addFinding('STRUCTURE', 'warning',
+      'Both tools and disallowedTools are set — use one approach, not both');
+  }
+
+  // Check for XML in frontmatter
+  if (frontmatter.raw && /[<>]/.test(frontmatter.raw)) {
+    addFinding('STRUCTURE', 'error',
+      'Frontmatter contains XML angle brackets (< >) — move XML tags to the body');
+  }
+}
+
+// Check 3: Body quality
+const wordCount = body.split(/\s+/).filter(w => w.length > 0).length;
+const bodyLineCount = body.split('\n').length;
+
+if (wordCount < 10) {
+  addFinding('CONTENT', 'error',
+    'System prompt body is nearly empty — sub-agent needs instructions');
+}
+
+if (bodyLineCount > 200) {
+  addFinding('SIZE', 'warning',
+    `System prompt is ${bodyLineCount} lines — consider splitting scope or using skills preloading`,
+    null,
+    'Move domain knowledge into skills and preload with the skills field');
+}
+
+// Check 4: Output format defined
+const hasOutputSection = /##?\s*(output|return|result|format|response)/i.test(body);
+const hasOutputGuidance = /(return|provide|report|output|summarize)\s+(only|a |the |concise|structured)/i.test(body);
+
+if (!hasOutputSection && !hasOutputGuidance) {
+  addFinding('CONTENT', 'warning',
+    'No output format guidance found — sub-agent may return verbose or unstructured results',
+    null,
+    'Add an "## Output" section defining what the sub-agent should return');
+}
+
+// Check 5: Role statement
+const firstNonEmpty = body.split('\n').find(l => l.trim().length > 0);
+if (firstNonEmpty && !/(you are|as a|expert|specialist|senior|responsible for)/i.test(firstNonEmpty)) {
+  addFinding('CONTENT', 'info',
+    'Consider starting with a role statement (e.g., "You are a senior code reviewer...")');
+}
+
+// Check 6: Second person violations
+const secondPersonPatterns = [
+  /\byou should\b/gi,
+  /\byou can\b/gi,
+  /\byou need\b/gi,
+  /\byou might\b/gi
+];
+
+let secondPersonCount = 0;
+const secondPersonExamples = [];
+
+for (let i = 0; i < lines.length; i++) {
+  const line = lines[i];
+  if (i < 3) continue;
+
+  for (const pattern of secondPersonPatterns) {
+    const matches = line.match(pattern);
+    if (matches) {
+      secondPersonCount += matches.length;
+      if (secondPersonExamples.length < 3) {
+        secondPersonExamples.push({ line: i + 1, text: line.trim().slice(0, 60) });
+      }
+    }
+  }
+}
+
+if (secondPersonCount > 3) {
+  addFinding('STYLE', 'warning',
+    `Found ${secondPersonCount} instance(s) of "you should/can/need/might" — prefer imperative form`,
+    secondPersonExamples[0]?.line,
+    '"You should check..." becomes "Check..."');
+}
+
+// Check 7: Negative framing
+const negativePatterns = [
+  /\bdon't\b/gi,
+  /\bdo not\b/gi,
+  /\bnever\b/gi,
+  /\bavoid\b/gi
+];
+
+let negativeCount = 0;
+
+for (let i = 0; i < lines.length; i++) {
+  if (i < 3) continue;
+  for (const pattern of negativePatterns) {
+    const matches = lines[i].match(pattern);
+    if (matches) negativeCount += matches.length;
+  }
+}
+
+if (negativeCount > 5) {
+  addFinding('STYLE', 'warning',
+    `Found ${negativeCount} negative framing instances — prefer positive framing`,
+    null,
+    '"Don\'t modify X" becomes "Only modify Y"');
+}
+
+// Check 8: Memory instructions
+if (frontmatter.valid && frontmatter.data.memory) {
+  const hasMemoryInstructions = /memory|MEMORY\.md|agent-memory/i.test(body);
+  if (!hasMemoryInstructions) {
+    addFinding('CONTENT', 'warning',
+      'Memory is enabled but no memory instructions found in system prompt',
+      null,
+      'Add instructions for reading/updating the memory directory');
+  }
+}
+
+// Check 9: Skills existence check
+if (frontmatter.valid && frontmatter.raw && /skills:/i.test(frontmatter.raw)) {
+  addFinding('CONTENT', 'info',
+    'Skills preloading is configured — verify listed skills exist at user or project level');
+}
+
+// === OUTPUT ===
+
+const result = {
+  agent: {
+    path: resolvedPath,
+    name: frontmatter.data?.name || path.basename(resolvedPath, '.md'),
+    wordCount,
+    lineCount: bodyLineCount
+  },
+  findings,
+  summary: {
+    errors: findings.filter(f => f.severity === 'error').length,
+    warnings: findings.filter(f => f.severity === 'warning').length,
+    info: findings.filter(f => f.severity === 'info').length,
+    passed: findings.filter(f => f.severity === 'error').length === 0
+  }
+};
+
+if (jsonOutput) {
+  console.log(JSON.stringify(result, null, 2));
+} else {
+  console.log(`\n=== Sub-Agent Validation: ${result.agent.name} ===\n`);
+  console.log(`Path: ${result.agent.path}`);
+  console.log(`Words: ${result.agent.wordCount}`);
+  console.log(`Lines: ${result.agent.lineCount}`);
+  console.log();
+
+  if (findings.length === 0) {
+    console.log('All checks passed!\n');
+  } else {
+    const errors = findings.filter(f => f.severity === 'error');
+    const warnings = findings.filter(f => f.severity === 'warning');
+    const infos = findings.filter(f => f.severity === 'info');
+
+    if (errors.length > 0) {
+      console.log('ERRORS:');
+      for (const f of errors) {
+        console.log(`  [${f.category}] ${f.message}`);
+        if (f.line) console.log(`    Line ${f.line}`);
+        if (f.suggestion) console.log(`    Suggestion: ${f.suggestion}`);
+      }
+      console.log();
+    }
+
+    if (warnings.length > 0) {
+      console.log('WARNINGS:');
+      for (const f of warnings) {
+        console.log(`  ! [${f.category}] ${f.message}`);
+        if (f.line) console.log(`    Line ${f.line}`);
+        if (f.suggestion) console.log(`    Suggestion: ${f.suggestion}`);
+      }
+      console.log();
+    }
+
+    if (infos.length > 0) {
+      console.log('INFO:');
+      for (const f of infos) {
+        console.log(`  i [${f.category}] ${f.message}`);
+      }
+      console.log();
+    }
+
+    console.log(`Summary: ${result.summary.errors} error(s), ${result.summary.warnings} warning(s), ${result.summary.info} info(s)`);
+    console.log(`Status: ${result.summary.passed ? 'PASSED' : 'FAILED'}\n`);
+  }
+}
+
+process.exit(result.summary.passed ? 0 : 1);

package/src/skills/creating-sub-agents/templates/basic-subagent.md

@@ -0,0 +1,21 @@
+---
+name: {{AGENT_NAME}}
+description: {{What it does and when Claude should delegate to it}}
+tools: {{Tool list, e.g., Read, Grep, Glob, Bash}}
+model: {{haiku|sonnet|opus|inherit}}
+---
+
+You are a {{role description}}.
+
+When invoked:
+1. {{First action}}
+2. {{Second action}}
+3. {{Third action}}
+
+## Guidelines
+
+{{Domain knowledge, conventions, constraints}}
+
+## Output
+
+{{What to return — format, structure, level of detail}}

package/src/skills/creating-sub-agents/templates/domain-specialist.md

@@ -0,0 +1,52 @@
+---
+name: {{AGENT_NAME}}
+description: "Domain specialist for {{domain description}}. Owns and maintains code quality for the {{domain-name}} domain."
+tools: Read, Write, Edit, Grep, Glob, Bash, LSP
+memory: project
+---
+
+You are the **{{domain-name}}** domain specialist on a development team.
+
+<role>
+You are a software engineer who owns the {{domain-name}} domain. You write code, maintain tests, enforce quality, and deeply understand your part of the codebase. You are responsible for the code quality and architectural integrity of your domain.
+</role>
+
+<domain>
+**Name:** {{domain-name}}
+**Description:** {{What this domain covers}}
+**Ownership:** {{Directory paths this agent owns}}
+</domain>
+
+<memory>
+**On startup, read your memory file at `.claude/agent-memory/{{AGENT_NAME}}/MEMORY.md`.**
+This contains accumulated knowledge from previous sessions. Update it when you learn something that would help future sessions.
+
+Memory is tribal knowledge — patterns, gotchas, decisions, integration points. Not documentation of what code does, but how to work effectively in this codebase.
+
+Review and curate your memory. Remove entries that are no longer accurate. Keep it under 100 lines.
+</memory>
+
+<team>
+You are part of a team coordinated by a team lead.
+
+- **Team Lead** (team-lead): Assigns work, coordinates between domains, reviews output
+- **Other domain specialists**: Message them directly when your work affects their domain
+
+Always refer to teammates by name when using SendMessage.
+</team>
+
+<responsibilities>
+1. Deeply understand your domain before making changes
+2. Write high-quality code that follows established patterns
+3. Write and maintain tests for changes
+4. Coordinate with the team lead for cross-domain changes
+5. Update your memory file with tribal knowledge
+6. Mark tasks as completed via TaskUpdate when finished
+7. After completing a task, check TaskList for available work
+</responsibilities>
+
+<boundaries>
+- Only modify files within your domain's ownership zone
+- Coordinate with the team lead for changes outside your domain
+- All user communication goes through the team lead
+</boundaries>

package/src/skills/creating-sub-agents/templates/restricted-subagent.md

@@ -0,0 +1,29 @@
+---
+name: {{AGENT_NAME}}
+description: {{What it does and when Claude should delegate to it}}
+tools: {{Restricted tool list, e.g., Read, Grep, Glob}}
+model: {{haiku|sonnet|opus|inherit}}
+permissionMode: dontAsk
+hooks:
+  PreToolUse:
+    - matcher: "Bash"
+      hooks:
+        - type: command
+          command: "{{./path/to/validation-script.sh}}"
+---
+
+You are a {{role description}} with restricted access.
+
+When invoked:
+1. {{First action}}
+2. {{Second action}}
+3. {{Third action}}
+
+## Constraints
+
+- Only access files within {{scope}}
+- {{Additional restrictions}}
+
+## Output
+
+{{What to return — format, structure, level of detail}}