cc-dev-template 0.1.77 → 0.1.79

package/package.json

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

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

@@ -0,0 +1,33 @@
+# 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:
+
+1. Were any audit criteria (length thresholds, content rules, hierarchy checks) wrong, incomplete, or too strict/lenient?
+2. Did you encounter a CLAUDE.md pattern or anti-pattern that the audit steps didn't account for?
+3. Were the fix instructions (extracting workflows, removing duplication, pruning) clear and correct?
+4. Did you discover structural issues or hierarchy edge cases that should be documented for next time?
+5. Were the principles in `references/principles.md` accurate, or did real-world files reveal gaps?
+
+## Act
+
+If you identified issues above, fix them now:
+
+1. Identify the specific file in the claude-md skill 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 claude-md skill and why, OR
+- That no updates were needed and the skill performed correctly

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

@@ -62,12 +62,6 @@ Remaining concerns:
 - [any issues needing human decision]
 ```
 
-## Reflect
+**IMPORTANT: You are not done. You MUST read and complete the next step. The workflow is incomplete without it.**
 
-Before ending, reflect on your experience using this skill.
-
-Were any CLAUDE.md principles, structural guidelines, or audit criteria in this skill wrong or incomplete? Did you discover a CLAUDE.md pattern or anti-pattern that should be documented for next time?
-
-If yes, update the specific file in the claude-md skill directory. Only add tribal knowledge — insights a fresh Claude instance would not already know. Keep files within size targets.
-
-Tell the user what you updated, or confirm no updates were needed.
+Read references/audit-reflect.md now.

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

@@ -0,0 +1,33 @@
+# 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:
+
+1. Were the hierarchy-checking instructions (finding parents, identifying gaps) clear and sufficient?
+2. Was the structure template useful, or did the real file need sections the template didn't suggest?
+3. Were the length guidelines (40-80 lines target) realistic for the file you created?
+4. Did the "What NOT to Include" list miss anything that tempted you to over-include?
+5. Were the principles in `references/principles.md` accurate, or did the creation process reveal gaps?
+
+## Act
+
+If you identified issues above, fix them now:
+
+1. Identify the specific file in the claude-md skill 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 claude-md skill and why, OR
+- That no updates were needed and the skill performed correctly

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

@@ -69,14 +69,8 @@ Verify:
 3. Would Claude know where it is and what matters?
 4. Written as orientation, not documentation?
 
-If all yes, you're done.
+If all yes, proceed to the reflection step.
 
-## Reflect
+**IMPORTANT: You are not done. You MUST read and complete the next step. The workflow is incomplete without it.**
 
-Before ending, reflect on your experience using this skill.
-
-Were any CLAUDE.md principles, structural guidelines, or audit criteria in this skill wrong or incomplete? Did you discover a CLAUDE.md pattern or anti-pattern that should be documented for next time?
-
-If yes, update the specific file in the claude-md skill directory. Only add tribal knowledge — insights a fresh Claude instance would not already know. Keep files within size targets.
-
-Tell the user what you updated, or confirm no updates were needed.
+Read references/create-reflect.md now.

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

@@ -0,0 +1,33 @@
+# 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:
+
+1. Were the file-selection rules (matching request type to the right CLAUDE.md level) accurate and complete?
+2. Did the hierarchy principle ("place at highest level where it applies") hold up, or were there edge cases?
+3. Were the section-matching rules (gotchas, conventions, current focus) sufficient for the content you added?
+4. Did the ~100 line overflow guidance (push deeper, prune, extract) work in practice?
+5. Were the principles in `references/principles.md` accurate, or did the modification process reveal gaps?
+
+## Act
+
+If you identified issues above, fix them now:
+
+1. Identify the specific file in the claude-md skill 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 claude-md skill and why, OR
+- That no updates were needed and the skill performed correctly

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

@@ -51,12 +51,6 @@ 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.
 
-## Reflect
+**IMPORTANT: You are not done. You MUST read and complete the next step. The workflow is incomplete without it.**
 
-Before ending, reflect on your experience using this skill.
-
-Were any CLAUDE.md principles, structural guidelines, or audit criteria in this skill wrong or incomplete? Did you discover a CLAUDE.md pattern or anti-pattern that should be documented for next time?
-
-If yes, update the specific file in the claude-md skill directory. Only add tribal knowledge — insights a fresh Claude instance would not already know. Keep files within size targets.
-
-Tell the user what you updated, or confirm no updates were needed.
+Read references/modify-reflect.md now.

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

@@ -141,7 +141,8 @@ skill-name/
 └── references/
     ├── step-1-[name].md        # Chains to step 2
     ├── step-2-[name].md        # Chains to step 3
-    └── step-3-[name].md        # Final step
+    ├── step-3-[name].md        # Chains to reflection (mandatory)
+    └── step-4-reflect.md       # Mandatory reflection step
 ```
 
 **When to add `scripts/`:** Deterministic operations that need reliability — validation, code generation, file operations.
@@ -157,11 +158,15 @@ List out the steps. Each step becomes one markdown file in `references/`. For ea
 - What signals the step is complete (the chain condition)
 - What the next step is
 
-### Include a Reflection Step
+### Include a Mandatory Reflection Step
 
-Every skill must end with a reflection section. This is not a separate chained step file — it is a section appended to the skill's existing final step (or the end of SKILL.md for informational skills). Plan for 10-20 lines.
+Every procedural skill must end with a dedicated reflection step file. This is a separate chained step — not a section appended to another step. The reflection step is the final file in the chain.
 
-The reflection section 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 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.**"
+
+For informational skills, append a reflection section to the end of SKILL.md (since there is no step chain).
 
 For forked-context skills (`context: fork`), use a "Skill Observations" section in the output format instead, since the sub-agent should not edit skill files from an isolated context.
 

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

@@ -159,23 +159,30 @@ If the skill involves tool calls, external services, or operations that can fail
 
 For critical validations, bundle a script rather than relying on language instructions. Code is deterministic; language interpretation is not.
 
-### Reflection Step
+### Reflection Step (Mandatory Separate File)
 
-Every skill's final step (or the end of single-file skills) must include a reflection section. This creates a self-learning loop: the agent assesses its experience and updates the skill for next time.
+Every procedural skill must have a dedicated reflection step as the final file in its chain. This is not a section in another file — it is its own step file. This creates a self-learning loop: the agent assesses its experience and updates the skill for next time.
 
-Place the reflection after the work completion section (after "Completion", "Report Results", or equivalent). Structure it as:
+**The reflection step file** should contain:
 
-1. **Trigger**: "Before ending, reflect on your experience using this skill."
-2. **Assessment**: "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, update the specific skill file where the issue lives. Apply the tribal knowledge test: only add what a fresh Claude instance would not already know."
-4. **Guardrails**: "Keep changes minimal. Fix what was wrong, add what was missing. Do not bloat the file beyond its size target or record situation-specific details that would not generalize."
-5. **Report**: "Tell the user what you changed and why, or confirm that no updates were needed."
+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."
 
 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.
 
-For forked-context skills (`context: fork`), add a "Skill Observations" optional section to the output format instead. The sub-agent notes any issues with its own instructions; the parent context decides whether to act.
+**The chain link to the reflection step** (in the previous step file) must use mandatory language. Do not use a soft chain link. Example:
+
+```
+**IMPORTANT: You are not done. You MUST read and complete the next step. The workflow is incomplete without it.**
 
-Keep the reflection section under 20 lines. Use imperative voice like all skill content.
+Read `references/step-N-reflect.md` now.
+```
+
+For informational skills (no step chain), append a reflection section to the end of SKILL.md instead.
+
+For forked-context skills (`context: fork`), add a "Skill Observations" optional section to the output format instead. The sub-agent notes any issues with its own instructions; the parent context decides whether to act.
 
 ### MCP Tool References
 

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

@@ -44,7 +44,9 @@ Go through each file and verify:
 - Name matches the directory name?
 - Description uses third person with quoted trigger phrases?
 - All referenced files exist? (no broken links)
-- Reflection step present in the final step file (or end of SKILL.md for informational skills)?
+- 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.")
+- For informational skills: reflection section at the end of SKILL.md?
 - For forked-context skills: "Skill Observations" section in the output format?
 
 ## Run Validation

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

@@ -62,12 +62,6 @@ Summarize what was created:
 - Trigger phrases
 - File structure (list all files)
 
-## Reflect
+**IMPORTANT: You are not done. You MUST read and complete the next step. The workflow is incomplete without it.**
 
-Before ending, reflect on your experience creating this skill.
-
-Were any instructions in the creating-agent-skills skill wrong, incomplete, or misleading? Did you discover techniques, gotchas, or patterns that should be encoded for next time? Did any steps send you down a wrong path or leave out critical guidance?
-
-If yes, identify the specific file in the creating-agent-skills skill where the issue lives and update it. Apply the tribal knowledge test: only add what a fresh Claude instance would not already know. Keep the file within its size target.
-
-Tell the user what you updated, or confirm no skill updates were needed.
+Read `references/create-step-6-reflect.md` now.

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

@@ -0,0 +1,33 @@
+# 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.
+
+## Assess
+
+Answer these questions honestly:
+
+1. Were any instructions in the creating-agent-skills workflow wrong, incomplete, or misleading?
+2. Did you discover techniques, gotchas, or patterns that should be encoded for next time?
+3. Did any steps send you down a wrong path or leave out critical guidance?
+4. Did you have to figure something out that the skill should have told you?
+5. Did any commands, paths, or patterns fail and require correction?
+
+## Act
+
+If you identified issues above, fix them now:
+
+1. Identify the specific file in the creating-agent-skills skill 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 creating-agent-skills skill and why, OR
+- That no updates were needed and the skill performed correctly

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

@@ -73,9 +73,11 @@ Evaluate each file against these criteria:
 - Any unreferenced files in `references/` that should be connected?
 
 ### Self-Learning
-- Does the skill have a reflection step in its final step file (or at the end of SKILL.md for informational skills)?
+- 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.")
+- 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, flag it — every skill needs a self-learning loop.
+- If missing or embedded as a section in another step file, flag it — every procedural skill needs a separate mandatory reflection step.
 
 ## Summarize Findings
 

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:** Append a reflection section to the skill's final step file (or end of SKILL.md for informational skills). See `references/create-step-3-write.md` "Reflection Step" section for the writing guidance. 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 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.
 
 ## Apply the Changes
 

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

@@ -53,12 +53,6 @@ Summarize what was fixed:
 - What was wrong and how it was resolved
 - Confirm with the user that the skill now behaves as expected
 
-## Reflect
+**IMPORTANT: You are not done. You MUST read and complete the next step. The workflow is incomplete without it.**
 
-Before ending, reflect on your experience fixing this skill.
-
-Were any diagnostic criteria, fix patterns, or writing principles in the creating-agent-skills skill wrong, incomplete, or misleading? Did you discover something during diagnosis or repair that should be encoded for next time?
-
-If yes, identify the specific file in the creating-agent-skills skill where the issue lives and update it. Apply the tribal knowledge test: only add what a fresh Claude instance would not already know. Keep the file within its size target.
-
-Tell the user what you updated, or confirm no skill updates were needed.
+Read `references/fix-step-4-reflect.md` now.

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

@@ -0,0 +1,32 @@
+# 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.
+
+## Assess
+
+Answer these questions honestly:
+
+1. Were any diagnostic criteria, fix patterns, or writing principles in the creating-agent-skills skill wrong, incomplete, or misleading?
+2. Did you discover something during diagnosis or repair that should be encoded for next time?
+3. Did you have to figure something out that the skill should have told you?
+4. Were any common fix patterns missing from the fix workflow?
+
+## Act
+
+If you identified issues above, fix them now:
+
+1. Identify the specific file in the creating-agent-skills skill 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 creating-agent-skills skill and why, OR
+- That no updates were needed and the skill performed correctly

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

@@ -75,12 +75,6 @@ Summarize what was created:
 - Memory scope (if any)
 - Skills preloaded (if any)
 
-## Reflect
+**IMPORTANT: You are not done. You MUST read and complete the next step. The workflow is incomplete without it.**
 
-Before ending, reflect on your experience creating this sub-agent.
-
-Were any instructions in the creating-sub-agents skill wrong, incomplete, or misleading? Did you discover techniques, gotchas, or patterns that should be encoded for next time? Did any steps send you down a wrong path or leave out critical guidance?
-
-If yes, identify the specific file in the creating-sub-agents skill where the issue lives and update it. Apply the tribal knowledge test: only add what a fresh Claude instance would not already know. Keep the file within its size target.
-
-Tell the user what you updated, or confirm no skill updates were needed.
+Read `references/create-step-6-reflect.md` now.

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

@@ -0,0 +1,33 @@
+# 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:
+
+1. Were any instructions in the creating-sub-agents workflow wrong, incomplete, or misleading?
+2. Did you discover techniques, gotchas, or patterns for sub-agent design that should be encoded for next time?
+3. Did any steps send you down a wrong path or leave out critical guidance?
+4. Did you have to figure something out about frontmatter, tool grants, delegation, or prompt structure that the skill should have told you?
+5. Did any commands, paths, validation scripts, or patterns fail and require correction?
+
+## Act
+
+If you identified issues above, fix them now:
+
+1. Identify the specific file in the creating-sub-agents skill 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 creating-sub-agents skill and why, OR
+- That no updates were needed and the skill performed correctly

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

@@ -51,12 +51,6 @@ Summarize what was fixed:
 - What was wrong and how it was resolved
 - Confirm with the user that the sub-agent now behaves as expected
 
-## Reflect
+**IMPORTANT: You are not done. You MUST read and complete the next step. The workflow is incomplete without it.**
 
-Before ending, reflect on your experience fixing this sub-agent.
-
-Were any diagnostic criteria, fix patterns, or writing principles in the creating-sub-agents skill wrong, incomplete, or misleading? Did you discover something during diagnosis or repair that should be encoded for next time?
-
-If yes, identify the specific file in the creating-sub-agents skill where the issue lives and update it. Apply the tribal knowledge test: only add what a fresh Claude instance would not already know. Keep the file within its size target.
-
-Tell the user what you updated, or confirm no skill updates were needed.
+Read `references/fix-step-4-reflect.md` now.

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

@@ -0,0 +1,33 @@
+# 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:
+
+1. Were any diagnostic criteria, fix patterns, or writing principles in the creating-sub-agents skill wrong, incomplete, or misleading?
+2. Did you discover something during diagnosis or repair that should be encoded for next time?
+3. Did the validation script catch the right issues, or did it miss something important?
+4. Did you have to figure something out about sub-agent frontmatter, tool grants, or prompt structure that the skill should have told you?
+5. Did any commands, paths, validation scripts, or patterns fail and require correction?
+
+## Act
+
+If you identified issues above, fix them now:
+
+1. Identify the specific file in the creating-sub-agents skill 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 creating-sub-agents skill and why, OR
+- That no updates were needed and the skill performed correctly

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

@@ -33,6 +33,7 @@ Read `references/workflow.md` for the full orchestration flow.
 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
 

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

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

package/src/skills/execute-spec/references/workflow.md

@@ -19,6 +19,10 @@ PHASE 4: TRIAGE
   For failed tasks: re-dispatch spec-implementer
   Re-validate
   Loop until clean or user defers
+
+PHASE 5: REFLECT
+  Assess orchestration experience → improve skill files
+  (Mandatory — workflow is NOT complete without this)
 ```
 
 ## Critical: Minimal Context
@@ -73,12 +77,6 @@ Read `phase-4-triage.md` for details.
 - **Task file is source of truth** - Implementation Notes and Review Notes track all history
 - **Parallelism** - Use `run_in_background: true` where possible
 
-## Reflect
-
-Before ending, reflect on your experience using this skill.
-
-Were any orchestration patterns, dispatch instructions, or triage procedures in this skill wrong or incomplete? Did the implementer/validator loop reveal a pattern that should be encoded for next time?
-
-If yes, update the specific file in the execute-spec skill directory. Only add tribal knowledge. Keep files within size targets.
+**IMPORTANT: You are not done. You MUST read and complete the next step. The workflow is incomplete without it.**
 
-Tell the user what you updated, or confirm no updates were needed.
+Read `references/phase-5-reflect.md` now.

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

@@ -32,12 +32,6 @@ Report what was created:
 
 End with: "Run `/prime` to start a session."
 
-## Reflect
+**IMPORTANT: You are not done. You MUST read and complete the next step. The workflow is incomplete without it.**
 
-Before ending, reflect on your experience using this skill.
-
-Were any template paths, placeholder formats, or initialization steps in this skill wrong or incomplete? Did you discover a project scaffolding pattern that should be encoded for next time?
-
-If yes, update this skill file. Only add tribal knowledge — details a fresh Claude instance would not already know. Keep within size targets.
-
-Tell the user what you updated, or confirm no updates were needed.
+Read references/reflect.md now.

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

@@ -0,0 +1,33 @@
+# 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:
+
+1. Were any template paths, placeholder formats, or initialization steps in this skill wrong or incomplete?
+2. Did you discover project scaffolding patterns or gotchas that should be encoded for next time?
+3. Did any steps send you down a wrong path or leave out critical guidance?
+4. Did you have to figure something out that the skill should have told you?
+5. Did any templates, paths, or placeholder substitutions fail and require correction?
+
+## Act
+
+If you identified issues above, fix them now:
+
+1. Identify the specific file in the initialize-project skill 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 initialize-project skill and why, OR
+- That no updates were needed and the skill performed correctly

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

@@ -69,12 +69,6 @@ Tell the user:
 
 If everything passed, the setup is complete.
 
-## Reflect
+**IMPORTANT: You are not done. You MUST read and complete the next step. The workflow is incomplete without it.**
 
-Before ending, reflect on your experience using this skill.
-
-Were any Makefile patterns, hook configurations, or verification steps in this skill wrong or incomplete? Did you discover a project setup convention that should be encoded for next time?
-
-If yes, update the specific file in the project-setup skill directory. Only add tribal knowledge. Keep files within size targets.
-
-Tell the user what you updated, or confirm no updates were needed.
+Read `references/step-6-reflect.md` now.

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

@@ -0,0 +1,34 @@
+# 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:
+
+1. Were any instructions in the project-setup workflow wrong, incomplete, or misleading?
+2. Did you discover Makefile patterns, script conventions, or hook configurations that should be encoded for next time?
+3. Did any steps send you down a wrong path or leave out critical guidance?
+4. Did you have to figure something out that the skill should have told you?
+5. Did any commands, paths, or patterns fail and require correction?
+6. Were there language-specific setup needs that the skill didn't cover?
+
+## Act
+
+If you identified issues above, fix them now:
+
+1. Identify the specific file in the project-setup skill 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 project-setup skill and why, OR
+- That no updates were needed and the skill performed correctly

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

@@ -0,0 +1,33 @@
+# 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:
+
+1. Were any prompting principles, writing guidance, or structural templates in this skill wrong or incomplete?
+2. Did you discover a prompt engineering technique that worked well but is not captured in the skill?
+3. Did the requirements-gathering questions miss something important that you had to figure out on your own?
+4. Did any guidance lead to a weaker prompt that needed correction during iteration?
+5. Did the self-review checklist catch real issues, or did it miss problems the user flagged?
+
+## Act
+
+If you identified issues above, fix them now:
+
+1. Identify the specific file in the prompting 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 prompt engineering
+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 prompting skill and why, OR
+- That no updates were needed and the skill performed correctly

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

@@ -58,12 +58,6 @@ Ask: "Does this capture what you need? Any adjustments?"
 
 Incorporate feedback until the user is satisfied.
 
-## Reflect
+**IMPORTANT: You are not done. You MUST read and complete the next step. The workflow is incomplete without it.**
 
-Before ending, reflect on your experience using this skill.
-
-Were any prompting principles, review criteria, or writing guidance in this skill wrong or incomplete? Did you apply a technique that worked well but is not captured here? Did any guidance lead to a weaker prompt that needed correction?
-
-If yes, update the specific file in the prompting skill directory. Only add tribal knowledge — patterns or insights a fresh Claude instance would not already know about prompt engineering. Keep the file within its size target.
-
-Tell the user what you updated, or confirm no updates were needed.
+Read `references/create-reflect.md` now.

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

@@ -0,0 +1,33 @@
+# 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:
+
+1. Were any review criteria, analysis checks, or prompting principles in this skill wrong or incomplete?
+2. Did you apply a review technique that caught real issues but is not captured in the skill?
+3. Did any of the four checks (positive framing, clarity, context, over-specification) miss a category of prompt problem you encountered?
+4. Did the review presentation format work well, or did the user need a different structure?
+5. Did any guidance lead you to flag something that was actually fine, or miss something that was genuinely problematic?
+
+## Act
+
+If you identified issues above, fix them now:
+
+1. Identify the specific file in the prompting 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 prompt engineering
+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 prompting skill and why, OR
+- That no updates were needed and the skill performed correctly

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

@@ -77,12 +77,6 @@ Ask: "Would you like me to adjust anything in the improved version?"
 
 Incorporate feedback and present updated version until the user is satisfied.
 
-## Reflect
+**IMPORTANT: You are not done. You MUST read and complete the next step. The workflow is incomplete without it.**
 
-Before ending, reflect on your experience using this skill.
-
-Were any prompting principles, review criteria, or writing guidance in this skill wrong or incomplete? Did you apply a technique that worked well but is not captured here? Did any guidance lead to a weaker prompt that needed correction?
-
-If yes, update the specific file in the prompting skill directory. Only add tribal knowledge — patterns or insights a fresh Claude instance would not already know about prompt engineering. Keep the file within its size target.
-
-Tell the user what you updated, or confirm no updates were needed.
+Read `references/review-reflect.md` now.

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

@@ -62,12 +62,6 @@ After writing the document:
 2. Summarize the key takeaways
 3. Return to the invoking context (spec-interview or user)
 
-## Reflect
+**IMPORTANT: You are not done. You MUST read and complete the next step. The workflow is incomplete without it.**
 
-Before ending, reflect on your experience using this skill.
-
-Were any research strategies, output format requirements, or source evaluation criteria in this skill wrong or incomplete? Did you discover a research approach or information synthesis technique that should be encoded for next time?
-
-If yes, update the specific file in the research skill directory. Only add tribal knowledge — insights a fresh Claude instance would not already know about conducting research. Keep files within size targets.
-
-Tell the user what you updated, or confirm no updates were needed.
+Read `references/step-3-reflect.md` now.

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

@@ -0,0 +1,33 @@
+# 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:
+
+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/references/step-7-finalize.md

@@ -55,14 +55,8 @@ Once user confirms no more review passes needed:
    - After all teammates confirm shutdown, use TeamDelete to clean up team resources
    - The `{spec_dir}/working/` directory remains on disk as reference for implementation
 
-## Reflect
-
-Before ending, reflect on your experience conducting this spec interview.
-
-Were any interview steps, team coordination patterns, or checkpoint instructions in this skill wrong or incomplete? Did you discover a question sequence, team interaction pattern, or spec structure that worked better than what the skill prescribed?
-
-If yes, identify the specific file in the spec-interview skill where the issue lives and update it. Only add tribal knowledge — insights a fresh Claude instance would not already know about conducting spec interviews. Keep the file within its size target.
+If yes to task breakdown, invoke `spec-to-tasks` and specify which spec to break down.
 
-Tell the user what you updated, or confirm no skill updates were needed.
+**IMPORTANT: You are not done. You MUST read and complete the next step. The workflow is incomplete without it.**
 
-If yes to task breakdown, invoke `spec-to-tasks` and specify which spec to break down.
+Read `references/step-8-reflect.md` now.

package/src/skills/spec-interview/references/step-8-reflect.md

@@ -0,0 +1,34 @@
+# 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.
+
+## Assess
+
+Answer these questions honestly:
+
+1. Were any interview steps wrong, incomplete, or misleading? Did any step send you down a wrong path or leave out critical guidance?
+2. Did the team coordination work smoothly? Were the checkpoint patterns (post-ideation, deep dive, finalize) at the right moments? Did any teammate produce findings too late or too early to be useful?
+3. Did the prompt templates (researcher, critic, pragmatist) give adequate direction? Did any teammate misunderstand its role or produce unhelpful output?
+4. Did you discover a question sequence, interview technique, or spec structure that worked better than what the skill prescribed?
+5. Did any commands, paths, tool interactions, or team communication patterns fail and require correction?
+6. Was the step ordering right? Should any steps be reordered, merged, or split?
+
+## Act
+
+If you identified issues above, fix them now:
+
+1. Identify the specific file in the spec-interview skill 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 spec interviews or coordinating agent teams
+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 spec-interview skill and why, OR
+- That no updates were needed and the skill performed correctly

package/src/skills/spec-to-tasks/SKILL.md

@@ -9,14 +9,15 @@ context: fork
 
 ## Workflow Overview
 
-This skill has 4 steps. **You must complete ALL steps before presenting to the user.**
+This skill has 5 steps. **You must complete ALL steps. Do not stop early or skip any step.**
 
 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** - Invoke `task-review` skill to validate, fix issues
+4. **Review Tasks** - Run review checklist in a loop until no critical issues remain
+5. **Reflect** - Note any skill issues observed during this run
 
-Do NOT skip step 4. The review catches dependency errors and coverage gaps.
+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.
 
 ## What To Do Now
 

package/src/skills/spec-to-tasks/references/step-3-generate.md

@@ -60,13 +60,10 @@ docs/specs/<name>/
 
 Use the template in `templates/task.md` for each file. Name files in dependency order so alphabetical sorting reflects execution order.
 
-## REQUIRED: Run Review Before Presenting
+## Do NOT Present Results Yet
 
-**Do NOT present results to the user yet.** After generating task files, you MUST:
+You have generated task files but you are NOT done. The review step is next and it is mandatory.
 
-1. Read `references/step-4-review.md`
-2. Invoke the `task-review` skill to validate the breakdown
-3. Fix any critical issues found
-4. Only then present results (including any warnings)
+**IMPORTANT: You are not done. You MUST read and complete the next step. The workflow is incomplete without it.**
 
-This review step catches dependency errors, coverage gaps, and verification issues. Skipping it leads to broken task breakdowns that fail during implementation.
+Read `references/step-4-review.md` now.

package/src/skills/spec-to-tasks/references/step-4-review.md

@@ -1,50 +1,95 @@
 # Step 4: Review Task Breakdown
 
-**This step is REQUIRED.** Do not present results until review is complete.
+**IMPORTANT: This step is mandatory. The spec-to-tasks workflow is not complete until this step is finished. Do not skip this.**
 
-## Run Task Review
+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.
 
-Invoke the task-review skill NOW:
+## Review Checklist
 
-```
-Skill(skill: "task-review", args: "<spec-name>")
-```
+Read every task file and the spec. Evaluate each area below. For each issue found, note the severity:
+- **Critical**: Must fix before proceeding
+- **Warning**: Should fix, but could proceed
+- **Note**: Minor suggestion
 
-Wait for the review to complete before proceeding.
+### 1. Coverage
 
-The review will check:
-- Coverage (all criteria have tasks)
-- Dependency order (tasks properly sequenced)
-- File plausibility (paths make sense)
-- Verification executability (concrete commands)
-- Task scope (appropriately sized)
-- Consistency (format, frontmatter)
+Compare acceptance criteria in the spec to tasks generated.
 
-## Handle Findings
+- Every acceptance criterion has exactly one corresponding task
+- No criteria were skipped or forgotten
+- No phantom tasks that don't map to a criterion
 
-The review returns findings categorized as Critical, Warning, or Note.
+**How to verify:** List each criterion from the spec's Acceptance Criteria section. For each, find the matching task file. Flag any orphans in either direction.
 
-**Critical issues**: Fix before proceeding. Update the affected task files.
+### 2. Dependency Order
 
-**Warnings**: Present to user with your recommendation (fix or skip).
+- Task file names sort in valid execution order (T001, T002, etc.)
+- Each task's `depends_on` references only earlier tasks
+- No circular dependencies
+- Foundation work comes before features that use it
 
-**Notes**: Mention briefly, no action required.
+### 3. File Plausibility
 
-## Present to User
+- File paths follow project conventions
+- Files to modify actually exist in the codebase
+- Files to create are in appropriate directories
+- No duplicate files across tasks (each file appears in exactly one task)
 
-After addressing critical issues, present:
+### 4. Verification Executability
 
-1. Number of tasks generated
-2. Task titles in dependency order
-3. Any warnings from the review (with recommendations)
-4. Offer to show task files or proceed to implementation
+- Verification is a specific command or script, not vague prose
+- Test file paths exist or will be created by the task
+- No "manually verify" without clear steps
+
+**Red flags:** "Verify it works correctly", "Check that the feature functions", test commands for files not listed in the task.
+
+### 5. Verification Completeness
+
+- Read the criterion text carefully — identify every distinct behavior or edge case mentioned
+- For each behavior, confirm there's a corresponding verification step
+- Flag any behaviors in the criterion that have no verification
+
+### 6. Dependency Completeness
+
+- If task X modifies a file, check if another task creates it — that task must be in X's depends_on
+- If task X uses a component/function/route, check if another task creates it — that task must be in X's depends_on
+
+### 7. Task Scope
+
+- No task touches more than ~10 files (consider splitting)
+- No trivially small tasks that could merge with related work
+- Each task produces a verifiable outcome
+
+### 8. Consistency
 
-If the user wants changes, update the task files and re-run the review.
+- Task titles match or closely reflect the acceptance criterion
+- Status is `pending` for all new tasks
+- Frontmatter format is consistent across all task files
 
-## Skill Observations
+### 9. Component Consolidation
 
-If any task generation patterns, step instructions, or template formats in this skill were wrong, incomplete, or misleading during this run, include a note in your final output to the user. This helps the parent context decide whether to update the skill.
+- 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
+
+Run the checklist above against all task files. Then:
+
+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 after a single pass if Critical issues exist. The loop must continue until clean.
+
+## Present to User
+
+After the review loop completes with no Critical issues, 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
 
-## Complete
+**IMPORTANT: You are not done. You MUST read and complete the next step. The workflow is incomplete without it.**
 
-Once the user approves the task breakdown, the skill is complete. The tasks are ready for implementation.
+Read `references/step-5-reflect.md` now.

package/src/skills/spec-to-tasks/references/step-5-reflect.md

@@ -0,0 +1,22 @@
+# Step 5: Skill Reflection
+
+**IMPORTANT: This step is mandatory. The spec-to-tasks workflow is not complete until this step is finished. Do not skip this.**
+
+## Reflect on This Run
+
+Think about how this skill performed during this session. Consider:
+
+1. **Step instructions**: Were any steps unclear, misleading, or missing information?
+2. **Task template**: Did the template work well, or did you need to deviate from it?
+3. **Review checklist**: Did the checklist catch real issues? Were any checks unnecessary or missing?
+4. **Workflow flow**: Did the step order make sense? Were there unnecessary steps or missing ones?
+
+## Report Issues
+
+If you identified any problems with the skill's instructions, templates, or workflow, include a brief note in your final output to the user under a "Skill Observations" heading. Keep it factual — what was wrong, what would be better.
+
+If everything worked well, state: "No skill issues observed."
+
+## Complete
+
+The spec-to-tasks workflow is now complete.