cc-dev-template 0.1.74 → 0.1.76

package/src/skills/creating-sub-agents/references/create-step-5-install.md

@@ -0,0 +1,76 @@
+# Step 5: Install and Test
+
+## Install
+
+Copy the `.md` file to the target location:
+
+| Level | Path |
+|-------|------|
+| User | `~/.claude/agents/<name>.md` |
+| Project | `.claude/agents/<name>.md` |
+
+Sub-agents loaded via `/agents` are available immediately. Manually created files require a session restart or use `/agents` to reload.
+
+## Test
+
+### 1. Delegation Tests
+
+Verify Claude delegates to the sub-agent at the right times.
+
+**Should delegate** — test 3-5 requests that should trigger delegation:
+- The obvious request matching the description
+- A paraphrased version
+- A domain-specific variant
+
+**Should NOT delegate** — test 2-3 unrelated requests:
+- A clearly unrelated task
+- A task in a similar domain that a different sub-agent should handle
+
+If the sub-agent under-triggers: strengthen the description with more specific phrasing or add "use proactively" if appropriate.
+If the sub-agent over-triggers: make the description more specific or narrow the scope.
+
+### 2. Functional Tests
+
+Test the sub-agent produces correct output:
+
+1. Start a new Claude Code session (or use `/agents` to reload)
+2. Request a task matching the sub-agent's description
+3. Verify:
+   - The sub-agent uses only its granted tools
+   - The output matches the expected format
+   - The sub-agent stays within its defined boundaries
+   - It completes without errors or hanging
+
+### 3. Explicit Invocation Test
+
+Ask Claude to use the sub-agent by name:
+```
+Use the code-reviewer sub-agent to review the authentication module
+```
+
+### 4. Edge Cases
+
+- What happens with an empty or trivial input?
+- What happens if the sub-agent encounters an error?
+- Does the output stay concise, or does it dump everything?
+
+### 5. Iteration
+
+If testing reveals issues, iterate:
+
+- Description wrong? Adjust description and retest.
+- Tools too broad or narrow? Adjust `tools` field.
+- Output too verbose? Add output format constraints to the prompt.
+- Prompt unclear? Go back to the write step.
+- Wrong scope entirely? Reconsider whether this should be a skill instead.
+
+## Completion
+
+Summarize what was created:
+- Sub-agent name
+- Install location
+- Description (when it triggers)
+- Tool access
+- Model
+- Memory scope (if any)
+- Skills preloaded (if any)

package/src/skills/creating-sub-agents/references/fix-step-1-diagnose.md

@@ -0,0 +1,99 @@
+# Step 1: Diagnose
+
+Find the sub-agent, read it, and understand what is wrong.
+
+## Find the Sub-Agent
+
+If the user named a specific sub-agent, locate it. Otherwise, discover available sub-agents:
+
+```bash
+node ~/.claude/skills/creating-sub-agents/scripts/find-subagents.js
+```
+
+Ask which sub-agent to fix.
+
+## Read the File
+
+Read the entire `.md` file — frontmatter and body. Sub-agents are single files, so there is only one file to read.
+
+Also check for related resources:
+- Hook scripts referenced in frontmatter
+- Skills listed in `skills` field (verify they exist)
+- MCP server configurations
+
+## Understand What Is Wrong
+
+Ask the user:
+- "What is the sub-agent supposed to do?"
+- "What does it actually do instead?"
+- "Can you show me an example of it failing or misbehaving?"
+
+Get specific about expected behavior versus actual behavior.
+
+## Diagnose Against Principles
+
+Read `references/principles.md` for the full set of principles, then evaluate:
+
+### Focus
+- Does the sub-agent have ONE clear job?
+- Is the scope too broad? (trying to review, debug, AND test)
+- Would splitting into multiple sub-agents help?
+
+### System Prompt Quality
+- Is there a clear role statement?
+- Are trigger instructions present? ("When invoked, do X")
+- Is the output format defined?
+- Does it contain only tribal knowledge, not public knowledge?
+- Any dead ends where the sub-agent wouldn't know what to do?
+
+### Frontmatter Configuration
+- Is `description` specific enough for Claude to delegate accurately?
+- Are `tools` appropriate? (reviewer with Write access? modifier without it?)
+- Is `model` appropriate for the task complexity?
+- If `skills` are listed, do those skills exist?
+- If `memory` is enabled, are memory instructions in the prompt?
+
+### Writing Style
+- Second person? ("You should check..." — should be "Check...")
+- Negative framing? ("Don't modify..." — should be "Only modify...")
+- Hedging? ("Maybe consider..." — should be "Analyze...")
+- Over-verbose? (public knowledge Claude already has)
+
+### Integration Issues
+- Name conflicts with other sub-agents at same or higher scope?
+- Description overlaps with other sub-agents?
+- Hook scripts exist and are executable?
+
+## Summarize Findings
+
+Present the diagnosis:
+- List each issue found
+- What principle it violates
+- What the fix would look like
+
+## Classify the Fix Type
+
+**Surface fixes** — wording, style, description tweaks, missing output format:
+- Fixing second person to imperative
+- Adding output format section
+- Improving description with better trigger language
+- Removing public knowledge
+- Adding missing constraints
+
+**Structural changes** — anything that changes the sub-agent's design:
+- Changing tool access strategy
+- Adding/removing skills preloading
+- Adding memory
+- Adding hooks
+- Splitting a broad sub-agent into multiple focused ones
+- Changing scope (project to user or vice versa)
+- Fundamentally rewriting the system prompt
+
+Tell the user which type of fix is needed.
+
+## Next Step
+
+| Fix Type | Action |
+|----------|--------|
+| Surface fixes only | Read `references/fix-step-2-apply.md` |
+| Structural changes needed | Read `references/create-step-2-design.md` to redesign, then `references/fix-step-2-apply.md` to apply |

package/src/skills/creating-sub-agents/references/fix-step-2-apply.md

@@ -0,0 +1,77 @@
+# Step 2: Apply Fixes
+
+Fix the issues identified in diagnosis. Plan changes, confirm, then apply.
+
+## If Coming From Design Step
+
+If you just read `create-step-2-design.md` for structural changes, use that design as the blueprint. The writing principles below still apply.
+
+## Plan Changes First
+
+Before editing, state:
+- What specifically changes in the frontmatter
+- What specifically changes in the system prompt body
+- Any external changes needed (hook scripts, skill files)
+
+Confirm the plan with the user before making changes.
+
+## Writing Principles
+
+Apply these while making every change:
+
+### System Prompt, Not Step-by-Step Instructions
+
+Sub-agent bodies provide context and behavior guidance, not sequential workflows.
+
+| Skill-style (wrong for sub-agents) | System prompt style (correct) |
+|---|---|
+| "Step 1: Read the file. Step 2: Parse the JSON. Step 3: Validate." | "When invoked, analyze files for schema compliance. Report violations by severity." |
+
+Exception: A brief "When invoked:" numbered list is fine for establishing the high-level workflow. Avoid micromanaging individual steps.
+
+### Imperative and Direct
+
+| Wrong | Right |
+|-------|-------|
+| "You should analyze the code" | "Analyze the code" |
+| "It might be helpful to check" | "Check" |
+| "Consider looking at" | "Inspect" |
+
+### Positive Framing
+
+| Negative | Positive |
+|----------|----------|
+| "Don't return verbose output" | "Return concise summaries" |
+| "Avoid files outside your domain" | "Only modify files within your domain" |
+| "Never skip validation" | "Always validate first" |
+
+### Tribal Knowledge Only
+
+Remove anything Claude already knows. Keep project-specific conventions, internal tool usage, and domain-specific patterns.
+
+### Output Format
+
+Every sub-agent needs clear output guidance. If missing, add it:
+
+```markdown
+Provide feedback organized by priority:
+- Critical issues (must fix)
+- Warnings (should fix)
+- Suggestions (consider improving)
+```
+
+### Description Improvement
+
+If the description needs fixing:
+- State WHAT the sub-agent does and WHEN to use it
+- Include "use proactively" for auto-triggering sub-agents
+- Keep it specific but not exhaustive
+- Avoid explaining HOW it works
+
+## Apply the Changes
+
+Make all planned modifications now.
+
+For structural changes that involve rewriting the system prompt, reference `references/create-step-3-write.md` for the complete writing guidance.
+
+Read `references/fix-step-3-validate.md` when all fixes are applied.

package/src/skills/creating-sub-agents/references/fix-step-3-validate.md

@@ -0,0 +1,52 @@
+# Step 3: Validate and Test
+
+## Public Knowledge Audit
+
+Go through every changed section. Find each code block, CLI command, and implementation detail.
+
+For each one: "Would a fresh Claude instance know how to do this?"
+- If yes: delete it, replace with high-level instruction.
+- If no: keep it — tribal knowledge.
+
+## Self-Review
+
+Re-read the entire file. Verify:
+
+- Role statement is concise?
+- Clear trigger behavior?
+- Output format defined?
+- Issues from diagnosis resolved?
+- Fixes did not introduce new problems?
+- Writing style correct? (imperative, positive, direct)
+- Frontmatter valid and consistent?
+
+## Run Validation
+
+```bash
+node ~/.claude/skills/creating-sub-agents/scripts/validate-subagent.js [agent-file-path]
+```
+
+Handle results:
+- **Errors:** Fix, re-run, repeat until passing
+- **Warnings:** Evaluate and fix most
+- **Info:** Review — may be acceptable
+
+## Test
+
+If the fix affected behavior:
+
+1. Restart Claude Code or use `/agents` to reload
+2. If description changed: test delegation with matching requests
+3. If prompt changed: invoke the sub-agent and verify behavior
+4. If tools changed: verify the sub-agent can (and cannot) access the right tools
+
+## If Issues Remain
+
+Go back to `references/fix-step-2-apply.md`.
+
+## Completion
+
+Summarize what was fixed:
+- Which aspects changed (frontmatter, prompt, hooks)
+- What was wrong and how it was resolved
+- Confirm with the user that the sub-agent now behaves as expected

package/src/skills/creating-sub-agents/references/principles.md

@@ -0,0 +1,157 @@
+# Sub-Agent Design Principles
+
+## Contents
+
+- [Sub-Agents vs Skills](#sub-agents-vs-skills)
+- [The System Prompt Is Everything](#the-system-prompt-is-everything)
+- [Prompt Design for Sub-Agents](#prompt-design-for-sub-agents)
+- [Focus and Constraint](#focus-and-constraint)
+- [Tool Restriction Philosophy](#tool-restriction-philosophy)
+- [Description Quality](#description-quality)
+- [Memory Design](#memory-design)
+- [Key Limitations](#key-limitations)
+- [Anti-Patterns](#anti-patterns)
+
+---
+
+## Sub-Agents vs Skills
+
+Sub-agents and skills solve different problems. Choose the right one:
+
+| Use a sub-agent when... | Use a skill when... |
+|---|---|
+| The task produces verbose output you want isolated | The task needs access to conversation history |
+| You want to enforce tool restrictions | You want reusable prompts that run inline |
+| The work is self-contained and returns a summary | Follow-up interaction is expected |
+| You want persistent memory across sessions | You need progressive disclosure across steps |
+| You want to route tasks to a cheaper/faster model | The instructions change based on user input |
+| Parallel execution benefits the workflow | The workflow has branching paths |
+
+**Key difference:** A skill is instructions Claude reads and follows in the current conversation. A sub-agent is an isolated worker with its own system prompt, tools, and context window.
+
+## The System Prompt Is Everything
+
+A sub-agent's markdown body IS its system prompt. Unlike skills (where content is instructions loaded on-demand), the sub-agent body is read once at spawn and provides all context for the sub-agent's entire execution.
+
+| Aspect | Skill SKILL.md | Sub-Agent .md body |
+|--------|----------------|---------------------|
+| When read | Each time skill is invoked | Once at spawn |
+| Purpose | Route to workflows, provide step-by-step instructions | Provide complete context for focused task |
+| Lifespan | Entire user session (repeated activations) | Single invocation |
+| Context | Shares main conversation context | Isolated context window |
+| Progressive disclosure | Essential — load content on-demand | Not applicable — one file, one prompt |
+
+Sub-agents receive only their system prompt plus basic environment details (working directory). They do not receive the full Claude Code system prompt.
+
+## Prompt Design for Sub-Agents
+
+Sub-agent prompts benefit from context that would be wasteful in skills:
+
+**Include in sub-agent prompts:**
+- Role and purpose — the sub-agent needs full context upfront
+- What success looks like — guides decision-making throughout execution
+- Constraints and boundaries — what the sub-agent should NOT do
+- Output format — what to return to the parent conversation
+- Domain knowledge the sub-agent needs to do its job
+
+**Omit from sub-agent prompts:**
+- Public knowledge Claude already has (standard tools, common patterns)
+- Step-by-step instructions for obvious tasks
+- Exhaustive examples when one or two suffice
+
+The test: does every line in the prompt help the sub-agent do its specific job better? If not, remove it.
+
+## Focus and Constraint
+
+Design each sub-agent to excel at ONE specific task. A focused sub-agent with clear boundaries outperforms a broad one with vague responsibilities.
+
+**Focused (good):** "Reviews code for quality, security, and best practices. Returns actionable feedback."
+
+**Broad (bad):** "Helps with various development tasks including code review, debugging, testing, and documentation."
+
+When a sub-agent's scope creeps, split it into multiple sub-agents.
+
+## Tool Restriction Philosophy
+
+Grant only the tools needed for the task. This is a security and focus benefit.
+
+| Sub-agent type | Typical tools |
+|---|---|
+| Read-only reviewer | Read, Grep, Glob, Bash |
+| Code modifier | Read, Grep, Glob, Edit, Write, Bash |
+| Research/exploration | Read, Grep, Glob |
+| Full-capability worker | All tools (inherit) |
+
+Use `tools` as an allowlist (explicitly grant tools) or `disallowedTools` as a denylist (explicitly remove tools from the inherited set). Choose one approach — do not mix both.
+
+For fine-grained control beyond tool-level, use `hooks` with `PreToolUse` to validate specific operations before they execute.
+
+## Description Quality
+
+The description determines when Claude delegates to the sub-agent. Write it for Claude, not for humans.
+
+**Effective descriptions:**
+- State what the sub-agent does and when to use it
+- Include "use proactively" if the sub-agent should auto-activate
+- Be specific enough that Claude can match tasks accurately
+
+**Good:**
+```
+Expert code review specialist. Proactively reviews code for quality,
+security, and maintainability. Use immediately after writing or
+modifying code.
+```
+
+**Bad:**
+```
+Helps with code stuff.
+```
+
+**Also bad (too detailed):**
+```
+Uses AST parsing to analyze cyclomatic complexity, checks for OWASP
+top 10 vulnerabilities including SQL injection and XSS, validates
+against the Google style guide...
+```
+
+If the description explains too much about HOW, Claude thinks it already knows enough and may not delegate. Focus on WHAT and WHEN.
+
+## Memory Design
+
+Enable memory when the sub-agent benefits from cross-session learning.
+
+| Scope | Location | Use when |
+|---|---|---|
+| `user` | `~/.claude/agent-memory/<name>/` | Knowledge applies across all projects |
+| `project` | `.claude/agent-memory/<name>/` | Knowledge is project-specific, shareable via git |
+| `local` | `.claude/agent-memory-local/<name>/` | Knowledge is project-specific, private |
+
+`user` is the recommended default. Use `project` when the sub-agent's knowledge is codebase-specific and the team benefits from sharing it.
+
+When memory is enabled, the system automatically includes the first 200 lines of `MEMORY.md` in the sub-agent's prompt and enables Read, Write, and Edit tools for the memory directory.
+
+Include memory instructions in the sub-agent's prompt:
+```
+Update your agent memory as you discover patterns, conventions,
+and key decisions. This builds institutional knowledge across sessions.
+```
+
+## Key Limitations
+
+- Sub-agents **cannot spawn other sub-agents**. Nesting depth is exactly 1.
+- Sub-agents **do not have access to the Skill tool**. They cannot discover or invoke skills.
+- Sub-agents **do not inherit skills** from the parent conversation. Use the `skills` frontmatter to pre-load skill content.
+- Sub-agents receive a **stripped-down system prompt**, not the full Claude Code system prompt.
+- Background sub-agents **auto-deny permission prompts** not pre-approved at launch. MCP tools are unavailable in background sub-agents.
+
+## Anti-Patterns
+
+**Over-broad sub-agents.** A sub-agent that "does everything" provides no focus benefit. Split into specialized sub-agents.
+
+**Missing output format.** Without clear output guidance, sub-agents may return verbose dumps instead of useful summaries. Always specify what to return.
+
+**Granting all tools by default.** Omitting `tools` inherits everything. Be intentional — a code reviewer should not have Write access.
+
+**Duplicate sub-agents at different scopes.** A project-level agent with the same name as a user-level agent shadows the user-level one. This causes confusion. Use distinct names or be intentional about overrides.
+
+**Putting step-by-step skill logic in a sub-agent prompt.** If the task has branching workflows or progressive disclosure, use a skill instead. Sub-agents are for focused, self-contained work.

package/src/skills/creating-sub-agents/scripts/find-subagents.js

@@ -0,0 +1,217 @@
+#!/usr/bin/env node
+
+/**
+ * find-subagents.js
+ *
+ * Discovers all Claude Code sub-agent definitions at user and project levels.
+ * Returns sub-agent locations and basic metadata.
+ *
+ * Usage: node find-subagents.js [--json] [--verbose]
+ */
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const args = process.argv.slice(2);
+const jsonOutput = args.includes('--json');
+const verbose = args.includes('--verbose');
+
+const locations = [
+  {
+    name: 'user',
+    path: path.join(os.homedir(), '.claude', 'agents'),
+    description: 'User-level sub-agents (~/.claude/agents/)'
+  },
+  {
+    name: 'project',
+    path: path.join(process.cwd(), '.claude', 'agents'),
+    description: 'Project-level sub-agents (.claude/agents/)'
+  }
+];
+
+function parseFrontmatter(content) {
+  const match = content.match(/^---\n([\s\S]*?)\n---/);
+  if (!match) return null;
+
+  const frontmatter = {};
+  const lines = match[1].split('\n');
+  let currentKey = null;
+  let inArray = false;
+  let arrayValues = [];
+
+  for (const line of lines) {
+    // Handle array items
+    if (inArray && line.match(/^\s+-\s+/)) {
+      arrayValues.push(line.replace(/^\s+-\s+/, '').trim());
+      continue;
+    } else if (inArray) {
+      frontmatter[currentKey] = arrayValues;
+      inArray = false;
+      arrayValues = [];
+    }
+
+    const colonIndex = line.indexOf(':');
+    if (colonIndex > 0) {
+      const key = line.slice(0, colonIndex).trim();
+      let value = line.slice(colonIndex + 1).trim();
+
+      if (value === '' || value === '|' || value === '>') {
+        currentKey = key;
+        if (value === '') {
+          // Could be start of array or multi-line
+          inArray = true;
+          arrayValues = [];
+        }
+        continue;
+      }
+
+      if ((value.startsWith('"') && value.endsWith('"')) ||
+          (value.startsWith("'") && value.endsWith("'"))) {
+        value = value.slice(1, -1);
+      }
+
+      frontmatter[key] = value;
+      currentKey = key;
+    }
+  }
+
+  if (inArray && currentKey) {
+    frontmatter[currentKey] = arrayValues;
+  }
+
+  return frontmatter;
+}
+
+function getBody(content) {
+  const match = content.match(/^---\n[\s\S]*?\n---\n([\s\S]*)$/);
+  return match ? match[1] : content;
+}
+
+function getAgentStats(filePath) {
+  if (!fs.existsSync(filePath)) return null;
+
+  const content = fs.readFileSync(filePath, 'utf-8');
+  const frontmatter = parseFrontmatter(content);
+  const body = getBody(content);
+  const wordCount = body.split(/\s+/).filter(w => w.length > 0).length;
+  const lineCount = body.split('\n').length;
+
+  return {
+    name: frontmatter?.name || path.basename(filePath, '.md'),
+    description: frontmatter?.description || null,
+    tools: frontmatter?.tools || '(inherits all)',
+    disallowedTools: frontmatter?.disallowedTools || null,
+    model: frontmatter?.model || 'inherit',
+    permissionMode: frontmatter?.permissionMode || 'default',
+    skills: frontmatter?.skills || null,
+    memory: frontmatter?.memory || null,
+    maxTurns: frontmatter?.maxTurns || null,
+    wordCount,
+    lineCount,
+    frontmatterValid: !!(frontmatter?.name && frontmatter?.description)
+  };
+}
+
+function scanLocation(location) {
+  const agents = [];
+
+  if (!fs.existsSync(location.path)) return agents;
+
+  const entries = fs.readdirSync(location.path, { withFileTypes: true });
+
+  for (const entry of entries) {
+    if (!entry.isFile() || !entry.name.endsWith('.md')) continue;
+
+    const filePath = path.join(location.path, entry.name);
+    const stats = getAgentStats(filePath);
+
+    if (stats) {
+      agents.push({
+        file: entry.name,
+        path: filePath,
+        location: location.name,
+        ...stats
+      });
+    }
+  }
+
+  return agents;
+}
+
+// Main
+const results = {
+  timestamp: new Date().toISOString(),
+  cwd: process.cwd(),
+  locations: {},
+  agents: [],
+  summary: {
+    total: 0,
+    byLocation: {}
+  }
+};
+
+for (const location of locations) {
+  const agents = scanLocation(location);
+
+  results.locations[location.name] = {
+    path: location.path,
+    exists: fs.existsSync(location.path),
+    count: agents.length
+  };
+
+  results.agents.push(...agents);
+  results.summary.byLocation[location.name] = agents.length;
+}
+
+results.summary.total = results.agents.length;
+
+if (jsonOutput) {
+  console.log(JSON.stringify(results, null, 2));
+} else {
+  console.log('\n=== Claude Code Sub-Agent 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(`  Sub-agents found: ${info.count}`);
+    console.log();
+  }
+
+  if (results.agents.length === 0) {
+    console.log('No sub-agents found.\n');
+  } else {
+    console.log('=== Sub-Agents ===\n');
+
+    for (const agent of results.agents) {
+      console.log(`[${agent.location}] ${agent.name}`);
+      console.log(`  File: ${agent.path}`);
+      console.log(`  Tools: ${agent.tools}`);
+      console.log(`  Model: ${agent.model}`);
+
+      if (verbose) {
+        console.log(`  Words: ${agent.wordCount}`);
+        console.log(`  Lines: ${agent.lineCount}`);
+        console.log(`  Valid frontmatter: ${agent.frontmatterValid ? 'Yes' : 'No'}`);
+        console.log(`  Permission mode: ${agent.permissionMode}`);
+        if (agent.skills) console.log(`  Skills: ${JSON.stringify(agent.skills)}`);
+        if (agent.memory) console.log(`  Memory: ${agent.memory}`);
+        if (agent.maxTurns) console.log(`  Max turns: ${agent.maxTurns}`);
+        if (agent.disallowedTools) console.log(`  Disallowed tools: ${agent.disallowedTools}`);
+
+        if (agent.description) {
+          const truncated = agent.description.length > 80
+            ? agent.description.slice(0, 80) + '...'
+            : agent.description;
+          console.log(`  Description: ${truncated}`);
+        }
+      }
+
+      console.log();
+    }
+
+    console.log(`Total: ${results.summary.total} sub-agent(s)\n`);
+  }
+}