cc-dev-template 0.1.74 → 0.1.76

package/bin/install.js

@@ -401,6 +401,13 @@ if (fs.existsSync(settingsFile)) {
       settingsModified = true;
     }
 
+    // Enable MCP tool search (loads MCP tools on-demand instead of in context)
+    if (settings.env.ENABLE_TOOL_SEARCH !== 'true') {
+      settings.env.ENABLE_TOOL_SEARCH = 'true';
+      console.log('✓ Set ENABLE_TOOL_SEARCH=true');
+      settingsModified = true;
+    }
+
     if (settingsModified) {
       fs.writeFileSync(settingsFile, JSON.stringify(settings, null, 2));
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cc-dev-template",
-  "version": "0.1.74",
+  "version": "0.1.76",
   "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-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`.

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

@@ -0,0 +1,181 @@
+# Step 2: Design the Sub-Agent
+
+Based on the conversation, design the sub-agent's configuration before writing anything.
+
+## Determine the Name
+
+- Hyphen-case: lowercase letters, numbers, and hyphens only
+- Descriptive of the role: `code-reviewer`, `test-runner`, `db-reader`
+- Must be unique across all scopes the user cares about
+- Max 64 characters
+
+## Choose the Scope
+
+| Level | Path | When to use |
+|-------|------|-------------|
+| Project | `.claude/agents/` | Specific to this codebase, shareable via git |
+| User | `~/.claude/agents/` | Available in all projects |
+| Session | `--agents` CLI flag | One-off testing or automation scripts |
+
+Project-level is ideal for team-shared sub-agents. User-level for personal workflow sub-agents.
+
+## Design the Frontmatter
+
+### Required Fields
+
+| Field | Rules |
+|-------|-------|
+| `name` | Hyphen-case, unique, max 64 chars |
+| `description` | When Claude should delegate to this sub-agent. Be specific. |
+
+### Tool Access
+
+Decide the tool restriction strategy:
+
+**Allowlist (recommended for restricted sub-agents):**
+```yaml
+tools: Read, Grep, Glob, Bash
+```
+Grants only the listed tools. Everything else is denied.
+
+**Denylist (for slightly restricted sub-agents):**
+```yaml
+disallowedTools: Write, Edit
+```
+Inherits all tools from the main conversation, minus the listed ones.
+
+**Full access (omit both fields):**
+The sub-agent inherits all tools from the main conversation, including MCP tools.
+
+Common tool sets:
+
+| Role | Tools |
+|------|-------|
+| Read-only analyst | `Read, Grep, Glob` |
+| Read-only with commands | `Read, Grep, Glob, Bash` |
+| Code modifier | `Read, Grep, Glob, Edit, Write, Bash` |
+| Full with LSP | `Read, Grep, Glob, Edit, Write, Bash, LSP` |
+
+For fine-grained control (e.g., allow Bash but only for read-only SQL), use `hooks` with `PreToolUse` instead of tool restrictions.
+
+### Model Selection
+
+| Value | When to use |
+|-------|-------------|
+| `haiku` | Fast, cheap tasks — exploration, simple analysis |
+| `sonnet` | Balanced — code review, moderate analysis |
+| `opus` | Complex reasoning — architectural decisions, nuanced review |
+| `inherit` (default) | Match the main conversation's model |
+
+Omitting `model` defaults to `inherit`.
+
+### Permission Mode
+
+| Mode | Behavior | When to use |
+|------|----------|-------------|
+| `default` | Standard permission prompts | Most sub-agents |
+| `acceptEdits` | Auto-accept file edits | Trusted code modifiers |
+| `dontAsk` | Auto-deny prompts not pre-allowed | Background tasks |
+| `bypassPermissions` | Skip all permission checks | Fully trusted automation |
+| `plan` | Read-only exploration mode | Research sub-agents |
+
+Use `default` unless there is a clear reason to change. `bypassPermissions` is dangerous — use only when the sub-agent's tools are already restricted.
+
+### Max Turns
+
+Set `maxTurns` to limit how many agentic turns the sub-agent can take. Use for:
+- Preventing runaway sub-agents
+- Bounding cost on expensive models
+- Ensuring quick responses for simple tasks
+
+Omit for no limit (the sub-agent runs until it finishes or hits context limits).
+
+### Skills Preloading
+
+List skills to inject into the sub-agent's context at startup:
+
+```yaml
+skills:
+  - api-conventions
+  - error-handling-patterns
+```
+
+Key facts about `skills`:
+- The **full content** of each skill is injected — not just the description
+- Sub-agents **do not inherit** any skills from the parent conversation
+- Sub-agents **cannot invoke the Skill tool** — preloading is the only way to give them skill content
+- `context: fork` on a preloaded skill is ignored — the content is injected as reference material, not executed as a task
+
+Use skills preloading when the sub-agent needs domain knowledge, conventions, or patterns captured in existing skills.
+
+### MCP Servers
+
+Grant access to MCP servers:
+
+```yaml
+mcpServers:
+  - slack
+  - name: custom-db
+    command: npx
+    args: ["-y", "@my/db-server"]
+```
+
+Each entry is either a server name (referencing an already-configured server) or an inline definition. MCP tools are unavailable in background sub-agents.
+
+### Memory
+
+Enable persistent cross-session memory:
+
+```yaml
+memory: project
+```
+
+| Scope | Location | When to use |
+|-------|----------|-------------|
+| `user` | `~/.claude/agent-memory/<name>/` | Knowledge applies across all projects |
+| `project` | `.claude/agent-memory/<name>/` | Project-specific, shareable via git |
+| `local` | `.claude/agent-memory-local/<name>/` | Project-specific, private |
+
+When enabled, the system auto-includes the first 200 lines of `MEMORY.md` and enables Read, Write, Edit for the memory directory. Include memory instructions in the system prompt.
+
+### Hooks
+
+Define lifecycle hooks scoped to the sub-agent:
+
+```yaml
+hooks:
+  PreToolUse:
+    - matcher: "Bash"
+      hooks:
+        - type: command
+          command: "./scripts/validate-command.sh"
+  PostToolUse:
+    - matcher: "Edit|Write"
+      hooks:
+        - type: command
+          command: "./scripts/run-linter.sh"
+```
+
+Supported events in sub-agent frontmatter:
+- `PreToolUse` — validate before tool execution
+- `PostToolUse` — react after tool execution
+- `Stop` — runs when the sub-agent finishes (converted to `SubagentStop` at runtime)
+
+Hook commands receive JSON via stdin with the tool input. Exit code 2 blocks the operation.
+
+## Confirm With the User
+
+Present the complete design:
+- Name and scope
+- Description
+- Tool access strategy
+- Model choice
+- Permission mode
+- Skills to preload (if any)
+- Memory scope (if any)
+- Hooks (if any)
+- MCP servers (if any)
+
+Ask: "Does this design look right?"
+
+Read `references/create-step-3-write.md` after confirmation.

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

@@ -0,0 +1,154 @@
+# Step 3: Write the System Prompt
+
+Write the sub-agent's markdown file. The frontmatter provides configuration; the body IS the system prompt.
+
+## The Fundamental Difference From Skills
+
+A skill's body is instructions Claude follows step-by-step. A sub-agent's body is a system prompt that shapes behavior for the entire execution. This changes what to include.
+
+**Skills:** "Parse the file. Validate the schema. Output the result."
+**Sub-agents:** "You are a schema validator. When invoked, analyze files for schema compliance and report violations by severity."
+
+## System Prompt Structure
+
+Effective sub-agent prompts follow this general structure:
+
+### 1. Role Statement
+
+One or two sentences establishing the sub-agent's identity and expertise.
+
+```markdown
+You are a senior code reviewer ensuring high standards of code quality and security.
+```
+
+Keep it concise. Do not write a paragraph about the sub-agent's background.
+
+### 2. Trigger Behavior
+
+What the sub-agent does when invoked. Use a numbered list of concrete steps.
+
+```markdown
+When invoked:
+1. Run git diff to see recent changes
+2. Focus on modified files
+3. Begin review immediately
+```
+
+### 3. Domain Knowledge
+
+Include only what a fresh Claude instance would NOT know:
+- Project-specific conventions
+- Internal tool usage
+- Non-obvious workflows
+- Domain-specific terminology or patterns
+
+Omit standard programming knowledge, common tool flags, and obvious best practices.
+
+### 4. Constraints and Boundaries
+
+What the sub-agent should NOT do, stated positively:
+
+```markdown
+Focus only on files within your domain's ownership zone.
+Coordinate with the team lead for cross-domain changes.
+```
+
+### 5. Output Format
+
+Define what the sub-agent returns. This is critical — without output guidance, sub-agents may return verbose dumps.
+
+```markdown
+Return a structured review with:
+- Critical issues (must fix)
+- Warnings (should fix)
+- Suggestions (consider improving)
+
+Include specific code examples for each issue.
+```
+
+For sub-agents used by automation or teams, enforce minimal output:
+```markdown
+Return ONLY a status line. All details go in the task file.
+
+Success: `Task complete: T005-feature.md`
+Blocked: `Blocked: T005 - [one-line reason]`
+```
+
+## Writing Style
+
+### Imperative and Direct
+
+State what to do, not what might be done.
+
+| Vague | Direct |
+|-------|--------|
+| "You might want to check for..." | "Check for..." |
+| "It could be helpful to..." | "Analyze..." |
+| "Consider looking at..." | "Inspect..." |
+
+### Positive Framing
+
+Tell the sub-agent what TO do.
+
+| Negative | Positive |
+|----------|----------|
+| "Don't return verbose output" | "Return concise summaries" |
+| "Avoid modifying files outside your domain" | "Only modify files within your domain" |
+| "Never skip tests" | "Always run tests before reporting" |
+
+### Public vs Tribal Knowledge
+
+Both the agent writing this and the agent executing it are Claude.
+
+**Public knowledge — state WHAT, not HOW:**
+- "Run the test suite" — not the exact test command with flags
+- "Check for security vulnerabilities" — not a list of OWASP categories Claude already knows
+- "Use git to find recent changes" — not the exact git diff command
+
+**Tribal knowledge — include specifics:**
+- "Run `make dev` to start the dev server (logs go to `.dev-logs/`)"
+- "Auth requires Clerk test credentials: email `test+clerk_test@yourdomain.com`, code `424242`"
+- "The event bus is async — always await dispatches or tests flake"
+
+### Size Guidance
+
+Sub-agent prompts are single files. Target length depends on complexity:
+
+| Complexity | Target |
+|---|---|
+| Simple focused task | 20-50 lines |
+| Moderate with domain knowledge | 50-100 lines |
+| Complex domain specialist | 100-200 lines |
+
+Over 200 lines — consider whether the sub-agent's scope is too broad. Split into multiple sub-agents or use the `skills` frontmatter to offload domain knowledge into preloaded skills.
+
+## Memory Instructions
+
+If memory is enabled, include instructions in the prompt:
+
+```markdown
+**On startup, read your memory file at the memory directory.**
+Update it when you learn patterns, conventions, or gotchas
+that would help future sessions. Keep it under 100 lines.
+Remove entries that are no longer accurate.
+```
+
+## Team Coordination Instructions
+
+If this sub-agent will be part of agent teams, include team context:
+
+```markdown
+You are part of a team coordinated by a team lead.
+- Use SendMessage to communicate with teammates by name
+- Mark tasks as completed via TaskUpdate when finished
+- After completing a task, check TaskList for available work
+- Only modify files within your domain's ownership zone
+```
+
+## Write the File
+
+With these principles applied, write the complete `.md` file now:
+1. YAML frontmatter with all designed configuration
+2. System prompt body following the structure above
+
+Read `references/create-step-4-review.md` when the file is written.

package/src/skills/creating-sub-agents/references/create-step-4-review.md

@@ -0,0 +1,67 @@
+# Step 4: Review
+
+Review the sub-agent file before proceeding. Fix issues now.
+
+## Public Knowledge Audit
+
+Go through the system prompt and find each:
+- Code block or CLI command
+- API call or library usage
+- Specific implementation detail
+
+For EACH one, ask: "Would a fresh Claude instance know how to do this?"
+
+- If yes: replace with a high-level instruction.
+- If no: keep it — this is tribal knowledge and belongs in the prompt.
+
+## Self-Review Checklist
+
+### Frontmatter
+
+- [ ] `name` is hyphen-case, matches intended filename (minus `.md`)
+- [ ] `description` clearly states WHEN Claude should delegate to this sub-agent
+- [ ] `tools` grants only what the sub-agent needs (not inheriting everything by default unless intentional)
+- [ ] `model` is appropriate for the task complexity
+- [ ] `permissionMode` is justified (default unless there's a reason otherwise)
+- [ ] `skills` lists only skills that exist and that the sub-agent genuinely needs
+- [ ] `memory` scope matches where the knowledge should persist
+- [ ] No conflicting fields (`tools` and `disallowedTools` should not both be present)
+
+### System Prompt Quality
+
+- [ ] Role statement is concise (1-2 sentences, not a paragraph)
+- [ ] Clear trigger behavior — "When invoked, do X"
+- [ ] Output format is explicitly defined
+- [ ] Contains only tribal knowledge, not public knowledge Claude already has
+- [ ] Constraints stated positively ("Only modify X" not "Don't modify Y")
+- [ ] No second person ("You should check..." should be "Check...")
+- [ ] No hedging ("Maybe consider..." should be "Analyze...")
+- [ ] Size is appropriate (not over 200 lines for non-specialist agents)
+
+### Scope and Focus
+
+- [ ] The sub-agent has ONE clear job
+- [ ] The prompt doesn't contain branching workflows (use a skill for that)
+- [ ] Tool access matches the job — a reviewer doesn't have Write access
+- [ ] If memory is enabled, memory instructions are in the prompt
+
+### Integration
+
+- [ ] Description doesn't overlap with existing sub-agents (check with find script)
+- [ ] Name doesn't conflict with existing sub-agents at the same or higher scope
+- [ ] If using `skills`, those skills exist at a location the sub-agent can access
+
+## Run Validation
+
+```bash
+node ~/.claude/skills/creating-sub-agents/scripts/validate-subagent.js [agent-file-path]
+```
+
+Handle results:
+- **Errors:** Fix each one, re-run validation, repeat until passing
+- **Warnings:** Evaluate and fix most of them
+- **Info:** Review — may be acceptable
+
+Only proceed when validation passes and self-review is clean.
+
+Read `references/create-step-5-install.md` when review passes.