cc-dev-template 0.1.80 → 0.1.81

package/src/skills/creating-sub-agents/references/create-step-6-reflect.md

@@ -1,9 +1,5 @@
 # Step 6: Reflect and Improve
 
-**IMPORTANT: This step is mandatory. The sub-agent creation workflow is not complete until this step is finished. Do not skip this.**
-
-Reflect on your experience creating this sub-agent. The purpose is to improve the creating-sub-agents skill itself based on what you just learned.
-
 ## Assess
 
 Answer these questions honestly:

package/src/skills/creating-sub-agents/references/fix-step-3-validate.md

@@ -51,6 +51,4 @@ Summarize what was fixed:
 - What was wrong and how it was resolved
 - Confirm with the user that the sub-agent now behaves as expected
 
-**IMPORTANT: You are not done. You MUST read and complete the next step. The workflow is incomplete without it.**
-
-Read `references/fix-step-4-reflect.md` now.
+Use the Read tool on `references/fix-step-4-reflect.md` to reflect on the fix process and note any skill issues.

package/src/skills/creating-sub-agents/references/fix-step-4-reflect.md

@@ -1,9 +1,5 @@
 # Step 4: Reflect and Improve
 
-**IMPORTANT: This step is mandatory. The sub-agent fix workflow is not complete until this step is finished. Do not skip this.**
-
-Reflect on your experience fixing this sub-agent. The purpose is to improve the creating-sub-agents skill itself based on what you just learned.
-
 ## Assess
 
 Answer these questions honestly:

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

@@ -1,4 +1,6 @@
 ---
+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:
@@ -12,8 +14,6 @@ hooks:
 
 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.
@@ -23,26 +23,18 @@ Invoke when you have a complete spec with a `tasks/` folder containing task file
 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
+- **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

@@ -68,4 +68,7 @@ Maintain a mapping of task IDs (T001, T002) to Claude task system IDs.
 
 - All tasks in Claude Code task system
 - Dependencies configured
-- Ready for Phase 2
+
+## 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

@@ -25,8 +25,7 @@ Loop until all tasks complete:
      )
 
 4. Wait for completions:
-   - Agents mark tasks complete when done
-   - Poll TaskList periodically to check status
+   - 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
@@ -60,4 +59,7 @@ Build Progress:
 
 - All tasks implemented (or failed with notes)
 - Implementation Notes written to each task file
-- Ready for Phase 3: Validate
+
+## 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

@@ -29,9 +29,7 @@ Dispatch spec-validator agents for each completed task.
 
 4. Wait for all validators to complete
 
-5. Collect results:
-   - Read Review Notes from each task file
-   - Aggregate issues by severity
+5. Collect results from validator returns (pass/fail status only)
 ```
 
 ## Validator Behavior
@@ -69,4 +67,7 @@ Validation Results:
 
 - Validation complete for all tasks
 - Issues collected and categorized
-- Ready for Phase 4: Triage
+
+## 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

@@ -73,3 +73,7 @@ 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,8 +1,6 @@
 # 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.
+Reflect on your experience orchestrating this spec execution.
 
 ## Assess
 

package/src/skills/initialize-project/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: initialize-project
-description: Scaffold docs structure for Claude Code sessions. Use when starting a new project, when "docs/CURRENT_WORK.md is missing", or when user says "initialize this project" or "set up session tracking".
+description: Scaffold docs structure for Claude Code sessions. Use when starting a new project, when the project lacks docs/CURRENT_WORK.md, or when the user wants session tracking initialized.
 ---
 
 # Initialize Project
@@ -32,6 +32,4 @@ Report what was created:
 
 End with: "Run `/prime` to start a session."
 
-**IMPORTANT: You are not done. You MUST read and complete the next step. The workflow is incomplete without it.**
-
-Read references/reflect.md now.
+Use the Read tool on `references/reflect.md` to reflect on the setup and note any skill issues.

package/src/skills/initialize-project/references/reflect.md

@@ -1,9 +1,5 @@
 # Reflect and Improve
 
-**IMPORTANT: This step is mandatory. The initialize-project workflow is not complete until this step is finished. Do not skip this.**
-
-Reflect on your experience using this skill. The purpose is to improve the initialize-project skill itself based on what you just learned.
-
 ## Assess
 
 Answer these questions honestly:

package/src/skills/project-setup/references/step-5-verify.md

@@ -69,6 +69,4 @@ Tell the user:
 
 If everything passed, the setup is complete.
 
-**IMPORTANT: You are not done. You MUST read and complete the next step. The workflow is incomplete without it.**
-
-Read `references/step-6-reflect.md` now.
+Use the Read tool on `references/step-6-reflect.md` to reflect on the setup experience and note any skill issues.

package/src/skills/project-setup/references/step-6-reflect.md

@@ -1,9 +1,5 @@
 # Step 6: Reflect and Improve
 
-**IMPORTANT: This step is mandatory. The project setup workflow is not complete until this step is finished. Do not skip this.**
-
-Reflect on your experience setting up this project. The purpose is to improve the project-setup skill itself based on what you just learned.
-
 ## Assess
 
 Answer these questions honestly:

package/src/skills/prompting/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: prompting
-description: Invoked when user says "review my prompt", "help me write a prompt", "improve this prompt", or "create a prompt for...". Guides prompt creation and improvement using Claude 4.x best practices.
+description: Guide prompt creation and improvement using Claude 4.x best practices. Use for reviewing existing prompts, creating new prompts, or improving prompt effectiveness.
 ---
 
 # Prompting

package/src/skills/prompting/references/create-reflect.md

@@ -1,9 +1,5 @@
 # Reflect on Prompt Creation
 
-**IMPORTANT: This step is mandatory. The prompt creation workflow is not complete until this step is finished. Do not skip this.**
-
-Reflect on your experience using this skill to create the prompt. The purpose is to improve the prompting skill itself based on what you just learned.
-
 ## Assess
 
 Answer these questions honestly:

package/src/skills/prompting/references/create.md

@@ -58,6 +58,4 @@ Ask: "Does this capture what you need? Any adjustments?"
 
 Incorporate feedback until the user is satisfied.
 
-**IMPORTANT: You are not done. You MUST read and complete the next step. The workflow is incomplete without it.**
-
-Read `references/create-reflect.md` now.
+Use the Read tool on `references/create-reflect.md` to reflect on the prompt creation and note any skill issues.

package/src/skills/prompting/references/review-reflect.md

@@ -1,9 +1,5 @@
 # Reflect on Prompt Review
 
-**IMPORTANT: This step is mandatory. The prompt review workflow is not complete until this step is finished. Do not skip this.**
-
-Reflect on your experience using this skill to review the prompt. The purpose is to improve the prompting skill itself based on what you just learned.
-
 ## Assess
 
 Answer these questions honestly:

package/src/skills/prompting/references/review.md

@@ -77,6 +77,4 @@ Ask: "Would you like me to adjust anything in the improved version?"
 
 Incorporate feedback and present updated version until the user is satisfied.
 
-**IMPORTANT: You are not done. You MUST read and complete the next step. The workflow is incomplete without it.**
-
-Read `references/review-reflect.md` now.
+Use the Read tool on `references/review-reflect.md` to reflect on the prompt review and note any skill issues.

package/src/skills/research/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: research
-description: Deep research on unfamiliar paradigms, libraries, or patterns before implementation. Activates when the user says "research X", "how should we implement X", "best practices for X", or when spec-interview identifies research needs. Outputs to docs/research/ with YAML frontmatter.
+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

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

@@ -62,6 +62,4 @@ After writing the document:
 2. Summarize the key takeaways
 3. Return to the invoking context (spec-interview or user)
 
-**IMPORTANT: You are not done. You MUST read and complete the next step. The workflow is incomplete without it.**
-
-Read `references/step-3-reflect.md` now.
+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,9 +1,5 @@
 # Step 3: Reflect and Improve
 
-**IMPORTANT: This step is mandatory. The research workflow is not complete until this step is finished. Do not skip this.**
-
-Reflect on your experience using this skill. The purpose is to improve the research skill itself based on what you just learned.
-
 ## Assess
 
 Answer these questions honestly:

package/src/skills/setup-lsp/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: setup-lsp
-description: Set up LSP language servers for the current project. Use when the user says "setup LSP", "configure LSP", "enable LSP", "install language servers", or "add code intelligence". Use "verify" argument after restart to confirm LSP is working.
+description: Set up LSP language servers for the current project. Use when the project needs code intelligence configured, or to verify an existing LSP setup. Pass "verify" argument after restart to confirm LSP is working.
 disable-model-invocation: true
 argument-hint: "[verify]"
 ---

package/src/skills/setup-lsp/references/step-1-scan.md

@@ -25,4 +25,4 @@ Show the user:
 
 Ask the user to confirm which LSPs to install. They may want to skip some languages.
 
-Read `references/step-2-install-configure.md`.
+Use the Read tool on `references/step-2-install-configure.md` to install language server binaries and configure Claude Code plugins.

package/src/skills/setup-lsp/references/step-2-install-configure.md

@@ -80,6 +80,4 @@ Tell the user:
 2. Restart Claude Code in this project directory
 3. Run `/setup-lsp verify` to confirm LSP is working
 
-**IMPORTANT: You are not done. You MUST read and complete the next step. The workflow is incomplete without it.**
-
-Read `references/step-4-reflect.md` now.
+Use the Read tool on `references/step-4-reflect.md` to reflect on the setup and capture any workarounds for future runs.

package/src/skills/setup-lsp/references/step-3-verify.md

@@ -38,6 +38,4 @@ Tell the user:
 - Which operations were tested and their results
 - Any operations that didn't work (with explanation)
 
-**IMPORTANT: You are not done. You MUST read and complete the next step. The workflow is incomplete without it.**
-
-Read `references/step-4-reflect.md` now.
+Use the Read tool on `references/step-4-reflect.md` to reflect on the setup and capture any workarounds for future runs.

package/src/skills/setup-lsp/references/step-4-reflect.md

@@ -1,7 +1,5 @@
 # Step 4: Reflect
 
-**IMPORTANT: This step is mandatory. The setup-lsp workflow is not complete until this step is finished. Do not skip this.**
-
 ## Assess
 
 - Were any install commands wrong, outdated, or platform-specific in a way the registry didn't account for?

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.**