cc-dev-template 0.1.26 → 0.1.28

package/bin/install.js

@@ -96,11 +96,21 @@ if (fs.existsSync(skillsDir)) {
 console.log('\nHooks:');
 const hooksDir = path.join(SRC_DIR, 'hooks');
 if (fs.existsSync(hooksDir)) {
-  const hookScripts = fs.readdirSync(hooksDir).filter(f => f.endsWith('.sh'));
+  const hookShellScripts = fs.readdirSync(hooksDir).filter(f => f.endsWith('.sh'));
+  const hookJsScripts = fs.readdirSync(hooksDir).filter(f => f.endsWith('.js'));
   const hookConfigs = fs.readdirSync(hooksDir).filter(f => f.endsWith('.json'));
 
   // Copy shell scripts and make executable
-  hookScripts.forEach(file => {
+  hookShellScripts.forEach(file => {
+    const src = path.join(hooksDir, file);
+    const dest = path.join(CLAUDE_DIR, 'hooks', file);
+    fs.copyFileSync(src, dest);
+    fs.chmodSync(dest, 0o755);  // Make executable
+    console.log(`  ${file}`);
+  });
+
+  // Copy JS scripts and make executable
+  hookJsScripts.forEach(file => {
     const src = path.join(hooksDir, file);
     const dest = path.join(CLAUDE_DIR, 'hooks', file);
     fs.copyFileSync(src, dest);
@@ -115,7 +125,8 @@ if (fs.existsSync(hooksDir)) {
     fs.copyFileSync(src, dest);
   });
 
-  console.log(`✓ ${hookScripts.length} hooks installed`);
+  const totalHooks = hookShellScripts.length + hookJsScripts.length;
+  console.log(`✓ ${totalHooks} hooks installed`);
 } else {
   console.log('  No hooks to install');
 }
@@ -229,7 +240,8 @@ if (fs.existsSync(mergeSettingsPath)) {
     { file: 'statusline-config.json', name: 'Custom status line' },
     { file: 'orchestration-hook.json', name: 'Orchestration guidance hook' },
     { file: 'bash-overflow-hook.json', name: 'Bash overflow guard hook' },
-    { file: 'bash-precheck-hook.json', name: 'Bash precheck hook' }
+    { file: 'bash-precheck-hook.json', name: 'Bash precheck hook' },
+    { file: 'plan-agent-hook.json', name: 'Plan agent context injection hook' }
   ];
 
   configs.forEach(({ file, name }) => {

package/package.json

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

package/src/agents/decomposition-agent.md

@@ -1,6 +1,6 @@
 ---
 name: decomposition-agent
-description: Breaks approved plans into executable tasks with dependencies, or reviews a decomposition for quality and completeness.
+description: Breaks approved plans into executable tasks with dependencies, or reviews a decomposition for quality and completeness. ORCHESTRATION ONLY - spawned by orchestrator during decomposition workflow. Requires plan context; do not use for general coding.
 tools: Read, Glob, Grep, Write, Edit
 model: opus
 color: cyan

package/src/agents/execution-agent.md

@@ -1,6 +1,6 @@
 ---
 name: execution-agent
-description: Implements a single task from a plan, or reviews an implementation for correctness and ADR compliance.
+description: Implements a single task from a plan, or reviews an implementation for correctness and ADR compliance. ORCHESTRATION ONLY - spawned by orchestrator during execution workflow. Requires plan/task context; do not use for general coding.
 tools: Read, Glob, Grep, Write, Edit, Bash
 model: opus
 color: yellow

package/src/agents/rca-agent.md

@@ -1,6 +1,6 @@
 ---
 name: rca-agent
-description: Investigates bugs to form testable hypotheses. Reads debug context, explores code, and returns a hypothesis specific enough to verify with a test.
+description: Investigates bugs to form testable hypotheses. Reads debug context, explores code, and returns a hypothesis specific enough to verify with a test. ORCHESTRATION ONLY - spawned by orchestrator during debugging workflow. Requires debug.yaml context; do not use for general coding.
 tools: Read, Glob, Grep, Edit, Bash
 model: opus
 color: orange

package/src/agents/tdd-agent.md

@@ -1,6 +1,6 @@
 ---
 name: tdd-agent
-description: Writes failing tests to verify bug hypotheses, or fixes code to make tests pass. Used in debugging workflows for test-driven bug fixes.
+description: Writes failing tests to verify bug hypotheses, or fixes code to make tests pass. ORCHESTRATION ONLY - spawned by orchestrator during debugging workflow. Requires debug.yaml and task context; do not use for general coding.
 tools: Read, Glob, Grep, Write, Edit, Bash
 model: opus
 color: red

package/src/hooks/orchestration-guidance.sh

@@ -9,14 +9,25 @@ cat << 'EOF'
 <orchestration-guidance>
 You are an ORCHESTRATOR, not an implementer. Your main thread is for coordination only.
 
-DELEGATE AGGRESSIVELY:
-- Use Task with model: haiku for read-only exploration: file search, code understanding, research
-- Use Task with model: opus for ALL reasoning, code changes, implementation, refactors
-- Default to opus when uncertain—it handles complexity better
+## THE WORKFLOW: Explore → Plan → Execute
+
+Never make code changes without a plan. Follow this sequence:
+
+1. **EXPLORE** - Use Task (haiku) to understand current state: file search, code patterns, dependencies
+2. **PLAN** - Use Task with subagent_type: "Plan" to design the change based on current state
+3. **EXECUTE** - Use Task (opus) to implement the approved plan
+
+## DELEGATE AGGRESSIVELY
+
+- Use Task with model: haiku for read-only exploration
+- Use Task with model: opus for ALL reasoning and implementation
+- Use Task with subagent_type: "Plan" before any non-trivial changes
 - Launch multiple agents in parallel when tasks are independent
 - The only tools you use directly: Task, TodoWrite, AskUserQuestion
 
-DISPATCH WITH CLARITY - Every sub-agent prompt must include:
+## DISPATCH WITH CLARITY
+
+Every sub-agent prompt must include:
 1. Concrete objective: What specific outcome is needed
 2. Acceptance criteria: How to verify the task is complete
 3. Assumptions: Context the agent should validate before proceeding
@@ -24,13 +35,16 @@ DISPATCH WITH CLARITY - Every sub-agent prompt must include:
 
 This ensures smooth feedback: sub-agents surface blockers early rather than going down wrong paths.
 
-YOUR ROLE:
+## YOUR ROLE
+
 1. Decompose problems into discrete tasks
 2. Dispatch sub-agents with clear objectives and acceptance criteria
 3. Verify results meet requirements
 4. Synthesize findings for the user
 
-SUCCESS LOOKS LIKE: Your main thread has almost no Read, Grep, Glob, Edit, or Write calls. Sub-agents do the work; you orchestrate and verify.
+## SUCCESS LOOKS LIKE
+
+Your main thread has almost no Read, Grep, Glob, Edit, or Write calls. Sub-agents do the work; you orchestrate and verify.
 
 ONLY handle directly: Single-command bash (git status, npm test), trivial typo fixes where you already know the exact line.
 </orchestration-guidance>

package/src/hooks/plan-agent-context.js

@@ -0,0 +1,140 @@
+#!/usr/bin/env node
+/**
+ * plan-agent-context.js - PreToolUse hook for Plan sub-agent
+ *
+ * Intercepts Task calls with subagent_type: "Plan" and injects:
+ * 1. All project ADRs (since sub-agents can't spawn other sub-agents)
+ * 2. Planning guidance (web search for libraries, remove ambiguities)
+ */
+
+const fs = require('fs');
+const path = require('path');
+const yaml = require('js-yaml');
+
+// Read hook input from stdin
+let input = '';
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', chunk => input += chunk);
+process.stdin.on('end', () => {
+  try {
+    const hookInput = JSON.parse(input);
+    const result = processHook(hookInput);
+    console.log(JSON.stringify(result));
+  } catch (err) {
+    // On error, allow the tool call to proceed unchanged
+    console.log(JSON.stringify({ decision: "allow" }));
+  }
+});
+
+function processHook(hookInput) {
+  const toolInput = hookInput.tool_input || {};
+
+  // Only intercept Plan agent calls
+  if (toolInput.subagent_type !== 'Plan') {
+    return { decision: "allow" };
+  }
+
+  // Collect ADRs
+  const adrs = collectADRs();
+
+  // Build the planning guidance
+  const planningGuidance = buildPlanningGuidance(adrs);
+
+  // Inject into the prompt
+  const originalPrompt = toolInput.prompt || '';
+  const augmentedPrompt = `${planningGuidance}\n\n---\n\nORIGINAL TASK:\n${originalPrompt}`;
+
+  return {
+    decision: "allow",
+    updatedInput: {
+      ...toolInput,
+      prompt: augmentedPrompt
+    }
+  };
+}
+
+function collectADRs() {
+  const adrDir = path.join(process.cwd(), '.claude', 'adrs');
+  const adrs = [];
+
+  if (!fs.existsSync(adrDir)) {
+    return adrs;
+  }
+
+  const files = fs.readdirSync(adrDir).filter(f => f.endsWith('.yaml'));
+
+  for (const file of files) {
+    try {
+      const content = fs.readFileSync(path.join(adrDir, file), 'utf8');
+      const adr = yaml.load(content);
+      if (adr && adr.status !== 'Superseded') {
+        adrs.push({
+          id: adr.id,
+          title: adr.title,
+          description: adr.description,
+          constraints: adr.constraints,
+          decision: adr.decision
+        });
+      }
+    } catch (err) {
+      // Skip malformed ADRs
+    }
+  }
+
+  return adrs;
+}
+
+function buildPlanningGuidance(adrs) {
+  let guidance = `<plan-agent-context>
+## Planning Guidelines
+
+You are creating an implementation plan. Follow these principles:
+
+### Research Before Planning
+- If the plan involves third-party libraries, APIs, or features not yet in the codebase, use WebSearch or WebFetch to get current documentation
+- Do not assume library APIs - verify them with up-to-date sources
+- Check compatibility with the project's infrastructure and existing patterns
+
+### Remove Ambiguity
+- Each step in your plan should be concrete and actionable
+- If requirements are unclear, surface the ambiguity rather than making assumptions
+- Identify decision points that need user input before execution
+
+### ADR Compliance
+The plan must respect these architectural decisions:
+
+`;
+
+  if (adrs.length === 0) {
+    guidance += `(No ADRs found in this project)\n`;
+  } else {
+    for (const adr of adrs) {
+      guidance += `### ${adr.id}: ${adr.title}\n`;
+      if (adr.description) {
+        guidance += `${adr.description.trim()}\n`;
+      }
+      if (adr.constraints) {
+        if (adr.constraints.must && adr.constraints.must.length > 0) {
+          guidance += `**MUST:**\n`;
+          for (const c of adr.constraints.must) {
+            guidance += `- ${c}\n`;
+          }
+        }
+        if (adr.constraints.must_not && adr.constraints.must_not.length > 0) {
+          guidance += `**MUST NOT:**\n`;
+          for (const c of adr.constraints.must_not) {
+            guidance += `- ${c}\n`;
+          }
+        }
+      }
+      if (adr.decision) {
+        guidance += `**Decision:** ${adr.decision.trim()}\n`;
+      }
+      guidance += `\n`;
+    }
+  }
+
+  guidance += `</plan-agent-context>`;
+
+  return guidance;
+}

package/src/hooks/plan-agent-hook.json

@@ -0,0 +1,15 @@
+{
+  "hooks": {
+    "PreToolUse": [
+      {
+        "matcher": "Task",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node $HOME/.claude/hooks/plan-agent-context.js"
+          }
+        ]
+      }
+    ]
+  }
+}