cc-dev-template 0.1.4 → 0.1.6

package/src/skills/create-agent-skills/scripts/find-skills.js

@@ -0,0 +1,206 @@
+#!/usr/bin/env node
+
+/**
+ * find-skills.js
+ *
+ * Discovers all Claude Code skills at user and project levels.
+ * Returns JSON with skill locations and basic metadata.
+ *
+ * Usage: node find-skills.js [--json] [--verbose]
+ */
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+// Parse arguments
+const args = process.argv.slice(2);
+const jsonOutput = args.includes('--json');
+const verbose = args.includes('--verbose');
+
+// Skill locations to scan
+const locations = [
+  {
+    name: 'user',
+    path: path.join(os.homedir(), '.claude', 'skills'),
+    description: 'User-level skills (~/.claude/skills/)'
+  },
+  {
+    name: 'project',
+    path: path.join(process.cwd(), '.claude', 'skills'),
+    description: 'Project-level skills (.claude/skills/)'
+  },
+  {
+    name: 'source',
+    path: path.join(process.cwd(), 'src', 'skills'),
+    description: 'Source skills (src/skills/)'
+  }
+];
+
+/**
+ * Parse YAML frontmatter from SKILL.md content
+ */
+function parseFrontmatter(content) {
+  const match = content.match(/^---\n([\s\S]*?)\n---/);
+  if (!match) return null;
+
+  const frontmatter = {};
+  const lines = match[1].split('\n');
+
+  for (const line of lines) {
+    const colonIndex = line.indexOf(':');
+    if (colonIndex > 0) {
+      const key = line.slice(0, colonIndex).trim();
+      let value = line.slice(colonIndex + 1).trim();
+
+      // Remove quotes if present
+      if ((value.startsWith('"') && value.endsWith('"')) ||
+          (value.startsWith("'") && value.endsWith("'"))) {
+        value = value.slice(1, -1);
+      }
+
+      frontmatter[key] = value;
+    }
+  }
+
+  return frontmatter;
+}
+
+/**
+ * Get basic stats about a skill
+ */
+function getSkillStats(skillPath) {
+  const skillMdPath = path.join(skillPath, 'SKILL.md');
+
+  if (!fs.existsSync(skillMdPath)) {
+    return null;
+  }
+
+  const content = fs.readFileSync(skillMdPath, 'utf-8');
+  const frontmatter = parseFrontmatter(content);
+
+  // Count words in body (after frontmatter)
+  const bodyMatch = content.match(/^---\n[\s\S]*?\n---\n([\s\S]*)$/);
+  const body = bodyMatch ? bodyMatch[1] : content;
+  const wordCount = body.split(/\s+/).filter(w => w.length > 0).length;
+
+  // Check for subdirectories
+  const hasReferences = fs.existsSync(path.join(skillPath, 'references'));
+  const hasScripts = fs.existsSync(path.join(skillPath, 'scripts'));
+  const hasAssets = fs.existsSync(path.join(skillPath, 'assets'));
+
+  return {
+    name: frontmatter?.name || path.basename(skillPath),
+    description: frontmatter?.description || null,
+    wordCount,
+    hasReferences,
+    hasScripts,
+    hasAssets,
+    frontmatterValid: !!(frontmatter?.name && frontmatter?.description)
+  };
+}
+
+/**
+ * Scan a location for skills
+ */
+function scanLocation(location) {
+  const skills = [];
+
+  if (!fs.existsSync(location.path)) {
+    return skills;
+  }
+
+  const entries = fs.readdirSync(location.path, { withFileTypes: true });
+
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+
+    const skillPath = path.join(location.path, entry.name);
+    const skillMdPath = path.join(skillPath, 'SKILL.md');
+
+    if (fs.existsSync(skillMdPath)) {
+      const stats = getSkillStats(skillPath);
+
+      skills.push({
+        directory: entry.name,
+        path: skillPath,
+        location: location.name,
+        ...stats
+      });
+    }
+  }
+
+  return skills;
+}
+
+// Main execution
+const results = {
+  timestamp: new Date().toISOString(),
+  cwd: process.cwd(),
+  locations: {},
+  skills: [],
+  summary: {
+    total: 0,
+    byLocation: {}
+  }
+};
+
+for (const location of locations) {
+  const skills = scanLocation(location);
+
+  results.locations[location.name] = {
+    path: location.path,
+    exists: fs.existsSync(location.path),
+    count: skills.length
+  };
+
+  results.skills.push(...skills);
+  results.summary.byLocation[location.name] = skills.length;
+}
+
+results.summary.total = results.skills.length;
+
+// Output
+if (jsonOutput) {
+  console.log(JSON.stringify(results, null, 2));
+} else {
+  console.log('\n=== Claude Code Skills Discovery ===\n');
+
+  for (const location of locations) {
+    const info = results.locations[location.name];
+    console.log(`${location.description}`);
+    console.log(`  Path: ${info.path}`);
+    console.log(`  Exists: ${info.exists ? 'Yes' : 'No'}`);
+    console.log(`  Skills found: ${info.count}`);
+    console.log();
+  }
+
+  if (results.skills.length === 0) {
+    console.log('No skills found.\n');
+  } else {
+    console.log('=== Skills ===\n');
+
+    for (const skill of results.skills) {
+      console.log(`[${skill.location}] ${skill.name}`);
+      console.log(`  Path: ${skill.path}`);
+
+      if (verbose) {
+        console.log(`  Words: ${skill.wordCount}`);
+        console.log(`  Valid frontmatter: ${skill.frontmatterValid ? 'Yes' : 'No'}`);
+        console.log(`  Has references/: ${skill.hasReferences ? 'Yes' : 'No'}`);
+        console.log(`  Has scripts/: ${skill.hasScripts ? 'Yes' : 'No'}`);
+
+        if (skill.description) {
+          const truncated = skill.description.length > 80
+            ? skill.description.slice(0, 80) + '...'
+            : skill.description;
+          console.log(`  Description: ${truncated}`);
+        }
+      }
+
+      console.log();
+    }
+
+    console.log(`Total: ${results.summary.total} skill(s)\n`);
+  }
+}

package/src/skills/create-agent-skills/scripts/validate-skill.js

@@ -0,0 +1,386 @@
+#!/usr/bin/env node
+
+/**
+ * validate-skill.js
+ *
+ * Validates a Claude Code skill against best practices.
+ * Returns detailed findings with severity levels.
+ *
+ * Usage: node validate-skill.js <skill-path> [--json] [--fix]
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+// Parse arguments
+const args = process.argv.slice(2);
+const skillPath = args.find(a => !a.startsWith('--'));
+const jsonOutput = args.includes('--json');
+const autoFix = args.includes('--fix');
+
+if (!skillPath) {
+  console.error('Usage: node validate-skill.js <skill-path> [--json] [--fix]');
+  process.exit(1);
+}
+
+// Resolve skill path
+const resolvedPath = path.resolve(skillPath);
+const skillMdPath = path.join(resolvedPath, 'SKILL.md');
+
+if (!fs.existsSync(skillMdPath)) {
+  console.error(`Error: SKILL.md not found at ${skillMdPath}`);
+  process.exit(1);
+}
+
+// Findings storage
+const findings = [];
+
+function addFinding(category, severity, message, line = null, suggestion = null) {
+  findings.push({ category, severity, message, line, suggestion });
+}
+
+/**
+ * Parse YAML frontmatter
+ */
+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) {
+      const key = line.slice(0, colonIndex).trim();
+      let value = line.slice(colonIndex + 1).trim();
+
+      // Handle multi-line values (basic support)
+      if (value === '' || value === '|' || value === '>') {
+        // Skip complex multi-line for now
+        continue;
+      }
+
+      // Remove quotes if present
+      if ((value.startsWith('"') && value.endsWith('"')) ||
+          (value.startsWith("'") && value.endsWith("'"))) {
+        value = value.slice(1, -1);
+      }
+
+      data[key] = value;
+    }
+  }
+
+  return { valid: true, data, raw };
+}
+
+/**
+ * Get body content (after frontmatter)
+ */
+function getBody(content) {
+  const match = content.match(/^---\n[\s\S]*?\n---\n([\s\S]*)$/);
+  return match ? match[1] : content;
+}
+
+// Read skill content
+const content = fs.readFileSync(skillMdPath, '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 {
+    // Check name format (hyphen-case)
+    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 (lowercase letters, numbers, hyphens)`);
+    }
+
+    // Check name matches directory
+    const dirName = path.basename(resolvedPath);
+    if (frontmatter.data.name !== dirName) {
+      addFinding('STRUCTURE', 'warning',
+        `Name "${frontmatter.data.name}" doesn't match directory "${dirName}"`);
+    }
+
+    // Check name length
+    if (frontmatter.data.name.length > 64) {
+      addFinding('STRUCTURE', 'error',
+        `Name exceeds 64 characters (${frontmatter.data.name.length})`);
+    }
+  }
+
+  if (!frontmatter.data.description) {
+    addFinding('STRUCTURE', 'error', 'Missing required field: description');
+  } else {
+    // Check description length
+    if (frontmatter.data.description.length > 1024) {
+      addFinding('DESCRIPTION', 'error',
+        `Description exceeds 1024 characters (${frontmatter.data.description.length})`);
+    }
+
+    // Check for third person
+    const desc = frontmatter.data.description.toLowerCase();
+    if (desc.startsWith('use this') || desc.startsWith('use when')) {
+      addFinding('DESCRIPTION', 'warning',
+        'Description should use third person ("This skill should be used when...") not second person',
+        null,
+        'Start with "This skill should be used when..." or similar third-person phrasing');
+    }
+
+    // Check for trigger phrases (quoted text)
+    const hasQuotedPhrases = /"[^"]+"|'[^']+'/.test(frontmatter.data.description);
+    if (!hasQuotedPhrases) {
+      addFinding('DESCRIPTION', 'warning',
+        'Description lacks quoted trigger phrases',
+        null,
+        'Add specific phrases users might say, e.g., "create a skill", "build a new skill"');
+    }
+
+    // Check if description is too detailed (might prevent activation)
+    if (frontmatter.data.description.length > 500 && !hasQuotedPhrases) {
+      addFinding('DESCRIPTION', 'info',
+        'Long description without trigger phrases may reduce activation reliability');
+    }
+  }
+}
+
+// Check 3: Second person violations
+const secondPersonPatterns = [
+  /\byou should\b/gi,
+  /\byou can\b/gi,
+  /\byou need\b/gi,
+  /\byou might\b/gi,
+  /\byou will\b/gi,
+  /\byou must\b/gi,
+  /\byour\b/gi
+];
+
+let secondPersonCount = 0;
+const secondPersonExamples = [];
+
+for (let i = 0; i < lines.length; i++) {
+  const line = lines[i];
+  // Skip frontmatter
+  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 > 0) {
+  addFinding('STYLE', 'error',
+    `Found ${secondPersonCount} instance(s) of second person language`,
+    secondPersonExamples[0]?.line,
+    'Convert to imperative form: "You should parse" → "Parse"');
+}
+
+// Check 4: Negative framing
+const negativePatterns = [
+  /\bdon't\b/gi,
+  /\bdo not\b/gi,
+  /\bnever\b/gi,
+  /\bavoid\b/gi,
+  /\bshould not\b/gi,
+  /\bshouldn't\b/gi,
+  /\bcan't\b/gi,
+  /\bcannot\b/gi
+];
+
+let negativeCount = 0;
+const negativeExamples = [];
+
+for (let i = 0; i < lines.length; i++) {
+  const line = lines[i];
+  if (i < 3) continue;
+
+  for (const pattern of negativePatterns) {
+    const matches = line.match(pattern);
+    if (matches) {
+      negativeCount += matches.length;
+      if (negativeExamples.length < 3) {
+        negativeExamples.push({ line: i + 1, text: line.trim().slice(0, 60) });
+      }
+    }
+  }
+}
+
+if (negativeCount > 3) {
+  addFinding('STYLE', 'warning',
+    `Found ${negativeCount} instance(s) of negative framing`,
+    negativeExamples[0]?.line,
+    'Use positive framing: "Don\'t do X" → "Do Y instead"');
+}
+
+// Check 5: Body size
+const wordCount = body.split(/\s+/).filter(w => w.length > 0).length;
+const lineCount = body.split('\n').length;
+
+if (wordCount > 5000) {
+  addFinding('SIZE', 'error',
+    `SKILL.md body is ${wordCount} words - strongly exceeds 2,000 word recommendation`,
+    null,
+    'Move detailed content to references/ directory');
+} else if (wordCount > 3500) {
+  addFinding('SIZE', 'warning',
+    `SKILL.md body is ${wordCount} words - exceeds 2,000 word recommendation`,
+    null,
+    'Consider moving detailed content to references/ directory');
+} else if (wordCount > 2000) {
+  addFinding('SIZE', 'info',
+    `SKILL.md body is ${wordCount} words - at upper limit of recommendation`);
+}
+
+// Check 6: Progressive disclosure
+const hasReferences = fs.existsSync(path.join(resolvedPath, 'references'));
+const hasScripts = fs.existsSync(path.join(resolvedPath, 'scripts'));
+
+if (wordCount > 2000 && !hasReferences) {
+  addFinding('DISCLOSURE', 'warning',
+    'Large SKILL.md without references/ directory - not using progressive disclosure',
+    null,
+    'Create references/ and move detailed content there');
+}
+
+// Check 7: Reference integrity
+const referencePaths = body.match(/`references\/[^`]+`|references\/[\w.-]+/g) || [];
+const scriptPaths = body.match(/`scripts\/[^`]+`|scripts\/[\w.-]+/g) || [];
+
+for (const ref of referencePaths) {
+  const cleanPath = ref.replace(/`/g, '');
+  const fullPath = path.join(resolvedPath, cleanPath);
+
+  if (!fs.existsSync(fullPath)) {
+    addFinding('BROKEN', 'error',
+      `Referenced file doesn't exist: ${cleanPath}`);
+  }
+}
+
+for (const ref of scriptPaths) {
+  const cleanPath = ref.replace(/`/g, '');
+  const fullPath = path.join(resolvedPath, cleanPath);
+
+  if (!fs.existsSync(fullPath)) {
+    addFinding('BROKEN', 'error',
+      `Referenced script doesn't exist: ${cleanPath}`);
+  }
+}
+
+// Check 8: Unreferenced resources
+if (hasReferences) {
+  const refDir = path.join(resolvedPath, 'references');
+  const refFiles = fs.readdirSync(refDir);
+
+  for (const file of refFiles) {
+    const isReferenced = body.includes(`references/${file}`) ||
+                         body.includes(`references/${path.basename(file, '.md')}`);
+    if (!isReferenced && file.endsWith('.md')) {
+      addFinding('DISCLOSURE', 'info',
+        `File references/${file} exists but may not be referenced in SKILL.md`);
+    }
+  }
+}
+
+if (hasScripts) {
+  const scriptDir = path.join(resolvedPath, 'scripts');
+  const scriptFiles = fs.readdirSync(scriptDir);
+
+  for (const file of scriptFiles) {
+    const isReferenced = body.includes(`scripts/${file}`);
+    if (!isReferenced) {
+      addFinding('DISCLOSURE', 'info',
+        `File scripts/${file} exists but may not be referenced in SKILL.md`);
+    }
+  }
+}
+
+// === OUTPUT ===
+
+const result = {
+  skill: {
+    path: resolvedPath,
+    name: frontmatter.data?.name || path.basename(resolvedPath),
+    wordCount,
+    lineCount,
+    hasReferences,
+    hasScripts
+  },
+  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=== Skill Validation: ${result.skill.name} ===\n`);
+  console.log(`Path: ${result.skill.path}`);
+  console.log(`Words: ${result.skill.wordCount}`);
+  console.log(`Has references/: ${result.skill.hasReferences ? 'Yes' : 'No'}`);
+  console.log(`Has scripts/: ${result.skill.hasScripts ? 'Yes' : 'No'}`);
+  console.log();
+
+  if (findings.length === 0) {
+    console.log('✓ All checks passed!\n');
+  } else {
+    // Group by severity
+    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`);
+  }
+}
+
+// Exit with error code if validation failed
+process.exit(result.summary.passed ? 0 : 1);

package/src/skills/orchestration/SKILL.md

@@ -23,7 +23,7 @@ Complete each step in order before proceeding to the next.
 Run the plan status script to find existing plans:
 
 ```bash
-node ~/.claude/scripts/plan-status.js
+node ~/.claude/skills/orchestration/scripts/plan-status.js
 ```
 
 This returns a list of plans with their current status (draft, approved, in_progress, completed).

package/src/skills/orchestration/references/planning/draft.md

@@ -94,14 +94,37 @@ relevant_adrs:
   - id: ADR-[XXX]
     title: [title]
     constraint: [What this ADR requires us to do or avoid]
+
+# Submodules affected by this work (for repos with git submodules)
+affected_submodules:
+  - path: [relative/path/to/submodule]
+    reason: [Why this submodule is affected by the plan]
 ```
 
 **Field guidance:**
 
 - **Required**: id, title, type, status, created, problem_statement, goals, success_criteria
-- **Include if relevant**: integration_points, data_models, api_contracts, relevant_adrs
+- **Include if relevant**: integration_points, data_models, api_contracts, relevant_adrs, affected_submodules
 - **Only include fields that were discussed**: The plan reflects the conversation from Phases 1 and 2
 
+**affected_submodules field:**
+
+Include this field when working in repositories with git submodules and the plan's scope touches specific submodules. This enables scope-aware ADR discovery—the adr-agent can filter to only show ADRs that are either global or scoped to the affected submodules.
+
+- `path` (required): Relative path to the submodule, matching what appears in `.gitmodules`
+- `reason` (optional): Brief explanation of why this submodule is affected by the plan
+
+Example:
+```yaml
+affected_submodules:
+  - path: packages/auth
+    reason: Adding new authentication method
+  - path: packages/shared
+    reason: Shared types need updating for new auth flow
+```
+
+When a plan declares affected_submodules, ADRs scoped to those submodules become relevant, while ADRs scoped to unaffected submodules can be filtered out. ADRs with no scope field are always treated as global and remain relevant regardless of which submodules are affected.
+
 **Why no approach or risks?** The plan defines WHAT we're building, not HOW. The approach (phases, task breakdown) gets figured out during decomposition in execution. Risks emerge naturally during exploration or decomposition.
 </step>
 

package/src/skills/orchestration/references/planning/explore.md

@@ -56,10 +56,13 @@ While codebase exploration is happening, also spawn the adr-agent to find archit
 ```
 Spawn adr-agent: "Find ADRs that would be relevant to [summary of requirements].
                   For each relevant ADR, explain why it matters and what
-                  constraints it imposes on this work."
+                  constraints it imposes on this work.
+
+                  If this work affects specific submodules, mention which ones
+                  so the agent can filter ADRs by scope."
 ```
 
-ADRs discovered now will inform the plan you write. Better to know the rules before you design than to discover violations later.
+ADRs discovered now will inform the plan you write. Better to know the rules before you design than to discover violations later. When specific submodules are involved, scope-aware discovery surfaces the most relevant ADRs while filtering out ADRs that only apply elsewhere.
 </step>
 
 <step name="Synthesize Findings">

package/src/skills/orchestration/references/planning/finalize.md

@@ -18,6 +18,7 @@ Complete each step in order before proceeding to the next.
 Spawn the adr-agent to validate the plan. The agent will:
 - Read the plan.yaml
 - Find ALL ADRs that might be relevant (not just the ones declared in the plan)
+- Use the plan's `affected_submodules` field for scope-aware filtering
 - Check compliance for each: COMPLIANT, TENSION, or CONFLICT
 - Report what needs attention
 
@@ -28,12 +29,16 @@ Find all ADRs that could be relevant to this work—check beyond what's
 declared in the plan's relevant_adrs field. Better to surface extra
 ADRs than miss important ones.
 
+Use the plan's affected_submodules field to focus on ADRs that apply
+to the relevant submodules. Global ADRs always apply; submodule-scoped
+ADRs only apply when their scope matches the affected submodules.
+
 For each relevant ADR, report:
 - COMPLIANT: Plan follows this ADR
 - TENSION: Potential friction, worth noting
 - CONFLICT: Plan violates this ADR, must resolve
 
-Return a validation report with findings for each ADR."
+Note in the report when ADRs were filtered by scope."
 ```
 
 **Show the validation report to the user** before proceeding.

package/src/skills/orchestration/scripts/plan-status.js

@@ -10,7 +10,7 @@
  * file scanning.
  *
  * Usage:
- *   node ~/.claude/scripts/plan-status.js
+ *   node ~/.claude/skills/orchestration/scripts/plan-status.js
  *
  * Output:
  *   JSON object to stdout: