bmad-module-skill-forge 0.8.3 → 0.9.0

package/src/workflows/rename-skill/steps-c/step-02-execute.md

@@ -0,0 +1,391 @@
+---
+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'
+---
+
+# Step 2: Execute Rename (Transactional)
+
+## STEP GOAL:
+
+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):
+
+### 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
+
+## MANDATORY SEQUENCE
+
+**CRITICAL:** This is transactional. After section 1 (copy), the old skill is untouched. If any section between 2 and 7 fails, delete `{new_skill_group}` and `{new_forge_group}`, report the failure, and halt — the old skill remains intact. Only section 8 (delete old) makes the operation irreversible. Do not skip, reorder, or improvise.
+
+### 0. Re-read Version-Paths Knowledge
+
+Read `{versionPathsKnowledge}` again and confirm the templates (`{skill_package}`, `{skill_group}`, `{forge_version}`, `{forge_group}`) and the Rename section. Also read `{managedSectionLogic}` for the managed-section format template and the skill index rebuild rules that will be reused in section 7.
+
+### 1. Copy skill_group and forge_group
+
+**Precondition:** Both `{new_skill_group}` and `{new_forge_group}` must NOT exist (step-01 validated this in the collision check, but verify again before copying).
+
+1. If `{new_skill_group}` or `{new_forge_group}` exists on disk, halt with: "**Collision detected at execution time.** `{new_skill_group}` or `{new_forge_group}` now exists on disk — it did not exist during step-01 selection. Aborting before any files are touched."
+
+2. Copy `{old_skill_group}` to `{new_skill_group}` recursively:
+   - Preserve file permissions, timestamps, and symlinks
+   - Equivalent to `cp -a {old_skill_group} {new_skill_group}` (preserves symlinks) or `cp -r` followed by explicit symlink re-creation in section 4
+   - If the copy fails: halt with "**Copy failed:** `{old_skill_group}` → `{new_skill_group}`: {error}. No files were modified. Old skill is intact."
+
+3. Copy `{old_forge_group}` to `{new_forge_group}` the same way:
+   - If the copy fails: **rollback** by deleting `{new_skill_group}` (just created in step 2), then halt with "**Copy failed:** `{old_forge_group}` → `{new_forge_group}`: {error}. Rolled back new skill_group. Old skill is intact."
+
+**Rollback procedure for this section:** `rm -rf {new_skill_group}` and `rm -rf {new_forge_group}` (whichever exist). Old skill is untouched.
+
+Report: "**Copied** `{old_skill_group}` → `{new_skill_group}` and `{old_forge_group}` → `{new_forge_group}`."
+
+### 2. Rename Inner Version Directories
+
+For each version `v` in `affected_versions`:
+
+1. Resolve the old inner directory: `{new_skill_group}/{v}/{old_name}/`
+2. Resolve the new inner directory: `{new_skill_group}/{v}/{new_name}/`
+3. Rename the directory (move within the same parent): `mv {new_skill_group}/{v}/{old_name} {new_skill_group}/{v}/{new_name}`
+4. If the old inner directory does not exist (orphaned version with no skill package), skip with a warning recorded in `section2_warnings`
+
+**Rollback on any rename failure:**
+
+- `rm -rf {new_skill_group}` and `rm -rf {new_forge_group}`
+- Halt with: "**Inner directory rename failed** at `{v}/{old_name}`: {error}. Rolled back both new directories. Old skill is intact."
+
+Report: "**Renamed {count} inner directories** to `{new_name}/`."
+
+### 3. Update File Contents Inside the New Location
+
+For each version `v` in `affected_versions`, operate on the files inside `{new_skill_group}/{v}/{new_name}/` (the freshly renamed inner directory) and `{new_forge_group}/{v}/`:
+
+**3a. SKILL.md frontmatter:**
+
+- Path: `{new_skill_group}/{v}/{new_name}/SKILL.md`
+- In the YAML frontmatter (between the leading `---` markers), replace the `name:` field value from `{old_name}` to `{new_name}`
+- Only replace within the frontmatter block — do not substitute matches inside the body text
+- If the file is missing, record it in `section3_warnings` and continue
+
+**3b. metadata.json:**
+
+- Path: `{new_skill_group}/{v}/{new_name}/metadata.json`
+- Parse the JSON, set `name` = `{new_name}`, write back preserving formatting
+- If the file is missing, record it in `section3_warnings` and continue
+
+**3c. context-snippet.md:**
+
+- 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}/`
+- If the file is missing, record it in `section3_warnings` and continue
+
+**3d. provenance-map.json:**
+
+- Path: `{new_forge_group}/{v}/provenance-map.json`
+- Parse JSON, set `skill_name` = `{new_name}`, write back preserving formatting
+- If the file is missing (some versions may not have a provenance map), record it in `section3_warnings` and continue
+
+**Rollback on any update failure (not just a missing file):**
+
+- `rm -rf {new_skill_group}` and `rm -rf {new_forge_group}`
+- Halt with: "**File update failed** at `{path}`: {error}. Rolled back both new directories. Old skill is intact."
+
+Report: "**Updated file contents** across {affected_versions_count} version(s): SKILL.md, metadata.json, context-snippet.md, provenance-map.json."
+
+### 4. Fix the `active` Symlink in the New Location
+
+Recreate or repair the `active` symlink in `{new_skill_group}`:
+
+1. Inspect `{old_skill_group}/active` to determine the target version (the value the symlink points to — typically just the version string, not an absolute path)
+2. Check `{new_skill_group}/active`:
+   - If the copy in section 1 preserved it correctly and it points to the same version string → leave it as-is
+   - If it exists but points somewhere invalid (e.g., an absolute path back into the old location) → remove and recreate it
+   - If it is missing (some copy tools do not preserve symlinks) → create it
+3. The symlink target should be a relative path: the version string alone (e.g., `0.6.0`), so that `{new_skill_group}/active/{new_name}/` resolves correctly
+
+**Rollback on failure:**
+
+- `rm -rf {new_skill_group}` and `rm -rf {new_forge_group}`
+- Halt with: "**Failed to repair `active` symlink** in `{new_skill_group}`: {error}. Rolled back both new directories. Old skill is intact."
+
+### 5. Verify — No Trace of `{old_name}` Inside the New Location
+
+This is the commit-point check. If any match is found, the rename is not safe to commit.
+
+For every version `v` in `affected_versions`, grep (literal substring, case-sensitive) for `{old_name}` in:
+
+- `{new_skill_group}/{v}/{new_name}/SKILL.md`
+- `{new_skill_group}/{v}/{new_name}/metadata.json`
+- `{new_skill_group}/{v}/{new_name}/context-snippet.md`
+- `{new_forge_group}/{v}/provenance-map.json`
+
+Also check the directory listing itself:
+
+- `{new_skill_group}/{v}/` should contain `{new_name}/` and MUST NOT contain `{old_name}/`
+
+**Important nuance:** body text of SKILL.md may legitimately mention the old name (e.g., historical notes, changelog, cross-references). The grep is allowed to match within SKILL.md body text ONLY if the match is clearly informational (surrounding prose, not a structural reference). For the purposes of this step, treat any match in `metadata.json`, `context-snippet.md`, `provenance-map.json`, or the SKILL.md frontmatter block as a hard failure. Matches inside the SKILL.md body below the closing `---` are recorded as `verification_warnings` but do not block the rename.
+
+**On hard failure (any structural reference to `{old_name}` remains):**
+
+- `rm -rf {new_skill_group}` and `rm -rf {new_forge_group}`
+- Halt with: "**Verification failed.** `{old_name}` still appears in: {list of paths}. Rolled back both new directories. Old skill is intact."
+
+Report: "**Verified** — no structural references to `{old_name}` remain inside the new location across {affected_versions_count} version(s). {if verification_warnings is non-empty: 'Informational body-text mentions retained in SKILL.md: {list}.'}"
+
+### 6. Update Export Manifest
+
+**If `manifest_exists = false` (step-01 recorded no manifest on disk):**
+
+Skip this section entirely. Set `manifest_updated = false` and `manifest_backup = null`. There is no manifest to re-key — the skill was never exported. Section 7 will find no platform context files to rebuild either (no manifest means no prior export, so no `<!-- SKF:BEGIN -->` markers exist), and any platform file that happens to be present will be left alone by the section 2 marker check.
+
+Report: "**Manifest update skipped** — no `.export-manifest.json` on disk. The rename is a pure on-disk operation."
+
+**If `manifest_exists = true`:**
+
+1. Load `{skills_output_folder}/.export-manifest.json`
+2. **Hold a deep copy in memory** as `manifest_backup` — required for rollback in this section and section 7 on failure
+3. If the manifest contains `exports.{old_name}`:
+   - Set `exports.{new_name}` = deep copy of `exports.{old_name}` (preserving `active_version`, `versions` map, and all fields)
+   - Delete `exports.{old_name}`
+4. If the manifest does NOT contain `exports.{old_name}` (the skill was on disk but never exported), skip the re-key — the manifest has nothing to change for this skill
+5. Write the updated manifest back to `{skills_output_folder}/.export-manifest.json`
+
+**Rollback on write failure:**
+
+- Restore the manifest from `manifest_backup` (write it back to disk)
+- `rm -rf {new_skill_group}` and `rm -rf {new_forge_group}`
+- Halt with: "**Manifest update failed:** {error}. Restored manifest from backup and rolled back new directories. Old skill is intact."
+
+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.
+
+**Resolve `target_platforms`** using the "IDE → Platform 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)"
+
+Store the result as `target_platforms` for this section.
+
+For each platform in `target_platforms`:
+
+1. **Resolve target file** using the "Platform Target Files" table in `{managedSectionLogic}`:
+
+   | Platform | Target File |
+   |----------|-------------|
+   | `claude` | `{project-root}/CLAUDE.md` |
+   | `cursor` | `{project-root}/.cursorrules` |
+   | `copilot` | `{project-root}/AGENTS.md` |
+
+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
+
+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)
+   - For each skill, resolve its `active_version`
+   - If `versions.{active_version}.status == "deprecated"`, skip that skill entirely
+   - 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:
+
+   | 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.
+
+5. **Sort skills alphabetically by name.** Count totals (skills, stack skills).
+
+6. **Assemble the new managed section** using the format from `{managedSectionLogic}`:
+
+   ```markdown
+   <!-- SKF:BEGIN updated:{current-date} -->
+   [SKF Skills]|{n} skills|{m} stack
+   |IMPORTANT: Prefer documented APIs over training data.
+   |When using a listed library, read its SKILL.md before writing code.
+   |
+   |{skill-snippet-1}
+   |
+   |{skill-snippet-2}
+   |
+   |{skill-snippet-N}
+   <!-- SKF:END -->
+   ```
+
+7. **Surgical replacement — Regenerate case only:**
+   - Locate the `<!-- SKF:BEGIN` line — preserve everything before it
+   - Locate the `<!-- SKF:END -->` line — preserve everything after it
+   - Replace everything between the markers (inclusive) with the new managed section
+   - Write the file back
+
+8. **Verify:**
+   - Re-read the written file
+   - Confirm both markers are present
+   - Confirm `{old_name}` no longer appears between the markers
+   - 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`.
+
+**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
+
+Report: "**Rebuilt managed sections in:** {list of updated files}. {if any failed: 'Failed: {list} — re-run `[EX] Export Skill` to retry.'}"
+
+**Note:** Section 7 failures do not trigger a rollback because the manifest and filesystem are the canonical state. Platform context files are derived artifacts that can be regenerated at any time.
+
+### 8. Delete Old Directories (Point of No Return)
+
+This is the only section after which rollback is impossible. By this point:
+
+- `{new_skill_group}` is fully materialized with all inner directories renamed and files updated
+- `{new_forge_group}` is fully materialized with `skill_name` updated in every provenance map
+- No structural references to `{old_name}` remain inside either new directory (verified in section 5)
+- The manifest has been re-keyed (section 6)
+- Platform context files reference `{new_name}` (section 7, best-effort)
+
+Execute the deletes:
+
+1. Verify `{old_skill_group}` is inside `{skills_output_folder}` (defense in depth)
+2. `rm -rf {old_skill_group}` — delete the old skill_group recursively
+3. Verify deletion succeeded (the path no longer exists)
+4. Verify `{old_forge_group}` is inside `{forge_data_folder}` (defense in depth)
+5. `rm -rf {old_forge_group}` — delete the old forge_group recursively
+6. Verify deletion succeeded
+
+**On deletion error:**
+
+- Record the error in `deletion_errors` against the specific path
+- Continue attempting the other path — partial cleanup is still better than none
+- Do NOT attempt any rollback — the new name is already committed and the old name's remnants can be removed manually
+
+Report: "**Deleted old directories:** `{old_skill_group}` and `{old_forge_group}`. {if deletion_errors is non-empty: 'Errors: {list} — remove manually with `rm -rf {path}`.'}"
+
+### 9. Store Results in Context
+
+Store the following for step-03:
+
+- `old_name` — the previous skill name
+- `new_name` — the new skill name
+- `affected_versions` — list of versions that were renamed
+- `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)
+- `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)
+- `deletion_errors` — list of post-commit deletion errors (empty if none)
+
+### 10. Load Next Step
+
+Load, read the full file, and then execute `{nextStepFile}`.
+
+## Error Handling Summary
+
+| Section | Failure Mode | Reversible? | Recovery Action |
+|---------|--------------|-------------|-----------------|
+| 1 | Copy failure | Yes | Delete whichever new directory exists; old skill intact |
+| 2 | Inner rename failure | Yes | `rm -rf` both new directories; old skill intact |
+| 3 | File update failure | Yes | `rm -rf` both new directories; old skill intact |
+| 4 | `active` symlink repair failure | Yes | `rm -rf` both new directories; old skill intact |
+| 5 | Verification failure | Yes | `rm -rf` both new directories; old skill intact |
+| 6 | Manifest write failure | Yes | Restore manifest from backup; `rm -rf` both new directories; old skill intact |
+| 7 | Platform context rebuild failure | Per-file | Record errors, continue other platforms; do NOT rollback — manifest and disk are canonical |
+| 8 | Delete failure | **No** | Record deletion errors; new name is already committed; user removes remnants manually |
+
+## CRITICAL STEP COMPLETION NOTE
+
+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/workflows/rename-skill/steps-c/step-03-report.md

@@ -0,0 +1,132 @@
+---
+name: 'step-03-report'
+description: 'Report rename operation results'
+---
+
+# 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.
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+### Universal Rules:
+
+- 🛑 NEVER modify any files in this step — report only
+- 📖 CRITICAL: Read the complete step file before taking any action
+- 📋 YOU ARE A FACILITATOR, summarizing what step-02 already executed
+- ⚙️ 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 — summarizing a transactional rename with precision
+- ✅ Be explicit about what changed and what did not — no glossing over partial failures
+- ✅ Surface every warning and deletion error so the user knows exactly where manual cleanup is required
+
+### Step-Specific Rules:
+
+- 🎯 Focus only on reporting the results stored in context by step-02
+- 🚫 FORBIDDEN to re-execute any part of the rename
+- 🚫 FORBIDDEN to hide verification warnings, platform rebuild failures, or deletion errors
+- 💬 Present the "next steps" guidance so the user knows which downstream workflows to run
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Render the report using the context values set in step-02 (`old_name`, `new_name`, `affected_versions`, `affected_versions_count`, `files_updated_per_version`, `manifest_rekeyed`, `platform_files_updated`, `platform_files_failed`, `section2_warnings`, `section3_warnings`, `verification_warnings`, `deletion_errors`)
+- 💬 Include the "next steps" block unconditionally — it captures the common follow-ups for any rename
+
+## CONTEXT BOUNDARIES:
+
+- Available: All decision and result values stored in context by step-01 and step-02
+- Focus: Rendering the final report
+- Limits: No file writes, no deletions, no further execution
+- Dependencies: Step-02 must have completed (or attempted all sections through section 8) and stored its results
+
+## 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})"}
+Platform files rebuilt: {list from platform_files_updated, or "(none)"}
+{if platform_files_failed is non-empty:}
+Platform files FAILED: {list from platform_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
+```
+
+### 2. Close the Workflow
+
+After rendering the report, the workflow is complete. Do not load any further step file — there is no `nextStepFile`.
+
+## CRITICAL STEP COMPLETION NOTE
+
+This is the final step. Once the report has been rendered, the rename-skill workflow is finished. Do not re-run any earlier step automatically — if the user wants another rename, they should re-invoke the workflow from the top.
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- Report rendered with old name, new name, and affected version list
+- Per-file update counts stated explicitly (SKILL.md, metadata.json, context-snippet.md, provenance-map.json)
+- Manifest re-key outcome clearly stated
+- Platform files rebuilt listed (and failures surfaced when present)
+- All warning categories surfaced (inner rename, missing files, informational body-text mentions)
+- Post-commit deletion errors surfaced with manual cleanup guidance
+- Next-steps block included unconditionally
+- No further file writes or executions performed
+
+### ❌ SYSTEM FAILURE:
+
+- Hiding failed platform rebuilds, verification warnings, or deletion errors
+- Reporting "complete" when step-02 partially failed without flagging it
+- Re-executing any part of the rename workflow
+- Omitting the next-steps guidance
+- Reading stale context values instead of the post-rename state stored by step-02
+
+**Master Rule:** The report must be an honest, complete summary of what step-02 actually did. Every partial failure must be visible so the user knows exactly what manual follow-up, if any, is required.

package/src/workflows/rename-skill/workflow.md

@@ -0,0 +1,64 @@
+---
+name: rename-skill
+description: "Rename a skill and all its versions. Transactional — copy, verify, then delete the old name. Rebuilds platform context files."
+web_bundle: true
+installed_path: '{project-root}/_bmad/skf/workflows/skillforge/rename-skill'
+---
+
+# Rename Skill
+
+**Goal:** Rename 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.
+
+**Your Role:** In addition to your name, communication_style, and persona, you are also Ferris in Management mode — a precision surgeon who operates on the entire skill group atomically. The agentskills.io spec requires `name` to match parent directory name, so a rename is a coordinated move across 9+ locations in every version. 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 ARCHITECTURE
+
+This uses **step-file architecture** for disciplined execution:
+
+### Core Principles
+
+- **Micro-file Design**: Each step is a self-contained instruction file that is a part of an overall workflow that must be followed exactly
+- **Just-In-Time Loading**: Only the current step file is in memory — never load future step files until told to do so
+- **Sequential Enforcement**: Sequence within the step files must be completed in order, no skipping or optimization allowed
+- **Transactional Safety**: Copy-verify-delete pattern — the new name is fully materialized and verified before the old name is removed. Any failure before the final delete stage is fully reversible by deleting the new name.
+- **Manifest-Driven Truth**: The export manifest is the source of truth for what exists and what is active; the filesystem and the manifest are updated together and must end in a consistent state
+
+### Step Processing Rules
+
+1. **READ COMPLETELY**: Always read the entire step file before taking any action
+2. **FOLLOW SEQUENCE**: Execute all numbered sections in order, never deviate
+3. **WAIT FOR INPUT**: If a menu is presented, halt and wait for user selection
+4. **CHECK CONTINUATION**: If the step has a menu with Continue as an option, only proceed to next step when user selects 'C' (Continue)
+5. **LOAD NEXT**: When directed, load, read entire file, then execute the next step file
+
+### Critical Rules (NO EXCEPTIONS)
+
+- 🛑 **NEVER** load multiple step files simultaneously
+- 📖 **ALWAYS** read entire step file before execution
+- 🚫 **NEVER** skip steps or optimize the sequence
+- 🎯 **ALWAYS** follow the exact instructions in the step file
+- ⏸️ **ALWAYS** halt at menus and wait for user input
+- 📋 **NEVER** create mental todo lists from future steps
+- ⚙️ **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
+- 🛡️ **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 the new directories) and halt
+- 🛡️ **NEVER** allow a rename to collide with an existing skill name
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`
+
+---
+
+## INITIALIZATION SEQUENCE
+
+### 1. Module Configuration Loading
+
+Load and read full 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`
+- Generate and store `timestamp` as the current date-time in `YYYYMMDD-HHmmss` format. This value is fixed for the entire workflow run and must not be regenerated in subsequent steps.
+
+### 2. First Step Execution
+
+Load, read the full file and then execute `./steps-c/step-01-select.md` to begin the workflow.

package/src/workflows/test-skill/steps-c/step-01-init.md

@@ -3,7 +3,7 @@ name: 'step-01-init'
 description: 'Discover skill, load forge tier state, validate inputs, create test report'
 
 nextStepFile: './step-02-detect-mode.md'
-outputFile: '{forge_data_folder}/{skill_name}/test-report-{skill_name}.md'
+outputFile: '{forge_version}/test-report-{skill_name}.md'
 templateFile: '../templates/test-report-template.md'
 sidecarFile: '{sidecar_path}/forge-tier.yaml'
 skillsOutputFolder: '{skills_output_folder}'
@@ -69,16 +69,24 @@ Provide the skill path or name. I'll search in `{skillsOutputFolder}`.
 
 **Path or name:**"
 
-### 2. Validate Skill Exists
+### 2. Validate Skill Exists (version-aware)
 
-Check that the skill directory contains required files:
+Resolve the skill path using version-aware resolution (see [knowledge/version-paths.md](../../../knowledge/version-paths.md)):
+
+1. Read `{skillsOutputFolder}/.export-manifest.json` and look up the skill name in `exports` to get `active_version`
+2. If found: resolve to `{skill_package}` = `{skillsOutputFolder}/{skill_name}/{active_version}/{skill_name}/`
+3. If not in manifest: check for `active` symlink at `{skillsOutputFolder}/{skill_name}/active` — resolve to `{skill_group}/active/{skill_name}/`
+4. If neither: fall back to flat path `{skillsOutputFolder}/{skill_name}/`. If SKILL.md exists at the flat path, auto-migrate per `knowledge/version-paths.md` migration rules
+5. Store the resolved path as `{resolved_skill_package}`
+
+Check that the skill package contains required files:
 
 **Required files:**
-- `{skillsOutputFolder}/{skill_name}/SKILL.md` — the skill documentation
-- `{skillsOutputFolder}/{skill_name}/metadata.json` — skill metadata
+- `{resolved_skill_package}/SKILL.md` — the skill documentation
+- `{resolved_skill_package}/metadata.json` — skill metadata
 
 **If SKILL.md missing:**
-"**Error: SKILL.md not found at `{skillsOutputFolder}/{skill_name}/SKILL.md`**
+"**Error: SKILL.md not found at `{resolved_skill_package}/SKILL.md`**
 
 This skill has not been created yet. Run the **create-skill** workflow first."
 
@@ -116,11 +124,9 @@ Read `{sidecarFile}` to determine available analysis depth.
 - Read tool availability flags (ast_grep, gh_cli, qmd)
 
 **If forge-tier.yaml missing:**
-"**Warning:** Forge tier not detected. Defaulting to **Quick** tier (structural checks only).
+"**Cannot proceed.** forge-tier.yaml not found at `{sidecarFile}`. Please run the **setup-forge** workflow first to configure your forge tier (Quick/Forge/Forge+/Deep)."
 
-Run **setup-forge** to enable deeper analysis with AST-backed verification."
-
-Default to Quick tier and continue.
+HALT — do not proceed.
 
 ### 4b. Apply Tier Override (if set)
 
@@ -194,7 +200,7 @@ ONLY WHEN all required files are validated, forge tier is loaded, output documen
 ### ✅ SUCCESS:
 
 - Skill path validated (SKILL.md exists)
-- Forge tier state loaded (or gracefully defaulted to Quick), override applied if set in preferences.yaml
+- Forge tier state loaded (HALT if missing), override applied if set in preferences.yaml
 - Skill metadata extracted
 - Output document created from template with initial frontmatter
 - Initialization status reported clearly

package/src/workflows/test-skill/steps-c/step-02-detect-mode.md

@@ -3,7 +3,7 @@ name: 'step-02-detect-mode'
 description: 'Determine naive (individual) vs contextual (stack) testing mode'
 
 nextStepFile: './step-03-coverage-check.md'
-outputFile: '{forge_data_folder}/{skill_name}/test-report-{skill_name}.md'
+outputFile: '{forge_version}/test-report-{skill_name}.md'
 ---
 
 # Step 2: Detect Mode