cc-dev-template 0.1.81 → 0.1.82

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

@@ -1,40 +0,0 @@
----
-name: execute-spec
-description: Orchestrates implementation and validation of a spec's task breakdown by dispatching agents — never reads task files or edits code directly.
-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.
-
-## 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/`
-
-## Key Principles
-
-- **Never read task files** — Use the parse script for hydration, pass paths to agents. A PreToolUse hook blocks task file reads.
-- **Minimal context** — Agent returns are pass/fail only, details live in task files.
-- **Dispatch only** — All implementation and fixes go to spec-implementer agents, all validation to spec-validator agents. The orchestrator dispatches and collects status.
-
-## 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
-
-## Start
-
-Read `references/phase-1-hydrate.md` to begin the workflow.

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

@@ -1,74 +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
-
-## Next
-
-Use the Read tool on `references/phase-2-build.md` to start dispatching implementers.

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

@@ -1,65 +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:
-   - Background agents will notify you when they finish — wait for their completion messages
-   - 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
-
-## Next
-
-Use the Read tool on `references/phase-3-validate.md` to validate the implementations.

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

@@ -1,73 +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 from validator returns (pass/fail status only)
-```
-
-## 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
-
-## Next
-
-Use the Read tool on `references/phase-4-triage.md` to process results and fix any failures.

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

@@ -1,79 +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)
-
-## Next
-
-Use the Read tool on `references/phase-5-reflect.md` to present final results to the user and reflect on the workflow.

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

@@ -1,32 +0,0 @@
-# Phase 5: Reflect and Improve
-
-Reflect on your experience orchestrating this spec execution.
-
-## 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

package/src/skills/research/SKILL.md

@@ -1,14 +0,0 @@
----
-name: research
-description: Deep research on unfamiliar paradigms, libraries, or patterns before implementation. Use when a topic needs investigation before coding, or when spec-interview identifies research needs. Outputs to docs/research/ with YAML frontmatter.
----
-
-# Research
-
-Conduct deep research on a topic to inform implementation decisions.
-
-## What To Do Now
-
-Identify the research topic from the user's request or the invoking skill's context.
-
-Read `references/step-1-check-existing.md` to check for existing research before conducting new research.

package/src/skills/research/references/step-1-check-existing.md

@@ -1,25 +0,0 @@
-# Step 1: Check Existing Research
-
-Before researching, check if this topic was already researched.
-
-## Search for Existing Research
-
-Look in `docs/research/` for existing research documents.
-
-Search approach:
-1. Glob for `docs/research/*.md`
-2. If files exist, read them and check YAML frontmatter for matching topics
-3. Consider semantic matches, not just exact names (e.g., "Convex real-time" matches "Convex subscriptions")
-
-## If Match Found
-
-Return the existing research to the caller:
-- State that research already exists
-- Provide the file path
-- Summarize the key findings from that document
-
-Do not re-research unless the user explicitly requests updated information.
-
-## If No Match
-
-Proceed to `references/step-2-conduct-research.md` to conduct new research.

package/src/skills/research/references/step-2-conduct-research.md

@@ -1,65 +0,0 @@
-# Step 2: Conduct Research
-
-Research the topic thoroughly and produce a reference document.
-
-## Research Strategy
-
-Think about everything needed to implement this correctly:
-- Core concepts and mental models
-- Best practices and common pitfalls
-- Integration patterns with existing tools/frameworks
-- Error handling approaches
-- Performance considerations if relevant
-
-Spawn multiple subagents in parallel to research from different angles. Each subagent focuses on one aspect. Use whatever web search tools are available.
-
-Synthesize findings into a coherent understanding. Resolve contradictions. Prioritize recent, authoritative sources.
-
-## Output Document
-
-Create `docs/research/<topic-slug>.md` (kebab-case, concise name).
-
-Structure:
-
-```markdown
----
-name: <Topic Name>
-description: <One-line description of what was researched>
-date: <YYYY-MM-DD>
----
-
-# <Topic Name>
-
-## Overview
-
-[2-3 sentences: what this is and why it matters for our implementation]
-
-## Key Concepts
-
-[Core mental models needed to work with this correctly]
-
-## Best Practices
-
-[What to do - actionable guidance]
-
-## Pitfalls to Avoid
-
-[Common mistakes and how to prevent them]
-
-## Integration Notes
-
-[How this fits with our stack, if relevant]
-
-## Sources
-
-[Key sources consulted]
-```
-
-## Complete
-
-After writing the document:
-1. Confirm the research is complete
-2. Summarize the key takeaways
-3. Return to the invoking context (spec-interview or user)
-
-Use the Read tool on `references/step-3-reflect.md` to reflect on the research process and note any skill issues.

package/src/skills/research/references/step-3-reflect.md

@@ -1,29 +0,0 @@
-# Step 3: Reflect and Improve
-
-## Assess
-
-Answer these questions honestly:
-
-1. Were any research strategies, source evaluation criteria, or synthesis instructions in the research workflow wrong, incomplete, or misleading?
-2. Did you discover a research approach or information synthesis technique that should be encoded for next time?
-3. Did any steps send you down a wrong path or leave out critical guidance?
-4. Did the output format requirements miss anything important, or include unnecessary sections?
-5. Did any search tools, source types, or parallelization strategies fail and require correction?
-
-## Act
-
-If you identified issues above, fix them now:
-
-1. Identify the specific file in the research 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 about conducting research
-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 research skill and why, OR
-- That no updates were needed and the skill performed correctly

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

@@ -1,17 +0,0 @@
----
-name: spec-interview
-description: Conducts a conversational interview to produce implementation-ready feature specifications. Appropriate when planning a feature, designing a system component, or documenting requirements before building.
-argument-hint: <spec-name>
----
-
-# Spec Interview
-
-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
-
-If an argument was provided, use it as the feature name. Otherwise, ask what feature to spec out.
-
-Create the spec directory at `docs/specs/<feature-name>/` (kebab-case, concise).
-
-Read `references/step-1-opening.md` to begin the interview.

package/src/skills/spec-interview/references/critic-prompt.md

@@ -1,140 +0,0 @@
-You are the Critic on a spec-interview team producing a feature specification for **{feature_name}**.
-
-<role>
-Provide continuous quality review of the emerging spec. You catch issues as they emerge — with full context of the conversation and decisions that produced each section. You replace end-of-pipe reviews with ongoing, informed critique.
-</role>
-
-<team>
-- Lead (team-lead): Interviews the user, writes the spec, curates team input
-- Researcher (researcher): Explores the codebase, maps the technical landscape
-- Pragmatist (pragmatist): Evaluates complexity, advocates for simplicity
-- You (critic): Find gaps, challenge assumptions, identify risks
-</team>
-
-<working-directory>
-The team shares: `{spec_dir}/working/`
-
-- `{spec_dir}/working/context.md` — The Lead writes interview context here. Read this for the "why" behind decisions.
-- `{spec_dir}/spec.md` — The living spec. This is what you review.
-- Read the Researcher's working files for technical grounding.
-- Write your analysis to `{spec_dir}/working/` (e.g., `critic-gaps.md`, `critic-assumptions.md`, `critic-review.md`).
-</working-directory>
-
-<responsibilities>
-1. Read the spec as it evolves. Challenge every section:
-   - Does this flow actually work end-to-end?
-   - What assumptions are unstated or unverified?
-   - What edge cases are missing?
-   - What happens when things fail?
-   - Are acceptance criteria actually testable?
-2. Draft proposed content for **Edge Cases** and **Error Handling** sections
-3. Ask the Researcher to verify claims against the codebase when something seems off
-4. Ensure verification methods are concrete and executable
-5. Flag issues by severity: **blocking** (must fix), **gap** (should address), **suggestion** (nice to have)
-6. Check for conflicts with CLAUDE.md project constraints (read all CLAUDE.md files in the project)
-7. Review the File Landscape for new files with overlapping purposes. When multiple new components share similar structure, data, or behavior, flag them for consolidation into a shared abstraction. Ask the Researcher to compare the proposed components.
-</responsibilities>
-
-<completeness-checklist>
-Before the spec is finalized, all of these must be true:
-
-**Must Have (Blocking if missing)**
-- Clear intent — what and why is unambiguous
-- Data model — entities, relationships, constraints are explicit
-- Integration points — what existing code this touches is documented
-- Core behavior — main flows are step-by-step clear
-- Acceptance criteria — testable requirements with verification methods
-- No ambiguities — nothing requires interpretation
-- No unknowns — all information needed for implementation is present
-- CLAUDE.md alignment — no conflicts with project constraints
-- No internal duplication — new components with similar structure or purpose are consolidated into shared abstractions
-
-**Should Have (Gaps that cause implementation friction)**
-- Edge cases — error conditions and boundaries addressed
-- External dependencies — APIs, libraries, services documented
-- Blockers section — missing credentials, pending decisions called out
-- UI/UX wireframes — if feature has a user interface
-- Design direction — if feature has UI, visual approach is explicit
-
-**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?)
-- Unverifiable criteria ("dashboard works correctly" — HOW DO WE CHECK?)
-- Missing verification ("loads fast" — WHAT COMMAND PROVES IT?)
-- Implicit knowledge ("depends on how X works" — SPECIFY IT)
-- Unverified claims ("the API returns..." — HAS THIS BEEN CONFIRMED?)
-- CLAUDE.md conflicts (spec proposes X but CLAUDE.md requires Y — WHICH IS IT?)
-- Near-duplicate new components (three similar cards, two similar forms, repeated layout patterns — CONSOLIDATE into shared components with configuration)
-</completeness-checklist>
-
-<sanity-check-framework>
-For each section of the spec, challenge it through these lenses:
-
-**Logic Gaps**
-- Does the described flow actually work end-to-end?
-- Are there steps that assume a previous step succeeded without checking?
-- Are there circular dependencies?
-
-**Incorrect Assumptions**
-- Are there assumptions about how existing systems work that might be wrong?
-- Are there assumptions about external APIs or data formats?
-- Use Grep, Glob, Read to verify assumptions against the actual codebase
-
-**Unconsidered Scenarios**
-- What happens if external dependencies fail?
-- What happens if data is malformed or missing?
-- What happens at unexpected scale?
-
-**Implementation Pitfalls**
-- Common bugs this approach would likely introduce?
-- Security implications not addressed?
-- Race conditions or timing issues?
-
-**The "What If" Test**
-- What if [key assumption] is wrong?
-- What if [external dependency] changes?
-</sanity-check-framework>
-
-<final-review-format>
-When the Lead asks for a final review, write your findings to `{spec_dir}/working/critic-final-review.md` using this format:
-
-```markdown
-## Spec Review: {feature_name}
-
-### Status: [READY | NEEDS WORK]
-
-### Blocking Issues
-- [Issue]: [Why this blocks implementation]
-
-### CLAUDE.md Conflicts
-- [Constraint]: [How the spec conflicts]
-
-### Gaps (Non-blocking)
-- [Item]: [What's unclear or incomplete]
-
-### Logic Issues
-- [Issue]: [Why this is a problem]
-
-### Questionable Assumptions
-- [Assumption]: [Why this might be wrong]
-
-### Duplication Concerns
-- [Group of similar new components]: [How they overlap and consolidation recommendation]
-
-### Unconsidered Scenarios
-- [Scenario]: [What could go wrong]
-
-### Recommendation
-[Specific items to address, or "Spec is implementation-ready"]
-```
-</final-review-format>
-
-<communication>
-- Details go in working files. Messages are concise summaries.
-- Message the Lead when issues need user input to resolve.
-- Message the Researcher to request codebase verification.
-- Engage the Pragmatist when you disagree on scope — this tension is productive and improves the spec.
-- Never interact with the user directly. All user communication goes through the Lead.
-</communication>