bmad-module-skill-forge 0.9.0 → 0.10.0

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "bmad-module-skill-forge",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "BMAD module — Turn code and docs into instructions AI agents can actually follow. Progressive capability tiers (Quick/Forge/Forge+/Deep).",
   "keywords": [
     "bmad",

package/src/module.yaml

@@ -20,6 +20,10 @@ sidecar_path:
   default: "_bmad/_memory/forger-sidecar"
   result: "{project-root}/{value}"
 
+health_check_repo:
+  prompt: false
+  default: "armelhbobdad/bmad-module-skill-forge"
+
 # Variables from Core Config inserted:
 ## user_name
 ## communication_language

package/src/workflows/analyze-source/steps-c/step-06-generate-briefs.md

@@ -4,6 +4,7 @@ description: 'Generate skill-brief.yaml per confirmed unit, write analysis summa
 
 outputFile: '{forge_data_folder}/analyze-source-report-{project_name}.md'
 schemaFile: '../data/skill-brief-schema.md'
+nextStepFile: '../../shared/health-check.md'
 ---
 
 # Step 6: Generate Briefs
@@ -212,6 +213,10 @@ nextWorkflow: '{primary recommendation}'
 
 **This analysis is complete.** To refine any brief, run the recommended next workflow. To re-analyze with different scope, run analyze-source again."
 
+### 9. Workflow Health Check
+
+Load and execute `{nextStepFile}` for workflow self-improvement check.
+
 ---
 
 ## 🚨 SYSTEM SUCCESS/FAILURE METRICS

package/src/workflows/audit-skill/steps-c/step-06-report.md

@@ -3,6 +3,7 @@ name: 'step-06-report'
 description: 'Finalize drift report with audit summary, remediation suggestions, and provenance metadata'
 
 outputFile: '{forge_version}/drift-report-{timestamp}.md'
+nextStepFile: '../../shared/health-check.md'
 ---
 
 # Step 6: Generate Report
@@ -31,7 +32,7 @@ Finalize the drift report by completing the Audit Summary with calculated metric
 - 🎯 Focus on completing the report — summary, remediation, provenance
 - 🚫 FORBIDDEN to discover new drift items or reclassify severity
 - 💬 Remediation suggestions must be practical: what to change, where, and why
-- 📋 This is the FINAL step — no nextStepFile
+- 📋 Chains to shared health check via `{nextStepFile}` — no further steps after that
 
 ## EXECUTION PROTOCOLS:
 
@@ -189,6 +190,10 @@ Update {outputFile} frontmatter:
 
 **Audit workflow complete.**"
 
+### Workflow Health Check
+
+Load and execute `{nextStepFile}` for workflow self-improvement check.
+
 ---
 
 ## 🚨 SYSTEM SUCCESS/FAILURE METRICS

package/src/workflows/brief-skill/steps-c/step-05-write-brief.md

@@ -3,6 +3,7 @@ name: 'step-05-write-brief'
 description: 'Generate and write skill-brief.yaml to the forge data folder'
 
 briefSchemaFile: '../data/skill-brief-schema.md'
+nextStepFile: '../../shared/health-check.md'
 ---
 
 # Step 5: Write Brief
@@ -216,13 +217,13 @@ After compilation, you can:
 
 **Brief-skill workflow complete.**"
 
-### 7. End Workflow
+### 7. Workflow Health Check
 
-This is the final step. No next step file to load. The workflow is complete.
+Load and execute `{nextStepFile}` for workflow self-improvement check.
 
 ## CRITICAL STEP COMPLETION NOTE
 
-This is the FINAL step of the brief-skill workflow. After writing the file and displaying the success summary, the workflow ends.
+This step chains to the shared health check. After the health check completes, the brief-skill workflow is fully done.
 
 ---
 

package/src/workflows/create-skill/steps-c/step-08-report.md

@@ -1,6 +1,7 @@
 ---
 name: 'step-08-report'
 description: 'Display compilation summary with confidence tiers, suggest next steps'
+nextStepFile: '../../shared/health-check.md'
 ---
 
 # Step 8: Report
@@ -137,17 +138,19 @@ Set `batch_active: false` in `{sidecar_path}/batch-state.yaml` to prevent stale
 
 End workflow. No further steps.
 
-### 6. Workflow Complete
+### 6. Workflow Health Check
 
-This is the final step. No `{nextStepFile}` to load.
+**If not batch mode (or all batch briefs complete):**
 
-Display: "Forge session complete. Return to Ferris menu for further actions."
+Load and execute `{nextStepFile}` for workflow self-improvement check.
+
+**If batch mode with remaining briefs:** Skip health check — loop back to step-01 for the next brief. Health check runs after the final brief in the batch.
 
 ## CRITICAL STEP COMPLETION NOTE
 
-This is the FINAL STEP of the create-skill workflow. After displaying the compilation report and next steps, the workflow is complete. No further steps are loaded.
+This step chains to the shared health check (unless batch mode loops back to step-01). After the health check completes, the create-skill workflow is fully done.
 
-For batch mode: loop back to step-01 for remaining briefs via sidecar checkpoint.
+For batch mode: loop back to step-01 for remaining briefs via sidecar checkpoint. Health check runs only after the last brief.
 
 ---
 

package/src/workflows/create-stack-skill/steps-c/step-09-report.md

@@ -1,6 +1,7 @@
 ---
 name: 'step-09-report'
 description: 'Display final stack skill summary with confidence distribution and next workflow recommendations'
+nextStepFile: '../../shared/health-check.md'
 ---
 
 # Step 9: Stack Skill Report
@@ -25,7 +26,7 @@ Display the final summary of the forged stack skill with confidence distribution
 
 ### Step-Specific Rules:
 
-- 🎯 This is the FINAL step — no nextStepFile
+- 🎯 Chains to shared health check via `{nextStepFile}` — no further steps after that
 - 🚫 FORBIDDEN to write or modify any files — report is console output only
 - 💬 Lead with the positive summary, then details, then warnings if any
 - 🎯 Recommend next workflows based on what was produced
@@ -119,6 +120,10 @@ Forge tier: **{tier}**"
 
 **Workflow complete.**"
 
+### 7. Workflow Health Check
+
+Load and execute `{nextStepFile}` for workflow self-improvement check.
+
 ---
 
 ## 🚨 SYSTEM SUCCESS/FAILURE METRICS

package/src/workflows/drop-skill/steps-c/step-03-report.md

@@ -1,6 +1,7 @@
 ---
 name: 'step-03-report'
 description: 'Report drop operation results'
+nextStepFile: '../../shared/health-check.md'
 ---
 
 # Step 3: Report Drop Results
@@ -100,13 +101,13 @@ restore the managed section entry.
 These require manual review — see the error-handling guidance in step-02.
 ```
 
-### 3. Close the Workflow
+### 3. Workflow Health Check
 
-After rendering the report, the workflow is complete. Do not load any further step file — there is no `nextStepFile`.
+Load and execute `{nextStepFile}` for workflow self-improvement check.
 
 ## CRITICAL STEP COMPLETION NOTE
 
-This is the final step. Once the report has been rendered, the drop-skill workflow is finished. Do not re-run any earlier step automatically — if the user wants another drop, they should re-invoke the workflow from the top.
+This step chains to the shared health check. After the health check completes, the drop-skill workflow is fully done. Do not re-run any earlier step automatically — if the user wants another drop, they should re-invoke the workflow from the top.
 
 ---
 

package/src/workflows/export-skill/steps-c/step-06-summary.md

@@ -1,6 +1,7 @@
 ---
 name: 'step-06-summary'
 description: 'Display export summary with distribution instructions'
+nextStepFile: '../../shared/health-check.md'
 ---
 
 # Step 6: Summary
@@ -130,7 +131,9 @@ npx skills add {resolved_skill_package}
 
 Replace `{resolved_skill_package}` with the absolute path to the package folder shown above (from step-02), e.g. `{skills_output_folder}/{skill-name}/{version}/{skill-name}/`.
 
-For other source formats (registry name, git URL, tarball, etc.), see the **Installation → Source Formats** section at <https://www.npmjs.com/package/skills>."
+For other source formats (registry name, git URL, tarball, etc.), see the **Installation → Source Formats** section at <https://www.npmjs.com/package/skills>.
+
+If the installed skill's commands are not available in the same IDE session, reload plugins (e.g. for Claude Code users, run `/reload-plugins`) or restart your AI editor. Next time you will see the command `/{skill-name}` (e.g. `/{skill-name}`)."
 
 ### 4. Dry Run Reminder (If Applicable)
 
@@ -156,9 +159,13 @@ No files were written. To run the export for real:
 
 **Skill forged and delivered.** ⚒️"
 
+### 7. Workflow Health Check
+
+Load and execute `{nextStepFile}` for workflow self-improvement check.
+
 ## CRITICAL STEP COMPLETION NOTE
 
-This is the final step. The workflow is complete. No further steps to load.
+This step chains to the shared health check. After the health check completes, the export-skill workflow is fully done.
 
 ---
 
@@ -170,6 +177,7 @@ This is the final step. The workflow is complete. No further steps to load.
 - Token counts included from step-05
 - Distribution instructions appropriate for source_authority
 - Local install command (`npx skills add {resolved_skill_package}`) displayed with npmjs.com/package/skills link for alternate source formats
+- Plugin reload hint shown (reload plugins or restart AI editor to see `/{skill-name}`)
 - Dry-run correctly indicated (if applicable)
 - Recommended next workflows listed
 - Clear workflow completion signal

package/src/workflows/quick-skill/steps-c/step-06-write.md

@@ -1,6 +1,7 @@
 ---
 name: 'step-06-write'
 description: 'Write output files to skills folder and display completion summary'
+nextStepFile: '../../shared/health-check.md'
 ---
 
 # Step 6: Write Output
@@ -37,14 +38,14 @@ To write the compiled SKILL.md, context-snippet.md, and metadata.json to the ski
 - 🎯 Follow the MANDATORY SEQUENCE exactly
 - 💾 Write three files to `{skill_package}` and create the `active` symlink
 - 📖 File I/O required for directory creation and file writing
-- 🚫 This is the final step — no next step to load
+- 🚫 After writing files, chains to shared health check — no further steps after that
 
 ## CONTEXT BOUNDARIES:
 
 - Previous steps provided: skill_content, context_snippet, metadata_json, validation_result
 - Also available: resolved_url, repo_name, language, skills_output_folder
 - Focus: file writing and completion only
-- This is the FINAL step — workflow ends here
+- Chains to shared health check after completion — no further steps after that
 - Path resolution: See `knowledge/version-paths.md` for canonical path templates. Quick-skill uses `{repo_name}` as the skill name and defaults `{version}` to `1.0.0` if not detected from the extraction inventory
 
 ## MANDATORY SEQUENCE
@@ -150,11 +151,9 @@ Please check:
 
 **Note:** This is a best-effort community skill. For deeper analysis with AST-verified exports and provenance tracking, use the full **create-skill** workflow with a skill brief."
 
-### 7. End Workflow
+### 7. Workflow Health Check
 
-This is the final step. The workflow is complete.
-
-No next step to load. Session ends here.
+Load and execute `{nextStepFile}` for workflow self-improvement check.
 
 ---
 
@@ -174,6 +173,6 @@ No next step to load. Session ends here.
 - Modifying content during write (write exactly what was compiled)
 - Not handling write failures with hard halt
 - Not displaying completion summary
-- Attempting to load a next step (this is final)
+- Attempting to load steps beyond the shared health check
 
 **Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.

package/src/workflows/refine-architecture/steps-c/step-06-report.md

@@ -3,13 +3,14 @@ name: 'step-06-report'
 description: 'Present refinement summary to user with counts, next steps, and review options'
 
 outputFile: '{output_folder}/refined-architecture-{project_name}.md'
+nextStepFile: '../../shared/health-check.md'
 ---
 
 # Step 6: Present Report
 
 ## STEP GOAL:
 
-Present the complete refinement summary to the user. Display counts of gaps filled, issues flagged, and improvements suggested. Provide the output file path and recommend next steps. Offer the user options to review changes in detail or exit. This is the FINAL step — no nextStepFile.
+Present the complete refinement summary to the user. Display counts of gaps filled, issues flagged, and improvements suggested. Provide the output file path and recommend next steps. Offer the user options to review changes in detail or exit. Chains to the shared health check on exit.
 
 ## MANDATORY EXECUTION RULES (READ FIRST):
 
@@ -30,7 +31,7 @@ Present the complete refinement summary to the user. Display counts of gaps fill
 - 🎯 Focus ONLY on presenting the completed refinement — no new analysis
 - 🚫 FORBIDDEN to discover new gaps, issues, or improvements
 - 🚫 FORBIDDEN to modify the refined document — only read and present
-- 📋 This is the FINAL step — no nextStepFile
+- 📋 Chains to shared health check via `{nextStepFile}` — no further steps after that
 
 ## EXECUTION PROTOCOLS:
 
@@ -110,15 +111,17 @@ Re-run **[RA] Refine Architecture** anytime after updating your skills or archit
 
 **Architecture refinement complete.**"
 
+  Then load and execute `{nextStepFile}` for workflow self-improvement check.
+
 #### EXECUTION RULES:
 
 - ALWAYS halt and wait for user input after presenting the menu
 - R may be selected multiple times — always walk through all refinements
-- X ends the workflow
+- X triggers the health check, which is the true workflow exit
 
 ## CRITICAL STEP COMPLETION NOTE
 
-This is the final step of the refine-architecture workflow. When the user selects X, the workflow is complete. The refined architecture at `{outputFile}` contains the full original content plus all gap-fills, issue annotations, and improvement suggestions backed by skill API evidence.
+When the user selects X, this step chains to the shared health check. After the health check completes, the refine-architecture workflow is fully done. The refined architecture at `{outputFile}` contains the full original content plus all gap-fills, issue annotations, and improvement suggestions backed by skill API evidence.
 
 ---
 

package/src/workflows/rename-skill/steps-c/step-03-report.md

@@ -1,6 +1,7 @@
 ---
 name: 'step-03-report'
 description: 'Report rename operation results'
+nextStepFile: '../../shared/health-check.md'
 ---
 
 # Step 3: Report Rename Results
@@ -98,13 +99,13 @@ Informational: the old name still appears in SKILL.md body text (prose only, non
   - If this skill was published to agentskills.io under `{old_name}`, the registry version is unchanged — this rename is a LOCAL operation only
 ```
 
-### 2. Close the Workflow
+### 2. Workflow Health Check
 
-After rendering the report, the workflow is complete. Do not load any further step file — there is no `nextStepFile`.
+Load and execute `{nextStepFile}` for workflow self-improvement check.
 
 ## CRITICAL STEP COMPLETION NOTE
 
-This is the final step. Once the report has been rendered, the rename-skill workflow is finished. Do not re-run any earlier step automatically — if the user wants another rename, they should re-invoke the workflow from the top.
+This step chains to the shared health check. After the health check completes, the rename-skill workflow is fully done. Do not re-run any earlier step automatically — if the user wants another rename, they should re-invoke the workflow from the top.
 
 ---
 

package/src/workflows/setup-forge/steps-c/step-04-report.md

@@ -3,6 +3,7 @@ name: 'step-04-report'
 description: 'Display forge status report with positive capability framing'
 
 tierRulesData: '../data/tier-rules.md'
+nextStepFile: '../../shared/health-check.md'
 ---
 
 # Step 4: Forge Status Report
@@ -37,7 +38,7 @@ Display the forge status report with positive capability framing, report tier ch
 - 🎯 Follow the MANDATORY SEQUENCE exactly
 - 💾 Load tier-rules.md for capability descriptions and re-run messages
 - 📖 Use context from step-01 (detected_tools, calculated_tier, previous_tier)
-- 🚫 This is the final step — no next step to load
+- 🚫 After reporting, chains to shared health check — no further steps after that
 
 ## CONTEXT BOUNDARIES:
 
@@ -126,11 +127,13 @@ Load and read {tierRulesData} for the tier capability descriptions and re-run me
 **If `--update-spec` was NOT passed:**
 - Skip silently
 
-### 4. Workflow Complete
+### 4. Workflow Health Check
 
-This is the final step. The setup-forge workflow is now complete.
+Load and execute `{nextStepFile}` for workflow self-improvement check.
 
-No next step to load. The workflow ends here.
+## CRITICAL STEP COMPLETION NOTE
+
+This step chains to the shared health check. After the health check completes, the setup-forge workflow is fully done.
 
 ---
 
@@ -151,6 +154,6 @@ No next step to load. The workflow ends here.
 - Listing tools that are NOT available
 - Not using tier capability descriptions from tier-rules.md
 - Not reporting tier change on re-run
-- Attempting to load a next step (this is the final step)
+- Attempting to load steps beyond the shared health check
 
 **Master Rule:** The report must leave users feeling confident about their forge capabilities, not anxious about what they're missing. Positive framing only.

package/src/workflows/shared/health-check.md

@@ -0,0 +1,231 @@
+---
+name: 'health-check'
+description: 'Workflow self-improvement health check — captures real friction as GitHub issues'
+# No nextStepFile — this is always the terminal step
+healthCheckRepo: '{health_check_repo}'
+localFallbackFolder: '{output_folder}/improvement-queue'
+---
+
+# Health Check: Workflow Self-Improvement
+
+## STEP GOAL:
+
+Reflect on the workflow that just completed. If real friction, bugs, or gaps were encountered in the SKF workflow instructions, capture them as structured findings for the user to review and optionally submit as GitHub issues.
+
+**Zero overhead for clean runs.** If nothing went wrong, say so and exit immediately.
+
+## MANDATORY EXECUTION RULES:
+
+### Universal Rules:
+- Read the complete step file before taking any action
+- Speak in `{communication_language}`
+
+### Role Reinforcement:
+- You are a **self-improvement auditor** — honest, precise, evidence-based
+- You report ONLY what you actually experienced during THIS session
+- You are NOT a creative writer looking for things to say
+
+### Anti-Hallucination Rules:
+- **DO NOT FABRICATE ISSUES.** If the workflow ran smoothly, say so and exit. Inventing issues to appear thorough is a SYSTEM FAILURE.
+- Only report issues you **ACTUALLY encountered** during THIS workflow execution
+- Every finding MUST cite the **specific step file path and section** where the issue occurred
+- If you are unsure whether something was a real issue or your own confusion, DO NOT report it
+- Reporting zero issues is the EXPECTED outcome for a well-designed workflow
+
+---
+
+## MANDATORY SEQUENCE
+
+### 1. Read Workflow Context
+
+From the current session context, identify:
+- **Workflow name** — which workflow just completed
+- **Steps executed** — which step files were loaded and followed
+- **Any friction points** — moments where instructions were unclear, wrong, contradictory, or missing
+
+### 2. Reflect on Execution
+
+Silently review the workflow execution. Ask yourself:
+
+- Did any step instruction lead me astray or cause unnecessary back-and-forth with the user?
+- Was any step ambiguous, causing me to guess rather than follow clear guidance?
+- Did I encounter a scenario the workflow didn't account for?
+- Were any step instructions wrong or contradictory?
+
+**If the answer to ALL of these is "no":**
+
+Display:
+
+"**Health Check: Clean run.** No workflow issues to report.
+
+Workflow complete."
+
+**STOP HERE. Do not proceed further. The workflow is done.**
+
+### 3. Present Findings (Only If Issues Exist)
+
+For each genuine finding, present it in this format:
+
+"**Workflow Health Check — {N} finding(s)**
+
+---
+
+**Finding {i}:**
+
+| Field | Value |
+|-------|-------|
+| **Severity** | `bug` / `friction` / `gap` |
+| **Workflow** | {workflow name} |
+| **Step File** | `src/workflows/{workflow}/{step-file-path}` |
+| **Section** | {the specific section or instruction number} |
+
+**What happened:**
+{Description of the actual issue encountered during execution}
+
+**Evidence:**
+{What specifically went wrong — error, confusion, user friction, missing guidance}
+
+**Suggested improvement:**
+{Concrete, actionable change to the step file or data}
+
+---"
+
+**Severity definitions:**
+- **`bug`** — Step instructions were wrong or contradictory
+- **`friction`** — Step worked but was unclear, ambiguous, or caused unnecessary back-and-forth
+- **`gap`** — A scenario arose that the workflow didn't account for at all
+
+### 4. User Review Gate
+
+After presenting all findings, ask:
+
+"**Submit these findings?**
+
+- **[Y]** Yes — submit all findings
+- **[N]** No — discard all findings
+- **[E]** Edit — let me revise before submitting
+
+_You are the final filter. Reject any finding that doesn't reflect a real issue you observed._"
+
+**HALT and wait for user input.**
+
+#### Menu Handling:
+
+- **IF Y:** Proceed to step 5
+- **IF N:** Display "Findings discarded. Workflow complete." — STOP
+- **IF E:** Let user specify which findings to keep, modify, or remove. Then re-present the revised list and ask again.
+
+### 5. Submit Findings
+
+**Check GitHub CLI availability:**
+
+Run `gh auth status` to determine if the `gh` CLI is authenticated.
+
+#### IF `gh` is available:
+
+For each confirmed finding, create a GitHub issue:
+
+**Command:**
+```
+gh issue create \
+  --repo {healthCheckRepo} \
+  --title "[health-check] [{severity}] {workflow}: {short description}" \
+  --label "health-check,workflow-improvement,{severity}" \
+  --body "{formatted body using issue template structure}"
+```
+
+**Issue body format:**
+```markdown
+## Workflow
+{workflow name}
+
+## Step File
+`{exact step file path relative to src/}`
+
+## Severity
+{bug | friction | gap}
+
+## Finding
+{description of what went wrong}
+
+## Evidence
+{what actually happened during execution}
+
+## Suggested Improvement
+{concrete change to improve the workflow}
+
+## Environment
+- **Date:** {date}
+- **OS:** {detected OS, e.g. macOS 15.2, Ubuntu 24.04, Windows 11}
+- **AI Editor:** {the AI editor or CLI being used, e.g. Claude Code, Cursor, Windsurf}
+- **Model:** {the model executing this workflow, e.g. Claude Opus 4.6, Claude Sonnet 4.6}
+- **Forge Tier:** {if available from sidecar, otherwise "N/A"}
+- **SKF Version:** {read from {project-root}/_bmad/skf/VERSION, otherwise "N/A"}
+```
+
+After creating all issues, display:
+
+"**{N} issue(s) created on {healthCheckRepo}:**
+{list each issue URL}
+
+Workflow complete."
+
+#### IF `gh` is NOT available:
+
+For each confirmed finding, write a local file to `{localFallbackFolder}/`:
+
+**Filename:** `hc-{workflow}-{timestamp}.md` (one file per finding, timestamp as YYYYMMDD-HHmmss)
+
+**File content:** Same structured format as the issue body above, with YAML frontmatter:
+
+```yaml
+---
+type: workflow-health-finding
+workflow: {workflow name}
+step_file: {step file path}
+severity: {bug | friction | gap}
+date: {ISO date}
+---
+```
+
+After writing all files, display:
+
+"**{N} finding(s) saved locally:**
+{list each file path}
+
+GitHub CLI is not available. To submit these as issues, run:
+`gh issue create --repo {healthCheckRepo} --title \"[title]\" --body-file {file-path}`
+
+Or open them manually at: <https://github.com/{healthCheckRepo}/issues/new/choose>
+
+Workflow complete."
+
+---
+
+## CRITICAL STEP COMPLETION NOTE
+
+This is the TERMINAL step — shared across all SKF workflows. After the health check completes (clean run or findings submitted/discarded), the workflow is fully done. No further steps to load.
+
+---
+
+## SYSTEM SUCCESS/FAILURE METRICS
+
+### SUCCESS:
+
+- Clean runs exit immediately with no findings (most common outcome)
+- Findings cite specific step files and sections with real evidence
+- User review gate presented before any submission
+- GitHub issues created with correct labels and structured body (when `gh` available)
+- Local fallback files written with clear manual submission instructions (when `gh` unavailable)
+- Workflow ends cleanly
+
+### SYSTEM FAILURE:
+
+- Fabricating issues that were not actually encountered during the session
+- Reporting vague issues without step file citations ("the workflow was confusing")
+- Skipping the user review gate
+- Creating issues without user confirmation
+- Not providing the local fallback when `gh` is unavailable
+- Continuing to load steps after this one (this is terminal)
+
+**Master Rule:** Honesty is the only policy. Zero findings is the expected, healthy outcome. Fabricating issues to appear thorough undermines the entire self-improvement system and constitutes SYSTEM FAILURE.

package/src/workflows/test-skill/steps-c/step-06-report.md

@@ -1,4 +1,5 @@
 ---
+nextStepFile: '../../shared/health-check.md'
 name: 'step-06-report'
 description: 'Generate gap report with remediation suggestions and finalize test report'
 
@@ -166,18 +167,18 @@ Display: "**Test complete.** [C] Finish"
 
 #### Menu Handling Logic:
 
-- IF C: Workflow is complete. No further steps to load.
+- IF C: Load and execute `{nextStepFile}` for workflow self-improvement check.
 - IF Any other: help user respond, then redisplay menu
 
 #### EXECUTION RULES:
 
 - ALWAYS halt and wait for user input after presenting menu
-- This is the final step — C ends the workflow
+- C triggers the health check, which is the true workflow exit
 - User may ask questions about the report before finishing
 
 ## CRITICAL STEP COMPLETION NOTE
 
-This is the final step of the test-skill workflow. When the user selects C, the workflow is complete. The test report document at `{outputFile}` contains the full analysis: Test Summary, Coverage Analysis, Coherence Analysis, Completeness Score, and Gap Report.
+When the user selects C, this step chains to the shared health check. After the health check completes, the test-skill workflow is fully done. The test report document at `{outputFile}` contains the full analysis: Test Summary, Coverage Analysis, Coherence Analysis, Completeness Score, and Gap Report.
 
 ---
 

package/src/workflows/update-skill/steps-c/step-07-report.md

@@ -1,6 +1,7 @@
 ---
 name: 'step-07-report'
 description: 'Display comprehensive change summary with diff visualization and workflow chaining recommendations'
+nextStepFile: '../../shared/health-check.md'
 ---
 
 # Step 7: Report
@@ -36,7 +37,7 @@ Present a comprehensive change summary showing what was updated, [MANUAL] sectio
 
 - 🎯 Follow MANDATORY SEQUENCE exactly
 - 💾 No file writes — display only
-- 📖 This is the final step — workflow completes here
+- 📖 Chains to shared health check via `{nextStepFile}` — no further steps after that
 
 ## CONTEXT BOUNDARIES:
 
@@ -64,7 +65,7 @@ Source code matches provenance map exactly. The skill `{skill_name}` is current
 
 **Recommendation:** No action required. Run audit-skill periodically to monitor for drift."
 
-→ **Workflow complete.** End here.
+→ Load and execute `{nextStepFile}` for workflow self-improvement check.
 
 ### 2. Present Change Summary
 
@@ -175,7 +176,9 @@ Based on the update results:"
 
 **Update-skill workflow complete for `{skill_name}`.**"
 
-→ **No next step.** Workflow ends here.
+### 7. Workflow Health Check
+
+Load and execute `{nextStepFile}` for workflow self-improvement check.
 
 ---
 

package/src/workflows/verify-stack/steps-c/step-06-report.md

@@ -3,6 +3,7 @@ name: 'step-06-report'
 description: 'Present the final feasibility report to the user with verdict, findings, and next steps'
 
 outputFile: '{forge_data_folder}/feasibility-report-{project_name}.md'
+nextStepFile: '../../shared/health-check.md'
 ---
 
 # Step 6: Present Report
@@ -30,7 +31,7 @@ Present the complete feasibility report to the user. Display the overall verdict
 - 🎯 Focus ONLY on presenting the completed report — no new analysis
 - 🚫 FORBIDDEN to discover new findings, re-analyze skills, or change verdicts
 - 🚫 FORBIDDEN to modify the report content — only read and present
-- 📋 This is the FINAL step — no nextStepFile
+- 📋 Chains to shared health check via `{nextStepFile}` — no further steps after that
 
 ## EXECUTION PROTOCOLS:
 
@@ -160,15 +161,17 @@ Re-run **[VS] Verify Stack** anytime after making changes to your skills or arch
 
 **Verification workflow complete.**"
 
+  Then load and execute `{nextStepFile}` for workflow self-improvement check.
+
 #### EXECUTION RULES:
 
 - ALWAYS halt and wait for user input after presenting the menu
 - R may be selected multiple times — always walk through the full report
-- X ends the workflow
+- X triggers the health check, which is the true workflow exit
 
 ## CRITICAL STEP COMPLETION NOTE
 
-This is the final step of the verify-stack workflow. When the user selects X, the workflow is complete. The feasibility report at `{outputFile}` contains the full analysis: Coverage Matrix, Integration Verdicts, Requirements Coverage, and Synthesis & Recommendations.
+When the user selects X, this step chains to the shared health check. After the health check completes, the verify-stack workflow is fully done. The feasibility report at `{outputFile}` contains the full analysis: Coverage Matrix, Integration Verdicts, Requirements Coverage, and Synthesis & Recommendations.
 
 ---
 

package/tools/cli/lib/compiler.js

@@ -195,7 +195,7 @@ ${agentSteps}    <step n="${menuStep}">Show greeting using {user_name} from conf
     <rules>
       <r>ALWAYS communicate in {communication_language} UNLESS contradicted by communication_style.</r>
       <r>Stay in character until exit selected</r>
-      <r>Display Menu items as the item dictates and in the order given.</r>
+      <r>Display Menu items as the item dictates and in the order given. Always end the menu with: "Run each workflow in a fresh context window for best results."</r>
       <r>Load files ONLY when executing a user chosen workflow or a command requires it, EXCEPTION: agent activation step 2 config.yaml</r>
     </rules>