bmad-module-skill-forge 1.2.0 → 1.3.0

package/src/skf-quick-skill/steps-c/step-01-resolve-target.md

@@ -1,10 +1,15 @@
 ---
 nextStepFile: './step-02-ecosystem-check.md'
 registryResolutionData: 'references/registry-resolution.md'
+packageResolverProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-resolve-package.py'
+  - '{project-root}/src/shared/scripts/skf-resolve-package.py'
 ---
 
 # Step 1: Resolve Target
 
+Communicate with the user in `{communication_language}`.
+
 ## STEP GOAL:
 
 To accept a GitHub URL or package name from the user, resolve it to a GitHub repository, detect the primary language, and prepare state for source extraction.
@@ -16,10 +21,12 @@ To accept a GitHub URL or package name from the user, resolve it to a GitHub rep
 
 ## MANDATORY SEQUENCE
 
-**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise unless user explicitly requests a change.
-
 ### 1. Accept User Input
 
+**Batch mode:** if `--batch` is active (see SKILL.md "Batch Mode"), the current target was already resolved by On Activation step 4 from the next batch line and placed into the workflow context as `target`, with optional `language_hint` and `scope_hint` per-line modifiers. Skip the prompt below — emit `{"batch":<n>,"target":"<target>","status":"start"}` to stderr and proceed directly to §1b with the batch-supplied values.
+
+**Single-target mode** (default):
+
 "**Quick Skill — fastest path to a skill.**
 
 Provide a **GitHub URL** or **package name** and I'll resolve it to source and compile a best-effort SKILL.md.
@@ -50,41 +57,88 @@ If no `@version` suffix is present, proceed as today — version will be auto-de
 - Extract org/repo from URL
 - Set `resolved_url` to the GitHub URL
 - Set `repo_name` to the repo name (last path segment)
-- Skip to step 4 (Detect Language)
+- Skip to step 3a (Verify Target Version Tag), then step 4 (Detect Language)
 
-**If input is a package name:**
+**If input is a package-name-like token** (no whitespace, matches `[@a-zA-Z0-9._/-]+(@<semver>)?`, e.g. `lodash`, `@scope/name`, `requests==2.31`, `cognee@0.5.0`):
 - Proceed to step 3 (Registry Resolution)
 
+**Otherwise — input looks like free-form prose, not a target:**
+
+The user typed something like "I want a skill that helps with onboarding" or "build me a brainstorming workflow" — quick-skill cannot resolve that to a GitHub repository. Instead of falling through to a registry-failure HARD HALT, redirect with a sibling-skill suggestion:
+
+"**This input looks like a description, not a package or URL.** Quick Skill needs a package name (e.g. `lodash`, `@vercel/og`, `requests`) or a GitHub URL (e.g. `https://github.com/lodash/lodash`).
+
+If you are describing a skill you want to **create from scratch** rather than compile from existing source:
+
+- Run `/skf-create-skill` with a skill brief — full pipeline with provenance tracking and AST-verified exports
+- Or use `bmad-agent-builder` for an interactive skill design session
+
+Otherwise, paste the package name or GitHub URL of the library you want to wrap, and quick-skill will resolve it."
+
+**GATE [default: HALT]** — In headless mode, emit the same redirect message and HALT with **exit code 3 (resolution-failure)** per the SKILL.md exit-code map. Before exiting, emit the error result contract per SKILL.md "Result Contract on HARD HALT" (`phase: "resolve-target"`, `error.code: "resolution-failure"`, `skill_package: null`). Do not attempt registry lookups against prose input; that wastes ~3-4 round trips and produces a less actionable error message than the redirect above.
+
 ### 3. Registry Resolution
 
-Load {registryResolutionData} for resolution patterns.
+Run the shared resolver against the deterministic registries (npm → PyPI → crates.io). The resolver does the HTTP+JSON+GitHub-URL-extraction work; the LLM only handles the web-search fallback below when needed.
+
+**Resolve `{packageResolver}`** from `{packageResolverProbeOrder}`; first existing path wins. If no candidate exists, fall back to the LLM walk of {registryResolutionData} for the full chain.
 
-**Execute the fallback chain in order — stop at first success:**
+```bash
+python3 {packageResolver} {package_name} --timeout 10
+```
 
-1. **npm registry:** Fetch `https://registry.npmjs.org/{package_name}` — extract `repository.url`
-2. **PyPI registry:** Fetch `https://pypi.org/pypi/{package_name}/json` — extract `info.project_urls.Source` or `info.home_page`
-3. **crates.io registry:** Fetch `https://crates.io/api/v1/crates/{package_name}` — extract `crate.repository`
-4. **Web search fallback:** Search `"{package_name} github repository"` — look for GitHub URL
+The resolver emits JSON with `status` (`"ok"` or `"fallthrough"`), `resolved_url`, `repo_owner`, `repo_name`, `registry_used`, `registries_tried`, and a per-registry `registry_outcomes` map. Exit 0 means ok; exit 1 means fallthrough.
 
-**If all methods fail — HARD HALT:**
+- **On `status: "ok"`** — capture `resolved_url`, `repo_name`, and `registry_used` from the JSON. Proceed to §3a.
+- **On `status: "fallthrough"`** — the deterministic chain returned no GitHub URL (every registry replied with 404 / no-github-link / timeout). Fall back to the web-search step from {registryResolutionData} §4: search `"{package_name} github repository"` with a 15s timeout and look for a GitHub URL in the top results. If found, set `resolved_url` and proceed. If web search also returns nothing, HARD HALT below.
+
+**If all methods fail — HARD HALT (exit code 3, resolution-failure):**
 
 "**Resolution failed.** Could not resolve `{package_name}` to a GitHub repository.
 
-Please check:
+Check:
 - Is the package name spelled correctly?
 - Is it a private package?
 - Is the source hosted on a non-GitHub platform?
 
 **Provide the GitHub URL directly to continue.**"
 
-Wait for corrected input. Loop back to step 2.
+In interactive mode, wait for corrected input and loop back to step 2. In headless mode, emit the error result contract per SKILL.md "Result Contract on HARD HALT" (`phase: "resolve-target"`, `error.code: "resolution-failure"`, `skill_package: null`) and exit 3.
+
+### 3a. Verify Target Version Tag (when applicable)
+
+Skip this section if `target_version` is null (auto-detect path — version comes from manifest read in step-03).
+
+When the user explicitly supplied `@version` in §1b, verify the tag exists in the resolved repo before extraction. Otherwise step-03 silently reads from the default branch while metadata records the requested version — a quiet provenance bug where the SKILL.md claims version 0.5.0 but the exports actually came from main.
+
+Probe both with-and-without v-prefix (the v-prefix is conventional but not universal across ecosystems):
+
+```bash
+gh api repos/{owner}/{repo}/git/ref/tags/{target_version} --silent \
+  || gh api repos/{owner}/{repo}/git/ref/tags/v{target_version} --silent
+```
+
+**If a matching tag is found** — set `source_ref` to the matching ref (with v-prefix when that variant matched). Step-03's ref-aware source reading uses this value to fetch from the tagged commit. Proceed to §4.
+
+**If no tag matches** — HARD HALT with **exit code 3 (resolution-failure)**:
+
+"**Tag `{target_version}` not found in `{owner}/{repo}`.**
+
+The version was parsed from your `@version` suffix but does not exist as a tag in the resolved repository. Quick-skill cannot extract from a version with no commit pointer — the result would be sourced from the default branch but labelled `{target_version}` in metadata.
+
+Recent tags in this repo:
+{list top 5 from `gh api repos/{owner}/{repo}/tags --paginate=false`, or "(none — repo has no tags; omit @version to auto-detect from default branch)"}
+
+Re-run with one of these tags, or omit the `@version` suffix to auto-detect from the default branch."
+
+Before exiting, emit the error result contract per SKILL.md "Result Contract on HARD HALT" (`phase: "resolve-target"`, `error.code: "resolution-failure"`, `error.details: {requested_version: "{target_version}", available_tags: [...top 5]}`, `skill_package: null`). In headless mode, exit immediately; do not loop.
 
 ### 4. Detect Language
 
 Determine primary language from:
 
-1. **User-provided language hint** (overrides detection)
-2. **Manifest file presence** (check via GitHub API or web browsing):
+1. **User-provided language hint** (overrides detection — skip the ambiguity gate below).
+2. **Manifest-presence scan** — check the repo root for ALL of these (priority order = first hit wins on auto-pick):
    - `package.json` → JavaScript/TypeScript
    - `pyproject.toml` or `setup.py` → Python
    - `Cargo.toml` → Rust
@@ -92,7 +146,21 @@ Determine primary language from:
    - `pom.xml` → Java (or Kotlin if `src/main/kotlin/` is present)
    - `build.gradle.kts` or `build.gradle` → Kotlin (or Java if only `src/main/java/` is present)
 
-Set `language` to detected language.
+   Collect every match into `detected_languages`.
+
+3. **Single-language case** (`len(detected_languages) <= 1`) — set `language` to the detected value (or HALT in step-01 §3 if zero matches).
+
+4. **Multi-language case** (`len(detected_languages) > 1`) — surface the choice rather than silently picking the first match. Multi-language repos (Python + JS bindings, or monorepos with mixed manifests) otherwise produce a skill for whichever manifest probe hits first, with no signal that the user might have wanted the other one.
+
+   "**`{repo_name}` has manifests for multiple languages:** {detected_languages}.
+
+   Primary guess: **{first_match}** (manifest-priority order). If you wanted a different language, abort and re-run with `--language-hint <lang>` or with the optional language hint at step-01 §1.
+
+   Select: [C] Continue with `{first_match}` · [A] Abort"
+
+   - **IF C** — log "user accepted multi-manifest pick: `{first_match}`" and set `language` to the first match.
+   - **IF A** — HARD HALT with **exit code 3 (resolution-failure)**: "Aborted to disambiguate language. Re-run with a `language_hint`." Before exiting, emit the error result contract per SKILL.md "Result Contract on HARD HALT" (`phase: "resolve-target"`, `error.code: "resolution-failure"`, `error.details: {detected_languages: [...], auto_pick: "{first_match}"}`, `skill_package: null`).
+   - **GATE [default: C]** — Headless mode auto-proceeds with the manifest-priority pick; record `detected_languages` and `language_resolution: "auto-picked-first"` in the extraction context so the result contract surfaces the ambiguity downstream.
 
 ### 5. Confirm Resolution
 

package/src/skf-quick-skill/steps-c/step-02-ecosystem-check.md

@@ -4,6 +4,8 @@ nextStepFile: './step-03-quick-extract.md'
 
 # Step 2: Ecosystem Check
 
+Communicate with the user in `{communication_language}`.
+
 ## STEP GOAL:
 
 To query the agentskills.io ecosystem for an existing official skill matching the resolved target, preventing unnecessary duplication. This is an advisory gate — it never blocks the workflow on failure.
@@ -16,8 +18,6 @@ To query the agentskills.io ecosystem for an existing official skill matching th
 
 ## MANDATORY SEQUENCE
 
-**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise unless user explicitly requests a change.
-
 ### 1. Query Ecosystem
 
 Search for an existing official skill matching `{repo_name}` in the agentskills.io ecosystem.
@@ -83,5 +83,5 @@ An official skill already exists. You can:
 
 ## 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 execute source extraction.
+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.
 

package/src/skf-quick-skill/steps-c/step-03-quick-extract.md

@@ -1,9 +1,14 @@
 ---
 nextStepFile: './step-04-compile.md'
+publicApiExtractorProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-extract-public-api.py'
+  - '{project-root}/src/shared/scripts/skf-extract-public-api.py'
 ---
 
 # Step 3: Quick Extract
 
+Communicate with the user in `{communication_language}`.
+
 ## STEP GOAL:
 
 To read the resolved GitHub repository source and extract the public API surface using surface-level source reading (no AST). Produces an extraction inventory of exports, descriptions, and manifest data for compilation.
@@ -16,10 +21,10 @@ To read the resolved GitHub repository source and extract the public API surface
 
 ## MANDATORY SEQUENCE
 
-**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise unless user explicitly requests a change.
-
 **Ref-aware source reading:** When `source_ref` is set from tag resolution (see step-01), 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.
 
+**Parallel-fetch directive:** §1 (README), §2 (manifest), and §3 (entry-point exports) read independent files from the same `?ref={source_ref}` and are safe to issue as one batched tool-call message rather than three sequential round trips. For multi-module Maven (`<modules>`) and multi-project Gradle (`include(...)`) builds, also fetch all submodule `pom.xml` / `build.gradle[.kts]` files in parallel rather than serially per module — N module fetches collapse to O(1) wall-clock time.
+
 ### 1. Read README
 
 Read `README.md` from the repository root via web browsing.
@@ -32,59 +37,74 @@ Extract:
 
 If README is unavailable, note and continue.
 
-### 2. Read Manifest File
+### 1.5. Repo-Shape Sniff
 
-Based on detected language, read the primary manifest file:
+After the README has loaded, classify the repo shape from the available signals before committing further effort to extraction. Quick-skill is designed to wrap a library; non-library repos sail through silently today and produce low-quality skills the user only notices via the description field after compilation.
 
-- **JavaScript/TypeScript:** `package.json` — extract name, version, description, main, exports, dependencies
-- **Python:** `pyproject.toml` or `setup.py` — extract project name, version, description, dependencies
-- **Rust:** `Cargo.toml` — extract package name, version, description, dependencies
-- **Go:** `go.mod` — extract module path, require list
-- **Java (Maven):** `pom.xml` — extract `<groupId>`, `<artifactId>`, `<version>`, `<description>`, direct `<dependencies>`. For multi-module projects, also enumerate `<modules><module>` entries and read each submodule's `pom.xml` (treat each as a logical unit in the extraction inventory).
-- **Kotlin / Java (Gradle):** `build.gradle.kts` or `build.gradle` — extract `group`, `version`, `description` (when declared), and top-level `dependencies { }` block. For multi-project builds, read `settings.gradle[.kts]` for `include(...)` entries and repeat per subproject.
+**Classify as one of:**
 
-Extract:
-- **Package metadata:** name, version, description
-- **Entry points:** main, exports, module fields
-- **Key dependencies:** direct dependencies list
+- **library** (default) — README has installation / usage / API content; manifest at root with publishable metadata. Proceed normally.
+- **awesome-list** — README H1 contains "awesome" (case-insensitive) or `awesome-` is in the repo name; README body is dominated by curated bullet links of the form `- [name](url) — desc`; no manifest at root.
+- **docs-site / website** — README is short (under ~50 non-empty lines) and primarily points elsewhere ("See https://… for docs"); root has no manifest, or only a docs-framework manifest (e.g. `docusaurus.config.js`, `astro.config.mjs`, `mkdocs.yml`).
+- **examples-only / tutorial** — README explicitly labels the repo as examples or a tutorial ("Code examples for…", "Tutorial: …", "Learn X by building Y"); typically no published package; many small standalone files instead of a single API surface.
+
+**If a non-library shape is detected** — soft-warn and gate before continuing:
+
+"**Heads up — `{repo_name}` looks like a `{shape}` repo, not a library.**
+
+Quick-skill is designed to wrap a library's public API. The compiled SKILL.md will likely have a thin Description and an empty Key Exports list. You can continue anyway, or abort and pick a target library.
+
+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`).
+
+**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.
+
+### 2. Fetch Source Files
+
+Fetch the manifest file and the top-level entry-point file(s) for the detected language. The helper invoked in §3 does pure parsing — no I/O — so this step does the fetch work using `gh api` (preferred when source_ref is set) or web browsing.
+
+| Language | Manifest | Entry-point files (quick mode) |
+| --- | --- | --- |
+| JavaScript / TypeScript | `package.json` | `index.{js,ts}`, `src/index.{ts,js}`, or the file pointed to by the `main` field |
+| Python | `pyproject.toml` or `setup.py` | `__init__.py`, `src/{package}/__init__.py` |
+| Rust | `Cargo.toml` | `src/lib.rs` |
+| Go | `go.mod` | top-level `*.go` files (3–5 best-effort) |
+| Java (Maven) | `pom.xml` | top-level `*.java` files under `src/main/java/<groupId-as-path>/` (3–5 best-effort) |
+| Kotlin (Gradle) | `build.gradle.kts` or `build.gradle` | top-level `*.kt` files under `src/main/kotlin/` (3–5 best-effort); also fetch `settings.gradle[.kts]` for `include(...)` entries when present |
 
-### 3. Scan Top-Level Exports
+**If `scope_hint` provided:** focus the entry-point fetch on the specified directories instead of repo root.
 
-Based on language and entry points from manifest, read the primary export files:
+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.
 
-**JavaScript/TypeScript:**
-- Read `index.js`, `index.ts`, `src/index.ts`, or `main` field from package.json
-- Extract: `export` statements, `module.exports` assignments
-- Pattern: lines matching `export (const|function|class|default|type|interface)`
+### 3. Parse Manifest and Scan Exports
 
-**Python:**
-- Read `__init__.py` or `src/{package}/__init__.py`
-- Extract: `__all__` list, top-level function/class definitions
-- Pattern: lines matching `def |class |__all__`
+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.
 
-**Rust:**
-- Read `src/lib.rs`
-- Extract: `pub fn`, `pub struct`, `pub enum`, `pub trait` declarations
-- Pattern: lines matching `pub (fn|struct|enum|trait|mod)`
+**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).
 
-**Go:**
-- Read exported functions from top-level `.go` files
-- Extract: capitalized function names (Go export convention)
-- Pattern: lines matching `func [A-Z]`
+Build the input payload from §2's fetched files and pipe it to the helper:
 
-**Java:**
-- Read `src/main/java/**/*.java` (focus on top-level packages declared in the manifest's `groupId`)
-- Extract: public classes, public methods, and framework annotations that mark API surfaces (Spring, Jakarta EE, CDI)
-- Pattern: lines matching `@(RestController|Service|Component|Configuration|Controller|Repository|Bean)|public (class|interface|enum|record) |public .* \(`
-- **Multi-module Maven:** iterate the `<module>` entries discovered in §2 and repeat the scan per module, reading each `{module}/src/main/java/**/*.java`
+```bash
+echo '{"language":"<lang>","manifest":{"path":"<rel>","content":"<...>"},"entries":[{"path":"<rel>","content":"<...>"},...],"mode":"quick"}' \
+  | python3 {publicApiExtractor} --mode quick
+```
+
+Where `<lang>` is one of `js`, `ts`, `javascript`, `typescript`, `python`, `rust`, `go`, `java`, `kotlin`. The helper accepts arbitrarily many `entries` items and aggregates exports across them.
+
+The helper emits JSON on stdout with:
+
+- `package_name`, `version`, `description` — parsed from the manifest
+- `exports[]` — `{name, type, source_file}` per discovered top-level public symbol
+- `dependencies[]` — declared direct dependencies
+- `modules[]` — for Maven `<modules>` and Gradle `include(...)`, the names of sub-modules to iterate (loop §2+§3 per entry)
+- `extra` — language-specific extras (e.g. `group_id` for Maven)
+- `warnings[]` — manifest parse failures or scanner errors (advisory only; the envelope is still valid)
 
-**Kotlin:**
-- Read `src/main/kotlin/**/*.kt` (Kotlin defaults to `public` visibility — omit `internal`/`private` declarations)
-- Extract: top-level `fun`, `class`, `object`, `interface` declarations
-- Pattern: lines matching `^(fun |class |object |interface |data class |sealed class |@(RestController|Service|Component|Configuration|Controller))`
-- **Multi-project Gradle:** iterate the `include(...)` entries discovered in §2 and repeat the scan per subproject
+Capture the helper's output into the extraction context. The shape of the envelope is the same for every language; §4 builds the inventory from it without per-language branching.
 
-**If scope_hint provided:** Focus reading on the specified directories instead of root.
+**Multi-module loop:** when `modules[]` is non-empty, fetch each sub-module's manifest + entry-point files (§2) and re-invoke the helper per module (§3), aggregating `exports[]` across all module envelopes. The aggregated `exports[]`, `dependencies[]`, and a single resolved `package_name` (from the parent manifest) feed §4.
 
 ### 4. Build Extraction Inventory
 
@@ -107,6 +127,29 @@ extraction_inventory:
 - Use README description and features as fallback content
 - Note: "No exports detected — SKILL.md will be based on README content only"
 
+### 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.
+
+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:
+
+"**Extraction yielded zero exports and no README description.**
+
+The compiled SKILL.md would be effectively empty — no API surface to document and no description to fall back on.
+
+Common causes:
+- Wrong scope (extraction read the repo root, but the public API lives in a subdir)
+- Wrong language (manifest probe picked the test/build language, not the lib language)
+- Repo lays out exports unconventionally (e.g., not in `src/index.*` or `lib.rs`)
+
+Select: [R] Retry with new hints · [P] Proceed anyway (low-confidence skill) · [A] Abort"
+
+- **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-03 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`).
+
+**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.
+
 ### 5. Report Extraction Summary
 
 "**Extraction complete:**

package/src/skf-quick-skill/steps-c/step-04-compile.md

@@ -1,10 +1,15 @@
 ---
-nextStepFile: './step-05-validate.md'
+nextStepFile: './step-05-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
 
+Communicate with the user in `{communication_language}`. Compile generated content (descriptions, usage notes, summaries) in `{document_output_language}`.
+
 ## STEP GOAL:
 
 To assemble the best-effort SKILL.md document, context-snippet.md in Vercel-aligned indexed format, and metadata.json with `source_authority: community` from the extraction inventory. Present compiled output for review before validation.
@@ -17,8 +22,6 @@ To assemble the best-effort SKILL.md document, context-snippet.md in Vercel-alig
 
 ## MANDATORY SEQUENCE
 
-**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise unless user explicitly requests a change.
-
 ### 1. Load Skill Template
 
 Load {skillTemplateData} to understand:
@@ -50,8 +53,8 @@ description: >
 
 **Required sections (after frontmatter):**
 - **Overview:** Package name, repository, language, source authority, generation date
-- **Description:** From extraction_inventory.description (README-derived)
-- **Key Exports:** From extraction_inventory.exports — list each with name, type, brief description
+- **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):**
@@ -65,7 +68,9 @@ description: >
 
 ### 3. Generate Context Snippet
 
-Create context-snippet.md in Vercel-aligned indexed format (~80-120 tokens):
+**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.
+
+Otherwise, create context-snippet.md in Vercel-aligned indexed format (~80-120 tokens):
 
 ```
 [{skill_name} v{version}]|root: skills/{skill_name}/
@@ -82,53 +87,37 @@ Create context-snippet.md in Vercel-aligned indexed format (~80-120 tokens):
 
 ### 4. Generate Metadata JSON
 
-Generate metadata.json following the exact structure defined in {skillTemplateData} metadata.json section. Populate fields from extraction_inventory:
-
-```json
-{
-  "name": "{skill_name}",
-  "version": "{extraction_inventory.version or 1.0.0}",
-  "description": "{brief description of the skill}",
-  "skill_type": "single",
-  "source_authority": "community",
-  "source_repo": "{resolved_url}",
-  "source_root": "{resolved_source_path}",
-  "source_commit": "{commit_sha_if_available}",
-  "source_package": "{package_name from manifest}",
-  "language": "{language}",
-  "generated_by": "quick-skill",
-  "generation_date": "{current ISO date}",
-  "confidence_tier": "Quick",
-  "spec_version": "1.3",
-  "exports": ["{export_1}", "{export_2}"],
-  "confidence_distribution": {
-    "t1": 0,
-    "t1_low": "{number of exports found — must be integer, not string}",
-    "t2": 0,
-    "t3": 0
-  },
-  "tool_versions": {
-    "ast_grep": null,
-    "qmd": null,
-    "skf": "{skf_version}"   // Resolution chain: _bmad/skf/package.json → npm require → _bmad/skf/VERSION → "unknown"
-  },
-  "stats": {
-    "exports_documented": "{number of exports found}",
-    "exports_public_api": "{number of exports found}",
-    "exports_internal": 0,
-    "exports_total": "{number of exports found}",
-    "public_api_coverage": 1.0,
-    "total_coverage": 1.0,
-    "scripts_count": 0,
-    "assets_count": 0
-  },
-  "dependencies": [],
-  "compatibility": "{semver-range or null}"
-}
+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).
+
+**Probe `tool_versions.skf` first** (the helper expects it as input — the filesystem walk stays here because the helper does no I/O):
+
+1. Read `{project-root}/_bmad/skf/package.json` → take `version`
+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:
+
+```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.
+
+**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:
+
+"Compiled: SKILL.md ({section_count} sections, {export_count} exports), context-snippet.md (~{snippet_token_count} tokens), metadata.json (version {version}, confidence {confidence}). Auto-approving [C]."
+
+Then proceed directly to §6 — the GATE default action takes over.
+
+**Otherwise (interactive mode):**
+
 "**Compilation complete. Review before validation:**
 
 ---
@@ -154,25 +143,29 @@ Generate metadata.json following the exact structure defined in {skillTemplateDa
 **Extraction confidence:** {confidence}
 **Exports documented:** {count}
 
-Review the output above. When ready, continue to validation."
+Review the output above, then choose: [C] continue to validation, [E] edit the description, [S] adjust scope and re-extract, or [Q] quit without writing."
 
 ### 6. Present MENU OPTIONS
 
-Display: **Select:** [C] Continue to Validation
+Display: **Select:** [C] Continue to Validation · [E] Edit description · [S] Adjust scope and re-extract · [Q] Quit without writing
 
 #### Menu Handling Logic:
 
-- IF C: Load, read entire file, then execute {nextStepFile}
-- IF Any other: Help user adjust compiled output, then redisplay menu
+- **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 Any other** — Help the user adjust the compiled output (treated as a free-form revision request), then redisplay the menu.
 
 #### EXECUTION RULES:
 
 - ALWAYS halt and wait for user input after presenting compiled output
 - **GATE [default: C]** — If `{headless_mode}`: auto-proceed with [C] Continue, log: "headless: auto-approve compiled output"
-- ONLY proceed to validation when user selects 'C'
-- User can request changes to the compiled output before proceeding
+- 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
 
 ## CRITICAL STEP COMPLETION NOTE
 
-ONLY WHEN the user reviews the compiled output and selects 'C' will you load and read fully `{nextStepFile}` to execute validation.
+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.