bmad-module-skill-forge 1.2.0 → 1.3.0

package/.claude-plugin/marketplace.json

@@ -30,7 +30,7 @@
       "name": "skill-forge",
       "source": "./",
       "description": "Evidence-based agent skills compiler with progressive capability tiers (Quick/Forge/Forge+/Deep).",
-      "version": "1.2.0",
+      "version": "1.3.0",
       "author": {
         "name": "Armel"
       },

package/docs/_data/pinned.yaml

@@ -26,7 +26,7 @@
 # Enforced two ways: (1) release.yaml bumps this line in the same commit
 # as package.json + marketplace.json on every release; (2) validate-docs-drift.js
 # cross-checks this value against package.json.version and fails on mismatch.
-skf_version: "1.2.0"
+skf_version: "1.3.0"
 
 # Path to the oh-my-skills repo, resolved relative to this repo's root.
 # Override at runtime with the OMS environment variable if oh-my-skills

package/docs/skill-model.md

@@ -25,51 +25,45 @@ Setup detects your installed tools and sets your tier automatically:
 ```
 
 ```
-┌─────────────────────────────┐
-│ FORGE STATUS                │
-└─────────────────────────────┘
+═══════════════════════════════════════
+  FORGE STATUS
+═══════════════════════════════════════
 
   Tier:  Deep
-
-  Deep tier active. Full capability unlocked — AST-backed code
-  analysis, GitHub repository exploration, and QMD knowledge search
-  with cross-repository synthesis. Maximum provenance and intelligence.
+  Deep tier active. Full capability unlocked — AST-backed code analysis,
+  GitHub repository exploration, and QMD knowledge search with
+  cross-repository synthesis. Maximum provenance and intelligence.
 
   Tools Detected:
-    ast-grep  — 0.42.0
-    gh        — 2.89.0
-    qmd       — operational (104 docs indexed globally)
-    ccc       — 0.2.10 (daemon healthy)
+  - ast-grep 0.42.0
+  - gh 2.91.0 (2026-04-22)
+  - qmd 2.0.1
+  - ccc (daemon healthy)
 
   QMD Registry:
-    0 collection(s) healthy
-    39 orphaned collection(s) removed
-    (empty — collections are created automatically when you run [CS] Create Skill)
+  0 collection(s) healthy
+  23 orphaned collection(s) kept
 
   CCC Index:
-    indexed this run — semantic discovery ready (2 files, 14 chunks)
-    SKF infrastructure excluded: _bmad, _bmad-output, .claude,
-    _skf-learn, skills, forge-data
-
-┌────────────────────────────────┐
-│ Forge ready. Deep tier active. │
-└────────────────────────────────┘
-
-Health Check: Clean run. No workflow issues to report.
+  indexed this run — semantic discovery ready (1 file)
 
-Workflow complete.
+  Files written this run:
+  - forge-tier.yaml — {project-root}/_bmad/_memory/forger-sidecar/forge-tier.yaml
+  - .cocoindex_code/settings.yml — {project-root}/.cocoindex_code/settings.yml (6 SKF exclusion patterns merged)
+  - .cocoindex_code/ ccc index — 1 file indexed
 
----
-Forge is live at Deep tier, armel. All four core tools are available, the CCC semantic index is built, and the QMD registry is clean.
+═══════════════════════════════════════
+  Forge ready. Deep tier active.
+═══════════════════════════════════════
 
-What would you like to forge next? Common starting points:
+  Next: try [BS] Brief Skill to scope your first compilation target,
+  or [QS] Quick Skill for a fast template-driven path.
+  Already have a skill? [AS] Audit Skill drift-checks an existing skill
+  against current sources.
 
-- QS — fast skill from a GitHub URL or package name
-- BS → CS — brief, then compile a skill from source
-- AN — analyze a large repo to discover what's worth skilling
-- WS — show current lifecycle status
+Health Check: Clean run. No workflow issues to report.
 
-Or chain them: forge (BS CS TS EX), forge-quick (QS TS EX), onboard (AN CS TS EX).
+Workflow complete.
 ```
 
 Don't have ast-grep, cocoindex-code, or QMD yet? No problem — Quick mode works with no additional tools. Optional GitHub CLI improves source access. Install tools later; your tier upgrades automatically.

package/docs/troubleshooting.md

@@ -9,6 +9,18 @@ If something isn't working, start here. For general setup help see [Getting Star
 
 ## Common errors
 
+### "Setup cannot proceed: `uv` is not installed"
+
+Surfaced by `/skf-setup` On Activation when `uv --version` is missing on `$PATH`. SKF helpers depend on `uv` to auto-resolve their Python dependencies via PEP 723 inline metadata; bare `python3` ignores that metadata and would fail later with `ModuleNotFoundError: No module named 'yaml'`. The probe halts the workflow up-front with one cohesive diagnostic instead of letting five steps each fail individually.
+
+**Fix:** install `uv` from <https://docs.astral.sh/uv/getting-started/installation/> and re-run `/skf-setup`. `uv` is documented as a runtime prerequisite in [Getting Started → Prerequisites](../getting-started/#prerequisites-full-reference).
+
+### "Setup cannot proceed: `_bmad/skf/config.yaml` was not found"
+
+Surfaced by `/skf-setup` On Activation when the SKF install config is missing — typically because you invoked `/skf-setup` from a directory that is not an SKF-initialised project. The check runs before any file mutation so nothing is written.
+
+**Fix:** from the project root, run `npx bmad-module-skill-forge install` (or `npx bmad-method install` and add SKF as a custom module — see [Getting Started → Install](../getting-started/#install)), then re-run `/skf-setup`. If you ARE in the right project but the file was deleted, restore it from version control or re-run the SKF installer. A separate "config.yaml is not valid YAML" diagnostic surfaces the parser error inline if the file exists but is malformed — open the file at the named path and repair the YAML.
+
 ### Forge reports ast-grep is unavailable
 
 If setup reports that ast-grep was not detected, install it to unlock the Forge tier: <https://ast-grep.github.io>. Re-run `@Ferris SF` afterward — your tier upgrades automatically.

package/docs/workflows.md

@@ -21,6 +21,11 @@ Trigger workflows by typing commands to [Ferris](../agents/). See [Concepts](../
 
 **Key Steps:** Detect tools + Determine tier → CCC index check (Forge+) → Write forge-tier.yaml → QMD + CCC registry hygiene (Deep/Forge+) → Status report
 
+**Flags:**
+
+- `--require-tier=<Quick|Forge|Forge+|Deep>` — fail-fast for CI: if the calculated tier does not satisfy the requested tier (tool-prerequisite check, not a name comparison — Deep does NOT subsume Forge+ because Deep does not require ccc), the workflow halts with a "REQUIRED TIER NOT MET" block and exits without chaining to the health check. Pipelines branch on the JSON envelope's `require_tier_satisfied` field.
+- `--headless` / `-H` — see [Headless Mode](#headless-mode) below. For `/skf-setup` specifically, headless mode emits a single-line `SKF_SETUP_RESULT_JSON: {…}` envelope to stdout (schema-locked, includes `tier`, `previous_tier`, `tier_changed`, `tools`, `tools_added`/`removed`, `files_written`, `warnings`, `error`) and SUPPRESSES the human-readable banner — the entire payload pipelines need is on one parseable line.
+
 **Agent:** Ferris (Architect mode)
 
 ---
@@ -79,6 +84,19 @@ Trigger workflows by typing commands to [Ferris](../agents/). See [Concepts](../
 
 **Key Steps:** Resolve target → Ecosystem check → Quick extract → Compile → Validate → Write
 
+**Headless / batch flags:**
+
+- `--headless` / `-H` — auto-proceed all confirmation gates with documented defaults; emits structured stderr progress events and exit codes (see [Headless Mode](#headless-mode))
+- `--batch <file>` — process N targets from a text file in sequence (one target per line, `#` comments and `language=<lang>` / `scope=<path>` per-line modifiers supported); implies `--headless`
+- `--fail-fast` — only with `--batch`; abort the whole batch on the first per-target failure instead of recording it and proceeding
+
+**Per-target overrides** (apply to a single-target run, or globally to every target in `--batch`):
+
+- `--description "<string>"` — override the LLM-derived description used in `SKILL.md` frontmatter and `metadata.json`
+- `--exports "name1,name2,..."` — override the extracted export list (comma-separated)
+- `--skip-snippet` — skip `context-snippet.md` generation and write
+- `--no-active-pointer` — skip the active-pointer flip in finalize (deliverables still land in `{skill_package}`)
+
 **Agent:** Ferris (Architect mode)
 
 ---
@@ -337,6 +355,41 @@ Add `--headless` or `-H` to any workflow command to skip all confirmation gates.
 
 You can also set `headless_mode: true` in your forge preferences (`_bmad/_memory/forger-sidecar/preferences.yaml`) to make headless the default for all workflows.
 
+**Exception — `/skf-setup` headless emits a single-line JSON envelope.** Unlike other workflows, headless `/skf-setup` SUPPRESSES the human-readable status banner entirely and emits exactly one prefixed line on stdout:
+
+```
+SKF_SETUP_RESULT_JSON: {"skf_setup":{"tier":"Deep","previous_tier":"Forge","tier_changed":true,"tools":{...},"tools_added":[...],"tools_removed":[],"config_path":"...","ccc_index":{...},"files_written":[...],"tier_override_active":false,"tier_override_invalid":false,"require_tier_satisfied":null,"warnings":[],"error":null}}
+```
+
+Parent skills and CI pipelines `grep` one line out of the workflow log to learn the outcome — no ASCII-art parsing, no race against the [`forge-tier.yaml`](https://github.com/armelhbobdad/bmad-module-skill-forge/blob/main/src/skf-setup/steps-c/step-02-write-config.md) writer. The envelope schema is versioned at [`src/shared/scripts/schemas/skf-setup-result-envelope.v1.json`](https://github.com/armelhbobdad/bmad-module-skill-forge/blob/main/src/shared/scripts/schemas/skf-setup-result-envelope.v1.json) and asserted against on every emit.
+
+**Exception — `/skf-quick-skill` headless emits structured progress + result envelopes.** Headless `/skf-quick-skill` runs are first-class building blocks for batch automators. Three operational contracts beyond per-gate auto-proceed:
+
+1. **Per-step JSON progress events to `stderr`** at each step's entry / exit / HARD HALT — one line per event, no pretty-print:
+
+   ```
+   {"step":3,"name":"quick-extract","status":"start"}
+   {"step":3,"name":"quick-extract","status":"done"}
+   {"step":1,"name":"resolve-target","status":"halt","exit":3}
+   ```
+
+   `<name>` is the kebab portion of the step filename: `resolve-target`, `ecosystem-check`, `quick-extract`, `compile`, `write-and-validate`, `finalize`, `health-check`.
+
+2. **Structured exit-code map.** Every HARD HALT exits with a stable code so pipelines branch on the failure class without grepping message text:
+
+   | Code | Meaning             |
+   | ---- | ------------------- |
+   | 0    | success             |
+   | 3    | resolution-failure  |
+   | 4    | write-failure       |
+   | 5    | overwrite-cancelled |
+   | 6    | compile-cancelled   |
+   | 7    | finalize-blocked    |
+
+3. **Error-variant result contract on every HARD HALT.** A `SKF_QUICK_SKILL_RESULT_JSON: {…}` envelope is emitted on `stderr` (always) and copied to `{skill_package}/quick-skill-result-latest.json` when the skill package is known (HALTs at step-05 §1 onward). The schema and full population rules live in [`src/skf-quick-skill/SKILL.md`](https://github.com/armelhbobdad/bmad-module-skill-forge/blob/main/src/skf-quick-skill/SKILL.md) § "Result Contract on HARD HALT".
+
+**Batch mode (`--batch <file>`).** Drives N targets through the full pipeline (steps 1–7 each) in sequence. Input format: one target per line, `#` comments and blank lines ignored, optional per-line modifiers `language=<lang>` and `scope=<path>`. Per-target output lands in `{skill_package}/` as today; an aggregated summary writes to `{skills_output_folder}/_batch/quick-skill-batch-{ts}.json` (with `quick-skill-batch-latest.json` copy). Per-target boundary events (`{"batch":N,"target":"…","status":"start|done|fail",…}`) and a final `{"batch_summary":true,…}` event extend the per-step event stream above. Full input grammar, summary schema, and exit-code semantics in [`src/skf-quick-skill/SKILL.md`](https://github.com/armelhbobdad/bmad-module-skill-forge/blob/main/src/skf-quick-skill/SKILL.md) § "Batch Mode".
+
 ---
 
 ## Terminal Step: Health Check

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "bmad-module-skill-forge",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "BMAD module — Turn code and docs into instructions AI agents can actually follow. Progressive capability tiers (Quick/Forge/Forge+/Deep).",
   "keywords": [
     "bmad",
@@ -53,7 +53,7 @@
     "test:cli": "node test/test-cli-integration.js",
     "test:install": "node test/test-installation-components.js",
     "test:knowledge": "node test/test-knowledge-base.js",
-    "test:python": "uv run --with pytest --with pyyaml pytest test/test-compute-score-contract.py test/test-skf-preflight.py test/test-skf-skill-inventory.py test/test-skf-validate-output.py test/test-skf-validate-frontmatter.py test/test-skf-manifest-ops.py test/test-skf-rebuild-managed-sections.py test/test-skf-severity-classify.py test/test-skf-structural-diff.py test/test-skf-detect-tools.py test/test-skf-forge-tier-rw.py test/test-skf-emit-result-envelope.py test/test-skf-qmd-classify-collections.py test/test-skf-merge-ccc-exclusions.py -v",
+    "test:python": "uv run --with pytest --with pyyaml pytest test/test-compute-score-contract.py test/test-skf-preflight.py test/test-skf-skill-inventory.py test/test-skf-validate-output.py test/test-skf-validate-frontmatter.py test/test-skf-manifest-ops.py test/test-skf-rebuild-managed-sections.py test/test-skf-severity-classify.py test/test-skf-structural-diff.py test/test-skf-detect-tools.py test/test-skf-forge-tier-rw.py test/test-skf-emit-result-envelope.py test/test-skf-qmd-classify-collections.py test/test-skf-merge-ccc-exclusions.py test/test-skf-resolve-package.py test/test-skf-extract-public-api.py test/test-skf-render-quick-metadata.py -v",
     "test:schemas": "node test/test-agent-schema.js",
     "test:workflow": "node test/test-workflow-state.js",
     "validate:refs": "node tools/validate-file-refs.js --strict",

package/src/shared/references/output-contract-schema.md

@@ -33,3 +33,13 @@ Each run writes **two files** to `{output_dir}`:
 Write the per-run record first, then copy it to the `-latest.json` path. If the copy fails, the per-run record still exists — the run is not lost.
 
 **Consumers (forger, CI, chained workflows):** read from `{skill-name}-result-latest.json`. Do not enumerate timestamped files unless inspecting prior-run history.
+
+## Available Helpers
+
+There is no generic helper that writes the schema above; each skill assembles the JSON in its terminal step today. One specialised helper exists:
+
+- **`src/shared/scripts/skf-emit-result-envelope.py`** — `skf-setup`-specific. Writes a different envelope (`SKF_SETUP_RESULT_JSON: {…}`) following the JSON schema at `src/shared/scripts/schemas/skf-setup-result-envelope.v1.json`. Carries setup-specific fields (`tier`, `previous_tier`, `tools`, `ccc_index`, `tier_override_*`, `qmd_status`, etc.) that have no analogue in other workflows. **Do not reuse for non-skf-setup skills.**
+
+A generalised emitter (matching this document's schema) is a reasonable future helper when a second consumer materialises with the same shape. For now, skills that write this contract assemble the JSON in their terminal step — the work is small (5–8 fields) and skill-specific summary content benefits from being expressed inline alongside the rest of the step's logic.
+
+skf-quick-skill writes both the success-variant contract (`step-06-finalize.md` §3) and the error-variant contract on every HARD HALT (per `SKILL.md` § "Result Contract on HARD HALT") in this hand-assembled style.