bmad-module-skill-forge 2.0.0 → 2.0.1

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

@@ -7,7 +7,7 @@ description: Fast skill from a package name or GitHub URL — no brief needed. U
 
 ## Overview
 
-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.
+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. Output is always community-tier quality, regardless of which tools are available.
 
 ## Conventions
 
@@ -28,7 +28,7 @@ These rules apply to every step in this workflow:
 - Never fabricate content — all data must come from source extraction or user input
 - 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.
+- **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 `references/halt-contract.md` 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"}`
@@ -55,61 +55,14 @@ These rules apply to every step in this workflow:
 |--------|--------|
 | **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 4 |
-| **Gates** | step 1: Input Gate [use args]; step 2: Choice Gate [P] (if match); step 4: Review Gate [C/E/S/Q] |
+| **Gates** | step 1: target input, multi-language disambiguation [C/A]; step 2: ecosystem match [P/I/A] (if match); step 3: repo-shape [C/A] + zero-exports rescue [R/P/A]; step 4: review [C/E/S/Q]; step 5: overwrite [Y/N] |
 | **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 |
+| **Exit codes** | See `references/halt-contract.md` |
 
-## Exit Codes
+## Exit Codes & HARD HALT Contract
 
-Every HARD HALT in this workflow exits with a stable, documented code so headless automators can branch on the failure class without grepping message text:
-
-| Code | Meaning                | Raised by                                                   |
-| ---- | ---------------------- | ----------------------------------------------------------- |
-| 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.
-
-## Result Contract on HARD HALT
-
-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**:
-
-```
-SKF_QUICK_SKILL_RESULT_JSON: {"status":"error","exit_code":<N>,"phase":"<slug>","error":{"code":"<class>","message":"<short>"},"outputs":{},"summary":{},"skill_package":"<path-or-null>"}
-```
-
-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 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 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:**
-
-| Field           | Type           | Notes                                                                                                       |
-| --------------- | -------------- | ----------------------------------------------------------------------------------------------------------- |
-| `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`, `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 5 §1                                              |
+See `references/halt-contract.md` for the exit-code map and the error-result envelope every HARD HALT emits (the `SKF_QUICK_SKILL_RESULT_JSON:` stderr line, the on-disk `-latest.json` write once `{skill_package}` is known, and the schema). Steps load it on their failure path so the wire format survives compaction.
 
 ## On Activation
 
@@ -139,8 +92,11 @@ so consumers that hardcode the `-latest.json` path see a deterministic file even
    - `{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/`
+   - `{onCompleteCommand}` ← `workflow.on_complete` if non-empty, else empty (no-op — step 6 §3 skips the hook invocation entirely)
 
-   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.
+   Stash all four as workflow-context variables. Stage files reference `{skillTemplatePath}` / `{registryResolutionPath}` / `{batchOutputPath}` / `{onCompleteCommand}` 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 (custom template, registry chain, batch output dir) or wire in a post-completion hook (git-add, register, notify) without forking the skill.
+
+   **Apply the array surfaces** so the declared overrides are not silent no-ops: execute each entry in `workflow.activation_steps_prepend` in order now; treat every entry in `workflow.persistent_facts` as standing context for the whole run (`file:`-prefixed entries are paths or globs whose contents load as facts — the bundled default loads any `project-context.md`); then, after activation completes and before the first stage runs, execute each entry in `workflow.activation_steps_append` in order.
 
 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.
 
@@ -156,9 +112,3 @@ so consumers that hardcode the `-latest.json` path see a deterministic file even
 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.
 
 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 Mode
-
-When `--batch <file>` is supplied, quick-skill processes a list of targets from a text file in sequence rather than a single argument.
-
-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

@@ -1,6 +1,8 @@
 # DO NOT EDIT -- overwritten on every update.
 #
 # Workflow customization surface for skf-quick-skill.
+# Team overrides:     _bmad/custom/skf-quick-skill.toml (under {project-root})
+# Personal overrides: _bmad/custom/skf-quick-skill.user.toml (under {project-root})
 
 [workflow]
 
@@ -42,3 +44,10 @@ persistent_facts = [
 skill_template_path = ""
 registry_resolution_path = ""
 batch_output_path = ""
+
+# Optional post-completion hook. When non-empty, invoked with
+# `--skill-package=<path>` after the result contract is finalized in step 6.
+# Failures are logged but never fail the workflow. Use for git-add,
+# skill-registry registration, or a notifier on the freshly compiled skill.
+
+on_complete = ""

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

@@ -6,7 +6,7 @@ nextStepFile: 'resolve-target.md'
 
 # 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).
+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, and batch meta-workflows.
 
 ## Input format
 
@@ -43,17 +43,19 @@ Per-line modifiers shadow the global `--description` / `--exports` / `--skip-sni
 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).
+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 `references/halt-contract.md`).
 
 ## 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)
+{batchOutputPath}quick-skill-batch-{YYYYMMDD-HHmmss}.json
+{batchOutputPath}quick-skill-batch-latest.json   (copy, not symlink)
 ```
 
+`{batchOutputPath}` is resolved at SKILL.md On Activation §3 from `workflow.batch_output_path` (bundled default `{skills_output_folder}/_batch/`, trailing slash included).
+
 Schema:
 
 ```json

package/src/skf-quick-skill/references/compile.md

@@ -1,6 +1,6 @@
 ---
 nextStepFile: 'write-and-validate.md'
-skillTemplateData: 'assets/skill-template.md'
+skillTemplateData: '{skillTemplatePath}'
 quickMetadataRendererProbeOrder:
   - '{project-root}/_bmad/skf/shared/scripts/skf-render-quick-metadata.py'
   - '{project-root}/src/shared/scripts/skf-render-quick-metadata.py'
@@ -20,7 +20,7 @@ To assemble the best-effort SKILL.md document, context-snippet.md in Vercel-alig
 - Follow template structure exactly from {skillTemplateData}
 - Mark any sections with insufficient data as best-effort
 
-## MANDATORY SEQUENCE
+## Steps
 
 ### 1. Load Skill Template
 
@@ -31,57 +31,28 @@ Load {skillTemplateData} to understand:
 
 ### 2. Assemble SKILL.md
 
-Using the template structure, populate each section from extraction_inventory:
+Populate the SKILL.md section structure from `{skillTemplateData}` § "SKILL.md Section Structure" (the frontmatter skeleton and the Required/Optional section list live there) using extraction_inventory. The rules below are the deltas the template does not encode:
 
-**Frontmatter (REQUIRED — agentskills.io compliance):**
-
-The SKILL.md MUST begin with YAML frontmatter:
-
-```yaml
----
-name: {skill_name}
-description: >
-  {Trigger-optimized description from extraction_inventory.description.
-  1-1024 chars. Include what it does, when to use it, and what NOT to use it for.}
----
-```
-
-**Frontmatter rules:**
+**Frontmatter rules (agentskills.io compliance):**
 - `name`: lowercase alphanumeric + hyphens only, must match the skill output directory name. Prefer gerund form (`processing-pdfs`) for clarity.
-- `description`: non-empty, max 1024 chars, optimized for agent discovery. MUST use third-person voice ("Processes..." not "I can..." or "You can...").
+- `description`: non-empty, max 1024 chars, optimized for agent discovery. Use third-person voice ("Processes..." not "I can..." / "You can...") so it reads correctly in the agent's skill index.
 - No other frontmatter fields — only `name` and `description` for community skills
 
-**Required sections (after frontmatter):**
-- **Overview:** Package name, repository, language, source authority, generation date
+**Per-section override wiring:**
 - **Description:** From `{overrides.description}` if set (subject to the same length/voice checks as extracted descriptions); otherwise from extraction_inventory.description (README-derived)
 - **Key Exports:** From `{overrides.exports}` if set (comma-separated names parsed and trimmed; empty items skipped); otherwise from extraction_inventory.exports — list each with name, type, brief description
-- **Usage Patterns:** From extraction_inventory.usage_patterns (README examples)
 
-**Optional sections (include when data available):**
-- **Configuration:** If configuration options were found in source
-- **Dependencies:** Key dependencies from manifest
-- **Notes:** Caveats, limitations, extraction confidence level
-- **Scripts & Assets Note** (if source contains `scripts/`, `bin/`, `assets/`, `templates/`, or `schemas/` directories): "This package may include scripts and assets. Run create-skill for full extraction with provenance tracking."
+**Scripts & Assets Note** (add as an optional section if source contains `scripts/`, `bin/`, `assets/`, `templates/`, or `schemas/` directories): "This package may include scripts and assets. Run create-skill for full extraction with provenance tracking."
 
-**If confidence is low:**
-- Include a note: "This skill was generated with limited source data. Consider running create-skill for a more thorough compilation."
+**If confidence is low** — include a note: "This skill was generated with limited source data. Consider running create-skill for a more thorough compilation."
 
 ### 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 5 §5 advisory snippet validation will report a "skipped" entry.
 
-Otherwise, create context-snippet.md in Vercel-aligned indexed format (~80-120 tokens):
+Otherwise, produce context-snippet.md in the Vercel-aligned indexed format from `{skillTemplateData}` § "context-snippet.md Format" (~80-120 tokens).
 
-```
-[{skill_name} v{version}]|root: skills/{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#usage-patterns}
-|api: {top-5 exports with () for functions}
-|key-types:{SKILL.md#key-exports} — {inline summary of most important type values}
-|gotchas: {2-3 most critical pitfalls or breaking changes, inline}
-```
-
-The anchors point to the QS template's actual headings — `#usage-patterns` (Usage Patterns) and `#key-exports` (Key Exports). The QS template has no `## Quick Start` / `## Key Types` headings (those are Deep-tier sections), so the Deep-tier anchors `#quick-start` / `#key-types` would dangle. If the assembled SKILL.md is missing the referenced heading, omit that line rather than emit a dangling anchor.
+The snippet anchors point to the QS template's actual headings — `#usage-patterns` (Usage Patterns) and `#key-exports` (Key Exports). The QS template has no `## Quick Start` / `## Key Types` headings (those are Deep-tier sections), so the Deep-tier anchors `#quick-start` / `#key-types` would dangle. If the assembled SKILL.md is missing the referenced heading, omit that line rather than emit a dangling anchor.
 
 **If fewer than 5 exports:** Use all available exports.
 **If no exports:** Omit the api line.
@@ -91,7 +62,7 @@ The anchors point to the QS template's actual headings — `#usage-patterns` (Us
 
 Run the shared renderer against the assembled state. The helper applies the constants, echoes input-derived fields, computes export counts and the ISO 8601 UTC timestamp, and emits the canonical envelope per `{skillTemplateData}` § "metadata.json Format".
 
-**Resolve `{quickMetadataRenderer}`** from `{quickMetadataRendererProbeOrder}`; first existing path wins. If no candidate exists, fall back to in-prompt rendering using the constants + input-derived rules previously documented in this section (the helper replaces but does not eliminate those rules — they live in the helper now).
+**Resolve `{quickMetadataRenderer}`** from `{quickMetadataRendererProbeOrder}`; first existing path wins. If no candidate exists, fall back to in-prompt rendering of the canonical envelope per `{skillTemplateData}` § "metadata.json Format".
 
 **Probe `tool_versions.skf` first** (the helper expects it as input — the filesystem walk stays here because the helper does no I/O):
 
@@ -108,8 +79,6 @@ echo '{"name":"<name>","version":"<v>","description":"<desc>","language":"<lang>
 
 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.
-
 ### 5. Present Compiled Output for Review
 
 **If `{headless_mode}` is true** — skip the inline preview (no human reviewer reads it) and emit a one-line summary instead:
@@ -156,18 +125,12 @@ 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 `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 Q** — HARD HALT with **exit code 6 (user-cancelled)** per the exit-code map in `references/halt-contract.md`: "Compilation cancelled. No files written." Before exiting, emit the error result contract per `references/halt-contract.md` (`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:
+#### Gate:
 
-- ALWAYS halt and wait for user input after presenting compiled output
+- Halt and wait for user input after presenting the compiled output; only [C] (or a headless auto-approve) chains to `{nextStepFile}` for validation.
 - **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 3 with new hints
-
-## CRITICAL STEP COMPLETION NOTE
-
-ONLY WHEN the user reviews the compiled output and selects 'C' (or [Q] HALTs / [S] re-runs / [E] redisplays) will you load and read fully `{nextStepFile}` to execute validation.
+- [E] re-renders the preview without re-running extraction; [S] discards the compiled output and re-runs step 3 with new hints.
 

package/src/skf-quick-skill/references/ecosystem-check.md

@@ -12,11 +12,10 @@ To query the agentskills.io ecosystem for an existing official skill matching th
 
 ## Rules
 
-- This check is advisory — never block the workflow on failure
 - 5-second timeout on ecosystem queries; tool unavailability is a silent skip, not an error
 - Do not begin extraction or compilation
 
-## MANDATORY SEQUENCE
+## Steps
 
 ### 1. Query Ecosystem
 
@@ -54,34 +53,20 @@ An official skill already exists. You can:
 **[I] Install** — Install the existing official skill instead (exits this workflow)
 **[A] Abort** — Cancel compilation"
 
-### 3. Handle Match Menu (ONLY if match found)
+### 3. Handle Match Menu (only when a match was found)
 
 #### 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, 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 I: Display install instructions for the official skill, emit the HARD HALT envelope per `references/halt-contract.md` (`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:
+#### Gate:
 
-- ONLY display this menu when ecosystem_status is match
-- ALWAYS halt and wait for user input when match is found
 - **GATE [default: P]** — If `{headless_mode}` and match found: auto-proceed with [P] Proceed (compile custom skill anyway), log: "headless: ecosystem match found, auto-proceeding with custom compilation"
-- For no-match and skip cases, auto-proceed without menu
 
 ### 4. Auto-Proceed (No Match or Skip)
 
-#### Menu Handling Logic:
-
-- After no-match or skip determination, immediately load, read entire file, then execute {nextStepFile}
-
-#### EXECUTION RULES:
-
-- This is an auto-proceed path — no user interaction needed
-- Proceed directly to extraction step
-
-## CRITICAL STEP COMPLETION NOTE
-
-ONLY WHEN ecosystem check completes (match with user choice, no-match, or skip) will you load and read fully `{nextStepFile}` to proceed to source extraction.
+For no-match and skip, load and execute {nextStepFile} to proceed to source extraction.
 

package/src/skf-quick-skill/references/finalize.md

@@ -19,7 +19,7 @@ To finalize the skill by creating the active-version pointer, displaying the com
 - Create the active pointer via the shared helper — never `rm` + `ln -s` manually
 - Result contract writing is mandatory (pipeline consumers depend on it)
 
-## MANDATORY SEQUENCE
+## Steps
 
 ### 1. Create Active Pointer (atomic flip, Windows-safe)
 
@@ -29,7 +29,7 @@ To finalize the skill by creating the active-version pointer, displaying the com
 
 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:
 
-**Resolve `{atomicWriteHelper}`** from `{atomicWriteProbeOrder}`; first existing path wins. HALT if no candidate exists — the active-pointer flip MUST go through the atomic helper.
+**Resolve `{atomicWriteHelper}`** from `{atomicWriteProbeOrder}`; first existing path wins. If no candidate exists, skip the flip the same way `--no-active-pointer` does: log "Active pointer: skipped — atomic-write helper unavailable", omit the active-pointer line from the completion summary and outputs, and record `active_pointer: "skipped-helper-missing"` in the result-contract summary (§3) so consumers see why the pointer is absent. The deliverables are already on disk, so a missing helper degrades to "no pointer" rather than a failed run. There is no manual fallback: a hand-rolled `rm` + `ln -s` loses the helper's atomicity and non-link guard, risking a half-flipped pointer or an `rm -rf` into a real directory.
 
 ```bash
 python3 {atomicWriteHelper} flip-link \
@@ -37,9 +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 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.
+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 exit-code map in `references/halt-contract.md`: "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 `references/halt-contract.md` (`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.
 
 Confirm: "Active pointer: {skill_group}/active -> {version} ({kind})" where `{kind}` is `symlink` or `junction` as returned by the helper.
 
@@ -76,6 +74,14 @@ Confirm: "Active pointer: {skill_group}/active -> {version} ({kind})" where `{ki
 
 Write the result contract per `shared/references/output-contract-schema.md`: the per-run record at `{skill_package}/quick-skill-result-{YYYYMMDD-HHmmss}.json` (UTC timestamp, resolution to seconds) and a copy at `{skill_package}/quick-skill-result-latest.json` (stable path for pipeline consumers — copy, not symlink). Include `SKILL.md`, `context-snippet.md`, and `metadata.json` paths in `outputs` and export count in `summary`.
 
+**Post-completion hook (optional).** If `{onCompleteCommand}` is non-empty (resolved at SKILL.md On Activation §3 from `workflow.on_complete`), invoke it after the result contract is finalized:
+
+```bash
+{onCompleteCommand} --skill-package={skill_package}
+```
+
+Log success/failure but never fail the workflow on a hook error — the skill is already written. The hook runs last so a git-add, registry registration, or notifier sees a complete package. When `{onCompleteCommand}` is empty (bundled default), skip the invocation entirely.
+
 ### 4. Chain to Health Check
 
-ONLY WHEN the active pointer has been created and the completion summary and result contract have been written will you then load, read the full file, and proceed to `{nextStepFile}`. The health-check step is the true terminal step — do not stop here even though the summary reads as final.
+Once the active pointer, completion summary, result contract, and any post-completion hook are done, load and execute {nextStepFile}. Do not stop here — health-check is the true terminal step even though the summary reads as final.

package/src/skf-quick-skill/references/halt-contract.md

@@ -0,0 +1,54 @@
+<!-- Config: communicate in {communication_language}. -->
+
+# HARD HALT Contract
+
+The exit-code map and error-result envelope every step emits on a HARD HALT. Any step loads this file on its failure path, so the wire format is available even if SKILL.md has been compacted mid-run.
+
+## Exit Codes
+
+Every HARD HALT in this workflow exits with a stable, documented code so headless automators can branch on the failure class without grepping message text:
+
+| Code | Meaning                | Raised by                                                   |
+| ---- | ---------------------- | ----------------------------------------------------------- |
+| 0    | success                | step 7 (terminal)                                          |
+| 3    | resolution-failure     | step 1 (prose input §2, registry chain §3, version-tag miss §3a, language abort §4); step 3 (non-library shape §1.5, zero-exports §4.5) |
+| 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]) |
+| 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) |
+
+## Result Contract on HARD HALT
+
+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**:
+
+```
+SKF_QUICK_SKILL_RESULT_JSON: {"status":"error","exit_code":<N>,"phase":"<slug>","error":{"code":"<class>","message":"<short>"},"outputs":{},"summary":{},"skill_package":"<path-or-null>"}
+```
+
+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 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 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:**
+
+| Field           | Type           | Notes                                                                                                       |
+| --------------- | -------------- | ----------------------------------------------------------------------------------------------------------- |
+| `status`        | string         | always `"error"` for HARD HALTs                                                                             |
+| `exit_code`     | integer        | matches the Exit Codes table above                                                                          |
+| `phase`         | string         | step slug where the HALT occurred (e.g. `resolve-target`, `compile`)                                        |
+| `error.code`    | string         | one of: `resolution-failure`, `write-failure`, `overwrite-cancelled`, `user-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 5 §1                                              |

package/src/skf-quick-skill/references/health-check.md

@@ -1,7 +1,7 @@
 ---
 # `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.
+# development), not relative to this step file.
 nextStepFile: 'shared/health-check.md'
 ---
 
@@ -16,9 +16,8 @@ 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 6
-- Delegate directly to `{nextStepFile}` with no additional commentary
-- Do not attempt any other action between loading this step and executing `{nextStepFile}`
+- Delegate directly to `{nextStepFile}` with no additional commentary or intervening action
 
-## MANDATORY SEQUENCE
+## Steps
 
 Load `{nextStepFile}`, read it fully, then proceed to execute it.

package/src/skf-quick-skill/references/quick-extract.md

@@ -19,7 +19,7 @@ To read the resolved GitHub repository source and extract the public API surface
 - Do not begin compilation or write output files
 - If no exports found, use README content as fallback
 
-## MANDATORY SEQUENCE
+## Steps
 
 **Ref-aware source reading:** When `source_ref` is set from tag resolution (see step 1), append `?ref={source_ref}` to all GitHub API content and tree requests (e.g., `gh api repos/{owner}/{repo}/contents/{path}?ref={source_ref}`) to read from the tagged version. When using web browsing, use the tagged URL format (e.g., `github.com/{owner}/{repo}/blob/{source_ref}/{path}`). This ensures extraction reads from the same source version resolved during tag resolution.
 
@@ -57,7 +57,7 @@ Quick-skill is designed to wrap a library's public API. The compiled SKILL.md wi
 Select: [C] Continue anyway · [A] Abort"
 
 - **IF C** — log "user accepted `{shape}` shape" and proceed to §2. Set `extraction_inventory.repo_shape` to the detected shape so the result contract carries the signal for automators.
-- **IF A** — HARD HALT with **exit code 3 (resolution-failure)** per the SKILL.md exit-code map: "Aborted. `{shape}` repos are best wrapped manually with `/skf-create-skill` from a brief, not auto-extracted." Before exiting, emit the error result contract per SKILL.md "Result Contract on HARD HALT" (`phase: "quick-extract"`, `error.code: "resolution-failure"`, `error.details: {repo_shape: "{shape}"}`, `skill_package: null`).
+- **IF A** — HARD HALT with **exit code 3 (resolution-failure)** per the exit-code map in `references/halt-contract.md`: "Aborted. `{shape}` repos are best wrapped manually with `/skf-create-skill` from a brief, not auto-extracted." Before exiting, emit the error result contract per `references/halt-contract.md` (`phase: "quick-extract"`, `error.code: "resolution-failure"`, `error.details: {repo_shape: "{shape}"}`, `skill_package: null`).
 
 **GATE [default: C]** — In headless mode, log "headless: detected `{shape}` repo, continuing anyway" and proceed; the result contract's `summary.repo_shape` carries the signal so automators can flag low-quality outputs without re-parsing logs.
 
@@ -76,13 +76,13 @@ Fetch the manifest file and the top-level entry-point file(s) for the detected l
 
 **If `scope_hint` provided:** focus the entry-point fetch on the specified directories instead of repo root.
 
-For multi-module Maven (`<modules>`) and multi-project Gradle (`include(...)`) builds, fetch the parent manifest first, then loop §2+§3 per module. Sub-module fetches are safe to issue as one batched tool-call message — N module fetches collapse to O(1) wall-clock time.
+For multi-module Maven (`<modules>`) and multi-project Gradle (`include(...)`) builds, fetch the parent manifest first, then loop §2+§3 per module. Batch the sub-module fetches per the parallel-fetch directive at the top of this step.
 
 ### 3. Parse Manifest and Scan Exports
 
 Run the shared extractor against the contents fetched in §2. The helper does manifest parse + export scan in one invocation and emits a structured envelope ready to feed §4's inventory.
 
-**Resolve `{publicApiExtractor}`** from `{publicApiExtractorProbeOrder}`; first existing path wins. If no candidate exists, fall back to in-prompt parsing (the legacy per-language regex tables that this section replaces).
+**Resolve `{publicApiExtractor}`** from `{publicApiExtractorProbeOrder}`; first existing path wins. If no candidate exists, fall back to in-prompt per-language regex parsing of the manifest and entry-point files.
 
 Build the input payload from §2's fetched files and pipe it to the helper:
 
@@ -129,7 +129,7 @@ extraction_inventory:
 
 ### 4.5. Zero-Exports Soft Gate (rescue mode)
 
-Run this gate **only when** `extraction_inventory.exports.length == 0` AND `extraction_inventory.description` is empty (no usable README content either). When either is non-empty, the README-fallback in §4 produces a usable skill and this section is skipped.
+Run this gate **only when** `extraction_inventory.exports.length == 0` and `extraction_inventory.description` is empty (no usable README content either). When either is non-empty, the README-fallback in §4 produces a usable skill and this section is skipped.
 
 When both are empty, the compiled SKILL.md would be effectively empty — no API surface to document and no description to fall back on. Offer the user a chance to retry with hints before producing a degenerate output:
 
@@ -146,7 +146,7 @@ Select: [R] Retry with new hints · [P] Proceed anyway (low-confidence skill) ·
 
 - **IF R** — prompt for new `scope_hint` ("New scope hint (e.g. `src/server/`):") and optional new `language_hint` ("New language hint (or empty to keep `{language}`):"). Update the extraction context with the new hints, then **re-execute step 3 from §1** with the new values. Discards the prior empty inventory.
 - **IF P** — log "user accepted zero-exports outcome" and proceed to §5. The compiled skill will be README-content-only with confidence `low`. Record `zero_exports_rescue: "user-accepted"` in the inventory so the result contract summary surfaces it.
-- **IF A** — HARD HALT with **exit code 3 (resolution-failure)**: "Aborted. Run `/skf-create-skill` from a brief if you want a guided extraction with provenance tracking." Before exiting, emit the error result contract per SKILL.md "Result Contract on HARD HALT" (`phase: "quick-extract"`, `error.code: "resolution-failure"`, `error.details: {exports_found: 0, description_empty: true, language: "{language}", scope: "{scope_hint or 'entire repo'}"}`, `skill_package: null`).
+- **IF A** — HARD HALT with **exit code 3 (resolution-failure)**: "Aborted. Run `/skf-create-skill` from a brief if you want a guided extraction with provenance tracking." Before exiting, emit the error result contract per `references/halt-contract.md` (`phase: "quick-extract"`, `error.code: "resolution-failure"`, `error.details: {exports_found: 0, description_empty: true, language: "{language}", scope: "{scope_hint or 'entire repo'}"}`, `skill_package: null`).
 
 **GATE [default: P]** — In headless mode, log "headless: zero exports + empty description, proceeding with low-confidence skill" and proceed; record `zero_exports_rescue: "auto-proceeded"` in the result contract summary so batch automators can re-queue these targets with stricter hints downstream. [P] preserves the pre-rescue behaviour for unattended pipelines.
 
@@ -164,16 +164,5 @@ Select: [R] Retry with new hints · [P] Proceed anyway (low-confidence skill) ·
 
 ### 6. Auto-Proceed to Compilation
 
-#### Menu Handling Logic:
-
-- After extraction summary, immediately load, read entire file, then execute {nextStepFile}
-
-#### EXECUTION RULES:
-
-- This is an auto-proceed step — extraction results flow directly to compilation
-- Proceed directly to next step after summary
-
-## CRITICAL STEP COMPLETION NOTE
-
-ONLY WHEN extraction is complete and extraction_inventory is assembled (even if minimal/low-confidence) will you load and read fully `{nextStepFile}` to execute compilation.
+Once extraction_inventory is assembled (even if minimal or low-confidence), load and execute {nextStepFile} to compile.
 

package/src/skf-quick-skill/references/registry-resolution.md

@@ -70,26 +70,4 @@ Please provide the GitHub URL directly, or check:
 
 **Hard halt** — cannot proceed without a resolved source.
 
-## Language Detection
-
-After resolving to a GitHub repo, detect primary language from:
-
-1. Manifest file presence:
-   - `package.json` → JavaScript/TypeScript
-   - `pyproject.toml` or `setup.py` → Python
-   - `Cargo.toml` → Rust
-   - `go.mod` → Go
-   - `pom.xml` or `build.gradle` → Java
-2. User-provided language hint (overrides detection)
-3. GitHub API language field (if accessible)
-
-## Manifest File Priority
-
-For each language, the primary manifest to read:
-
-| Language | Manifest       | Key Fields                                                               |
-|----------|----------------|--------------------------------------------------------------------------|
-| JS/TS    | package.json   | name, version, description, main, exports, dependencies                  |
-| Python   | pyproject.toml | project.name, project.version, project.description, project.dependencies |
-| Rust     | Cargo.toml     | package.name, package.version, package.description, dependencies         |
-| Go       | go.mod         | module path, require list                                                |
+Language detection is authoritative in `resolve-target.md` §4 (Detect Language) — this file covers only the package-to-repo registry chain.