bmad-module-skill-forge 0.8.4 → 0.10.0

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

@@ -0,0 +1,290 @@
+---
+name: 'step-02-execute'
+description: 'Execute the drop operation — update manifest, rebuild context files, delete files if purge'
+nextStepFile: './step-03-report.md'
+versionPathsKnowledge: '../../../knowledge/version-paths.md'
+managedSectionLogic: '../../export-skill/data/managed-section-format.md'
+---
+
+# Step 2: Execute Drop
+
+## STEP GOAL:
+
+Execute the drop decisions recorded in step-01: update the export manifest, rebuild platform context files so dropped versions disappear from managed sections, and (in purge mode) delete the affected directories from disk. Record everything that was changed for the final report in step-03.
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+### Universal Rules:
+
+- 🛑 NEVER modify content outside `<!-- SKF:BEGIN/END -->` markers in platform context files
+- 🛑 NEVER delete files outside the `affected_directories` list from step-01
+- 📖 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 destructive operation specialist
+- ✅ Execute only the decisions confirmed in step-01 — no scope expansion, no "while I'm at it" extras
+- ✅ Surgical precision: preserve all content outside `<!-- SKF:BEGIN/END -->` markers
+- ✅ Manifest and filesystem must end in a consistent state
+
+### Step-Specific Rules:
+
+- 🎯 Focus only on manifest update, context rebuild, and (in purge mode) file deletion
+- 🚫 FORBIDDEN to re-prompt the user — decisions were made in step-01
+- 🚫 FORBIDDEN to delete files in deprecate mode
+- 🚫 FORBIDDEN to widen the deletion scope beyond `affected_directories`
+- 💬 Report each stage's outcome as it completes so the user sees progress
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Re-read version-paths knowledge to avoid drift between step files
+- 💾 Persist the manifest update before touching platform context files
+- 📖 Rebuild managed sections from the updated manifest, not from memory
+- 🚫 If any stage fails, halt and report which stage failed with recovery guidance
+
+## CONTEXT BOUNDARIES:
+
+- Available: Decisions from step-01 (`target_skill`, `target_versions`, `drop_mode`, `is_skill_level`, `affected_directories`), SKF module config, version-paths knowledge, managed-section format
+- Focus: Manifest mutation, context rebuild, filesystem deletion (purge only)
+- Limits: Only modify content between `<!-- SKF:BEGIN/END -->` markers; only delete directories enumerated in `affected_directories`
+- Dependencies: Step-01 must have completed and stored all decisions in context
+
+## MANDATORY SEQUENCE
+
+**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise unless user explicitly requests a change.
+
+### 1. Re-read Version-Paths Knowledge
+
+Read `{versionPathsKnowledge}` again and confirm the templates and management operations. This ensures the execution step uses the same rules as the selection step even when run in isolation.
+
+Also read `{managedSectionLogic}` for the format template, the four-case logic, and the skill index rebuild rules that will be reused in section 3.
+
+### 2. Update Export Manifest
+
+**If `target_in_manifest == false`** (draft skill discovered only by on-disk scan): Skip this section entirely. There is no manifest entry to deprecate or delete. Set `manifest_updated = false` and proceed directly to section 3. Step-01 forced `drop_mode = "purge"` and `is_skill_level = true` in this case, so the subsequent sections will hard-delete the on-disk directories without any manifest interaction.
+
+**If `target_in_manifest == true`:**
+
+Load `{skills_output_folder}/.export-manifest.json`.
+
+**If `is_skill_level == false` (version-level drop):**
+
+For each version in `target_versions`:
+
+1. Navigate to `exports.{target_skill}.versions.{version}`
+2. Set `status = "deprecated"`
+3. Leave `platforms`, `last_exported`, and all other fields unchanged
+
+Do NOT change `active_version` on the skill entry in this pass — if the dropped version was the active one (only reachable when it was the sole non-deprecated version per the step-01 guard), the active_version field will still point at it, but every consumer excludes deprecated versions from exports.
+
+**If `is_skill_level == true` (skill-level drop):**
+
+1. Delete the `exports.{target_skill}` key entirely from the manifest
+2. Leave all other skill entries untouched
+
+**Write the updated manifest back to `{skills_output_folder}/.export-manifest.json`.**
+
+Set context flag `manifest_updated = true`.
+
+**On error (read/parse/write failure):**
+
+- Do not proceed to section 3
+- Report: "**Manifest update failed:** {error}. No files were deleted and platform context files were not rebuilt. The manifest is in its pre-drop state — rerun the workflow once the underlying issue is resolved."
+- Store `manifest_updated = false` and jump to section 6
+
+### 3. 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 drop on a malformed context file. The manifest has already been updated in section 2 and is canonical state; the platform file can be repaired manually and rebuilt on the next `[EX] Export Skill` run.
+
+3. **Build the exported skill set (version-aware, deprecated-excluded)** using the same logic as export-skill step-04 section 4b:
+   - Read the manifest's `exports` object (already updated in section 2)
+   - For each skill, resolve its `active_version`
+   - If `versions.{active_version}.status == "deprecated"`, skip that skill entirely
+   - The result is the set of `{skill-name, active_version}` pairs that should appear in the managed section
+
+4. **Resolve and filter snippets** using export-skill step-04 section 4c logic:
+   - For each `{skill-name, active_version}` in the set, read `{skills_output_folder}/{skill-name}/{active_version}/{skill-name}/context-snippet.md`
+   - If the file is missing, fall back to the `active` symlink path, then skip with a warning if still not found
+   - Collect successful snippets into the skill index
+
+5. **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.
+
+6. **Sort skills alphabetically by name.** Count totals (skills, stack skills).
+
+7. **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 -->
+   ```
+
+   If the filtered skill index is empty (e.g., the dropped skill was the only one), still emit the header with `0 skills|0 stack` and no skill entries. This keeps the managed section syntactically valid.
+
+8. **Surgical replacement — Case 3 (Regenerate) 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
+
+9. **Verify:**
+   - Re-read the written file
+   - Confirm both markers are present
+   - Confirm `{target_skill}` (at the dropped version, or at all versions if skill-level) no longer appears between the markers
+   - Confirm content outside the markers is byte-identical to what was preserved
+
+10. **On per-file failure:** record the error against that platform and continue to the next IDE. Do not halt — other platforms should still be rebuilt.
+
+**After the loop,** record `platform_files_updated` as the list of files that were successfully rewritten, and `platform_files_failed` as the list of any that failed.
+
+Report: "**Rebuilt managed sections in:** {list of updated files}. {if any failed: 'Failed: {list}'}"
+
+### 4. Delete Files (Purge Mode Only)
+
+**If `drop_mode != "purge"`**, skip this section entirely. Set `files_deleted = []` and `disk_freed = "N/A (soft drop)"`, then jump to section 5.
+
+**If `drop_mode == "purge"`:**
+
+1. Initialize `files_deleted = []` and `bytes_freed = 0`.
+
+2. For each directory path in `affected_directories`:
+   a. Verify the path is inside either `{skills_output_folder}` or `{forge_data_folder}` (defense in depth against accidental deletion of unrelated paths)
+   b. If the directory does not exist, record it as "(already absent)" and continue
+   c. Compute the directory size in bytes before deletion (recursive sum)
+   d. Delete the directory recursively
+   e. Verify deletion succeeded (the path no longer exists)
+   f. Append the path to `files_deleted` and add its byte size to `bytes_freed`
+
+3. **Version-level purge, single version:**
+   - `{skills_output_folder}/{target_skill}/{version}/` is deleted, but `{skills_output_folder}/{target_skill}/` remains (it still contains other versions or the `active` symlink)
+   - If the `active` symlink pointed to the just-deleted version, update or remove it:
+     - If other versions remain in the manifest for `{target_skill}`, repoint `active` to the manifest's current `active_version` (skipping deprecated)
+     - If no non-deprecated versions remain, remove the `active` symlink (reachable only when dropping the sole surviving version, which in step-01 was permitted because no other non-deprecated versions existed)
+
+4. **Skill-level purge:**
+   - `{skills_output_folder}/{target_skill}/` and `{forge_data_folder}/{target_skill}/` are deleted in full — the `active` symlink disappears with the parent directory
+
+5. Convert `bytes_freed` to a human-readable string for the final report (e.g. `"4.2 MB"`). Store as `disk_freed`.
+
+**On deletion error:**
+
+- Record which path failed and the error message
+- Continue attempting the remaining paths — partial purge is still better than no purge
+- Report all failures at the end of this section
+
+### 5. Verify Final State
+
+Run these verification checks:
+
+1. **Manifest check:** Re-read `{skills_output_folder}/.export-manifest.json` and confirm:
+   - Version-level drop: `exports.{target_skill}.versions.{version}.status == "deprecated"`
+   - Skill-level drop: `exports.{target_skill}` is absent
+
+2. **Platform files check:** For each file in `platform_files_updated`, spot-check that the dropped skill/version is no longer referenced between the markers.
+
+3. **Purge check (purge mode only):** For each path in `files_deleted`, confirm it no longer exists on disk.
+
+If any verification fails, record the specific failure in `verification_errors` but do not halt — proceed to step-03 so the report can surface what succeeded and what needs manual attention.
+
+### 6. Store Results in Context
+
+Store the following for step-03:
+
+- `files_deleted` — list of directory paths actually deleted (purge mode) or `[]` (soft drop)
+- `disk_freed` — human-readable size (purge mode) or `"N/A (soft drop)"`
+- `manifest_updated` — boolean (true if section 2 succeeded)
+- `platform_files_updated` — list of successfully rebuilt files
+- `platform_files_failed` — list of files that failed to rebuild (empty if none)
+- `verification_errors` — list of verification failures (empty if none)
+
+### 7. Load Next Step
+
+Load, read the full file, and then execute `{nextStepFile}`.
+
+## Error Handling Summary
+
+If any stage fails, record which stage failed and provide recovery guidance in the final report:
+
+| Failed Stage | Recovery Guidance |
+|--------------|-------------------|
+| Manifest update | "Manifest is in pre-drop state. Re-run the workflow once the underlying I/O issue is resolved. No files were deleted." |
+| Platform rebuild | "Manifest is already updated. Re-run `[EX] Export Skill` against any still-valid skill to regenerate the affected managed sections, or rerun the drop workflow." |
+| File deletion (purge) | "Manifest and platform files are consistent. Remaining directories listed in the report can be deleted manually: `rm -rf {path}`." |
+| Verification | "Execution completed but post-write checks found drift. See the report for specific paths requiring manual review." |
+
+## CRITICAL STEP COMPLETION NOTE
+
+ONLY WHEN all execution stages have been attempted (manifest update, context rebuild, file deletion in purge mode, verification) 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
+- Export manifest updated correctly (deprecated status for version-level, skill removal for skill-level)
+- Platform context files rebuilt for all configured IDEs using the same logic as export-skill step-04 (sections 4b–5), with surgical replacement preserving all content outside markers
+- Deprecated versions no longer appear in any managed section
+- Purge mode: all directories in `affected_directories` deleted with size accounting; `active` symlink updated or removed as appropriate
+- Soft drop: no files deleted; `files_deleted` is empty and `disk_freed` is `"N/A (soft drop)"`
+- Verification checks executed on manifest, platform files, and (if purge) deleted paths
+- All results stored in context for step-03
+- Errors at any stage are recorded with recovery guidance rather than silently swallowed
+
+### ❌ SYSTEM FAILURE:
+
+- Deleting files in soft drop mode
+- Deleting directories outside the `affected_directories` list
+- Modifying content outside `<!-- SKF:BEGIN/END -->` markers
+- Rebuilding managed sections from memory instead of the updated manifest
+- Including deprecated versions in the rebuilt skill index
+- Not updating the `active` symlink after a version-level purge when the dropped version was the target
+- Not verifying the final state
+- Hardcoding paths instead of using `{skill_package}`, `{skill_group}`, `{forge_version}`, `{forge_group}` templates
+- Halting the entire workflow on a recoverable per-platform error instead of continuing and reporting
+
+**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE. The manifest and the filesystem must end in a consistent state, and every destructive action must trace back to a decision made in step-01.

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

@@ -0,0 +1,136 @@
+---
+name: 'step-03-report'
+description: 'Report drop operation results'
+nextStepFile: '../../shared/health-check.md'
+---
+
+# Step 3: Report Drop Results
+
+## STEP GOAL:
+
+Present a clear, final summary of what the drop workflow changed — manifest state, platform context files, deleted directories, disk freed, and remaining versions — 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 destructive operation with precision
+- ✅ Be explicit about what changed and what did not — no glossing over partial failures
+- ✅ Surface recovery guidance when any stage in step-02 reported an error
+
+### Step-Specific Rules:
+
+- 🎯 Focus only on reporting the results stored in context by step-02
+- 🚫 FORBIDDEN to re-execute any part of the drop
+- 🚫 FORBIDDEN to hide verification errors or failed platform rebuilds
+- 💬 Present the final state clearly, including remaining versions for the affected skill
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Render the report using the context values set in step-02 (`target_skill`, `target_versions`, `drop_mode`, `is_skill_level`, `files_deleted`, `disk_freed`, `manifest_updated`, `platform_files_updated`, `platform_files_failed`, `verification_errors`)
+- 📖 For the "remaining versions" section, re-read `{skills_output_folder}/.export-manifest.json` (already updated by step-02) to show the current state
+- 💬 Include the reversibility note only when `drop_mode == "deprecate"`
+
+## CONTEXT BOUNDARIES:
+
+- Available: All decision and result values stored in context by step-01 and step-02, plus the updated export manifest on disk
+- Focus: Rendering the final report
+- Limits: No file writes, no deletions, no further execution
+- Dependencies: Step-02 must have completed (or attempted all stages) and stored its results
+
+## MANDATORY SEQUENCE
+
+**CRITICAL:** Follow this sequence exactly.
+
+### 1. Determine Remaining Versions
+
+**If `is_skill_level == true`:**
+
+Set `remaining_versions_display = "(skill fully removed)"`.
+
+**If `is_skill_level == false`:**
+
+Read `{skills_output_folder}/.export-manifest.json` and look up `exports.{target_skill}.versions`. Build a human-readable list of every remaining version with its status, with the active one marked:
+
+```
+  - 0.1.0 (deprecated)
+  - 0.5.0 (archived)
+  - 0.6.0 (active) *
+```
+
+### 2. Render the Report
+
+Display the following block, filling in values from context:
+
+```
+**Drop operation complete.**
+
+Operation:     {Deprecate | Purge}
+Skill:         {target_skill}
+Version(s):    {comma-separated target_versions or "ALL"}
+
+Changes:
+- Manifest updated:      {yes | no}
+- 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}
+{if drop_mode == "purge":}
+- Files deleted:         {list from files_deleted, or "(none — nothing on disk)"}
+- Disk space freed:      {disk_freed}
+
+Remaining versions for {target_skill}:
+{remaining_versions_display}
+
+{if drop_mode == "deprecate":}
+**Note:** Files remain on disk. This operation is reversible by manually editing
+`{skills_output_folder}/.export-manifest.json` and changing the version's `status`
+field back to `"active"` or `"archived"`, then re-running `[EX] Export Skill` to
+restore the managed section entry.
+
+{if verification_errors is non-empty:}
+**Verification warnings:**
+{list each verification error}
+These require manual review — see the error-handling guidance in step-02.
+```
+
+### 3. Workflow Health Check
+
+Load and execute `{nextStepFile}` for workflow self-improvement check.
+
+## CRITICAL STEP COMPLETION NOTE
+
+This step chains to the shared health check. After the health check completes, the drop-skill workflow is fully done. Do not re-run any earlier step automatically — if the user wants another drop, they should re-invoke the workflow from the top.
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- Report rendered with operation type, skill, version(s), and mode
+- Manifest update outcome clearly stated (yes/no)
+- Platform files rebuilt listed (and failures surfaced when present)
+- Purge mode: files deleted and disk freed reported
+- Soft drop: reversibility note included with concrete instructions
+- Remaining versions for the affected skill accurately listed from the updated manifest (or "(skill fully removed)" for skill-level drops)
+- Verification warnings surfaced, not hidden
+- No further file writes or executions performed
+
+### ❌ SYSTEM FAILURE:
+
+- Hiding failed platform rebuilds or verification errors
+- Reporting "complete" when step-02 partially failed without flagging it
+- Reading stale manifest data instead of the post-drop state
+- Re-executing any part of the drop workflow
+- Omitting the reversibility note in soft drop mode
+- Displaying remaining versions from memory rather than from the updated manifest
+
+**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/drop-skill/workflow.md

@@ -0,0 +1,63 @@
+---
+name: drop-skill
+description: "Drop (deprecate or purge) skill versions. Soft drop keeps files; hard drop deletes them. Active version guarded."
+web_bundle: true
+installed_path: '{project-root}/_bmad/skf/workflows/skillforge/drop-skill'
+---
+
+# Drop Skill
+
+**Goal:** Drop a specific skill version or an entire skill, either as a soft deprecation (manifest-only, files retained) or a hard purge (files deleted). Ensures platform context files are rebuilt to exclude dropped versions.
+
+**Your Role:** In addition to your name, communication_style, and persona, you are also Ferris in Delivery/Management mode — a destructive operation specialist who enforces safety guards. You treat every drop as potentially irreversible and require explicit user confirmation before touching the manifest or the filesystem. You protect the active version, keep the export manifest consistent with on-disk state, and ensure that downstream platform context files (CLAUDE.md / AGENTS.md / .cursorrules) are rebuilt so dropped versions disappear cleanly.
+
+---
+
+## 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
+- **Safety-First Destruction**: Every destructive action is preceded by an explicit user confirmation gate; nothing is deleted silently
+- **Manifest-Driven Truth**: The export manifest is the source of truth for what exists and what is active; the filesystem is updated to match
+
+### 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 files without explicit user confirmation in purge mode
+- 🛡️ **NEVER** drop an active version when other non-deprecated versions exist — enforce the active version guard
+- ✅ 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/export-skill/data/managed-section-format.md

@@ -18,9 +18,31 @@
 
 | Platform | Flag Value | Target File |
 |----------|-----------|-------------|
-| Claude | `claude` (default) | CLAUDE.md |
+| Copilot | `copilot` (default) | AGENTS.md |
+| Claude | `claude` | CLAUDE.md |
 | Cursor | `cursor` | .cursorrules |
-| Copilot | `copilot` | AGENTS.md |
+
+## IDE → Platform Mapping (config.yaml `ides` list)
+
+The installer writes installer-specific IDE identifiers to `config.yaml` under the `ides` key (not platform values). Any workflow that rebuilds platform context files from `config.yaml` MUST map each entry to a platform before looking up its target file.
+
+| config.yaml IDE value | Platform | Target File | Rationale |
+|----------------------|----------|-------------|-----------|
+| `claude-code` | `claude` | CLAUDE.md | native — reads `CLAUDE.md` and `.claude/skills/` |
+| `cursor` | `cursor` | .cursorrules | native — reads `.cursorrules` and `.cursor/skills/` |
+| `github-copilot` | `copilot` | AGENTS.md | native — reads `AGENTS.md` and `.agents/skills/` |
+| `codex` | `copilot` | AGENTS.md | OpenAI Codex reads `AGENTS.md` (same convention as copilot) |
+| `cline` | `copilot` | AGENTS.md | uses `AGENTS.md` as fallback context file |
+| `roo` | `copilot` | AGENTS.md | uses `AGENTS.md` as fallback context file |
+| `windsurf` | `copilot` | AGENTS.md | uses `AGENTS.md` as fallback context file |
+| `other` | `copilot` | AGENTS.md | generic AGENTS.md fallback |
+| _(any unknown value)_ | `copilot` | AGENTS.md | warn: "Unknown IDE '{value}' in config.yaml — defaulting to copilot" |
+
+**Deduplication:** When multiple IDE entries map to the same platform (e.g. `codex` and `cline` both → `copilot`), deduplicate so each platform is processed exactly once. Report the deduplication to the user.
+
+**Missing `ides` key:** If the `ides` key is absent from `config.yaml`, treat it as an empty list. If the resulting platform set is empty (no recognized entries), fall back to `["copilot"]`.
+
+This mapping is the single source of truth. Workflows that need it: `export-skill/step-01` (resolves `target_platforms` for the export), `drop-skill/step-02` and `rename-skill/step-02` (rebuild platform context files after a management operation).
 
 ## Four-Case Logic
 
@@ -62,13 +84,16 @@ Target file contains `<!-- SKF:BEGIN` but no matching `<!-- SKF:END -->` marker.
 
 ## Regeneration: Full Index Rebuild
 
-When regenerating (Case 3), rebuild the COMPLETE skill index:
+When regenerating (Case 3) or creating/appending (Cases 1-2), rebuild the skill index from the **exported skill set** only:
+
+1. Read `{skills_output_folder}/.export-manifest.json` (v2 schema — see [knowledge/version-paths.md](../../../knowledge/version-paths.md)) to determine which skills have been explicitly exported and their `active_version` (if no manifest exists, only the current export target qualifies)
+2. For each skill in the exported set, resolve the snippet at `{skills_output_folder}/{skill-name}/{active_version}/{skill-name}/context-snippet.md` (i.e., `{skill_package}/context-snippet.md`). Do NOT use glob patterns across version directories — always resolve via manifest `active_version` or `active` symlink
+3. Count total skills and stack skills (from filtered set only)
+4. Assemble filtered snippets into managed section
+5. Sort alphabetically by skill name
+6. Update the header line with correct counts
 
-1. Scan `{skills_output_folder}/*/context-snippet.md` for all exported skills
-2. Count total skills and stack skills
-3. Assemble all snippets into managed section
-4. Sort alphabetically by skill name
-5. Update the header line with correct counts
+**Rationale:** create-skill and update-skill also write `context-snippet.md` as a build artifact, but only export-skill is the publishing gate (ADR-K). The `.export-manifest.json` file tracks which skills have passed through export-skill, preventing draft skills from leaking into the agent's passive context.
 
 ## Safety Rules
 

package/src/workflows/export-skill/data/snippet-format.md

@@ -1,5 +1,17 @@
 # Context Snippet Format (Vercel-Aligned Indexed Format)
 
+## Platform Root Path Mapping
+
+The snippet `root:` path must reflect the platform-specific skills directory:
+
+| Platform | Root Path Prefix |
+|----------|-----------------|
+| `claude` | `.claude/skills/` |
+| `cursor` | `.cursor/skills/` |
+| `copilot` | `.agents/skills/` |
+
+The root path in context-snippet.md on disk uses the **first platform in `target_platforms`** (the first entry from config.yaml IDE mapping, or the explicit `--platform` flag value if provided). When assembling managed sections for other platforms, step-04 rewrites root paths to match the target platform.
+
 ## Format Rules
 
 - Indexed pipe-delimited format per skill — retrieval instruction + file map + inline gotchas
@@ -13,7 +25,7 @@
 ## Single Skill Snippet Template
 
 ```markdown
-[{skill-name} v{version}]|root: skills/{skill-name}/
+[{skill-name} v{version}]|root: {platform_root}{skill-name}/
 |IMPORTANT: {skill-name} v{version} — read SKILL.md before writing {skill-name} code. Do NOT rely on training data.
 |quick-start:{SKILL.md#quick-start}
 |api: {top exports with () for functions, comma-separated}
@@ -21,7 +33,7 @@
 |gotchas: {2-3 most critical pitfalls or breaking changes, inline}
 ```
 
-- **Line 1:** Skill name + version + root path — version signals training data staleness
+- **Line 1:** Skill name + version + platform-aware root path — version signals training data staleness
 - **Line 2 (IMPORTANT):** Retrieval instruction — always present
 - **Line 3 (quick-start):** Anchor pointer to Quick Start section
 - **Line 4 (api):** Top exports from metadata.json `exports` array (up to 10, with `()` for functions)
@@ -31,7 +43,7 @@
 ## Stack Skill Snippet Template
 
 ```markdown
-[{project}-stack v{version}]|root: skills/{project}-stack/
+[{project}-stack v{version}]|root: {platform_root}{project}-stack/
 |IMPORTANT: {project}-stack — read SKILL.md before writing integration code. Do NOT rely on training data.
 |stack: {dep-1}@{v1}, {dep-2}@{v2}, {dep-3}@{v3}
 |integrations: {pattern-1}, {pattern-2}
@@ -48,4 +60,4 @@
 - If fewer exports than the limit, list all available
 - If no exports data available, omit the api line
 - Section anchors must be verified against actual SKILL.md headings during generation. For split-body skills (where `references/` exists and `## Full` headings are stubs), if a heading is missing from SKILL.md, rewrite the anchor to point to the reference file path (preferred). Omit the anchor line only if the heading cannot be found in either SKILL.md or `references/*.md`
-- Skill path is relative to project root
+- Skill path is relative to project root and uses the platform-specific root prefix (see Platform Root Path Mapping above)