cc-dev-template 0.1.79 → 0.1.81

package/src/skills/spec-interview/SKILL.md

@@ -6,38 +6,7 @@ argument-hint: <spec-name>
 
 # Spec Interview
 
-## Team-Based Approach
-
-**IMPORTANT:** This skill uses an agent team for collaborative spec development. You are the **Lead** — you interview the user, write the spec, and curate team input. Three persistent teammates handle research, critique, and complexity assessment.
-
-### Team Composition
-
-All teammates run on Opus:
-- **Researcher** (researcher): Continuously explores the codebase, maps file landscape, integration points, data model. Drafts technical sections.
-- **Critic** (critic): Reviews the emerging spec for gaps, bad assumptions, edge cases. Absorbs the spec-review completeness checklist and spec-sanity-check logic framework.
-- **Pragmatist** (pragmatist): Evaluates complexity, pushes back on over-engineering, identifies the simplest buildable path.
-
-### Working Directory
-
-The team shares `{spec_dir}/working/`:
-- `context.md` — You (the Lead) write interview updates here. Append-only — each update is a new section with a heading (e.g., `## Step 1: Feature Overview`). This replaces broadcasting — teammates read this file to stay current.
-- Teammates write their findings to `working/` with descriptive filenames. Read these at checkpoints.
-- `spec.md` (parent dir) — The living spec. You own this file. Teammates read it but never write to it.
-
-### Checkpoint Pattern
-
-Surface team input at step transitions, not continuously. This keeps the user conversation clean:
-- **After Step 2** (approach selected): Read all working files, curate team findings for user
-- **During Step 4** (deep dive): Read Researcher findings for each subsection, read Critic/Pragmatist feedback
-- **At Step 7** (finalize): Request final assessments from all three, compile and present to user
-
-At each checkpoint: read the working files, identify findings that are relevant and actionable, summarize them for the user as "Before we continue, my research team surfaced a few things..." Skip trivial items.
-
-### Team Lifecycle
-
-1. **Spawn** — After Step 1 (once the feature is understood), create the working directory, read the three prompt templates from `references/`, substitute `{spec_dir}` and `{feature_name}`, use TeamCreate to create a team named `spec-{feature-name}`, then spawn the three teammates via the Task tool
-2. **Communicate** — Update context.md after each step. Message teammates for specific questions. Read their working files at checkpoints.
-3. **Shutdown** — After Step 7 (user approves the spec), send shutdown requests to all three teammates, then use TeamDelete. Leave the `working/` directory in place as reference for implementation.
+Conduct a structured interview to produce an implementation-ready feature spec. This skill uses an agent team — three persistent teammates (Researcher, Critic, Pragmatist) handle codebase exploration, quality review, and complexity assessment while you lead the interview.
 
 ## What To Do Now
 

package/src/skills/spec-interview/references/step-1-opening.md

@@ -22,7 +22,38 @@ Move on when:
 
 ## Initialize the Team
 
-Before proceeding to Step 2, set up the agent team:
+You are the **Lead** — you interview the user, write the spec, and curate team input. Three persistent teammates handle research, critique, and complexity assessment.
+
+### Team Composition
+
+All teammates run on Opus:
+- **Researcher** (researcher): Continuously explores the codebase, maps file landscape, integration points, data model. Drafts technical sections.
+- **Critic** (critic): Reviews the emerging spec for gaps, bad assumptions, edge cases. Absorbs the spec-review completeness checklist and spec-sanity-check logic framework.
+- **Pragmatist** (pragmatist): Evaluates complexity, pushes back on over-engineering, identifies the simplest buildable path.
+
+### Working Directory
+
+The team shares `{spec_dir}/working/`:
+- `context.md` — You (the Lead) write interview updates here. Append-only — each update is a new section with a heading (e.g., `## Step 1: Feature Overview`). This replaces broadcasting — teammates read this file to stay current.
+- Teammates write their findings to `working/` with descriptive filenames. Read these at checkpoints.
+- `spec.md` (parent dir) — The living spec. You own this file. Teammates read it but never write to it.
+
+### Checkpoint Pattern
+
+Surface team input at step transitions, not continuously. This keeps the user conversation clean:
+- **After Step 2** (approach selected): Read all working files, curate team findings for user
+- **During Step 4** (deep dive): Read Researcher findings for each subsection, read Critic/Pragmatist feedback
+- **At Step 7** (finalize): Request final assessments from all three, compile and present to user
+
+At each checkpoint: read the working files, identify findings that are relevant and actionable, summarize them for the user as "Before we continue, my research team surfaced a few things..." Skip trivial items.
+
+### Team Lifecycle
+
+1. **Spawn** — After the opening questions (once the feature is understood), create the working directory, read the three prompt templates from `references/`, substitute `{spec_dir}` and `{feature_name}`, use TeamCreate to create a team named `spec-{feature-name}`, then spawn the three teammates via the Task tool
+2. **Communicate** — Update context.md after each step. Message teammates for specific questions. Read their working files at checkpoints.
+3. **Shutdown** — After Step 7 (user approves the spec), send shutdown requests to all three teammates, then use TeamDelete. Leave the `working/` directory in place as reference for implementation.
+
+### Spawn Steps
 
 1. Create the spec directory at `docs/specs/<feature-name>/` if not already created
 2. Create `docs/specs/<feature-name>/working/` subdirectory

package/src/skills/spec-interview/references/step-2-ideation.md

@@ -14,7 +14,7 @@ Use AskUserQuestion to ask:
 
 ## Hybrid Brainstorming
 
-Research shows that combining human and AI ideas produces more original solutions than either alone. The key: get human ideas first, before AI suggestions anchor their thinking.
+Get human ideas first, before AI suggestions anchor their thinking.
 
 ### 1. Collect User Ideas First
 
@@ -22,7 +22,7 @@ Use AskUserQuestion:
 
 > "Before I suggest anything - what approaches have you been considering? Even rough or half-formed ideas are valuable."
 
-Let them share freely. Don't evaluate yet. The goal is to capture their independent thinking before AI ideas influence it.
+Capture ideas without evaluating. The goal is to capture their independent thinking before AI ideas influence it.
 
 ### 2. Generate AI Alternatives
 

package/src/skills/spec-interview/references/step-4-deep-dive.md

@@ -42,6 +42,15 @@ This becomes the File Landscape section of the spec, which spec-to-tasks uses di
 - Triggers and resulting actions
 - Different modes or variations
 
+### Constraints
+- What is explicitly out of scope (features, users, flows to NOT build)
+- Technology boundaries (must use X, must not introduce Y)
+- Performance requirements (latency, throughput, resource limits)
+- Security requirements (auth, PII handling, logging restrictions)
+- Compatibility requirements (browsers, platforms, API versions)
+
+Constraints that aren't written down don't exist during implementation. If the spec doesn't say "don't introduce a new ORM" or "must stay under 200ms," those boundaries won't be respected downstream.
+
 ### Edge Cases & Error Handling
 - Failure modes and how to handle them
 - Invalid input handling
@@ -67,6 +76,15 @@ Write to `docs/specs/<name>/spec.md` with this structure:
 - [Primary goal]
 - [Secondary goals]
 
+## Approach
+[Chosen approach and rationale. What alternatives were considered and why this one was selected.]
+
+## Constraints
+- **Out of scope:** [What this feature explicitly does NOT do]
+- **Technology:** [Must use / must not introduce]
+- **Performance:** [Latency, throughput, resource limits]
+- **Security:** [Auth, PII, logging restrictions]
+
 ## Integration Points
 - Touches: [existing components]
 - External: [APIs, services, libraries]

package/src/skills/spec-interview/references/step-7-finalize.md

@@ -57,6 +57,4 @@ Once user confirms no more review passes needed:
 
 If yes to task breakdown, invoke `spec-to-tasks` and specify which spec to break down.
 
-**IMPORTANT: You are not done. You MUST read and complete the next step. The workflow is incomplete without it.**
-
-Read `references/step-8-reflect.md` now.
+Use the Read tool on `references/step-8-reflect.md` to reflect on the interview process and note any skill issues.

package/src/skills/spec-interview/references/step-8-reflect.md

@@ -1,8 +1,6 @@
 # Step 8: Reflect and Improve
 
-**IMPORTANT: This step is mandatory. The spec interview workflow is not complete until this step is finished. Do not skip this.**
-
-Reflect on your experience conducting this spec interview. The purpose is to improve the spec-interview skill itself based on what you just learned.
+Reflect on this spec interview to improve the skill itself.
 
 ## Assess
 

package/src/skills/spec-review/SKILL.md

@@ -1,22 +1,21 @@
 ---
 name: spec-review
-description: This skill should be used when the user says "review the spec", "check spec completeness", or "is this spec ready". Also invoked by spec-interview when a spec is complete.
+description: Review a feature spec for completeness and implementation readiness. Checks data models, integration points, acceptance criteria, CLAUDE.md alignment, and duplication.
 argument-hint: <spec-name>
 context: fork
 ---
 
 # Spec Review
 
-## Steps
+## Find the Spec
 
-1. **Find the spec** - Use the path from the prompt if provided. Otherwise, find the most recently modified file in `docs/specs/`. If no specs exist, inform the user and stop.
-2. **Read the spec file**
-3. **Find all CLAUDE.md files** - Search for every CLAUDE.md in the project (root and subdirectories)
-4. **Read all CLAUDE.md files** - These contain project constraints and conventions
-5. **Evaluate against the checklist below** - Including CLAUDE.md alignment
-6. **Return structured feedback using the output format**
+Use the path from the prompt if provided. Otherwise, find the most recently modified file in `docs/specs/`. If no specs exist, inform the user and stop.
 
-## Completeness Checklist
+## Read Context
+
+Read the spec file and all CLAUDE.md files in the project (root and subdirectories). CLAUDE.md files contain project constraints and conventions to check alignment against.
+
+## Evaluate Against Checklist
 
 A spec is implementation-ready when ALL of these are satisfied:
 

package/src/skills/spec-sanity-check/SKILL.md

@@ -1,13 +1,13 @@
 ---
 name: spec-sanity-check
-description: This skill should be used alongside spec-review to catch logic gaps and incorrect assumptions. Invoked when the user says "sanity check this spec", "does this plan make sense", or "what am I missing". Also auto-invoked by spec-interview during finalization.
+description: Fresh-eyes review of a spec's logic and assumptions. Checks for logic gaps, incorrect assumptions about existing systems, unconsidered scenarios, and implementation pitfalls.
 argument-hint: <spec-path>
 context: fork
 ---
 
 # Spec Sanity Check
 
-Provide a "fresh eyes" review of the spec. This is different from spec-review — you're not checking format or completeness. You're checking whether the plan will actually work.
+Review the spec with fresh eyes. Focus on whether the plan will actually work, not format or completeness.
 
 ## Find the Spec
 

package/src/skills/spec-to-tasks/SKILL.md

@@ -13,11 +13,11 @@ This skill has 5 steps. **You must complete ALL steps. Do not stop early or skip
 
 1. **Identify Spec** - Find and verify the spec file
 2. **Verify File Landscape** - Map files to acceptance criteria
-3. **Generate Tasks** - Create task files in `tasks/` directory
-4. **Review Tasks** - Run review checklist in a loop until no critical issues remain
+3. **Draft Tasks** - Create draft task files in `tasks/` directory
+4. **Review and Present** - Review drafts, auto-fix issues, then present final results to the user
 5. **Reflect** - Note any skill issues observed during this run
 
-Steps 4 and 5 are mandatory. The review loop in step 4 is automated — fix issues and re-check until clean, with no user input required.
+Step 4 is where you present results to the user. Step 3 produces drafts; step 4 reviews, fixes, and presents them.
 
 ## What To Do Now
 

package/src/skills/spec-to-tasks/references/step-3-generate.md

@@ -1,6 +1,6 @@
-# Step 3: Generate Task Files
+# Step 3: Draft Task Files
 
-Create individual task files based on the spec and codebase exploration.
+Create draft task files based on the spec and codebase exploration. These are drafts — you will review, fix, and present them in the next step.
 
 ## Task Principles
 
@@ -60,10 +60,8 @@ docs/specs/<name>/
 
 Use the template in `templates/task.md` for each file. Name files in dependency order so alphabetical sorting reflects execution order.
 
-## Do NOT Present Results Yet
+After writing all draft task files, use the Read tool on `references/step-4-review.md` to review and present your results to the user.
 
-You have generated task files but you are NOT done. The review step is next and it is mandatory.
+## Continue to Review
 
-**IMPORTANT: You are not done. You MUST read and complete the next step. The workflow is incomplete without it.**
-
-Read `references/step-4-review.md` now.
+Draft task files are ready. Use the Read tool on `references/step-4-review.md` now — that is where you review the drafts and present the final results to the user.

package/src/skills/spec-to-tasks/references/step-4-review.md

@@ -1,8 +1,8 @@
-# Step 4: Review Task Breakdown
+# Step 4: Review and Present Tasks
 
-**IMPORTANT: This step is mandatory. The spec-to-tasks workflow is not complete until this step is finished. Do not skip this.**
+Review the draft tasks, auto-fix all issues, then present the final results to the user. This is the step where the user sees your output.
 
-You must review the generated tasks, fix any issues, and re-review until the breakdown is clean. This is fully automated — do not ask the user for input during this step.
+This is fully automated — fix every issue you find without asking the user. Do not ask for input during this step.
 
 ## Review Checklist
 
@@ -71,24 +71,19 @@ Compare acceptance criteria in the spec to tasks generated.
 - No two tasks create components with similar names, purposes, or overlapping structure
 - Shared patterns use a single shared component with configuration, not separate implementations
 
-## Review Loop
+## Review and Fix Loop
 
-Run the checklist above against all task files. Then:
+Run the checklist above against all task files. Fix every issue you find — Critical, Warning, and fixable Notes — by editing the task files directly. Then re-run the full checklist from the top. Repeat until no issues remain.
 
-1. **If Critical issues found:** Fix them by editing the task files. Then re-run the full checklist again from the top. Repeat until no Critical issues remain.
-2. **If only Warnings/Notes remain:** Proceed — you will present these to the user.
-3. **If no issues found:** Proceed.
+Do not present results until the loop is clean.
 
-Do NOT present results after a single pass if Critical issues exist. The loop must continue until clean.
+## Present Results to User
 
-## Present to User
-
-After the review loop completes with no Critical issues, present:
+After the review loop completes clean, present:
 
 1. Number of tasks generated
 2. Task dependency tree (visual format)
-3. Any Warnings from the review (with your recommendation)
-4. Offer to show task files or proceed to implementation
+3. Summary of review findings and fixes applied (what you found, what you fixed)
 
 **IMPORTANT: You are not done. You MUST read and complete the next step. The workflow is incomplete without it.**
 

package/src/skills/task-review/SKILL.md

@@ -7,7 +7,7 @@ context: fork
 
 # Task Review
 
-Review the task breakdown to catch issues before implementation begins.
+Review the task breakdown, auto-fix all issues found, and report what was fixed.
 
 ## What To Do Now
 
@@ -15,4 +15,4 @@ If an argument was provided, use it as the spec name. Otherwise, find the most r
 
 Read the spec file and all task files in the `tasks/` directory.
 
-Then read `references/checklist.md` and evaluate each item.
+Then read `references/checklist.md` and run the review-and-fix loop.

package/src/skills/task-review/references/checklist.md

@@ -1,9 +1,9 @@
 # Task Review Checklist
 
-Evaluate each area. For each issue found, note the severity:
-- **Critical**: Must fix before implementation
-- **Warning**: Should fix, but could proceed
-- **Note**: Minor suggestion
+Evaluate each area. Fix every issue you find by editing the task files directly. Note what you found and fixed:
+- **Critical**: Must fix — fix immediately
+- **Warning**: Should fix — fix now
+- **Note**: Minor suggestion — fix if straightforward
 
 ## 1. Coverage
 
@@ -132,24 +132,22 @@ Compare files-to-create across all tasks. Group by similarity (naming patterns,
 
 ---
 
-## Output Format
+## Review and Fix Loop
 
-Return findings as a structured list:
+Run the checklist above against all task files. Fix every issue you find by editing the task files directly. Then re-run the full checklist from the top. Repeat until no issues remain.
 
-```
-## Critical Issues
-- [T002] Depends on T005 which comes later - wrong order
-- [T003] Missing verification method
+## Output Format
 
-## Warnings
-- [T001] touches 12 files - consider splitting
-- Criterion "User can delete account" has no corresponding task
+After all issues are fixed, report what you found and fixed:
 
-## Notes
-- [T004] Could merge with T005 since they share the same files
+```
+## Review Summary
+- [T002] Fixed: reordered dependency — was depending on T005 which came later
+- [T003] Fixed: added concrete verification command (was missing)
+- [T001] Fixed: split into T001a/T001b — was touching 12 files
 
 ## Skill Observations (optional)
-If any checklist items, severity criteria, or review patterns in this skill were wrong, incomplete, or misleading during this review, note them here. Leave empty if no issues were found.
+If any checklist items or review patterns in this skill were wrong or misleading, note them here.
 ```
 
 If no issues found, state: "Task breakdown looks good. All criteria covered, dependencies valid, verification methods concrete."

package/src/skills/execute-spec/references/workflow.md

@@ -1,82 +0,0 @@
-# Execute Spec Workflow
-
-## Overview
-
-```
-PHASE 1: HYDRATE
-  Run parse script → TaskCreate with dependencies
-  (NO file reading by orchestrator)
-
-PHASE 2: BUILD
-  Loop: find unblocked tasks → dispatch spec-implementer → receive minimal status
-  Continue until all tasks built
-
-PHASE 3: VALIDATE
-  Dispatch spec-validator for each task (all in parallel)
-  Receive pass/fail status only
-
-PHASE 4: TRIAGE
-  For failed tasks: re-dispatch spec-implementer
-  Re-validate
-  Loop until clean or user defers
-
-PHASE 5: REFLECT
-  Assess orchestration experience → improve skill files
-  (Mandatory — workflow is NOT complete without this)
-```
-
-## Critical: Minimal Context
-
-**Agent returns are pass/fail only.** All details go in task files.
-
-- Implementer returns: `Task complete: T005` or `Blocked: T005 - reason`
-- Validator returns: `Pass: T005` or `Issues: T005 - [brief list]`
-
-The orchestrator never reads task files. It dispatches paths and receives status.
-
-## Phase 1: Hydrate
-
-Read `phase-1-hydrate.md` for details.
-
-Use the parse script to get task metadata:
-```bash
-node ~/.claude/scripts/parse-task-files.js {spec-path}
-```
-
-This returns JSON with task IDs, titles, dependencies, and paths. Create tasks from this output without reading any files.
-
-## Phase 2: Build
-
-Read `phase-2-build.md` for details.
-
-1. Find unblocked tasks via TaskList
-2. Dispatch spec-implementer with just the file path
-3. Receive minimal status (pass/fail)
-4. Repeat until all built
-
-## Phase 3: Validate
-
-Read `phase-3-validate.md` for details.
-
-1. Dispatch spec-validator for each task (parallel)
-2. Receive pass/fail status
-3. Collect list of failed task IDs
-
-## Phase 4: Triage
-
-Read `phase-4-triage.md` for details.
-
-1. For failed tasks: re-dispatch spec-implementer (it reads Review Notes and fixes)
-2. Re-run spec-validator on fixed tasks
-3. Loop until all pass or user defers remaining issues
-
-## Key Principles
-
-- **No file reading by orchestrator** - Hook blocks task file reads
-- **Minimal returns** - Agents return status only, details in task files
-- **Task file is source of truth** - Implementation Notes and Review Notes track all history
-- **Parallelism** - Use `run_in_background: true` where possible
-
-**IMPORTANT: You are not done. You MUST read and complete the next step. The workflow is incomplete without it.**
-
-Read `references/phase-5-reflect.md` now.