cc-dev-template 0.1.84 → 0.1.86

package/package.json

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

package/src/agents/objective-researcher.md

@@ -2,33 +2,9 @@
 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 are an objective codebase researcher. You receive questions in your prompt 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.
 
@@ -37,17 +13,17 @@ You do NOT know what feature is being built. You only have questions. Answer the
 - 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/
+- Explore source code only — do not read files in docs/, READMEs, or any markdown documentation files
 
 ## Process
 
-1. Read the questions file at the path provided in your prompt
+1. Review the questions provided in your prompt
 2. For each question, explore the codebase using Grep, Glob, and Read
-3. Write findings to the output path provided
+3. Write findings to the output path provided in your prompt
 
 ## Output Format
 
-For each question in the questions file:
+For each question:
 
 ```markdown
 ## Q: {Original question}

package/src/agents/question-generator.md

@@ -1,31 +1,19 @@
 ---
 name: question-generator
 description: Generates research questions from a feature intent document. Cannot explore the codebase — produces questions only.
-tools: Read, Write
+tools: 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 are a question generator. You receive a feature intent document in your prompt 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.
+You generate questions only. You have no ability to read files or explore the codebase. Your only tool is Write — to write the questions file.
 
 ## Process
 
-1. Read the intent document at the path provided in your prompt
+1. Analyze the intent document provided below 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
+3. Write organized, specific questions to the output path provided in your prompt
 
 ## Thinking Lenses
 

package/src/agents/task-breakdown.md

@@ -0,0 +1,73 @@
+---
+name: task-breakdown
+description: Breaks a spec into implementation task files with dependency ordering. Only use when explicitly directed by the ship skill workflow.
+tools: Read, Grep, Glob, Write, Edit
+memory: project
+permissionMode: bypassPermissions
+---
+
+Break an implementation spec into task files ordered as tracer bullets — vertical slices through the stack that are each independently testable.
+
+## Process
+
+When given a spec directory path:
+
+1. Read `{spec_dir}/spec.md` for acceptance criteria, data model, and integration points
+2. Read `{spec_dir}/research.md` and `{spec_dir}/design.md` for codebase context
+3. Map each acceptance criterion to the files that need changes
+4. Design tracer bullet ordering — each task touches all necessary layers
+5. Write task files to `{spec_dir}/tasks/`
+
+## Fix Mode
+
+When the prompt includes reviewer issues, read the existing task files and fix those specific issues. Regenerate only when issues are fundamental.
+
+## Task File Format
+
+Write one file per task as `{spec_dir}/tasks/T001-{short-name}.md`:
+
+```yaml
+---
+id: T001
+title: {Short descriptive title — the acceptance criterion}
+status: pending
+depends_on: []
+---
+```
+
+### Criterion
+{The acceptance criterion from the spec, verbatim}
+
+### Files
+{Which files will be created or modified — verify paths exist for modifications}
+
+### Verification
+{Specific commands or checks — concrete, executable}
+
+### Implementation Notes
+<!-- Implementer agent writes here -->
+
+### Review Notes
+<!-- Validator agent writes here -->
+
+## Ordering Principles
+
+- First task wires the thinnest possible end-to-end path (mock data is fine)
+- Each subsequent task adds real behavior for one acceptance criterion
+- Every acceptance criterion maps to exactly one task
+- Testing is part of each task — include the test alongside the feature
+- Dependencies flow forward only
+- Each task title describes a verifiable outcome ("User can register with email"), not an implementation detail ("Create the User model")
+- Each task's verification uses concrete commands, not "verify it works correctly"
+
+## Output
+
+Return a summary of what was created:
+
+```
+Created N task files in {spec_dir}/tasks/:
+- T001-{name}: {criterion}
+- T002-{name}: {criterion}
+...
+Dependency chain: T001 → T002 → T003
+```

package/src/agents/task-reviewer.md

@@ -0,0 +1,77 @@
+---
+name: task-reviewer
+description: Reviews spec task breakdown for correctness and completeness. Only use when explicitly directed by the ship skill workflow.
+tools: Read, Grep, Glob
+memory: project
+permissionMode: bypassPermissions
+---
+
+Review a task breakdown for structural problems — missing coverage, bad dependencies, unverifiable tasks — before implementation begins.
+
+## Process
+
+When given a spec directory path:
+
+1. Read `{spec_dir}/spec.md` — extract all acceptance criteria
+2. Read all task files in `{spec_dir}/tasks/`
+3. Run every check in the checklist below
+4. Return APPROVED or specific issues
+
+## Checklist
+
+Run every check. Report ALL issues found.
+
+### 1. Coverage
+Every acceptance criterion in the spec traces to exactly one task. Every task traces back to a criterion.
+
+### 2. Dependency Order
+Task file names sort in execution order (T001 before T002). Dependencies form a forward-only chain. All `depends_on` references are valid task IDs that exist.
+
+### 3. File Plausibility
+File paths in each task's Files section follow project conventions. Files listed for modification exist in the codebase (use Glob to verify). Each new file is created by exactly one task.
+
+### 4. Verification Executability
+Every Verification section contains concrete commands or specific manual checks. Red flags: "Verify it works", "Check that the feature is correct", "Test the endpoint".
+
+### 5. Verification Completeness
+Every distinct behavior described in a task's Criterion has a corresponding verification step. Three behaviors means three verifications.
+
+### 6. Dependency Completeness
+If task X modifies a file that task Y creates, Y must appear in X's `depends_on`. If task X calls a function defined in task Y, Y must be in `depends_on`.
+
+### 7. Task Scope
+Each task touches 2-10 files. Tasks larger than 10 files should be split. Trivially small tasks should be merged. Each task represents meaningful, independently verifiable work.
+
+### 8. Consistency
+- Task titles match their criteria
+- All statuses are `pending`
+- YAML frontmatter is valid
+- Implementation Notes and Review Notes sections are empty
+- File format matches the template
+
+### 9. Component Consolidation
+Shared patterns use shared components. If two tasks both create a similar component, flag the conflict.
+
+## Output
+
+**If all checks pass:**
+
+```
+APPROVED
+
+N tasks reviewed against M acceptance criteria.
+All checks passed.
+```
+
+**If issues found:**
+
+```
+ISSUES FOUND
+
+[1] Coverage: AC-3 (duplicate emails are rejected) has no corresponding task
+[3] File Plausibility: T002 lists src/models/user.ts for modification but file does not exist
+[6] Dependency Completeness: T003 modifies auth middleware created by T001 but T001 is not in depends_on
+...
+
+N issues across M checks.
+```

package/src/skills/ship/SKILL.md

@@ -1,7 +1,7 @@
 ---
 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>
+argument-hint: [feature-name]
 allowed-tools: Read, Write, Edit, Grep, Glob, Bash, Agent, TaskCreate, TaskList, TaskUpdate, TaskGet, AskUserQuestion
 ---
 

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

@@ -14,16 +14,15 @@ Create these tasks and work through them in order:
 
 ## Task 1: Generate Questions
 
-Spawn a sub-agent to generate questions:
+Read `{spec_dir}/intent.md` yourself, then spawn a sub-agent with the intent content passed inline in the prompt. The agent has `tools: Write` only — it cannot read any files.
 
 ```
 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"
+  prompt: "Write research questions to {spec_dir}/questions.md based on this intent document:\n\n{paste the full intent.md content here}"
 ```
 
-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.
+The question-generator has zero read access. The intent content comes via the prompt, and its only tool is Write. It cannot explore the codebase.
 
 ## Task 2: Review Questions
 

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

@@ -14,16 +14,15 @@ Create these tasks and work through them in order:
 
 ## Task 1: Research Codebase
 
-Spawn a sub-agent to research the codebase:
+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/.
 
 ```
 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"
+  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}"
 ```
 
-The objective-researcher has full codebase access (Read, Grep, Glob, Bash) but no knowledge of the feature being built. It only sees the questions.
+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
 

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

@@ -1,8 +1,6 @@
 # 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.
+Break the spec into implementation tasks using dedicated sub-agents. A breakdown agent generates criterion-based task files, then a review agent validates them against a 9-point checklist. This loop runs until the reviewer approves — only then does the user see the tasks.
 
 Read `{spec_dir}/spec.md` before proceeding.
 
@@ -10,71 +8,54 @@ Read `{spec_dir}/spec.md` before proceeding.
 
 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
+1. "Generate task breakdown" — spawn the task-breakdown agent
+2. "Review task breakdown" — spawn the task-reviewer agent, loop until approved
+3. "Review tasks with user" — present the approved breakdown
 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
-- ...
+## Task 1: Generate Breakdown
 
-Each task touches all necessary layers of the stack and produces something independently testable.
+Spawn the task-breakdown agent with the spec directory path:
 
-Map each acceptance criterion from the spec to one or more tasks. Every AC must be covered.
-
-## Task 2: Write Task Files
+```
+Agent tool:
+  subagent_type: "task-breakdown"
+  prompt: "Break the spec at {spec_dir} into implementation task files. Read spec.md, research.md, and design.md for context. Write task files to {spec_dir}/tasks/."
+```
 
-Create `{spec_dir}/tasks/` directory. Write one file per task.
+## Task 2: Review Loop
 
-`{spec_dir}/tasks/T001-{short-name}.md`:
+Spawn the task-reviewer agent to validate the breakdown:
 
-```yaml
----
-id: T001
-title: {Short descriptive title}
-status: pending
-depends_on: []
----
+```
+Agent tool:
+  subagent_type: "task-reviewer"
+  prompt: "Review the task breakdown at {spec_dir}. Read spec.md and all files in {spec_dir}/tasks/. Run the full checklist and return APPROVED or specific issues."
 ```
 
-### Criterion
-{Which acceptance criterion this task addresses}
+**If APPROVED**: Move to Task 3.
 
-### Files
-{Which files will be created or modified, with brief description of changes}
+**If issues found**: Re-spawn the task-breakdown agent with the issues:
 
-### Verification
-{How to verify this task is done — specific test commands, manual checks}
+```
+Agent tool:
+  subagent_type: "task-breakdown"
+  prompt: "Fix the following issues in the task breakdown at {spec_dir}. Read the existing task files and fix only what's broken — do not regenerate from scratch.\n\n{paste the reviewer's issue list here}"
+```
 
-### Implementation Notes
-{Patterns to follow, edge cases, things to watch out for}
+Then re-spawn the task-reviewer. Repeat until APPROVED.
 
-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.
+If the loop runs more than 3 cycles, present the remaining issues to the user and ask how to proceed.
 
-## Task 3: Review Tasks
+## Task 3: Review With User
 
-Present the task breakdown to the user. For each task, show:
+Present the approved task breakdown. For each task, show:
 
-- What it does
-- Why it's in this order (the vertical reasoning)
+- What it does (the criterion)
+- Why it's in this order (the dependency reasoning)
 - How it can be independently verified
 
-Revise based on user feedback.
+Revise based on user feedback. If changes are substantial, re-run the review loop (Task 2).
 
 ## Task 4: Proceed