cc-dev-template 0.1.80 → 0.1.82

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

@@ -0,0 +1,86 @@
+# Spec Generation
+
+These are drafts — you will review, refine, and present the spec to the user before proceeding.
+
+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`
+
+## 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
+
+## Task 1: External Research (if needed)
+
+Check `{spec_dir}/design.md` 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}
+
+## Overview
+{What this feature does, 2-3 sentences}
+
+## 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}
+
+## Integration Points
+{How this feature connects to existing systems — which files, which patterns, which services. Reference specific code from research.md.}
+
+## Acceptance Criteria
+
+### AC-1: {Criterion name}
+- **Given**: {precondition}
+- **When**: {action}
+- **Then**: {expected result}
+- **Verification**: {how to test — unit test, integration test, manual check}
+
+### AC-2: ...
+
+## Implementation Notes
+{Patterns to follow from design.md, ordering considerations, things to watch out for}
+
+## Out of Scope
+{Explicitly what this feature does NOT do}
+```
+
+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 3: Review Spec
+
+Present the full spec to the user. Walk through each section. Pay particular attention to:
+
+- 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?
+
+Revise based on user feedback.
+
+## Task 4: Proceed
+
+Update `{spec_dir}/state.yaml` — set `phase: tasks`.
+
+Use the Read tool on `references/step-6-tasks.md` to break the spec into implementation tasks.

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

@@ -0,0 +1,83 @@
+# 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.
+
+Read `{spec_dir}/spec.md` before proceeding.
+
+## Create Tasks
+
+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
+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
+- ...
+
+Each task touches all necessary layers of the stack and produces something independently testable.
+
+Map each acceptance criterion from the spec to one or more tasks. Every AC must be covered.
+
+## Task 2: Write Task Files
+
+Create `{spec_dir}/tasks/` directory. Write one file per task.
+
+`{spec_dir}/tasks/T001-{short-name}.md`:
+
+```yaml
+---
+id: T001
+title: {Short descriptive title}
+status: pending
+depends_on: []
+---
+```
+
+### 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}
+
+### Implementation Notes
+{Patterns to follow, edge cases, things to watch out for}
+
+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.
+
+## Task 3: Review Tasks
+
+Present the task breakdown to the user. For each task, show:
+
+- What it does
+- Why it's in this order (the vertical reasoning)
+- How it can be independently verified
+
+Revise based on user feedback.
+
+## Task 4: Proceed
+
+Update `{spec_dir}/state.yaml` — set `phase: implement`.
+
+Use the Read tool on `references/step-7-implement.md` to begin implementation.

package/src/skills/ship/references/step-7-implement.md

@@ -0,0 +1,61 @@
+# Implementation
+
+Orchestrate implementation using spec-implementer and spec-validator sub-agents. This follows the execute-spec pattern — you dispatch agents, you do not write code yourself.
+
+Read `{spec_dir}/spec.md` and list all task files in `{spec_dir}/tasks/`.
+
+## Create Tasks
+
+Create these tasks and work through them in order:
+
+1. "Hydrate task system" — load task files into Claude Code's task system
+2. "Implement tasks" — dispatch implementer agents
+3. "Validate tasks" — dispatch validator agents
+4. "Handle failures" — triage and re-attempt if needed
+5. "Finalize" — present results
+
+## Task 1: Hydrate
+
+Read each task file in `{spec_dir}/tasks/`. For each one, create a Claude Code task (TaskCreate) with the task title and description. Set up `blockedBy` relationships based on the `depends_on` field in each task file's frontmatter.
+
+## Task 2: Implement
+
+For each task that is ready (no blockers), dispatch an implementer:
+
+```
+Agent tool:
+  subagent_type: "spec-implementer"
+  prompt: "Implement the task described in {task_file_path}. Read the task file for requirements, files to modify, and verification steps. Also read {spec_dir}/spec.md for overall context. After implementation, run the verification steps described in the task file."
+```
+
+Run independent tasks in parallel when possible. Mark each Claude Code task as completed when its implementer finishes successfully.
+
+## Task 3: Validate
+
+For each completed task, dispatch a validator:
+
+```
+Agent tool:
+  subagent_type: "spec-validator"
+  prompt: "Validate the task described in {task_file_path}. Review the code changes, run tests, and verify against the acceptance criteria in {spec_dir}/spec.md. Report pass/fail with details."
+```
+
+## Task 4: Handle Failures
+
+If any validation fails:
+
+- Re-dispatch the spec-implementer with the validation feedback appended to the prompt
+- Re-validate after fixes
+- If a task fails validation twice, flag it for the user with the error details and ask how to proceed
+
+## Task 5: Finalize
+
+Update `{spec_dir}/state.yaml` — set `phase: complete`.
+
+Present a summary to the user:
+
+- What was implemented
+- What tests pass
+- Any tasks that needed manual intervention
+
+Use the Read tool on `references/step-8-reflect.md` to review and improve this workflow.

package/src/skills/ship/references/step-8-reflect.md

@@ -0,0 +1,21 @@
+# Reflect
+
+Review how this workflow performed and identify improvements.
+
+## Self-Assessment
+
+Consider each phase:
+
+1. **Intent capture**: Did the intent document accurately capture what the user wanted? Did the spec drift from the original intent?
+2. **Question quality**: Were the research questions comprehensive? Were any critical questions missing that caused problems later?
+3. **Research objectivity**: Did the research stay objective? Did the contamination prevention work — or did implementation opinions leak in despite the separation?
+4. **Design decisions**: Were the design questions the right ones? Did the user have to course-correct on things that should have been caught earlier?
+5. **Spec completeness**: Were the API contracts and acceptance criteria specific enough for implementation agents?
+6. **Task ordering**: Did the tracer bullet ordering work? Were there dependency issues or tasks that should have been ordered differently?
+7. **Implementation**: Did agents struggle with any tasks? Were the task descriptions clear enough?
+
+## Skill Improvement
+
+If you identified concrete improvements to this workflow, edit the relevant step file in `references/` to address the issue. Only make changes that are clearly beneficial based on this session's experience — do not speculate about hypothetical improvements.
+
+Present your reflection and any changes to the user.

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

@@ -1,48 +0,0 @@
----
-allowed-tools: Grep, Glob, Task, TaskCreate, TaskList, TaskUpdate, TaskGet, AskUserQuestion, Bash
-hooks:
-  PreToolUse:
-    - matcher: "Read"
-      hooks:
-        - type: command
-          command: "$HOME/.claude/scripts/block-task-files.sh"
----
-
-# Execute Spec
-
-Orchestrates the implementation and validation of a spec's task breakdown.
-
-**Important**: This skill is an orchestrator only. It does NOT read task files or edit code directly. It dispatches agents and receives minimal status responses. All detailed work happens in the agents; all detailed findings live in the task files.
-
-## When to Use
-
-Invoke when you have a complete spec with a `tasks/` folder containing task files (T001-*.md, T002-*.md, etc.) ready for implementation.
-
-## Arguments
-
-This skill takes a spec path as an argument:
-- `docs/specs/my-feature` - path to the spec folder containing `spec.md` and `tasks/`
-
-## Workflow
-
-Read `references/workflow.md` for the full orchestration flow.
-
-## Phases
-
-1. **Hydrate** - Run parse script, create tasks with dependencies (NO file reading)
-2. **Build** - Dispatch spec-implementer agents, receive minimal status
-3. **Validate** - Dispatch spec-validator agents, receive pass/fail
-4. **Triage** - Re-dispatch implementers for failed tasks, loop until clean
-5. **Reflect** - Assess orchestration experience, improve skill files (mandatory)
-
-## Key Principles
-
-- **Never read task files** - Use the parse script for hydration, pass paths to agents
-- **Minimal context** - Agent returns are pass/fail only, details in task files
-- **Delegate everything** - Fixes go to spec-implementer, not done by orchestrator
-
-## Requirements
-
-- Spec folder must contain `spec.md` and `tasks/` directory
-- Task files must have YAML frontmatter with `id`, `title`, `status`, `depends_on`
-- The `spec-implementer` and `spec-validator` agents must be installed

package/src/skills/execute-spec/references/phase-1-hydrate.md

@@ -1,71 +0,0 @@
-# Phase 1: Hydrate Tasks
-
-Load task metadata into the Claude Code task system using the parse script.
-
-## Important: No File Reading
-
-The orchestrator does NOT read task files directly. Use the parse script.
-
-## Process
-
-```bash
-# Run the parse script
-node ~/.claude/scripts/parse-task-files.js {spec-path}
-```
-
-This outputs JSON:
-```json
-{
-  "specPath": "docs/specs/kiosk-storefront",
-  "specFile": "docs/specs/kiosk-storefront/spec.md",
-  "taskCount": 15,
-  "tasks": [
-    {
-      "id": "T001",
-      "title": "Public API endpoints",
-      "status": "pending",
-      "depends_on": [],
-      "path": "docs/specs/kiosk-storefront/tasks/T001-public-api-endpoints.md"
-    },
-    {
-      "id": "T002",
-      "title": "Kiosk routing",
-      "depends_on": ["T001"],
-      "path": "..."
-    }
-  ]
-}
-```
-
-## Create Tasks
-
-For each task in the JSON:
-
-```
-TaskCreate(
-  subject: "{id}: {title}",
-  description: "{path}",
-  activeForm: "Implementing {title}"
-)
-```
-
-The description is JUST the path. Agents read the file themselves.
-
-## Set Dependencies
-
-After creating all tasks, set up blockedBy relationships:
-
-```
-TaskUpdate(
-  taskId: {claude-task-id},
-  addBlockedBy: [mapped IDs from depends_on]
-)
-```
-
-Maintain a mapping of task IDs (T001, T002) to Claude task system IDs.
-
-## Output
-
-- All tasks in Claude Code task system
-- Dependencies configured
-- Ready for Phase 2

package/src/skills/execute-spec/references/phase-2-build.md

@@ -1,63 +0,0 @@
-# Phase 2: Build
-
-Dispatch spec-implementer agents for each task, respecting dependencies.
-
-## Process
-
-```
-Loop until all tasks complete:
-
-1. TaskList() to get current state
-
-2. Find ready tasks:
-   - status: pending
-   - blockedBy: empty (no unfinished dependencies)
-
-3. For each ready task:
-   - Extract task file path from description
-   - Mark as in_progress: TaskUpdate(taskId, status: "in_progress")
-   - Dispatch implementer:
-     Task(
-       subagent_type: "spec-implementer",
-       prompt: "{task-file-path}",
-       run_in_background: true,
-       description: "Implement {task-id}"
-     )
-
-4. Wait for completions:
-   - Agents mark tasks complete when done
-   - Poll TaskList periodically to check status
-   - As tasks complete, newly unblocked tasks become ready
-
-5. Repeat until no pending tasks remain
-```
-
-## Parallelism Strategy
-
-- Dispatch ALL ready tasks simultaneously
-- The dependency graph controls what can run in parallel
-- Example: If T002, T003, T004 all depend only on T001, they all start when T001 completes
-
-## Monitoring Progress
-
-Report progress as tasks complete:
-```
-Build Progress:
-  [x] T001: Public API endpoints (complete)
-  [~] T002: Kiosk routing (in progress)
-  [~] T003: Entity chain validation (in progress)
-  [ ] T007: Cart persistence (blocked by T005, T006)
-  ...
-```
-
-## Error Handling
-
-- If an implementer fails: Note the error, continue with other tasks
-- If a task stays in_progress too long: May need manual intervention
-- Failed tasks block their dependents
-
-## Output
-
-- All tasks implemented (or failed with notes)
-- Implementation Notes written to each task file
-- Ready for Phase 3: Validate

package/src/skills/execute-spec/references/phase-3-validate.md

@@ -1,72 +0,0 @@
-# Phase 3: Validate
-
-Dispatch spec-validator agents for each completed task.
-
-## Prerequisites
-
-- All build tasks complete
-- Code is stable (no more modifications happening)
-
-## Process
-
-```
-1. Get list of all tasks from TaskList()
-
-2. For each completed task:
-   - Extract task file path from description
-   - Dispatch validator:
-     Task(
-       subagent_type: "spec-validator",
-       prompt: "{task-file-path}",
-       run_in_background: true,
-       description: "Validate {task-id}"
-     )
-
-3. All validators run in parallel:
-   - Each creates its own browser session
-   - No dependencies between validators
-   - They don't modify code, just read and test
-
-4. Wait for all validators to complete
-
-5. Collect results:
-   - Read Review Notes from each task file
-   - Aggregate issues by severity
-```
-
-## Validator Behavior
-
-Each validator:
-1. Reviews code changes for the task
-2. Runs automated tests if available
-3. Performs E2E testing with agent-browser
-4. Writes findings to Review Notes section
-
-## Browser Session Isolation
-
-Validators use isolated sessions to prevent conflicts when running in parallel:
-```
---session validator-T001
---session validator-T002
-...
-```
-
-## Collecting Results
-
-After all validators complete, structure findings:
-```
-Validation Results:
-  T001: PASS
-  T002: PASS
-  T003: FAIL
-    - [critical] Button not clickable at /kiosk/:id/product
-    - [warning] ProductCard.tsx is 342 lines, consider splitting
-  T004: PASS
-  ...
-```
-
-## Output
-
-- Validation complete for all tasks
-- Issues collected and categorized
-- Ready for Phase 4: Triage

package/src/skills/execute-spec/references/phase-4-triage.md

@@ -1,75 +0,0 @@
-# Phase 4: Triage
-
-Process validation results and iterate until all tasks pass.
-
-## Process
-
-```
-1. Collect failed task IDs from validator returns
-   (Returns are minimal: "Issues: T005 - [brief list]")
-
-2. For each failed task:
-   - Re-dispatch spec-implementer with the task path
-   - Implementer reads Review Notes and addresses issues
-   - Returns: "Task complete: T005"
-
-3. Re-run spec-validator on fixed tasks
-   - Returns: "Pass: T005" or "Issues: T005 - ..."
-
-4. Repeat until:
-   - All tasks pass, OR
-   - User defers remaining issues
-```
-
-## No Separate Fixer Agent
-
-The spec-implementer handles fixes. When it reads the task file:
-- If Review Notes has issues → fix mode (address those issues)
-- If Review Notes is empty → initial mode (implement from scratch)
-
-The task file's Review Notes section IS the feedback mechanism.
-
-## When to Escalate to User
-
-Use AskUserQuestion when:
-- Same issue persists after 2+ fix attempts
-- Issue is architectural or unclear how to resolve
-- Trade-off decision needed (performance vs simplicity, etc.)
-
-```
-AskUserQuestion(
-  questions: [{
-    header: "Fix approach",
-    question: "T005 failed twice with: [issue]. How should we proceed?",
-    options: [
-      { label: "Try approach A", description: "..." },
-      { label: "Try approach B", description: "..." },
-      { label: "Defer", description: "Skip for now, add to backlog" }
-    ]
-  }]
-)
-```
-
-## Log-Based History
-
-Each pass appends to the task file:
-- Implementer appends to Implementation Notes
-- Validator appends to Review Notes
-
-This creates a debugging trail:
-```
-Implementation Notes:
-  Pass 1: Initial implementation...
-  Pass 2: Fixed idle timer issue...
-
-Review Notes:
-  Pass 1: [critical] Timer doesn't pause...
-  Pass 2: [pass] All issues resolved
-```
-
-## Exit Conditions
-
-Phase completes when:
-1. All validators return "Pass: TXXX"
-2. User explicitly defers remaining issues
-3. Max retry limit reached (suggest user intervention)

package/src/skills/execute-spec/references/phase-5-reflect.md

@@ -1,34 +0,0 @@
-# Phase 5: Reflect and Improve
-
-**IMPORTANT: This step is mandatory. The execute-spec workflow is not complete until this step is finished. Do not skip this.**
-
-Reflect on your experience orchestrating this spec execution. The purpose is to improve the execute-spec skill itself based on what you just learned.
-
-## Assess
-
-Answer these questions honestly:
-
-1. Were any orchestration patterns in this workflow wrong, incomplete, or misleading?
-2. Did the dispatch instructions for implementers or validators cause confusion or failures?
-3. Did the triage loop reveal a pattern that should be encoded for next time?
-4. Were the dependency resolution or parallelism strategies effective, or did they need adjustment?
-5. Did the minimal-context principle (pass/fail only) hold up, or did you need more detail from agents?
-6. Did any scripts, paths, or agent types fail and require correction?
-
-## Act
-
-If you identified issues above, fix them now:
-
-1. Identify the specific file in the execute-spec skill directory where the issue lives
-2. Read that file
-3. Apply the fix — add what was missing, correct what was wrong
-4. Apply the tribal knowledge test: only add what a fresh Claude instance would not already know
-5. Keep the file within its size target
-
-If no issues were found, confirm that to the user.
-
-## Report
-
-Tell the user:
-- What you changed in the execute-spec skill and why, OR
-- That no updates were needed and the skill performed correctly