bmad-module-skill-forge 1.4.0 → 1.5.0

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

@@ -9,6 +9,14 @@ description: Fast skill from a package name or GitHub URL — no brief needed. U
 
 The fastest path to a skill — accept a GitHub URL or package name, resolve to source, extract the public API surface, and produce a best-effort SKILL.md with context snippet and metadata. No brief needed. Quick Skill is tier-unaware by design — all output is produced at community-tier quality regardless of available tools.
 
+## 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.
+
 ## Role
 
 You are a rapid skill compiler collaborating with a developer. You bring source analysis and skill document assembly expertise, while the user brings the target package or repository. Work together efficiently — speed is the priority.
@@ -18,37 +26,36 @@ You are a rapid skill compiler collaborating with a developer. You bring source
 These rules apply to every step in this workflow:
 
 - Never fabricate content — all data must come from source extraction or user input
-- 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}`
+- **Universal cancel-line affordance** — at any interactive prompt the user may type `cancel`, `exit`, `:q`, or select the `[X] Cancel and exit` menu option (where surfaced) to leave cleanly. HARD HALT with **exit code 6 (user-cancelled)** and emit the error result contract per "Result Contract on HARD HALT" with `error.code: "user-cancelled"`. In step 4 §6 the equivalent affordance is `[Q] Quit without writing` — same exit code, same envelope contract.
 - If `{headless_mode}` is true, auto-proceed through confirmation gates with their default action and log each auto-decision
 - If `{headless_mode}` is true, emit a single-line JSON progress event to **stderr** at each step's entry and exit so pipeline schedulers can stream live progress instead of post-mortem-parsing the result contract:
   - entry: `{"step":N,"name":"<slug>","status":"start"}`
   - exit (just before chaining to nextStepFile): `{"step":N,"name":"<slug>","status":"done"}`
   - on HARD HALT: `{"step":N,"name":"<slug>","status":"halt","exit":<code>}` instead of "done"
 
-  `N` is the step number (1–7) and `<slug>` is the kebab portion of the filename after the number — `resolve-target`, `ecosystem-check`, `quick-extract`, `compile`, `write-and-validate`, `finalize`, `health-check`. One line per event; do not pretty-print.
+  `N` is the step number and `<slug>` is the kebab portion of the filename (see the Stages table below for the canonical list). One line per event; do not pretty-print.
 
 ## Stages
 
 | # | Step | File | Auto-proceed |
 |---|------|------|--------------|
-| 1 | Resolve Target | steps-c/step-01-resolve-target.md | Yes |
-| 2 | Ecosystem Check | steps-c/step-02-ecosystem-check.md | Yes |
-| 3 | Quick Extract | steps-c/step-03-quick-extract.md | Yes |
-| 4 | Compile | steps-c/step-04-compile.md | No (review) |
-| 5 | Write & Validate | steps-c/step-05-write-and-validate.md | Yes |
-| 6 | Finalize | steps-c/step-06-finalize.md | Yes |
-| 7 | Workflow Health Check | steps-c/step-07-health-check.md | Yes |
+| 1 | Resolve Target | references/resolve-target.md | Yes |
+| 2 | Ecosystem Check | references/ecosystem-check.md | Yes |
+| 3 | Quick Extract | references/quick-extract.md | Yes |
+| 4 | Compile | references/compile.md | No (review) |
+| 5 | Write & Validate | references/write-and-validate.md | Yes |
+| 6 | Finalize | references/finalize.md | Yes |
+| 7 | Workflow Health Check | references/health-check.md | Yes |
 
 ## Invocation Contract
 
 | Aspect | Detail |
 |--------|--------|
 | **Inputs** | target (GitHub URL or package name) [required for single-target mode], language_hint [optional], scope_hint [optional] |
-| **Overrides** | `--description`, `--exports`, `--skip-snippet`, `--no-active-pointer`, `--batch <file>`, `--fail-fast` — see On Activation step 3 |
-| **Gates** | step-01: Input Gate [use args]; step-02: Choice Gate [P] (if match); step-04: Review Gate [C/E/S/Q] |
+| **Overrides** | `--description`, `--exports`, `--skip-snippet`, `--no-active-pointer`, `--batch <file>`, `--fail-fast` — see On Activation step 4 |
+| **Gates** | step 1: Input Gate [use args]; step 2: Choice Gate [P] (if match); step 4: Review Gate [C/E/S/Q] |
 | **Outputs** | SKILL.md, context-snippet.md, metadata.json, active pointer, result contract (timestamped + `-latest` copy). Snippet and active pointer can be skipped per overrides. |
 | **Headless** | All gates auto-resolve with default action when `{headless_mode}` is true |
 | **Exit codes** | See "Exit Codes" below |
@@ -59,18 +66,19 @@ Every HARD HALT in this workflow exits with a stable, documented code so headles
 
 | Code | Meaning                | Raised by                                                   |
 | ---- | ---------------------- | ----------------------------------------------------------- |
-| 0    | success                | step-07 (terminal)                                          |
-| 3    | resolution-failure     | step-01 §2c (prose input), step-01 §3 (registry chain failed) |
-| 4    | write-failure          | step-05 §2 (deliverable write failed)                       |
-| 5    | overwrite-cancelled    | step-05 §1 (user selected [N])                              |
-| 6    | compile-cancelled      | step-04 §6 (user selected [Q])                              |
-| 7    | finalize-blocked       | step-06 §1 (active-pointer flip refused — non-link in place) |
+| 0    | success                | step 7 (terminal)                                          |
+| 3    | resolution-failure     | step 1 §2c (prose input), step 1 §3 (registry chain failed) |
+| 4    | write-failure          | step 5 §2 (deliverable write failed)                       |
+| 5    | overwrite-cancelled    | step 5 §1 (user selected [N])                              |
+| 6    | user-cancelled         | step 1 §1 ([X] Cancel and exit, or cancel-line affordance); step 2 §3 ([A] Abort at ecosystem-match gate); step 4 §6 (user selected [Q]) — originally `compile-cancelled`, generalised to cover any interactive gate |
+| 7    | finalize-blocked       | step 6 §1 (active-pointer flip refused — non-link in place) |
+| 8    | ecosystem-redirect     | step 2 §3 ([I] Install at ecosystem-match gate — user opted to install the existing official skill instead of compiling a custom community skill) |
 
-Reserved: `validator-missing` may be promoted from advisory log to fatal exit code in a future revision; consumers should not assume code 8+ is unused.
+Reserved: `validator-missing` may be promoted from advisory log to fatal exit code in a future revision.
 
 ## Result Contract on HARD HALT
 
-In addition to the success-variant result contract written by step-06 §3, every HARD HALT must surface an **error variant** so headless automators don't silently break when `quick-skill-result-latest.json` is missing on failed runs.
+In addition to the success-variant result contract written by step 6 §3, every HARD HALT must surface an **error variant** so headless automators don't silently break when `quick-skill-result-latest.json` is missing on failed runs.
 
 **Always (every HARD HALT, regardless of phase)** — emit a single line on **stderr**:
 
@@ -80,14 +88,14 @@ SKF_QUICK_SKILL_RESULT_JSON: {"status":"error","exit_code":<N>,"phase":"<slug>",
 
 One line, no pretty-print. Matches the prefix-and-envelope convention used by `skf-emit-result-envelope.py`.
 
-**Additionally, when `{skill_package}` is known** (HALT at step-05 §1 onward) — write the same JSON object (without the `SKF_QUICK_SKILL_RESULT_JSON: ` prefix) to disk:
+**Additionally, when `{skill_package}` is known** (HALT at step 5 §1 onward) — write the same JSON object (without the `SKF_QUICK_SKILL_RESULT_JSON: ` prefix) to disk:
 
 ```
 {skill_package}/quick-skill-result-{YYYYMMDD-HHmmss}.json
 {skill_package}/quick-skill-result-latest.json   (copy, not symlink)
 ```
 
-so consumers that hardcode the `-latest.json` path see a deterministic file even on failed runs. HALTs at step-01/02/03/04 cannot write to disk because `{skill_package}` is computed only in step-05 §1; for those, the stderr envelope plus exit code is the contract.
+so consumers that hardcode the `-latest.json` path see a deterministic file even on failed runs. HALTs at step 1/02/03/04 cannot write to disk because `{skill_package}` is computed only in step 5 §1; for those, the stderr envelope plus exit code is the contract.
 
 **Schema:**
 
@@ -96,129 +104,61 @@ so consumers that hardcode the `-latest.json` path see a deterministic file even
 | `status`        | string         | always `"error"` for HARD HALTs                                                                             |
 | `exit_code`     | integer        | matches the Exit Codes table                                                                                |
 | `phase`         | string         | step slug where the HALT occurred (e.g. `resolve-target`, `compile`)                                        |
-| `error.code`    | string         | one of: `resolution-failure`, `write-failure`, `overwrite-cancelled`, `compile-cancelled`, `finalize-blocked` |
+| `error.code`    | string         | one of: `resolution-failure`, `write-failure`, `overwrite-cancelled`, `user-cancelled` (formerly `compile-cancelled`), `finalize-blocked`, `ecosystem-redirect` |
 | `error.message` | string         | the user-facing message that was displayed                                                                  |
 | `error.details` | any            | optional — phase-specific context (e.g. the failed file path)                                               |
 | `outputs`       | object         | empty `{}` on early HALTs; partial when files were already written                                          |
 | `summary`       | object         | empty `{}` on early HALTs                                                                                   |
-| `skill_package` | string \| null | absolute path when known, `null` when HALT preceded step-05 §1                                              |
+| `skill_package` | string \| null | absolute path when known, `null` when HALT preceded step 5 §1                                              |
 
 ## On Activation
 
-1. Read `{project-root}/_bmad/skf/config.yaml` and `{forger_root}/preferences.yaml` in parallel (one batched tool-call message — they are independent files), then resolve:
-   - From config: `project_name`, `output_folder`, `user_name`, `communication_language`, `document_output_language`, `skills_output_folder`, `forge_data_folder`
+1. Read `{project-root}/_bmad/skf/config.yaml` and `{sidecar_path}/preferences.yaml` in parallel (one batched tool-call message — they are independent files), then resolve:
+   - From config: `project_name`, `output_folder`, `user_name`, `communication_language`, `document_output_language`, `skills_output_folder`, `forge_data_folder`, `sidecar_path`
    - From preferences: `headless_mode` (default false)
 
 2. **Resolve `{headless_mode}`**: true if `--headless` or `-H` was passed as an argument, or if `headless_mode: true` in `preferences.yaml`. Default: false.
 
-3. **Parse CLI overrides** — capture optional override flags into the workflow context as `{overrides}`. Each override is opt-in; when omitted, the workflow runs as today.
-
-   | Flag | Effect |
-   | --- | --- |
-   | `--description "<string>"` | Override the LLM-derived description in step-04 §2 (used in SKILL.md frontmatter and metadata.json). Subject to the same agentskills.io length (1–1024 chars) and voice (third-person) checks as extracted descriptions. |
-   | `--exports "<name1,name2,...>"` | Override the extracted export list. Parse as comma-separated; trim whitespace per item; skip empty items. Used in step-04 §2 Key Exports and the count-derived metadata stats. |
-   | `--skip-snippet` | Skip context-snippet.md generation in step-04 §3 and its write in step-05 §2. Artifact omitted from `outputs`; step-05 §5 advisory snippet validation reports a "skipped" entry. |
-   | `--no-active-pointer` | Skip the active-pointer flip in step-06 §1. Deliverables still land in `{skill_package}` but `{skill_group}/active` is not updated. Useful for batch automators that flip pointers in a separate stage. |
-   | `--batch <file>` | Run the workflow against a list of targets from a text file rather than a single argument. Implies `--headless` (gates cannot be human-driven across N targets). See "Batch Mode" below for input format and summary contract. Single-target overrides above apply globally to every target in the batch. |
-   | `--fail-fast` | Only meaningful with `--batch`. Abort the whole batch on the first per-target failure instead of recording the failure in the summary and proceeding to the next target. |
-
-4. **If `--batch` is set**, force `{headless_mode} = true` (log "headless: coerced by --batch" if it was false), read the batch file, and parse the target list per "Batch Mode" below. Continue at step 5; the batch loop documented in "Batch Mode" wraps the step-01 → step-07 pipeline that follows.
-
-5. Load, read the full file, and then execute `./steps-c/step-01-resolve-target.md` to begin the workflow. (In batch mode, control returns here for each subsequent target after step-07 completes; see "Batch Mode" below.)
-
-## Batch Mode
-
-When `--batch <file>` is supplied, quick-skill processes a list of targets from a text file in sequence rather than a single target from arguments. Designed for unattended bulk runs (CI pipelines, mass-rebuilds, the skf-batch-skills meta-workflow when it lands).
-
-### Input format
-
-One target per line. Empty lines and lines starting with `#` (after optional leading whitespace) are ignored. Each non-empty line has the same shape as the single-target `target` argument, with optional space-separated per-line modifiers:
-
-```
-# A batch input file.
-lodash
-@vercel/og
-cognee@0.5.0
-https://github.com/foo/bar
-https://github.com/foo/bar@2.1.0-beta
-
-# Per-line modifiers — overrides for THIS target only:
-lodash language=javascript scope=src/
-cognee@0.5.0 language=python scope=cognee/api/
-```
-
-Recognised per-line modifiers:
-
-| Modifier | Effect (this target only) |
-| --- | --- |
-| `language=<lang>` | Sets `language_hint` for this target — same effect as the optional `language_hint` input on a single-target run. |
-| `scope=<path>` | Sets `scope_hint` for this target — same effect as the optional `scope_hint` input on a single-target run. |
-
-Per-line modifiers shadow the global `--description` / `--exports` / `--skip-snippet` / `--no-active-pointer` overrides only when those override fields are not set. Global overrides apply to every target unless a future modifier extends per-line override syntax.
-
-### Execution
+3. **Resolve workflow customization.** Run:
 
-`--batch` implies `--headless`. The batch loop runs the full quick-skill pipeline (steps 1–7) for each target in file order:
+   ```bash
+   python3 {project-root}/_bmad/scripts/resolve_customization.py \
+       --skill {skill-root} --key workflow
+   ```
 
-1. Set `target`, `target_version`, `language_hint`, `scope_hint` from the batch line into the workflow context.
-2. Execute steps 1–7 per the normal pipeline.
-3. After step-07 completes (success or HARD HALT), record the per-target outcome (target, status, exit_code, skill_package, error.code) into the batch result list.
-4. If `--fail-fast` is set and the target failed, exit the batch loop immediately. Otherwise continue with the next target.
+   The script merges the three customization layers per `bmad-customize`'s structural merge rules (scalars override, arrays append):
 
-Per-target output lands in `{skill_package}/` as today, with the per-target result contract at `{skill_package}/quick-skill-result-latest.json` (success or error variant per "Result Contract on HARD HALT" above).
+   - `{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)
 
-### Batch summary contract
+   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.
 
-After the last target completes (or `--fail-fast` triggers an early exit), write the batch summary at:
+   Apply the path-scalar fallback now so stage files don't have to repeat the conditional logic. For each of the three scalars, if the merged value is empty or absent, use the bundled default:
 
-```
-{skills_output_folder}/_batch/quick-skill-batch-{YYYYMMDD-HHmmss}.json
-{skills_output_folder}/_batch/quick-skill-batch-latest.json   (copy, not symlink)
-```
-
-Schema:
-
-```json
-{
-  "skill": "skf-quick-skill",
-  "mode": "batch",
-  "status": "success | partial | failed",
-  "timestamp": "<ISO 8601 UTC>",
-  "input_file": "<path passed to --batch>",
-  "targets_total": 0,
-  "succeeded": 0,
-  "failed": 0,
-  "fail_fast_triggered": false,
-  "results": [
-    {
-      "target": "<line from batch file>",
-      "status": "success | error",
-      "exit_code": 0,
-      "skill_package": "<absolute path or null>",
-      "error_code": null
-    }
-  ]
-}
-```
+   - `{skillTemplatePath}` ← `workflow.skill_template_path` if non-empty, else `assets/skill-template.md`
+   - `{registryResolutionPath}` ← `workflow.registry_resolution_path` if non-empty, else `references/registry-resolution.md`
+   - `{batchOutputPath}` ← `workflow.batch_output_path` if non-empty, else `{skills_output_folder}/_batch/`
 
-`status` resolves as: `"success"` when `failed == 0`; `"partial"` when `failed > 0 && succeeded > 0`; `"failed"` when `succeeded == 0`. `fail_fast_triggered` is `true` only when `--fail-fast` aborted the loop early — `targets_total` then reflects the count actually attempted, not the file's line count.
+   Stash all three as workflow-context variables. Stage files reference `{skillTemplatePath}` / `{registryResolutionPath}` / `{batchOutputPath}` directly — no conditional at the usage site. Empty-string overrides cleanly fall through to the bundled default; non-empty values let orgs swap in house-style copies without forking the skill.
 
-### Headless events
+4. **Parse CLI overrides** — capture optional override flags into the workflow context as `{overrides}`. Each override is opt-in; when omitted, the workflow runs as today.
 
-Batch mode emits per-target boundary events on stderr in addition to the per-step events documented in Workflow Rules:
+   | Flag | Effect |
+   | --- | --- |
+   | `--description "<string>"` | Override the LLM-derived description in step 4 §2 (used in SKILL.md frontmatter and metadata.json). Subject to the same agentskills.io length (1–1024 chars) and voice (third-person) checks as extracted descriptions. |
+   | `--exports "<name1,name2,...>"` | Override the extracted export list. Parse as comma-separated; trim whitespace per item; skip empty items. Used in step 4 §2 Key Exports and the count-derived metadata stats. |
+   | `--skip-snippet` | Skip context-snippet.md generation in step 4 §3 and its write in step 5 §2. Artifact omitted from `outputs`; step 5 §5 advisory snippet validation reports a "skipped" entry. |
+   | `--no-active-pointer` | Skip the active-pointer flip in step 6 §1. Deliverables still land in `{skill_package}` but `{skill_group}/active` is not updated. Useful for batch automators that flip pointers in a separate stage. |
+   | `--batch <file>` | Run the workflow against a list of targets from a text file rather than a single argument. Implies `--headless` (gates cannot be human-driven across N targets). See `references/batch-mode.md` for input format and summary contract. Single-target overrides above apply globally to every target in the batch. |
+   | `--fail-fast` | Only meaningful with `--batch`. Abort the whole batch on the first per-target failure instead of recording the failure in the summary and proceeding to the next target. |
 
-```
-{"batch":<n>,"target":"<target>","status":"start"}
-{"batch":<n>,"target":"<target>","status":"done","exit":<code>}
-{"batch":<n>,"target":"<target>","status":"fail","exit":<code>,"error_code":"<class>"}
-```
+5. **If `--batch` is set**, force `{headless_mode} = true` (log "headless: coerced by --batch" if it was false), then load and read `references/batch-mode.md` in full before proceeding. Follow its protocol to read the batch file, parse the target list, and drive the batch loop that wraps the step 1 → step 7 pipeline that follows.
 
-`<n>` is the 1-based index of the target in the parsed list. After the loop ends, emit one final batch-summary event:
+6. Load, read the full file, and then execute `references/resolve-target.md` to begin the workflow. (In batch mode, control returns here for each subsequent target after step 7 completes; see `references/batch-mode.md`.)
 
-```
-{"batch_summary":true,"targets_total":N,"succeeded":K,"failed":M,"status":"<...>","fail_fast_triggered":<bool>}
-```
+## Batch Mode
 
-### Exit code
+When `--batch <file>` is supplied, quick-skill processes a list of targets from a text file in sequence rather than a single argument.
 
-The batch process exits with code `0` when `failed == 0`, otherwise with the exit code of the first failed target (so automators that already branch on the single-target exit-code map continue to work without batch-specific handling). When `--fail-fast` triggers, the exit code is the failing target's code.
+See `references/batch-mode.md` for the full protocol (input format, execution loop, summary contract, headless events, exit code).

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

@@ -0,0 +1,44 @@
+# DO NOT EDIT -- overwritten on every update.
+#
+# Workflow customization surface for skf-quick-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 compilation 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
+# (house style, naming conventions, compilation guardrails).
+# Overrides append.
+#
+# Each entry is either:
+#   - a literal sentence, e.g. "All skills must cite their upstream source."
+#   - a file reference prefixed with `file:`, e.g.
+#     "file:{project-root}/docs/skill-style.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.
+
+skill_template_path = ""
+registry_resolution_path = ""
+batch_output_path = ""

package/src/skf-quick-skill/references/batch-mode.md

@@ -0,0 +1,102 @@
+---
+nextStepFile: 'resolve-target.md'
+---
+
+<!-- Config: communicate in {communication_language}. -->
+
+# Batch Mode
+
+When `--batch <file>` is supplied, quick-skill processes a list of targets from a text file in sequence rather than a single target from arguments. Designed for unattended bulk runs (CI pipelines, mass-rebuilds, the skf-batch-skills meta-workflow when it lands).
+
+## Input format
+
+One target per line. Empty lines and lines starting with `#` (after optional leading whitespace) are ignored. Each non-empty line has the same shape as the single-target `target` argument, with optional space-separated per-line modifiers:
+
+```
+# A batch input file.
+lodash
+@vercel/og
+cognee@0.5.0
+https://github.com/foo/bar
+https://github.com/foo/bar@2.1.0-beta
+
+# Per-line modifiers — overrides for THIS target only:
+lodash language=javascript scope=src/
+cognee@0.5.0 language=python scope=cognee/api/
+```
+
+Recognised per-line modifiers:
+
+| Modifier | Effect (this target only) |
+| --- | --- |
+| `language=<lang>` | Sets `language_hint` for this target — same effect as the optional `language_hint` input on a single-target run. |
+| `scope=<path>` | Sets `scope_hint` for this target — same effect as the optional `scope_hint` input on a single-target run. |
+
+Per-line modifiers shadow the global `--description` / `--exports` / `--skip-snippet` / `--no-active-pointer` overrides only when those override fields are not set. Global overrides apply to every target unless a future modifier extends per-line override syntax.
+
+## Execution
+
+`--batch` implies `--headless`. The batch loop runs the full quick-skill pipeline (steps 1–7) for each target in file order:
+
+1. Set `target`, `target_version`, `language_hint`, `scope_hint` from the batch line into the workflow context.
+2. Execute steps 1–7 per the normal pipeline.
+3. After step 7 completes (success or HARD HALT), record the per-target outcome (target, status, exit_code, skill_package, error.code) into the batch result list.
+4. If `--fail-fast` is set and the target failed, exit the batch loop immediately. Otherwise continue with the next target.
+
+Per-target output lands in `{skill_package}/` as today, with the per-target result contract at `{skill_package}/quick-skill-result-latest.json` (success or error variant per "Result Contract on HARD HALT" above).
+
+## Batch summary contract
+
+After the last target completes (or `--fail-fast` triggers an early exit), write the batch summary at:
+
+```
+{skills_output_folder}/_batch/quick-skill-batch-{YYYYMMDD-HHmmss}.json
+{skills_output_folder}/_batch/quick-skill-batch-latest.json   (copy, not symlink)
+```
+
+Schema:
+
+```json
+{
+  "skill": "skf-quick-skill",
+  "mode": "batch",
+  "status": "success | partial | failed",
+  "timestamp": "<ISO 8601 UTC>",
+  "input_file": "<path passed to --batch>",
+  "targets_total": 0,
+  "succeeded": 0,
+  "failed": 0,
+  "fail_fast_triggered": false,
+  "results": [
+    {
+      "target": "<line from batch file>",
+      "status": "success | error",
+      "exit_code": 0,
+      "skill_package": "<absolute path or null>",
+      "error_code": null
+    }
+  ]
+}
+```
+
+`status` resolves as: `"success"` when `failed == 0`; `"partial"` when `failed > 0 && succeeded > 0`; `"failed"` when `succeeded == 0`. `fail_fast_triggered` is `true` only when `--fail-fast` aborted the loop early — `targets_total` then reflects the count actually attempted, not the file's line count.
+
+## Headless events
+
+Batch mode emits per-target boundary events on stderr in addition to the per-step events documented in Workflow Rules:
+
+```
+{"batch":<n>,"target":"<target>","status":"start"}
+{"batch":<n>,"target":"<target>","status":"done","exit":<code>}
+{"batch":<n>,"target":"<target>","status":"fail","exit":<code>,"error_code":"<class>"}
+```
+
+`<n>` is the 1-based index of the target in the parsed list. After the loop ends, emit one final batch-summary event:
+
+```
+{"batch_summary":true,"targets_total":N,"succeeded":K,"failed":M,"status":"<...>","fail_fast_triggered":<bool>}
+```
+
+## Exit code
+
+The batch process exits with code `0` when `failed == 0`, otherwise with the exit code of the first failed target (so automators that already branch on the single-target exit-code map continue to work without batch-specific handling). When `--fail-fast` triggers, the exit code is the failing target's code.

package/src/skf-quick-skill/{steps-c/step-04-compile.md → references/compile.md}

@@ -1,14 +1,14 @@
 ---
-nextStepFile: './step-05-write-and-validate.md'
+nextStepFile: 'write-and-validate.md'
 skillTemplateData: 'assets/skill-template.md'
 quickMetadataRendererProbeOrder:
   - '{project-root}/_bmad/skf/shared/scripts/skf-render-quick-metadata.py'
   - '{project-root}/src/shared/scripts/skf-render-quick-metadata.py'
 ---
 
-# Step 4: Compile
+<!-- Config: communicate in {communication_language}. Generated SKILL.md text in {document_output_language}. -->
 
-Communicate with the user in `{communication_language}`. Compile generated content (descriptions, usage notes, summaries) in `{document_output_language}`.
+# Step 4: Compile
 
 ## STEP GOAL:
 
@@ -16,7 +16,7 @@ To assemble the best-effort SKILL.md document, context-snippet.md in Vercel-alig
 
 ## Rules
 
-- Focus only on assembling the three output documents — do not write files to disk (that's step-06)
+- Focus only on assembling the three output documents — do not write files to disk (that's step 6)
 - Follow template structure exactly from {skillTemplateData}
 - Mark any sections with insufficient data as best-effort
 
@@ -68,7 +68,7 @@ description: >
 
 ### 3. Generate Context Snippet
 
-**If `{overrides.skip_snippet}` is true** — skip generation and note in the §5 preview: "context-snippet.md skipped per `--skip-snippet` override." Step-05 §2 will skip the corresponding write; step-05 §5 advisory snippet validation will report a "skipped" entry.
+**If `{overrides.skip_snippet}` is true** — skip generation and note in the §5 preview: "context-snippet.md skipped per `--skip-snippet` override." Step-05 §2 will skip the corresponding write; step 5 §5 advisory snippet validation will report a "skipped" entry.
 
 Otherwise, create context-snippet.md in Vercel-aligned indexed format (~80-120 tokens):
 
@@ -97,14 +97,14 @@ Run the shared renderer against the assembled state. The helper applies the cons
 2. If absent, read `{project-root}/_bmad/skf/VERSION`
 3. If absent, set to `"unknown"`
 
-Build the input payload from the extraction inventory + step-01 resolution + the probed `tool_versions.skf` and pipe it to the renderer:
+Build the input payload from the extraction inventory + step 1 resolution + the probed `tool_versions.skf` and pipe it to the renderer:
 
 ```bash
 echo '{"name":"<name>","version":"<v>","description":"<desc>","language":"<lang>","source_repo":"<url>","source_root":"<path or empty>","source_commit":"<source_ref or empty>","source_package":"<package or name>","exports":[{"name":"...","type":"..."}],"dependencies":["..."],"compatibility":"<semver-range or empty>","language_hint":<hint or null>,"scope_hint":<hint or null>,"skf_version":"<probed>"}' \
   | python3 {quickMetadataRenderer}
 ```
 
-The renderer emits the rendered metadata.json on stdout. Capture the output as `metadata` for the §5 preview and step-05 §2's deliverable write.
+The renderer emits the rendered metadata.json on stdout. Capture the output as `metadata` for the §5 preview and step 5 §2's deliverable write.
 
 **Schema is canonical in the renderer.** When `{skillTemplateData}` adds a field, the renderer is updated to populate it (constants gain a row; input-derived fields gain a payload key). Do not hand-edit the rendered envelope here — the helper is the single source of truth for the population logic.
 
@@ -153,8 +153,8 @@ Display: **Select:** [C] Continue to Validation · [E] Edit description · [S] A
 
 - **IF C** — Load, read entire file, then execute {nextStepFile}.
 - **IF E** — Ask the user for a replacement description ("New description (1–1024 chars):"). Update SKILL.md frontmatter `description` and `metadata.json.description` in the in-memory compiled output, then re-render the §5 preview and redisplay this menu. Do not re-run extraction.
-- **IF S** — Ask the user for an adjusted `scope_hint` ("New scope (e.g. `src/server/`, `packages/core/`):") and optionally a `language_hint`. Update the extraction context with the new hints, then load `./step-03-quick-extract.md` to re-extract. The new extraction returns to §1 of this step on completion. Discards the prior compiled output.
-- **IF Q** — HARD HALT with **exit code 6 (compile-cancelled)** per the SKILL.md exit-code map: "Compilation cancelled. No files written." Before exiting, emit the error result contract per SKILL.md "Result Contract on HARD HALT" (`phase: "compile"`, `error.code: "compile-cancelled"`, `skill_package: null`). Do not proceed to validation; do not write any artifacts.
+- **IF S** — Ask the user for an adjusted `scope_hint` ("New scope (e.g. `src/server/`, `packages/core/`):") and optionally a `language_hint`. Update the extraction context with the new hints, then load `quick-extract.md` to re-extract. The new extraction returns to §1 of this step on completion. Discards the prior compiled output.
+- **IF Q** — HARD HALT with **exit code 6 (user-cancelled)** per the SKILL.md exit-code map: "Compilation cancelled. No files written." Before exiting, emit the error result contract per SKILL.md "Result Contract on HARD HALT" (`phase: "compile"`, `error.code: "user-cancelled"`, `skill_package: null`). Do not proceed to validation; do not write any artifacts.
 - **IF Any other** — Help the user adjust the compiled output (treated as a free-form revision request), then redisplay the menu.
 
 #### EXECUTION RULES:
@@ -163,7 +163,7 @@ Display: **Select:** [C] Continue to Validation · [E] Edit description · [S] A
 - **GATE [default: C]** — If `{headless_mode}`: auto-proceed with [C] Continue, log: "headless: auto-approve compiled output"
 - ONLY proceed to validation when the user selects 'C' (or headless auto-approve)
 - [E] is local: re-renders the preview without re-running extraction
-- [S] is the heavy option: it discards the compiled output and re-runs step-03 with new hints
+- [S] is the heavy option: it discards the compiled output and re-runs step 3 with new hints
 
 ## CRITICAL STEP COMPLETION NOTE
 

package/src/skf-quick-skill/{steps-c/step-02-ecosystem-check.md → references/ecosystem-check.md}

@@ -1,10 +1,10 @@
 ---
-nextStepFile: './step-03-quick-extract.md'
+nextStepFile: 'quick-extract.md'
 ---
 
-# Step 2: Ecosystem Check
+<!-- Config: communicate in {communication_language}. -->
 
-Communicate with the user in `{communication_language}`.
+# Step 2: Ecosystem Check
 
 ## STEP GOAL:
 
@@ -59,8 +59,8 @@ An official skill already exists. You can:
 #### Menu Handling Logic:
 
 - IF P: Set `ecosystem_status: match-proceed`, then load, read entire file, then execute {nextStepFile}
-- IF I: Display install instructions for the official skill, then end workflow
-- IF A: Display "Compilation cancelled." and end workflow
+- IF I: Display install instructions for the official skill, emit the HARD HALT envelope per SKILL.md "Result Contract on HARD HALT" (`phase: "ecosystem-check"`, `error.code: "ecosystem-redirect"`, `error.message: "User opted to install existing official skill instead of compiling a custom community skill."`, `skill_package: null`), exit with code 8 (ecosystem-redirect). Skill package is unknown at this phase — no on-disk result file is written.
+- IF A: Display "Compilation cancelled.", emit the HARD HALT envelope (`phase: "ecosystem-check"`, `error.code: "user-cancelled"`, `error.message: "User aborted at ecosystem-match gate."`, `skill_package: null`), exit with code 6 (user-cancelled). Skill package is unknown at this phase — no on-disk result file is written.
 - IF Any other: help user, then redisplay the match menu
 
 #### EXECUTION RULES:

package/src/skf-quick-skill/{steps-c/step-06-finalize.md → references/finalize.md}

@@ -1,21 +1,21 @@
 ---
-nextStepFile: './step-07-health-check.md'
+nextStepFile: 'health-check.md'
 atomicWriteProbeOrder:
   - '{project-root}/_bmad/skf/shared/scripts/skf-atomic-write.py'
   - '{project-root}/src/shared/scripts/skf-atomic-write.py'
 ---
 
-# Step 6: Finalize
+<!-- Config: communicate in {communication_language}. Generated SKILL.md text in {document_output_language}. -->
 
-Communicate with the user in `{communication_language}`. Render the user-facing completion summary content in `{document_output_language}`.
+# Step 6: Finalize
 
 ## STEP GOAL:
 
-To finalize the skill by creating the active-version pointer, displaying the completion summary, and writing the result contract. Deliverables (SKILL.md, context-snippet.md, metadata.json) were already written in step-05 so that validation could run against files on disk; this step only performs the post-write finalization.
+To finalize the skill by creating the active-version pointer, displaying the completion summary, and writing the result contract. Deliverables (SKILL.md, context-snippet.md, metadata.json) were already written in step 5 so that validation could run against files on disk; this step only performs the post-write finalization.
 
 ## Rules
 
-- Do not rewrite deliverables — they were written and validated in step-05
+- Do not rewrite deliverables — they were written and validated in step 5
 - Create the active pointer via the shared helper — never `rm` + `ln -s` manually
 - Result contract writing is mandatory (pipeline consumers depend on it)
 
@@ -25,7 +25,7 @@ To finalize the skill by creating the active-version pointer, displaying the com
 
 **If `{overrides.no_active_pointer}` is true** — skip the helper invocation entirely. Log: "Active pointer: skipped per `--no-active-pointer` override." Do not update `{skill_group}/active`. Proceed to §2 with the active-pointer line omitted from the completion summary and the outputs payload.
 
-`{skill_group}` and `{skill_package}` were computed in step-05 §1 from `{skills_output_folder}`, `{repo_name}`, and `{version}`; `{version}` was resolved from the extraction inventory. Reuse the same values here — do not recompute.
+`{skill_group}` and `{skill_package}` were computed in step 5 §1 from `{skills_output_folder}`, `{repo_name}`, and `{version}`; `{version}` was resolved from the extraction inventory. Reuse the same values here — do not recompute.
 
 Create or update the `active` pointer at `{skill_group}/active` pointing to `{version}` using the shared atomic-flip helper. The helper acquires an `flock` on `{skill_group}/active.skf-lock`, refuses to replace a non-link at `{skill_group}/active` (protecting against accidental `rm -rf` of a real directory), and uses a rename-over-symlink pattern so the update is atomic from a concurrent reader's perspective. On Windows the helper automatically falls back to a directory junction (`mklink /J`) when `os.symlink` fails with `PRIVILEGE_NOT_HELD` / `ACCESS_DENIED` — junctions require no admin elevation and resolve identically for `skf-skill-inventory`'s consumers:
 
@@ -37,7 +37,7 @@ python3 {atomicWriteHelper} flip-link \
   --target {version}
 ```
 
-The helper returns non-zero (helper exit 2) if `{skill_group}/active` already exists as a real directory or file rather than a link — in that case, HARD HALT the workflow with **exit code 7 (finalize-blocked)** per the SKILL.md exit-code map: "Refusing to flip `{skill_group}/active` — existing path is not a symlink or junction. Investigate manually; expected a link pointing at a version directory." Before exiting, emit the error result contract per SKILL.md "Result Contract on HARD HALT" (`phase: "finalize"`, `error.code: "finalize-blocked"`, `skill_package` set, `outputs` listing the deliverables already on disk from step-05). A common cause on Windows is a prior run that executed `ln -s` under git-bash without Developer Mode enabled, which silently wrote a full directory copy; remove that copy and retry.
+The helper returns non-zero (helper exit 2) if `{skill_group}/active` already exists as a real directory or file rather than a link — in that case, HARD HALT the workflow with **exit code 7 (finalize-blocked)** per the SKILL.md exit-code map: "Refusing to flip `{skill_group}/active` — existing path is not a symlink or junction. Investigate manually; expected a link pointing at a version directory." Before exiting, emit the error result contract per SKILL.md "Result Contract on HARD HALT" (`phase: "finalize"`, `error.code: "finalize-blocked"`, `skill_package` set, `outputs` listing the deliverables already on disk from step 5). A common cause on Windows is a prior run that executed `ln -s` under git-bash without Developer Mode enabled, which silently wrote a full directory copy; remove that copy and retry.
 
 **Never `rm` + `ln -s` the active pointer manually.** The bare-rm pattern has two failure modes: (1) a concurrent reader sees a missing `active` mid-flip, and (2) a bug or typo that replaces `{skill_group}/active` with a plain directory turns the next manual `rm -rf {skill_group}/active` into data loss. The helper encapsulates both guards and the Windows junction fallback.
 

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

@@ -5,9 +5,9 @@
 nextStepFile: 'shared/health-check.md'
 ---
 
-# Step 7: Workflow Health Check
+<!-- Config: communicate in {communication_language}. -->
 
-Communicate with the user in `{communication_language}`.
+# Step 7: Workflow Health Check
 
 ## STEP GOAL:
 
@@ -15,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}`