bmad-module-skill-forge 1.1.0 → 1.3.0

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

@@ -23,6 +23,12 @@ These rules apply to every step in this workflow:
 - Only load one step file at a time — never preload future steps
 - Always communicate in `{communication_language}`
 - If `{headless_mode}` is true, auto-proceed through confirmation gates with their default action and log each auto-decision
+- If `{headless_mode}` is true, emit a single-line JSON progress event to **stderr** at each step's entry and exit so pipeline schedulers can stream live progress instead of post-mortem-parsing the result contract:
+  - entry: `{"step":N,"name":"<slug>","status":"start"}`
+  - exit (just before chaining to nextStepFile): `{"step":N,"name":"<slug>","status":"done"}`
+  - on HARD HALT: `{"step":N,"name":"<slug>","status":"halt","exit":<code>}` instead of "done"
+
+  `N` is the step number (1–7) and `<slug>` is the kebab portion of the filename after the number — `resolve-target`, `ecosystem-check`, `quick-extract`, `compile`, `write-and-validate`, `finalize`, `health-check`. One line per event; do not pretty-print.
 
 ## Stages
 
@@ -32,25 +38,187 @@ These rules apply to every step in this workflow:
 | 2 | Ecosystem Check | steps-c/step-02-ecosystem-check.md | Yes |
 | 3 | Quick Extract | steps-c/step-03-quick-extract.md | Yes |
 | 4 | Compile | steps-c/step-04-compile.md | No (review) |
-| 5 | Write & Validate | steps-c/step-05-validate.md | Yes |
-| 6 | Finalize | steps-c/step-06-write.md | Yes |
+| 5 | Write & Validate | steps-c/step-05-write-and-validate.md | Yes |
+| 6 | Finalize | steps-c/step-06-finalize.md | Yes |
 | 7 | Workflow Health Check | steps-c/step-07-health-check.md | Yes |
 
 ## Invocation Contract
 
 | Aspect | Detail |
 |--------|--------|
-| **Inputs** | target (GitHub URL or package name) [required], language_hint [optional], scope_hint [optional] |
-| **Gates** | step-01: Input Gate [use args] | step-02: Choice Gate [P] (if match) | step-04: Review Gate [C] |
-| **Outputs** | SKILL.md, context-snippet.md, metadata.json, active symlink |
+| **Inputs** | target (GitHub URL or package name) [required for single-target mode], language_hint [optional], scope_hint [optional] |
+| **Overrides** | `--description`, `--exports`, `--skip-snippet`, `--no-active-pointer`, `--batch <file>`, `--fail-fast` — see On Activation step 3 |
+| **Gates** | step-01: Input Gate [use args]; step-02: Choice Gate [P] (if match); step-04: Review Gate [C/E/S/Q] |
+| **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
+
+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-07 (terminal)                                          |
+| 3    | resolution-failure     | step-01 §2c (prose input), step-01 §3 (registry chain failed) |
+| 4    | write-failure          | step-05 §2 (deliverable write failed)                       |
+| 5    | overwrite-cancelled    | step-05 §1 (user selected [N])                              |
+| 6    | compile-cancelled      | step-04 §6 (user selected [Q])                              |
+| 7    | finalize-blocked       | step-06 §1 (active-pointer flip refused — non-link in place) |
+
+Reserved: `validator-missing` may be promoted from advisory log to fatal exit code in a future revision; consumers should not assume code 8+ is unused.
+
+## Result Contract on HARD HALT
+
+In addition to the success-variant result contract written by step-06 §3, every HARD HALT must surface an **error variant** so headless automators don't silently break when `quick-skill-result-latest.json` is missing on failed runs.
+
+**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-05 §1 onward) — write the same JSON object (without the `SKF_QUICK_SKILL_RESULT_JSON: ` prefix) to disk:
+
+```
+{skill_package}/quick-skill-result-{YYYYMMDD-HHmmss}.json
+{skill_package}/quick-skill-result-latest.json   (copy, not symlink)
+```
+
+so consumers that hardcode the `-latest.json` path see a deterministic file even on failed runs. HALTs at step-01/02/03/04 cannot write to disk because `{skill_package}` is computed only in step-05 §1; for those, the stderr envelope plus exit code is the contract.
+
+**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`, `compile-cancelled`, `finalize-blocked` |
+| `error.message` | string         | the user-facing message that was displayed                                                                  |
+| `error.details` | any            | optional — phase-specific context (e.g. the failed file path)                                               |
+| `outputs`       | object         | empty `{}` on early HALTs; partial when files were already written                                          |
+| `summary`       | object         | empty `{}` on early HALTs                                                                                   |
+| `skill_package` | string \| null | absolute path when known, `null` when HALT preceded step-05 §1                                              |
 
 ## On Activation
 
-1. Load config from `{project-root}/_bmad/skf/config.yaml` and resolve:
-   - `project_name`, `output_folder`, `user_name`, `communication_language`, `document_output_language`
-   - `skills_output_folder`, `forge_data_folder`
+1. Read `{project-root}/_bmad/skf/config.yaml` and `{forger_root}/preferences.yaml` in parallel (one batched tool-call message — they are independent files), then resolve:
+   - From config: `project_name`, `output_folder`, `user_name`, `communication_language`, `document_output_language`, `skills_output_folder`, `forge_data_folder`
+   - From preferences: `headless_mode` (default false)
+
+2. **Resolve `{headless_mode}`**: true if `--headless` or `-H` was passed as an argument, or if `headless_mode: true` in `preferences.yaml`. Default: false.
+
+3. **Parse CLI overrides** — capture optional override flags into the workflow context as `{overrides}`. Each override is opt-in; when omitted, the workflow runs as today.
+
+   | Flag | Effect |
+   | --- | --- |
+   | `--description "<string>"` | Override the LLM-derived description in step-04 §2 (used in SKILL.md frontmatter and metadata.json). Subject to the same agentskills.io length (1–1024 chars) and voice (third-person) checks as extracted descriptions. |
+   | `--exports "<name1,name2,...>"` | Override the extracted export list. Parse as comma-separated; trim whitespace per item; skip empty items. Used in step-04 §2 Key Exports and the count-derived metadata stats. |
+   | `--skip-snippet` | Skip context-snippet.md generation in step-04 §3 and its write in step-05 §2. Artifact omitted from `outputs`; step-05 §5 advisory snippet validation reports a "skipped" entry. |
+   | `--no-active-pointer` | Skip the active-pointer flip in step-06 §1. Deliverables still land in `{skill_package}` but `{skill_group}/active` is not updated. Useful for batch automators that flip pointers in a separate stage. |
+   | `--batch <file>` | Run the workflow against a list of targets from a text file rather than a single argument. Implies `--headless` (gates cannot be human-driven across N targets). See "Batch Mode" below for input format and summary contract. Single-target overrides above apply globally to every target in the batch. |
+   | `--fail-fast` | Only meaningful with `--batch`. Abort the whole batch on the first per-target failure instead of recording the failure in the summary and proceeding to the next target. |
+
+4. **If `--batch` is set**, force `{headless_mode} = true` (log "headless: coerced by --batch" if it was false), read the batch file, and parse the target list per "Batch Mode" below. Continue at step 5; the batch loop documented in "Batch Mode" wraps the step-01 → step-07 pipeline that follows.
+
+5. Load, read the full file, and then execute `./steps-c/step-01-resolve-target.md` to begin the workflow. (In batch mode, control returns here for each subsequent target after step-07 completes; see "Batch Mode" below.)
+
+## Batch Mode
+
+When `--batch <file>` is supplied, quick-skill processes a list of targets from a text file in sequence rather than a single target from arguments. Designed for unattended bulk runs (CI pipelines, mass-rebuilds, the skf-batch-skills meta-workflow when it lands).
+
+### Input format
+
+One target per line. Empty lines and lines starting with `#` (after optional leading whitespace) are ignored. Each non-empty line has the same shape as the single-target `target` argument, with optional space-separated per-line modifiers:
+
+```
+# A batch input file.
+lodash
+@vercel/og
+cognee@0.5.0
+https://github.com/foo/bar
+https://github.com/foo/bar@2.1.0-beta
+
+# Per-line modifiers — overrides for THIS target only:
+lodash language=javascript scope=src/
+cognee@0.5.0 language=python scope=cognee/api/
+```
+
+Recognised per-line modifiers:
+
+| Modifier | Effect (this target only) |
+| --- | --- |
+| `language=<lang>` | Sets `language_hint` for this target — same effect as the optional `language_hint` input on a single-target run. |
+| `scope=<path>` | Sets `scope_hint` for this target — same effect as the optional `scope_hint` input on a single-target run. |
+
+Per-line modifiers shadow the global `--description` / `--exports` / `--skip-snippet` / `--no-active-pointer` overrides only when those override fields are not set. Global overrides apply to every target unless a future modifier extends per-line override syntax.
+
+### Execution
+
+`--batch` implies `--headless`. The batch loop runs the full quick-skill pipeline (steps 1–7) for each target in file order:
+
+1. Set `target`, `target_version`, `language_hint`, `scope_hint` from the batch line into the workflow context.
+2. Execute steps 1–7 per the normal pipeline.
+3. After step-07 completes (success or HARD HALT), record the per-target outcome (target, status, exit_code, skill_package, error.code) into the batch result list.
+4. If `--fail-fast` is set and the target failed, exit the batch loop immediately. Otherwise continue with the next target.
+
+Per-target output lands in `{skill_package}/` as today, with the per-target result contract at `{skill_package}/quick-skill-result-latest.json` (success or error variant per "Result Contract on HARD HALT" above).
+
+### Batch summary contract
+
+After the last target completes (or `--fail-fast` triggers an early exit), write the batch summary at:
+
+```
+{skills_output_folder}/_batch/quick-skill-batch-{YYYYMMDD-HHmmss}.json
+{skills_output_folder}/_batch/quick-skill-batch-latest.json   (copy, not symlink)
+```
+
+Schema:
+
+```json
+{
+  "skill": "skf-quick-skill",
+  "mode": "batch",
+  "status": "success | partial | failed",
+  "timestamp": "<ISO 8601 UTC>",
+  "input_file": "<path passed to --batch>",
+  "targets_total": 0,
+  "succeeded": 0,
+  "failed": 0,
+  "fail_fast_triggered": false,
+  "results": [
+    {
+      "target": "<line from batch file>",
+      "status": "success | error",
+      "exit_code": 0,
+      "skill_package": "<absolute path or null>",
+      "error_code": null
+    }
+  ]
+}
+```
+
+`status` resolves as: `"success"` when `failed == 0`; `"partial"` when `failed > 0 && succeeded > 0`; `"failed"` when `succeeded == 0`. `fail_fast_triggered` is `true` only when `--fail-fast` aborted the loop early — `targets_total` then reflects the count actually attempted, not the file's line count.
+
+### Headless events
+
+Batch mode emits per-target boundary events on stderr in addition to the per-step events documented in Workflow Rules:
+
+```
+{"batch":<n>,"target":"<target>","status":"start"}
+{"batch":<n>,"target":"<target>","status":"done","exit":<code>}
+{"batch":<n>,"target":"<target>","status":"fail","exit":<code>,"error_code":"<class>"}
+```
+
+`<n>` is the 1-based index of the target in the parsed list. After the loop ends, emit one final batch-summary event:
+
+```
+{"batch_summary":true,"targets_total":N,"succeeded":K,"failed":M,"status":"<...>","fail_fast_triggered":<bool>}
+```
 
-2. **Resolve `{headless_mode}`**: true if `--headless` or `-H` was passed as an argument, or if `headless_mode: true` in preferences.yaml. Default: false.
+### Exit code
 
-3. Load, read the full file, and then execute `./steps-c/step-01-resolve-target.md` to begin the workflow.
+The batch process exits with code `0` when `failed == 0`, otherwise with the exit code of the first failed target (so automators that already branch on the single-target exit-code map continue to work without batch-specific handling). When `--fail-fast` triggers, the exit code is the failing target's code.

package/src/skf-quick-skill/assets/skill-template.md

@@ -101,6 +101,10 @@ Indexed format targeting ~80-120 tokens per skill:
     "assets_count": 0
   },
   "dependencies": [],
-  "compatibility": "{semver-range}"
+  "compatibility": "{semver-range}",
+  "provenance": {
+    "language_hint": "{language_hint or null}",
+    "scope_hint": "{scope_hint or null}"
+  }
 }
 ```

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

@@ -13,6 +13,8 @@ When the user provides a package name instead of a GitHub URL, use this fallback
 
 Try each registry in order. Stop at first success.
 
+**Per-call timeout:** apply a 10s timeout to each registry HTTP call (15s for the web-search fallback) so a single hung registry cannot stall the workflow under hostile network conditions. Treat a timeout as a soft failure and fall through to the next entry in the chain.
+
 #### 1. npm Registry (JavaScript/TypeScript)
 
 ```

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:**