cc-dev-template 0.1.55 → 0.1.58

package/package.json

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

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

@@ -16,6 +16,6 @@ Then explore:
 
 ## When to Move On
 
-Move to `references/step-2-ui-ux.md` when:
+Move to `references/step-2-ideation.md` when:
 - The core problem and user goal are clear
 - Success criteria are understood at a high level

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

@@ -0,0 +1,59 @@
+# Step 2: Ideation
+
+Before designing a solution, explore the solution space. This step prevents premature convergence on the first idea that comes to mind.
+
+## Determine Mode
+
+Use AskUserQuestion to ask:
+
+> "Do you already have a clear approach in mind, or would you like to explore different options first?"
+
+**Options:**
+- **I know my approach** → Skip to `references/step-3-ui-ux.md` (or step-4-deep-dive.md if no UI)
+- **Let's explore options** → Continue with brainstorming below
+
+## 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.
+
+### 1. Collect User Ideas First
+
+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.
+
+### 2. Generate AI Alternatives
+
+Now generate 3-4 different approaches to the same problem. These should:
+- Include options the user didn't mention
+- Vary meaningfully in architecture, complexity, or tradeoffs
+- Not just be variations on the user's ideas
+
+Frame it as: "Let me add some alternatives you might not have considered..."
+
+### 3. Diversity Check
+
+Review all ideas (user's and yours). Ask yourself:
+- Are these actually different, or variations of the same approach?
+- What's the boldest option here?
+- Can any ideas be combined into something better?
+
+If the options feel too similar, push for a more divergent alternative.
+
+### 4. Select or Combine
+
+Present all approaches with tradeoffs. Use AskUserQuestion:
+
+> "Looking at these together, which direction feels right? Or should we combine elements from multiple approaches?"
+
+Document the chosen approach and why before proceeding.
+
+## When to Move On
+
+Proceed to `references/step-3-ui-ux.md` when:
+- An approach has been selected (or user chose to skip brainstorming)
+- The rationale for the choice is understood
+
+If the feature has no user interface, skip to `references/step-4-deep-dive.md`.

package/src/skills/spec-interview/references/{step-2-ui-ux.md → step-3-ui-ux.md}

@@ -1,6 +1,6 @@
-# Step 2: UI/UX Design
+# Step 3: UI/UX Design
 
-If the feature has no user interface, skip to `references/step-3-deep-dive.md`.
+If the feature has no user interface, skip to `references/step-4-deep-dive.md`.
 
 ## Determine Design Direction
 
@@ -67,7 +67,7 @@ Format as simple numbered steps under each flow name.
 
 ## When to Move On
 
-Proceed to `references/step-3-deep-dive.md` when:
+Proceed to `references/step-4-deep-dive.md` when:
 - Design direction is agreed upon
 - Wireframes exist for primary screens
 - User has confirmed the layout approach

package/src/skills/spec-interview/references/{step-3-deep-dive.md → step-4-deep-dive.md}

@@ -1,4 +1,4 @@
-# Step 3: Deep Dive
+# Step 4: Deep Dive
 
 Cover all specification areas through conversation. Update `docs/specs/<name>/spec.md` incrementally as information emerges.
 
@@ -27,6 +27,19 @@ Example: To understand auth integration:
 
 No assumptions. If you don't know how something works, send an Explorer to find out.
 
+### File Landscape
+
+Once the feature is understood, identify concrete file paths. Ask an Explorer:
+
+> "To implement [this feature], what files would need to be created or modified? Give me concrete file paths."
+
+Capture:
+- **Files to create**: New files with full paths (e.g., `src/models/notification.ts`)
+- **Files to modify**: Existing files that need changes (e.g., `src/routes/index.ts`)
+- **Directory conventions**: Where each type of code lives in this project
+
+This becomes the File Landscape section of the spec, which spec-to-tasks uses directly.
+
 ### Data Model
 - Entities and relationships
 - Constraints (required fields, validations, limits)
@@ -67,6 +80,14 @@ Write to `docs/specs/<name>/spec.md` with this structure:
 - External: [APIs, services, libraries]
 - Data flows: [in/out]
 
+## File Landscape
+
+### Files to Create
+- [path/to/new-file.ts]: [purpose]
+
+### Files to Modify
+- [path/to/existing-file.ts]: [what changes]
+
 ## Data Model
 [Entities, relationships, constraints]
 
@@ -79,6 +100,7 @@ Write to `docs/specs/<name>/spec.md` with this structure:
 
 ## Acceptance Criteria
 - [ ] [Testable requirement]
+  **Verify:** [verification method]
 
 ## Blockers
 - [ ] [Blocker]: [what's needed]
@@ -86,4 +108,4 @@ Write to `docs/specs/<name>/spec.md` with this structure:
 
 ## When to Move On
 
-Move to `references/step-4-research-needs.md` when all areas have been covered and the spec document is substantially complete.
+Move to `references/step-5-research-needs.md` when all areas have been covered and the spec document is substantially complete.

package/src/skills/spec-interview/references/{step-4-research-needs.md → step-5-research-needs.md}

@@ -1,4 +1,4 @@
-# Step 4: Identify Research Needs
+# Step 5: Identify Research Needs
 
 Before finalizing, determine if implementation requires unfamiliar paradigms.
 
@@ -40,11 +40,11 @@ Wait for research to complete before continuing. The research output goes to `do
 
 ## If No Research Needed
 
-State that all paradigms have existing examples in the codebase. Proceed to `references/step-5-verification.md`.
+State that all paradigms have existing examples in the codebase. Proceed to `references/step-6-verification.md`.
 
 ## When to Move On
 
-Proceed to `references/step-5-verification.md` when:
+Proceed to `references/step-6-verification.md` when:
 - All new paradigms have been researched, OR
 - User confirmed no research is needed, OR
 - All patterns have existing codebase examples

package/src/skills/spec-interview/references/{step-5-verification.md → step-6-verification.md}

@@ -1,4 +1,4 @@
-# Step 5: Verification Planning
+# Step 6: Verification Planning
 
 Every acceptance criterion needs a specific, executable verification method. The goal: autonomous implementation with zero ambiguity about whether something works.
 
@@ -71,4 +71,4 @@ The standard: if the agent executes the verification and it passes, the feature
 
 ## When to Move On
 
-Proceed to `references/step-6-finalize.md` when every acceptance criterion has a verification method and the user agrees each method proves the criterion works.
+Proceed to `references/step-7-finalize.md` when every acceptance criterion has a verification method and the user agrees each method proves the criterion works.

package/src/skills/spec-interview/references/{step-6-finalize.md → step-7-finalize.md}

@@ -1,4 +1,4 @@
-# Step 6: Finalize
+# Step 7: Finalize
 
 Review the spec for completeness and soundness, then hand off.
 

package/src/skills/spec-to-tasks/references/step-1-identify-spec.md

@@ -19,11 +19,20 @@ If no specs found in git history, check `docs/specs/` for any spec files and ask
 ## Verify the Spec
 
 Read the spec file. Confirm it contains enough detail to generate implementation tasks:
-- Clear requirements or user stories
-- Technical approach or architecture decisions
-- Defined scope
 
-If the spec is incomplete or unclear, inform the user and ask if they want to complete the spec first.
+**Required:**
+- Acceptance Criteria with verification methods (each criterion becomes a task)
+- Clear behavior descriptions
+
+**Expected (from spec-interview):**
+- File Landscape section listing files to create/modify
+- Integration points and data model
+
+**If missing acceptance criteria or verification methods:**
+Inform the user: "This spec doesn't have acceptance criteria with verification methods. Each task needs a clear pass/fail test. Would you like to add them now, or run spec-interview to complete the spec?"
+
+**If missing file landscape:**
+Proceed to step 2 where we'll discover file paths via exploration.
 
 ## Next Step
 

package/src/skills/spec-to-tasks/references/step-2-explore.md

@@ -1,25 +1,43 @@
-# Step 2: Explore the Codebase
+# Step 2: Verify File Landscape
 
-Before generating tasks, understand the codebase structure to determine accurate file paths.
+The spec should already contain a File Landscape section from the interview process. This step verifies and supplements it.
 
-## Launch Exploration Subagent
+## Check the Spec
 
-Use a subagent to explore the codebase. The subagent should identify:
+Read the spec's File Landscape section. It should list:
+- **Files to create**: New files with paths and purposes
+- **Files to modify**: Existing files that need changes
 
-- **Existing patterns**: Where do models, services, routes, and components live?
-- **Naming conventions**: How are files and directories named?
-- **Files to modify**: Which existing files need changes for this feature?
-- **Files to create**: What new files are needed and where should they go?
+If the File Landscape section is missing or incomplete, use an Explorer to fill the gaps:
 
-Provide the subagent with the spec content so it understands what is being implemented.
+> "To implement [feature from spec], what files would need to be created or modified? Give me concrete file paths."
 
-## Capture Findings
+## Map Files to Acceptance Criteria
 
-The subagent should return:
-- A list of directories and their purposes
-- Specific file paths for each aspect of the feature
-- Any existing code that the new feature should integrate with
+For each acceptance criterion in the spec, identify which files are involved. This mapping drives task generation.
+
+Example:
+```
+"User can receive notifications"
+  → src/models/notification.ts
+  → src/services/notificationService.ts
+  → src/services/notificationService.test.ts
+
+"User can view notification list"
+  → src/routes/notifications.ts
+  → src/components/NotificationList.tsx
+```
+
+If a criterion's files aren't clear from the spec, ask an Explorer:
+
+> "What files would be involved in making this criterion pass: [criterion]?"
+
+## Output
+
+You should now have:
+1. Complete list of files to create and modify
+2. Each acceptance criterion mapped to its files
 
 ## Next Step
 
-Once exploration is complete and file paths are known, read `references/step-3-generate.md`.
+Once files are mapped to criteria, read `references/step-3-generate.md`.

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

@@ -1,31 +1,65 @@
-# Step 3: Generate Task Manifest
+# Step 3: Generate Task Files
 
-Create the task manifest based on the spec and codebase exploration.
+Create individual task files based on the spec and codebase exploration.
 
 ## Task Principles
 
-**Atomic**: Each task is a single, focused change — one model, one endpoint, one component, or one test file. A task should take an AI agent one focused session to complete.
+**Criterion-based**: Each task corresponds to one acceptance criterion from the spec. A task includes all files needed to make that criterion pass. Do NOT split by file or architectural layer.
 
-**Ordered**: Sequence tasks so each can be completed without blocking. Tasks with no dependencies can share the same `depends_on` value to signal parallel execution.
+**Verifiable**: Every task has a verification method from the spec. A coder implements, a QA agent verifies, and the loop continues until it passes.
 
-**Concrete file paths**: Use the file paths discovered in Step 2. Every task specifies which files it touches.
+**Ordered**: Name files so they sort in dependency order (T001, T002, etc.). Tasks with no dependencies on each other can be worked in parallel.
 
-**Declarative**: Tasks describe WHAT to implement, not HOW. Implementation details live in the spec.
+**Concrete file paths**: Use the file paths discovered in Step 2. Every task lists all files it touches.
 
-## Generate the Manifest
+## Deriving Tasks from Acceptance Criteria
 
-Write to `docs/specs/<name>/tasks.yaml` using the template in `templates/tasks.yaml`.
+Each acceptance criterion in the spec becomes one task.
 
-Derive tasks from the spec:
-- Break each requirement or feature section into atomic units
-- Sequence by dependency (data layer, then business logic, then API, then integration)
-- Reference specific spec sections in task descriptions where helpful
+**For each criterion, determine:**
+1. What files must exist or change for this to pass?
+2. What's the verification method from the spec?
+3. What other criteria must pass first? (dependencies)
 
-## Review with User
+**Grouping rules:**
+- If two criteria share foundational work (e.g., both need a model), the first task creates the foundation, later tasks build on it
+- If a criterion is too large (touches 10+ files), flag it — the spec may need refinement
+- Small tasks are fine; artificial splits are not
 
-Present:
-1. Number of tasks and estimated scope
-2. Task titles in dependency order
-3. Offer to show full YAML or proceed to implementation
+**Anti-patterns to avoid:**
+- "Create the User model" — no verifiable outcome
+- "Add service layer" — implementation detail, not behavior
+- "Set up database schema" — means to an end, not the end
 
-Save the manifest to `docs/specs/<name>/tasks.yaml`.
+**Good task boundaries:**
+- "User can register with email" — verifiable, coherent
+- "Duplicate emails are rejected" — verifiable, coherent
+- "Dashboard shows notification count" — verifiable, coherent
+
+## Validate Criteria Quality
+
+Before generating tasks, verify each acceptance criterion has:
+- A specific, testable condition
+- A verification method (test command, agent-browser script, or query)
+
+If criteria are vague or missing verification, stop and ask:
+> "The criterion '[X]' doesn't have a clear verification method. Should I suggest one, or would you like to refine the spec first?"
+
+## Generate Task Files
+
+Create a `tasks/` directory inside the spec folder:
+
+```
+docs/specs/<name>/
+├── spec.md
+└── tasks/
+    ├── T001-<slug>.md
+    ├── T002-<slug>.md
+    └── T003-<slug>.md
+```
+
+Use the template in `templates/task.md` for each file. Name files in dependency order so alphabetical sorting reflects execution order.
+
+## Next Step
+
+Once task files are generated, read `references/step-4-review.md` to run the review before presenting to the user.

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

@@ -0,0 +1,44 @@
+# Step 4: Review Task Breakdown
+
+Before presenting to the user, run a review to catch issues.
+
+## Run Task Review
+
+Invoke the `task-review` skill, specifying the spec name:
+
+```
+Skill(skill: "task-review", args: "<spec-name>")
+```
+
+The review will check:
+- Coverage (all criteria have tasks)
+- Dependency order (tasks properly sequenced)
+- File plausibility (paths make sense)
+- Verification executability (concrete commands)
+- Task scope (appropriately sized)
+- Consistency (format, frontmatter)
+
+## Handle Findings
+
+The review returns findings categorized as Critical, Warning, or Note.
+
+**Critical issues**: Fix before proceeding. Update the affected task files.
+
+**Warnings**: Present to user with your recommendation (fix or skip).
+
+**Notes**: Mention briefly, no action required.
+
+## Present to User
+
+After addressing critical issues, present:
+
+1. Number of tasks generated
+2. Task titles in dependency order
+3. Any warnings from the review (with recommendations)
+4. Offer to show task files or proceed to implementation
+
+If the user wants changes, update the task files and re-run the review.
+
+## Complete
+
+Once the user approves the task breakdown, the skill is complete. The tasks are ready for implementation.

package/src/skills/spec-to-tasks/templates/task.md

@@ -0,0 +1,30 @@
+---
+id: T00X
+title: <Short descriptive title — the acceptance criterion>
+status: pending
+depends_on: []
+---
+
+## Criterion
+
+<The acceptance criterion from the spec, verbatim or lightly edited for clarity>
+
+## Files
+
+- <path/to/file.ts>
+- <path/to/another-file.ts>
+- <path/to/test-file.test.ts>
+
+## Verification
+
+<The verification method from the spec — test command, agent-browser script, or manual steps>
+
+---
+
+## Implementation Notes
+
+<!-- Coder agent writes here after each implementation attempt -->
+
+## Review Notes
+
+<!-- QA agent writes here after each review pass -->

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

@@ -0,0 +1,17 @@
+---
+name: task-review
+description: Reviews task breakdown for completeness, correct ordering, and implementation readiness. Use after spec-to-tasks generates task files.
+argument-hint: <spec-name>
+---
+
+# Task Review
+
+Review the task breakdown to catch issues before implementation begins.
+
+## What To Do Now
+
+If an argument was provided, use it as the spec name. Otherwise, find the most recent spec with a `tasks/` directory.
+
+Read the spec file and all task files in the `tasks/` directory.
+
+Then read `references/checklist.md` and evaluate each item.

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

@@ -0,0 +1,101 @@
+# 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
+
+## 1. Coverage
+
+Compare acceptance criteria in the spec to tasks generated.
+
+**Check:**
+- [ ] Every acceptance criterion has exactly one corresponding task
+- [ ] No criteria were skipped or forgotten
+- [ ] No phantom tasks that don't map to a criterion
+
+**How to verify:**
+List each criterion from the spec's Acceptance Criteria section. For each, find the matching task file. Flag any orphans in either direction.
+
+## 2. Dependency Order
+
+Tasks should be sequenced so each can be completed without waiting on later tasks.
+
+**Check:**
+- [ ] Task file names sort in valid execution order (T001, T002, etc.)
+- [ ] Each task's `depends_on` references only earlier tasks
+- [ ] No circular dependencies
+- [ ] Foundation work comes before features that use it
+
+**Common issues:**
+- API route task before the service it calls
+- UI component before the API it fetches from
+- Test file before the code it tests (tests should be in same task as code)
+
+## 3. File Plausibility
+
+Files listed in each task should make sense for the project.
+
+**Check:**
+- [ ] File paths follow project conventions (use Explorer if unsure)
+- [ ] Files to modify actually exist in the codebase
+- [ ] Files to create are in appropriate directories
+- [ ] No duplicate files across tasks (each file appears in exactly one task)
+
+**How to verify:**
+For files to modify, confirm they exist. For files to create, confirm the parent directory exists and the naming follows conventions.
+
+## 4. Verification Executability
+
+Each task's verification method must be concrete and runnable.
+
+**Check:**
+- [ ] Verification is a specific command or script, not vague prose
+- [ ] Test file paths exist or will be created by the task
+- [ ] agent-browser commands reference real routes/elements
+- [ ] No "manually verify" without clear steps
+
+**Red flags:**
+- "Verify it works correctly"
+- "Check that the feature functions"
+- Test commands for files not listed in the task
+
+## 5. Task Scope
+
+Each task should be appropriately sized for the coder→QA loop.
+
+**Check:**
+- [ ] No task touches more than ~10 files (consider splitting)
+- [ ] No trivially small tasks that could merge with related work
+- [ ] Each task produces a verifiable outcome, not just "creates a file"
+
+## 6. Consistency
+
+Cross-check task files against each other and the spec.
+
+**Check:**
+- [ ] Task titles match or closely reflect the acceptance criterion
+- [ ] Status is `pending` for all new tasks
+- [ ] Frontmatter format is consistent across all task files
+- [ ] Implementation Notes and Review Notes sections exist (empty is fine)
+
+---
+
+## Output Format
+
+Return findings as a structured list:
+
+```
+## Critical Issues
+- [T002] Depends on T005 which comes later - wrong order
+- [T003] Missing verification method
+
+## Warnings
+- [T001] touches 12 files - consider splitting
+- Criterion "User can delete account" has no corresponding task
+
+## Notes
+- [T004] Could merge with T005 since they share the same files
+```
+
+If no issues found, state: "Task breakdown looks good. All criteria covered, dependencies valid, verification methods concrete."

package/src/skills/spec-to-tasks/templates/tasks.yaml

@@ -1,25 +0,0 @@
-spec: <name>
-spec_path: docs/specs/<name>/spec.md
-generated: <ISO timestamp>
-
-tasks:
-  - id: T001
-    title: <Short descriptive title>
-    description: |
-      <What to implement>
-      <Reference to spec section if applicable>
-    files:
-      - <path/to/file.ts>
-    depends_on: []
-    acceptance: |
-      <How to verify this task is complete>
-
-  - id: T002
-    title: <Next task>
-    description: |
-      <What to implement>
-    files:
-      - <path/to/file.ts>
-    depends_on: [T001]
-    acceptance: |
-      <Verification criteria>