cc-dev-template 0.1.80 → 0.1.82

package/bin/install.js

@@ -280,7 +280,16 @@ console.log('\nCleanup:');
 let cleanupPerformed = false;
 
 // Remove deprecated skills
-const deprecatedSkills = ['youtube-to-notes'];
+const deprecatedSkills = [
+  'youtube-to-notes',
+  'spec-interview',
+  'spec-to-tasks',
+  'execute-spec',
+  'research',
+  'spec-review',
+  'spec-sanity-check',
+  'task-review',
+];
 deprecatedSkills.forEach(skill => {
   const skillPath = path.join(CLAUDE_DIR, 'skills', skill);
   if (fs.existsSync(skillPath)) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "cc-dev-template",
-  "version": "0.1.80",
+  "version": "0.1.82",
   "description": "Structured AI-assisted development framework for Claude Code",
   "bin": {
     "cc-dev-template": "./bin/install.js"

package/src/agents/objective-researcher.md

@@ -0,0 +1,52 @@
+---
+name: objective-researcher
+description: Answers codebase questions objectively without knowing the feature being built. Produces factual research documentation.
+tools: Read, Grep, Glob, Bash, Write
+permissionMode: bypassPermissions
+maxTurns: 30
+model: sonnet
+---
+
+You are an objective codebase researcher. You receive questions about a codebase and answer them by exploring the code.
+
+## Critical Rule
+
+You do NOT know what feature is being built. You only have questions. Answer them factually.
+
+- Report what EXISTS, not what SHOULD exist
+- Do not suggest implementations or improvements
+- Do not speculate about what someone might want to build
+- If you find multiple patterns for the same thing, report ALL of them with locations
+- If a question cannot be answered from the codebase, say so explicitly
+
+## Process
+
+1. Read the questions file at the path provided in your prompt
+2. For each question, explore the codebase using Grep, Glob, and Read
+3. Write findings to the output path provided
+
+## Output Format
+
+For each question in the questions file:
+
+```markdown
+## Q: {Original question}
+
+**Finding**: {Your answer with specific details}
+
+**Evidence**:
+- `path/to/file.ts:42` — {what this file shows}
+- `path/to/other.ts:108` — {what this code does}
+
+**Confidence**: high | medium | low
+
+**Notes**: {Any ambiguities, multiple patterns found, or related observations}
+```
+
+After answering all questions, add a final section:
+
+```markdown
+## Additional Observations
+
+{Anything noteworthy you discovered while researching that wasn't directly asked about but seems relevant to understanding this area of the codebase}
+```

package/src/agents/question-generator.md

@@ -0,0 +1,70 @@
+---
+name: question-generator
+description: Generates research questions from a feature intent document. Cannot explore the codebase — produces questions only.
+tools: Read, Write
+permissionMode: bypassPermissions
+maxTurns: 5
+model: sonnet
+hooks:
+  PreToolUse:
+    - matcher: "Read"
+      hooks:
+        - type: command
+          command: "$HOME/.claude/scripts/restrict-to-spec-dir.sh"
+    - matcher: "Write"
+      hooks:
+        - type: command
+          command: "$HOME/.claude/scripts/restrict-to-spec-dir.sh"
+---
+
+You are a question generator. You read a feature intent document and produce research questions that a senior engineer would need answered about the codebase before implementing this feature.
+
+## Your Role
+
+You generate questions. You do NOT:
+
+- Research or explore the codebase (you have no search tools)
+- Suggest implementations or architectural decisions
+- Write code or pseudocode
+- Speculate about how the codebase might work
+
+## Process
+
+1. Read the intent document at the path provided in your prompt
+2. Think about what a senior engineer would need to know about the codebase before they could implement this
+3. Write organized, specific questions to the output path provided
+
+## Output Format
+
+Write a markdown file with questions organized by category:
+
+```markdown
+# Research Questions
+
+## Existing Patterns
+- How does the codebase currently handle {relevant functionality}?
+- What patterns are used for {similar features}?
+- Are there existing utilities or helpers for {relevant operations}?
+
+## Data Model
+- What data structures exist for {relevant entities}?
+- How is {relevant data} currently stored and accessed?
+
+## Integration Points
+- What services or modules would this feature interact with?
+- Are there existing APIs or interfaces it should conform to?
+
+## Testing Infrastructure
+- What testing patterns does the project use for {relevant scenarios}?
+- What test runners and frameworks are configured?
+
+## Dependencies
+- Are there existing libraries in the project for {relevant functionality}?
+- What versions of key frameworks are in use?
+```
+
+Each question must be:
+
+- **Specific**: "How does the auth module handle session tokens?" not "How does auth work?"
+- **Codebase-answerable**: Answerable by reading project files, not by asking the user
+- **Relevant**: Directly related to implementing the feature described in the intent

package/src/scripts/restrict-to-spec-dir.sh

@@ -0,0 +1,23 @@
+#!/bin/bash
+# Restricts Read/Write operations to the docs/specs/ directory.
+# Used by question-generator sub-agent to prevent codebase exploration.
+# Receives JSON on stdin with tool_name and tool_input.
+
+input=$(cat)
+file_path=$(echo "$input" | jq -r '.tool_input.file_path // empty')
+
+# If no file_path in the tool input, allow the operation
+if [ -z "$file_path" ]; then
+  exit 0
+fi
+
+# Allow access to docs/specs/ directory
+if [[ "$file_path" == *"/docs/specs/"* ]]; then
+  exit 0
+fi
+
+# Deny everything else
+cat << 'EOF'
+{"permissionDecision":"deny","message":"Access restricted to docs/specs/ directory only."}
+EOF
+exit 0

package/src/skills/agent-browser/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: agent-browser
-description: Browser automation CLI for AI agents. Use when the user needs to interact with websites, including navigating pages, filling forms, clicking buttons, taking screenshots, extracting data, testing web apps, or automating any browser task. Triggers include requests to "open a website", "fill out a form", "click a button", "take a screenshot", "scrape data from a page", "test this web app", "login to a site", "automate browser actions", or any task requiring programmatic web interaction.
+description: Browser automation CLI for AI agents. Use when interacting with websites — navigating pages, filling forms, clicking buttons, taking screenshots, extracting data, or testing web apps.
 ---
 
 # Browser Automation with agent-browser
@@ -63,97 +63,6 @@ agent-browser screenshot --full       # Full page screenshot
 agent-browser pdf output.pdf          # Save as PDF
 ```
 
-## Common Patterns
-
-### Form Submission
-
-```bash
-agent-browser open https://example.com/signup
-agent-browser snapshot -i
-agent-browser fill @e1 "Jane Doe"
-agent-browser fill @e2 "jane@example.com"
-agent-browser select @e3 "California"
-agent-browser check @e4
-agent-browser click @e5
-agent-browser wait --load networkidle
-```
-
-### Authentication with State Persistence
-
-```bash
-# Login once and save state
-agent-browser open https://app.example.com/login
-agent-browser snapshot -i
-agent-browser fill @e1 "$USERNAME"
-agent-browser fill @e2 "$PASSWORD"
-agent-browser click @e3
-agent-browser wait --url "**/dashboard"
-agent-browser state save auth.json
-
-# Reuse in future sessions
-agent-browser state load auth.json
-agent-browser open https://app.example.com/dashboard
-```
-
-### Data Extraction
-
-```bash
-agent-browser open https://example.com/products
-agent-browser snapshot -i
-agent-browser get text @e5           # Get specific element text
-agent-browser get text body > page.txt  # Get all page text
-
-# JSON output for parsing
-agent-browser snapshot -i --json
-agent-browser get text @e1 --json
-```
-
-### Parallel Sessions
-
-```bash
-agent-browser --session site1 open https://site-a.com
-agent-browser --session site2 open https://site-b.com
-
-agent-browser --session site1 snapshot -i
-agent-browser --session site2 snapshot -i
-
-agent-browser session list
-```
-
-### Visual Browser (Debugging)
-
-```bash
-agent-browser --headed open https://example.com
-agent-browser highlight @e1          # Highlight element
-agent-browser record start demo.webm # Record session
-```
-
-### iOS Simulator (Mobile Safari)
-
-```bash
-# List available iOS simulators
-agent-browser device list
-
-# Launch Safari on a specific device
-agent-browser -p ios --device "iPhone 16 Pro" open https://example.com
-
-# Same workflow as desktop - snapshot, interact, re-snapshot
-agent-browser -p ios snapshot -i
-agent-browser -p ios tap @e1          # Tap (alias for click)
-agent-browser -p ios fill @e2 "text"
-agent-browser -p ios swipe up         # Mobile-specific gesture
-
-# Take screenshot
-agent-browser -p ios screenshot mobile.png
-
-# Close session (shuts down simulator)
-agent-browser -p ios close
-```
-
-**Requirements:** macOS with Xcode, Appium (`npm install -g appium && appium driver install xcuitest`)
-
-**Real devices:** Works with physical iOS devices if pre-configured. Use `--device "<UDID>"` where UDID is from `xcrun xctrace list devices`.
-
 ## Ref Lifecycle (Important)
 
 Refs (`@e1`, `@e2`, etc.) are invalidated when the page changes. Always re-snapshot after:
@@ -168,49 +77,14 @@ agent-browser snapshot -i            # MUST re-snapshot
 agent-browser click @e1              # Use new refs
 ```
 
-## Semantic Locators (Alternative to Refs)
-
-When refs are unavailable or unreliable, use semantic locators:
-
-```bash
-agent-browser find text "Sign In" click
-agent-browser find label "Email" fill "user@test.com"
-agent-browser find role button click --name "Submit"
-agent-browser find placeholder "Search" type "query"
-agent-browser find testid "submit-btn" click
-```
-
-## Deep-Dive Documentation
-
-| Reference | When to Use |
-|-----------|-------------|
-| [references/commands.md](references/commands.md) | Full command reference with all options |
-| [references/snapshot-refs.md](references/snapshot-refs.md) | Ref lifecycle, invalidation rules, troubleshooting |
-| [references/session-management.md](references/session-management.md) | Parallel sessions, state persistence, concurrent scraping |
-| [references/authentication.md](references/authentication.md) | Login flows, OAuth, 2FA handling, state reuse |
-| [references/video-recording.md](references/video-recording.md) | Recording workflows for debugging and documentation |
-| [references/proxy-support.md](references/proxy-support.md) | Proxy configuration, geo-testing, rotating proxies |
-
-## Ready-to-Use Templates
-
-| Template | Description |
-|----------|-------------|
-| [templates/form-automation.sh](templates/form-automation.sh) | Form filling with validation |
-| [templates/authenticated-session.sh](templates/authenticated-session.sh) | Login once, reuse state |
-| [templates/capture-workflow.sh](templates/capture-workflow.sh) | Content extraction with screenshots |
-
-```bash
-./templates/form-automation.sh https://example.com/form
-./templates/authenticated-session.sh https://app.example.com/login
-./templates/capture-workflow.sh https://example.com ./output
-```
+## Reference Files
 
-## Reflect After Use
+For common patterns (forms, auth, data extraction, parallel sessions, debugging), read `references/common-patterns.md`.
 
-After completing the browser automation task, reflect on your experience.
+For semantic locators as an alternative to refs, read `references/semantic-locators.md`.
 
-Were any commands, flags, patterns, or workarounds in this reference incorrect or missing? Did you discover a command syntax, a workaround for a specific site, or a pattern that should be documented here?
+For iOS Simulator and mobile Safari automation, read `references/ios-simulator.md`.
 
-If yes, update the relevant section of this skill file. Only add tribal knowledge — commands and patterns a fresh Claude instance would not know about agent-browser specifically. Keep within size targets.
+## Reflect
 
-Tell the user what you updated, or confirm no updates were needed.
+Use the Read tool on `references/reflect.md` to reflect on the browser automation and note any skill issues.

package/src/skills/agent-browser/references/common-patterns.md

@@ -0,0 +1,64 @@
+# Common Patterns
+
+## Form Submission
+
+```bash
+agent-browser open https://example.com/signup
+agent-browser snapshot -i
+agent-browser fill @e1 "Jane Doe"
+agent-browser fill @e2 "jane@example.com"
+agent-browser select @e3 "California"
+agent-browser check @e4
+agent-browser click @e5
+agent-browser wait --load networkidle
+```
+
+## Authentication with State Persistence
+
+```bash
+# Login once and save state
+agent-browser open https://app.example.com/login
+agent-browser snapshot -i
+agent-browser fill @e1 "$USERNAME"
+agent-browser fill @e2 "$PASSWORD"
+agent-browser click @e3
+agent-browser wait --url "**/dashboard"
+agent-browser state save auth.json
+
+# Reuse in future sessions
+agent-browser state load auth.json
+agent-browser open https://app.example.com/dashboard
+```
+
+## Data Extraction
+
+```bash
+agent-browser open https://example.com/products
+agent-browser snapshot -i
+agent-browser get text @e5           # Get specific element text
+agent-browser get text body > page.txt  # Get all page text
+
+# JSON output for parsing
+agent-browser snapshot -i --json
+agent-browser get text @e1 --json
+```
+
+## Parallel Sessions
+
+```bash
+agent-browser --session site1 open https://site-a.com
+agent-browser --session site2 open https://site-b.com
+
+agent-browser --session site1 snapshot -i
+agent-browser --session site2 snapshot -i
+
+agent-browser session list
+```
+
+## Visual Browser (Debugging)
+
+```bash
+agent-browser --headed open https://example.com
+agent-browser highlight @e1          # Highlight element
+agent-browser record start demo.webm # Record session
+```

package/src/skills/agent-browser/references/ios-simulator.md

@@ -0,0 +1,25 @@
+# iOS Simulator (Mobile Safari)
+
+```bash
+# List available iOS simulators
+agent-browser device list
+
+# Launch Safari on a specific device
+agent-browser -p ios --device "iPhone 16 Pro" open https://example.com
+
+# Same workflow as desktop - snapshot, interact, re-snapshot
+agent-browser -p ios snapshot -i
+agent-browser -p ios tap @e1          # Tap (alias for click)
+agent-browser -p ios fill @e2 "text"
+agent-browser -p ios swipe up         # Mobile-specific gesture
+
+# Take screenshot
+agent-browser -p ios screenshot mobile.png
+
+# Close session (shuts down simulator)
+agent-browser -p ios close
+```
+
+**Requirements:** macOS with Xcode, Appium (`npm install -g appium && appium driver install xcuitest`)
+
+**Real devices:** Works with physical iOS devices if pre-configured. Use `--device "<UDID>"` where UDID is from `xcrun xctrace list devices`.

package/src/skills/agent-browser/references/reflect.md

@@ -0,0 +1,9 @@
+# Reflect After Use
+
+After completing the browser automation task, reflect on your experience.
+
+Were any commands, flags, patterns, or workarounds in this reference incorrect or missing? Did you discover a command syntax, a workaround for a specific site, or a pattern that should be documented here?
+
+If yes, update the relevant section of this skill file. Only add tribal knowledge -- commands and patterns a fresh Claude instance would not know about agent-browser specifically. Keep within size targets.
+
+Tell the user what you updated, or confirm no updates were needed.

package/src/skills/agent-browser/references/semantic-locators.md

@@ -0,0 +1,11 @@
+# Semantic Locators (Alternative to Refs)
+
+When refs are unavailable or unreliable, use semantic locators:
+
+```bash
+agent-browser find text "Sign In" click
+agent-browser find label "Email" fill "user@test.com"
+agent-browser find role button click --name "Submit"
+agent-browser find placeholder "Search" type "query"
+agent-browser find testid "submit-btn" click
+```

package/src/skills/claude-md/SKILL.md

@@ -1,12 +1,10 @@
 ---
 name: claude-md
-description: Manages CLAUDE.md files in a project. Activates when the user says "audit CLAUDE.md files", "update CLAUDE.md", "add to CLAUDE.md", or invokes /claude-md. With no arguments, audits all CLAUDE.md files. With arguments, intelligently updates the appropriate file.
+description: Manage CLAUDE.md files in a project. With no arguments, audits all CLAUDE.md files for accuracy and completeness. With arguments, intelligently updates the appropriate file.
 ---
 
 # CLAUDE.md Management
 
-Base directory for this skill: ~/.claude/skills/claude-md
-
 ## What To Do
 
 Check if arguments were provided:

package/src/skills/claude-md/references/audit-reflect.md

@@ -1,9 +1,5 @@
 # Audit Reflection
 
-**IMPORTANT: This step is mandatory. The audit workflow is not complete until this step is finished. Do not skip this.**
-
-Reflect on your experience auditing the project's CLAUDE.md files. The purpose is to improve the claude-md skill itself based on what you just learned.
-
 ## Assess
 
 Answer these questions honestly:

package/src/skills/claude-md/references/audit.md

@@ -62,6 +62,4 @@ Remaining concerns:
 - [any issues needing human decision]
 ```
 
-**IMPORTANT: You are not done. You MUST read and complete the next step. The workflow is incomplete without it.**
-
-Read references/audit-reflect.md now.
+Use the Read tool on `references/audit-reflect.md` to reflect on the audit and note any skill issues.

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

@@ -1,9 +1,5 @@
 # Create Reflection
 
-**IMPORTANT: This step is mandatory. The create workflow is not complete until this step is finished. Do not skip this.**
-
-Reflect on your experience creating a new CLAUDE.md file. The purpose is to improve the claude-md skill itself based on what you just learned.
-
 ## Assess
 
 Answer these questions honestly:

package/src/skills/claude-md/references/create.md

@@ -71,6 +71,4 @@ Verify:
 
 If all yes, proceed to the reflection step.
 
-**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 creation process and note any skill issues.

package/src/skills/claude-md/references/modify-reflect.md

@@ -1,9 +1,5 @@
 # Modify Reflection
 
-**IMPORTANT: This step is mandatory. The modify workflow is not complete until this step is finished. Do not skip this.**
-
-Reflect on your experience modifying the project's CLAUDE.md files. The purpose is to improve the claude-md skill itself based on what you just learned.
-
 ## Assess
 
 Answer these questions honestly:

package/src/skills/claude-md/references/modify.md

@@ -51,6 +51,4 @@ If the content would make the file exceed ~100 lines, consider:
 
 Tell the user what was added and where. If creating a new CLAUDE.md file, explain why that location was chosen.
 
-**IMPORTANT: You are not done. You MUST read and complete the next step. The workflow is incomplete without it.**
-
-Read references/modify-reflect.md now.
+Use the Read tool on `references/modify-reflect.md` to reflect on the modification and note any skill issues.

package/src/skills/creating-agent-skills/SKILL.md

@@ -11,8 +11,8 @@ Ask the user what they need.
 
 | Intent | Action |
 |--------|--------|
-| Create a new skill | Read `references/create-step-1-understand.md` |
-| Fix, improve, audit, or modify an existing skill | Read `references/fix-step-1-diagnose.md` |
+| Create a new skill | Use the Read tool on `references/create-step-1-understand.md` to start the creation workflow |
+| Fix, improve, audit, or modify an existing skill | Use the Read tool on `references/fix-step-1-diagnose.md` to diagnose the issue |
 
 If the user says "audit my skills", that is the fix path.
 If they mention a specific skill that needs changes, that is also the fix path.

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

@@ -48,4 +48,4 @@ Move on when all of these are true:
 - You understand WHY the approaches work, not just WHAT they are
 - 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 skill's structure.

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

@@ -164,7 +164,7 @@ Every procedural skill must end with a dedicated reflection step file. This is a
 
 The reflection step is where the agent looks back on its experience using the skill and, if the instructions were wrong, incomplete, or suboptimal, updates the skill files. This creates a self-learning loop — skills improve through use.
 
-The chain link to the reflection step must use mandatory language. The agent must understand that the workflow is incomplete without it. Example: "**IMPORTANT: You are not done. You MUST read and complete the next step. The workflow is incomplete without it.**"
+The chain link to the reflection step must use the redirect pattern — frame reading the reflection step as how the agent presents results to the user. Example: "Use the Read tool on `references/step-N-reflect.md` to review your work and report results to the user."
 
 For informational skills, append a reflection section to the end of SKILL.md (since there is no step chain).
 
@@ -201,5 +201,5 @@ Ask: "Does this design look right?"
 
 | Context | Action |
 |---------|--------|
-| Creating a new skill | Read `references/create-step-3-write.md` |
-| Fixing an existing skill (came from fix-step-1-diagnose) | Read `references/fix-step-2-apply.md` to apply the structural changes |
+| Creating a new skill | Use the Read tool on `references/create-step-3-write.md` to write the skill files |
+| Fixing an existing skill (came from fix-step-1-diagnose) | Use the Read tool on `references/fix-step-2-apply.md` to apply the structural changes |

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

@@ -113,7 +113,7 @@ Each step file covers ONE phase of the workflow. Structure each file:
 
 1. A clear header naming the step
 2. Immediate actionable instructions — what to do NOW
-3. A chain link at the bottom: "Read `references/[next-step].md`" with an optional condition
+3. A chain link: "Use the Read tool on `references/[next-step].md` to [what the next step accomplishes]"
 
 **Critical rules:**
 - No table of contents across steps
@@ -144,8 +144,8 @@ description: [third person, trigger phrases, WHEN not HOW]
 
 | Choice | Action |
 |--------|--------|
-| Option A | Read `references/step-1-a.md` |
-| Option B | Read `references/step-1-b.md` |
+| Option A | Use the Read tool on `references/step-1-a.md` to [what it accomplishes] |
+| Option B | Use the Read tool on `references/step-1-b.md` to [what it accomplishes] |
 ```
 
 Keep it minimal. Only include context that is needed at EVERY activation.
@@ -165,19 +165,51 @@ Every procedural skill must have a dedicated reflection step as the final file i
 
 **The reflection step file** should contain:
 
-1. **Mandatory language at the top**: Start with "**IMPORTANT: This step is mandatory. The [workflow name] workflow is not complete until this step is finished. Do not skip this.**"
-2. **Assessment**: Domain-specific questions — "Were any instructions wrong, incomplete, or misleading? Did you have to figure something out that the skill should have told you? Did any commands, paths, or patterns fail and require correction?"
-3. **Action**: "If yes, identify the specific file where the issue lives, read it, and apply the fix. Apply the tribal knowledge test: only add what a fresh Claude instance would not already know."
-4. **Report**: "Tell the user what you changed and why, or confirm that no updates were needed."
+1. **Assessment**: Domain-specific questions — "Were any instructions wrong, incomplete, or misleading? Did you have to figure something out that the skill should have told you? Did any commands, paths, or patterns fail and require correction?"
+2. **Action**: "If yes, identify the specific file where the issue lives, read it, and apply the fix. Apply the tribal knowledge test: only add what a fresh Claude instance would not already know."
+3. **Report**: "Tell the user what you changed and why, or confirm that no updates were needed."
 
 Tailor the assessment questions to the skill's domain — what "went wrong" means for a prompting skill is different from what it means for a browser automation skill.
 
-**The chain link to the reflection step** (in the previous step file) must use mandatory language. Do not use a soft chain link. Example:
+### Chain Links Between Steps
 
+Chain links connect one step to the next. The key challenge: after a heavy generation step, the model's completion impulse is strong — it wants to present results and stop. Chain links must redirect that impulse rather than fight it.
+
+**The redirect pattern:**
+
+```
+Use the Read tool on `references/step-N-[name].md` to [what the next step accomplishes for the user].
+```
+
+This works because it frames reading the next step as HOW the model accomplishes what it already wants to do (present results, finish the task).
+
+**Why the old "IMPORTANT: You are not done" pattern fails:** Negative framing ("you are NOT done") fights the completion impulse head-on. After heavy generation, the model has strong momentum toward completion and ignores imperative warnings. The redirect pattern harnesses that momentum instead.
+
+**Pre-work priming:** At the TOP of generation-heavy steps (before the work begins), add a framing line:
+
+```
+These are drafts — review and present final results in the next step.
+```
+
+This primes the model to expect a follow-up step, reducing the completion impulse before it builds.
+
+**Integration rules:**
+- Place chain links INSIDE the action section, not as a separate afterthought section
+- For the final work step before reflection/presentation: frame the next step as where results get presented to the user
+- Keep chain links to one line — no multi-line bold warnings
+
+**Before/after example:**
+
+Before (old pattern — fails after heavy generation):
 ```
 **IMPORTANT: You are not done. You MUST read and complete the next step. The workflow is incomplete without it.**
 
-Read `references/step-N-reflect.md` now.
+Read `references/step-4-reflect.md` now.
+```
+
+After (redirect pattern — works with the completion impulse):
+```
+Use the Read tool on `references/step-4-reflect.md` to review your work and report results to the user.
 ```
 
 For informational skills (no step chain), append a reflection section to the end of SKILL.md instead.
@@ -208,4 +240,4 @@ With these principles applied, write all the skill files now:
 2. For procedural: each step file in `references/`
 3. Any `scripts/` or `templates/` files if the design calls for them
 
-Read `references/create-step-4-review.md` when all files are written.
+Use the Read tool on `references/create-step-4-review.md` to review all files before proceeding.