bmad-module-skill-forge 1.1.0 → 1.2.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.1.0",
+      "version": "1.2.0",
       "author": {
         "name": "Armel"
       },

package/README.md

@@ -16,7 +16,7 @@
 [![Discord](https://img.shields.io/badge/Discord-Join%20Community-7289da?logo=discord&logoColor=white)](https://discord.gg/gk8jAdXWmj)
 [![GitHub stars](https://img.shields.io/github/stars/armelhbobdad/bmad-module-skill-forge?style=social)](https://github.com/armelhbobdad/bmad-module-skill-forge/stargazers)
 
-_Skill Forge analyzes your code repositories, documentation, and developer discourse to build verified instruction files for AI agents. Every instruction links back to a specific file and line in the source it was compiled from._
+_Skill Forge analyzes your code repositories, documentation, and developer discourse to build verified instruction files for AI agents. Every instruction links back to its upstream — a specific `file:line` at a pinned commit when source is available, or a documentation URL when it isn't._
 
 **If SKF fixes your agent's API guesses, give it a ⭐ — it helps others find this tool.**
 **If it saved you an afternoon, [grab me a coffee ☕](https://buymeacoffee.com/armelhbobdad) — it helps me keep forging.**
@@ -94,7 +94,7 @@ A skeptical reader is probably already considering one of these alternatives:
 
 |                            | **Skill Forge**                           | MCP doc servers   | Hand-edited `.cursorrules` | awesome-\* lists |
 | -------------------------- | ----------------------------------------- | ----------------- | -------------------------- | ---------------- |
-| Reproducible from source   | AST extraction + pinned commit            | varies; opaque    | whatever you wrote         | none             |
+| Reproducible from upstream | AST + pinned commit (or pinned doc URL)   | varies; opaque    | whatever you wrote         | none             |
 | Version-pinned & immutable | yes — per-version directories             | runtime-dependent | rots silently              | no               |
 | Audit trail                | `provenance-map.json` + test + evidence   | depends on server | none                       | none             |
 | Runtime cost               | zero (markdown + JSON)                    | a running process | zero                       | zero             |
@@ -115,13 +115,15 @@ SKF extracts real function signatures, types, and patterns from code, docs, and
 
 ## Verifying a Skill
 
-You can falsify any AST citation in an SKF-compiled skill in under a minute:
+You can falsify any citation in an SKF-compiled skill in under a minute:
 
 1. **Open the skill's `provenance-map.json`** — find your symbol; read its `source_file` and `source_line`.
 2. **Open the skill's `metadata.json`** — read `source_commit` and `source_repo`.
 3. **Jump to the upstream repo at that commit**, open that file, find that line. The signature in `SKILL.md` should match the one you're reading.
 
-If it doesn't, that's a bug — open an issue and SKF will republish with a new commit SHA and a new provenance map. Falsifiability isn't a feature; it's the whole deal.
+For docs-only skills, the audit shape is the same — `provenance-map.json` still lists every symbol — but entries cite `[EXT:{url}]` instead of `file:line@SHA`, and step 3 becomes "open the doc URL and confirm the signature matches."
+
+If it doesn't, that's a bug — open an issue and SKF will republish the skill with a fresh provenance map (a new commit SHA for source skills, a fresh fetch for docs-only). Falsifiability isn't a feature; it's the whole deal.
 
 **Reference output: [oh-my-skills](https://github.com/armelhbobdad/oh-my-skills)** — four Deep-tier skills compiled by SKF (cocoindex, cognee, Storybook v10, uitripled), each shipping its full audit trail in-repo. Scores range from 99.0% to 99.49%. Every claim walks to an upstream line in under 60 seconds. Serves as both the worked example for this section and ongoing proof that the pipeline does what it says.
 

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.1.0"
+skf_version: "1.2.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/bmad-synergy.md

@@ -9,7 +9,7 @@ This page builds on BMAD concepts (BMM phases, TEA, modules). New to BMAD? Start
 
 ## Launcher Skills vs Content Skills
 
-A BMAD project that also uses SKF ends up with two different kinds of `SKILL.md` files living in the same IDE skills directory. SKF supports 23 IDEs — Claude Code (`.claude/skills/`), Cursor (`.cursor/skills/`), GitHub Copilot (`.github/skills/`), Windsurf (`.windsurf/skills/`), Cline (`.cline/skills/`), Roo Code (`.roo/skills/`), Gemini CLI (`.gemini/skills/`), and 16 others — each with its own skill directory. See the [complete IDE → Context File mapping](https://github.com/armelhbobdad/bmad-module-skill-forge/blob/main/src/skf-export-skill/assets/managed-section-format.md) for the full list. They look similar. They are not the same thing. This is the single most durable point of confusion, so get it straight up front.
+A BMAD project that also uses SKF ends up with two different kinds of `SKILL.md` files living in the same IDE skills directory. SKF supports 24 IDEs — Claude Code (`.claude/skills/`), Cursor (`.cursor/skills/`), GitHub Copilot (`.github/skills/`), Windsurf (`.windsurf/skills/`), Cline (`.cline/skills/`), Roo Code (`.roo/skills/`), Gemini CLI (`.gemini/skills/`), and 17 others — each with its own skill directory. See the [complete IDE → Context File mapping](https://github.com/armelhbobdad/bmad-module-skill-forge/blob/main/src/skf-export-skill/assets/managed-section-format.md) for the full list. They look similar. They are not the same thing. This is the single most durable point of confusion, so get it straight up front.
 
 | | BMAD launcher skill | SKF content skill |
 |---|---|---|
@@ -166,7 +166,7 @@ Beyond briefing, CIS and SKF don't overlap — CIS covers ideation, storytelling
 
 ## Delivery and Lifecycle in a BMAD Project
 
-`@Ferris EX` is the **only workflow that introduces new skill context** into the three context files that serve all 23 IDEs: `CLAUDE.md` (Claude Code), `.cursorrules` (Cursor), and `AGENTS.md` (the remaining 21 IDEs — GitHub Copilot, Windsurf, Cline, Roo Code, Gemini CLI, and others). Each IDE also has its own skill root directory where skill files are installed (e.g., `.windsurf/skills/`, `.roo/skills/`, `.gemini/skills/`). Create-skill and update-skill produce draft artifacts that never touch those files directly — nothing reaches an agent's passive context until it has been through the EX gate. See [Skill Model → Dual-Output Strategy](../skill-model/#dual-output-strategy) for the architectural rationale.
+`@Ferris EX` is the **only workflow that introduces new skill context** into the three context files that serve all 24 IDEs: `CLAUDE.md` (Claude Code), `.cursorrules` (Cursor), and `AGENTS.md` (the remaining 22 IDEs — GitHub Copilot, Windsurf, Cline, Roo Code, Gemini CLI, and others). Each IDE also has its own skill root directory where skill files are installed (e.g., `.windsurf/skills/`, `.roo/skills/`, `.gemini/skills/`). Create-skill and update-skill produce draft artifacts that never touch those files directly — nothing reaches an agent's passive context until it has been through the EX gate. See [Skill Model → Dual-Output Strategy](../skill-model/#dual-output-strategy) for the architectural rationale.
 
 This matters specifically in a BMAD project: you may have multiple BMAD modules, each with its own launcher skills, plus SKF content skills, all trying to contribute context. The write-guard means only verified, tested SKF skills ever reach an agent's passive context — nothing half-baked sneaks in. `@Ferris EX` injects managed sections that coexist cleanly with whatever BMAD's installer wrote in the same files.
 

package/docs/getting-started.md

@@ -135,7 +135,7 @@ Analyzes your project's dependencies and generates a consolidated stack skill wi
 
 ## Common use cases
 
-> **Looking for end-to-end examples?** See [Examples](../examples/) for eleven real-world scenarios with full command transcripts — from Quick Skill under a minute, to brownfield onboarding, stack verification, release-prep drift remediation, and SaaS docs-only skills.
+> **Looking for end-to-end examples?** See [Examples](../examples/) for thirteen real-world scenarios with full command transcripts — from Quick Skill under a minute, to brownfield onboarding, stack verification, release-prep drift remediation, and SaaS docs-only skills.
 
 ---
 

package/docs/troubleshooting.md

@@ -13,7 +13,7 @@ If something isn't working, start here. For general setup help see [Getting Star
 
 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.
 
-### "No brief found"
+### "No skill brief found"
 
 Run `@Ferris BS` first to create a skill brief, or use `@Ferris QS` for brief-less generation. `CS` requires either a brief or a direct invocation with scope arguments.
 

package/docs/why-skf.md

@@ -3,7 +3,7 @@ title: Why Skill Forge?
 description: The strategic case for SKF — the problem it solves, how it compares to alternatives, who it's for, and who it isn't.
 ---
 
-Skill Forge is the only AI-skills toolchain where every claim your agent reads cites a file, a line, and a commit SHA. Not "sourced from training data." Not "retrieved from context." **Cited.** You can open the upstream repo at the pinned commit and see the function exists — in under a minute. That's the wedge. This page explains why it matters, how SKF compares to alternatives, and who it's for.
+Skill Forge is the only AI-skills toolchain where every claim your agent reads points back to a real upstream location — a `file:line` at a pinned commit when source is available, or a documentation URL when it isn't. Not "sourced from training data." Not "retrieved from context." **Cited.** You can open the upstream repo (or the doc page) and see the function exists — in under a minute. That's the wedge. This page explains why it matters, how SKF compares to alternatives, and who it's for.
 
 ---
 
@@ -26,7 +26,7 @@ SKF treats this as a citation problem, not a model problem. If a skill claims `c
 | RAG / context stuffing | Retrieves relevant code snippets | Returns fragments without synthesis — no coherent skill output |
 | Manual authoring | High initial accuracy | Drifts as the source code changes, doesn't scale across dependencies |
 | IDE built-in context (Copilot, Cursor) | Convenient, zero setup | Uses generic training data, not your project's specific integration patterns |
-| **Skill Forge** | **Every instruction cites upstream `file:line` at a pinned commit. Falsifiable in 60 seconds.** | **Coverage depends on which tools you've installed (Quick / Forge / Forge+ / Deep tiers).** |
+| **Skill Forge** | **Every instruction cites upstream — `file:line@SHA` for source skills, doc URL for docs-only skills. Falsifiable in 60 seconds.** | **Coverage depends on which tools you've installed (Quick / Forge / Forge+ / Deep tiers).** |
 
 </div>
 
@@ -40,6 +40,8 @@ Pick any symbol in any SKF-compiled skill. Three clicks:
 2. Open the skill's `provenance-map.json` — find your symbol; it lists the file and line.
 3. Visit the upstream repo at that commit and that line. The signature in the skill should match.
 
+For docs-only skills, the audit shape is the same — `provenance-map.json` still lists every symbol — but entries cite `[EXT:{url}]` instead of `file:line@SHA`, and step 3 becomes "open the doc URL and confirm the signature matches."
+
 If it doesn't, **that's a bug.** [Open an issue](https://github.com/armelhbobdad/bmad-module-skill-forge/issues/new/choose) and SKF republishes the skill with a new commit SHA and a new provenance map. No other AI-skills tool treats disagreement between claim and source as a defect. SKF does.
 
 See the [Verifying a Skill](../verifying-a-skill/) page for the full three-step audit on real skills, the test reports that log *exactly* where coverage falls short, and the scoring formula behind the 80% pass threshold.
@@ -78,9 +80,8 @@ You're considering running SKF across a brownfield platform. You need to know ab
 ## Not for you if…
 
 - You want docs that hand-hold through every happy path with screenshots and emojis. SKF is a citation machine, not a tutorial series.
-- You need perfect coverage of every private implementation detail. SKF extracts public APIs; if you want internals, read the code directly.
 - You don't have Node.js ≥ 22 and Python ≥ 3.10 installed. SKF is a Node/Python toolchain at its core.
-- You're looking for something that generates skills from natural-language descriptions alone. SKF compiles from source code and documentation — not prompts.
+- You have neither source code nor published documentation for the target. SKF compiles from one or both — a source repo (citations as `file:line@SHA`) or doc URLs (citations as `[EXT:{url}]`). A vague description with no upstream artifact to cite isn't enough.
 
 Everything else is downstream of one question: *are the instructions your AI reads provably true?* If yes, SKF isn't adding value. If you can't be sure, SKF is the tool.
 

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "bmad-module-skill-forge",
-  "version": "1.1.0",
+  "version": "1.2.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 -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 -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/knowledge/ccc-bridge.md

@@ -48,7 +48,7 @@ Returns: list of `{file, score, snippet}` entries ranked by semantic relevance t
 ### `ccc_bridge.status()`
 
 **Resolves to:** Two-step verification:
-1. `ccc --help` — confirms binary exists (exit 0)
+1. `ccc --help` — confirms binary exists (exit 0) AND output contains the `CocoIndex Code` identity marker (rejects unrelated `ccc`-named binaries shadowing PATH)
 2. `ccc doctor` — confirms daemon is running, extracts version string, validates embedding model
 
 **Usage context:** Called exclusively by setup step-01 during tool detection. Downstream workflows read the result from forge-tier.yaml — they do not re-verify.

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

@@ -0,0 +1,134 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://github.com/armelhbobdad/bmad-module-skill-forge/src/shared/scripts/schemas/skf-setup-result-envelope.v1.json",
+  "title": "SKF_SETUP_RESULT_JSON envelope (v1)",
+  "description": "Single-line JSON document emitted by skf-setup step-04 §4 when {headless_mode} is true, prefixed with the literal 'SKF_SETUP_RESULT_JSON: '. Pipelines grep one line out of the workflow log without parsing ASCII-art and without racing the forge-tier.yaml writer. Schema added in PR #247, extended in PR #248 (header / outputs / failure modes), extended again in this PR with previous_tier / tier_changed / tools_added / tools_removed / error.",
+  "type": "object",
+  "additionalProperties": false,
+  "required": ["skf_setup"],
+  "properties": {
+    "skf_setup": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "tier",
+        "previous_tier",
+        "tier_changed",
+        "tools",
+        "tools_added",
+        "tools_removed",
+        "config_path",
+        "ccc_index",
+        "files_written",
+        "tier_override_active",
+        "tier_override_invalid",
+        "require_tier_satisfied",
+        "warnings",
+        "error"
+      ],
+      "properties": {
+        "tier": {
+          "type": "string",
+          "enum": ["Quick", "Forge", "Forge+", "Deep"],
+          "description": "Active capability tier this run."
+        },
+        "previous_tier": {
+          "type": ["string", "null"],
+          "enum": ["Quick", "Forge", "Forge+", "Deep", null],
+          "description": "Tier read from the existing forge-tier.yaml at workflow start. Null on first runs."
+        },
+        "tier_changed": {
+          "type": "boolean",
+          "description": "True when previous_tier is non-null AND differs from tier. False on first runs and same-tier re-runs. Lets pipelines react to upgrades without re-reading forge-tier.yaml."
+        },
+        "tools": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["ast_grep", "gh_cli", "qmd", "ccc"],
+          "properties": {
+            "ast_grep": { "type": "boolean" },
+            "gh_cli": { "type": "boolean" },
+            "qmd": { "type": "boolean" },
+            "ccc": { "type": "boolean" }
+          }
+        },
+        "tools_added": {
+          "type": "array",
+          "items": { "type": "string", "enum": ["ast_grep", "gh_cli", "qmd", "ccc"] },
+          "uniqueItems": true,
+          "description": "Tool keys with available=true that were NOT available in previous_tools. On first runs, equals the currently-detected tools."
+        },
+        "tools_removed": {
+          "type": "array",
+          "items": { "type": "string", "enum": ["ast_grep", "gh_cli", "qmd", "ccc"] },
+          "uniqueItems": true,
+          "description": "Tool keys that were available in previous_tools but are NOT available now."
+        },
+        "config_path": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Absolute path to the forge-tier.yaml that this run wrote (or attempted to write — see error)."
+        },
+        "ccc_index": {
+          "type": "object",
+          "additionalProperties": false,
+          "required": ["status", "indexed_path", "file_count"],
+          "properties": {
+            "status": {
+              "type": "string",
+              "enum": ["fresh", "created", "failed", "none"]
+            },
+            "indexed_path": { "type": ["string", "null"] },
+            "file_count": { "type": ["integer", "null"], "minimum": 0 }
+          }
+        },
+        "files_written": {
+          "type": "array",
+          "items": {
+            "type": "string",
+            "enum": ["forge-tier.yaml", "preferences.yaml", "settings.yml", "ccc_index"]
+          },
+          "uniqueItems": true,
+          "description": "Files actually written this run. Empty array when a write failure halted the run before any file was written."
+        },
+        "tier_override_active": {
+          "type": "boolean",
+          "description": "True when a valid tier_override from preferences.yaml was applied."
+        },
+        "tier_override_invalid": {
+          "type": "boolean",
+          "description": "True when tier_override was set but did not match Quick|Forge|Forge+|Deep (case-sensitive). Detected tier was used as fallback."
+        },
+        "require_tier_satisfied": {
+          "type": ["boolean", "null"],
+          "description": "Null when --require-tier was not set. Otherwise true if the tool prerequisites of the requested tier are met (Deep does NOT subsume Forge+)."
+        },
+        "warnings": {
+          "type": "array",
+          "items": { "type": "string" },
+          "description": "Non-fatal anomalies surfaced during the run. May include tier_override_invalid, tier_override_unsafe, ccc_exclusion_warnings entries, ccc_registry_stale_removed entries, qmd_daemon_stopped, ccc_indexing_failed, etc. Empty when none."
+        },
+        "error": {
+          "oneOf": [
+            { "type": "null" },
+            {
+              "type": "object",
+              "additionalProperties": false,
+              "required": ["phase", "path", "reason"],
+              "properties": {
+                "phase": {
+                  "type": "string",
+                  "minLength": 1,
+                  "description": "Step or operation that failed (e.g. 'step-02-write-config:forge-tier.yaml')."
+                },
+                "path": { "type": "string", "minLength": 1, "description": "Absolute path of the file the failed operation targeted." },
+                "reason": { "type": "string", "minLength": 1, "description": "Human-readable error message." }
+              }
+            }
+          ],
+          "description": "Null on success. Object describing the failure when forge-tier.yaml or preferences.yaml could not be written. Pipelines branch on error !== null for 'exit code 2' semantics."
+        }
+      }
+    }
+  }
+}