bmad-module-skill-forge 0.9.0 → 0.10.1-alpha.0

package/src/{workflows/refine-architecture → skf-refine-architecture}/steps-c/step-02-gap-analysis.md

@@ -1,9 +1,6 @@
 ---
-name: 'step-02-gap-analysis'
-description: 'Find undocumented integration paths that the architecture does not describe but skill APIs suggest'
-
 nextStepFile: './step-03-issue-detection.md'
-refinementRulesData: '../data/refinement-rules.md'
+refinementRulesData: 'references/refinement-rules.md'
 ---
 
 # Step 2: Gap Analysis
@@ -12,42 +9,10 @@ refinementRulesData: '../data/refinement-rules.md'
 
 Find undocumented integration paths — library pairs that have compatible APIs (from the generated skills) but are not described in the architecture document. For each gap, document what APIs connect and propose an architecture section describing the integration.
 
-## MANDATORY EXECUTION RULES (READ FIRST):
-
-### Universal Rules:
-
-- 📖 CRITICAL: Read the complete step file before taking any action
-- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read
-- ⚙️ TOOL/SUBPROCESS FALLBACK: If any instruction references a subprocess, subagent, or tool you do not have access to, you MUST still achieve the outcome in your main context thread
-- ✅ YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`
-
-### Role Reinforcement:
-
-- ✅ You are an architecture refinement analyst performing gap detection
-- ✅ Every gap must cite specific APIs from the generated skills — no speculation
-- ✅ Apply the gap detection rules from {refinementRulesData} strictly
-
-### Step-Specific Rules:
+## Rules
 
-- 🎯 Focus ONLY on undocumented integration paths (gaps)
-- 🚫 FORBIDDEN to detect contradictions or issues — that is Step 03
-- 🚫 FORBIDDEN to suggest capability expansions or improvements — that is Step 04
-- 💬 Every gap MUST include evidence citations from actual skill content
-
-## EXECUTION PROTOCOLS:
-
-- Load refinement rules for gap detection criteria
-- Extract integration claims from architecture document using prose co-mention analysis
-- Generate all possible library pairs and cross-reference against architecture
-- Append gap analysis findings as workflow state for Step 05
-- Only gap detection — no issue detection, no improvement suggestions
-
-## CONTEXT BOUNDARIES:
-
-- Available: Architecture document content, skill inventory from Step 01, SKILL.md and metadata.json files, refinement rules
-- Focus: Finding library pairs with compatible APIs that the architecture does not describe
-- Limits: Only detect gaps — do not flag issues or suggest improvements
-- Dependencies: Step 01 must have loaded skill inventory and validated architecture document
+- Focus only on undocumented integration paths (gaps) — do not detect contradictions (Step 03) or suggest expansions (Step 04)
+- Every gap must include evidence citations from actual skill content
 
 ## MANDATORY SEQUENCE
 
@@ -85,15 +50,33 @@ For N skills, this produces N*(N-1)/2 unique pairs.
 
 ### 4. Load Skill API Surfaces for Cross-Reference
 
-For each library in the skill inventory, load the skill artifacts:
+<!-- Subagent delegation: read SKILL.md files in parallel, return compact JSON -->
+
+For each library in the skill inventory, delegate reading to a parallel subagent. Launch up to **8 subagents concurrently** (batch larger inventories in rounds of 8).
 
-**From SKILL.md, extract:**
-- Exported functions and their signatures
-- Exported types, interfaces, and classes
-- Protocol indicators (HTTP, gRPC, WebSocket, message queue, file I/O, IPC)
-- Data format indicators (JSON, protobuf, CSV, binary, streaming)
+**Each subagent receives one skill's SKILL.md path and MUST:**
+1. Read the SKILL.md file
+2. Extract the API surface
+3. ONLY return this compact JSON — no prose, no extra commentary:
 
-**From metadata.json, extract:**
+```json
+{
+  "skill_name": "...",
+  "exports": ["functionName(params): ReturnType", "..."],
+  "protocols": ["HTTP", "gRPC", "WebSocket", "message queue", "file I/O", "IPC"],
+  "data_formats": ["JSON", "protobuf", "CSV", "binary", "streaming"]
+}
+```
+
+**Extraction rules for subagents:**
+- `exports`: exported functions with signatures, exported types/interfaces/classes
+- `protocols`: any protocol indicators found in the SKILL.md
+- `data_formats`: any data format indicators found in the SKILL.md
+- If a field has no matches, return an empty array `[]`
+
+**Parent collects all subagent JSON summaries.** Do not load full SKILL.md content into parent context.
+
+**From metadata.json (read in parent — lightweight), also extract:**
 - `language` — primary programming language
 - `exports` — export count and names
 
@@ -152,28 +135,3 @@ Store all gap findings as workflow state for Step 05. To ensure durability acros
 
 Load, read the full file and then execute `{nextStepFile}`.
 
----
-
-## 🚨 SYSTEM SUCCESS/FAILURE METRICS
-
-### ✅ SUCCESS:
-
-- Refinement rules loaded from {refinementRulesData}
-- Integration claims extracted from architecture document using prose co-mention analysis
-- All possible library pairs generated from skill inventory
-- Skill API surfaces loaded for cross-reference
-- Each gap includes evidence citations from actual skill content
-- Gap analysis results displayed with count and details
-- Gap findings stored as workflow state for Step 05
-- Auto-proceeded to step 03
-
-### ❌ SYSTEM FAILURE:
-
-- Inventing APIs not present in the actual skills
-- Flagging contradictions or issues (that is Step 03)
-- Suggesting capability improvements (that is Step 04)
-- Gaps without evidence citations from generated skills
-- Parsing Mermaid diagrams instead of using prose-based co-mention analysis
-- Hardcoded paths instead of frontmatter variables
-
-**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.

package/src/{workflows/refine-architecture → skf-refine-architecture}/steps-c/step-03-issue-detection.md

@@ -1,9 +1,6 @@
 ---
-name: 'step-03-issue-detection'
-description: 'Find contradictions between architecture claims and verified API reality from skills and optional VS report'
-
 nextStepFile: './step-04-improvements.md'
-refinementRulesData: '../data/refinement-rules.md'
+refinementRulesData: 'references/refinement-rules.md'
 ---
 
 # Step 3: Issue Detection
@@ -12,43 +9,11 @@ refinementRulesData: '../data/refinement-rules.md'
 
 Find contradictions between what the architecture document claims and what the generated skills reveal about actual API surfaces. Detect language boundary issues not addressed, protocol mismatches assumed away, and missing bridge layers. If a VS feasibility report is available, incorporate RISKY and BLOCKED verdicts as confirmed issues.
 
-## MANDATORY EXECUTION RULES (READ FIRST):
-
-### Universal Rules:
-
-- 📖 CRITICAL: Read the complete step file before taking any action
-- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read
-- ⚙️ TOOL/SUBPROCESS FALLBACK: If any instruction references a subprocess, subagent, or tool you do not have access to, you MUST still achieve the outcome in your main context thread
-- ✅ YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`
-
-### Role Reinforcement:
-
-- ✅ You are an architecture refinement analyst performing contradiction detection
-- ✅ Every issue must cite evidence from actual skill content AND the architecture claim it contradicts
-- ✅ Apply the issue detection rules from {refinementRulesData} strictly
-
-### Step-Specific Rules:
-
-- 🎯 Focus ONLY on contradictions between architecture claims and skill API reality
-- 🚫 FORBIDDEN to detect undocumented integration paths — that was Step 02
-- 🚫 FORBIDDEN to suggest capability expansions — that is Step 04
-- 💬 Every issue MUST cite both the architecture claim AND the contradicting skill evidence
-
-## EXECUTION PROTOCOLS:
-
-- Load refinement rules for issue detection criteria
-- Extract all integration claims from the architecture document
-- Verify each claim against skill API surfaces
-- Incorporate VS report verdicts if available
-- Append issue findings as workflow state for Step 05
-- Only issue detection — no gap analysis, no improvement suggestions
+## Rules
 
-## CONTEXT BOUNDARIES:
-
-- Available: Architecture document content, skill inventory and SKILL.md files, VS feasibility report (if provided), refinement rules
-- Focus: Finding contradictions between documented claims and verified API reality
-- Limits: Only detect issues — do not fill gaps or suggest improvements
-- Dependencies: Step 01 (skill inventory, architecture doc, VS report status), Step 02 (gap analysis complete)
+- Focus only on contradictions between architecture claims and skill API reality
+- Do not detect gaps (Step 02) or suggest expansions (Step 04)
+- Every issue must cite both the architecture claim and the contradicting skill evidence
 
 ## MANDATORY SEQUENCE
 
@@ -155,28 +120,3 @@ Store all issue findings as workflow state for Step 05. To ensure durability acr
 
 Load, read the full file and then execute `{nextStepFile}`.
 
----
-
-## 🚨 SYSTEM SUCCESS/FAILURE METRICS
-
-### ✅ SUCCESS:
-
-- Refinement rules loaded from {refinementRulesData}
-- All integration claims extracted from architecture document
-- Each claim verified against actual skill API surfaces
-- VS report verdicts incorporated if report was provided
-- Every issue includes both architecture citation AND contradicting skill evidence
-- Issues classified by severity (Critical, Major, Minor)
-- Issue detection results displayed with count and details
-- Issue findings stored as workflow state for Step 05
-- Auto-proceeded to step 04
-
-### ❌ SYSTEM FAILURE:
-
-- Issues without evidence from actual skills (speculation)
-- Not citing the architecture claim that is contradicted
-- Filling gaps (that was Step 02) or suggesting improvements (that is Step 04)
-- Ignoring VS report verdicts when the report was provided
-- Hardcoded paths instead of frontmatter variables
-
-**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.

package/src/{workflows/refine-architecture → skf-refine-architecture}/steps-c/step-04-improvements.md

@@ -1,9 +1,6 @@
 ---
-name: 'step-04-improvements'
-description: 'Suggest capability expansions from skill data not leveraged in the architecture'
-
 nextStepFile: './step-05-compile.md'
-refinementRulesData: '../data/refinement-rules.md'
+refinementRulesData: 'references/refinement-rules.md'
 ---
 
 # Step 4: Improvement Detection
@@ -12,42 +9,11 @@ refinementRulesData: '../data/refinement-rules.md'
 
 Identify capability expansions — library features documented in the generated skills that the architecture does not leverage. Detect unused capabilities, cross-library synergies visible from skill API surfaces, and alternative patterns that could strengthen the architecture. For each improvement, document the capability and suggest how to incorporate it.
 
-## MANDATORY EXECUTION RULES (READ FIRST):
-
-### Universal Rules:
-
-- 📖 CRITICAL: Read the complete step file before taking any action
-- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read
-- ⚙️ TOOL/SUBPROCESS FALLBACK: If any instruction references a subprocess, subagent, or tool you do not have access to, you MUST still achieve the outcome in your main context thread
-- ✅ YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`
-
-### Role Reinforcement:
-
-- ✅ You are an architecture refinement analyst identifying untapped capabilities
-- ✅ Every improvement must cite specific APIs from the generated skills — no speculation
-- ✅ Improvements are suggestions, not mandates — present them as optional enhancements
-
-### Step-Specific Rules:
-
-- 🎯 Focus ONLY on capability expansions not leveraged in the architecture
-- 🚫 FORBIDDEN to detect gaps (Step 02) or issues (Step 03) — those are already captured
-- 🎯 Improvements are ADDITIVE suggestions — they enhance, not contradict, the architecture
-- 💬 Every improvement MUST include evidence citations from actual skill content
-
-## EXECUTION PROTOCOLS:
-
-- Load refinement rules for improvement detection criteria
-- Compare full skill API surfaces against architecture usage
-- Detect unused capabilities, cross-library synergies, and alternative patterns
-- Append improvement findings as workflow state for Step 05
-- Only improvement detection — no gap or issue analysis
+## Rules
 
-## CONTEXT BOUNDARIES:
-
-- Available: Architecture document content, skill inventory and SKILL.md files, refinement rules
-- Focus: Finding capabilities in skills that the architecture does not use
-- Limits: Only detect improvements — do not re-detect gaps or issues from earlier steps
-- Dependencies: Step 01 (skill inventory), Steps 02-03 (complete — do not duplicate findings)
+- Focus only on capability expansions not leveraged in the architecture — do not repeat gaps (Step 02) or issues (Step 03)
+- Improvements are additive suggestions — they enhance, not contradict, the architecture
+- Every improvement must include evidence citations from actual skill content
 
 ## MANDATORY SEQUENCE
 
@@ -142,28 +108,3 @@ Store all improvement findings as workflow state for Step 05. To ensure durabili
 
 Load, read the full file and then execute `{nextStepFile}`.
 
----
-
-## 🚨 SYSTEM SUCCESS/FAILURE METRICS
-
-### ✅ SUCCESS:
-
-- Refinement rules loaded from {refinementRulesData}
-- Architecture usage map built for each referenced library
-- Full skill API surfaces compared against architecture usage
-- Cross-library synergies checked for complementary capabilities
-- Every improvement includes evidence citations from actual skill content
-- Improvements categorized by value (High, Medium, Low)
-- Improvement results displayed with count and details
-- Improvement findings stored as workflow state for Step 05
-- Auto-proceeded to step 05
-
-### ❌ SYSTEM FAILURE:
-
-- Improvements without evidence from actual skills (speculation)
-- Re-detecting gaps (Step 02) or issues (Step 03)
-- Presenting trivial internal-only exports as improvements
-- Not categorizing improvements by value
-- Hardcoded paths instead of frontmatter variables
-
-**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.

package/src/{workflows/refine-architecture → skf-refine-architecture}/steps-c/step-05-compile.md

@@ -1,7 +1,4 @@
 ---
-name: 'step-05-compile'
-description: 'Produce the refined architecture document by annotating the original with gaps, issues, and improvements'
-
 nextStepFile: './step-06-report.md'
 outputFile: '{output_folder}/refined-architecture-{project_name}.md'
 ---
@@ -12,35 +9,11 @@ outputFile: '{output_folder}/refined-architecture-{project_name}.md'
 
 Produce the refined architecture document by starting with the original as a base, adding gap-fill subsections, issue callout blocks, and improvement suggestions. Append a Refinement Summary. Present for user review before finalizing.
 
-## MANDATORY EXECUTION RULES (READ FIRST):
-
-### Universal Rules:
-
-- 📖 CRITICAL: Read the complete step file before taking any action
-- ⚙️ TOOL/SUBPROCESS FALLBACK: If any instruction references a subprocess, subagent, or tool you do not have access to, you MUST still achieve the outcome in your main context thread
-- ✅ YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`
-
-### Role Reinforcement:
-
-- ✅ You are an architecture refinement analyst compiling the final refined document
-- ✅ Additive, not destructive — preserve every word of the original, only add refinements
-- ✅ The document must be in `{document_output_language}`
-
-### Step-Specific Rules:
-
-- 🚫 FORBIDDEN to discover new gaps, issues, or improvements — use only what Steps 02-04 produced
-- 🚫 FORBIDDEN to delete, reword, or rearrange original architecture content
-- 💬 Present compiled document for user review (Gate checkpoint)
-
-## EXECUTION PROTOCOLS:
-
-- Compile refined architecture from original + findings from Steps 02-04
-- Write output to {outputFile}, wait for user approval before proceeding
+## Rules
 
-## CONTEXT BOUNDARIES:
-
-- From Steps 01-04: Architecture document, skill inventory, gap/issue/improvement findings
-- This step produces: The refined architecture document at {outputFile}
+- Do not discover new gaps, issues, or improvements — use only what Steps 02-04 produced
+- Do not delete, reword, or rearrange original architecture content
+- Present compiled document for user review (gate checkpoint)
 
 ## MANDATORY SEQUENCE
 
@@ -166,6 +139,7 @@ Display: **Select:** [C] Continue to Final Report
 #### EXECUTION RULES:
 
 - ALWAYS halt and wait for user input after presenting compilation
+- **GATE [default: C]** — If `{headless_mode}`: auto-proceed with [C] Continue, log: "headless: auto-approve compiled architecture"
 - ONLY proceed to next step when user approves and selects 'C'
 
 #### Menu Handling Logic:
@@ -173,28 +147,3 @@ Display: **Select:** [C] Continue to Final Report
 - IF C: Load, read entire file, then execute {nextStepFile}
 - IF Any other: Process as feedback, adjust specific refinements in the document, rewrite {outputFile}, redisplay preview, then [Redisplay Menu Options](#8-present-menu-options)
 
----
-
-## 🚨 SYSTEM SUCCESS/FAILURE METRICS
-
-### ✅ SUCCESS:
-
-- Original architecture document preserved in full without modifications
-- Gap-fill subsections inserted at logical locations with evidence citations
-- Issue callout blocks inserted adjacent to contradicted claims with severity
-- Improvement suggestions inserted with value ratings and evidence
-- Refinement Summary section appended with accurate counts
-- Refined document written to {outputFile}
-- User reviewed and approved compilation
-- Proceeded to step 06 only after user selected C
-
-### ❌ SYSTEM FAILURE:
-
-- Deleting, rewording, or rearranging original architecture content
-- Discovering new findings not from Steps 02-04
-- Inserting refinements without evidence citations
-- Proceeding without user review (Gate checkpoint)
-- Not writing the document to {outputFile} before presenting for review
-- Hardcoded paths instead of frontmatter variables
-
-**Master Rule:** Additive only. Preserve the original. Get user approval before proceeding.

package/src/{workflows/refine-architecture → skf-refine-architecture}/steps-c/step-06-report.md

@@ -1,50 +1,19 @@
 ---
-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: './step-07-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.
-
-## MANDATORY EXECUTION RULES (READ FIRST):
-
-### Universal Rules:
-
-- 📖 CRITICAL: Read the complete step file before taking any action
-- ⚙️ TOOL/SUBPROCESS FALLBACK: If any instruction references a subprocess, subagent, or tool you do not have access to, you MUST still achieve the outcome in your main context thread
-- ✅ YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`
-
-### Role Reinforcement:
-
-- ✅ You are an architecture refinement analyst delivering the final summary
-- ✅ Present findings clearly and concisely — the user needs to decide which refinements to keep
-- ✅ Next step recommendations must be specific and actionable
-
-### Step-Specific Rules:
-
-- 🎯 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
-
-## EXECUTION PROTOCOLS:
-
-- Load and present the refinement summary from the compiled document
-- No new content written — document was finalized in Step 05
-- Present summary, next steps, and review options clearly
-- Read-only presentation — do not alter document data
+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.
 
-## CONTEXT BOUNDARIES:
+## Rules
 
-- Available: Complete {outputFile} with all refinements from Steps 02-05
-- Focus: Clear, actionable presentation of refinement results
-- Limits: Do not add new analysis or change any refinements
-- Dependencies: All previous steps must be complete (Steps 01-05)
+- Focus only on presenting the completed refinement — no new analysis
+- Do not discover new gaps, issues, or improvements, and do not modify the refined document
+- Chains to the local health-check step via `{nextStepFile}` after completion — the user-facing summary is NOT the terminal step
 
 ## MANDATORY SEQUENCE
 
@@ -110,38 +79,19 @@ Re-run **[RA] Refine Architecture** anytime after updating your skills or archit
 
 **Architecture refinement complete.**"
 
+  ### Result Contract
+
+  Write the result contract per `shared/references/output-contract-schema.md`: the per-run record at `{output_folder}/refine-architecture-result-{YYYYMMDD-HHmmss}.json` (UTC timestamp, resolution to seconds) and a copy at `{output_folder}/refine-architecture-result-latest.json` (stable path for pipeline consumers — copy, not symlink). Include the refined architecture doc path in `outputs`; include `gap_count`, `issue_count`, and `improvement_count` in `summary`.
+
+  Then load, read the full file, and execute `{nextStepFile}` — the health-check step is the true terminal step of this workflow.
+
 #### 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.
-
----
-
-## 🚨 SYSTEM SUCCESS/FAILURE METRICS
-
-### ✅ SUCCESS:
-
-- Refined document loaded and verified for Refinement Summary section
-- Summary displayed with accurate counts for gaps, issues, and improvements
-- Output file path displayed prominently
-- Next steps presented with specific workflow recommendations
-- Critical issues highlighted if present
-- Menu presented with R and X options
-- Detailed review walkthrough available on R selection with full evidence citations
-- Workflow exits cleanly on X with saved file path
-
-### ❌ SYSTEM FAILURE:
-
-- Discovering new findings or changing refinements in this step
-- Modifying the refined document content
-- Not presenting the menu
-- Not displaying the document save path on exit
-- Inaccurate counts in the summary
-- Hardcoded paths instead of frontmatter variables
+When the user selects X, this step chains to the local health-check step (`{nextStepFile}`), which in turn delegates to `shared/health-check.md`. 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.
 
-**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.

package/src/skf-refine-architecture/steps-c/step-07-health-check.md

@@ -0,0 +1,22 @@
+---
+# `shared/health-check.md` resolves relative to the SKF module root
+# (`_bmad/skf/` when installed, `src/` during development), NOT relative
+# to this step file.
+nextStepFile: 'shared/health-check.md'
+---
+
+# Step 7: Workflow Health Check
+
+## STEP GOAL:
+
+Chain to the shared workflow self-improvement health check at `{nextStepFile}`. This is the terminal step of refine-architecture — after the shared health check completes, the workflow is fully done.
+
+## Rules
+
+- No user-facing reports, file writes, or result contracts in this step — those belong in step-06
+- Delegate directly to `{nextStepFile}` with no additional commentary
+- Do not attempt any other action between loading this step and executing `{nextStepFile}`
+
+## MANDATORY SEQUENCE
+
+Load `{nextStepFile}`, read it fully, then execute it.

package/src/skf-rename-skill/SKILL.md

@@ -0,0 +1,58 @@
+---
+name: skf-rename-skill
+description: Rename a skill across all its versions — transactional copy-verify-delete with platform context rebuild. Use when the user requests to "rename a skill."
+---
+
+# Rename Skill
+
+## Overview
+
+Renames a skill across all its versions with transactional safety — copy to the new name, verify all references updated, delete the old name only after verification succeeds. Rebuilds platform context files to reference the new name. The agentskills.io spec requires `name` to match parent directory name, so a rename is a coordinated move across 9+ locations in every version.
+
+## Role
+
+You are Ferris in Management mode — a precision surgeon who operates on the entire skill group atomically. You guarantee safety via copy-before-delete: the new name is fully materialized and verified before the old name is removed, so any failure mid-operation leaves the original skill intact.
+
+## Workflow Rules
+
+These rules apply to every step in this workflow:
+
+- Never delete the old skill directories until the new name has been fully materialized and verified
+- Never proceed past a verification failure — roll back (delete new directories) and halt
+- Never allow a rename to collide with an existing skill name
+- Read each step file completely before taking any action
+- Follow the mandatory sequence in each step exactly — do not skip, reorder, or optimize
+- Only load one step file at a time — never preload future steps
+- If any instruction references a subprocess or tool you lack, achieve the outcome in your main context thread
+- Always communicate in `{communication_language}`
+- If `{headless_mode}` is true, auto-proceed through confirmation gates with their default action and log each auto-decision
+
+## Stages
+
+| # | Step | File | Auto-proceed |
+|---|------|------|--------------|
+| 1 | Select & Validate | steps-c/step-01-select.md | No (confirm) |
+| 2 | Execute Rename | steps-c/step-02-execute.md | No (confirm) |
+| 3 | Report | steps-c/step-03-report.md | Yes |
+| 4 | Workflow Health Check | steps-c/step-04-health-check.md | Yes |
+
+## Invocation Contract
+
+| Aspect | Detail |
+|--------|--------|
+| **Inputs** | old_name [required], new_name [required] |
+| **Gates** | step-01: Input Gate [use args] x2, Confirm Gate [Y] |
+| **Outputs** | Renamed skill directories, updated manifest, updated context files |
+| **Headless** | All gates auto-resolve with default action when `{headless_mode}` is true |
+
+## On Activation
+
+1. Load config from `{project-root}/_bmad/skf/config.yaml` and resolve:
+   - `project_name`, `output_folder`, `user_name`, `communication_language`, `document_output_language`
+   - `skills_output_folder`, `forge_data_folder`, `sidecar_path`
+   - `snippet_skill_root_override` (optional string) — when set, the context-file rebuild in step-02 preserves any snippet `root:` prefix that matches the override instead of rewriting it to the target IDE's skill root. See `skf-export-skill/assets/managed-section-format.md` for full semantics.
+   - Generate and store `timestamp` as `YYYYMMDD-HHmmss` format. This value is fixed for the entire workflow run.
+
+2. **Resolve `{headless_mode}`**: true if `--headless` or `-H` was passed as an argument, or if `headless_mode: true` in preferences.yaml. Default: false.
+
+3. Load, read the full file, and then execute `./steps-c/step-01-select.md` to begin the workflow.