bmad-module-skill-forge 1.9.0 → 2.0.1

package/src/skf-forger/scripts/parse-pipeline.py

@@ -0,0 +1,270 @@
+#!/usr/bin/env python3
+# /// script
+# requires-python = ">=3.10"
+# ///
+"""Deterministic parse + validation of a forger pipeline invocation.
+
+Pipeline Mode (references/pipeline-mode.md §1-2) turns a raw code sequence
+(`BS CS[cocoindex] TS[min:80] EX`, `AN -> CS -> TS -> EX`, or a bare alias like
+`forge-auto`) into a normalized run plan and a list of sequence anti-patterns.
+Splitting the tokens, expanding aliases against a fixed table, classifying each
+bracket argument, and detecting anti-patterns (duplicates, ordering, missing
+prerequisites) is set/order plumbing with exactly one correct answer per input —
+so it runs here, not in the prompt. The prompt keeps only the judgment the
+script cannot make: interpreting the user's freeform request into a code
+sequence, and deciding whether to proceed past a warned anti-pattern.
+
+The alias-expansion and anti-pattern tables mirror
+`src/shared/references/pipeline-contracts.md` (the human-readable contract);
+this script is the executable form the forger consumes.
+
+CLI usage:
+  uv run scripts/parse-pipeline.py 'BS CS TS EX'      # positional
+  uv run scripts/parse-pipeline.py 'forge-auto'       # bare alias
+  echo 'AN -> CS -> TS -> EX' | uv run scripts/parse-pipeline.py --stdin
+
+Output (stdout, one object):
+  {
+    "raw": "<input>",
+    "alias": "forge" | null,          # set when the input was a lone alias
+    "deprecated_alias": "deepwiki" | null,
+    "removed_alias": "onboard" | null,
+    "expanded": ["BS", "CS", "TS", "EX"],   # normalized tokens (post-expansion)
+    "plan": [{"code","min","mode","target"}, ...],
+    "codes": ["BS", "CS", "TS", "EX"],
+    "unknown_codes": [],
+    "anti_patterns": [{"pattern","message","suggestion"}, ...],
+    "valid": <bool>                   # runnable: real codes, no unknowns, not removed
+  }
+
+Exit codes:
+  0  — parsed, runnable (anti-patterns and a deprecated alias are warnings)
+  1  — no input provided (usage error)
+  2  — removed alias (e.g. `onboard`) — the forger HALTs
+  3  — nothing runnable (empty, or unknown codes) — the forger corrects course
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import re
+import sys
+
+# Workflow codes that can appear in a pipeline. KI/WS are inline actions, not
+# pipeline steps; `campaign` is a standalone workflow, not a pipeline code.
+KNOWN_CODES = frozenset(
+    {"SF", "AN", "BS", "CS", "QS", "SS", "US", "AS", "VS", "RA", "TS", "EX", "RS", "DS"}
+)
+
+# Only these accept a `min:N` circuit-breaker override; on other codes a
+# `min:N` bracket is ignored (recorded as `min: null`).
+CIRCUIT_BREAKER_CODES = frozenset({"AN", "CS", "TS", "AS", "VS"})
+
+# Alias table — mirrors pipeline-contracts.md. `forge-auto`'s TS[min:90] gate is
+# non-default and is kept in lockstep with init.md §1b's forge-auto → 90 lookup.
+ALIASES = {
+    "forge-auto": ["AN[auto]", "BS[auto]", "CS", "TS[min:90]", "EX"],
+    "forge": ["BS", "CS", "TS", "EX"],
+    "forge-quick": ["QS", "TS", "EX"],
+    "maintain": ["AS", "US", "TS", "EX"],
+}
+DEPRECATED_ALIASES = {"deepwiki": "forge-auto"}  # renamed; still expands
+REMOVED_ALIASES = {"onboard"}  # no expansion — the forger HALTs
+
+_TOKEN_RE = re.compile(r"^([A-Za-z]+)(?:\[([^\]]*)\])?$")
+_ARROWS = re.compile(r"->|→|—>|»")
+
+
+def _tokenize(raw):
+    """Split a raw sequence on whitespace and arrow separators."""
+    normalized = _ARROWS.sub(" ", raw)
+    return [t for t in normalized.split() if t]
+
+
+def _classify_bracket(code, value):
+    """Return (min, mode, target) for a bracket value on a given code."""
+    if value is None or value == "":
+        return None, None, None
+    m = re.fullmatch(r"min:(\d+)", value)
+    if m:
+        # min:N only applies to circuit-breaker codes; ignored elsewhere.
+        return (int(m.group(1)) if code in CIRCUIT_BREAKER_CODES else None), None, None
+    if value == "auto":
+        return None, "auto", None
+    return None, None, value
+
+
+def _detect_anti_patterns(codes):
+    """Deterministic sequence checks — mirrors pipeline-contracts.md."""
+    found = []
+
+    # Duplicate codes.
+    seen = set()
+    dupes = []
+    for c in codes:
+        if c in seen and c not in dupes:
+            dupes.append(c)
+        seen.add(c)
+    if dupes:
+        found.append(
+            {
+                "pattern": "duplicate-codes",
+                "codes": dupes,
+                "message": f"same workflow appears more than once: {', '.join(dupes)}",
+                "suggestion": "remove the duplicate",
+            }
+        )
+
+    # EX before TS (equivalently, TS after EX).
+    ex_idxs = [i for i, c in enumerate(codes) if c == "EX"]
+    ts_idxs = [i for i, c in enumerate(codes) if c == "TS"]
+    if ex_idxs and ts_idxs and min(ex_idxs) < max(ts_idxs):
+        found.append(
+            {
+                "pattern": "ex-before-ts",
+                "codes": ["EX", "TS"],
+                "message": "EX (export) runs before TS (test) — exporting an untested skill",
+                "suggestion": "move TS before EX",
+            }
+        )
+
+    # CS without BS or AN.
+    if "CS" in codes and "BS" not in codes and "AN" not in codes:
+        found.append(
+            {
+                "pattern": "cs-without-brief",
+                "codes": ["CS"],
+                "message": "CS (compile) has no preceding BS or AN — compiling without a brief",
+                "suggestion": "use QS for the quick path, or add AN/BS to produce a brief",
+            }
+        )
+
+    # US without AS.
+    if "US" in codes and "AS" not in codes:
+        found.append(
+            {
+                "pattern": "us-without-audit",
+                "codes": ["US"],
+                "message": "US (update) has no preceding AS — updating without an audit",
+                "suggestion": "run AS first to detect what changed",
+            }
+        )
+
+    return found
+
+
+def parse_pipeline(raw):
+    """Parse and validate a raw pipeline sequence. Deterministic."""
+    tokens = _tokenize(raw)
+    result = {
+        "raw": raw,
+        "alias": None,
+        "deprecated_alias": None,
+        "removed_alias": None,
+        "expanded": [],
+        "plan": [],
+        "codes": [],
+        "unknown_codes": [],
+        "anti_patterns": [],
+        "valid": False,
+    }
+    if not tokens:
+        return result
+
+    # Alias handling — only when the sequence is a lone alias token.
+    if len(tokens) == 1:
+        lone = tokens[0].lower()
+        if lone in REMOVED_ALIASES:
+            result["removed_alias"] = lone
+            return result
+        if lone in DEPRECATED_ALIASES:
+            result["deprecated_alias"] = lone
+            target = DEPRECATED_ALIASES[lone]
+            result["alias"] = target
+            tokens = list(ALIASES[target])
+        elif lone in ALIASES:
+            result["alias"] = lone
+            tokens = list(ALIASES[lone])
+
+    result["expanded"] = []
+    for tok in tokens:
+        m = _TOKEN_RE.match(tok)
+        if not m:
+            result["unknown_codes"].append(tok)
+            continue
+        code = m.group(1).upper()
+        value = m.group(2)
+        result["expanded"].append(
+            f"{code}[{value}]" if value not in (None, "") else code
+        )
+        if code not in KNOWN_CODES:
+            result["unknown_codes"].append(tok)
+            continue
+        min_n, mode, target = _classify_bracket(code, value)
+        result["codes"].append(code)
+        result["plan"].append(
+            {"code": code, "min": min_n, "mode": mode, "target": target}
+        )
+
+    result["anti_patterns"] = _detect_anti_patterns(result["codes"])
+    result["valid"] = bool(result["codes"]) and not result["unknown_codes"]
+    return result
+
+
+# --- CLI --------------------------------------------------------------------
+
+
+def _build_parser():
+    parser = argparse.ArgumentParser(
+        prog="parse-pipeline",
+        description=(
+            "Deterministic parse + validation of a forger pipeline invocation "
+            "(pipeline-mode.md §1-2): tokenize, expand aliases, classify bracket "
+            "arguments, and detect sequence anti-patterns, returning a normalized "
+            "run plan as JSON."
+        ),
+        formatter_class=argparse.RawDescriptionHelpFormatter,
+    )
+    src = parser.add_mutually_exclusive_group()
+    src.add_argument(
+        "sequence",
+        nargs="?",
+        help="Raw pipeline sequence as a positional argument.",
+    )
+    src.add_argument(
+        "--stdin",
+        action="store_true",
+        help="Read the raw sequence from stdin.",
+    )
+    return parser
+
+
+def _resolve_input(args):
+    if args.stdin:
+        return sys.stdin.read()
+    if args.sequence is not None:
+        return args.sequence
+    return ""
+
+
+def main(argv=None):
+    parser = _build_parser()
+    args = parser.parse_args(argv)
+    raw = _resolve_input(args)
+    if not raw.strip():
+        parser.print_usage(file=sys.stderr)
+        print("error: no input provided (positional arg or --stdin)", file=sys.stderr)
+        return 1
+
+    result = parse_pipeline(raw)
+    print(json.dumps(result, indent=2))
+    if result["removed_alias"]:
+        return 2
+    if not result["valid"]:
+        return 3
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

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.