bmad-module-skill-forge 1.2.0 → 1.4.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.4.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.4.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)
 
 ---
@@ -268,15 +286,15 @@ flowchart TD
 
 ## Workflow Categories
 
-| Category | Workflows | Description |
-|----------|-----------|-------------|
-| Core | SF, BS, CS, US | Setup, brief, create, and update skills |
-| Feature | QS, SS, AN | Quick skill, stack skill, and analyze source |
-| Quality | AS, TS | Detect skill drift (AS) and verify skill completeness (TS) |
-| Architecture Verification | VS, RA | Pre-code architecture feasibility and refinement |
-| Management | RS, DS | Rename and drop skill versions with transactional safety |
-| Utility | EX | Package and export for consumption |
-| In-Agent | WS, KI | WS: show lifecycle position, active briefs, and forge tier; KI: list knowledge fragments (both in-agent, no file-based workflow) |
+| Category                  | Workflows      | Description                                                                                                                      |
+| ------------------------- | -------------- | -------------------------------------------------------------------------------------------------------------------------------- |
+| Core                      | SF, BS, CS, US | Setup, brief, create, and update skills                                                                                          |
+| Feature                   | QS, SS, AN     | Quick skill, stack skill, and analyze source                                                                                     |
+| Quality                   | AS, TS         | Detect skill drift (AS) and verify skill completeness (TS)                                                                       |
+| Architecture Verification | VS, RA         | Pre-code architecture feasibility and refinement                                                                                 |
+| Management                | RS, DS         | Rename and drop skill versions with transactional safety                                                                         |
+| Utility                   | EX             | Package and export for consumption                                                                                               |
+| In-Agent                  | WS, KI         | WS: show lifecycle position, active briefs, and forge tier; KI: list knowledge fragments (both in-agent, no file-based workflow) |
 
 ---
 
@@ -295,12 +313,12 @@ Instead of running one workflow per session, you can chain multiple workflows in
 
 ### Pipeline Aliases
 
-| Alias | Expands To | First Workflow | Required Target |
-|-------|-----------|----------------|-----------------|
-| `forge` | `BS CS TS EX` | BS | GitHub URL or local path **+** skill name |
-| `forge-quick` | `QS TS EX` | QS | GitHub URL **or** package name |
-| `onboard` | `AN CS TS EX` | AN | Project path (defaults to current directory) |
-| `maintain` | `AS US TS EX` | AS | Existing skill name |
+| Alias         | Expands To    | First Workflow | Required Target                              |
+| ------------- | ------------- | -------------- | -------------------------------------------- |
+| `forge`       | `BS CS TS EX` | BS             | GitHub URL or local path **+** skill name    |
+| `forge-quick` | `QS TS EX`    | QS             | GitHub URL **or** package name               |
+| `onboard`     | `AN CS TS EX` | AN             | Project path (defaults to current directory) |
+| `maintain`    | `AS US TS EX` | AS             | Existing skill name                          |
 
 **The first workflow's input contract defines what arguments the pipeline needs.** A bare package name works for `forge-quick` (QS resolves packages via the registry) but **not** for `forge` — BS requires both an unambiguous target (URL or path) and a skill name.
 
@@ -337,6 +355,60 @@ 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".
+
+**Exception — `/skf-brief-skill` headless emits a final result envelope and supports presets.** Headless `/skf-brief-skill` is a first-class building block for scripted brief generation (e.g. seeding briefs for N SaaS SDKs that share scope/authority defaults). Three operational contracts beyond per-gate auto-proceed:
+
+1. **Pre-supplied inputs replace prompts.** Headless args are consumed at step-01's GATE in place of the interactive menus: `target_repo`, `skill_name`, `target_version`, `language`, `source_type`, `source_authority`, `doc_urls`, `scope_type`, `scripts_intent`, `force`, `preset`. Required-arg shape depends on `source_type` (`target_repo` + `skill_name` for source-backed; `doc_urls` + `skill_name` for `docs-only`). Absent `source_authority` and `scope_type` are NOT guessed — they're resolved by signal-driven detection (`gh api user` vs. repo owner for authority; the 5-rule heuristic ladder for scope). Full grammar in [`src/skf-brief-skill/references/headless-args.md`](https://github.com/armelhbobdad/bmad-module-skill-forge/blob/main/src/skf-brief-skill/references/headless-args.md).
+
+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                       |
+   | 2    | input-missing / input-invalid |
+   | 3    | resolution-failure            |
+   | 4    | write-failure                 |
+   | 5    | overwrite-cancelled           |
+   | 6    | user-cancelled                |
+
+3. **Final result envelope on every terminal exit.** Step-05 emits a single-line `SKF_BRIEF_RESULT_JSON: {…}` envelope on **stdout** before chaining to step-06 on success; every HARD HALT emits the same envelope shape on **stderr** with `status: "error"` and a typed `halt_reason` (`input-missing`, `input-invalid`, `forge-tier-missing`, `target-inaccessible`, `gh-auth-failed`, `write-failed`, `overwrite-cancelled`, `user-cancelled`). Full envelope schema and population rules in [`src/skf-brief-skill/SKILL.md`](https://github.com/armelhbobdad/bmad-module-skill-forge/blob/main/src/skf-brief-skill/SKILL.md) § "Result Contract (Headless)".
+
+**Presets (`--preset <name>`).** Loads `{sidecar_path}/brief-presets/{name}.yaml` and merges its keys as defaults at step-01 §8; explicit headless args override preset values. The preset file is YAML containing any subset of the headless args above; unknown fields are ignored with a warning. Useful for repeated patterns — e.g. briefing 5 SaaS SDKs that all share `source_authority=community`, `scope_type=full-library`, `scripts_intent=skip`.
+
 ---
 
 ## 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.4.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 test/test-skf-validate-brief-inputs.py test/test-skf-emit-brief-result-envelope.py test/test-skf-write-skill-brief.py test/test-skf-detect-workspaces.py test/test-skf-recommend-scope-type.py test/test-skf-detect-language.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.

package/src/shared/scripts/schemas/skf-brief-result-envelope.v1.json

@@ -0,0 +1,58 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/armelhbobdad/bmad-module-skill-forge/src/shared/scripts/schemas/skf-brief-result-envelope.v1.json",
+  "title": "SKF_BRIEF_RESULT_JSON envelope (v1)",
+  "description": "Single-line JSON document emitted by skf-brief-skill step-05 §4b when {headless_mode} is true, prefixed with the literal 'SKF_BRIEF_RESULT_JSON: '. Pipelines grep one line out of the workflow log to branch on the brief outcome without parsing prose. Schema mirrors the contract in src/skf-brief-skill/SKILL.md Result Contract section.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["status", "brief_path", "skill_name", "version", "language", "scope_type", "exit_code", "halt_reason"],
+  "properties": {
+    "status": {
+      "type": "string",
+      "enum": ["success", "error"],
+      "description": "'success' on the terminal happy path (after step-05 wrote the brief and step-06 returned). 'error' on any HARD HALT."
+    },
+    "brief_path": {
+      "type": ["string", "null"],
+      "description": "Absolute path to the written skill-brief.yaml on success. Null when the run errored before any file was written (or when overwrite-cancelled aborted before write)."
+    },
+    "skill_name": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Brief's skill_name field — present in every envelope (success and error) since it is captured at step-01 §6 before any of the other failure branches."
+    },
+    "version": {
+      "type": ["string", "null"],
+      "description": "Resolved brief version (target_version if set, else auto-detected, else '1.0.0'). Null when the run errored before step-05's version-resolution ran."
+    },
+    "language": {
+      "type": ["string", "null"],
+      "description": "Detected or user-confirmed primary language. Null when the run errored before step-02's language-detection ran."
+    },
+    "scope_type": {
+      "type": ["string", "null"],
+      "enum": ["full-library", "specific-modules", "public-api", "component-library", "reference-app", "docs-only", null],
+      "description": "Confirmed scope.type from step-03. Null when the run errored before scope was confirmed."
+    },
+    "exit_code": {
+      "type": "integer",
+      "enum": [0, 2, 3, 4, 5, 6],
+      "description": "Process exit code matching the SKILL.md Exit Codes table. Derived deterministically from halt_reason: null→0, input-missing/input-invalid→2, forge-tier-missing/target-inaccessible/gh-auth-failed→3, write-failed→4, overwrite-cancelled→5, user-cancelled→6."
+    },
+    "halt_reason": {
+      "type": ["string", "null"],
+      "enum": [
+        null,
+        "input-missing",
+        "input-invalid",
+        "forge-tier-missing",
+        "target-inaccessible",
+        "gh-auth-failed",
+        "write-failed",
+        "overwrite-cancelled",
+        "user-cancelled"
+      ],
+      "description": "Null on success. One of the documented HALT classes on error. Pipelines branch on this to surface the right operator message without grepping the prose error."
+    }
+  }
+}

package/src/shared/scripts/schemas/skill-brief.v1.json

@@ -0,0 +1,77 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/armelhbobdad/bmad-module-skill-forge/src/shared/scripts/schemas/skill-brief.v1.json",
+  "title": "skill-brief.yaml (v1)",
+  "description": "Canonical schema for the skill-brief.yaml artifact written by skf-brief-skill step-05 and consumed by skf-create-skill, skf-update-skill, skf-audit-skill. Mirrors src/skf-brief-skill/assets/skill-brief-schema.md.",
+  "type": "object",
+  "required": ["name", "version", "source_repo", "language", "description", "forge_tier", "created", "created_by", "scope"],
+  "properties": {
+    "name": {
+      "type": "string",
+      "pattern": "^[a-z0-9]([a-z0-9-]*[a-z0-9])?$",
+      "description": "Unique skill identifier (kebab-case)."
+    },
+    "version": {
+      "type": "string",
+      "pattern": "^v?\\d+\\.\\d+\\.\\d+([.\\-+][0-9A-Za-z][0-9A-Za-z.\\-+]*)?$",
+      "description": "Resolved semver. target_version wins; else auto-detected; else 1.0.0."
+    },
+    "target_version": {
+      "type": "string",
+      "pattern": "^v?\\d+\\.\\d+\\.\\d+([.\\-+][0-9A-Za-z][0-9A-Za-z.\\-+]*)?$",
+      "description": "User-specified target. When present, MUST equal version."
+    },
+    "source_type": {
+      "type": "string",
+      "enum": ["source", "docs-only"]
+    },
+    "source_repo": {
+      "type": "string",
+      "minLength": 1,
+      "description": "GitHub URL or local path. Required even for docs-only (set to doc site URL)."
+    },
+    "source_authority": {
+      "type": "string",
+      "enum": ["official", "community", "internal"]
+    },
+    "doc_urls": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": ["url"],
+        "properties": {
+          "url": { "type": "string", "minLength": 1 },
+          "label": { "type": "string" }
+        }
+      },
+      "minItems": 1,
+      "description": "Required when source_type is docs-only; allowed as supplemental for source."
+    },
+    "language": { "type": "string", "minLength": 1 },
+    "description": { "type": "string", "minLength": 1 },
+    "forge_tier": {
+      "type": "string",
+      "enum": ["Quick", "Forge", "Forge+", "Deep"]
+    },
+    "created": {
+      "type": "string",
+      "pattern": "^\\d{4}-\\d{2}-\\d{2}$"
+    },
+    "created_by": { "type": "string", "minLength": 1 },
+    "scripts_intent": { "type": "string", "minLength": 1 },
+    "assets_intent": { "type": "string", "minLength": 1 },
+    "scope": {
+      "type": "object",
+      "required": ["type", "include", "exclude", "notes"],
+      "properties": {
+        "type": {
+          "type": "string",
+          "enum": ["full-library", "specific-modules", "public-api", "component-library", "reference-app", "docs-only"]
+        },
+        "include": { "type": "array", "items": { "type": "string" } },
+        "exclude": { "type": "array", "items": { "type": "string" } },
+        "notes": { "type": "string" }
+      }
+    }
+  }
+}

package/src/shared/scripts/schemas/workspace-detection.v1.json

@@ -0,0 +1,44 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://armelhbobdad.github.io/bmad-module-skill-forge/schemas/workspace-detection.v1.json",
+  "title": "Workspace Detection Result (v1)",
+  "description": "Result envelope returned by skf-detect-workspaces.py. Reports whether the inspected target is a monorepo, which manifest kind drives it, and the list of resolved workspaces.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["is_monorepo", "manifest_kind", "workspaces", "warnings"],
+  "properties": {
+    "is_monorepo": {
+      "type": "boolean",
+      "description": "True if any detector matched at least one workspace."
+    },
+    "manifest_kind": {
+      "description": "Which detector produced the result. null when is_monorepo is false.",
+      "oneOf": [
+        {
+          "type": "string",
+          "enum": ["npm-workspaces", "pnpm-workspaces", "lerna", "cargo-workspace", "python-multi-package", "generic-folders"]
+        },
+        { "type": "null" }
+      ]
+    },
+    "workspaces": {
+      "type": "array",
+      "description": "Resolved workspaces. Empty when is_monorepo is false. Each entry has a name, a repository-relative path, and the path to its recognised manifest.",
+      "items": {
+        "type": "object",
+        "additionalProperties": false,
+        "required": ["name", "path", "manifest"],
+        "properties": {
+          "name": { "type": "string", "minLength": 1 },
+          "path": { "type": "string", "minLength": 1 },
+          "manifest": { "type": "string", "minLength": 1 }
+        }
+      }
+    },
+    "warnings": {
+      "type": "array",
+      "description": "Non-fatal parse warnings encountered during detection (e.g. malformed manifests that the detector skipped).",
+      "items": { "type": "string" }
+    }
+  }
+}