cc-dev-template 0.1.76 → 0.1.78

package/bin/install.js

@@ -255,8 +255,8 @@ if (fs.existsSync(mergeSettingsPath)) {
     { file: 'read-guard-hook.json', name: 'Context guard for large reads' },
     { file: 'task-output-guard-hook.json', name: 'TaskOutput context guard' },
     { file: 'statusline-config.json', name: 'Custom status line' },
-    // Spinner verbs - choose one (Helldivers or Factorio)
-    { file: 'spinner-verbs-helldivers.json', name: 'Helldivers spinner verbs' }
+    // Spinner verbs - choose one (Star Trek or Factorio)
+    { file: 'spinner-verbs-startrek.json', name: 'Star Trek spinner verbs' }
     // { file: 'spinner-verbs-factorio.json', name: 'Factorio spinner verbs' }
   ];
 
@@ -312,7 +312,8 @@ const deprecatedFiles = [
   path.join(CLAUDE_DIR, 'scripts', 'bash-precheck-hook.json'),
   path.join(CLAUDE_DIR, 'hooks', 'bash-overflow-guard.sh'),
   path.join(CLAUDE_DIR, 'scripts', 'bash-overflow-hook.json'),
-  path.join(CLAUDE_DIR, 'scripts', 'env-config.json')
+  path.join(CLAUDE_DIR, 'scripts', 'env-config.json'),
+  path.join(CLAUDE_DIR, 'scripts', 'spinner-verbs-helldivers.json')
 ];
 
 deprecatedFiles.forEach(file => {

package/package.json

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

package/src/scripts/spinner-verbs-startrek.json

@@ -0,0 +1,47 @@
+{
+  "spinnerVerbs": {
+    "mode": "replace",
+    "verbs": [
+      "Engaging warp drive",
+      "Hailing frequencies open",
+      "Scanning for lifeforms",
+      "Routing through deflector dish",
+      "Calibrating phasers",
+      "Modulating shield harmonics",
+      "Consulting the computer",
+      "Running diagnostic",
+      "Reversing polarity",
+      "Diverting auxiliary power",
+      "Locking on target",
+      "Compensating for interference",
+      "Rerouting power",
+      "Establishing uplink",
+      "Analyzing subspace anomaly",
+      "Initializing transporter",
+      "Plotting course",
+      "Processing sensor data",
+      "Accessing Starfleet database",
+      "Raising shields",
+      "Optimizing ratios",
+      "Expanding the factory",
+      "Researching technology",
+      "Balancing belts",
+      "Routing logistics",
+      "Smelting ore",
+      "Automating production",
+      "Deploying blueprints",
+      "Scaling throughput",
+      "Refining petroleum",
+      "Extending rail network",
+      "Calculating ratios",
+      "Processing resources",
+      "Assembling components",
+      "Constructing outpost",
+      "Launching rockets",
+      "Clearing biters",
+      "Inserting inserters",
+      "Growing the factory",
+      "The factory must grow"
+    ]
+  }
+}

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

@@ -204,3 +204,13 @@ agent-browser find testid "submit-btn" click
 ./templates/authenticated-session.sh https://app.example.com/login
 ./templates/capture-workflow.sh https://example.com ./output
 ```
+
+## 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/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

@@ -61,3 +61,7 @@ Changes made:
 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.

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,4 +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.
+
+**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.

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

@@ -50,3 +50,7 @@ If the content would make the file exceed ~100 lines, consider:
 ## Step 5: Confirm
 
 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.

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,6 +158,18 @@ 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 Mandatory Reflection Step
+
+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 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.
+
 ## Confirm With the User
 
 Present the design:

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

@@ -159,6 +159,31 @@ 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 (Mandatory Separate File)
+
+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.
+
+**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."
+
+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:
+
+```
+**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.
+```
+
+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
 
 When a skill uses MCP tools, use fully qualified names:

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

@@ -44,6 +44,10 @@ 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)
+- 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

@@ -61,3 +61,7 @@ Summarize what was created:
 - Install location
 - 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.

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

@@ -72,6 +72,13 @@ Evaluate each file against these criteria:
 - All referenced files exist?
 - Any unreferenced files in `references/` that should be connected?
 
+### 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.")
+- 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.
+
 ## Summarize Findings
 
 Present the diagnosis to the user:
@@ -90,6 +97,7 @@ Based on your diagnosis, determine which type of fix is needed:
 - Removing meta-descriptions
 - Fixing broken file references
 - Small description improvements
+- Adding a missing reflection step
 
 **Structural changes** — anything that changes the skill's architecture:
 - Converting between informational and procedural types

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

@@ -94,6 +94,8 @@ 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.
+
 ## Apply the Changes
 
 Make all planned modifications now.

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

@@ -52,3 +52,7 @@ Summarize what was fixed:
 - Which files changed
 - 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.

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

@@ -74,3 +74,7 @@ Summarize what was created:
 - Model
 - 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.

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

@@ -50,3 +50,7 @@ Summarize what was fixed:
 - Which aspects changed (frontmatter, prompt, hooks)
 - 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.

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
@@ -72,3 +76,7 @@ Read `phase-4-triage.md` for details.
 - **Minimal returns** - Agents return status only, details in task files
 - **Task file is source of truth** - Implementation Notes and Review Notes track all history
 - **Parallelism** - Use `run_in_background: true` where possible
+
+**IMPORTANT: You are not done. You MUST read and complete the next step. The workflow is incomplete without it.**
+
+Read `references/phase-5-reflect.md` now.

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

@@ -31,3 +31,7 @@ Report what was created:
 - `CLAUDE.md` - created or unchanged
 
 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.

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

@@ -68,3 +68,7 @@ Tell the user:
 - Whether the project is ready to use
 
 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.

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

@@ -57,3 +57,7 @@ Present the draft prompt to the user.
 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.

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

@@ -76,3 +76,7 @@ Format the review as:
 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.

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

@@ -61,3 +61,7 @@ After writing the document:
 1. Confirm the research is complete
 2. Summarize the key takeaways
 3. Return to the invoking context (spec-interview or user)
+
+**IMPORTANT: You are not done. You MUST read and complete the next step. The workflow is incomplete without it.**
+
+Read `references/step-3-reflect.md` now.

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

@@ -56,3 +56,7 @@ Once user confirms no more review passes needed:
    - The `{spec_dir}/working/` directory remains on disk as reference for implementation
 
 If yes to task breakdown, invoke `spec-to-tasks` and specify which spec to break down.
+
+**IMPORTANT: You are not done. You MUST read and complete the next step. The workflow is incomplete without it.**
+
+Read `references/step-8-reflect.md` now.

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

@@ -81,6 +81,9 @@ Return the review as:
 ### Blocking Dependencies
 - [Dependency]: [What's needed before implementation can start]
 
+### Skill Observations (optional)
+If any checklist items, evaluation criteria, or output format instructions in this skill were wrong, incomplete, or misleading during this review, note them here. Leave empty if no issues were found.
+
 ### Recommendation
 [Specific questions to ask the user, or "Spec is implementation-ready"]
 ```

package/src/skills/spec-sanity-check/SKILL.md

@@ -71,6 +71,9 @@ Return findings as:
 ### Potential Pitfalls
 - [Pitfall]: [How to avoid]
 
+### Skill Observations (optional)
+If any evaluation questions, check categories, or output format instructions in this skill were wrong, incomplete, or misleading during this review, note them here. Leave empty if no issues were found.
+
 ### Recommendation
 [Either "Plan is sound" or specific concerns to address]
 ```

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

@@ -41,6 +41,10 @@ After addressing critical issues, present:
 
 If the user wants changes, update the task files and re-run the review.
 
+## Skill Observations
+
+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.
+
 ## Complete
 
 Once the user approves the task breakdown, the skill is complete. The tasks are ready for implementation.

package/src/skills/task-review/references/checklist.md

@@ -147,6 +147,9 @@ Return findings as a structured list:
 
 ## Notes
 - [T004] Could merge with T005 since they share the same files
+
+## Skill Observations (optional)
+If any checklist items, severity criteria, or review patterns in this skill were wrong, incomplete, or misleading during this review, note them here. Leave empty if no issues were found.
 ```
 
 If no issues found, state: "Task breakdown looks good. All criteria covered, dependencies valid, verification methods concrete."

package/src/scripts/spinner-verbs-helldivers.json

@@ -1,27 +0,0 @@
-{
-  "spinnerVerbs": {
-    "mode": "replace",
-    "verbs": [
-      "Spreading democracy",
-      "Liberating",
-      "Deploying stratagems",
-      "Calling in reinforcements",
-      "Eliminating hostiles",
-      "Securing perimeter",
-      "Extracting intel",
-      "Suppressing resistance",
-      "Dispensing freedom",
-      "Neutralizing threats",
-      "Conducting reconnaissance",
-      "Mobilizing forces",
-      "Purging enemies",
-      "Defending liberty",
-      "Executing orbital strike",
-      "Requesting extraction",
-      "Fortifying position",
-      "Engaging targets",
-      "Invoking Super Earth",
-      "Upholding managed democracy"
-    ]
-  }
-}