cc-dev-template 0.1.80 → 0.1.82

package/src/skills/creating-agent-skills/references/create-step-4-review.md

@@ -45,7 +45,7 @@ Go through each file and verify:
 - Description uses third person with quoted trigger phrases?
 - All referenced files exist? (no broken links)
 - For procedural skills: dedicated reflection step file as the final step in the chain?
-- Chain link to reflection step uses mandatory language? ("IMPORTANT: You are not done. You MUST read and complete the next step.")
+- Chain link to reflection step uses redirect pattern? ("Use the Read tool on `references/...` to review your work and report results to the user.")
 - For informational skills: reflection section at the end of SKILL.md?
 - For forked-context skills: "Skill Observations" section in the output format?
 
@@ -64,4 +64,4 @@ Only proceed when validation passes and self-review is clean.
 
 If you found and fixed issues, re-run both the self-review and validation to confirm.
 
-Read `references/create-step-5-install.md` when review passes with no remaining issues.
+Use the Read tool on `references/create-step-5-install.md` to install and test the skill.

package/src/skills/creating-agent-skills/references/create-step-5-install.md

@@ -62,6 +62,4 @@ Summarize what was created:
 - Trigger phrases
 - File structure (list all files)
 
-**IMPORTANT: You are not done. You MUST read and complete the next step. The workflow is incomplete without it.**
-
-Read `references/create-step-6-reflect.md` now.
+Use the Read tool on `references/create-step-6-reflect.md` to review your work and report results to the user.

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

@@ -1,8 +1,6 @@
 # Step 6: Reflect and Improve
 
-**IMPORTANT: This step is mandatory. The skill creation workflow is not complete until this step is finished. Do not skip this.**
-
-Reflect on your experience creating this skill. The purpose is to improve the creating-agent-skills skill itself based on what you just learned.
+Reflect on your experience creating this skill and report results to the user. This step improves the creating-agent-skills skill itself based on what you just learned.
 
 ## Assess
 

package/src/skills/creating-agent-skills/references/fix-step-1-diagnose.md

@@ -74,10 +74,11 @@ Evaluate each file against these criteria:
 
 ### Self-Learning
 - For procedural skills: does the skill have a dedicated reflection step file as the final step in its chain?
-- Does the chain link to the reflection step use mandatory language? ("IMPORTANT: You are not done. You MUST read and complete the next step.")
+- Does the chain link to the reflection step use the redirect pattern? (e.g., "Use the Read tool on `references/step-N-reflect.md` to review your work and report results to the user.")
+- Do chain links use positive redirect framing, not negative warnings like "IMPORTANT: You are not done"?
 - For informational skills: is there a reflection section at the end of SKILL.md?
 - For forked-context skills (`context: fork`): does the output format include a "Skill Observations" section?
-- If missing or embedded as a section in another step file, flag it — every procedural skill needs a separate mandatory reflection step.
+- If missing or embedded as a section in another step file, flag it — every procedural skill needs a separate reflection step.
 
 ## Summarize Findings
 
@@ -114,5 +115,5 @@ Tell the user which type of fix is needed.
 
 | Fix Type | Action |
 |----------|--------|
-| Surface fixes only | Read `references/fix-step-2-apply.md` |
-| Structural changes needed | Read `references/create-step-2-design.md` first to design the new structure, then read `references/fix-step-2-apply.md` to apply |
+| Surface fixes only | Use the Read tool on `references/fix-step-2-apply.md` to apply the fixes |
+| Structural changes needed | Use the Read tool on `references/create-step-2-design.md` to design the new structure, then read `references/fix-step-2-apply.md` to apply |

package/src/skills/creating-agent-skills/references/fix-step-2-apply.md

@@ -94,7 +94,7 @@ Does this justify its token cost? If Claude already knows it — remove it. If i
 
 **Fix description:** Rewrite to third person, add quoted trigger phrases, focus on WHEN not HOW.
 
-**Add reflection step:** Create a dedicated reflection step file as the final step in the chain. Add a mandatory chain link from the previous final step using "**IMPORTANT: You are not done. You MUST read and complete the next step. The workflow is incomplete without it.**" See `references/create-step-3-write.md` "Reflection Step" section for the full writing guidance. For informational skills, append a reflection section to the end of SKILL.md instead. For forked-context skills, add a "Skill Observations" section to the output format instead.
+**Add reflection step:** Create a dedicated reflection step file as the final step in the chain. Add a redirect chain link from the previous final step: "Use the Read tool on `references/step-N-reflect.md` to review your work and report results to the user." See `references/create-step-3-write.md` "Chain Links Between Steps" section for the full pattern. For informational skills, append a reflection section to the end of SKILL.md instead. For forked-context skills, add a "Skill Observations" section to the output format instead.
 
 ## Apply the Changes
 
@@ -102,4 +102,4 @@ Make all planned modifications now.
 
 For structural changes that involve writing new files (new step files, new SKILL.md sections, new scripts), reference `references/create-step-3-write.md` for the complete writing guidance — it covers size targets, step file structure, MCP tool references, and anti-patterns in more depth than the principles above.
 
-Read `references/fix-step-3-validate.md` when all fixes are applied.
+Use the Read tool on `references/fix-step-3-validate.md` to validate and test the fixes.

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

@@ -53,6 +53,4 @@ Summarize what was fixed:
 - What was wrong and how it was resolved
 - Confirm with the user that the skill 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 review your work and report results to the user.

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

@@ -1,8 +1,6 @@
 # Step 4: Reflect and Improve
 
-**IMPORTANT: This step is mandatory. The skill fix workflow is not complete until this step is finished. Do not skip this.**
-
-Reflect on your experience fixing this skill. The purpose is to improve the creating-agent-skills skill itself based on what you just learned.
+Reflect on your experience fixing this skill and report results to the user. This step improves the creating-agent-skills skill itself based on what you just learned.
 
 ## Assess
 

package/src/skills/creating-agent-skills/templates/router-skill.md

@@ -11,6 +11,6 @@ Ask the user what they need.
 
 | Intent | Action |
 |--------|--------|
-| {{First option}} | Read `references/{{first-workflow}}.md` |
-| {{Second option}} | Read `references/{{second-workflow}}.md` |
-| {{Third option}} | Read `references/{{third-workflow}}.md` |
+| {{First option}} | Use the Read tool on `references/{{first-workflow}}.md` to {{what it accomplishes}} |
+| {{Second option}} | Use the Read tool on `references/{{second-workflow}}.md` to {{what it accomplishes}} |
+| {{Third option}} | Use the Read tool on `references/{{third-workflow}}.md` to {{what it accomplishes}} |

package/src/skills/creating-sub-agents/references/create-step-1-understand.md

@@ -43,4 +43,4 @@ Move on when all of these are true:
 - Tool requirements are known
 - The user confirms you understand their needs
 
-Read `references/create-step-2-design.md`.
+Use the Read tool on `references/create-step-2-design.md` to design the sub-agent's configuration.

package/src/skills/creating-sub-agents/references/create-step-2-design.md

@@ -178,4 +178,4 @@ Present the complete design:
 
 Ask: "Does this design look right?"
 
-Read `references/create-step-3-write.md` after confirmation.
+Use the Read tool on `references/create-step-3-write.md` to write the sub-agent's system prompt.

package/src/skills/creating-sub-agents/references/create-step-3-write.md

@@ -151,4 +151,4 @@ With these principles applied, write the complete `.md` file now:
 1. YAML frontmatter with all designed configuration
 2. System prompt body following the structure above
 
-Read `references/create-step-4-review.md` when the file is written.
+Use the Read tool on `references/create-step-4-review.md` to review the sub-agent before installation.

package/src/skills/creating-sub-agents/references/create-step-4-review.md

@@ -64,4 +64,4 @@ Handle results:
 
 Only proceed when validation passes and self-review is clean.
 
-Read `references/create-step-5-install.md` when review passes.
+Use the Read tool on `references/create-step-5-install.md` to install and test the sub-agent.

package/src/skills/creating-sub-agents/references/create-step-5-install.md

@@ -75,6 +75,4 @@ Summarize what was created:
 - Memory scope (if any)
 - Skills preloaded (if any)
 
-**IMPORTANT: You are not done. You MUST read and complete the next step. The workflow is incomplete without it.**
-
-Read `references/create-step-6-reflect.md` now.
+Use the Read tool on `references/create-step-6-reflect.md` to reflect on the creation process and note any skill issues.

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/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/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/ship/SKILL.md

@@ -0,0 +1,46 @@
+---
+name: ship
+description: End-to-end workflow for shipping complex features through intent discovery, contamination-free research, design discussion, spec generation, task breakdown, and implementation. Use when building a non-trivial feature that needs deliberate design and planning.
+argument-hint: <feature-name>
+allowed-tools: Read, Write, Edit, Grep, Glob, Bash, Agent, TaskCreate, TaskList, TaskUpdate, TaskGet, AskUserQuestion
+---
+
+# Ship
+
+You orchestrate a multi-phase workflow for shipping complex features. Each phase produces artifacts that feed the next, with clean context separation to prevent intent contamination.
+
+Every invocation of this skill is for a complex feature. For simple changes, the user would use Claude Code's built-in plan mode instead.
+
+## Determine Feature
+
+If an argument was provided, use it as the feature name (convert to hyphen-case). If no argument, ask the user what feature they want to build and derive a short hyphen-case name from their description.
+
+The spec directory is `docs/specs/{feature-name}/`.
+
+## Check State
+
+Look for `docs/specs/{feature-name}/state.yaml`.
+
+**If state.yaml exists**, read it. The `phase` field tells you where to resume:
+
+| Phase | Step file |
+|---|---|
+| intent | `references/step-1-intent.md` |
+| questions | `references/step-2-questions.md` |
+| research | `references/step-3-research.md` |
+| design | `references/step-4-design.md` |
+| spec | `references/step-5-spec.md` |
+| tasks | `references/step-6-tasks.md` |
+| implement | `references/step-7-implement.md` |
+
+Read the step file for the current phase and follow its instructions.
+
+**If state.yaml does not exist**, this is a new feature. Create the spec directory and an initial state.yaml:
+
+```yaml
+feature: {feature-name}
+phase: intent
+dir: docs/specs/{feature-name}
+```
+
+Then read `references/step-1-intent.md` to begin.

package/src/skills/ship/references/step-1-intent.md

@@ -0,0 +1,50 @@
+# Intent Discovery
+
+Capture what the user wants to build through conversation. This produces the intent document — a clear statement of the feature, not a spec, not a plan.
+
+## Create Tasks
+
+Create these tasks and work through them in order:
+
+1. "Discuss the feature with the user" — understand what, why, and constraints
+2. "Write intent.md" — capture the understanding
+3. "Begin question generation" — proceed to the next phase
+
+## Task 1: Discuss
+
+Have a conversation with the user about:
+
+- **What** they want to build — the feature or change
+- **Why** it matters — the problem it solves, who it's for
+- **Constraints** — any technical limitations, patterns to follow, things to avoid
+- **Success** — how they'll know it works (high-level, not formal acceptance criteria yet)
+
+Keep this natural. A few rounds of back-and-forth is enough. You're building understanding, not conducting an interrogation.
+
+## Task 2: Write intent.md
+
+When you have enough understanding, write `{spec_dir}/intent.md`:
+
+```markdown
+# Feature: {Feature Name}
+
+## What
+{Clear description of what's being built}
+
+## Why
+{The problem this solves and who benefits}
+
+## Constraints
+{Any stated technical limitations, patterns, or preferences}
+
+## Success Criteria
+{High-level criteria for knowing it's done}
+```
+
+Present the intent document to the user for confirmation. Adjust if they have corrections.
+
+## Task 3: Proceed
+
+Update `{spec_dir}/state.yaml` — set `phase: questions`.
+
+Use the Read tool on `references/step-2-questions.md` to generate research questions from the intent.

package/src/skills/ship/references/step-2-questions.md

@@ -0,0 +1,42 @@
+# Question Generation
+
+Generate research questions that a senior engineer would need answered about the codebase before implementing this feature. A restricted sub-agent handles this — it reads the intent and produces questions but cannot explore the codebase.
+
+The intent document captures what the user wants. The questions document will be used by a DIFFERENT agent to research the codebase — an agent that will NOT see the intent. This separation prevents implementation opinions from contaminating the research.
+
+## Create Tasks
+
+Create these tasks and work through them in order:
+
+1. "Generate research questions from intent" — spawn the question-generator
+2. "Review questions with user" — present and refine
+3. "Begin objective research" — proceed to the next phase
+
+## Task 1: Generate Questions
+
+Spawn a sub-agent to generate questions:
+
+```
+Agent tool:
+  subagent_type: "question-generator"
+  prompt: "Read the intent document at {spec_dir}/intent.md. Write research questions to {spec_dir}/questions.md."
+  model: "sonnet"
+```
+
+The question-generator is restricted — it can only read and write within docs/specs/. It has no search tools. It cannot explore the codebase even if it wanted to.
+
+## Task 2: Review Questions
+
+Read `{spec_dir}/questions.md` and present the questions to the user. Ask:
+
+- Are these the right questions?
+- Any questions missing?
+- Any questions that aren't relevant?
+
+Update `questions.md` based on user feedback. The user may add questions about patterns, existing implementations, or concerns they have.
+
+## Task 3: Proceed
+
+Update `{spec_dir}/state.yaml` — set `phase: research`.
+
+Use the Read tool on `references/step-3-research.md` to begin objective codebase research.

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

@@ -0,0 +1,44 @@
+# Objective Research
+
+A sub-agent researches the codebase using ONLY the questions — it does not see the intent document. This produces factual, objective documentation about the codebase without implementation bias.
+
+This is the critical contamination prevention step. The research agent answers questions about what EXISTS in the codebase. It does not know what feature is being built, so it cannot steer findings toward a particular implementation.
+
+## Create Tasks
+
+Create these tasks and work through them in order:
+
+1. "Research codebase using questions" — spawn the objective-researcher
+2. "Review research with user" — present findings
+3. "Begin design discussion" — proceed to the next phase
+
+## Task 1: Research Codebase
+
+Spawn a sub-agent to research the codebase:
+
+```
+Agent tool:
+  subagent_type: "objective-researcher"
+  prompt: "Read the questions at {spec_dir}/questions.md. Research the codebase to answer each question. Write your findings to {spec_dir}/research.md. Do NOT read any other files in {spec_dir} — only questions.md."
+  model: "sonnet"
+```
+
+The objective-researcher has full codebase access (Read, Grep, Glob, Bash) but no knowledge of the feature being built. It only sees the questions.
+
+## Task 2: Review Research
+
+Read `{spec_dir}/research.md` and present a summary to the user. Highlight:
+
+- Any questions the researcher couldn't answer (gaps)
+- Places where multiple patterns were found (need disambiguation)
+- Anything surprising or noteworthy
+
+The user may add context the researcher missed, or flag patterns that are outdated.
+
+If the research is thin or missing critical areas, spawn the objective-researcher again with additional targeted questions.
+
+## Task 3: Proceed
+
+Update `{spec_dir}/state.yaml` — set `phase: design`.
+
+Use the Read tool on `references/step-4-design.md` to begin the design discussion with the user.

package/src/skills/ship/references/step-4-design.md

@@ -0,0 +1,70 @@
+# Design Discussion
+
+This is the highest-leverage phase. You now have the objective research AND the original intent. Combine them to make design decisions with the user.
+
+Read `{spec_dir}/intent.md` and `{spec_dir}/research.md` before proceeding.
+
+## Create Tasks
+
+Create these tasks and work through them in order:
+
+1. "Surface patterns and present design questions" — analyze research, identify decisions needed
+2. "Resolve design decisions with user" — interactive discussion
+3. "Write design.md" — capture resolved decisions
+4. "Begin spec generation" — proceed to the next phase
+
+## Task 1: Surface Patterns
+
+From the research document, identify:
+
+**Patterns to Follow**: Code patterns from the codebase relevant to this feature. If the research found multiple patterns for the same thing (e.g., old way vs. new way of handling forms), list them all and flag for disambiguation.
+
+**Design Questions**: Decisions that need human input before implementation. For each question:
+
+- State the question clearly
+- Provide Option A and Option B (grounded in what the research found)
+- Note which option you'd recommend and why
+- Leave room for the user to propose Option C
+
+Common design questions include:
+
+- Which existing pattern to follow when there are multiple
+- Where new code should live (which directory, which module)
+- How to handle edge cases and error states
+- What to do about backward compatibility
+- Testing strategy (unit, integration, E2E)
+
+## Task 2: Resolve Decisions
+
+Present the patterns and design questions to the user. Work through each decision:
+
+- Let the user choose options or propose alternatives
+- If the user isn't sure, provide your reasoning
+- If a decision requires understanding external technology the codebase doesn't use yet, note it as an open item — the spec phase can handle external research
+
+This is interactive. Go back and forth until all design questions are resolved.
+
+## Task 3: Write design.md
+
+Write `{spec_dir}/design.md`:
+
+```markdown
+# Design Decisions: {Feature Name}
+
+## Patterns to Follow
+{List each pattern with code location and why it's relevant}
+
+## Resolved Decisions
+{For each design question: the question, the chosen option, and the rationale}
+
+## Open Items
+{Anything requiring external research or further investigation}
+```
+
+Present to the user for confirmation.
+
+## Task 4: Proceed
+
+Update `{spec_dir}/state.yaml` — set `phase: spec`.
+
+Use the Read tool on `references/step-5-spec.md` to generate the implementation specification.