cc-dev-template 0.1.73 → 0.1.75

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cc-dev-template",
-  "version": "0.1.73",
+  "version": "0.1.75",
   "description": "Structured AI-assisted development framework for Claude Code",
   "bin": {
     "cc-dev-template": "./bin/install.js"

package/src/commands/done.md

@@ -49,11 +49,37 @@ Add to CLAUDE.md only high-value operational knowledge that can't be found by re
 
 Most sessions: add nothing.
 
-**4. Push**
+**4. Reflect on session and update memory**
+
+Review the full session for lessons worth preserving across conversations. Your memory directory persists between sessions — use it to build institutional knowledge.
+
+What belongs in memory:
+- Debugging breakthroughs — "X error was caused by Y, the fix is Z"
+- Gotchas that wasted time — things you'd want to know next time
+- Confirmed patterns — approaches that worked well (or didn't)
+- Corrections — things you assumed wrong and now know better
+- User preferences discovered through interaction (not stated in CLAUDE.md)
+
+What does NOT belong:
+- Anything already in CLAUDE.md (memory supplements it, doesn't duplicate it)
+- Task-specific context (what you worked on today — that's in git and CURRENT_WORK.md)
+- Obvious things discoverable by reading the code
+- Speculative conclusions from a single observation
+
+How to update:
+- Read your existing MEMORY.md first — edit, don't just append
+- Remove or correct entries that turned out wrong
+- Keep MEMORY.md under 200 lines (it's injected into your system prompt)
+- Use topic files (`debugging.md`, `patterns.md`) for detailed notes, link from MEMORY.md
+- Organize by topic, not chronologically
+
+Most sessions: a small edit or nothing. Occasionally: a meaningful addition. The bar is "would this save me real time or prevent a real mistake next session?"
+
+**5. Push**
 
 Push your commits to the remote.
 
-**5. Report what was updated**
+**6. Report what was updated**
 
 Summarize: commits made, CURRENT_WORK.md changes, any items removed/added.
 
@@ -64,3 +90,4 @@ Summarize: commits made, CURRENT_WORK.md changes, any items removed/added.
 | Git history | What was done | Every session |
 | CURRENT_WORK.md | What to do next | Every session (kept minimal) |
 | CLAUDE.md | How to work here | Rarely |
+| Memory | What I've learned | When something non-obvious is discovered |

package/src/scripts/task-output-guard.js

@@ -8,17 +8,14 @@
  * Each poll dumps the entire transcript (not a delta) into the orchestrator's
  * context, causing severe bloat with background agents.
  *
- * This hook intercepts TaskOutput calls, reads the output file directly,
- * extracts only the last few assistant messages, and returns those as the
- * deny reason. The orchestrator gets useful status without the full transcript.
+ * This hook intercepts TaskOutput calls and denies them with a brief message.
+ * The agent's output is already delivered via the Task tool's return value,
+ * so TaskOutput is redundant and would only duplicate content in context.
  */
 
 const fs = require('fs');
 const path = require('path');
 
-const MAX_ASSISTANT_MESSAGES = 3;
-const MAX_CHARS_PER_MESSAGE = 500;
-
 async function readStdin() {
   return new Promise((resolve) => {
     let data = '';
@@ -58,50 +55,6 @@ function findOutputFile(taskId, cwd) {
   return null;
 }
 
-/**
- * Parse JSONL output file and extract the last N assistant text messages.
- */
-function extractAssistantMessages(filePath) {
-  try {
-    const content = fs.readFileSync(filePath, 'utf8');
-    const lines = content.trim().split('\n');
-
-    const assistantMessages = [];
-
-    for (const line of lines) {
-      try {
-        const entry = JSON.parse(line);
-        if (entry.type !== 'assistant' || !entry.message) continue;
-        if (entry.message.role !== 'assistant' || !entry.message.content) continue;
-
-        // Extract text blocks only (skip tool_use blocks)
-        const textParts = [];
-        const contentArr = Array.isArray(entry.message.content)
-          ? entry.message.content
-          : [entry.message.content];
-
-        for (const block of contentArr) {
-          if (typeof block === 'string' && block.trim()) {
-            textParts.push(block.trim());
-          } else if (block.type === 'text' && block.text && block.text.trim()) {
-            textParts.push(block.text.trim());
-          }
-        }
-
-        if (textParts.length > 0) {
-          assistantMessages.push(textParts.join('\n'));
-        }
-      } catch {
-        // Skip malformed lines
-      }
-    }
-
-    return assistantMessages.slice(-MAX_ASSISTANT_MESSAGES);
-  } catch {
-    return [];
-  }
-}
-
 async function main() {
   const input = await readStdin();
   if (!input) process.exit(0);
@@ -119,26 +72,11 @@ async function main() {
     process.exit(0);
   }
 
-  const messages = extractAssistantMessages(outputFile);
-
-  let summary;
-  if (messages.length === 0) {
-    summary = `Agent ${taskId} is running but has no assistant messages yet. Wait for the blocking return instead of polling.`;
-  } else {
-    const trimmed = messages.map((msg, i) => {
-      const truncated = msg.length > MAX_CHARS_PER_MESSAGE
-        ? msg.slice(0, MAX_CHARS_PER_MESSAGE) + '...'
-        : msg;
-      return `[${i + 1}] ${truncated}`;
-    });
-    summary = `Last ${messages.length} assistant message(s) from agent ${taskId}:\n\n${trimmed.join('\n\n')}`;
-  }
-
   const output = {
     hookSpecificOutput: {
       hookEventName: "PreToolUse",
       permissionDecision: "deny",
-      permissionDecisionReason: summary
+      permissionDecisionReason: `TaskOutput blocked for agent ${taskId} — agent output is delivered via the Task tool return. Do not call TaskOutput; the result will arrive automatically.`
     }
   };
 

package/src/skills/agent-browser/SKILL.md

@@ -1,7 +1,6 @@
 ---
 name: agent-browser
 description: Browser automation CLI for AI agents. Use when the user needs to interact with websites, including navigating pages, filling forms, clicking buttons, taking screenshots, extracting data, testing web apps, or automating any browser task. Triggers include requests to "open a website", "fill out a form", "click a button", "take a screenshot", "scrape data from a page", "test this web app", "login to a site", "automate browser actions", or any task requiring programmatic web interaction.
-allowed-tools: Bash(agent-browser:*)
 ---
 
 # Browser Automation with agent-browser

package/src/skills/creating-agent-skills/references/create-step-1-understand.md

@@ -2,8 +2,17 @@
 
 The skill's quality depends entirely on understanding the domain. Start a conversation with the user.
 
+## Try It First
+
+Before building a skill, the best approach is to do the task in a live conversation first. Iterate until Claude succeeds at the task, then extract the winning approach into the skill. This grounds the skill in something that actually worked rather than theoretical instructions.
+
+Ask: "Have you already done this task successfully with Claude? Can you share that conversation or walk me through what worked?"
+
+If the user has a working conversation, use it as the primary source material. If not, consider running the workflow live together before designing the skill.
+
 ## What To Uncover
 
+- **2-3 concrete use cases** — specific scenarios where this skill would activate. What does the user want to accomplish?
 - **The task** they want to standardize — what do they do repeatedly that they want encoded?
 - **Domain knowledge** Claude does not naturally have — terminology, patterns, edge cases, gotchas
 - **Why certain approaches work** — not just what the steps are, but the reasoning behind them

package/src/skills/creating-agent-skills/references/create-step-2-design.md

@@ -8,6 +8,7 @@ Based on what you learned in the conversation, design the skill's structure befo
 - Prefer gerund form: `processing-pdfs`, `creating-reports`, `reviewing-code`
 - Must match the directory name
 - Max 64 characters
+- Reserved prefixes: names starting with "claude" or "anthropic" are not allowed
 
 ## Determine the Skill Type
 
@@ -79,6 +80,12 @@ Every skill has YAML frontmatter. Required and optional fields:
 | `context` | Set `fork` to run in an isolated sub-agent context |
 | `agent` | Sub-agent type when `context: fork` is set (`Explore`, `Plan`, `general-purpose`, or custom) |
 | `hooks` | Lifecycle hooks scoped to this skill |
+| `compatibility` | Environment requirements — intended product, required system packages, network access needs (1-500 chars) |
+
+### Security Restrictions
+
+- No XML angle brackets (`<` or `>`) in frontmatter — frontmatter appears in Claude's system prompt
+- Skill names starting with "claude" or "anthropic" are reserved
 
 ### String Substitutions Available in Skill Content
 
@@ -107,6 +114,8 @@ Combine into a description that:
 
 **Key insight:** If the description explains too much about WHAT the skill does, Claude believes it already knows enough and will not activate. Keep it about WHEN.
 
+**Negative triggers:** If the skill could over-trigger on related but wrong queries, add scope boundaries. Example: "Advanced data analysis for CSV files. Use for statistical modeling, regression, clustering. Do NOT use for simple data exploration or visualization."
+
 ### For User-Invoked Only Skills
 
 The description just needs to tell the user what the skill does. Keep it minimal:
@@ -139,6 +148,8 @@ skill-name/
 
 **When to add `templates/`:** Boilerplate files that get copied or modified by the agent.
 
+**Do not add:** `README.md` inside the skill folder. All documentation goes in SKILL.md or `references/`.
+
 ## For Procedural Skills: Plan the Steps
 
 List out the steps. Each step becomes one markdown file in `references/`. For each step, determine:
@@ -158,6 +169,19 @@ Present the design:
 - File layout
 - For procedural: the step breakdown
 
+## Define Success Criteria
+
+Before writing, establish how the user will know the skill is working:
+
+- **Triggering**: Does it activate on relevant queries? (Aim for ~90% of intended triggers)
+- **Precision**: Does it stay silent on unrelated queries?
+- **Completeness**: Does the workflow complete without the user needing to redirect or clarify?
+- **Consistency**: Do repeated runs produce structurally similar, quality results?
+
+These are rough benchmarks, not precise thresholds. Ask the user: "What would a successful skill look like for you?"
+
+## Confirm With the User
+
 Ask: "Does this design look right?"
 
 ## Next Step

package/src/skills/creating-agent-skills/references/create-step-3-write.md

@@ -150,6 +150,15 @@ description: [third person, trigger phrases, WHEN not HOW]
 
 Keep it minimal. Only include context that is needed at EVERY activation.
 
+### Error Handling
+
+If the skill involves tool calls, external services, or operations that can fail, include error handling guidance:
+- Common failure modes and what to do about them
+- MCP connection failures: verify server is connected, check authentication, test independently
+- Validation failures: what to check, how to recover
+
+For critical validations, bundle a script rather than relying on language instructions. Code is deterministic; language interpretation is not.
+
 ### MCP Tool References
 
 When a skill uses MCP tools, use fully qualified names:

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

@@ -15,20 +15,44 @@ Copy the skill directory to the target location. Ensure all files are in place
 
 ## Test
 
-Guide the user through testing:
+Guide the user through structured testing:
+
+### 1. Triggering Tests
+
+Verify the skill loads at the right times.
+
+**Should trigger** — test 3-5 phrases that should activate the skill:
+- The obvious request (e.g., "help me plan this sprint")
+- A paraphrased version (e.g., "I need to set up sprint tasks")
+- A domain-specific variant (e.g., "create Linear tickets for Q4")
+
+**Should NOT trigger** — test 2-3 unrelated queries:
+- A clearly unrelated request
+- A request in a similar domain that a different skill should handle
+
+If the skill under-triggers: add more trigger phrases and keywords to the description.
+If the skill over-triggers: add negative scope boundaries or be more specific.
+
+### 2. Functional Tests
+
+Verify the skill produces correct output:
 
 1. Start a new Claude Code session (or restart the current one)
 2. Test explicit invocation: type `/skill-name`
 3. Test autonomous activation: say one of the trigger phrases from the description
-4. Verify the skill activates and behaves as expected
+4. Run through the full workflow — does it complete without the user needing to redirect or clarify?
+5. For skills with tool calls: verify calls succeed and outputs are correct
 
-## If Testing Reveals Issues
+### 3. Iteration
 
-Iterate. The job is not done until the skill works.
+If testing reveals issues, iterate immediately:
 
-- Instructions wrong? Go back to the write step.
+- Instructions unclear or wrong? Go back to the write step.
 - Structure wrong? Go back to the design step.
 - Domain knowledge missing? Go back to the understand step.
+- Description under/over-triggers? Adjust the description and retest.
+
+The job is not done until the skill works.
 
 ## Completion
 

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

@@ -118,6 +118,12 @@ if (!frontmatter.valid) {
       addFinding('STRUCTURE', 'error',
         `Name exceeds 64 characters (${frontmatter.data.name.length})`);
     }
+
+    // Check reserved name prefixes
+    if (frontmatter.data.name.startsWith('claude') || frontmatter.data.name.startsWith('anthropic')) {
+      addFinding('STRUCTURE', 'error',
+        `Name "${frontmatter.data.name}" uses a reserved prefix ("claude" or "anthropic")`);
+    }
   }
 
   if (!frontmatter.data.description) {
@@ -153,6 +159,14 @@ if (!frontmatter.valid) {
         'Long description without trigger phrases may reduce activation reliability');
     }
   }
+
+  // Check for XML angle brackets in frontmatter
+  if (frontmatter.raw && /[<>]/.test(frontmatter.raw)) {
+    addFinding('STRUCTURE', 'error',
+      'Frontmatter contains XML angle brackets (< >) — these are forbidden as frontmatter appears in system prompt',
+      null,
+      'Remove all < and > characters from frontmatter values');
+  }
 }
 
 // Check 3: Second person violations
@@ -162,8 +176,7 @@ const secondPersonPatterns = [
   /\byou need\b/gi,
   /\byou might\b/gi,
   /\byou will\b/gi,
-  /\byou must\b/gi,
-  /\byour\b/gi
+  /\byou must\b/gi
 ];
 
 let secondPersonCount = 0;
@@ -229,26 +242,39 @@ if (negativeCount > 3) {
     'Use positive framing: "Don\'t do X" → "Do Y instead"');
 }
 
-// Check 5: Body size
+// Check 5: Forbidden files
+const readmePath = path.join(resolvedPath, 'README.md');
+if (fs.existsSync(readmePath)) {
+  addFinding('STRUCTURE', 'warning',
+    'Skill folder contains README.md — all documentation should be in SKILL.md or references/',
+    null,
+    'Move README.md content into SKILL.md or references/ and delete README.md');
+}
+
+// Check 6: 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`,
+    `SKILL.md body is ${wordCount} words - exceeds 5,000 word limit`,
     null,
     'Move detailed content to references/ directory');
-} else if (wordCount > 3500) {
+} else if (wordCount > 2000) {
   addFinding('SIZE', 'warning',
-    `SKILL.md body is ${wordCount} words - exceeds 2,000 word recommendation`,
+    `SKILL.md body is ${wordCount} words - consider moving content to references/`,
     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`);
+    'Keep SKILL.md focused; move detailed content to references/ directory');
+}
+
+if (lineCount > 300) {
+  addFinding('SIZE', 'warning',
+    `SKILL.md body is ${lineCount} lines - exceeds 300 line target for informational skills (150 for routers)`,
+    null,
+    'Move content to references/ to stay within size targets');
 }
 
-// Check 6: Progressive disclosure
+// Check 7: Progressive disclosure
 const hasReferences = fs.existsSync(path.join(resolvedPath, 'references'));
 const hasScripts = fs.existsSync(path.join(resolvedPath, 'scripts'));
 
@@ -259,7 +285,7 @@ if (wordCount > 2000 && !hasReferences) {
     'Create references/ and move detailed content there');
 }
 
-// Check 7: Reference integrity
+// Check 8: Reference integrity
 const referencePaths = body.match(/`references\/[^`]+`|references\/[\w.-]+/g) || [];
 const scriptPaths = body.match(/`scripts\/[^`]+`|scripts\/[\w.-]+/g) || [];
 
@@ -283,7 +309,7 @@ for (const ref of scriptPaths) {
   }
 }
 
-// Check 8: Unreferenced resources
+// Check 9: Unreferenced resources
 if (hasReferences) {
   const refDir = path.join(resolvedPath, 'references');
   const refFiles = fs.readdirSync(refDir);

package/src/skills/creating-agent-skills/templates/router-skill.md

@@ -7,55 +7,10 @@ description: {{What it does}} Use when {{trigger conditions}}.
 
 ## What To Do Now
 
-**Ask the user:**
+Ask the user what they need.
 
-What would you like to do?
-1. {{First option}}
-2. {{Second option}}
-3. {{Third option}}
-
-**Wait for response before proceeding.**
-
-## Route to Workflow
-
-| Response | Action |
-|----------|--------|
-| 1, "{{keywords}}" | Read `references/{{first-workflow}}.md` |
-| 2, "{{keywords}}" | Read `references/{{second-workflow}}.md` |
-| 3, "{{keywords}}" | Read `references/{{third-workflow}}.md` |
-
-After reading the workflow, follow it exactly.
-
-## Essential Principles
-
-{{Principles that ALWAYS apply, regardless of which workflow runs}}
-
-### 1. {{First principle}}
-
-{{Explanation}}
-
-### 2. {{Second principle}}
-
-{{Explanation}}
-
-### 3. {{Third principle}}
-
-{{Explanation}}
-
-## Quick Reference
-
-{{Brief reference information always useful to have visible}}
-
-## Resources
-
-**References** (in `references/`):
-- {{reference-1.md}} - {{purpose}}
-- {{reference-2.md}} - {{purpose}}
-
-**Workflows** (in `references/`):
-
-| Workflow | Purpose |
-|----------|---------|
-| {{first-workflow}}.md | {{purpose}} |
-| {{second-workflow}}.md | {{purpose}} |
-| {{third-workflow}}.md | {{purpose}} |
+| Intent | Action |
+|--------|--------|
+| {{First option}} | Read `references/{{first-workflow}}.md` |
+| {{Second option}} | Read `references/{{second-workflow}}.md` |
+| {{Third option}} | Read `references/{{third-workflow}}.md` |

package/src/skills/creating-agent-skills/templates/simple-skill.md

@@ -22,13 +22,3 @@ description: {{What it does}} Use when {{trigger conditions}}.
 ### Step 3: {{Third action}}
 
 {{Instructions for step 3}}
-
-## Completion Checklist
-
-{{Skill name}} is complete when:
-
-```
-- [ ] {{First success criterion}}
-- [ ] {{Second success criterion}}
-- [ ] {{Third success criterion}}
-```

package/src/skills/creating-sub-agents/SKILL.md

@@ -0,0 +1,18 @@
+---
+name: creating-sub-agents
+description: Expert guidance for creating and managing Claude Code sub-agents. Use when the user asks to "create a sub-agent", "build a new agent", "fix a sub-agent", "audit agents", "review my agents", "update an agent", "modify an agent", or mentions sub-agent development, .claude/agents/ files, agent frontmatter, or agent delegation.
+---
+
+# Creating Sub-Agents
+
+## What To Do Now
+
+Ask the user what they need.
+
+| Intent | Action |
+|--------|--------|
+| Create a new sub-agent | Read `references/create-step-1-understand.md` |
+| Fix, improve, audit, or modify an existing sub-agent | Read `references/fix-step-1-diagnose.md` |
+
+If the user says "audit my agents", that is the fix path.
+If they mention a specific agent that needs changes, that is also the fix path.

package/src/skills/creating-sub-agents/references/create-step-1-understand.md

@@ -0,0 +1,46 @@
+# Step 1: Understand the Need
+
+Determine what task the user wants to delegate to a sub-agent, and whether a sub-agent is the right tool.
+
+## Validate the Choice
+
+Before designing a sub-agent, confirm it is the right approach. Ask:
+
+- Does this task produce verbose output that would clutter the main conversation?
+- Does the task benefit from tool restrictions or isolation?
+- Is the work self-contained and returnable as a summary?
+- Does the user want persistent memory across sessions for this task?
+
+If the answer to all of these is no, a skill might be more appropriate. Suggest a skill if the task needs conversation history, branching workflows, or progressive disclosure.
+
+## What To Uncover
+
+Have a conversation with the user to understand:
+
+- **The task** — What specific job should this sub-agent do? Get concrete.
+- **The trigger** — When should Claude delegate to this sub-agent? What signals it?
+- **The output** — What should the sub-agent return? A summary? A fixed file? A report?
+- **The tools** — Does it need to modify files, or just read them? Does it need Bash?
+- **The scope** — Should this be available everywhere (user-level) or just this project?
+- **Existing patterns** — Has the user already been doing this manually? What worked?
+
+## How To Have This Conversation
+
+If the user already provided comprehensive context, verify understanding and move on. If the context is thin, ask one or two questions at a time.
+
+Good questions:
+- "Walk me through what you'd want this agent to do from start to finish."
+- "What should it return when it's done?"
+- "Does it need to modify files, or just analyze them?"
+- "Should this work across all your projects, or just this one?"
+- "Are there tools or services it needs access to?"
+
+## When To Move On
+
+Move on when all of these are true:
+- The task is clearly defined and self-contained
+- The expected output format is understood
+- Tool requirements are known
+- The user confirms you understand their needs
+
+Read `references/create-step-2-design.md`.