cc-dev-template 0.1.82 → 0.1.83

package/package.json

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

package/src/agents/objective-researcher.md

@@ -1,23 +1,43 @@
 ---
 name: objective-researcher
 description: Answers codebase questions objectively without knowing the feature being built. Produces factual research documentation.
-tools: Read, Grep, Glob, Bash, Write
 permissionMode: bypassPermissions
 maxTurns: 30
 model: sonnet
+hooks:
+  PreToolUse:
+    - matcher: "Read"
+      hooks:
+        - type: command
+          command: "$HOME/.claude/scripts/restrict-researcher.sh"
+    - matcher: "Write"
+      hooks:
+        - type: command
+          command: "$HOME/.claude/scripts/restrict-researcher.sh"
+    - matcher: "Edit"
+      hooks:
+        - type: command
+          command: "$HOME/.claude/scripts/restrict-researcher.sh"
+    - matcher: "Grep"
+      hooks:
+        - type: command
+          command: "$HOME/.claude/scripts/restrict-researcher.sh"
+    - matcher: "Glob"
+      hooks:
+        - type: command
+          command: "$HOME/.claude/scripts/restrict-researcher.sh"
 ---
 
-You are an objective codebase researcher. You receive questions about a codebase and answer them by exploring the code.
+You are an objective codebase researcher. You receive questions about a codebase and answer them by exploring the source code.
 
-## Critical Rule
-
-You do NOT know what feature is being built. You only have questions. Answer them factually.
+You do NOT know what feature is being built. You only have questions. Answer them factually by reading source code.
 
 - Report what EXISTS, not what SHOULD exist
 - Do not suggest implementations or improvements
 - Do not speculate about what someone might want to build
 - If you find multiple patterns for the same thing, report ALL of them with locations
 - If a question cannot be answered from the codebase, say so explicitly
+- Explore source code only — not documentation, READMEs, or markdown files in docs/
 
 ## Process
 

package/src/agents/question-generator.md

@@ -19,52 +19,34 @@ hooks:
 
 You are a question generator. You read a feature intent document and produce research questions that a senior engineer would need answered about the codebase before implementing this feature.
 
-## Your Role
-
-You generate questions. You do NOT:
-
-- Research or explore the codebase (you have no search tools)
-- Suggest implementations or architectural decisions
-- Write code or pseudocode
-- Speculate about how the codebase might work
+You generate questions only. You cannot explore the codebase, suggest implementations, write code, or speculate about how the codebase works.
 
 ## Process
 
 1. Read the intent document at the path provided in your prompt
-2. Think about what a senior engineer would need to know about the codebase before they could implement this
+2. Think deeply about what you'd need to know to actually build this — not just what the system looks like, but how you'd hook into it
 3. Write organized, specific questions to the output path provided
 
-## Output Format
+## Thinking Lenses
 
-Write a markdown file with questions organized by category:
+Go beyond "what exists" questions. Apply these lenses:
 
-```markdown
-# Research Questions
+**Integration seams** — Where would this feature plug into the existing system? What hooks, extension points, callbacks, event systems, or middleware would you need? How does the system currently propagate changes, and can you intercept or extend that flow?
 
-## Existing Patterns
-- How does the codebase currently handle {relevant functionality}?
-- What patterns are used for {similar features}?
-- Are there existing utilities or helpers for {relevant operations}?
+**Identity and addressing** — How are the entities this feature touches identified, referenced, and addressed? What are their keys, IDs, or paths? What happens to identity when entities are created, split, merged, moved, or deleted?
 
-## Data Model
-- What data structures exist for {relevant entities}?
-- How is {relevant data} currently stored and accessed?
+**Implicit contracts** — What assumptions does the existing code likely make that this feature might violate? What invariants exist around data shape, ordering, uniqueness, or lifecycle? What would break if two users did the same thing simultaneously?
 
-## Integration Points
-- What services or modules would this feature interact with?
-- Are there existing APIs or interfaces it should conform to?
+**Data flow and mutation** — How does data currently flow from user action → state change → persistence → UI update? Can you inject operations into that flow, or do you have to replace it? Is state management pull-based or push-based?
 
-## Testing Infrastructure
-- What testing patterns does the project use for {relevant scenarios}?
-- What test runners and frameworks are configured?
+**Failure and recovery** — What happens when this feature partially fails? What are the rollback semantics? How does the system currently handle the degraded versions of what this feature introduces?
+
+## Output Format
 
-## Dependencies
-- Are there existing libraries in the project for {relevant functionality}?
-- What versions of key frameworks are in use?
-```
+Write a markdown file with questions organized by category. Derive categories from the feature — they should reflect the actual problem domains, not generic buckets.
 
 Each question must be:
 
 - **Specific**: "How does the auth module handle session tokens?" not "How does auth work?"
 - **Codebase-answerable**: Answerable by reading project files, not by asking the user
-- **Relevant**: Directly related to implementing the feature described in the intent
+- **Deep**: Prioritize "how would I hook into X" over "what does X look like"

package/src/scripts/restrict-researcher.sh

@@ -0,0 +1,49 @@
+#!/bin/bash
+# Restricts objective-researcher from reading docs/intent or any documentation.
+# The researcher must answer questions by exploring CODE, not documentation.
+# It can only read questions.md (input) and write research.md (output) in docs/specs/.
+# Receives JSON on stdin with tool_name and tool_input.
+
+input=$(cat)
+tool_name=$(echo "$input" | jq -r '.tool_name // empty')
+file_path=$(echo "$input" | jq -r '.tool_input.file_path // empty')
+search_path=$(echo "$input" | jq -r '.tool_input.path // empty')
+
+# Write/Edit: only allow research.md in docs/specs/
+if [[ "$tool_name" == "Write" || "$tool_name" == "Edit" ]]; then
+  if [[ "$file_path" == */docs/specs/*/research.md ]]; then
+    exit 0
+  fi
+  cat << 'EOF'
+{"permissionDecision":"deny","message":"Write access restricted to research.md only."}
+EOF
+  exit 0
+fi
+
+# Read: allow questions.md, block everything else in docs/
+if [[ "$tool_name" == "Read" ]]; then
+  if [[ "$file_path" == */docs/specs/*/questions.md ]]; then
+    exit 0
+  fi
+  if [[ "$file_path" == */docs/* ]]; then
+    cat << 'EOF'
+{"permissionDecision":"deny","message":"Cannot read documentation. Research the codebase source code only — not docs, READMEs, or intent files."}
+EOF
+    exit 0
+  fi
+  exit 0
+fi
+
+# Grep/Glob: block if searching inside docs/
+if [[ "$tool_name" == "Grep" || "$tool_name" == "Glob" ]]; then
+  if [[ "$search_path" == */docs/* || "$search_path" == */docs ]]; then
+    cat << 'EOF'
+{"permissionDecision":"deny","message":"Cannot search documentation. Research the codebase source code only."}
+EOF
+    exit 0
+  fi
+  exit 0
+fi
+
+# Allow everything else
+exit 0

package/src/scripts/restrict-to-spec-dir.sh

@@ -1,23 +1,43 @@
 #!/bin/bash
-# Restricts Read/Write operations to the docs/specs/ directory.
-# Used by question-generator sub-agent to prevent codebase exploration.
+# Restricts question-generator to only reading intent.md and writing questions.md.
 # Receives JSON on stdin with tool_name and tool_input.
 
 input=$(cat)
+tool_name=$(echo "$input" | jq -r '.tool_name // empty')
 file_path=$(echo "$input" | jq -r '.tool_input.file_path // empty')
 
-# If no file_path in the tool input, allow the operation
+# If no file_path in the tool input, deny (shouldn't happen for Read/Write)
 if [ -z "$file_path" ]; then
+  cat << 'EOF'
+{"permissionDecision":"deny","message":"No file path provided."}
+EOF
+  exit 0
+fi
+
+# Read: only allow intent.md within docs/specs/
+if [[ "$tool_name" == "Read" ]]; then
+  if [[ "$file_path" == */docs/specs/*/intent.md ]]; then
+    exit 0
+  fi
+  cat << 'EOF'
+{"permissionDecision":"deny","message":"Read access restricted to intent.md only. You generate questions from the intent — do not explore the codebase."}
+EOF
   exit 0
 fi
 
-# Allow access to docs/specs/ directory
-if [[ "$file_path" == *"/docs/specs/"* ]]; then
+# Write: only allow questions.md within docs/specs/
+if [[ "$tool_name" == "Write" ]]; then
+  if [[ "$file_path" == */docs/specs/*/questions.md ]]; then
+    exit 0
+  fi
+  cat << 'EOF'
+{"permissionDecision":"deny","message":"Write access restricted to questions.md only."}
+EOF
   exit 0
 fi
 
-# Deny everything else
+# Deny anything else
 cat << 'EOF'
-{"permissionDecision":"deny","message":"Access restricted to docs/specs/ directory only."}
+{"permissionDecision":"deny","message":"Access restricted to intent.md (read) and questions.md (write) only."}
 EOF
 exit 0

package/src/skills/ignore-config/SKILL.md

@@ -0,0 +1,14 @@
+---
+name: ignore-config
+description: Analyze a project and recommend a .claudeignore file. Use when setting up or updating .claudeignore to exclude git-tracked files that aren't useful for Claude.
+disable-model-invocation: true
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
+---
+
+# Claudeignore
+
+Analyze the current project and recommend a `.claudeignore` configuration.
+
+`.claudeignore` excludes files from Claude's indexing. Since `.gitignore` is already respected, `.claudeignore` targets **git-tracked files** that aren't useful for Claude — lock files, large generated assets, binary files, fixture data, etc.
+
+Use the Read tool on `references/step-1-analyze.md` to begin the analysis.

package/src/skills/ignore-config/references/step-1-analyze.md

@@ -0,0 +1,32 @@
+# Step 1: Analyze the Project
+
+## Check Existing State
+
+1. Check if `.claudeignore` already exists. If it does, read it — this is an update flow, and recommendations should complement what's already there.
+2. Check `.gitignore` to understand what's already excluded from Claude's view.
+
+## Scan for Candidates
+
+Run `git ls-files` and identify tracked files that are poor candidates for Claude's context. Focus on:
+
+- **Lock files** — dependency locks are large and not useful for understanding code (package-lock.json, yarn.lock, pnpm-lock.yaml, Gemfile.lock, poetry.lock, Cargo.lock, composer.lock, etc.)
+- **Generated/compiled assets** — minified JS/CSS, source maps, bundled output, compiled protobuf, auto-generated code committed to the repo
+- **Binary files** — images, fonts, compiled binaries, archives, database files
+- **Large data files** — fixtures, seed data, snapshots, migration dumps, sample datasets
+- **Vendored dependencies** — committed vendor/ or third-party directories
+
+Use file size as a signal — find the largest tracked files to surface high-impact candidates.
+
+## Present Recommendations
+
+Group findings by category. For each recommendation, include:
+
+- The pattern (e.g., `package-lock.json`, `*.min.js`, `vendor/`)
+- Why it's not useful for Claude
+- The file size or count impact
+
+If the project is small and clean with nothing worth ignoring, say so — a `.claudeignore` isn't always needed.
+
+If there is an existing `.claudeignore`, highlight only new recommendations not already covered.
+
+Present the recommendations and ask the user which patterns to include. Use the Read tool on `references/step-2-create.md` to create the file based on their decisions.

package/src/skills/ignore-config/references/step-2-create.md

@@ -0,0 +1,20 @@
+# Step 2: Create the File
+
+Based on the user's selections, write the `.claudeignore` file.
+
+## Format
+
+- Group patterns by category with comment headers
+- Add a brief comment at the top explaining the file's purpose
+- One pattern per line
+- Keep it clean — match `.gitignore` conventions
+
+## If Updating
+
+Read the existing `.claudeignore` and merge. Place new patterns in the appropriate category sections. Avoid duplicates.
+
+## After Writing
+
+Show the user the final file contents and confirm it looks right. If they want changes, apply them.
+
+Use the Read tool on `references/step-3-reflect.md` to review your work and report results to the user.

package/src/skills/ignore-config/references/step-3-reflect.md

@@ -0,0 +1,18 @@
+# Step 3: Reflect
+
+Review how this skill performed.
+
+## Assessment
+
+- Were the scan heuristics effective? Did they catch the right files, or miss obvious candidates?
+- Were any recommendations wrong — patterns that would have excluded files Claude actually needs?
+- Did the category groupings make sense for this project type?
+- Was the file size scan command effective, or did it need adjustment?
+
+## Action
+
+If any instructions were wrong, incomplete, or misleading, identify the specific file where the issue lives, read it, and apply the fix. Only add knowledge a fresh Claude instance would not already have.
+
+## Report
+
+Tell the user what was created and summarize the impact (approximate number of files/size excluded from Claude's context). If skill files were updated, explain what changed and why.