cc-dev-template 0.1.85 → 0.1.87

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.85",
+  "version": "0.1.87",
   "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,160 @@
+---
+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 APPROVED if all checks pass, or report remaining issues that could not be auto-fixed
+
+## 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 (all checks pass):**
+```
+APPROVED
+
+N issues found and fixed.
+All 12 checks passed.
+```
+
+**Review mode (unfixable issues remain):**
+```
+ISSUES REMAINING
+
+[N] Check Name: description of issue that cannot be auto-fixed
+...
+```

package/src/agents/task-breakdown.md

@@ -0,0 +1,130 @@
+---
+name: task-breakdown
+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
+---
+
+You operate in one of two modes depending on your prompt.
+
+## Write Mode
+
+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
+
+## Review Mode
+
+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 APPROVED if all checks pass, or report remaining issues that could not be auto-fixed
+
+## 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"
+
+## 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.
+
+### 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}
+- T002-{name}: {criterion}
+...
+Dependency chain: T001 → T002 → T003
+```
+
+**Review mode (all checks pass):**
+```
+APPROVED
+
+N tasks reviewed against M acceptance criteria.
+N issues found and fixed.
+All 9 checks passed.
+```
+
+**Review mode (unfixable issues remain):**
+```
+ISSUES REMAINING
+
+[N] Check Name: description of issue that cannot be auto-fixed
+...
+```

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

@@ -1,85 +1,71 @@
 # 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 the reviewer returns APPROVED.
 
-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}
-
-## API Contracts
-{Endpoints, function signatures, input/output shapes — specific enough that tests can be written against these contracts}
+```
+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."
+```
 
-## Integration Points
-{How this feature connects to existing systems — which files, which patterns, which services. Reference specific code from research.md.}
+## Task 3: Review Loop
 
-## Acceptance Criteria
+Spawn a FRESH instance of spec-writer in review mode:
 
-### AC-1: {Criterion name}
-- **Given**: {precondition}
-- **When**: {action}
-- **Then**: {expected result}
-- **Verification**: {how to test — unit test, integration test, manual check}
+```
+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 all checks pass, or ISSUES REMAINING for anything you cannot auto-fix."
+```
 
-### AC-2: ...
+**If APPROVED**: Move to Task 4.
 
-## 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 3 cycles without 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,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.
+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 the reviewer returns APPROVED.
 
 Read `{spec_dir}/spec.md` before proceeding.
 
@@ -10,71 +8,46 @@ 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 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: 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 in write mode:
 
-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 a FRESH instance of task-breakdown in review mode:
 
-```yaml
----
-id: T001
-title: {Short descriptive title}
-status: pending
-depends_on: []
----
+```
+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 all checks pass, or ISSUES REMAINING for anything you cannot auto-fix."
 ```
 
-### 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}
+**If APPROVED**: Move to Task 3.
 
-### Implementation Notes
-{Patterns to follow, edge cases, 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.
 
-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 without APPROVED, 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