cc-dev-template 0.1.94 → 0.1.95

package/package.json

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

@@ -45,7 +45,7 @@ When prompted to review a spec:
 2. Run every check in the review checklist below
 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 could lead an implementer astray — vague acceptance criteria, unclear integration point, unverifiable criterion
+   - **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
@@ -120,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.
@@ -135,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:

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-5-spec.md

@@ -2,7 +2,7 @@
 
 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
 

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.