cc-dev-template 0.1.92 → 0.1.94

package/bin/install.js

@@ -252,7 +252,6 @@ const settingsFile = path.join(CLAUDE_DIR, 'settings.json');
 
 if (fs.existsSync(mergeSettingsPath)) {
   const configs = [
-    { file: 'read-guard-hook.json', name: 'Context guard for large reads' },
     { file: 'task-output-guard-hook.json', name: 'TaskOutput context guard' },
     { file: 'statusline-config.json', name: 'Custom status line' },
     // Spinner verbs - choose one (Star Trek or Factorio)
@@ -344,7 +343,9 @@ const deprecatedFiles = [
   path.join(CLAUDE_DIR, 'hooks', 'bash-overflow-guard.sh'),
   path.join(CLAUDE_DIR, 'scripts', 'bash-overflow-hook.json'),
   path.join(CLAUDE_DIR, 'scripts', 'env-config.json'),
-  path.join(CLAUDE_DIR, 'scripts', 'spinner-verbs-helldivers.json')
+  path.join(CLAUDE_DIR, 'scripts', 'spinner-verbs-helldivers.json'),
+  path.join(CLAUDE_DIR, 'scripts', 'read-guard.js'),
+  path.join(CLAUDE_DIR, 'scripts', 'read-guard-hook.json')
 ];
 
 deprecatedFiles.forEach(file => {
@@ -388,6 +389,24 @@ if (fs.existsSync(settingsFile)) {
       });
     }
 
+    // Remove read-guard hooks from settings
+    if (settings.hooks) {
+      ['PreToolUse'].forEach(hookType => {
+        if (settings.hooks[hookType] && Array.isArray(settings.hooks[hookType])) {
+          const originalLength = settings.hooks[hookType].length;
+          settings.hooks[hookType] = settings.hooks[hookType].filter(hook => {
+            const command = hook.hooks?.[0]?.command || '';
+            return !command.includes('read-guard');
+          });
+          if (settings.hooks[hookType].length < originalLength) {
+            console.log(`✓ Removed deprecated read-guard hook from ${hookType}`);
+            settingsModified = true;
+            cleanupPerformed = true;
+          }
+        }
+      });
+    }
+
     // Remove bash-overflow-guard hooks from settings
     if (settings.hooks) {
       ['PostToolUse'].forEach(hookType => {

package/package.json

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

package/src/agents/spec-writer.md

@@ -43,11 +43,15 @@ When prompted to review a spec:
 
 1. Read `{spec_dir}/spec.md` and all upstream artifacts (intent.md, research.md, design.md)
 2. Run every check in the review checklist below
-3. Fix every issue found directly in spec.md — do not report issues, fix them
-4. After fixing, re-run the checklist to verify
-5. Return one of three verdicts:
-   - **APPROVED** — zero issues found on any check. The spec is clean.
-   - **APPROVED_WITH_FIXES** — issues were found and fixed. Another reviewer must verify the fixes.
+3. **Focus on medium-to-high severity issues only.** Classify each issue:
+   - **HIGH**: Something legitimately forgotten, missing, or wrong that would cause implementation problems — missing API contract, wrong data model, contradicts research, missing edge case that could cause bugs
+   - **MEDIUM**: Ambiguity or gap that could lead an implementer astray — vague acceptance criteria, unclear integration point, unverifiable criterion
+   - **LOW**: Minor wording, slight clarifications, formatting, stylistic improvements — **ignore these entirely**, do not fix or report them
+4. Fix every medium-to-high issue found directly in spec.md — do not report issues, fix them
+5. After fixing, re-run the checklist to verify the fixes
+6. Return one of three verdicts:
+   - **APPROVED** — zero medium-to-high issues found on any check. The spec is clean.
+   - **APPROVED_WITH_FIXES** — medium-to-high issues were found and fixed. Another reviewer must verify the fixes.
    - **ISSUES REMAINING** — unfixable issues exist (e.g., missing prerequisites that need user action).
 
 ## Spec Format
@@ -163,11 +167,11 @@ Sections:
 - Out of Scope: N exclusions
 ```
 
-**Review mode (zero issues found — clean pass):**
+**Review mode (zero medium-to-high issues — clean pass):**
 ```
 APPROVED
 
-0 issues found.
+0 medium-to-high issues found.
 All 12 checks passed.
 ```
 
@@ -176,9 +180,10 @@ All 12 checks passed.
 APPROVED_WITH_FIXES
 
 N issues found and fixed:
-- [Check Name]: what was fixed
+- [HIGH] [Check Name]: what was fixed
+- [MEDIUM] [Check Name]: what was fixed
 ...
-All 12 checks now pass, but fixes need verification by a fresh reviewer.
+All 12 checks now pass for medium-to-high issues.
 ```
 
 **Review mode (unfixable issues remain):**

package/src/skills/ship/references/step-3-research.md

@@ -1,30 +1,43 @@
 # Objective Research
 
-A sub-agent researches the codebase using ONLY the questions — it does not see the intent document. This produces factual, objective documentation about the codebase without implementation bias.
+Sub-agents research the codebase using ONLY the questions — they do not see the intent document. This produces factual, objective documentation about the codebase without implementation bias.
 
-This is the critical contamination prevention step. The research agent answers questions about what EXISTS in the codebase. It does not know what feature is being built, so it cannot steer findings toward a particular implementation.
+This is the critical contamination prevention step. The research agents answer questions about what EXISTS in the codebase. They do not know what feature is being built, so they cannot steer findings toward a particular implementation.
+
+Questions are distributed across parallel researchers by category — each agent gets a focused subset, giving it more context per question and a more manageable scope.
 
 ## Create Tasks
 
 Create these tasks and work through them in order:
 
-1. "Research codebase using questions" — spawn the objective-researcher
-2. "Review research with user" — present findings
-3. "Begin design discussion" — proceed to the next phase
+1. "Group questions and distribute to parallel researchers" — spawn multiple objective-researchers
+2. "Merge research" — combine results into a single file
+3. "Review research with user" — present findings
+4. "Begin design discussion" — proceed to the next phase
+
+## Task 1: Distribute Research
+
+Read `{spec_dir}/questions.md` yourself. Identify the category sections (the `##` headers the question-generator produces).
 
-## Task 1: Research Codebase
+For each category, spawn an `objective-researcher` with that category's questions passed inline. Spawn ALL agents in parallel — use multiple Agent tool calls in a single message.
 
-Read `{spec_dir}/questions.md` yourself, then spawn a sub-agent with the questions passed inline in the prompt. The agent never sees the intent document or any files in docs/.
+Each agent writes to a separate file to avoid write conflicts:
 
 ```
 Agent tool:
   subagent_type: "objective-researcher"
-  prompt: "Research the codebase to answer these questions. Write your findings to {spec_dir}/research.md.\n\n{paste the full questions.md content here}"
+  prompt: "Research the codebase to answer these questions. Write your findings to {spec_dir}/research-{category-slug}.md.\n\n{paste this category's questions here}"
 ```
 
+If there are many small categories (6+), group related ones together to keep the agent count reasonable — 3 to 5 parallel agents is the sweet spot.
+
 The objective-researcher has full codebase access (Read, Grep, Glob, Bash) but no knowledge of the feature being built. It receives only the questions via its prompt — it never reads from docs/.
 
-## Task 2: Review Research
+## Task 2: Merge Research
+
+After all researchers complete, read each `research-{slug}.md` file. Concatenate them into a single `{spec_dir}/research.md` (preserving the section structure from each file). Then delete the individual `research-{slug}.md` files — downstream steps only need the merged file.
+
+## Task 3: Review Research
 
 Read `{spec_dir}/research.md` and present a summary to the user. Highlight:
 
@@ -36,7 +49,7 @@ The user may add context the researcher missed, or flag patterns that are outdat
 
 If the research is thin or missing critical areas, spawn the objective-researcher again with additional targeted questions.
 
-## Task 3: Proceed
+## Task 4: Proceed
 
 Update `{spec_dir}/state.yaml` — set `phase: design`.
 

package/src/skills/ship/references/step-4-design.md

@@ -19,12 +19,7 @@ From the research document, identify:
 
 **Patterns to Follow**: Code patterns from the codebase relevant to this feature. If the research found multiple patterns for the same thing (e.g., old way vs. new way of handling forms), list them all and flag for disambiguation.
 
-**Design Questions**: Decisions that need human input before implementation. For each question:
-
-- State the question clearly
-- Provide Option A and Option B (grounded in what the research found)
-- Note which option you'd recommend and why
-- Leave room for the user to propose Option C
+**Design Questions**: Decisions that need human input before implementation. Prepare an ordered list of questions, prioritizing foundational decisions first (architecture, patterns) before detail-level ones (error handling, edge cases).
 
 Common design questions include:
 
@@ -36,13 +31,16 @@ Common design questions include:
 
 ## Task 2: Resolve Decisions
 
-Present the patterns and design questions to the user. Work through each decision:
+Walk through each design question ONE AT A TIME using the `AskUserQuestion` tool. For each question:
+
+1. State the question clearly
+2. Provide concrete options (A, B, etc.) grounded in what the research found
+3. Include your recommendation and reasoning — tell the user which option you'd choose and why
+4. Leave room for the user to propose an alternative
 
-- Let the user choose options or propose alternatives
-- If the user isn't sure, provide your reasoning
-- If a decision requires understanding external technology the codebase doesn't use yet, note it as an open item — the spec phase can handle external research
+Wait for the user's response before moving to the next question. If the user isn't sure, elaborate on your recommendation. If a decision requires understanding external technology the codebase doesn't use yet, note it as an open item — the spec phase can handle external research.
 
-This is interactive. Go back and forth until all design questions are resolved.
+Continue until all design questions are resolved.
 
 ## Task 3: Write design.md
 

package/src/skills/ship/references/step-5-spec.md

@@ -1,6 +1,6 @@
 # Spec Generation
 
-The orchestrator spawns a spec-writer agent to generate the spec, then spawns a fresh instance of the same agent to review and fix it. Each review is a clean context window — the reviewer didn't write the spec, so it reads with fresh eyes. Loop until a reviewer finds zero issues — if a reviewer fixes issues, those fixes must be verified by another fresh reviewer.
+The orchestrator spawns a spec-writer agent to generate the spec, then spawns a fresh instance of the same agent to review and fix it. Each review is a clean context window — the reviewer didn't write the spec, so it reads with fresh eyes. The reviewer focuses on medium-to-high severity issues only — if a reviewer only fixes minor issues, the orchestrator moves on rather than over-rotating. If medium-to-high issues are fixed, those fixes must be verified by another fresh reviewer.
 
 The spec is the last line of defense. Any error or ambiguity here multiplies through task breakdown and implementation.
 
@@ -38,17 +38,19 @@ Agent tool:
 
 ## Task 3: Review Loop
 
-Spawn a FRESH instance of spec-writer in review mode:
+Spawn a FRESH instance of spec-writer in review mode. At least one review is mandatory.
 
 ```
 Agent tool:
   subagent_type: "spec-writer"
-  prompt: "Review the spec at {spec_dir}/spec.md against the upstream artifacts (intent.md, research.md, design.md). Run the full 12-point checklist. Fix every issue you find directly in spec.md. Return APPROVED if zero issues found, APPROVED_WITH_FIXES if issues were found and fixed, or ISSUES REMAINING for anything you cannot auto-fix."
+  prompt: "Review the spec at {spec_dir}/spec.md against the upstream artifacts (intent.md, research.md, design.md). Run the full 12-point checklist. Focus on medium-to-high severity issues — ignore minor wording or formatting. Fix every medium-to-high issue directly in spec.md. Return APPROVED if zero medium-to-high issues found, APPROVED_WITH_FIXES with severity tags if issues were found and fixed, or ISSUES REMAINING for anything you cannot auto-fix."
 ```
 
-**If APPROVED** (zero issues found): The spec is verified clean. Move to Task 4.
+**If APPROVED** (zero medium-to-high issues found): The spec is verified clean. Move to Task 4.
 
-**If APPROVED_WITH_FIXES**: The reviewer fixed issues, but those fixes have not been verified. Spawn another fresh instance to review again. Continue until a reviewer returns APPROVED with zero issues.
+**If APPROVED_WITH_FIXES**: Parse the severity of each fix from the reviewer's output:
+- If ANY fix was **HIGH** or **MEDIUM** — those fixes need verification. Spawn another fresh instance to review again.
+- If somehow all fixes were low-severity — the reviewer is finding diminishing returns. Move to Task 4.
 
 **If ISSUES REMAINING**: Spawn another fresh instance to review again. The previous reviewer already fixed what it could — the next reviewer may catch different things or resolve what the last one couldn't.
 

package/src/scripts/read-guard-hook.json

@@ -1,15 +0,0 @@
-{
-  "hooks": {
-    "PreToolUse": [
-      {
-        "matcher": "Read",
-        "hooks": [
-          {
-            "type": "command",
-            "command": "node ~/.claude/scripts/read-guard.js"
-          }
-        ]
-      }
-    ]
-  }
-}

package/src/scripts/read-guard.js

@@ -1,146 +0,0 @@
-#!/usr/bin/env node
-
-/**
- * read-guard.js - Block large file reads to preserve context
- *
- * This script intercepts Read tool calls and blocks reads of large files that would
- * consume excessive context. It forces Claude to use more targeted approaches like
- * Grep to find relevant sections, then Read with offset/limit parameters.
- *
- * Usage:
- *   echo '{"tool_input":{"file_path":"/path/to/file.js"}}' | node read-guard.js
- *
- * Input format (JSON via stdin):
- *   {
- *     "tool_input": {
- *       "file_path": "/absolute/path/to/file.js",
- *       "limit": 100,  // optional - if present, allow the read
- *       "offset": 0    // optional
- *     }
- *   }
- *
- * Exit codes:
- *   0 - Allow the read (outputs nothing or JSON to allow/deny)
- *
- * Environment variables:
- *   CONTEXT_GUARD_TOKEN_LIMIT - Token threshold (default: 5000)
- *
- * Token estimation:
- *   Rough heuristic: file_size_bytes / 4 ≈ tokens
- *   This catches obvious context bloat without needing a tokenizer.
- */
-
-const fs = require('fs');
-
-const TOKEN_THRESHOLD = parseInt(process.env.CONTEXT_GUARD_TOKEN_LIMIT || '5000', 10);
-
-/**
- * Read JSON from stdin
- * @returns {Promise<object | null>} - Parsed JSON or null if invalid
- */
-async function readStdin() {
-  return new Promise((resolve) => {
-    let data = '';
-
-    process.stdin.setEncoding('utf8');
-    process.stdin.on('data', chunk => {
-      data += chunk;
-    });
-
-    process.stdin.on('end', () => {
-      try {
-        resolve(JSON.parse(data));
-      } catch {
-        resolve(null);
-      }
-    });
-
-    process.stdin.on('error', () => {
-      resolve(null);
-    });
-  });
-}
-
-/**
- * Format file size for display
- * @param {number} bytes - File size in bytes
- * @returns {string} - Human-readable size
- */
-function formatSize(bytes) {
-  if (bytes < 1024) return `${bytes}B`;
-  if (bytes < 1024 * 1024) return `${(bytes / 1024).toFixed(1)}KB`;
-  return `${(bytes / (1024 * 1024)).toFixed(1)}MB`;
-}
-
-/**
- * Main execution
- */
-async function main() {
-  const inputData = await readStdin();
-
-  // If we can't parse input, allow the read
-  if (!inputData) {
-    process.exit(0);
-  }
-
-  const toolInput = inputData.tool_input || {};
-  const filePath = toolInput.file_path;
-  const limit = toolInput.limit;
-
-  // If limit is already specified, Claude is being intentional - allow it
-  if (limit !== undefined) {
-    process.exit(0);
-  }
-
-  // Image files: token consumption based on dimensions, not file size
-  const imageExtensions = ['.png', '.jpg', '.jpeg', '.gif', '.webp', '.svg', '.bmp', '.ico', '.tiff', '.tif'];
-  const ext = filePath.toLowerCase().slice(filePath.lastIndexOf('.'));
-  if (imageExtensions.includes(ext)) {
-    process.exit(0);
-  }
-
-  // If file doesn't exist or no path, let Read tool handle the error
-  if (!filePath || !fs.existsSync(filePath)) {
-    process.exit(0);
-  }
-
-  // Get file stats
-  let stats;
-  try {
-    stats = fs.statSync(filePath);
-  } catch {
-    // Can't stat file, let Read tool handle it
-    process.exit(0);
-  }
-
-  // Skip directories
-  if (stats.isDirectory()) {
-    process.exit(0);
-  }
-
-  // Estimate tokens from file size
-  const fileSizeBytes = stats.size;
-  const estimatedTokens = Math.ceil(fileSizeBytes / 4);
-
-  // If under threshold, allow the read
-  if (estimatedTokens <= TOKEN_THRESHOLD) {
-    process.exit(0);
-  }
-
-  // Block the read with guidance
-  const output = {
-    hookSpecificOutput: {
-      hookEventName: "PreToolUse",
-      permissionDecision: "deny",
-      permissionDecisionReason: `This file (~${estimatedTokens.toLocaleString()} tokens, ${formatSize(fileSizeBytes)}) would consume significant context. Use Grep to find relevant sections first, then Read with offset/limit parameters to read specific portions. If you need the full file, use multiple parallel Read calls with offset/limit to read it in chunks.`
-    }
-  };
-
-  console.log(JSON.stringify(output));
-  process.exit(0);
-}
-
-main().catch(() => {
-  // If anything goes wrong, allow the read to avoid disrupting workflow
-  process.exit(0);
-});