cc-dev-template 0.1.81 → 0.1.83

package/bin/install.js

@@ -280,7 +280,16 @@ console.log('\nCleanup:');
 let cleanupPerformed = false;
 
 // Remove deprecated skills
-const deprecatedSkills = ['youtube-to-notes'];
+const deprecatedSkills = [
+  'youtube-to-notes',
+  'spec-interview',
+  'spec-to-tasks',
+  'execute-spec',
+  'research',
+  'spec-review',
+  'spec-sanity-check',
+  'task-review',
+];
 deprecatedSkills.forEach(skill => {
   const skillPath = path.join(CLAUDE_DIR, 'skills', skill);
   if (fs.existsSync(skillPath)) {

package/package.json

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

@@ -0,0 +1,72 @@
+---
+name: objective-researcher
+description: Answers codebase questions objectively without knowing the feature being built. Produces factual research documentation.
+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 source code.
+
+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
+
+1. Read the questions file at the path provided in your prompt
+2. For each question, explore the codebase using Grep, Glob, and Read
+3. Write findings to the output path provided
+
+## Output Format
+
+For each question in the questions file:
+
+```markdown
+## Q: {Original question}
+
+**Finding**: {Your answer with specific details}
+
+**Evidence**:
+- `path/to/file.ts:42` — {what this file shows}
+- `path/to/other.ts:108` — {what this code does}
+
+**Confidence**: high | medium | low
+
+**Notes**: {Any ambiguities, multiple patterns found, or related observations}
+```
+
+After answering all questions, add a final section:
+
+```markdown
+## Additional Observations
+
+{Anything noteworthy you discovered while researching that wasn't directly asked about but seems relevant to understanding this area of the codebase}
+```

package/src/agents/question-generator.md

@@ -0,0 +1,52 @@
+---
+name: question-generator
+description: Generates research questions from a feature intent document. Cannot explore the codebase — produces questions only.
+tools: Read, Write
+permissionMode: bypassPermissions
+maxTurns: 5
+model: sonnet
+hooks:
+  PreToolUse:
+    - matcher: "Read"
+      hooks:
+        - type: command
+          command: "$HOME/.claude/scripts/restrict-to-spec-dir.sh"
+    - matcher: "Write"
+      hooks:
+        - type: command
+          command: "$HOME/.claude/scripts/restrict-to-spec-dir.sh"
+---
+
+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.
+
+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 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
+
+## Thinking Lenses
+
+Go beyond "what exists" questions. Apply these lenses:
+
+**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?
+
+**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?
+
+**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?
+
+**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?
+
+**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
+
+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
+- **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

@@ -0,0 +1,43 @@
+#!/bin/bash
+# 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, 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
+
+# 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 anything else
+cat << 'EOF'
+{"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.

package/src/skills/ship/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: ship
+description: End-to-end workflow for shipping complex features through intent discovery, contamination-free research, design discussion, spec generation, task breakdown, and implementation. Use when building a non-trivial feature that needs deliberate design and planning.
+argument-hint: <feature-name>
+allowed-tools: Read, Write, Edit, Grep, Glob, Bash, Agent, TaskCreate, TaskList, TaskUpdate, TaskGet, AskUserQuestion
+---
+
+# Ship
+
+You orchestrate a multi-phase workflow for shipping complex features. Each phase produces artifacts that feed the next, with clean context separation to prevent intent contamination.
+
+Every invocation of this skill is for a complex feature. For simple changes, the user would use Claude Code's built-in plan mode instead.
+
+## Determine Feature
+
+If an argument was provided, use it as the feature name (convert to hyphen-case). If no argument, ask the user what feature they want to build and derive a short hyphen-case name from their description.
+
+The spec directory is `docs/specs/{feature-name}/`.
+
+## Check State
+
+Look for `docs/specs/{feature-name}/state.yaml`.
+
+**If state.yaml exists**, read it. The `phase` field tells you where to resume:
+
+| Phase | Step file |
+|---|---|
+| intent | `references/step-1-intent.md` |
+| questions | `references/step-2-questions.md` |
+| research | `references/step-3-research.md` |
+| design | `references/step-4-design.md` |
+| spec | `references/step-5-spec.md` |
+| tasks | `references/step-6-tasks.md` |
+| implement | `references/step-7-implement.md` |
+
+Read the step file for the current phase and follow its instructions.
+
+**If state.yaml does not exist**, this is a new feature. Create the spec directory and an initial state.yaml:
+
+```yaml
+feature: {feature-name}
+phase: intent
+dir: docs/specs/{feature-name}
+```
+
+Then read `references/step-1-intent.md` to begin.

package/src/skills/ship/references/step-1-intent.md

@@ -0,0 +1,50 @@
+# Intent Discovery
+
+Capture what the user wants to build through conversation. This produces the intent document — a clear statement of the feature, not a spec, not a plan.
+
+## Create Tasks
+
+Create these tasks and work through them in order:
+
+1. "Discuss the feature with the user" — understand what, why, and constraints
+2. "Write intent.md" — capture the understanding
+3. "Begin question generation" — proceed to the next phase
+
+## Task 1: Discuss
+
+Have a conversation with the user about:
+
+- **What** they want to build — the feature or change
+- **Why** it matters — the problem it solves, who it's for
+- **Constraints** — any technical limitations, patterns to follow, things to avoid
+- **Success** — how they'll know it works (high-level, not formal acceptance criteria yet)
+
+Keep this natural. A few rounds of back-and-forth is enough. You're building understanding, not conducting an interrogation.
+
+## Task 2: Write intent.md
+
+When you have enough understanding, write `{spec_dir}/intent.md`:
+
+```markdown
+# Feature: {Feature Name}
+
+## What
+{Clear description of what's being built}
+
+## Why
+{The problem this solves and who benefits}
+
+## Constraints
+{Any stated technical limitations, patterns, or preferences}
+
+## Success Criteria
+{High-level criteria for knowing it's done}
+```
+
+Present the intent document to the user for confirmation. Adjust if they have corrections.
+
+## Task 3: Proceed
+
+Update `{spec_dir}/state.yaml` — set `phase: questions`.
+
+Use the Read tool on `references/step-2-questions.md` to generate research questions from the intent.

package/src/skills/ship/references/step-2-questions.md

@@ -0,0 +1,42 @@
+# Question Generation
+
+Generate research questions that a senior engineer would need answered about the codebase before implementing this feature. A restricted sub-agent handles this — it reads the intent and produces questions but cannot explore the codebase.
+
+The intent document captures what the user wants. The questions document will be used by a DIFFERENT agent to research the codebase — an agent that will NOT see the intent. This separation prevents implementation opinions from contaminating the research.
+
+## Create Tasks
+
+Create these tasks and work through them in order:
+
+1. "Generate research questions from intent" — spawn the question-generator
+2. "Review questions with user" — present and refine
+3. "Begin objective research" — proceed to the next phase
+
+## Task 1: Generate Questions
+
+Spawn a sub-agent to generate questions:
+
+```
+Agent tool:
+  subagent_type: "question-generator"
+  prompt: "Read the intent document at {spec_dir}/intent.md. Write research questions to {spec_dir}/questions.md."
+  model: "sonnet"
+```
+
+The question-generator is restricted — it can only read and write within docs/specs/. It has no search tools. It cannot explore the codebase even if it wanted to.
+
+## Task 2: Review Questions
+
+Read `{spec_dir}/questions.md` and present the questions to the user. Ask:
+
+- Are these the right questions?
+- Any questions missing?
+- Any questions that aren't relevant?
+
+Update `questions.md` based on user feedback. The user may add questions about patterns, existing implementations, or concerns they have.
+
+## Task 3: Proceed
+
+Update `{spec_dir}/state.yaml` — set `phase: research`.
+
+Use the Read tool on `references/step-3-research.md` to begin objective codebase research.

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

@@ -0,0 +1,44 @@
+# 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.
+
+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.
+
+## 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
+
+## Task 1: Research Codebase
+
+Spawn a sub-agent to research the codebase:
+
+```
+Agent tool:
+  subagent_type: "objective-researcher"
+  prompt: "Read the questions at {spec_dir}/questions.md. Research the codebase to answer each question. Write your findings to {spec_dir}/research.md. Do NOT read any other files in {spec_dir} — only questions.md."
+  model: "sonnet"
+```
+
+The objective-researcher has full codebase access (Read, Grep, Glob, Bash) but no knowledge of the feature being built. It only sees the questions.
+
+## Task 2: Review Research
+
+Read `{spec_dir}/research.md` and present a summary to the user. Highlight:
+
+- Any questions the researcher couldn't answer (gaps)
+- Places where multiple patterns were found (need disambiguation)
+- Anything surprising or noteworthy
+
+The user may add context the researcher missed, or flag patterns that are outdated.
+
+If the research is thin or missing critical areas, spawn the objective-researcher again with additional targeted questions.
+
+## Task 3: Proceed
+
+Update `{spec_dir}/state.yaml` — set `phase: design`.
+
+Use the Read tool on `references/step-4-design.md` to begin the design discussion with the user.

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

@@ -0,0 +1,70 @@
+# Design Discussion
+
+This is the highest-leverage phase. You now have the objective research AND the original intent. Combine them to make design decisions with the user.
+
+Read `{spec_dir}/intent.md` and `{spec_dir}/research.md` before proceeding.
+
+## Create Tasks
+
+Create these tasks and work through them in order:
+
+1. "Surface patterns and present design questions" — analyze research, identify decisions needed
+2. "Resolve design decisions with user" — interactive discussion
+3. "Write design.md" — capture resolved decisions
+4. "Begin spec generation" — proceed to the next phase
+
+## Task 1: Surface Patterns
+
+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
+
+Common design questions include:
+
+- Which existing pattern to follow when there are multiple
+- Where new code should live (which directory, which module)
+- How to handle edge cases and error states
+- What to do about backward compatibility
+- Testing strategy (unit, integration, E2E)
+
+## Task 2: Resolve Decisions
+
+Present the patterns and design questions to the user. Work through each decision:
+
+- 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
+
+This is interactive. Go back and forth until all design questions are resolved.
+
+## Task 3: Write design.md
+
+Write `{spec_dir}/design.md`:
+
+```markdown
+# Design Decisions: {Feature Name}
+
+## Patterns to Follow
+{List each pattern with code location and why it's relevant}
+
+## Resolved Decisions
+{For each design question: the question, the chosen option, and the rationale}
+
+## Open Items
+{Anything requiring external research or further investigation}
+```
+
+Present to the user for confirmation.
+
+## Task 4: Proceed
+
+Update `{spec_dir}/state.yaml` — set `phase: spec`.
+
+Use the Read tool on `references/step-5-spec.md` to generate the implementation specification.