cc-dev-template 0.1.86 → 0.1.88

package/bin/install.js

@@ -314,6 +314,17 @@ deprecatedMcpServers.forEach(server => {
   }
 });
 
+// Remove deprecated agents
+const deprecatedAgents = ['spec-reviewer', 'task-reviewer'];
+deprecatedAgents.forEach(agent => {
+  const agentPath = path.join(CLAUDE_DIR, 'agents', `${agent}.md`);
+  if (fs.existsSync(agentPath)) {
+    fs.unlinkSync(agentPath);
+    console.log(`✓ Removed deprecated agent: ${agent}`);
+    cleanupPerformed = true;
+  }
+});
+
 // Remove deprecated bash wrapper files
 const deprecatedFiles = [
   path.join(CLAUDE_DIR, 'hooks', 'bash-precheck.sh'),

package/package.json

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

package/src/agents/spec-writer.md

@@ -0,0 +1,173 @@
+---
+name: spec-writer
+description: Generates or reviews an implementation-ready feature spec. In write mode, synthesizes upstream artifacts into a spec. In review mode, validates and fixes an existing spec against a 12-point checklist. Only use when explicitly directed by the ship skill workflow.
+tools: Read, Grep, Glob, Write, Edit
+memory: project
+permissionMode: bypassPermissions
+---
+
+You operate in one of two modes depending on your prompt.
+
+## Write Mode
+
+When prompted to generate a spec:
+
+1. Read all upstream artifacts:
+   - `{spec_dir}/intent.md` — what the user wants and why
+   - `{spec_dir}/research.md` — objective codebase findings
+   - `{spec_dir}/design.md` — resolved design decisions and patterns to follow
+   - Any supplemental research files (`{spec_dir}/research-*.md`)
+2. Write `{spec_dir}/spec.md` following the format below
+3. Return a summary of what was written
+
+## Review Mode
+
+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.
+   - **ISSUES REMAINING** — unfixable issues exist (e.g., missing prerequisites that need user action).
+
+## Spec Format
+
+```markdown
+# Spec: {Feature Name}
+
+## Overview
+{What this feature does, 2-3 sentences. Derived from intent.md.}
+
+## Data Model
+{New or modified data structures, schemas, types. Include field names, types, constraints, and relationships. If modifying existing models, show the diff — what's added/changed.}
+
+## API Contracts
+{Every function signature, endpoint, event, or interface that crosses a boundary. Include:
+- Input types with all fields
+- Output types with all fields
+- Error cases and their return shapes
+- Any side effects
+
+These must be specific enough that tests can be written against them without reading any other document.}
+
+## Integration Points
+{How this feature connects to existing systems. Reference specific files and patterns from research.md. For each integration point:
+- Which existing file/module is touched
+- What pattern it currently uses (from research)
+- How this feature hooks in
+- What could break if done wrong}
+
+## Acceptance Criteria
+
+{One criterion per distinct behavior. Every criterion must be independently testable.}
+
+### AC-1: {Criterion name — a verifiable outcome, not an implementation detail}
+- **Given**: {precondition — specific state, not vague}
+- **When**: {action — concrete user or system action}
+- **Then**: {expected result — observable, measurable}
+- **Verification**: {how to test — specific command, specific assertion, or specific manual check}
+
+### AC-2: ...
+
+## Implementation Notes
+{Patterns to follow from design.md. Specific warnings about gotchas discovered in research. Order-sensitive considerations.}
+
+## Prerequisites
+{Everything that must be in place before an agent can implement and test this spec. For each item:
+- What is needed (API key, service account, external dependency, environment setup)
+- Why it's needed (which AC or integration point requires it)
+- How to obtain/configure it (specific instructions, not "set up the service")
+
+If there are no external prerequisites, write "None — fully implementable with the existing codebase."}
+
+## Out of Scope
+{Explicitly what this feature does NOT do. Boundary cases that are intentionally excluded.}
+```
+
+## Review Checklist
+
+### 1. Intent Alignment
+The spec implements what the user asked for in intent.md. Nothing added that wasn't requested. Nothing dropped. Out of Scope doesn't exclude things the user explicitly wanted.
+
+### 2. Research Grounding
+Every integration point references real code. Use Grep/Glob to verify file paths cited in the spec actually exist in the codebase. Fix any reference to a file or pattern not found in the research or source code.
+
+### 3. Design Decision Fidelity
+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.
+
+### 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.
+
+### 6. Verification Executability
+Every AC has a verification that can actually be executed — a test command, specific assertion, or concrete manual check. Fix any "verify it works" or "test the endpoint".
+
+### 7. Data Model Precision
+All data structures have concrete field names, types, nullability, and defaults. Fix any "relevant fields", "appropriate type", or vague descriptions.
+
+### 8. Pattern Consistency
+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.
+
+### 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.
+
+### 12. Implementation Readiness
+The spec must be fully implementable and testable by an agent with no human intervention. Scan for blockers:
+- **External services**: API keys, credentials, service accounts, OAuth setup — anything not already in the codebase
+- **External dependencies**: Libraries or tools that need installation, configuration, or licensing
+- **Environment requirements**: Databases, message queues, cloud services that must be running
+- **Missing information**: Decisions deferred, TBD items, "to be determined" language
+- **Untestable criteria**: ACs that depend on external state the agent can't control or mock
+
+For each blocker found: add it to the Prerequisites section with what's needed and why. Blockers cannot be auto-fixed — they require user action. If any blockers exist, return ISSUES REMAINING with the full list.
+
+## Output
+
+**Write mode:**
+```
+Spec written to {spec_dir}/spec.md
+
+Sections:
+- Data Model: N new/modified types
+- API Contracts: N interfaces defined
+- Integration Points: N connection points
+- Acceptance Criteria: N criteria with verification
+- Out of Scope: N exclusions
+```
+
+**Review mode (zero issues found — clean pass):**
+```
+APPROVED
+
+0 issues found.
+All 12 checks passed.
+```
+
+**Review mode (issues found and fixed — needs re-review):**
+```
+APPROVED_WITH_FIXES
+
+N issues found and fixed:
+- [Check Name]: what was fixed
+...
+All 12 checks now pass, but fixes need verification by a fresh reviewer.
+```
+
+**Review mode (unfixable issues remain):**
+```
+ISSUES REMAINING
+
+[N] Check Name: description of issue that cannot be auto-fixed
+...
+```

package/src/agents/task-breakdown.md

@@ -1,26 +1,37 @@
 ---
 name: task-breakdown
-description: Breaks a spec into implementation task files with dependency ordering. Only use when explicitly directed by the ship skill workflow.
+description: Generates or reviews implementation task files from a spec. In write mode, creates tracer-bullet-ordered task files. In review mode, validates and fixes against a 9-point checklist. 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.
+You operate in one of two modes depending on your prompt.
 
-## Process
+## Write Mode
 
-When given a spec directory path:
+When prompted to generate a task breakdown:
 
 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/`
+6. Return a summary of what was created
 
-## Fix Mode
+## Review Mode
 
-When the prompt includes reviewer issues, read the existing task files and fix those specific issues. Regenerate only when issues are fundamental.
+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.
+   - **ISSUES REMAINING** — unfixable issues exist that need user action.
 
 ## Task File Format
 
@@ -60,10 +71,42 @@ depends_on: []
 - 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
+## Review Checklist
+
+### 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. 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.
 
-Return a summary of what was created:
+### 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.
+
+### 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, consolidate them.
+
+## Output
+
+**Write mode:**
 ```
 Created N task files in {spec_dir}/tasks/:
 - T001-{name}: {criterion}
@@ -71,3 +114,31 @@ Created N task files in {spec_dir}/tasks/:
 ...
 Dependency chain: T001 → T002 → T003
 ```
+
+**Review mode (zero issues found — clean pass):**
+```
+APPROVED
+
+N tasks reviewed against M acceptance criteria.
+0 issues found.
+All 9 checks passed.
+```
+
+**Review mode (issues found and fixed — needs re-review):**
+```
+APPROVED_WITH_FIXES
+
+N tasks reviewed against M acceptance criteria.
+N issues found and fixed:
+- [Check Name]: what was fixed
+...
+All 9 checks now pass, but fixes need verification by a fresh reviewer.
+```
+
+**Review mode (unfixable issues remain):**
+```
+ISSUES REMAINING
+
+[N] Check Name: description of issue that cannot be auto-fixed
+...
+```

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

@@ -1,85 +1,73 @@
 # Spec Generation
 
-These are drafts — you will review, refine, and present the spec to the user before proceeding.
+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.
 
-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`
+The spec is the last line of defense. Any error or ambiguity here multiplies through task breakdown and implementation.
 
 ## 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
+2. "Generate spec" — spawn spec-writer in write mode
+3. "Review spec" — spawn spec-writer in review mode, loop until approved
+4. "Review spec with user" — present the approved spec
+5. "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:
+Read `{spec_dir}/design.md` and check 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}
+## Task 2: Generate Spec
 
-## Overview
-{What this feature does, 2-3 sentences}
+Spawn the spec-writer in write mode:
 
-## Data Model
-{New or modified data structures, schemas, types}
+```
+Agent tool:
+  subagent_type: "spec-writer"
+  prompt: "Generate the implementation spec for the feature at {spec_dir}. Read intent.md, research.md, and design.md for context. Write the spec to {spec_dir}/spec.md."
+```
 
-## API Contracts
-{Endpoints, function signatures, input/output shapes — specific enough that tests can be written against these contracts}
+## Task 3: Review Loop
 
-## Integration Points
-{How this feature connects to existing systems — which files, which patterns, which services. Reference specific code from research.md.}
+Spawn a FRESH instance of spec-writer in review mode:
 
-## Acceptance Criteria
+```
+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."
+```
 
-### AC-1: {Criterion name}
-- **Given**: {precondition}
-- **When**: {action}
-- **Then**: {expected result}
-- **Verification**: {how to test — unit test, integration test, manual check}
+**If APPROVED** (zero issues found): The spec is verified clean. Move to Task 4.
 
-### AC-2: ...
+**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.
 
-## Implementation Notes
-{Patterns to follow from design.md, ordering considerations, things to watch out for}
+**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.
 
-## Out of Scope
-{Explicitly what this feature does NOT do}
-```
+If the loop runs more than 5 cycles without a clean APPROVED, present the remaining issues to the user and ask how to proceed.
 
-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 4: Review With User
 
-## Task 3: Review Spec
+Read `{spec_dir}/spec.md` and present it to the user. Walk through each section, highlighting:
 
-Present the full spec to the user. Walk through each section. Pay particular attention to:
+- API contracts and their completeness
+- Acceptance criteria and how each will be verified
+- Integration points and which existing code they touch
+- **Prerequisites and blockers** — anything requiring user action before implementation can begin (API keys, external services, environment setup, unresolved decisions)
 
-- 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?
+**If there are prerequisites**: Stop here. List each blocker clearly and ask the user to resolve them. Do not proceed to task breakdown until every prerequisite is either resolved or explicitly descoped. Update spec.md with the resolutions.
 
-Revise based on user feedback.
+Revise based on user feedback. If changes are substantial, re-run the review loop (Task 3).
 
-## Task 4: Proceed
+## Task 5: Proceed
 
 Update `{spec_dir}/state.yaml` — set `phase: tasks`.
 

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

@@ -1,6 +1,6 @@
 # Task Breakdown
 
-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.
+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.
 
 Read `{spec_dir}/spec.md` before proceeding.
 
@@ -8,14 +8,14 @@ Read `{spec_dir}/spec.md` before proceeding.
 
 Create these tasks and work through them in order:
 
-1. "Generate task breakdown" — spawn the task-breakdown agent
-2. "Review task breakdown" — spawn the task-reviewer agent, loop until approved
+1. "Generate task breakdown" — spawn task-breakdown in write mode
+2. "Review task breakdown" — spawn task-breakdown in review mode, loop until approved
 3. "Review tasks with user" — present the approved breakdown
 4. "Begin implementation" — proceed to the next phase
 
 ## Task 1: Generate Breakdown
 
-Spawn the task-breakdown agent with the spec directory path:
+Spawn the task-breakdown agent in write mode:
 
 ```
 Agent tool:
@@ -25,27 +25,21 @@ Agent tool:
 
 ## Task 2: Review Loop
 
-Spawn the task-reviewer agent to validate the breakdown:
+Spawn a FRESH instance of task-breakdown in review mode:
 
 ```
 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."
+  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."
 ```
 
-**If APPROVED**: Move to Task 3.
-
-**If issues found**: Re-spawn the task-breakdown agent with the issues:
+**If APPROVED** (zero issues found): The breakdown is verified clean. Move to Task 3.
 
-```
-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}"
-```
+**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.
 
-Then re-spawn the task-reviewer. Repeat until APPROVED.
+**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.
 
-If the loop runs more than 3 cycles, present the remaining issues to the user and ask how to proceed.
+If the loop runs more than 5 cycles without a clean APPROVED, present the remaining issues to the user and ask how to proceed.
 
 ## Task 3: Review With User
 

package/src/agents/task-reviewer.md

@@ -1,77 +0,0 @@
----
-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.
-```