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

package/src/{workflows/rename-skill → skf-rename-skill}/steps-c/step-01-select.md

@@ -1,8 +1,6 @@
 ---
-name: 'step-01-select'
-description: 'Select skill to rename and validate the new name'
 nextStepFile: './step-02-execute.md'
-versionPathsKnowledge: '../../../knowledge/version-paths.md'
+versionPathsKnowledge: 'knowledge/version-paths.md'
 ---
 
 # Step 1: Select Rename Target
@@ -11,46 +9,12 @@ versionPathsKnowledge: '../../../knowledge/version-paths.md'
 
 Identify the skill the user wants to rename, validate the new name against the agentskills.io spec (kebab-case, length, uniqueness), warn about source authority implications, enumerate every version that will be touched, and obtain explicit user confirmation before any filesystem operation is scheduled. Every selection decision is stored in context so step-02 can execute the rename transactionally.
 
-## MANDATORY EXECUTION RULES (READ FIRST):
+## Rules
 
-### Universal Rules:
-
-- 🛑 NEVER schedule a rename without explicit user confirmation
-- 🛑 NEVER accept a new name that collides with an existing skill
-- 📖 CRITICAL: Read the complete step file before taking any action
-- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read
-- 📋 YOU ARE A FACILITATOR, not a content generator
-- ⚙️ 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 Ferris in Management mode — a precision surgeon for transactional renames
-- ✅ You validate the new name against agentskills.io spec constraints before anything moves
-- ✅ You enumerate the full blast radius (every affected version and directory) before asking for confirmation
-- ✅ Safety via copy-before-delete — the old skill is untouched until step-02 finishes verification
-
-### Step-Specific Rules:
-
-- 🎯 Focus only on selection, validation, and confirmation
-- 🚫 FORBIDDEN to proceed without explicit user confirmation at the final gate
-- 🚫 FORBIDDEN to modify the manifest, copy, or delete any files in this step — execution happens in step-02
-- 🚫 FORBIDDEN to accept a new name that fails validation (kebab-case, length, uniqueness)
-- 💬 Present the list of affected versions clearly so the user understands the scope before committing
-
-## EXECUTION PROTOCOLS:
-
-- 🎯 Load version-paths knowledge and the export manifest (if present) alongside an on-disk skill scan
-- 💾 Gather all selection decisions into context for step-02
-- 📖 Show the full list of affected versions and the resolved paths clearly
-- 🚫 Halt only if neither the manifest nor an on-disk scan yields any skill — rename must still work for draft skills that were never exported, so a missing or empty manifest is not fatal
-
-## CONTEXT BOUNDARIES:
-
-- Available: Export manifest v2, SKF module config variables, on-disk skill directory listing, version-paths knowledge (Rename section)
-- Focus: Selection, validation, and user confirmation
-- Limits: Do not write to the manifest, do not copy or delete any files — execution is deferred to step-02
-- Dependencies: At least one skill must exist in the export manifest (or on disk); otherwise the workflow halts
+- Focus only on selection, validation, and confirmation — do not modify manifest, copy, or delete files
+- Do not proceed without explicit user confirmation at the final gate
+- Do not accept a new name that fails validation (kebab-case, length, uniqueness)
+- Present the list of affected versions clearly so the user understands the scope
 
 ## MANDATORY SEQUENCE
 
@@ -108,7 +72,7 @@ Available skills:
 "**Which skill would you like to rename?**
 Enter the skill name or its number from the list above."
 
-Wait for user input. Accept either the numeric index or the skill name (exact match).
+Wait for user input. Accept either the numeric index or the skill name (exact match). **GATE [default: use args]** — If `{headless_mode}` and old skill name was provided as argument: select that skill and auto-proceed. If not provided, HALT: "headless mode requires old_name argument."
 
 **If the user's input does not match any listed skill:** Re-display the list and ask again.
 
@@ -119,7 +83,9 @@ Store the selection as `old_name`.
 "**What is the new name for this skill?**
 The new name must be kebab-case: lowercase alphanumeric with hyphens, 1-64 characters, matching the regex `^[a-z][a-z0-9-]*[a-z0-9]$` (single-character names may be a single lowercase letter or digit)."
 
-Wait for user input. Trim whitespace. Apply the following validations in order:
+Wait for user input. Trim whitespace. **GATE [default: use args]** — If `{headless_mode}` and new_name was provided as argument: use it and auto-proceed through validation. If not provided, HALT: "headless mode requires new_name argument."
+
+Apply the following validations in order:
 
 1. **Kebab-case format:** Must match `^[a-z][a-z0-9-]*[a-z0-9]$` (or `^[a-z0-9]$` for the single-character case). If it fails:
    "**Invalid name format.** The new name must be lowercase alphanumeric with hyphens, starting with a letter and ending with a letter or digit. Try again."
@@ -222,6 +188,8 @@ directories are removed and the old skill remains intact.
 Proceed? [Y/N]
 ```
 
+**GATE [default: Y]** — If `{headless_mode}`: auto-proceed with [Y], log: "headless: auto-confirmed rename {old_name} → {new_name}"
+
 Wait for explicit user response.
 
 - **If `Y`** → proceed to section 9
@@ -250,32 +218,3 @@ Load, read the full file, and then execute `{nextStepFile}`.
 
 ONLY WHEN the user has confirmed with `Y` at the confirmation gate AND all selection decisions have been stored in context, will you then load and read fully `{nextStepFile}` to execute the rename.
 
----
-
-## 🚨 SYSTEM SUCCESS/FAILURE METRICS
-
-### ✅ SUCCESS:
-
-- Version-paths knowledge loaded and the Rename section internalized before any decision
-- Export manifest read and validated (halt if empty/missing)
-- Complete skill list displayed with version counts and active version
-- Old name selected by explicit user input
-- New name validated against kebab-case regex, length, identity, and collision checks
-- `source_authority: "official"` warning shown and acknowledged when applicable
-- `affected_versions` enumerated from both the manifest and the on-disk directory listing
-- All four outer paths resolved from templates (no hardcoding)
-- Explicit user confirmation (`Y`) received at the confirmation gate
-- All selection decisions stored in context for step-02
-
-### ❌ SYSTEM FAILURE:
-
-- Proceeding without reading version-paths knowledge
-- Halting when the manifest is missing but on-disk skills exist — the fallback on-disk scan MUST be attempted before any "nothing to rename" halt
-- Accepting a new name that fails any of the four validation checks
-- Missing the source_authority warning when `"official"` is present
-- Hardcoding directory paths instead of using `{skill_package}`, `{skill_group}`, `{forge_version}`, `{forge_group}` templates
-- Modifying the manifest, copying, or deleting files in this step (execution belongs to step-02)
-- Skipping the confirmation gate or proceeding on any response other than `Y`
-- Not storing decisions in context for step-02
-
-**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE. No filesystem operation proceeds without explicit user confirmation, and no invalid new name is ever accepted.

package/src/{workflows/rename-skill → skf-rename-skill}/steps-c/step-02-execute.md

@@ -1,9 +1,7 @@
 ---
-name: 'step-02-execute'
-description: 'Execute the rename transactionally — copy, verify, then delete old'
 nextStepFile: './step-03-report.md'
-versionPathsKnowledge: '../../../knowledge/version-paths.md'
-managedSectionLogic: '../../export-skill/data/managed-section-format.md'
+versionPathsKnowledge: 'knowledge/version-paths.md'
+managedSectionLogic: 'skf-export-skill/assets/managed-section-format.md'
 ---
 
 # Step 2: Execute Rename (Transactional)
@@ -12,46 +10,13 @@ managedSectionLogic: '../../export-skill/data/managed-section-format.md'
 
 Execute the rename decisions recorded in step-01 as a transaction. Copy the old `{skill_group}` and `{forge_group}` to the new name, rename inner directories, rewrite every in-file reference, verify no trace of the old name remains inside the new location, update the export manifest, rebuild platform context files, and only then delete the old directories. Any failure before the final delete rolls back by removing the new directories — the old skill remains intact.
 
-## MANDATORY EXECUTION RULES (READ FIRST):
+## Rules
 
-### Universal Rules:
-
-- 🛑 **NEVER** delete `{old_skill_group}` or `{old_forge_group}` until sections 1-7 have all succeeded
-- 🛑 **NEVER** modify content outside `<!-- SKF:BEGIN/END -->` markers in platform context files
-- 🛑 **NEVER** skip verification — the rename is not committed until section 5 passes
-- 📖 CRITICAL: Read the complete step file before taking any action
-- 🔄 CRITICAL: When loading next step, 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 Ferris in Management mode — a transactional rename surgeon
-- ✅ Copy-before-delete: the new name is fully materialized and verified before the old name is touched
-- ✅ Every step before section 8 is reversible — on any failure, delete `{new_skill_group}` and `{new_forge_group}` and halt
-- ✅ Surgical precision on platform context files: preserve all content outside `<!-- SKF:BEGIN/END -->` markers
-
-### Step-Specific Rules:
-
-- 🎯 Execute sections strictly in order — each section depends on the previous one
-- 🚫 FORBIDDEN to re-prompt the user — decisions were made in step-01
-- 🚫 FORBIDDEN to delete anything from `{old_skill_group}` or `{old_forge_group}` before section 8
-- 🚫 FORBIDDEN to proceed past a verification failure in section 5
-- 💬 Report each section's outcome as it completes so the user sees progress
-
-## EXECUTION PROTOCOLS:
-
-- 🎯 Re-read version-paths knowledge at the start to avoid drift between step files
-- 💾 Hold a copy of the manifest in memory before modifying it so section 6 can roll back on failure
-- 📖 Rebuild managed sections from the **updated** manifest (after section 6), not from memory
-- 🚫 If any section before section 8 fails, execute the rollback procedure defined for that section and halt
-
-## CONTEXT BOUNDARIES:
-
-- Available: Decisions from step-01 (`old_name`, `new_name`, `affected_versions`, `old_skill_group`, `new_skill_group`, `old_forge_group`, `new_forge_group`), SKF module config, version-paths knowledge, managed-section format
-- Focus: Copy → rename inner dirs → rewrite files → verify → update manifest → rebuild context → delete old
-- Limits: Only touch paths inside `{skills_output_folder}` and `{forge_data_folder}`; only modify content between `<!-- SKF:BEGIN/END -->` markers in platform context files
-- Dependencies: Step-01 must have completed and stored all decisions in context
+- Execute sections strictly in order — each section depends on the previous one
+- Do not re-prompt the user — decisions were made in step-01
+- Do not delete anything from old directories before section 8
+- Do not proceed past a verification failure in section 5
+- Report each section's outcome as it completes
 
 ## MANDATORY SEQUENCE
 
@@ -116,13 +81,10 @@ For each version `v` in `affected_versions`, operate on the files inside `{new_s
 
 - Path: `{new_skill_group}/{v}/{new_name}/context-snippet.md`
 - Replace the display name header `[{old_name} v...]` → `[{new_name} v...]` (preserving the version suffix)
-- Rewrite every `root:` path that references the old name to use the new name. This must handle both platform paths and draft paths:
-  - `root: .claude/skills/{old_name}/` → `root: .claude/skills/{new_name}/`
-  - `root: .cursor/skills/{old_name}/` → `root: .cursor/skills/{new_name}/`
-  - `root: .agents/skills/{old_name}/` → `root: .agents/skills/{new_name}/`
-  - `root: skills/{old_name}/` → `root: skills/{new_name}/` (draft form written by create-skill/quick-skill/create-stack-skill before first export)
-  - Legacy pre-fix form `root: skills/{old_name}/active/{old_name}/` (from older skills created before the create-skill template was corrected) → `root: skills/{new_name}/` (also normalize to flat form during rename)
-  - Any other `root:` prefix ending in `{old_name}/` → replace the `{old_name}/` segment with `{new_name}/`
+- Rewrite every `root:` path that references the old name to use the new name. Parse the `root:` line as `root: {prefix}{old_name}/`, preserve the prefix as-is, and replace `{old_name}` with `{new_name}`. This generically handles any IDE's skill root path (e.g., `.claude/skills/`, `.windsurf/skills/`, `.github/skills/`) as well as the draft `skills/` prefix and legacy forms — no enumeration of known prefixes needed.
+  - Example: `root: .windsurf/skills/{old_name}/` → `root: .windsurf/skills/{new_name}/`
+  - Example: `root: skills/{old_name}/` → `root: skills/{new_name}/`
+  - Legacy pre-fix form `root: skills/{old_name}/active/{old_name}/` → `root: skills/{new_name}/` (normalize to flat form during rename)
 - If the file is missing, record it in `section3_warnings` and continue
 
 **3d. provenance-map.json:**
@@ -206,33 +168,27 @@ Set context flag `manifest_updated = true`.
 
 Report: "**Manifest updated** — re-keyed `exports.{old_name}` → `exports.{new_name}`."
 
-### 7. Rebuild Platform Context Files
-
-Load the `ides` list from `config.yaml`. The installer writes installer-specific IDE identifiers (e.g. `claude-code`, `github-copilot`, `codex`, `cline`, `roo`, `windsurf`, `cursor`, `other`), NOT platform values — these must be mapped to platforms before any target-file lookup.
+### 7. Rebuild Context Files
 
-**Resolve `target_platforms`** using the "IDE → Platform Mapping" table in `{managedSectionLogic}`:
+Load the `ides` list from `config.yaml`. The installer writes IDE identifiers — these must be mapped to context files and skill roots using the "IDE → Context File Mapping" table in `{managedSectionLogic}`.
 
-1. For each entry in `config.yaml.ides`, look up its platform value (`claude-code` → `claude`, `github-copilot` → `copilot`, `codex`/`cline`/`roo`/`windsurf`/`other` → `copilot`, `cursor` → `cursor`)
-2. For any entry not found in the table, default to `copilot` and emit a warning: "Unknown IDE '{value}' in config.yaml — defaulting to copilot"
-3. Deduplicate the resulting platform list (e.g. both `codex` and `cline` collapse to a single `copilot` entry)
-4. If `config.yaml.ides` is absent or the mapping yields an empty list, fall back to `["copilot"]` and emit a note: "No IDEs configured in config.yaml — defaulting to copilot (AGENTS.md)"
+**Resolve `target_context_files`** using the canonical mapping table in `{managedSectionLogic}`:
 
-Store the result as `target_platforms` for this section.
+1. For each entry in `config.yaml.ides`, look up its `context_file` and `skill_root` from the mapping table
+2. For any entry not found in the table, default to AGENTS.md / `.agents/skills/` and emit a warning: "Unknown IDE '{value}' in config.yaml — defaulting to AGENTS.md"
+3. Deduplicate by `context_file` — when multiple IDEs map to the same context file, use the first configured IDE's `skill_root`
+4. If `config.yaml.ides` is absent or the mapping yields an empty list, fall back to `[{context_file: "AGENTS.md", skill_root: ".agents/skills/"}]` and emit a note: "No IDEs configured in config.yaml — defaulting to AGENTS.md"
 
-For each platform in `target_platforms`:
+Store the result as `target_context_files` for this section.
 
-1. **Resolve target file** using the "Platform Target Files" table in `{managedSectionLogic}`:
+For each entry in `target_context_files`:
 
-   | Platform | Target File |
-   |----------|-------------|
-   | `claude` | `{project-root}/CLAUDE.md` |
-   | `cursor` | `{project-root}/.cursorrules` |
-   | `copilot` | `{project-root}/AGENTS.md` |
+1. **Resolve target file** at `{context_file}`.
 
 2. **Read the current file.**
-   - If the file does not exist, skip this platform (nothing to rebuild — the file will be re-created next time export-skill runs)
-   - If the file exists but contains no `<!-- SKF:BEGIN -->` marker, skip this platform (no managed section to rewrite)
-   - If the file contains `<!-- SKF:BEGIN -->` but no matching `<!-- SKF:END -->`, record the error against that platform and continue to the next IDE — do not halt the entire rename on a malformed context file
+   - If the file does not exist, skip this context file (nothing to rebuild — the file will be re-created next time export-skill runs)
+   - If the file exists but contains no `<!-- SKF:BEGIN -->` marker, skip this context file (no managed section to rewrite)
+   - If the file contains `<!-- SKF:BEGIN -->` but no matching `<!-- SKF:END -->`, record the error against that context file and continue to the next entry — do not halt the entire rename on a malformed context file
 
 3. **Build the exported skill set (version-aware, deprecated-excluded)** using the same logic as export-skill step-04 section 4b and the snippet resolution logic from section 4c:
    - Read the manifest's `exports` object (already updated in section 6, so `{new_name}` is present and `{old_name}` is absent)
@@ -241,15 +197,9 @@ For each platform in `target_platforms`:
    - For each remaining `{skill-name, active_version}` pair, read `{skills_output_folder}/{skill-name}/{active_version}/{skill-name}/context-snippet.md`
    - If missing, fall back to the `active` symlink path; if still missing, skip with a warning
 
-4. **Rewrite root paths for the current platform** using export-skill step-04 section 4d logic:
+4. **Rewrite root paths for the current context file** using the generic rewrite algorithm from export-skill step-04 section 4d:
 
-   | Platform | Root Path Prefix |
-   |----------|-----------------|
-   | `claude` | `.claude/skills/` |
-   | `cursor` | `.cursor/skills/` |
-   | `copilot` | `.agents/skills/` |
-
-   For each snippet, detect its current `root:` prefix and rewrite it to the current platform's prefix if different.
+   For each snippet, parse the `root:` line (`root: {prefix}{skill-name}/`), strip the trailing `{skill-name}/` to extract the current prefix, and replace it with the current entry's `skill_root` if different. **Override guard:** If `snippet_skill_root_override` is set in config.yaml AND the extracted prefix equals the override value, skip the rewrite — leave the root path untouched. See `skf-export-skill/steps-c/step-04-update-context.md` §4d for full semantics.
 
 5. **Sort skills alphabetically by name.** Count totals (skills, stack skills).
 
@@ -282,12 +232,12 @@ For each platform in `target_platforms`:
    - Confirm `{new_name}` appears between the markers (if this skill's active version is not deprecated)
    - Confirm content outside the markers is byte-identical to what was preserved
 
-9. **On per-file failure:** record the error against that platform and continue to the next IDE. Do not halt the rename on a recoverable per-platform error — the manifest and filesystem are already consistent; platform context files can be re-rebuilt later via `[EX] Export Skill`.
+9. **On per-file failure:** record the error against that context file and continue to the next entry. Do not halt the rename on a recoverable per-context-file error — the manifest and filesystem are already consistent; context files can be re-rebuilt later via `[EX] Export Skill`.
 
 **After the loop:**
 
-- Record `platform_files_updated` as the list of files that were successfully rewritten
-- Record `platform_files_failed` as the list of any that failed
+- Record `context_files_updated` as the list of files that were successfully rewritten
+- Record `context_files_failed` as the list of any that failed
 
 Report: "**Rebuilt managed sections in:** {list of updated files}. {if any failed: 'Failed: {list} — re-run `[EX] Export Skill` to retry.'}"
 
@@ -330,8 +280,8 @@ Store the following for step-03:
 - `affected_versions_count` — integer count
 - `files_updated_per_version` — structured summary (SKILL.md, metadata.json, context-snippet.md, provenance-map.json — each with ×count)
 - `manifest_rekeyed` — boolean (true if section 6 succeeded)
-- `platform_files_updated` — list of successfully rebuilt files
-- `platform_files_failed` — list of files that failed to rebuild (empty if none)
+- `context_files_updated` — list of successfully rebuilt files
+- `context_files_failed` — list of files that failed to rebuild (empty if none)
 - `section2_warnings` — list of orphaned version warnings (empty if none)
 - `section3_warnings` — list of missing file warnings (empty if none)
 - `verification_warnings` — list of informational SKILL.md body mentions of `{old_name}` retained (empty if none)
@@ -358,34 +308,3 @@ Load, read the full file, and then execute `{nextStepFile}`.
 
 ONLY WHEN all execution sections have been attempted (copy, inner rename, file updates, symlink fix, verification, manifest re-key, context rebuild, old delete) and results have been stored in context, will you then load and read fully `{nextStepFile}` to generate the final report.
 
----
-
-## 🚨 SYSTEM SUCCESS/FAILURE METRICS
-
-### ✅ SUCCESS:
-
-- Version-paths knowledge and managed-section format re-read at the start of the step
-- `{new_skill_group}` and `{new_forge_group}` copied from the old paths with symlinks preserved
-- Inner version directories renamed from `{old_name}/` to `{new_name}/` across every affected version
-- SKILL.md frontmatter, metadata.json, context-snippet.md (display name + root paths), and provenance-map.json updated across every version
-- `active` symlink in the new location points to the correct version
-- Verification grep confirms no structural references to `{old_name}` remain inside the new directories
-- Export manifest re-keyed from `exports.{old_name}` to `exports.{new_name}` preserving `active_version` and `versions` map
-- Platform context files rebuilt from the updated manifest using export-skill step-04 logic with surgical marker replacement
-- Old `{skill_group}` and `{forge_group}` deleted only after all previous sections succeeded
-- All failures before section 8 trigger a full rollback; failures in section 8 are recorded for manual cleanup
-- All results stored in context for step-03
-
-### ❌ SYSTEM FAILURE:
-
-- Deleting any part of `{old_skill_group}` or `{old_forge_group}` before section 8
-- Proceeding past a verification failure in section 5 instead of rolling back
-- Failing to restore the manifest from backup after a write failure in section 6
-- Rewriting content outside `<!-- SKF:BEGIN/END -->` markers in platform context files
-- Rebuilding managed sections from the pre-update manifest instead of the re-keyed one
-- Leaving structural references to `{old_name}` inside `{new_skill_group}` or `{new_forge_group}`
-- Hardcoding paths instead of using `{skill_package}`, `{skill_group}`, `{forge_version}`, `{forge_group}` templates
-- Halting the entire workflow on a recoverable per-platform error in section 7
-- Not storing results in context for step-03
-
-**Master Rule:** The rename is transactional. Copy-before-delete is inviolable. Every section before section 8 must have a concrete rollback procedure, and rollback must be executed on failure without exception. The old skill is canonical until the new name is fully verified.

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

@@ -0,0 +1,83 @@
+---
+nextStepFile: './step-04-health-check.md'
+---
+
+# Step 3: Report Rename Results
+
+## STEP GOAL:
+
+Present a clear, final summary of what the rename workflow changed — old and new names, versions renamed, file-level update counts, manifest re-key, platform context rebuild, and any residual warnings or deletion errors — so the user can verify the outcome and know whether any manual follow-up is required.
+
+## Rules
+
+- Focus only on reporting results stored in context by step-02 — do not re-execute any part of the rename
+- Do not hide verification warnings, context file rebuild failures, or deletion errors
+- Present next-steps guidance so the user knows which downstream workflows to run
+- Chains to the local health-check step via `{nextStepFile}` after completion — the user-facing report is NOT the terminal step
+
+## MANDATORY SEQUENCE
+
+**CRITICAL:** Follow this sequence exactly.
+
+### 1. Render the Report
+
+Display the following block, filling in values from context:
+
+```
+**Rename complete.**
+
+From: {old_name}
+To:   {new_name}
+
+Versions renamed: {affected_versions_count} ({comma-separated affected_versions})
+
+References updated:
+  - SKILL.md frontmatter       (×{affected_versions_count})
+  - metadata.json              (×{affected_versions_count})
+  - context-snippet.md         (×{affected_versions_count})
+  - provenance-map.json        (×{affected_versions_count})
+
+Manifest updated: {if manifest_rekeyed: "exports.{new_name} (re-keyed from exports.{old_name})" else: "(no manifest entry existed for {old_name})"}
+Context files rebuilt: {list from context_files_updated, or "(none)"}
+{if context_files_failed is non-empty:}
+Context files FAILED: {list from context_files_failed}
+  → Re-run `[EX] Export Skill` to retry the managed section rebuild for these files.
+
+{if section2_warnings is non-empty:}
+Warnings (inner directory rename):
+  {list each warning from section2_warnings}
+
+{if section3_warnings is non-empty:}
+Warnings (missing files during content update):
+  {list each warning from section3_warnings}
+
+{if verification_warnings is non-empty:}
+Informational: the old name still appears in SKILL.md body text (prose only, non-structural) in:
+  {list each path from verification_warnings}
+  → These are typically historical notes or changelog entries. Review and edit manually if you want them updated.
+
+{if deletion_errors is non-empty:}
+**Post-commit deletion errors:**
+  {list each error}
+  → The new name is fully committed. Remove the remnants manually with `rm -rf {path}`.
+
+---
+
+**Next steps:**
+  - Run `@Ferris EX` if you want to re-verify the managed sections in platform context files
+  - If you had QMD collections or external tooling registered under `{old_name}`, re-run `@Ferris SF` (or your registration command) to re-index under `{new_name}`
+  - If this skill was published to agentskills.io under `{old_name}`, the registry version is unchanged — this rename is a LOCAL operation only
+```
+
+### Result Contract
+
+Write the result contract per `shared/references/output-contract-schema.md`: the per-run record at `{skills_output_folder}/{new_name}/rename-skill-result-{YYYYMMDD-HHmmss}.json` (UTC timestamp, resolution to seconds) and a copy at `{skills_output_folder}/{new_name}/rename-skill-result-latest.json` (stable path for pipeline consumers — copy, not symlink). Include all updated file paths (SKILL.md, metadata.json, context-snippet.md, provenance-map.json) in `outputs`; include `old_name`, `new_name`, and `versions_renamed` in `summary`.
+
+### 2. Chain to Health Check
+
+ONLY WHEN the rename report has been rendered and the result contract saved will you then load, read the full file, and execute `{nextStepFile}`. The health-check step is the true terminal step — do not stop here even though the report reads as final.
+
+## CRITICAL STEP COMPLETION NOTE
+
+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 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/skf-rename-skill/steps-c/step-04-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 4: Workflow Health Check
+
+## STEP GOAL:
+
+Chain to the shared workflow self-improvement health check at `{nextStepFile}`. This is the terminal step of rename-skill — 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-03
+- 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-setup/SKILL.md

@@ -0,0 +1,55 @@
+---
+name: skf-setup
+description: Initialize forge environment, detect tools, and set capability tier (Quick/Forge/Forge+/Deep). Use when the user requests to "set up" or "initialize the forge."
+---
+
+# Setup Forge
+
+## Overview
+
+Initializes the forge environment by detecting available tools, determining the capability tier (Quick/Forge/Forge+/Deep), writing persistent configuration, and optionally indexing the project for deep search. This is a fully autonomous workflow — no user interaction is required during execution.
+
+## Role
+
+You are a system executor performing environment resolution. Run each step in sequence, write configuration files, and report results at completion.
+
+## Workflow Rules
+
+These rules apply to every step in this workflow:
+
+- Fully autonomous — all steps auto-proceed with no user interaction until the final report
+- 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
+- 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 | Detect Tools & Set Tier | steps-c/step-01-detect-and-tier.md | Yes |
+| 1b | CCC Index | steps-c/step-01b-ccc-index.md | Yes |
+| 2 | Write Config | steps-c/step-02-write-config.md | Yes |
+| 3 | QMD Hygiene | steps-c/step-03-auto-index.md | Yes |
+| 4 | Report | steps-c/step-04-report.md | Yes |
+| 5 | Workflow Health Check | steps-c/step-05-health-check.md | Yes |
+
+## Invocation Contract
+
+| Aspect | Detail |
+|--------|--------|
+| **Inputs** | (none — fully autonomous) |
+| **Gates** | One optional: orphaned QMD collection removal (step 3, Deep tier only; default: Keep) |
+| **Outputs** | forge-tier.yaml, preferences.yaml, forge-data directories |
+| **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` (from installer-generated config.yaml, not module.yaml), `output_folder`, `user_name`, `communication_language`, `document_output_language`
+   - `skills_output_folder`, `forge_data_folder`, `sidecar_path`
+
+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-detect-and-tier.md` to begin the workflow.

package/src/{workflows/setup-forge → skf-setup}/steps-c/step-01-detect-and-tier.md

@@ -1,9 +1,6 @@
 ---
-name: 'step-01-detect-and-tier'
-description: 'Detect available tools and determine forge capability tier'
-
 nextStepFile: './step-01b-ccc-index.md'
-tierRulesData: '../data/tier-rules.md'
+tierRulesData: 'references/tier-rules.md'
 ---
 
 # Step 1: Detect Tools and Determine Tier
@@ -12,41 +9,11 @@ tierRulesData: '../data/tier-rules.md'
 
 Verify availability of the four forge tools (ast-grep, gh, qmd, ccc), read any existing configuration for re-run comparison, check for tier override, and calculate the capability tier.
 
-## MANDATORY EXECUTION RULES (READ FIRST):
-
-### Universal Rules:
-
-- 📖 CRITICAL: Read the complete step file before taking any action
-- 🔄 CRITICAL: When loading next step, ensure entire file is read
-- 🎯 Execute all operations autonomously — no user interaction
-
-### Role Reinforcement:
-
-- ✅ You are a system executor performing environment resolution
-- ✅ Tool detection must be empirical — run actual commands, never assume
-- ✅ Record exact results (version strings, error messages)
-
-### Step-Specific Rules:
-
-- 🎯 Focus only on tool detection and tier calculation
-- 🚫 FORBIDDEN to write any files — that is step-02's job
-- 🚫 FORBIDDEN to skip any tool check — all 4 must be verified
-- 💬 Tool command failures are NOT errors — they indicate unavailability
-
-## EXECUTION PROTOCOLS:
-
-- 🎯 Follow the MANDATORY SEQUENCE exactly
-- 💾 Store all results in memory for step-02
-- 📖 Load tier-rules.md for calculation reference
-- 🚫 FORBIDDEN to proceed without checking all 4 tools
+## Rules
 
-## CONTEXT BOUNDARIES:
-
-- This is the first step — no prior context exists
-- Available: forge-tier.yaml and preferences.yaml may exist from prior runs
-- Focus: tool verification and tier calculation only
-- Produces: `{detected_tools}`, `{calculated_tier}`, `{previous_tier}`, `{tier_override}` for downstream steps
-- Dependencies: none — this step bootstraps everything
+- Focus only on tool detection and tier calculation — do not write any files (Step 02)
+- Do not skip any tool check — all 4 must be verified
+- Tool command failures are not errors — they indicate unavailability
 
 ## MANDATORY SEQUENCE
 
@@ -119,7 +86,7 @@ ccc availability gates the Forge+ tier and enhances Deep tier when present.
 
 **If no override, apply tier rules from {tierRulesData} in order — the first matching rule wins. Do not continue checking once a match is found:**
 - `{ast_grep}` AND `{gh_cli}` AND `{qmd}` all true → **Deep**
-- `{ast_grep}` AND `{ccc}` both true (regardless of gh/qmd) → **Forge+**
+- `{ast_grep}` AND `{ccc}` both true, but NOT (`{gh_cli}` AND `{qmd}`) → **Forge+**
 - `{ast_grep}` true (regardless of ccc/gh/qmd) → **Forge**
 - Otherwise → **Quick**
 
@@ -142,26 +109,3 @@ ccc availability gates the Forge+ tier and enhances Deep tier when present.
 
 ONLY WHEN all 4 core tools have been verified, optional security scan checked, and the tier calculated will you load and read fully `{nextStepFile}` to execute the CCC index check step.
 
----
-
-## 🚨 SYSTEM SUCCESS/FAILURE METRICS
-
-### ✅ SUCCESS:
-
-- All 4 tools checked via verification commands (not existence checks)
-- Existing forge-tier.yaml read for re-run comparison (if present)
-- Existing preferences.yaml read for tier_override (if present)
-- Tier correctly calculated from tool results or override applied
-- All results stored in context for step-01b and step-02
-- Auto-proceeded to step-01b
-
-### ❌ SYSTEM FAILURE:
-
-- Skipping any tool verification (ast-grep, gh, qmd, ccc — all 4 must be checked)
-- Using `which` or `command -v` instead of verification commands
-- Assuming tool availability without running the command
-- Writing files in this step (that is step-02)
-- Not checking for existing configuration on re-runs
-- Not checking ccc availability (both binary and daemon health)
-
-**Master Rule:** Every tool MUST be verified empirically. No assumptions, no shortcuts.