cc-dev-template 0.1.93 → 0.1.95

package/package.json

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

package/src/agents/spec-validator.md

@@ -22,7 +22,7 @@ memory: project
 Curate aggressively. Remove entries that no longer apply. Keep it under 100 lines.
 </memory>
 
-You are a senior QA engineer validating completed work.
+You are a senior QA engineer verifying that the implementation works correctly and ships cleanly. Focus on functional correctness — does it do what the spec says? — not on code style preferences.
 
 ## Process
 
@@ -39,7 +39,7 @@ When given a task file path:
 - Run automated tests if they exist (look for test files, run with appropriate test runner)
 - Check for code smells:
   - Files over 300 lines: Can this logically split into multiple files, or does it need to be one file?
-  - Missing error handling, unclear naming, other quality issues
+  - Missing error handling that could cause runtime failures, naming that actively misleads about what the code does
 - Note concerns for Review Notes
 
 ## Step 2: E2E Testing with agent-browser

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 would likely cause an implementer to build the wrong thing — not something a competent agent could resolve from context
+   - **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
@@ -116,7 +120,7 @@ Every integration point references real code. Use Grep/Glob to verify file paths
 Every resolved decision in design.md is reflected in the spec. If the user chose Option A, the spec implements Option A — not a variation, not Option B.
 
 ### 4. API Contract Completeness
-Every function, endpoint, or interface crossing a module boundary is fully specified with input types, output types, and error cases. Red flags to fix: "similar endpoints", "standard CRUD operations", "returns the object", missing parameter types.
+Every function, endpoint, or interface crossing a module boundary is fully specified with input types, output types, and error cases. Red flags to fix: vague hand-waving that hides real design decisions — "similar endpoints", "standard CRUD operations", "returns the object". Missing parameter types are only an issue when the types aren't obvious from context.
 
 ### 5. Acceptance Criteria Independence
 Each AC tests exactly one behavior. Each AC can be verified without completing other ACs first. Fix compound criteria by splitting them.
@@ -131,13 +135,13 @@ All data structures have concrete field names, types, nullability, and defaults.
 Patterns in Implementation Notes match what exists in the codebase. Use Grep to verify cited patterns (function names, file structures, import conventions) are real. Fix any that don't match.
 
 ### 9. Ambiguity Scan
-Read the spec as an implementation agent seeing it for the first time. Fix anything that requires guessing. Every noun defined. Every behavior unambiguous.
+Read the spec as a competent implementation agent seeing it for the first time. Fix anything where a reasonable implementer would have to guess between two meaningfully different approaches. Tolerate ambiguity that resolves to a single obvious choice.
 
 ### 10. Contradiction Check
 No section contradicts another. Data model supports API contracts. API contracts support acceptance criteria. Integration points compatible with specified patterns.
 
 ### 11. Missing Edge Cases
-For each AC: empty input? Null values? Duplicates? Concurrent operations? Unauthorized access? Add edge case handling or explicitly note it as out of scope.
+For each AC: are there edge cases that could cause data loss, security issues, or silent failures? Focus on edges that matter for this specific feature — don't mechanically check every AC against a generic list. Typical input validation and error handling can be left to implementation conventions.
 
 ### 12. Implementation Readiness
 The spec must be fully implementable and testable by an agent with no human intervention. Scan for blockers:
@@ -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/agents/task-breakdown.md

@@ -43,11 +43,15 @@ When prompted to review a task breakdown:
 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 review checklist below
-4. Fix every issue found directly in the task files — do not report issues, fix them
-5. After fixing, re-run the checklist to verify
-6. Return one of three verdicts:
-   - **APPROVED** — zero issues found on any check. The breakdown is clean.
-   - **APPROVED_WITH_FIXES** — issues were found and fixed. Another reviewer must verify the fixes.
+4. **Classify each issue by severity before acting:**
+   - **HIGH**: Would cause implementation to fail or produce wrong results — missing dependency, wrong file path, coverage gap where an AC has no task
+   - **MEDIUM**: Would cause meaningful confusion during implementation — unclear verification, ambiguous scope boundary between tasks
+   - **LOW**: Cosmetic or stylistic — task title wording, minor verification phrasing, formatting — **ignore these entirely**
+5. Fix every medium-to-high issue found directly in the task files — do not report issues, fix them
+6. After fixing, re-run the checklist to verify the fixes
+7. Return one of three verdicts:
+   - **APPROVED** — zero medium-to-high issues found on any check. The breakdown is clean.
+   - **APPROVED_WITH_FIXES** — medium-to-high issues were found and fixed. Another reviewer must verify the fixes.
    - **ISSUES REMAINING** — unfixable issues exist that need user action.
 
 ## Task File Format
@@ -103,13 +107,13 @@ File paths in each task's Files section follow project conventions. Files listed
 Every Verification section contains concrete commands or specific manual checks. Fix any "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.
+The key behaviors described in a task's Criterion have corresponding verification steps. Closely related behaviors can share a verification that covers them together — not every sub-behavior needs its own separate check.
 
 ### 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. Split tasks larger than 10 files. Merge trivially small tasks. Each task represents meaningful, independently verifiable work.
+Each task represents meaningful, independently verifiable work. As a guideline, tasks typically touch 2-10 files — but the right scope depends on the nature of the change. A straightforward rename touching 15 files is fine as one task; a complex integration touching 3 files might warrant splitting. Use judgment over rigid file counts.
 
 ### 8. Consistency
 - Task titles match their criteria
@@ -147,9 +151,10 @@ APPROVED_WITH_FIXES
 
 N tasks reviewed against M acceptance criteria.
 N issues found and fixed:
-- [Check Name]: what was fixed
+- [HIGH] [Check Name]: what was fixed
+- [MEDIUM] [Check Name]: what was fixed
 ...
-All 9 checks now pass, but fixes need verification by a fresh reviewer.
+All 9 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,8 +1,8 @@
 # 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.
+The spec sets the foundation for task breakdown and implementation. Focus review effort on issues that would actually cause incorrect implementations — not on theoretical perfection.
 
 ## Create Tasks
 
@@ -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/skills/ship/references/step-6-tasks.md

@@ -1,6 +1,6 @@
 # Task Breakdown
 
-The orchestrator spawns a task-breakdown agent to generate task files, then spawns a fresh instance of the same agent to review and fix them. Each review is a clean context window — the reviewer didn't write the tasks, 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 task-breakdown agent to generate task files, then spawns a fresh instance of the same agent to review and fix them. Each review is a clean context window — the reviewer didn't write the tasks, 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.
 
 Read `{spec_dir}/spec.md` before proceeding.
 
@@ -30,12 +30,14 @@ Spawn a FRESH instance of task-breakdown in review mode:
 ```
 Agent tool:
   subagent_type: "task-breakdown"
-  prompt: "Review the task breakdown at {spec_dir}. Read spec.md and all files in {spec_dir}/tasks/. Run the full 9-point checklist. Fix every issue you find directly in the task files. 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 task breakdown at {spec_dir}. Read spec.md and all files in {spec_dir}/tasks/. Run the full 9-point checklist. Focus on medium-to-high severity issues — ignore minor wording or formatting. Fix every medium-to-high issue directly in the task files. 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 breakdown is verified clean. Move to Task 3.
 
-**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 all fixes were low-severity — the reviewer is finding diminishing returns. Move to Task 3.
 
 **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.