bmad-module-skill-forge 0.2.0 → 0.3.0

package/README.md

@@ -1,8 +1,27 @@
+<div align="center">
+
+<img src="website/public/img/skf-logo.svg" alt="Skill Forge Logo" width="120" />
+
 # Skill Forge (SKF)
 
-SKF (Skill Forge) is a standalone BMAD module that transforms code repositories, documentation websites, and developer discourse into agentskills.io-compliant, version-pinned, provenance-backed agent skills. It provides a single expert agent (Ferris, Skill Architect & Integrity Guardian) and ten workflows spanning source analysis, skill briefing, AST-backed compilation, integrity testing, and ecosystem-ready export across progressive capability tiers (Quick/Forge/Deep).
+**Agent Skill Compiler — AST-verified, version-pinned, zero hallucination**
+
+[![Quality & Validation](https://github.com/armelhbobdad/bmad-module-skill-forge/actions/workflows/quality.yaml/badge.svg)](https://github.com/armelhbobdad/bmad-module-skill-forge/actions/workflows/quality.yaml)
+[![npm](https://img.shields.io/npm/v/bmad-module-skill-forge)](https://www.npmjs.com/package/bmad-module-skill-forge)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![BMad Module](https://img.shields.io/badge/BMad-module-blue)](https://github.com/bmad-code-org/BMAD-METHOD)
+[![Docs](https://img.shields.io/badge/docs-online-green)](https://armelhbobdad.github.io/bmad-module-skill-forge/)
+[![GitHub stars](https://img.shields.io/github/stars/armelhbobdad/bmad-module-skill-forge?style=social)](https://github.com/armelhbobdad/bmad-module-skill-forge/stargazers)
+
+*Transforms code repositories, documentation, and developer discourse into [agentskills.io](https://agentskills.io)-compliant agent skills with AST-backed provenance.*
+
+**If SKF helps your agent stop hallucinating, give it a ⭐ — it helps others find this tool.**
 
-Docs: <https://armelhbobdad.github.io/bmad-module-skill-forge/>
+</div>
+
+---
+
+SKF is a standalone BMAD module that provides a single expert agent (Ferris, Skill Architect & Integrity Guardian) and ten workflows spanning source analysis, skill briefing, AST-backed compilation, integrity testing, and ecosystem-ready export across progressive capability tiers (Quick/Forge/Deep).
 
 ## Why SKF
 
@@ -28,15 +47,15 @@ BMad is a small **agent + workflow engine**. There is no external orchestrator
 
 Each workflow directory contains these files, and each has a specific job:
 
-| File | What it does | When it loads |
-| --- | --- | --- |
-| `forger.agent.yaml` | Expert persona — identity, principles, critical actions, menu of triggers | First — always in context |
-| `workflow.md` | Human-readable entry point — goals, mode menu (Create/Edit/Validate), routes to first step | Second — presents mode choice |
-| `steps-c/*.md` | **Create** steps — primary execution, 4-9 sequential files | One at a time (just-in-time) |
-| `data/*.md` | Workflow-specific reference data — schemas, heuristics, rules, patterns | Read by steps on demand |
-| `templates/*.md` | Output skeletons with placeholder vars — steps fill these in to produce the final artifact | Read by steps when generating output |
-| `skf-knowledge-index.csv` | Knowledge fragment index — id, name, tags, tier, file path | Read by steps to decide which fragments to load |
-| `knowledge/*.md` | 8 reusable fragments — cross-cutting principles and patterns (e.g., `zero-hallucination.md`, `confidence-tiers.md`) | Selectively read into context when a step directs |
+| File                      | What it does                                                                                                        | When it loads                                     |
+|---------------------------|---------------------------------------------------------------------------------------------------------------------|---------------------------------------------------|
+| `forger.agent.yaml`       | Expert persona — identity, principles, critical actions, menu of triggers                                           | First — always in context                         |
+| `workflow.md`             | Human-readable entry point — goals, mode menu (Create/Edit/Validate), routes to first step                          | Second — presents mode choice                     |
+| `steps-c/*.md`            | **Create** steps — primary execution, 4-9 sequential files                                                          | One at a time (just-in-time)                      |
+| `data/*.md`               | Workflow-specific reference data — schemas, heuristics, rules, patterns                                             | Read by steps on demand                           |
+| `templates/*.md`          | Output skeletons with placeholder vars — steps fill these in to produce the final artifact                          | Read by steps when generating output              |
+| `skf-knowledge-index.csv` | Knowledge fragment index — id, name, tags, tier, file path                                                          | Read by steps to decide which fragments to load   |
+| `knowledge/*.md`          | 10 reusable fragments — cross-cutting principles and patterns (e.g., `zero-hallucination.md`, `confidence-tiers.md`) | Selectively read into context when a step directs |
 
 ```mermaid
 flowchart LR
@@ -63,25 +82,25 @@ flowchart LR
 
 Ferris operates in four workflow-driven modes (mode is determined by which workflow is running, not conversation state):
 
-| Mode | Workflows | Behavior |
-| --- | --- | --- |
-| **Architect** | AN, BS, SF | Exploratory, assembling — discovers structure and scope |
-| **Surgeon** | CS, QS, SS, US | Precise, preserving — extracts and compiles with provenance |
-| **Audit** | AS, TS | Judgmental, scoring — evaluates quality and detects drift |
-| **Delivery** | EX | Packaging, ecosystem-ready — bundles for distribution |
+| Mode          | Workflows          | Behavior                                                    |
+|---------------|--------------------|-------------------------------------------------------------|
+| **Architect** | SF, AN, BS, CS, QS, SS | Exploratory, assembling — discovers structure and scope     |
+| **Surgeon**   | US                 | Precise, preserving — extracts and compiles with provenance |
+| **Audit**     | AS, TS             | Judgmental, scoring — evaluates quality and detects drift   |
+| **Delivery**  | EX                 | Packaging, ecosystem-ready — bundles for distribution       |
 
 ## Install
 
+Requires [Node.js](https://nodejs.org/) >= 22.
+
 There are three ways to install SKF, depending on your setup.
 
 ### Method 1: Standalone (recommended for trying SKF)
 
 ```bash
-npx skill-forge install
+npx bmad-module-skill-forge install
 ```
 
-Or equivalently: `npx bmad-module-skill-forge install`
-
 Installs SKF on its own. You'll be prompted for project name, output folders, and which IDEs to configure. The installer generates IDE-specific command files (e.g. `.claude/commands/`, `.cursor/commands/`) so workflows appear in your IDE's command palette.
 
 ### Method 2: As a custom module during BMad Method installation
@@ -103,7 +122,7 @@ This installs BMad core + SKF together with full IDE integration, manifests, and
 If you already have BMad installed, you can add SKF afterward by running the standalone installer in the same directory:
 
 ```bash
-npx skill-forge install
+npx bmad-module-skill-forge install
 ```
 
 The installer detects the existing `_bmad/` directory and installs SKF alongside your current modules. IDE command files are generated for SKF workflows.
@@ -135,12 +154,27 @@ The installer detects the existing `_bmad/` directory and installs SKF alongside
 
 | Tier | Tools | Capability |
 | --- | --- | --- |
-| **Quick** | gh + skills_ref | Source reading + spec validation |
+| **Quick** | gh + skill-check + tessl | Source reading + spec validation + content quality review |
 | **Forge** | + ast-grep | Structural truth, T1 confidence |
 | **Deep** | + QMD | Knowledge search, temporal provenance |
 
 The `setup-forge` workflow detects available tools and writes the tier to `forge-tier.yaml`. All subsequent workflows adapt their behavior to the detected tier.
 
+> **Recommended:** If your IDE supports MCP servers, install the [ast-grep MCP server](https://github.com/ast-grep/ast-grep-mcp) alongside the CLI. SKF's extraction protocol prefers the MCP tool for compact, memory-efficient AST queries and falls back to CLI streaming for large codebases.
+
+### Security Scanning (Optional)
+
+`skill-check` includes security scanning via [Snyk Agent Scan](https://github.com/snyk/agent-scan) to check for prompt injection risks, sensitive data exposure, and unsafe tool permissions. To enable:
+
+1. You need a Snyk account with API access — the Snyk API requires an **Enterprise plan** (see [Snyk API authentication docs](https://docs.snyk.io/snyk-api/authentication-for-api))
+2. Copy your API token from Account Settings
+3. Add to your environment: `export SNYK_TOKEN=your-token`
+4. Re-run `@Ferris SF` to detect the token
+
+> **Note:** The Snyk API is not available on free or Team plans. If you don't have an Enterprise account, security scanning will be skipped gracefully — it does not affect your tier level or block skill compilation.
+
+Security scanning runs automatically during validation. Use `--no-security-scan` to skip.
+
 ## Knowledge Base
 
 SKF relies on a curated skill compilation knowledge base:
@@ -154,10 +188,11 @@ Workflows load only the fragments required for the current task to stay focused
 
 SKF variables are defined in `src/module.yaml` and prompted during install:
 
-| Variable | Purpose | Default |
-| --- | --- | --- |
-| `skills_output_folder` | Where generated skills are saved | `{project-root}/skills` |
-| `forge_data_folder` | Where workspace artifacts are stored | `{project-root}/forge-data` |
+| Variable               | Purpose                                                                                              | Default                     |
+|------------------------|------------------------------------------------------------------------------------------------------|-----------------------------|
+| `skills_output_folder` | Where generated skills are saved                                                                     | `{project-root}/skills`     |
+| `forge_data_folder`    | Where workspace artifacts are stored                                                                 | `{project-root}/forge-data` |
+| `tier_override`        | Force a specific tier for comparison or testing (in `_bmad/_memory/forger-sidecar/preferences.yaml`) | `~` (auto-detect)           |
 
 Runtime configuration (tool detection, tier, parallel settings) is managed by the `setup-forge` workflow in `forge-tier.yaml`.
 
@@ -167,12 +202,6 @@ Runtime configuration (tool detection, tier, parallel settings) is managed by th
 src/
 ├── module.yaml
 ├── module-help.csv
-├── README.md
-├── docs/
-│   ├── getting-started.md
-│   ├── agents.md
-│   ├── workflows.md
-│   └── examples.md
 ├── agents/
 │   └── forger.agent.yaml
 ├── forger/
@@ -181,21 +210,36 @@ src/
 │   └── README.md
 ├── knowledge/
 │   ├── skf-knowledge-index.csv
-│   └── *.md (8 fragments)
+│   └── *.md (10 fragments)
 └── workflows/
-    └── skillforge/
-        ├── setup-forge/
-        ├── analyze-source/
-        ├── brief-skill/
-        ├── create-skill/
-        ├── quick-skill/
-        ├── create-stack-skill/
-        ├── update-skill/
-        ├── audit-skill/
-        ├── test-skill/
-        └── export-skill/
+    ├── setup-forge/
+    ├── analyze-source/
+    ├── brief-skill/
+    ├── create-skill/
+    ├── quick-skill/
+    ├── create-stack-skill/
+    ├── update-skill/
+    ├── audit-skill/
+    ├── test-skill/
+    └── export-skill/
 ```
 
+## Acknowledgements
+
+SKF builds on these excellent open-source tools:
+
+| Tool                                                         | Role in SKF                                                        |
+|--------------------------------------------------------------|--------------------------------------------------------------------|
+| [agentskills.io](https://github.com/agentskills/agentskills) | Skill specification and ecosystem standard                         |
+| [GitHub CLI](https://cli.github.com/)                        | Source code access and repository intelligence (all tiers)         |
+| [ast-grep](https://github.com/ast-grep/ast-grep)             | AST-based structural code extraction (Forge/Deep tiers)            |
+| [ast-grep MCP](https://github.com/ast-grep/ast-grep-mcp)     | MCP server for memory-efficient AST queries (recommended)          |
+| [QMD](https://github.com/tobi/qmd)                           | Local hybrid search engine for knowledge indexing (Deep tier)      |
+| [skill-check](https://github.com/thedaviddias/skill-check)   | Skill validation, auto-fix, quality scoring, and security scanning |
+| [Snyk Agent Scan](https://github.com/snyk/agent-scan)   | Security scanning for prompt injection and data exposure (optional) |
+| [tessl](https://tessl.io)                                     | Content quality review, actionability scoring, and AI judge evaluation |
+| [BMad Method](https://github.com/bmad-code-org/BMAD-METHOD)  | Agent-workflow framework that SKF extends as a module              |
+
 ## Contributing
 
 See [CONTRIBUTORS.md](CONTRIBUTORS.md) for guidelines.

package/docs/agents.md

@@ -31,7 +31,7 @@ Ferris handles all SKF workflows. You always interact with Ferris — he switche
 
 | Mode | Behavior | Workflows |
 |------|----------|-----------|
-| **Architect** | Exploratory, structural, assembling | BS, CS, QS, SS, AN |
+| **Architect** | Exploratory, structural, assembling | SF, AN, BS, CS, QS, SS |
 | **Surgeon** | Precise, semantic diffing, preserves [MANUAL] | US |
 | **Audit** | Judgmental, drift reports, completeness scoring | AS, TS |
 | **Delivery** | Packaging, platform-aware, ecosystem-ready | EX |

package/docs/architecture.md

@@ -32,7 +32,7 @@ SKF uses an additive tier model. Each tier is the previous tier plus one tool. Y
 
 | Tier | Tools | What You Get |
 |------|-------|-------------|
-| **Quick** | `gh_bridge` + `skills_ref` | Source reading + spec validation. Best-effort skills in under a minute. |
+| **Quick** | `gh_bridge` + `skill-check` + `tessl` | Source reading + spec validation + content quality review. Best-effort skills in under a minute. |
 | **Forge** | + `ast_bridge` | Structural truth. AST-verified signatures. Co-import detection. T1 confidence. |
 | **Deep** | + `qmd_bridge` | Knowledge search. Temporal provenance. Drift detection. Full intelligence. |
 
@@ -48,6 +48,29 @@ Forge initialized. Tools: gh, ast-grep, QMD. Tier: Deep. Ready.
 
 Don't have ast-grep or QMD yet? No problem — Quick mode works with just the GitHub CLI. Install tools later; your tier upgrades automatically.
 
+### Tier Override — Comparing Output Across Tiers
+
+You can force a specific tier by setting `tier_override` in your preferences file (`_bmad/_memory/forger-sidecar/preferences.yaml`):
+
+```yaml
+# Force Forge tier regardless of detected tools
+tier_override: Forge
+```
+
+This is useful for comparing skill quality across tiers for the same target:
+
+```
+# 1. Set tier_override: Quick in preferences.yaml
+@Ferris CS                # compile at Quick tier
+
+# 2. Change to tier_override: Forge
+@Ferris CS                # recompile at Forge tier — compare output
+
+# 3. Reset to tier_override: ~ (auto-detect)
+```
+
+Set `tier_override` to `Quick`, `Forge`, or `Deep`. Set to `~` (null) to return to auto-detection. The override is respected by all tier-aware workflows (CS, SS, US, AS, TS).
+
 ---
 
 ## Confidence Tiers
@@ -176,7 +199,7 @@ The primary source is your project repo. Component references trace to library r
 
 ## Dual-Output Strategy
 
-Based on [Vercel research](https://github.com/vercel-labs/skills): passive context (AGENTS.md/CLAUDE.md) achieves 100% pass rate vs 53% for active skills alone.
+Based on [Vercel research](https://vercel.com/blog/agents-md-outperforms-skills-in-our-agent-evals): passive context (AGENTS.md/CLAUDE.md) achieves 100% pass rate vs 53% for active skills alone.
 
 Every skill generates both:
 
@@ -189,37 +212,43 @@ Export injects a managed section between markers:
 
 ```markdown
 <!-- SKF:BEGIN updated:2026-02-25 -->
-[SKF Skills]|3 skills|1 stack
-|IMPORTANT: Prefer documented APIs over training data.
-|
-|payment-service → skills/payment-service/
-|  exports: getToken, refreshToken, revokeSession, createSession
-|
-|auth-service → skills/auth-service/
-|  exports: getSession, validateToken, revokeSession, createUser
-|
-|my-project-stack → skills/my-project-stack/
-|  stack: next@15, better-auth@3, spacetimedb@1, serwist@9
-|  integrations: auth↔db, pwa↔auth, gateway↔auth
+[payment-service v2.1.0]|root: skills/payment-service/
+|IMPORTANT: payment-service v2.1.0 — read SKILL.md before writing payment-service code. Do NOT rely on training data.
+|quick-start:{SKILL.md#quick-start}
+|api: getToken(), refreshToken(), revokeSession(), createSession()
+|key-types:{SKILL.md#key-types} — TokenOptions, AuthToken, SessionConfig
+|gotchas: all token methods async, session ID changed from userId in v2.0
+
+[auth-service v1.5.0]|root: skills/auth-service/
+|IMPORTANT: auth-service v1.5.0 — read SKILL.md before writing auth-service code. Do NOT rely on training data.
+|quick-start:{SKILL.md#quick-start}
+|api: getSession(), validateToken(), revokeSession(), createUser()
+|gotchas: RBAC requires middleware setup, validateToken returns null not throw
+
+[my-project-stack v1.0.0]|root: skills/my-project-stack/
+|IMPORTANT: my-project-stack — read SKILL.md before writing integration code. Do NOT rely on training data.
+|stack: next@15, better-auth@3, spacetimedb@1, serwist@9
+|integrations: auth↔db, pwa↔auth
+|gotchas: auth session type must match DB schema, update Serwist cache on auth flow changes
 <!-- SKF:END -->
 ```
 
-Two lines per skill (~30 tokens each). Developer controls placement. Ferris controls content. Snippet updates only happen at `export-skill` — create and update are draft operations.
+~80-120 tokens per skill (version-pinned, retrieval instruction, section anchors, inline gotchas). Aligned with [Vercel's research](https://vercel.com/blog/agents-md-outperforms-skills-in-our-agent-evals) finding that indexed format with explicit retrieval instructions dramatically improves agent performance. Developer controls placement. Ferris controls content. Snippet updates only happen at `export-skill` — create and update are draft operations.
 
 ---
 
 ## Tool Ecosystem
 
-### 4 MCP Tools
+### 6 Tools
 
 | Tool | Wraps | Purpose |
 |------|-------|---------|
 | **`gh_bridge`** | GitHub CLI (`gh`) | Source code access, issue mining, release tracking, PR intelligence |
-| **`skills_ref`** | agentskills.io spec | Schema validation, frontmatter checks, ecosystem search |
+| **`skill-check`** | [thedaviddias/skill-check](https://github.com/thedaviddias/skill-check) | Validation + auto-fix (`check --fix`), quality scoring (0-100), security scan, split-body, diff comparison |
+| **`tessl`** | [tessl](https://tessl.io) | Content quality review, actionability scoring, progressive disclosure evaluation, AI judge with suggestions |
 | **`ast_bridge`** | ast-grep CLI | Structural extraction, custom AST queries, co-import detection |
 | **`qmd_bridge`** | QMD (local search) | BM25 keyword search, vector semantic search, collection indexing |
-
-Optional addon: **`doc_fetcher`** for remote documentation (Firecrawl/Jina.ai). Output quarantined as T3.
+| **`doc_fetcher`** | Environment web tools | Remote documentation fetching for T3-confidence content. Tool-agnostic — uses whatever web fetching is available (Firecrawl, WebFetch, curl, etc.). Output quarantined as T3. |
 
 ### Conflict Resolution
 
@@ -288,7 +317,7 @@ Provenance maps enable verification: an `official` skill's provenance must trace
 - Input sanitization: allowlist characters for repo names, file paths, patterns
 - File paths validated against project root (no directory traversal)
 - **Source code never leaves the machine.** All processing is local (AST, QMD, validation).
-- `doc_fetcher` warns before transmitting URLs to external services
+- `doc_fetcher` informs users which URLs will be fetched externally before processing
 
 ---
 

package/docs/examples.md

@@ -93,7 +93,17 @@ Checks ecosystem first. If no official skill exists: generates from source. `sou
 
 No source code available — only documentation.
 
-Generate from docs + QMD-indexed content. T2/T3 confidence only. `source_authority: community`.
+```
+@Ferris BS
+# When asked for target, provide documentation URLs:
+# https://docs.cognee.ai/
+# Ferris sets source_type: "docs-only" and collects doc_urls
+@Ferris CS
+# step-03 skips (no source), step-03c fetches docs via doc_fetcher
+# All content is T3 [EXT:url] confidence. source_authority: community
+```
+
+The brief's `doc_urls` field drives the doc_fetcher step. The agent uses whatever web fetching tool is available in its environment (Firecrawl, WebFetch, curl, etc.) to retrieve documentation as markdown and extract API information with T3 citations.
 
 ---
 
@@ -139,6 +149,7 @@ Quick mode reads source without AST analysis. Install ast-grep to upgrade to For
 
 - Run `/bmad-help` — analyzes your current state and suggests what to do next
   (e.g. `/bmad-help my batch creation failed halfway, how do I resume?`)
+  *Provided by the [BMad Method](https://github.com/bmad-code-org/BMAD-METHOD) — not available in standalone SKF installations.*
 - Run `@Ferris SF` to check your current tier and tool availability
-- Review `forge-config.yaml` for runtime configuration
+- Review `forge-tier.yaml` in your forger sidecar for runtime configuration
 - Check module configuration in your BMAD settings

package/docs/getting-started.md

@@ -22,11 +22,9 @@ There are three ways to install SKF, depending on your setup.
 ### Standalone (recommended for trying SKF)
 
 ```bash
-npx skill-forge install
+npx bmad-module-skill-forge install
 ```
 
-Or equivalently: `npx bmad-module-skill-forge install`
-
 Installs SKF on its own. You'll be prompted for project name, output folders, and which IDEs to configure. The installer generates IDE-specific command files (e.g. `.claude/commands/`, `.cursor/commands/`) so workflows appear in your IDE's command palette.
 
 ### As a custom module during BMad Method installation
@@ -48,7 +46,7 @@ This installs BMad core + SKF together with full IDE integration, manifests, and
 If you already have BMad installed, you can add SKF afterward by running the standalone installer in the same directory:
 
 ```bash
-npx skill-forge install
+npx bmad-module-skill-forge install
 ```
 
 The installer detects the existing `_bmad/` directory and installs SKF alongside your current modules.
@@ -57,13 +55,16 @@ The installer detects the existing `_bmad/` directory and installs SKF alongside
 
 ## Prerequisites
 
-| Tool                                                                   | Required For       | Install                     |
-|------------------------------------------------------------------------|--------------------|-----------------------------|
-| `gh` (GitHub CLI)                                                      | All modes          | <https://cli.github.com>      |
-| `ast-grep`  (CLI tool for code structural search, lint, and rewriting) | Forge + Deep modes | <https://ast-grep.github.io>  |
-| `qmd` (local hybrid search engine for markdown)                        | Deep mode          | <https://github.com/tobi/qmd> |
+| Tool                                                                   | Required For               | Install                                                |
+|------------------------------------------------------------------------|----------------------------|--------------------------------------------------------|
+| [Node.js](https://nodejs.org/) >= 22                                   | Installation, npx commands | <https://nodejs.org>                                   |
+| `gh` (GitHub CLI)                                                      | All modes                  | <https://cli.github.com>                               |
+| `ast-grep`  (CLI tool for code structural search, lint, and rewriting) | Forge + Deep modes         | <https://ast-grep.github.io>                           |
+| `ast-grep` MCP server (recommended alongside CLI)                      | Forge + Deep modes         | <https://github.com/ast-grep/ast-grep-mcp>             |
+| `qmd` (local hybrid search engine for project files)                   | Deep mode                  | <https://github.com/tobi/qmd>                          |
+| `SNYK_TOKEN` (Snyk API token — **Enterprise plan required**)           | Optional security scan     | <https://docs.snyk.io/snyk-api/authentication-for-api> |
 
-Don't worry if you don't have all tools — SKF detects what's available and sets your tier automatically.
+Don't worry if you don't have all tools — SKF detects what's available and sets your tier automatically. Security scanning via Snyk is optional and requires an Enterprise plan; it does not affect your tier level.
 
 ---
 
@@ -148,13 +149,13 @@ Analyze Source scans the project, identifies skillable units, maps exports, and
 
 ### I want the highest accuracy possible
 
-Quick mode reads source files. Forge mode adds AST parsing for structural truth. Deep mode goes further — QMD indexes your project's markdown (docs, changelogs, issues, migration guides) into searchable collections, then uses BM25 keyword search, vector semantic search, and LLM-powered re-ranking to surface context no other tool can find.
+Quick mode reads source files. Forge mode adds AST parsing for structural truth. Deep mode goes further — as skills are compiled, SKF indexes curated extraction artifacts and skill briefs into QMD collections, then uses BM25 keyword search, vector semantic search, and LLM-powered re-ranking to surface context no other tool can find.
 
 ```
 @Ferris SF    # Setup detects your tools and sets tier automatically
 ```
 
-If `ast-grep` and `qmd` are available, Ferris activates Deep mode. Every skill gets AST-verified signatures (T1) enriched with deep knowledge search (T2) — deprecation warnings, breaking change history, common pitfalls surfaced by hybrid search across your indexed documentation.
+If `ast-grep` and `qmd` are available, Ferris activates Deep mode. Every skill gets AST-verified signatures (T1) enriched with deep knowledge search (T2) — deprecation warnings, breaking change history, common pitfalls surfaced by searching across your indexed skill artifacts.
 
 ### I maintain an OSS library and want official skills
 
@@ -194,5 +195,6 @@ Your existing skill is now out of date. Audit detects the drift, Update regenera
 If you run into issues:
 1. Run `/bmad-help` — analyzes your current state and suggests what to do next
    (e.g. `/bmad-help my quick skill has low confidence scores, how do I improve them?`)
+   *Provided by the [BMad Method](https://github.com/bmad-code-org/BMAD-METHOD) — not available in standalone SKF installations.*
 2. Run `@Ferris SF` to check your tool availability and tier
-3. Check `forge-config.yaml` for your current configuration
+3. Check `forge-tier.yaml` in your forger sidecar for your current configuration

package/docs/index.md

@@ -26,10 +26,12 @@ Skill Forge is an automated skill compiler for the AI agent ecosystem. It transf
 
 ## Quick Install
 
+Requires [Node.js](https://nodejs.org/) >= 22.
+
 **Standalone:**
 
 ```bash
-npx skill-forge install
+npx bmad-module-skill-forge install
 ```
 
 **Or as a custom module with BMad Method** (for the full development workflow):

package/docs/workflows.md

@@ -15,11 +15,11 @@ SKF includes 10 workflows organized by purpose:
 
 **Command:** `@Ferris SF`
 
-**Purpose:** Initialize forge environment, detect tools, set capability tier, auto-index project.
+**Purpose:** Initialize forge environment, detect tools, set capability tier, verify QMD collection health.
 
 **When to Use:** First time using SKF in a project. Run once per project.
 
-**Key Steps:** Detect tools → Determine tier → Create forge-config.yaml → Auto-index (Deep)
+**Key Steps:** Detect tools → Determine tier → Write forge-tier.yaml → QMD hygiene (Deep)
 
 **Agent:** Ferris (Architect mode)
 

package/package.json

@@ -1,14 +1,17 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "bmad-module-skill-forge",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "BMAD module — AST-verified, provenance-backed agent skills compiler with progressive capability tiers (Quick/Forge/Deep)",
   "keywords": [
     "bmad",
+    "bmad-method",
+    "bmad-module",
     "agent-skills",
     "agentskills",
     "skill-forge",
     "ast-grep",
+    "qmd",
     "provenance",
     "code-analysis"
   ],
@@ -20,8 +23,7 @@
   "author": "armelhbobdad",
   "main": "tools/cli/skf-cli.js",
   "bin": {
-    "bmad-module-skill-forge": "tools/skf-npx-wrapper.js",
-    "skill-forge": "tools/skf-npx-wrapper.js"
+    "bmad-module-skill-forge": "tools/skf-npx-wrapper.js"
   },
   "scripts": {
     "docs:build": "node tools/build-docs.js",

package/src/forger/forge-tier.yaml

@@ -8,6 +8,6 @@ tools:
   qmd: ~
 
 # Capability tier (derived from tool availability)
-# Quick = no tools | Forge = ast-grep | Deep = ast-grep + gh + qmd
+# Quick = no tools required | Forge = + ast-grep | Deep = + ast-grep + gh + QMD
 tier: ~
 tier_detected_at: ~

package/src/forger/preferences.yaml

@@ -1,5 +1,12 @@
 # Ferris Sidecar: User Preferences
-# Written by setup-forge workflow on first run
+# Created by setup-forge workflow on first run
+# Edit this file to customize Ferris behavior
+
+# Override detected tier (set to Quick, Forge, or Deep to force a tier)
+tier_override: ~
+
+# Passive context injection (set to false to skip snippet generation and CLAUDE.md updates during export)
+passive_context: true
 
 # Language defaults
 output_language: ~

package/src/knowledge/doc-fetcher.md

@@ -0,0 +1,55 @@
+# Doc Fetcher
+
+## Purpose
+
+T3 external documentation fetching retrieves content from URLs specified in the extraction brief. It serves as the primary extraction source in Scenario D (docs-only, SaaS, closed-source) where no source code is available, and as a supplemental source when a brief includes `doc_urls` alongside a source repository.
+
+## Tool-Agnostic Principle
+
+`doc_fetcher` is not a wrapper around any specific CLI tool. The LLM agent uses whatever web fetching capability is available in its environment — Firecrawl MCP, WebFetch, curl, browser automation tools, or any other URL retrieval mechanism. The extraction workflow never assumes a particular fetching tool exists; it discovers available capabilities at runtime and uses the best option present.
+
+## T3 Quarantine Rules
+
+All content obtained through doc fetching is classified as **external, untrusted** and subject to quarantine constraints:
+
+1. **Citation format** — every doc-fetched claim uses `[EXT:{url}]` citation format
+2. **Conflict resolution priority** — T3 has the lowest priority: `T1 > T2 > source reading > T3`
+3. **Source authority cap** — T3 content forces `source_authority: community` in metadata; it never qualifies as `official`
+4. **No structural claims** — T3 cannot assert verified signatures or line-level precision
+
+## When to Use
+
+| Scenario | Role | Example |
+| --- | --- | --- |
+| Scenario D — docs-only / SaaS / closed-source | **Primary source** | Stripe API, Twilio SDK docs |
+| Brief includes `doc_urls` alongside source repo | **Supplemental enrichment** | README links, hosted API reference |
+
+When used as supplemental enrichment, T3 content adds context but never overrides T1 or T1-low claims extracted from the actual source code.
+
+## Security Considerations
+
+- URLs specified in the brief are transmitted to external services for content extraction — the agent must inform the user which URLs will be fetched before initiating retrieval
+- Fetched content should not be trusted as authoritative; it may be outdated, modified, or incorrect
+- The agent should not follow redirects to unexpected domains without user confirmation
+
+## Interaction with Other Tiers
+
+- **T3 never replaces T1 (AST) or T2 (QMD)** content for the same export — quarantine rules enforce this
+- **Deep tier**: T3 content can be enriched by QMD (T2 annotations layered onto a T3 base), producing richer output while preserving the T3 confidence label on the base claim
+- **Forge tier**: T3 content exists alongside T1 AST content; T1 takes precedence for any overlapping claims
+- **Quick tier**: T3 may be the only external enrichment available, but T1-low source-read claims still outrank it
+
+## Anti-Patterns
+
+- Citing doc-fetched content with `[AST:...]` or `[SRC:...]` format — always use `[EXT:{url}]`
+- Promoting T3 claims to `source_authority: official` regardless of the documentation source
+- Fetching URLs without informing the user which external services will be contacted
+- Using T3 content to override a contradicting T1 or T1-low extraction
+
+## Related Fragments
+
+- [confidence-tiers.md](confidence-tiers.md) — tier definitions, citation formats, and precedence rules
+- [progressive-capability.md](progressive-capability.md) — how capability tiers determine available extraction methods
+- [zero-hallucination.md](zero-hallucination.md) — the foundational principle that T3 quarantine enforces
+
+_Source: consolidated from extraction brief schema, create-skill Scenario D handling, and confidence tier conflict resolution rules_

package/src/knowledge/overview.md

@@ -20,15 +20,16 @@ With knowledge files:
 
 ## Knowledge Map
 
-| File | Purpose | Key Workflows |
-| --- | --- | --- |
-| [zero-hallucination.md](zero-hallucination.md) | Every claim traces to source; uncitable content excluded | AN, BS, CS, QS, SS, US, AS, TS |
-| [confidence-tiers.md](confidence-tiers.md) | T1/T1-low/T2/T3 trust model and citation formats | AN, BS, CS, QS, SS, US, AS, TS, EX |
-| [progressive-capability.md](progressive-capability.md) | Quick/Forge/Deep tier philosophy and behavior adaptation | All 10 |
-| [agentskills-spec.md](agentskills-spec.md) | agentskills.io output format principles and compliance | CS, QS, SS, US, TS, EX |
-| [skill-lifecycle.md](skill-lifecycle.md) | End-to-end pipeline, artifact flow, workflow selection | All 10 |
-| [provenance-tracking.md](provenance-tracking.md) | Provenance-map.json, evidence reports, claim traceability | CS, QS, SS, US, AS, TS |
-| [manual-section-integrity.md](manual-section-integrity.md) | \[MANUAL\] marker preservation and merge algorithm | CS, US, AS, TS, EX |
+| File                                                       | Purpose                                                           | Key Workflows                      |
+|------------------------------------------------------------|-------------------------------------------------------------------|------------------------------------|
+| [zero-hallucination.md](zero-hallucination.md)             | Every claim traces to source; uncitable content excluded          | AN, BS, CS, QS, SS, US, AS, TS     |
+| [confidence-tiers.md](confidence-tiers.md)                 | T1/T1-low/T2/T3 trust model and citation formats                  | AN, BS, CS, QS, SS, US, AS, TS, EX |
+| [progressive-capability.md](progressive-capability.md)     | Quick/Forge/Deep tier philosophy and behavior adaptation          | All 10                             |
+| [agentskills-spec.md](agentskills-spec.md)                 | agentskills.io output format principles and compliance            | CS, QS, SS, US, TS, EX             |
+| [skill-lifecycle.md](skill-lifecycle.md)                   | End-to-end pipeline, artifact flow, workflow selection            | All 10                             |
+| [provenance-tracking.md](provenance-tracking.md)           | Provenance-map.json, evidence reports, claim traceability         | CS, QS, SS, US, AS, TS             |
+| [manual-section-integrity.md](manual-section-integrity.md) | \[MANUAL\] marker preservation and merge algorithm                | CS, US, AS, TS, EX                 |
+| [qmd-registry.md](qmd-registry.md)                         | Progressive QMD collection registry and collection gate principle | SF, BS, CS, US, AS                 |
 
 ## JiT Loading Protocol
 
@@ -39,13 +40,13 @@ With knowledge files:
 
 ## Knowledge vs. Data
 
-| Aspect | Knowledge Files (`knowledge/`) | Data Files (`data/`) |
-| --- | --- | --- |
-| Scope | Cross-cutting, multi-workflow | Single workflow, single step |
-| Content | Principles, patterns, judgment rules | Schemas, templates, scoring formulas |
-| Loading | JiT via index lookup | JiT via step instruction |
-| Examples | Zero hallucination, confidence tiers | skill-brief-schema.md, scoring-rules.md |
-| Stability | Rarely changes | Changes with workflow evolution |
+| Aspect    | Knowledge Files (`knowledge/`)       | Data Files (`data/`)                    |
+|-----------|--------------------------------------|-----------------------------------------|
+| Scope     | Cross-cutting, multi-workflow        | Single workflow, single step            |
+| Content   | Principles, patterns, judgment rules | Schemas, templates, scoring formulas    |
+| Loading   | JiT via index lookup                 | JiT via step instruction                |
+| Examples  | Zero hallucination, confidence tiers | skill-brief-schema.md, scoring-rules.md |
+| Stability | Rarely changes                       | Changes with workflow evolution         |
 
 ## Related Fragments