bmad-module-skill-forge 0.10.0 → 1.0.0-rc.3

package/src/knowledge/qmd-registry.md

@@ -6,7 +6,7 @@ QMD collections in the Skill Forge follow a **progressive registry architecture*
 
 ## Rationale
 
-Early SKF versions used a blind auto-index strategy: setup-forge would scan all project directories and index them into QMD collections. This created three problems:
+Early SKF versions used a blind auto-index strategy: setup would scan all project directories and index them into QMD collections. This created three problems:
 
 - On fresh workspaces, auto-indexing found nothing — wasted work
 - Raw source code indexing produced low signal-to-noise search results
@@ -22,7 +22,7 @@ The progressive registry solves all three by indexing **curated workflow artifac
 | --- | --- | --- |
 | **Producer** | brief-skill, create-skill | Creates QMD collections from workflow artifacts and registers them in forge-tier.yaml |
 | **Consumer** | audit-skill, update-skill, create-stack-skill | Reads the registry, discovers collections by skill name and type, queries via qmd_bridge (see [tool-resolution.md](tool-resolution.md) for concrete resolution) |
-| **Janitor** | setup-forge | Cross-references live QMD collections against the registry, cleans orphans and stale entries |
+| **Janitor** | setup | Cross-references live QMD collections against the registry, cleans orphans and stale entries |
 
 ### Registry Schema
 
@@ -45,7 +45,7 @@ qmd_collections:
 
 **Optional field: `status`**
 
-The `status` field is only present when QMD embed verification fails during collection creation. When `status: "pending"` is set, the collection exists in QMD but vector embeddings may be incomplete — only BM25 keyword `search` is reliable. `vector_search` and `deep_search` may return no results until re-embedded. Collections without a `status` field are fully operational. The setup-forge janitor should flag `"pending"` collections for re-embedding.
+The `status` field is only present when QMD embed verification fails during collection creation. When `status: "pending"` is set, the collection exists in QMD but vector embeddings may be incomplete — only BM25 keyword `search` is reliable. `vector_search` and `deep_search` may return no results until re-embedded. Collections without a `status` field are fully operational. The setup janitor should flag `"pending"` collections for re-embedding.
 
 ### Collection Types
 
@@ -70,7 +70,7 @@ create-skill compiles skill → indexes {name}-extraction → registers in forge
 audit-skill reads registry → queries {name}-extraction for drift baseline
 update-skill reads registry → queries {name}-extraction for T2 enrichment
     ↓
-setup-forge reads registry + QMD state → cleans orphans, removes stale entries
+setup reads registry + QMD state → cleans orphans, removes stale entries
 ```
 
 ## Collection Gate
@@ -111,8 +111,8 @@ The `ccc_index_registry` array in forge-tier.yaml is a **parallel but separate**
 |--------|----------------|-------------------|
 | **What is indexed** | Curated workflow artifacts (SKILL.md, briefs, temporal data) | Source code (the actual codebase) |
 | **Index engine** | QMD (BM25 + optional vector search) | cocoindex-code (AST + vector embeddings) |
-| **Lifecycle** | Per-skill: created by create-skill, consumed by audit/update-skill | Per-project: created by setup-forge, verified by create-skill |
-| **Janitor** | setup-forge step-03 (orphan/stale QMD collection cleanup) | setup-forge step-03 section 5b (stale path cleanup) |
+| **Lifecycle** | Per-skill: created by create-skill, consumed by audit/update-skill | Per-project: created by setup, verified by create-skill |
+| **Janitor** | setup step-03 (orphan/stale QMD collection cleanup) | setup step-03 section 5b (stale path cleanup) |
 | **Availability** | Deep tier only | Forge+ and Deep tiers |
 
 These registries are orthogonal — they never reference each other, and their janitor sections operate independently.
@@ -139,7 +139,7 @@ Then append/replace the registry entry in forge-tier.yaml. Failures never block
 
 **Implementation:** Read `qmd_collections` from forge-tier.yaml. Find entry where `skill_name` matches AND `type` is `"extraction"`. If found, query via qmd_bridge. If not found, log and continue without T2 enrichment — not an error.
 
-### Example 3: Janitor Hygiene (setup-forge)
+### Example 3: Janitor Hygiene (setup)
 
 **Context:** Setup-forge verifies QMD health on every run.
 
@@ -151,4 +151,4 @@ Then append/replace the registry entry in forge-tier.yaml. Failures never block
 - [skill-lifecycle.md](skill-lifecycle.md) — end-to-end pipeline showing where producers and consumers sit
 - [provenance-tracking.md](provenance-tracking.md) — provenance map that provides file:line context without QMD
 
-_Source: progressive QMD registry architecture implemented across setup-forge, brief-skill, create-skill, audit-skill, and update-skill workflows_
+_Source: progressive QMD registry architecture implemented across setup, brief-skill, create-skill, audit-skill, and update-skill workflows_

package/src/knowledge/skf-knowledge-index.csv

@@ -1,11 +1,11 @@
 id,name,description,tags,tier,fragment_file
-overview,Knowledge Overview,"Entry point — knowledge map, JiT loading protocol, relationship to workflow data/ files","knowledge,navigation,jit-loading",core,knowledge/overview.md
+overview,Knowledge Overview,"Entry point — knowledge map, JiT loading protocol, relationship to workflow references/ and assets/ files","knowledge,navigation,jit-loading",core,knowledge/overview.md
 zero-hallucination,Zero Hallucination Principle,"Foundational principle — uncitable content is excluded not guessed, every claim traces to source","integrity,provenance,extraction",core,knowledge/zero-hallucination.md
 confidence-tiers,Confidence Tiers,"Trust model — T1/T1-low/T2/T3 labels, citation formats, tier interaction rules","confidence,citations,evidence,tiers",core,knowledge/confidence-tiers.md
 progressive-capability,Progressive Capability,"Quick/Forge/Forge+/Deep philosophy — every tier is legitimate, positive framing, graceful degradation","tiers,quick,forge,forge+,deep,capability",core,knowledge/progressive-capability.md
 ccc-bridge,CCC Bridge,"cocoindex-code semantic discovery — ccc_bridge interface, indexing lifecycle, Forge+ tier, discovery-before-extraction principle","ccc,cocoindex,semantic,discovery,forge+,bridge",core,knowledge/ccc-bridge.md
 agentskills-spec,agentskills.io Specification,"Format principles — frontmatter, progressive disclosure, directory structure, compliance rules, MCP tool naming, script quality, development methodology","agentskills,format,compliance,output,mcp,scripts,methodology",core,knowledge/agentskills-spec.md
-skill-lifecycle,Skill Lifecycle,"End-to-end pipeline — workflow connections, artifact flow, decision rules for workflow selection","lifecycle,pipeline,workflows,artifacts",core,knowledge/skill-lifecycle.md
+skill-lifecycle,Skill Lifecycle,"End-to-end pipeline — workflow connections, artifact flow, decision rules for workflow selection, pipeline invocation syntax and aliases","lifecycle,pipeline,workflows,artifacts,chaining,headless",core,knowledge/skill-lifecycle.md
 provenance-tracking,Provenance Tracking,"Provenance mechanism — provenance-map.json entries and file_entries, evidence reports, claim traceability","provenance,evidence,traceability,citations,file-entries",core,knowledge/provenance-tracking.md
 manual-section-integrity,Manual Section Integrity,"[MANUAL] preservation — marker format, merge algorithm, orphan detection","manual,preservation,merge,markers",core,knowledge/manual-section-integrity.md
 qmd-registry,QMD Collection Registry,"Progressive registry architecture — producer/consumer/janitor roles, collection gate principle, forge-tier.yaml registry schema","qmd,registry,collections,deep,indexing",core,knowledge/qmd-registry.md

package/src/knowledge/skill-lifecycle.md

@@ -167,6 +167,21 @@ SS (compose) → SKILL.md (stack skill synthesized from individual skills + arch
 - SS detects integration patterns (e.g., "express + passport always used together for auth routes")
 - Individual skills track per-library provenance; stack skills track inter-library relationships
 
+## Pipeline Invocation
+
+Users can chain workflows by providing multiple codes to Ferris:
+
+```
+BS CS TS EX           — space-separated
+forge                 — alias for BS CS TS EX
+forge-quick           — alias for QS TS EX
+onboard               — alias for AN CS TS EX
+maintain              — alias for AS US TS EX
+CS[cocoindex] TS[min:80] EX  — with arguments and circuit breakers
+```
+
+Pipelines automatically activate headless mode. The forger passes data between workflows using the artifact flow described above. Circuit breakers halt the pipeline when output quality falls below a threshold (e.g., TS score < 60 blocks EX). See `shared/references/pipeline-contracts.md` for the full specification.
+
 ## Integration Points
 
 - **Setup Forge** must run before any other workflow — it establishes the tier
@@ -183,4 +198,4 @@ SS (compose) → SKILL.md (stack skill synthesized from individual skills + arch
 - [provenance-tracking.md](provenance-tracking.md) — how provenance flows through the pipeline
 - [version-paths.md](version-paths.md) — version-aware storage layout, path templates, and migration rules
 
-_Source: synthesized from all 12 workflow.md files (including VS, RA) and module-help.csv_
+_Source: synthesized from all 14 SKILL.md files (including VS, RA, RS, DS) and module-help.csv_

package/src/knowledge/split-body-strategy.md

@@ -50,6 +50,6 @@ Split-body affects only SKILL.md content movement to `references/`. The `scripts
 
 - [agentskills-spec.md](agentskills-spec.md) — 500-line guideline for SKILL.md body size and the `references/` directory structure
 - [skill-lifecycle.md](skill-lifecycle.md) — where split-body decisions fit in the compilation pipeline
-- `test-skill/data/scoring-rules.md` — tessl/split-body interaction and the pre-split baseline recommendation during test reporting
+- `test-skill/references/scoring-rules.md` — tessl/split-body interaction and the pre-split baseline recommendation during test reporting
 
 _Source: derived from agentskills.io split-body guidance and Vercel agent accuracy research (inline vs on-demand retrieval)_

package/src/knowledge/version-paths.md

@@ -35,16 +35,21 @@ All workflows MUST use these templates when constructing paths. Never hardcode p
 | `{forge_version}` | `{forge_data_folder}/{skill-name}/{version}/` | Version-specific workspace artifacts — provenance-map.json, evidence-report.md, extraction-rules.yaml, test-report |
 | `{forge_group}` | `{forge_data_folder}/{skill-name}/` | Parent directory — contains skill-brief.yaml (version-independent) and version subdirectories |
 
-### Platform Paths (Unchanged — Flat)
+### IDE Skill Root Paths (Unchanged — Flat)
 
-| Platform | Root Path |
-|----------|-----------|
-| `claude` | `.claude/skills/{skill-name}/` |
+Each IDE has its own skill root path derived from its `target_dir` in `platform-codes.yaml`. The snippet `root:` line uses this path. Examples:
+
+| IDE | Root Path |
+|-----|-----------|
+| `claude-code` | `.claude/skills/{skill-name}/` |
 | `cursor` | `.cursor/skills/{skill-name}/` |
-| `copilot` | `.agents/skills/{skill-name}/` |
-| _(legacy)_ | `skills/{skill-name}/` |
+| `github-copilot` | `.github/skills/{skill-name}/` |
+| `windsurf` | `.windsurf/skills/{skill-name}/` |
+| _(draft/legacy)_ | `skills/{skill-name}/` |
+
+See `skf-export-skill/assets/managed-section-format.md` for the complete IDE → Context File Mapping table with all 23 IDE root paths.
 
-Platform paths are **not versioned**. The export workflow resolves the active version from the manifest and references its `{skill_package}` when building the managed section. The snippet `root:` always uses the flat platform path.
+IDE skill root paths are **not versioned**. The export workflow resolves the active version from the manifest and references its `{skill_package}` when building the managed section. The snippet `root:` always uses the flat IDE skill root path.
 
 ## Directory Structure
 
@@ -139,12 +144,12 @@ The export manifest gains version awareness:
       "active_version": "0.6.0",
       "versions": {
         "0.5.0": {
-          "platforms": ["claude"],
+          "ides": ["claude-code"],
           "last_exported": "2026-03-15",
           "status": "archived"
         },
         "0.6.0": {
-          "platforms": ["claude", "copilot"],
+          "ides": ["claude-code", "github-copilot"],
           "last_exported": "2026-04-04",
           "status": "active"
         }
@@ -158,7 +163,7 @@ The export manifest gains version awareness:
 - `schema_version`: `"2"` — enables v1-to-v2 migration detection
 - `active_version`: The version whose `{skill_package}` supplies the context snippet for the managed section. Must match exactly one version with `status: "active"`
 - `versions.{v}.status`: `"active"` (currently exported), `"archived"` (previously exported, retained on disk), `"deprecated"` (dropped via drop-skill workflow, excluded from all exports), `"draft"` (created but never exported)
-- `versions.{v}.platforms`: Array of platforms this version was last exported to
+- `versions.{v}.ides`: Array of IDE identifiers from `config.yaml.ides` whose context file this version was last exported to (e.g. `["claude-code", "cursor"]`). NOT context file names, NOT skill root paths — the canonical IDE identifier used by the installer. Pre-rename manifests used `platforms` for this field; `skf-manifest-ops.py` silently upgrades them on read
 - `versions.{v}.last_exported`: ISO date of the last export
 
 **Only one version per skill can have `status: "active"` at any time.**
@@ -180,7 +185,7 @@ Renames a skill across all versions. Because the agentskills.io spec requires `n
 8. Export manifest: remove old key, add new key with same version data
 9. Platform context files (CLAUDE.md, AGENTS.md, .cursorrules): rebuild managed sections
 
-Rename is transactional — copy-verify-delete pattern. If any step fails, old skill remains intact. See `workflows/rename-skill/`.
+Rename is transactional — copy-verify-delete pattern. If any step fails, old skill remains intact. See `skf-rename-skill/`.
 
 ### Drop (DS - Drop Skill)
 
@@ -194,7 +199,7 @@ Drops a specific version or the entire skill with two modes:
 
 **Skill-level drop:** Removes the entire `{skill_group}` from the manifest. If purge, also deletes `{skill_group}` and `{forge_group}` directories.
 
-See `workflows/drop-skill/`.
+See `skf-drop-skill/`.
 
 ## Version Sanitization
 

package/src/module-help.csv

@@ -1,17 +1,18 @@
-module,phase,name,code,sequence,workflow-file,command,required,agent,options,description,output-location,outputs,
-skf,anytime,Setup Forge,SF,,_bmad/skf/workflows/skillforge/setup-forge/workflow.md,skf_setup_forge,false,ferris,Create Mode,"Initialize forge environment — detect tools and set capability tier (Quick/Forge/Forge+/Deep)",,forge-tier.yaml,
-skf,anytime,Analyze Source,AN,,_bmad/skf/workflows/skillforge/analyze-source/workflow.md,skf_analyze_source,false,ferris,Create Mode,"Discover what to skill in a large repo — produces recommended skill briefs",forge_data_folder,skill-brief.yaml,
-skf,anytime,Brief Skill,BS,,_bmad/skf/workflows/skillforge/brief-skill/workflow.md,skf_brief_skill,false,ferris,Create Mode,"Design a skill scope through guided discovery",forge_data_folder,skill-brief.yaml,
-skf,anytime,Create Skill,CS,,_bmad/skf/workflows/skillforge/create-skill/workflow.md,skf_create_skill,false,ferris,Create Mode,"Compile a skill from a brief — supports --batch for multiple briefs",skills_output_folder,SKILL.md,
-skf,anytime,Quick Skill,QS,,_bmad/skf/workflows/skillforge/quick-skill/workflow.md,skf_quick_skill,false,ferris,Create Mode,"Fast skill from a package name or GitHub URL — no brief needed",skills_output_folder,SKILL.md,
-skf,anytime,Stack Skill,SS,,_bmad/skf/workflows/skillforge/create-stack-skill/workflow.md,skf_create_stack_skill,false,ferris,Create Mode,"Consolidated project stack skill with integration patterns — code-mode (analyzes manifests) or compose-mode (synthesizes from existing skills + architecture doc)",skills_output_folder,SKILL.md,
-skf,anytime,Update Skill,US,,_bmad/skf/workflows/skillforge/update-skill/workflow.md,skf_update_skill,false,ferris,Surgeon Mode,"Smart regeneration preserving [MANUAL] sections after source changes",skills_output_folder,SKILL.md,
-skf,anytime,Audit Skill,AS,,_bmad/skf/workflows/skillforge/audit-skill/workflow.md,skf_audit_skill,false,ferris,Audit Mode,"Drift detection between skill and current source code",,"drift report",
-skf,anytime,Test Skill,TS,,_bmad/skf/workflows/skillforge/test-skill/workflow.md,skf_test_skill,false,ferris,Audit Mode,"Cognitive completeness verification — quality gate before export",,"completeness score",
-skf,anytime,Export Skill,EX,,_bmad/skf/workflows/skillforge/export-skill/workflow.md,skf_export_skill,false,ferris,Delivery Mode,"Package for distribution and inject context into CLAUDE.md/AGENTS.md/.cursorrules",skills_output_folder,"agentskills.io package",
-skf,anytime,Rename Skill,RS,,_bmad/skf/workflows/skillforge/rename-skill/workflow.md,skf_rename_skill,false,ferris,Management Mode,"Rename a skill across all its versions — transactional copy-verify-delete with platform context rebuild",skills_output_folder,"renamed skill group",
-skf,anytime,Drop Skill,DS,,_bmad/skf/workflows/skillforge/drop-skill/workflow.md,skf_drop_skill,false,ferris,Management Mode,"Drop a specific skill version or an entire skill — soft (deprecate) or hard (purge) with platform context rebuild",skills_output_folder,"updated manifest",
-skf,anytime,Verify Stack,VS,,_bmad/skf/workflows/skillforge/verify-stack/workflow.md,skf_verify_stack,false,ferris,Audit Mode,"Pre-code stack feasibility verification against architecture and PRD documents",forge_data_folder,"feasibility-report-{project_name}.md",
-skf,anytime,Refine Architecture,RA,,_bmad/skf/workflows/skillforge/refine-architecture/workflow.md,skf_refine_architecture,false,ferris,Architect Mode,"Improve architecture doc using verified skill data and VS feasibility findings",output_folder,"refined-architecture-{project_name}.md",
-skf,anytime,Workflow Status,WS,,,skf_workflow_status,false,ferris,Reference,"Show current lifecycle position, active skill briefs, and forge tier status",,lifecycle status,
-skf,anytime,Knowledge Index,KI,,_bmad/skf/knowledge/skf-knowledge-index.csv,skf_knowledge_index,false,ferris,Reference,"Cross-cutting principles and patterns — JiT loaded by workflows via index lookup",,"knowledge fragments",
+module,skill,display-name,menu-code,description,action,args,phase,after,before,required,output-location,outputs
+skf,skf-forger,Ferris — Skill Forge Agent,FF,"Skill compilation specialist — the forge master. Invoke to access all SKF workflows via guided menu.",,,anytime,,,false,,
+skf,skf-setup,Setup Forge,SF,"Initialize forge environment — detect tools and set capability tier (Quick/Forge/Forge+/Deep)",,,anytime,,"skf-analyze-source,skf-brief-skill,skf-quick-skill,skf-verify-stack",false,,forge-tier.yaml
+skf,skf-analyze-source,Analyze Source,AN,"Discover what to skill in a large repo — produces recommended skill briefs",,,anytime,skf-setup,skf-brief-skill,false,forge_data_folder,skill-brief.yaml
+skf,skf-brief-skill,Brief Skill,BS,"Design a skill scope through guided discovery",,,anytime,"skf-setup,skf-analyze-source",skf-create-skill,false,forge_data_folder,skill-brief.yaml
+skf,skf-create-skill,Create Skill,CS,"Compile a skill from a brief — supports --batch for multiple briefs",,--batch,anytime,skf-brief-skill,"skf-test-skill,skf-create-stack-skill",false,skills_output_folder,SKILL.md
+skf,skf-quick-skill,Quick Skill,QS,"Fast skill from a package name or GitHub URL — no brief needed",,<package-name | github-url>,anytime,skf-setup,skf-test-skill,false,skills_output_folder,SKILL.md
+skf,skf-create-stack-skill,Stack Skill,SS,"Consolidated project stack skill with integration patterns — code-mode or compose-mode",,,anytime,skf-create-skill,skf-test-skill,false,skills_output_folder,SKILL.md
+skf,skf-update-skill,Update Skill,US,"Smart regeneration preserving [MANUAL] sections after source changes",,,anytime,skf-export-skill,,false,skills_output_folder,SKILL.md
+skf,skf-audit-skill,Audit Skill,AS,"Drift detection between skill and current source code",,,anytime,skf-export-skill,,false,,drift report
+skf,skf-verify-stack,Verify Stack,VS,"Pre-code stack feasibility verification against architecture and PRD documents",,,anytime,skf-setup,skf-refine-architecture,false,forge_data_folder,feasibility-report-{project_name}.md
+skf,skf-refine-architecture,Refine Architecture,RA,"Improve architecture doc using verified skill data and VS feasibility findings",,,anytime,skf-verify-stack,,false,output_folder,refined-architecture-{project_name}.md
+skf,skf-test-skill,Test Skill,TS,"Cognitive completeness verification — quality gate before export",,,anytime,"skf-create-skill,skf-create-stack-skill,skf-quick-skill",skf-export-skill,false,,completeness score
+skf,skf-export-skill,Export Skill,EX,"Package for distribution and inject context into CLAUDE.md/AGENTS.md/.cursorrules",,,anytime,skf-test-skill,"skf-update-skill,skf-audit-skill,skf-rename-skill,skf-drop-skill",false,skills_output_folder,agentskills.io package
+skf,skf-rename-skill,Rename Skill,RS,"Rename a skill across all its versions — transactional copy-verify-delete with platform context rebuild",,,anytime,skf-export-skill,,false,skills_output_folder,renamed skill group
+skf,skf-drop-skill,Drop Skill,DS,"Drop a specific skill version or an entire skill — soft (deprecate) or hard (purge) with platform context rebuild",,,anytime,skf-export-skill,,false,skills_output_folder,updated manifest
+skf,skf-forger,Knowledge Index,KI,"Cross-cutting principles and patterns — JiT loaded by workflows via index lookup",,,anytime,,,false,,knowledge fragments
+skf,skf-forger,Workflow Status,WS,"Show current lifecycle position, active skill briefs, and forge tier status",,,anytime,,,false,,lifecycle status

package/src/shared/health-check.md

@@ -0,0 +1,372 @@
+---
+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'
+seenCachePath: '$HOME/.skf/health-check-seen.json'
+liveSubmitSeverities: ['bug']  # friction/gap go local-queue-default with explicit opt-in
+---
+
+# Health Check: Workflow Self-Improvement
+
+> **Path convention:** This file is referenced as `shared/health-check.md` from workflow step frontmatter. All `shared/` paths resolve relative to the SKF module root (`_bmad/skf/` when installed, `src/` during development), not relative to the calling step file.
+
+## 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
+
+### 0. Announce Arrival
+
+**Display in `{communication_language}`:**
+
+"**Running a quick self-improvement check on this workflow.** If nothing rough came up, I'll close out immediately."
+
+**GATE [default: skip]** — If `{headless_mode}`: skip the display entirely, log: "headless: skipped health-check arrival announcement".
+
+**If interactive:** display the line above, then proceed to step 1 (Read Workflow Context) without waiting. The line is informational, not a commitment gate — the user's commitment to continuing was already captured upstream (either via an explicit menu in the calling step or by auto-chain). This announcement just tells them what is about to happen.
+
+### 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/skf-{workflow}/steps-c/{step-file-path}` |
+| **Section** | {the specific section or instruction number — use a stable section heading slug, not line numbers} |
+| **Fingerprint** | `fp-{7-hex}` — first 7 hex chars of `sha1("{severity}|{workflow}|{step_file}|{section-slug}")` |
+
+**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. Route Each Finding by Severity
+
+Before any submission, route each confirmed finding by severity:
+
+- **`bug`** → live-submit path (step 5a below). High signal, priority for maintainers.
+- **`friction`** / **`gap`** → local-queue by default (step 5c below). These are the most subjective categories and produce the most near-duplicates. Ask the user once per session: *"Also submit the {N} friction/gap finding(s) as GitHub issues? \[y/N]"* — only if the user affirms explicitly, route them through 5a.
+
+### 5a. Live-Submit Path: Compute Fingerprint and Dedup
+
+For each finding routed to live-submit:
+
+**1. Compute the fingerprint** — a deterministic 7-hex dedup key:
+
+```
+fp="fp-$(printf '%s|%s|%s|%s' "{severity}" "{workflow}" "{step_file}" "{section-slug}" | sha1sum | cut -c1-7)"
+```
+
+The `section-slug` is a kebab-case normalized section heading (e.g. `missing-staging-path`). Never include line numbers — they drift when files are edited.
+
+**2. Check the local seen-cache** at `{seenCachePath}`:
+
+If the cache exists and already contains this fingerprint for this user, skip submission silently and log: `"fp-{hash}: already submitted from this machine on {date}, issue {url} — skipping"`. This prevents the same user from re-reporting the same defect across sessions.
+
+**3. Check GitHub CLI availability** with `gh auth status`. If `gh` is unavailable, fall through to step 5c (local fallback).
+
+**4. Remote dedup search** — one deterministic call:
+
+```
+gh search issues --repo {healthCheckRepo} --state open "{fp} in:title" --json number,url,title --limit 1
+```
+
+**5a-i. If a matching open issue exists:**
+
+Present to user:
+
+> "**Matching report found:** #{N} — {title}
+>
+> Your finding has the same fingerprint `{fp}`. Options:
+> - **\[R]** React (👍) on the existing issue — silent upvote, adds no comment
+> - **\[C]** React + comment with YOUR environment/evidence delta (use only if it materially differs from the original)
+> - **\[N]** Create a new issue anyway — only if you're certain this is a distinct defect
+> - **\[S]** Skip — don't submit this finding"
+
+Execute the chosen action:
+
+- **R:** `gh api -X POST /repos/{repo}/issues/{N}/reactions -f content='+1'`
+- **C:** Same reaction call, then `gh issue comment {N} --body "{minimal env+delta body}"`. The delta body is the Environment table plus ONE sentence describing what's different from the original. No session narrative.
+- **N:** Proceed to step 5a-ii.
+- **S:** Record nothing.
+
+Record the outcome to the seen-cache under the fingerprint with fields `{action, issue_url, date}`.
+
+**5a-ii. If no matching open issue exists** — create a new issue:
+
+For each confirmed finding, create a GitHub issue:
+
+**First, ensure the `{fp}` label exists** — it is per-fingerprint, so the first reporter of any defect is always creating a brand-new label. `gh issue create --label fp-XXXX` hard-fails if the label is missing, so guard it:
+
+```
+gh label create "{fp}" --repo {healthCheckRepo} \
+  --color "ededed" \
+  --description "Health-check fingerprint dedup key" 2>/dev/null || true
+```
+
+The `|| true` makes this idempotent: if the label already exists (second reporter of the same defect whose prior issue was closed, racing a parallel submission, etc.), `gh label create` exits non-zero and we proceed unharmed. The other labels in the command below (`health-check`, `workflow-improvement`, `bug`/`friction`/`gap`) are pre-created repo labels and do not need this guard.
+
+**Then create the issue:**
+```
+gh issue create \
+  --repo {healthCheckRepo} \
+  --title "[health-check][{severity}][{fp}] {workflow}: {short description}" \
+  --label "health-check,workflow-improvement,{severity},{fp}" \
+  --body "{formatted body using issue template structure}"
+```
+
+The fingerprint `{fp}` appears in both title (human-readable) and label (server-side filterable). Maintainers can query all reports for a defect via the `fp-*` label without relying on title text.
+
+After the issue is created, write the fingerprint → issue-url mapping to the seen-cache at `{seenCachePath}` so this user never re-reports the same fingerprint.
+
+**Writing rules — non-negotiable:**
+
+- **One issue per finding.** If you observed two independent problems, submit two issues.
+- **Respect the length budgets.** Finding, Expected, Actual, Impact are each ONE sentence. Evidence is 2-5 bullets, not prose. Suggested Fix is 1-3 sentences with ONE recommendation — multiple options go in the `Alternatives considered` collapsible or (better) not at all.
+- **Quote, don't paraphrase.** In Evidence, cite the exact `file:line` and put the quoted text in quotes. Link the convention to the instruction that caused it.
+- **Never narrate the session.** The reader wants the defect, not the story. If a sentence starts with "During my run..." or "I was trying to...", delete it.
+- **If unsure whether it's a real issue, do not submit it.** Reporting zero findings is a healthy outcome.
+
+**Issue body format:**
+```markdown
+## Workflow
+{workflow name, e.g. `skf-create-skill`}
+
+## Step File
+`src/skf-{workflow}/steps-c/step-NN-name.md`
+
+## Severity
+`{bug | friction | gap}`
+<!-- bug: instructions were wrong or contradictory -->
+<!-- friction: instructions worked but caused back-and-forth or guessing -->
+<!-- gap: a scenario arose that wasn't covered at all -->
+
+## Fingerprint
+`{fp}`
+<!-- Deterministic dedup key: sha1(severity|workflow|step_file|section-slug)[:7]. -->
+<!-- Also applied as a label so maintainers can filter all variants server-side. -->
+
+## Finding
+<!-- ONE sentence. What is the problem? Do not explain why yet. -->
+{e.g. Step-05 forbids writes to `skills/` but does not name a staging directory.}
+
+## Expected
+<!-- ONE sentence. What did the step instruct or imply should happen? -->
+{e.g. The step should name the staging directory between assembly and final write.}
+
+## Actual
+<!-- ONE sentence. What did you observe instead? -->
+{e.g. No staging path specified, so artifacts were written to `skills/{name}/` and step-07 had to reorganize them.}
+
+## Evidence
+<!-- Bulleted `file:line` citations. 2-5 bullets. No narrative prose. -->
+- `path/to/file.md:17` — "quoted text from the file"
+- `path/to/other.md:62` — brief note on what it shows
+
+## Impact
+<!-- ONE sentence. What did this cost in THIS session? -->
+{e.g. 50KB of artifacts written to the wrong path; step-07 required a file-move pass.}
+
+## Suggested Fix
+<!-- ONE recommended change. 1-3 sentences. Do NOT list multiple options here. -->
+{e.g. Add a rule to step-05 naming `_bmad-output/{skill-name}/` as the staging directory used by step-06 validation.}
+
+<details>
+<summary>Alternatives considered (optional)</summary>
+
+<!-- Only fill this if you seriously considered 2+ approaches. Keep under 100 words total. -->
+
+</details>
+
+## Environment
+| Field | Value |
+|-------|-------|
+| Date | {ISO date} |
+| OS | {e.g. macOS 15.2, Ubuntu 24.04, Windows 11} |
+| AI Editor | {e.g. Claude Code, Cursor, Windsurf} |
+| Model | {e.g. Claude Opus 4.6, Claude Sonnet 4.6} |
+| Forge Tier | {Quick/Forge/Forge+/Deep, else N/A} |
+| SKF Version | {from `{project-root}/_bmad/skf/VERSION`, else N/A} |
+```
+
+After creating all issues, display:
+
+"**{N} issue(s) created on {healthCheckRepo}:**
+{list each issue URL}
+
+Workflow complete."
+
+### 5b. On success, update the seen-cache
+
+After each successful `gh issue create`, append to `{seenCachePath}`:
+
+```json
+{
+  "fp-XXXXXXX": {
+    "issue_url": "https://github.com/.../issues/123",
+    "action": "created",
+    "date": "YYYY-MM-DD"
+  }
+}
+```
+
+Ensure the parent directory exists. This file is global across the user's machine — not per-project — so the same defect is never re-reported across different repos the user works in.
+
+### 5c. Local-Queue Path (gh unavailable OR friction/gap default)
+
+For findings that didn't go live (gh unavailable, user declined the friction/gap opt-in, or user chose **\[S]** at the dedup gate), 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}
+fingerprint: {fp-XXXXXXX}
+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
+- Severity gate respected: only `bug` submits live by default; `friction`/`gap` require explicit opt-in
+- Fingerprint computed deterministically and applied to both title prefix and `fp-*` label
+- `fp-*` label is ensured idempotently (`gh label create ... || true`) before `gh issue create`, so a first reporter of a defect never hard-fails
+- Remote dedup search performed before every live submission; existing issues get reactions/delta-comments rather than duplicates
+- Seen-cache at `{seenCachePath}` updated after every submission/reaction and consulted before every search
+- 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
+- Creating a new issue when a matching `fp-*` open issue already exists (without explicit user \[N] override)
+- Submitting `friction` or `gap` findings live without the explicit severity-gate opt-in
+- Using LLM-judged "similarity" in place of the deterministic fingerprint
+- Not updating the seen-cache, causing the same user to re-report identical fingerprints
+- 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.