bmad-module-skill-forge 1.4.1 → 1.5.1

package/src/skf-drop-skill/{steps-c/step-03-report.md → references/report.md}

@@ -1,7 +1,9 @@
 ---
-nextStepFile: './step-04-health-check.md'
+nextStepFile: 'health-check.md'
 ---
 
+<!-- Config: communicate in {communication_language}. Render the report block in {document_output_language}. -->
+
 # Step 3: Report Drop Results
 
 ## STEP GOAL:
@@ -10,14 +12,12 @@ Present a clear, final summary of what the drop workflow changed — manifest st
 
 ## Rules
 
-- Focus only on reporting results stored in context by step-02 — do not re-execute any part of the drop
+- Focus only on reporting results stored in context by step 2 — do not re-execute any part of the drop
 - Do not hide verification errors or failed context file rebuilds
 - 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. Determine Remaining Versions
 
 **If `is_skill_level == true`:**
@@ -66,13 +66,21 @@ 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.
+These require manual review — see the error-handling guidance in step 2.
 ```
 
 ### Result Contract
 
 Write the result contract per `shared/references/output-contract-schema.md`: the per-run record at `{skills_output_folder}/drop-skill-result-{YYYYMMDD-HHmmss}.json` (UTC timestamp, resolution to seconds) and a copy at `{skills_output_folder}/drop-skill-result-latest.json` (stable path for pipeline consumers — copy, not symlink). Include all purged file paths in `outputs`; include `target_skill`, `drop_mode`, and `versions_affected` in `summary`.
 
+When `{headless_mode}` is true, also emit the single-line envelope on **stdout** before chaining to step 4 (matches the SKILL.md "Result Contract (Headless)" shape):
+
+```
+SKF_DROP_SKILL_RESULT_JSON: {"status":"success","skill":"{target_skill}","drop_mode":"{drop_mode}","versions_affected":{target_versions},"files_deleted":{files_deleted},"manifest_updated":{manifest_updated},"exit_code":0,"halt_reason":null}
+```
+
+Substitute `{target_versions}` as a JSON array (e.g. `["0.5.0"]`) or the literal string `"all"`; substitute `{files_deleted}` as a JSON array of absolute paths (`[]` in soft-drop mode); `manifest_updated` is the boolean from step 2's context.
+
 ### 3. Chain to Health Check
 
 ONLY WHEN the 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.

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

@@ -1,8 +1,10 @@
 ---
-nextStepFile: './step-02-execute.md'
+nextStepFile: 'execute.md'
 versionPathsKnowledge: 'knowledge/version-paths.md'
 ---
 
+<!-- Config: communicate in {communication_language}. -->
+
 # Step 1: Select Drop Target
 
 ## STEP GOAL:
@@ -18,8 +20,6 @@ Identify exactly what the user wants to drop — which skill, which version(s),
 
 ## MANDATORY SEQUENCE
 
-**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise unless user explicitly requests a change.
-
 ### 1. Load Knowledge
 
 Read `{versionPathsKnowledge}` completely and extract:
@@ -38,7 +38,7 @@ Load `{skills_output_folder}/.export-manifest.json` if it exists.
 
 **If the file exists with entries:** Parse JSON and verify `schema_version` is `"2"`. If the manifest is v1 (no `schema_version` field), note this but continue — treat every entry as having a single active version derived from its current state. Store `manifest_exists = true`.
 
-**Hard halt condition:** If the file exists but is malformed (not valid JSON), halt with: "**Export manifest is corrupt** at `{skills_output_folder}/.export-manifest.json` — fix or remove the file before dropping."
+**Hard halt condition:** If the file exists but is malformed (not valid JSON), halt with: "**Export manifest is corrupt** at `{skills_output_folder}/.export-manifest.json` — fix or remove the file before dropping." HALT (exit code 3, `halt_reason: "manifest-corrupt"`). In headless mode, emit the error envelope per SKILL.md "Result Contract (Headless)" with `skill: null`, `drop_mode: null`, `versions_affected: []`.
 
 ### 3. List Available Skills
 
@@ -53,7 +53,7 @@ For each skill in the manifest's `exports` (only if `manifest_exists = true` and
 
 Also scan `{skills_output_folder}/` for any top-level directories that are NOT present in the manifest's `exports` object. Record these as "(not in manifest)" — they represent draft or orphaned skills eligible for purge mode only. When the manifest is missing or empty, every on-disk skill appears in this category.
 
-**If the combined list is empty** (no manifest entries AND no on-disk skill directories): halt with "**Drop Skill — nothing to drop.** No skills found in `{skills_output_folder}/` and no entries in `.export-manifest.json`. Run `[CS] Create Skill` first."
+**If the combined list is empty** (no manifest entries AND no on-disk skill directories): halt with "**Drop Skill — nothing to drop.** No skills found in `{skills_output_folder}/` and no entries in `.export-manifest.json`. Run `[CS] Create Skill` first." HALT (exit code 3, `halt_reason: "nothing-to-drop"`). In headless mode, emit the error envelope with `skill: null`, `drop_mode: null`, `versions_affected: []`.
 
 Display the combined list:
 
@@ -73,11 +73,12 @@ Available skills:
 ### 4. Ask Which Skill
 
 "**Which skill would you like to drop?**
-Enter the skill name or its number from the list above."
+Enter the skill name or its number from the list above, or `cancel` / `exit` / `:q` to abort."
 
-Wait for user input. Accept either the numeric index or the skill name (exact match). **GATE [default: use args]** — If `{headless_mode}` and skill name was provided as argument: select that skill and auto-proceed. If not provided, HALT: "headless mode requires skill name argument."
+Wait for user input. Accept either the numeric index or the skill name (exact match). **GATE [default: use args]** — If `{headless_mode}` and skill name was provided as argument: select that skill and auto-proceed. If not provided, HALT (exit code 2, `halt_reason: "input-missing"`): "headless mode requires skill name argument." In headless mode, emit the error envelope with `skill: null`, `drop_mode: null`.
 
-**If the user's input does not match any listed skill:** Re-display the list and ask again.
+- If the user enters `cancel`, `exit`, `[X]`, `q`, or `:q`: Display "Cancelled — no changes were made." and HALT (exit code 6, `halt_reason: "user-cancelled"`).
+- **If the user's input does not match any listed skill:** Re-display the list and ask again.
 
 Store the selection as `target_skill`. Also store `target_in_manifest = true` if the selected skill has an entry in the manifest, `false` otherwise — subsequent sections use this flag to restrict the available drop options.
 
@@ -114,10 +115,13 @@ Store the selection as `target_skill`. Also store `target_in_manifest = true` if
 "**Drop which version(s)?**
 
 - **[N]** Specific version — soft deprecate or hard purge a single version
-- **[A]** All versions — drops the entire skill (skill-level operation)"
+- **[A]** All versions — drops the entire skill (skill-level operation)
+- **[X]** Cancel and exit (or type `cancel` / `exit` / `:q`)"
 
 Wait for user selection.
 
+- If the user enters `cancel`, `exit`, `[X]`, `q`, or `:q`: Display "Cancelled — no changes were made." and HALT (exit code 6, `halt_reason: "user-cancelled"`).
+
 **If [N] Specific version:**
 
 "**Which version?** Enter the version string (e.g. `0.5.0`)."
@@ -149,7 +153,7 @@ Set `target_versions = "all"` and `is_skill_level = true`.
 
       **(b)** Use the `[A] All versions` option to drop every version of `{target_skill}` at once."
 
-      HALT the workflow. Do not proceed.
+      HALT (exit code 5, `halt_reason: "active-version-guard-refused"`). In headless mode, emit the error envelope per SKILL.md "Result Contract (Headless)" with `skill: "{target_skill}"`, `drop_mode: null`, `versions_affected: ["{version}"]`. Do not proceed.
 
    c. If the count is `0` → the active version is the ONLY version; allow the drop to continue (it is functionally equivalent to a skill-level drop on a single-version skill)
 
@@ -159,13 +163,20 @@ Set `target_versions = "all"` and `is_skill_level = true`.
 
 **If `target_in_manifest = true`:**
 
+**If `{defaultMode}` is non-empty (`"deprecate"` or `"purge"`)**: skip the prompt, set `drop_mode = "{defaultMode}"`, and log the override source for the headless decision trail (`"customize.toml.workflow.default_mode"`).
+
+**Otherwise:**
+
 "**How should this be dropped?**
 
 - **[D]** Deprecate (soft) — Mark the version as `deprecated` in the manifest. Files remain on disk. Export-skill will exclude it from all platform context files. Reversible by editing the manifest.
-- **[P]** Purge (hard) — Deprecate AND delete files from disk (`{skill_package}` and `{forge_version}`, or full `{skill_group}` and `{forge_group}` for a skill-level drop). **Irreversible.**"
+- **[P]** Purge (hard) — Deprecate AND delete files from disk (`{skill_package}` and `{forge_version}`, or full `{skill_group}` and `{forge_group}` for a skill-level drop). **Irreversible.**
+- **[X]** Cancel and exit (or type `cancel` / `exit` / `:q`)"
 
 Wait for user selection.
 
+- If the user enters `cancel`, `exit`, `[X]`, `q`, or `:q`: Display "Cancelled — no changes were made." and HALT (exit code 6, `halt_reason: "user-cancelled"`).
+
 Set `drop_mode` to `"deprecate"` (on D) or `"purge"` (on P).
 
 ### 9. Compute Affected Directories
@@ -187,9 +198,27 @@ Store the list as `affected_directories`.
 
 If `drop_mode == "deprecate"`, record the list but present it as "retained" in the confirmation output — no deletion will occur.
 
+#### 9b. Compute Blast-Radius Metrics (for §10 summary)
+
+Compute three scalars to put in front of the path list at §10. The user's "I didn't know it would touch THAT" footgun is real — 12 paths can hide 50MB of on-disk content and a sweep across every IDE's managed section. A one-line summary makes the scale legible before the gate.
+
+1. **`versions_count`** — the number of skill versions in scope:
+   - Version-level drop: `len(target_versions)` (typically `1`)
+   - Skill-level drop: count of non-deprecated versions in `exports.{target_skill}.versions` (the deprecated ones are already absent from the active managed sections)
+
+2. **`bytes_total`** — recursive sum of byte sizes for every path in `affected_directories` that exists on disk. For each path, walk it and sum file sizes (`du -sb {path}` or equivalent). Skip non-existent paths silently — the §10 display is best-effort. Convert to a human-readable string for display (e.g. `"4.2 MB"`, `"812 KB"`); store the raw integer alongside as `bytes_total_raw` if a downstream step wants exact arithmetic. Defense in depth with execute.md §4 — that section will recompute per-path sizes for the canonical `disk_freed` reporting; this pre-compute is purely for the gate display and may slightly disagree if files change between gate and execute (acceptable for an "approximate" label).
+
+3. **`context_files_count`** — the number of distinct context files the §3 rebuild loop will rewrite:
+   - Read `config.yaml.ides`
+   - For each entry, look up its `context_file` via the canonical mapping table in `skf-export-skill/assets/managed-section-format.md` (use `AGENTS.md` fallback for unknown IDEs)
+   - Deduplicate by `context_file`
+   - Count the result. If `config.yaml.ides` is absent or empty, default to `1` (the AGENTS.md fallback)
+
+Store as `blast_radius = {versions_count, bytes_total, bytes_total_raw, context_files_count}` for §10's summary line.
+
 ### 10. Confirmation Gate
 
-Display the full operation summary:
+Display the full operation summary with the blast-radius summary line ahead of the path list so the user sees the scale before scanning paths:
 
 ```
 **About to drop:**
@@ -197,6 +226,7 @@ Display the full operation summary:
   Skill:   {target_skill}
   Version: {version or "ALL versions"}
   Mode:    {Deprecate (soft) | Purge (hard)}
+  Scope:   {versions_count} version(s), ~{bytes_total} on disk, will rebuild {context_files_count} context file(s)
   Files:
     {for each path in affected_directories, list one per line}
     {or "(retained on disk — soft drop)" if drop_mode == "deprecate"}
@@ -209,24 +239,42 @@ Display the full operation summary:
 Proceed? [Y/N]
 ```
 
+The `Scope:` line is the §9b-computed `blast_radius` rendered as one line. In `deprecate` mode the `~{bytes_total} on disk` reads as "size that will remain on disk (soft drop — files retained)"; the user is still served by knowing it. In `purge` mode it reads as "approximate disk that will be freed". The wording stays the same — the surrounding `Mode:` field disambiguates intent.
+
 **GATE [default: Y]** — If `{headless_mode}`: auto-proceed with [Y], log: "headless: auto-confirmed drop of {target_skill}"
 
 Wait for explicit user response.
 
+**If `--dry-run` was passed**: skip the Y/N prompt entirely. Display the `[DRY RUN]` line followed by a copy-pasteable selection memo so the user can capture this preview in their shell history and re-run it (interactively, picking the same values) when they're ready to commit:
+
+```
+**[DRY RUN] No changes were made — preview above shows what would be dropped.**
+
+To repeat this selection later:
+  Skill:   {target_skill}
+  Version: {target_versions[0] if is_skill_level == false else "all"}
+  Mode:    {Deprecate (soft) | Purge (hard)}
+
+Re-invoke `/skf-drop-skill {target_skill}` and re-select these values, or
+re-run with `--dry-run` to preview again.
+```
+
+Then emit the success envelope per SKILL.md "Result Contract (Headless)" with `status: "dry-run"`, the resolved `skill`, `drop_mode`, and `versions_affected`, then HALT (exit code 0). The manifest, filesystem, and context files are untouched.
+
 - **If `Y`** → proceed to section 11
-- **If `N`** → "**Cancelled.** No changes were made." HALT the workflow
+- **If `N`** (or `cancel` / `exit` / `[X]` / `:q`) → "**Cancelled.** No changes were made. (Tip: invoke with `--dry-run` next time to preview the operation without reaching the commit prompt.)" HALT (exit code 6, `halt_reason: "user-cancelled"`). In headless mode, emit the error envelope per SKILL.md "Result Contract (Headless)" with the resolved `skill`, `drop_mode`, and `versions_affected`.
 - **Any other input** → re-display the confirmation and ask again
 
 ### 11. Store Decisions in Context
 
-Store the following decisions in workflow context for step-02:
+Store the following decisions in workflow context for step 2:
 
 - `target_skill` — the skill name
 - `target_in_manifest` — boolean (true if the skill has a manifest entry, false if it was discovered only by on-disk scan)
 - `target_versions` — list of version strings (`[<version>]`) or the literal string `"all"`
 - `drop_mode` — `"deprecate"` or `"purge"` (always `"purge"` when `target_in_manifest = false`)
 - `is_skill_level` — boolean (true if all versions; always true when `target_in_manifest = false`)
-- `affected_directories` — list of absolute directory paths that step-02 will delete in purge mode (or retain in deprecate mode)
+- `affected_directories` — list of absolute directory paths that step 2 will delete in purge mode (or retain in deprecate mode)
 
 ### 12. Load Next Step
 

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

@@ -9,6 +9,15 @@ description: Package for distribution and inject context into CLAUDE.md/AGENTS.m
 
 Packages a completed skill as an agentskills.io-compliant package, generates context snippets, and updates the managed section in CLAUDE.md/.cursorrules/AGENTS.md for platform-aware context injection. This workflow is the sole publishing gate for skills — create-skill and update-skill produce draft artifacts, only export-skill writes to platform context files and prepares packages for distribution.
 
+## Conventions
+
+- Bare paths (e.g. `references/<name>.md`) resolve from the skill root.
+- `references/` holds prompt content carved out of SKILL.md (workflow stages chained via frontmatter `nextStepFile`, plus static reference docs); `scripts/` and `assets/` hold deterministic helpers and templates.
+- `{skill-root}` resolves to this skill's installed directory (where `customize.toml` lives, if present).
+- `{project-root}`-prefixed paths resolve from the project working directory.
+- `{skill-name}` resolves to the skill directory's basename.
+- **Cross-skill data coupling (export-skill is a hub):** `assets/managed-section-format.md` is loaded by `skf-drop-skill/references/execute.md` and `skf-rename-skill/references/execute.md` (IDE→context-file mapping table and four-case logic). `references/update-context.md` §4a manifest-schema documentation is the source of truth for the v2 schema enforced by `skf-manifest-ops.py`. Other skills depend on these files at install time — schema-breaking changes here require coordinated updates across at least three skills.
+
 ## Role
 
 You are a delivery and packaging specialist collaborating with a skill developer. You bring expertise in skill packaging, ecosystem compliance, and context injection patterns, while the user brings their completed skill and distribution requirements.
@@ -17,33 +26,57 @@ You are a delivery and packaging specialist collaborating with a skill developer
 
 These rules apply to every step in this workflow:
 
-- 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}`
+- At any interactive prompt, the inputs `cancel`, `exit`, `[X]`, `q`, or `:q` exit cleanly with exit code 6 (`halt_reason: "user-cancelled"`)
 - 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 | Load Skill | steps-c/step-01-load-skill.md | No (confirm) |
-| 2 | Package | steps-c/step-02-package.md | Yes |
-| 3 | Generate Snippet | steps-c/step-03-generate-snippet.md | Yes |
-| 4 | Update Context | steps-c/step-04-update-context.md | No (confirm) |
-| 5 | Token Report | steps-c/step-05-token-report.md | Yes |
-| 6 | Summary | steps-c/step-06-summary.md | Yes |
-| 7 | Workflow Health Check | steps-c/step-07-health-check.md | Yes |
+| 1 | Load Skill | references/load-skill.md | No (confirm) |
+| 2 | Package | references/package.md | Yes |
+| 3 | Generate Snippet | references/generate-snippet.md | Yes |
+| 4 | Update Context | references/update-context.md | No (confirm) |
+| 5 | Token Report | references/token-report.md | Yes |
+| 6 | Summary | references/summary.md | Yes |
+| 7 | Workflow Health Check | references/health-check.md | Yes |
 
 ## Invocation Contract
 
 | Aspect | Detail |
 |--------|--------|
-| **Inputs** | skill_name [one or more, required unless `--all`], `--all` [optional — exports every non-deprecated skill in `.export-manifest.json`] |
-| **Gates** | step-01: single Confirm Gate [C] for the whole batch | step-04: single Confirm Gate [C] for the whole batch |
-| **Outputs** | Updated .export-manifest.json (every skill in the batch), updated context files (CLAUDE.md/AGENTS.md/.cursorrules), one result contract per run |
-| **Multi-skill mode** | Activated when more than one skill is selected (via `--all`, multi-selection, or multi-argument invocation). See `steps-c/step-01-load-skill.md` §1c for the per-step iteration map. |
-| **Headless** | All gates auto-resolve with default action when `{headless_mode}` is true |
+| **Inputs** | `skill_name` [one or more, required unless `--all`] |
+| **Flags** | `--headless` / `-H` (auto-resolve all gates); `--all` (export every non-deprecated skill in `.export-manifest.json`); `--dry-run` (resolve and stage everything but exit before §4 writes to context files; envelope `status="dry-run"`) |
+| **Gates** | step 1: single Confirm Gate [C] for the whole batch | step 4: single Confirm Gate [C] for the whole batch |
+| **Outputs** | Updated `.export-manifest.json` (every skill in the batch), updated context files (CLAUDE.md/AGENTS.md/.cursorrules), per-skill `context-snippet.md`, per-run result contract `export-skill-result-{timestamp}.json` and `export-skill-result-latest.json` |
+| **Multi-skill mode** | Activated when more than one skill is selected (via `--all`, multi-selection, or multi-argument invocation). See `references/load-skill.md` §1c for the per-step iteration map. |
+| **Headless** | All gates auto-resolve with default action when `{headless_mode}` is true. Each auto-resolved gate appends a `{gate, default_action, taken_action, reason}` entry to `headless_decisions[]`, surfaced in step 6's `SKF_EXPORT_RESULT_JSON` envelope so non-interactive runs can be audited post-hoc. |
+| **Exit codes** | See "Exit Codes" below |
+
+## Exit Codes
+
+Every HARD HALT in this workflow exits with a stable code so headless automators can branch on the failure class without grepping message text:
+
+| Code | Meaning              | Raised by                                                                                    |
+| ---- | -------------------- | -------------------------------------------------------------------------------------------- |
+| 0    | success              | step 7 (terminal); also `status="dry-run"` when `--dry-run` is set                          |
+| 2    | input-missing / input-invalid | step 1 (no `skill_name` and no `--all` in headless) → `input-missing`; non-existent or malformed skill → `input-invalid` |
+| 3    | resolution-failure   | step 1 §2 (no skills found / required artifacts missing); step 1 §1c (multi-skill batch contains a stack-skill that requires re-composition) |
+| 4    | write-failure        | On-Activation §3 pre-flight write probe; step 4 §6 (managed-section rewrite); step 4 §9 (manifest write); step 6 §4 (result-contract write) |
+| 5    | state-conflict       | step 4 §3b/§4c.1 (orphan context-files or manifest-orphan rows when user selects [c] Cancel); step 4 (malformed `<!-- SKF:BEGIN/END -->` markers in target context file) |
+| 6    | user-cancelled       | step 1 §6 confirmation gate `[X]`/cancel; step 4 §8 confirmation gate `[X]`/cancel; any prompt that accepted `cancel`/`exit`/`:q` |
+
+## Result Contract (Headless)
+
+When `{headless_mode}` is true, step 6 emits a single-line JSON envelope on **stdout** before chaining to step 7, and every HARD HALT emits the same envelope shape on **stderr** with `status: "error"`:
+
+```
+SKF_EXPORT_RESULT_JSON: {"status":"success|error|dry-run","skills":[],"context_files_updated":[],"manifest_path":"…|null","headless_decisions":[],"exit_code":0,"halt_reason":null}
+```
+
+`status` is `"success"` on the terminal happy path, `"dry-run"` when `--dry-run` was set and the workflow exited before §4 writes, `"error"` on any HALT. `halt_reason` is one of: `null` (success / dry-run), `"input-missing"`, `"input-invalid"`, `"resolution-failure"`, `"stack-redirect"`, `"orphan-cancelled"`, `"malformed-markers"`, `"manifest-write-failed"`, `"context-rebuild-failed"`, `"write-failed"`, `"user-cancelled"`. `exit_code` matches the table above.
 
 ## On Activation
 
@@ -52,6 +85,42 @@ These rules apply to every step in this workflow:
    - `skills_output_folder`, `forge_data_folder`, `sidecar_path`
    - `snippet_skill_root_override` (optional string) — when set, overrides the IDE-derived `skill_root` for snippet `root:` paths. Authoring repos that keep all skills under a single on-disk folder (e.g. `skills/`) set this once so exported snippets reference the real layout instead of a per-IDE directory that does not exist. Consuming projects omit it.
 
-2. **Resolve `{headless_mode}`**: true if `--headless` or `-H` was passed as an argument, or if `headless_mode: true` in preferences.yaml. Default: false.
+2. **Compute run-scoped variables:**
+   - `timestamp` ← UTC `YYYYMMDD-HHmmss` captured at activation time. Fixed for the entire workflow run; summary.md reuses this when writing the result contract.
+
+3. **Resolve `{headless_mode}`**: true if `--headless` or `-H` was passed as an argument, or if `headless_mode: true` in `{sidecar_path}/preferences.yaml`. Default: false.
+
+4. **Resolve workflow customization.** Run:
+
+   ```bash
+   python3 {project-root}/_bmad/scripts/resolve_customization.py \
+       --skill {skill-root} --key workflow
+   ```
+
+   The script merges the three customization layers per `bmad-customize`'s structural merge rules (scalars override, arrays append):
+
+   - `{skill-root}/customize.toml` — bundled defaults
+   - `_bmad/custom/<skill-name>.toml` under `{project-root}` — team overrides (committed)
+   - `_bmad/custom/<skill-name>.user.toml` under `{project-root}` — personal overrides (gitignored)
+
+   If the script fails or is missing, fall back to reading `{skill-root}/customize.toml` directly — the bundled defaults are an empty string for each path scalar.
+
+   Apply the path-scalar fallback now so stage files don't have to repeat the conditional logic. For each scalar, if the merged value is empty or absent, use the bundled default:
+
+   - `{managedSectionFormatPath}` ← `workflow.managed_section_format_path` if non-empty, else `assets/managed-section-format.md`
+   - `{snippetFormatPath}` ← `workflow.snippet_format_path` if non-empty, else `assets/snippet-format.md`
+   - `{exportManifestPath}` ← `workflow.export_manifest_path` if non-empty, else `{skills_output_folder}/.export-manifest.json`
+
+   Stash all three as workflow-context variables. Stage files reference them directly — no conditional at the usage site.
+
+5. **Pre-flight write probe.** Verify `{skills_output_folder}` is writable. A read-only mount, full disk, or permissions-denied path otherwise only surfaces at step 4's managed-section rewrite — by then the user has already confirmed the batch:
+
+   ```bash
+   mkdir -p "{skills_output_folder}" && \
+     printf 'probe' > "{skills_output_folder}/.skf-write-probe" && \
+     rm "{skills_output_folder}/.skf-write-probe"
+   ```
+
+   On any non-zero exit: HALT (exit code 4, `halt_reason: "write-failed"`). In headless mode, emit the error envelope per **Result Contract (Headless)** with `skills: []`, `context_files_updated: []`, `manifest_path: null`.
 
-3. Load, read the full file, and then execute `./steps-c/step-01-load-skill.md` to begin the workflow.
+6. Load, read the full file, and then execute `references/load-skill.md` to begin the workflow.

package/src/skf-export-skill/assets/managed-section-format.md

@@ -70,14 +70,14 @@ All other IDEs use AGENTS.md as the context file, each with its own skill direct
 
 **`snippet_skill_root_override` (optional):** Authoring repos where all skills live under one shared on-disk directory (e.g. `skills/`) that does not match any per-IDE skill root may set `snippet_skill_root_override: skills/` in `config.yaml`. When set:
 
-- `export-skill/step-03` §2.7 uses the override as `{skill_root}` for snippet generation instead of the IDE-mapped value
-- `export-skill/step-04` §4d (and its equivalents in `drop-skill/step-02` and `rename-skill/step-02`) treat the override as the effective target prefix for the managed-section rebuild: snippets whose prefix already matches the override pass through unchanged, and any other prefix — including per-IDE prefixes carried by sibling snippets that were exported before the override was adopted, and legacy `skills/` drafts — is rewritten to the override so the rebuilt managed section uniformly references the real on-disk location
+- `export-skill/step 3` §2.7 uses the override as `{skill_root}` for snippet generation instead of the IDE-mapped value
+- `export-skill/step 4` §4d (and its equivalents in `drop-skill/step 2` and `rename-skill/step 2`) treat the override as the effective target prefix for the managed-section rebuild: snippets whose prefix already matches the override pass through unchanged, and any other prefix — including per-IDE prefixes carried by sibling snippets that were exported before the override was adopted, and legacy `skills/` drafts — is rewritten to the override so the rebuilt managed section uniformly references the real on-disk location
 
 Consuming projects (the common case) omit the field and keep the default IDE-mapping behavior. The override is a narrow escape hatch for repos that author skills into `{skills_output_folder}` and never duplicate them into `.claude/skills/`-style directories.
 
 ### Consumers
 
-This mapping is the single source of truth. Workflows that need it: `export-skill/step-01` (resolves `target_context_files` from config.yaml IDE list), `export-skill/step-04` (applies four-case logic and rewrites root paths when writing managed sections), `drop-skill/step-02` and `rename-skill/step-02` (rebuild context files after a management operation).
+This mapping is the single source of truth. Workflows that need it: `export-skill/step 1` (resolves `target_context_files` from config.yaml IDE list), `export-skill/step 4` (applies four-case logic and rewrites root paths when writing managed sections), `drop-skill/step 2` and `rename-skill/step 2` (rebuild context files after a management operation).
 
 ## Four-Case Logic
 

package/src/skf-export-skill/assets/snippet-format.md

@@ -4,9 +4,9 @@
 
 The snippet `root:` path must reflect the IDE's actual skill directory — its `skill_root` from the IDE → Context File Mapping table in `managed-section-format.md`. Each IDE has its own skill directory (e.g., `.claude/skills/`, `.windsurf/skills/`, `.github/skills/`).
 
-The root path in context-snippet.md on disk uses the **`skill_root` of the first entry in `target_context_files`** (resolved in step-01 from config.yaml IDE mapping). When assembling managed sections for other context files, step-04 rewrites root paths to match the target context file's skill root.
+The root path in context-snippet.md on disk uses the **`skill_root` of the first entry in `target_context_files`** (resolved in step 1 from config.yaml IDE mapping). When assembling managed sections for other context files, step 4 rewrites root paths to match the target context file's skill root.
 
-**Authoring-repo override:** If `snippet_skill_root_override` is set in `config.yaml`, it replaces the IDE-mapped value for snippet generation and freezes matching prefixes against step-04 rewrites. See the "Resolution rules" section in `managed-section-format.md` for the full semantics.
+**Authoring-repo override:** If `snippet_skill_root_override` is set in `config.yaml`, it replaces the IDE-mapped value for snippet generation and freezes matching prefixes against step 4 rewrites. See the "Resolution rules" section in `managed-section-format.md` for the full semantics.
 
 ## Format Rules
 

package/src/skf-export-skill/customize.toml

@@ -0,0 +1,49 @@
+# DO NOT EDIT -- overwritten on every update.
+#
+# Workflow customization surface for skf-export-skill.
+
+[workflow]
+
+# --- Configurable below. Overrides merge per BMad structural rules: ---
+#   scalars: override wins • arrays (persistent_facts, activation_steps_*): append
+#   arrays-of-tables with `code`/`id`: replace matching items, append new ones.
+
+# Steps to run before the standard activation (uv probe, config load).
+# Overrides append. Use for org-wide pre-flight checks (auth, network,
+# compliance) that must precede any export work.
+
+activation_steps_prepend = []
+
+# Steps to run after activation but before the first stage executes.
+# Overrides append. Use for context loads or banner customization that
+# should run once activation completes successfully.
+
+activation_steps_append = []
+
+# Persistent facts the workflow keeps in mind for the whole run
+# (publishing standards, distribution-instruction house style, snippet
+# token-budget guardrails). Overrides append.
+#
+# Each entry is either:
+#   - a literal sentence, e.g. "All exported skills must include a CHANGELOG entry."
+#   - a file reference prefixed with `file:`, e.g.
+#     "file:{project-root}/docs/export-policy.md" (globs supported; file
+#     contents are loaded and treated as facts).
+
+persistent_facts = [
+  "file:{project-root}/**/project-context.md",
+]
+
+# --- Optional asset overrides ---
+#
+# Lift the canonical asset paths so orgs can substitute house-style copies
+# without forking the skill. Empty string = use the bundled default.
+
+managed_section_format_path = ""
+snippet_format_path = ""
+
+# Override the manifest location. Empty = use
+# {skills_output_folder}/.export-manifest.json. Useful for orgs that want
+# a cross-project manifest at a stable path (e.g. ~/.skf/export-manifest.json).
+
+export_manifest_path = ""

package/src/skf-export-skill/{steps-c/step-03-generate-snippet.md → references/generate-snippet.md}

@@ -1,8 +1,10 @@
 ---
-nextStepFile: './step-04-update-context.md'
-snippetFormatData: 'assets/snippet-format.md'
+nextStepFile: 'update-context.md'
+snippetFormatData: '{snippetFormatPath}'
 ---
 
+<!-- Config: communicate in {communication_language}. Generate snippet content in {document_output_language}. -->
+
 # Step 3: Generate Snippet
 
 ## STEP GOAL:
@@ -12,16 +14,14 @@ To generate or update context-snippet.md for the skill in the Vercel-aligned ind
 ## Rules
 
 - Focus only on generating the context-snippet.md content — T1-now only, no T2 annotations
-- If `passive_context: false` was detected in step-01, skip this step entirely
-- **Multi-skill mode:** when step-01 loaded more than one skill (`len(skill_batch) > 1`), iterate sections 2–5 per skill. Each skill has its own prior-gotchas carry-forward state (§2.5) — do not share state across skills. §2.7 resolves `{skill_root}` once for the run (it depends on `target_context_files`, not the skill). See step-01 §1c.
+- If `passive_context: false` was detected in step 1, skip this step entirely
+- **Multi-skill mode:** when step 1 loaded more than one skill (`len(skill_batch) > 1`), iterate sections 2–5 per skill. Each skill has its own prior-gotchas carry-forward state (§2.5) — do not share state across skills. §2.7 resolves `{skill_root}` once for the run (it depends on `target_context_files`, not the skill). See step 1 §1c.
 
 ## MANDATORY SEQUENCE
 
-**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise unless user explicitly requests a change.
-
 ### 1. Check Passive Context Setting
 
-**If `passive_context: false` was detected in step-01:**
+**If `passive_context: false` was detected in step 1:**
 
 "**Passive context disabled in preferences.yaml. Skipping snippet generation.**"
 
@@ -37,7 +37,7 @@ Load {snippetFormatData} and read the format template for the skill type.
 
 Before generating new snippet content, check for a prior snippet:
 
-1. Read `{resolved_skill_package}/context-snippet.md` if it exists (resolved in step-01 — see `knowledge/version-paths.md`)
+1. Read `{resolved_skill_package}/context-snippet.md` if it exists (resolved in step 1 — see `knowledge/version-paths.md`)
 2. If it exists, extract the `|gotchas:` line (if any). Trim leading whitespace and the `|gotchas:` prefix, then capture the remaining content as `prior_gotchas_content`.
 3. **Detect the carry-forward marker:** If `prior_gotchas_content` starts with the token `[CARRIED]` (whitespace-insensitive), set `prior_gotchas_already_carried = true` and strip the marker before storing the remainder. Otherwise set `prior_gotchas_already_carried = false`.
 4. **Distinguish empty from absent:** If the `|gotchas:` line exists but has no non-whitespace content after the prefix, treat it as **absent** — set `prior_gotchas = null`. Only a non-empty value counts as a prior gotchas line worth carrying forward.
@@ -49,7 +49,7 @@ These values will be used as a fallback in section 3 if new gotchas cannot be de
 
 **If `snippet_skill_root_override` is set in config.yaml:** Use its value directly as `{skill_root}` and skip the IDE-mapping lookup below. This is the authoring-repo escape hatch — repos where skills live under a single shared directory (e.g. `skills/`) that does not match any per-IDE skill root. Log: "Using snippet_skill_root_override: `{override}` — bypassing IDE mapping for snippet root path."
 
-**Otherwise (default):** Using the first entry in `target_context_files` (resolved in step-01), take its `skill_root` value. This is the IDE's actual skill directory (e.g., `.claude/skills/`, `.windsurf/skills/`, `.github/skills/`).
+**Otherwise (default):** Using the first entry in `target_context_files` (resolved in step 1), take its `skill_root` value. This is the IDE's actual skill directory (e.g., `.claude/skills/`, `.windsurf/skills/`, `.github/skills/`).
 
 Store `{skill_root}` for use in snippet generation. The context-snippet.md written to disk uses this resolved skill root path.
 
@@ -65,7 +65,7 @@ Store `{skill_root}` for use in snippet generation. The context-snippet.md writt
 
    **Detect first-export state before applying carry-forward logic.** The `[CARRIED]` one-cycle expiry is meaningful only on a *re-export*. On a first export, the prior `context-snippet.md` was authored by `create-skill` (or `update-skill`) from the evidence report inside the same forge cycle — those gotchas are freshly derived, not "left over from a previous export." Treating them as carry-forward primes them for premature expiry on the second export.
 
-   Read `{skills_output_folder}/.export-manifest.json` (the same file step-04 §4a will rewrite). If the skill name is **absent** from `exports`, OR present with no resolvable `last_exported` for any version under `versions`, this is a first export — set `is_first_export = true`. Otherwise `is_first_export = false`. (Step-04 reads the manifest authoritatively for the rebuild; this read is the lightweight probe step-03 needs to choose the right branch below.)
+   Read `{skills_output_folder}/.export-manifest.json` (the same file step 4 §4a will rewrite). If the skill name is **absent** from `exports`, OR present with no resolvable `last_exported` for any version under `versions`, this is a first export — set `is_first_export = true`. Otherwise `is_first_export = false`. (Step-04 reads the manifest authoritatively for the rebuild; this read is the lightweight probe step 3 needs to choose the right branch below.)
 
    - **If new gotchas are derived:** Use them (they supersede any prior gotchas). Write as `|gotchas: {pitfall-1}, {pitfall-2}` with no marker.
    - **If NO new gotchas are derived AND `is_first_export == true` AND `prior_gotchas` exists:** Treat the prior gotchas as **freshly derived** by create-skill/update-skill — write them **without** the `[CARRIED]` marker. (The marker only applies to re-exports.) No warning needed; this is the normal first-export shape.
@@ -122,7 +122,7 @@ Estimate token count of generated snippet (approximate: words * 1.3).
 
 **Estimated tokens:** {count}"
 
-Hold content in context for step-04.
+Hold content in context for step 4.
 
 **If NOT dry-run:**
 

package/src/skf-export-skill/{steps-c/step-07-health-check.md → references/health-check.md}

@@ -1,10 +1,12 @@
 ---
-# `shared/health-check.md` resolves relative to the SKF module root
-# (`_bmad/skf/` when installed, `src/` during development), NOT relative
-# to this step file.
+# Note: `shared/health-check.md` resolves relative to the SKF module root
+# ({project-root}/_bmad/skf/ when installed, {project-root}/src/ during
+# development), NOT relative to this step file.
 nextStepFile: 'shared/health-check.md'
 ---
 
+<!-- Config: communicate in {communication_language}. -->
+
 # Step 7: Workflow Health Check
 
 ## STEP GOAL:
@@ -13,7 +15,7 @@ Chain to the shared workflow self-improvement health check at `{nextStepFile}`.
 
 ## Rules
 
-- No user-facing reports, file writes, or result contracts in this step — those belong in step-06
+- No user-facing reports, file writes, or result contracts in this step — those belong in step 6
 - Delegate directly to `{nextStepFile}` with no additional commentary
 - Do not attempt any other action between loading this step and executing `{nextStepFile}`