cc-dev-template 0.1.50 → 0.1.51

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

@@ -0,0 +1,77 @@
+# Step 2: Deep Dive
+
+Cover all specification areas through conversation. Update `docs/specs/<name>/spec.md` incrementally as information emerges.
+
+## Areas to Cover
+
+### Intent & Goals
+- Primary goal and business/user value
+- Success metrics and how to verify it works
+
+### Integration Points
+- Existing system components this touches
+- External services, APIs, or libraries
+- Data flows in and out
+
+Spawn exploration subagents to investigate the codebase when integration questions arise. They return only relevant findings.
+
+### Data Model
+- Entities and relationships
+- Constraints (required fields, validations, limits)
+- Extending existing models vs creating new ones
+
+### Behavior & Flows
+- Main user flows, step by step
+- Triggers and resulting actions
+- Different modes or variations
+
+### Edge Cases & Error Handling
+- Failure modes and how to handle them
+- Invalid input handling
+- Boundary conditions
+- Partial failure recovery
+
+### Blockers & Dependencies
+- External dependencies (APIs, services, libraries)
+- Credentials or access needed
+- Decisions that must be made before implementation
+
+## Spec Structure
+
+Write to `docs/specs/<name>/spec.md` with this structure:
+
+```markdown
+# [Feature Name]
+
+## Overview
+[2-3 sentences: what and why]
+
+## Goals
+- [Primary goal]
+- [Secondary goals]
+
+## Integration Points
+- Touches: [existing components]
+- External: [APIs, services, libraries]
+- Data flows: [in/out]
+
+## Data Model
+[Entities, relationships, constraints]
+
+## Behavior
+### [Flow 1]
+[Step by step]
+
+## Edge Cases
+- [Case]: [handling]
+
+## Acceptance Criteria
+- [ ] [Testable requirement]
+
+## Blockers
+- [ ] [Blocker]: [what's needed]
+```
+
+## When to Move On
+
+Move to `references/step-3-finalize.md` when all areas have been covered and the spec document is substantially complete.

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

@@ -0,0 +1,19 @@
+# Step 3: Finalize
+
+Review the spec for completeness and hand off.
+
+## Review for Gaps
+
+Invoke the `spec-review` skill, specifying which spec to review. It analyzes the spec and returns feedback.
+
+If gaps are found, ask follow-up questions to address them. Repeat until review passes.
+
+## Complete the Interview
+
+Once review passes:
+
+1. Show the user the final spec
+2. Confirm they are satisfied
+3. Ask if they want to proceed to task breakdown
+
+If yes, invoke `spec-to-tasks` and specify which spec to break down.

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

@@ -1,20 +1,18 @@
 ---
 name: spec-review
-description: Reviews a feature specification for completeness. Called by spec-interview when a spec seems complete, or invoke directly with "review the spec", "check spec completeness", "is this spec ready".
+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.
 argument-hint: <spec-name>
 context: fork
 ---
 
 # Spec Review
 
-Analyze a specification for completeness and identify gaps.
+## Steps
 
-## What To Do
-
-1. **Identify the spec to review** - use the spec path if specified in the prompt, otherwise check git for the most recently modified spec in `docs/specs/`
+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. **Evaluate against the checklist below**
-4. **Return structured feedback**
+4. **Return structured feedback using the output format**
 
 ## Completeness Checklist
 
@@ -36,13 +34,13 @@ A spec is implementation-ready when ALL of these are satisfied:
 
 ### Implementation Readiness
 
-Ask yourself: "Could someone implement this feature completely hands-off, with zero questions?"
+The test: could someone implement this feature completely hands-off, with zero questions?
 
-Check for:
-- Vague language ("should handle errors appropriately" → HOW?)
-- Missing details ("integrates with auth" → WHERE? HOW?)
-- Unstated assumptions ("uses the standard pattern" → WHICH pattern?)
-- Blocking dependencies ("needs API access" → DO WE HAVE IT?)
+Flag these problems:
+- Vague language ("should handle errors appropriately" — HOW?)
+- Missing details ("integrates with auth" — WHERE? HOW?)
+- Unstated assumptions ("uses the standard pattern" — WHICH pattern?)
+- Blocking dependencies ("needs API access" — DO WE HAVE IT?)
 
 ## Output Format
 
@@ -66,5 +64,5 @@ Return the review as:
 [Specific questions to ask the user, or "Spec is implementation-ready"]
 ```
 
-If status is READY, the spec can proceed to task breakdown.
-If status is NEEDS WORK, list the specific questions that need answers.
+**READY**: Spec can proceed to task breakdown.
+**NEEDS WORK**: List specific questions that need answers.

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

@@ -1,94 +1,12 @@
 ---
 name: spec-to-tasks
-description: Breaks a feature specification into implementation tasks. Use when the user says "break down the spec", "create tasks from spec", "generate task list", or after a spec review passes.
+description: Converts a feature specification into implementation tasks. Use after a spec is complete and approved, or when planning work for a defined feature.
 argument-hint: <spec-name>
 context: fork
 ---
 
 # Spec to Tasks
 
-Convert a completed specification into an ordered list of atomic implementation tasks.
+## What To Do Now
 
-## What To Do
-
-1. **Identify the spec** - use the spec path if specified in the prompt, otherwise check git for the most recently modified spec in `docs/specs/`
-2. **Explore the codebase** - use a subagent to identify existing patterns, conventions, and where code should live
-3. **Generate the task manifest** - create `tasks.yaml` in the same directory as the spec
-4. **Review with user** - show the task list for approval
-
-## Task Principles
-
-**Atomic tasks.** Each task is a single, focused change:
-- One model/entity
-- One endpoint/route
-- One component
-- One test file
-
-A task should take an AI agent one focused session to complete.
-
-**Ordered by dependency.** Tasks are sequenced so each can be completed in order without blocking.
-
-**Include file paths.** Each task specifies the target file(s) based on codebase exploration.
-
-**No code in tasks.** Tasks describe WHAT to do, not HOW. Implementation details are in the spec.
-
-## Task Format
-
-Write to `docs/specs/<name>/tasks.yaml`:
-
-```yaml
-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>
-```
-
-## Generating File Paths
-
-Before writing tasks, explore the codebase to understand:
-- Existing file patterns (where do models live? services? routes?)
-- Specific files that need modification
-- New files that need creation and where they should go
-
-Use these findings to populate the `files` field for each task.
-
-## Ordering Tasks
-
-Sequence by dependency:
-1. **Data layer first** - Models, schemas, database changes
-2. **Business logic** - Services, utilities, core functions
-3. **API layer** - Routes, controllers, endpoints
-4. **Integration** - Connecting components, wiring up
-5. **Tests** - Can be parallel with implementation or after
-
-If tasks are independent, give them the same `depends_on`. This signals they could run in parallel.
-
-## Output
-
-After generating:
-1. Show the user a summary: number of tasks, estimated scope
-2. List the task titles in order
-3. Ask if they want to see the full YAML or proceed to implementation
-
-Save the manifest to `docs/specs/<name>/tasks.yaml`.
+Read `references/step-1-identify-spec.md` and begin.

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

@@ -0,0 +1,30 @@
+# Step 1: Identify the Spec
+
+Locate the specification to convert into tasks.
+
+## If Spec Path Provided
+
+Use the path from the user's prompt. Verify the file exists and read it.
+
+## If No Path Provided
+
+Find the most recently modified spec:
+
+```bash
+git log -1 --name-only --diff-filter=AM -- 'docs/specs/**/*.md' | tail -1
+```
+
+If no specs found in git history, check `docs/specs/` for any spec files and ask the user which one to use.
+
+## 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.
+
+## Next Step
+
+Once the spec is identified and verified, read `references/step-2-explore.md`.

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

@@ -0,0 +1,25 @@
+# Step 2: Explore the Codebase
+
+Before generating tasks, understand the codebase structure to determine accurate file paths.
+
+## Launch Exploration Subagent
+
+Use a subagent to explore the codebase. The subagent should identify:
+
+- **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?
+
+Provide the subagent with the spec content so it understands what is being implemented.
+
+## Capture Findings
+
+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
+
+## Next Step
+
+Once exploration is complete and file paths are known, read `references/step-3-generate.md`.

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

@@ -0,0 +1,31 @@
+# Step 3: Generate Task Manifest
+
+Create the task manifest 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.
+
+**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.
+
+**Concrete file paths**: Use the file paths discovered in Step 2. Every task specifies which files it touches.
+
+**Declarative**: Tasks describe WHAT to implement, not HOW. Implementation details live in the spec.
+
+## Generate the Manifest
+
+Write to `docs/specs/<name>/tasks.yaml` using the template in `templates/tasks.yaml`.
+
+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
+
+## Review with User
+
+Present:
+1. Number of tasks and estimated scope
+2. Task titles in dependency order
+3. Offer to show full YAML or proceed to implementation
+
+Save the manifest to `docs/specs/<name>/tasks.yaml`.

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

@@ -0,0 +1,25 @@
+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>

package/src/mcp-servers/qa-server/README.md

@@ -1,122 +0,0 @@
-# QA Server
-
-MCP server that spawns a Claude sub-agent for frontend visual inspection.
-
-## Problem
-
-Playwright MCP adds ~20k tokens to context just from tool definitions, even when browser inspection isn't needed. This wastes context in long sessions.
-
-## Solution
-
-This server exposes a single `inspect_frontend` tool (~500 tokens) that spawns a sub-agent with full browser capabilities on-demand.
-
-```
-Main Conversation (~500 tokens)
-    │
-    └── mcp__qa__inspect_frontend
-            │
-            └── Sub-agent with @playwright/mcp (full browser control)
-                    │
-                    └── Returns QA report
-```
-
-**Note:** No system Chrome installation is required. Playwright automatically downloads and manages its own Chromium browser.
-
-## Installation
-
-```bash
-cd src/mcp-servers/qa-server
-npm install
-npm run build
-```
-
-Then add to Claude Code:
-
-```bash
-claude mcp add qa node /path/to/qa-server/dist/index.js
-```
-
-Or in `~/.claude.json`:
-
-```json
-{
-  "mcpServers": {
-    "qa": {
-      "type": "stdio",
-      "command": "node",
-      "args": ["/path/to/qa-server/dist/index.js"]
-    }
-  }
-}
-```
-
-## After Setup
-
-Remove Playwright MCP from your main config to save tokens (if previously added):
-
-```bash
-claude mcp remove playwright
-```
-
-## Usage
-
-From Claude Code conversation:
-
-```
-Inspect http://localhost:3000 and verify the login form works
-```
-
-Claude will call `mcp__qa__inspect_frontend` with:
-- url: "http://localhost:3000"
-- task: "verify the login form works"
-
-The sub-agent will:
-1. Navigate to the URL
-2. Take screenshots
-3. Check console errors
-4. Perform the task (click, fill forms, etc.)
-5. Return a structured QA report
-
-## Tool Definition
-
-```typescript
-{
-  name: "inspect_frontend",
-  description: "Spawn a QA sub-agent to visually inspect a frontend...",
-  inputSchema: {
-    type: "object",
-    properties: {
-      url: { type: "string", description: "URL to inspect" },
-      task: { type: "string", description: "What to inspect or test" }
-    },
-    required: ["url", "task"]
-  }
-}
-```
-
-## Sub-agent Capabilities
-
-The spawned sub-agent uses Opus (best visual understanding) and has access to Playwright MCP tools:
-
-- **Navigation**: browser_navigate, browser_tab_new, browser_tab_list, browser_tab_select, browser_wait_for
-- **Inspection**: browser_screenshot, browser_snapshot, browser_console_messages
-- **Interaction**: browser_click, browser_type, browser_hover, browser_press_key, browser_handle_dialog
-
-## Token Savings
-
-| Before | After |
-|--------|-------|
-| ~20k tokens (26 browser tools always loaded) | ~500 tokens (1 tool) |
-
-## Development
-
-```bash
-# Run in development mode
-npm run dev
-
-# Build for production
-npm run build
-
-# Run production build
-npm start
-```