cc-dev-template 0.1.81 → 0.1.82

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.82",
   "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,52 @@
+---
+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
+---
+
+You are an objective codebase researcher. You receive questions about a codebase and answer them by exploring the code.
+
+## Critical Rule
+
+You do NOT know what feature is being built. You only have questions. Answer them factually.
+
+- 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
+
+## 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,70 @@
+---
+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.
+
+## 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
+
+## 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
+3. Write organized, specific questions to the output path provided
+
+## Output Format
+
+Write a markdown file with questions organized by category:
+
+```markdown
+# Research Questions
+
+## 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}?
+
+## Data Model
+- What data structures exist for {relevant entities}?
+- How is {relevant data} currently stored and accessed?
+
+## Integration Points
+- What services or modules would this feature interact with?
+- Are there existing APIs or interfaces it should conform to?
+
+## Testing Infrastructure
+- What testing patterns does the project use for {relevant scenarios}?
+- What test runners and frameworks are configured?
+
+## Dependencies
+- Are there existing libraries in the project for {relevant functionality}?
+- What versions of key frameworks are in use?
+```
+
+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

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

@@ -0,0 +1,23 @@
+#!/bin/bash
+# Restricts Read/Write operations to the docs/specs/ directory.
+# Used by question-generator sub-agent to prevent codebase exploration.
+# Receives JSON on stdin with tool_name and tool_input.
+
+input=$(cat)
+file_path=$(echo "$input" | jq -r '.tool_input.file_path // empty')
+
+# If no file_path in the tool input, allow the operation
+if [ -z "$file_path" ]; then
+  exit 0
+fi
+
+# Allow access to docs/specs/ directory
+if [[ "$file_path" == *"/docs/specs/"* ]]; then
+  exit 0
+fi
+
+# Deny everything else
+cat << 'EOF'
+{"permissionDecision":"deny","message":"Access restricted to docs/specs/ directory only."}
+EOF
+exit 0

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.

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

@@ -0,0 +1,86 @@
+# Spec Generation
+
+These are drafts — you will review, refine, and present the spec to the user before proceeding.
+
+Generate an implementation-ready specification from the intent, research, and design decisions. Read all three documents before writing:
+
+- `{spec_dir}/intent.md`
+- `{spec_dir}/research.md`
+- `{spec_dir}/design.md`
+
+## Create Tasks
+
+Create these tasks and work through them in order:
+
+1. "Conduct any needed external research" — resolve open items from design.md
+2. "Write spec.md" — generate the specification
+3. "Review spec with user" — present and refine
+4. "Begin task breakdown" — proceed to the next phase
+
+## Task 1: External Research (if needed)
+
+Check `{spec_dir}/design.md` for open items. If any require research into external libraries, frameworks, or paradigms:
+
+```
+Agent tool:
+  subagent_type: "general-purpose"
+  prompt: "Research {topic}. Write findings to {spec_dir}/research-{topic-slug}.md. Focus on: API surface, integration patterns, gotchas, and typical usage."
+  model: "sonnet"
+```
+
+Skip this task if there are no open items.
+
+## Task 2: Write spec.md
+
+Write `{spec_dir}/spec.md` using this structure:
+
+```markdown
+# Spec: {Feature Name}
+
+## Overview
+{What this feature does, 2-3 sentences}
+
+## Data Model
+{New or modified data structures, schemas, types}
+
+## API Contracts
+{Endpoints, function signatures, input/output shapes — specific enough that tests can be written against these contracts}
+
+## Integration Points
+{How this feature connects to existing systems — which files, which patterns, which services. Reference specific code from research.md.}
+
+## Acceptance Criteria
+
+### AC-1: {Criterion name}
+- **Given**: {precondition}
+- **When**: {action}
+- **Then**: {expected result}
+- **Verification**: {how to test — unit test, integration test, manual check}
+
+### AC-2: ...
+
+## Implementation Notes
+{Patterns to follow from design.md, ordering considerations, things to watch out for}
+
+## Out of Scope
+{Explicitly what this feature does NOT do}
+```
+
+The acceptance criteria and API contracts are the most important sections. They must be specific enough that an agent can write tests against them without additional context.
+
+## Task 3: Review Spec
+
+Present the full spec to the user. Walk through each section. Pay particular attention to:
+
+- Are the API contracts correct and complete?
+- Are the acceptance criteria independently testable?
+- Are the integration points accurate (grounded in the research)?
+- Anything missing or out of scope that should be in scope?
+
+Revise based on user feedback.
+
+## Task 4: Proceed
+
+Update `{spec_dir}/state.yaml` — set `phase: tasks`.
+
+Use the Read tool on `references/step-6-tasks.md` to break the spec into implementation tasks.

package/src/skills/ship/references/step-6-tasks.md

@@ -0,0 +1,83 @@
+# Task Breakdown
+
+These task files are a first draft — you will review and refine them with the user before proceeding to implementation.
+
+Break the spec into implementation tasks ordered as tracer bullets — vertical slices through the stack, not horizontal layers.
+
+Read `{spec_dir}/spec.md` before proceeding.
+
+## Create Tasks
+
+Create these tasks and work through them in order:
+
+1. "Design tracer bullet task ordering" — plan the vertical implementation order
+2. "Write task files" — create individual task files
+3. "Review tasks with user" — present and refine
+4. "Begin implementation" — proceed to the next phase
+
+## Task 1: Design Task Ordering
+
+Do NOT create horizontal plans. A horizontal plan looks like:
+
+- Task 1: Create all database models
+- Task 2: Create all service layer functions
+- Task 3: Create all API endpoints
+- Task 4: Create all frontend components
+
+Nothing is testable until the end.
+
+Instead, create **vertical / tracer bullet** ordering:
+
+- Task 1: Wire end-to-end with mock data (create the endpoint, return hardcoded data, render a placeholder in the UI)
+- Task 2: Add real data layer for the first acceptance criterion
+- Task 3: Add real logic for the second acceptance criterion
+- ...
+
+Each task touches all necessary layers of the stack and produces something independently testable.
+
+Map each acceptance criterion from the spec to one or more tasks. Every AC must be covered.
+
+## Task 2: Write Task Files
+
+Create `{spec_dir}/tasks/` directory. Write one file per task.
+
+`{spec_dir}/tasks/T001-{short-name}.md`:
+
+```yaml
+---
+id: T001
+title: {Short descriptive title}
+status: pending
+depends_on: []
+---
+```
+
+### Criterion
+{Which acceptance criterion this task addresses}
+
+### Files
+{Which files will be created or modified, with brief description of changes}
+
+### Verification
+{How to verify this task is done — specific test commands, manual checks}
+
+### Implementation Notes
+{Patterns to follow, edge cases, things to watch out for}
+
+Include testing in each task — not as a separate task at the end. If a task adds a feature, the same task adds the test for that feature.
+
+## Task 3: Review Tasks
+
+Present the task breakdown to the user. For each task, show:
+
+- What it does
+- Why it's in this order (the vertical reasoning)
+- How it can be independently verified
+
+Revise based on user feedback.
+
+## Task 4: Proceed
+
+Update `{spec_dir}/state.yaml` — set `phase: implement`.
+
+Use the Read tool on `references/step-7-implement.md` to begin implementation.

package/src/skills/ship/references/step-7-implement.md

@@ -0,0 +1,61 @@
+# Implementation
+
+Orchestrate implementation using spec-implementer and spec-validator sub-agents. This follows the execute-spec pattern — you dispatch agents, you do not write code yourself.
+
+Read `{spec_dir}/spec.md` and list all task files in `{spec_dir}/tasks/`.
+
+## Create Tasks
+
+Create these tasks and work through them in order:
+
+1. "Hydrate task system" — load task files into Claude Code's task system
+2. "Implement tasks" — dispatch implementer agents
+3. "Validate tasks" — dispatch validator agents
+4. "Handle failures" — triage and re-attempt if needed
+5. "Finalize" — present results
+
+## Task 1: Hydrate
+
+Read each task file in `{spec_dir}/tasks/`. For each one, create a Claude Code task (TaskCreate) with the task title and description. Set up `blockedBy` relationships based on the `depends_on` field in each task file's frontmatter.
+
+## Task 2: Implement
+
+For each task that is ready (no blockers), dispatch an implementer:
+
+```
+Agent tool:
+  subagent_type: "spec-implementer"
+  prompt: "Implement the task described in {task_file_path}. Read the task file for requirements, files to modify, and verification steps. Also read {spec_dir}/spec.md for overall context. After implementation, run the verification steps described in the task file."
+```
+
+Run independent tasks in parallel when possible. Mark each Claude Code task as completed when its implementer finishes successfully.
+
+## Task 3: Validate
+
+For each completed task, dispatch a validator:
+
+```
+Agent tool:
+  subagent_type: "spec-validator"
+  prompt: "Validate the task described in {task_file_path}. Review the code changes, run tests, and verify against the acceptance criteria in {spec_dir}/spec.md. Report pass/fail with details."
+```
+
+## Task 4: Handle Failures
+
+If any validation fails:
+
+- Re-dispatch the spec-implementer with the validation feedback appended to the prompt
+- Re-validate after fixes
+- If a task fails validation twice, flag it for the user with the error details and ask how to proceed
+
+## Task 5: Finalize
+
+Update `{spec_dir}/state.yaml` — set `phase: complete`.
+
+Present a summary to the user:
+
+- What was implemented
+- What tests pass
+- Any tasks that needed manual intervention
+
+Use the Read tool on `references/step-8-reflect.md` to review and improve this workflow.

package/src/skills/ship/references/step-8-reflect.md

@@ -0,0 +1,21 @@
+# Reflect
+
+Review how this workflow performed and identify improvements.
+
+## Self-Assessment
+
+Consider each phase:
+
+1. **Intent capture**: Did the intent document accurately capture what the user wanted? Did the spec drift from the original intent?
+2. **Question quality**: Were the research questions comprehensive? Were any critical questions missing that caused problems later?
+3. **Research objectivity**: Did the research stay objective? Did the contamination prevention work — or did implementation opinions leak in despite the separation?
+4. **Design decisions**: Were the design questions the right ones? Did the user have to course-correct on things that should have been caught earlier?
+5. **Spec completeness**: Were the API contracts and acceptance criteria specific enough for implementation agents?
+6. **Task ordering**: Did the tracer bullet ordering work? Were there dependency issues or tasks that should have been ordered differently?
+7. **Implementation**: Did agents struggle with any tasks? Were the task descriptions clear enough?
+
+## Skill Improvement
+
+If you identified concrete improvements to this workflow, edit the relevant step file in `references/` to address the issue. Only make changes that are clearly beneficial based on this session's experience — do not speculate about hypothetical improvements.
+
+Present your reflection and any changes to the user.