bmad-module-skill-forge 0.9.0 → 0.10.1-alpha.0

package/docs/verifying-a-skill.md

@@ -0,0 +1,232 @@
+---
+title: Verifying a Skill
+description: How to audit any SKF-compiled skill — walk every instruction back to an upstream commit and line number in under 60 seconds.
+---
+
+**Nothing is made up.** Every instruction in every skill traces back to a specific file, a specific line, and a specific commit in the upstream source. If a skill claims a function exists, you can open the real source tree at the pinned commit and see it with your own eyes. If the claim and the source disagree — that's a bug, and SKF treats it as one.
+
+---
+
+## The three-step audit
+
+Pick any symbol in any SKF-compiled skill. You can trace it to the exact line of upstream source in under 60 seconds.
+
+### 1. Open the skill's `metadata.json`
+
+Every skill ships a `metadata.json` next to its `SKILL.md`. Note two fields:
+
+- `source_commit` — the exact commit SHA the skill was compiled from
+- `source_repo` — the upstream repository
+
+This is the anchor. Everything else traces back to this commit.
+
+### 2. Open the skill's `provenance-map.json`
+
+Provenance maps live in `forge-data/{skill}/{version}/provenance-map.json` alongside each compiled skill. Find your symbol. Every entry carries its own `source_file` and `source_line`:
+
+```json
+{
+  "export_name": "search",
+  "export_type": "function",
+  "params": ["query_text: str", "query_type: SearchType = GRAPH_COMPLETION", "top_k: int = 10"],
+  "return_type": "List[SearchResult]",
+  "source_file": "cognee/api/v1/search/search.py",
+  "source_line": 27,
+  "confidence": "T1",
+  "extraction_method": "ast-grep"
+}
+```
+
+The snippet above is a real entry from [`forge-data/oms-cognee/1.0.0/provenance-map.json`](https://github.com/armelhbobdad/oh-my-skills/blob/main/forge-data/oms-cognee/1.0.0/provenance-map.json). Line number is not rounded. Confidence tier is explicit. Extraction method is named. Nothing is paraphrased.
+
+### 3. Visit the upstream repo at the pinned commit
+
+Open `{source_repo}` at `{source_commit}`, jump to `{source_file}` line `{source_line}`. The signature in `SKILL.md` should match what you see in the source.
+
+If it doesn't, **that's a bug**. [Open an issue](https://github.com/armelhbobdad/bmad-module-skill-forge/issues/new/choose). SKF will republish the skill with a new commit SHA and a new provenance map. Falsifiability isn't a feature — it's the whole deal.
+
+### Workflow-time enforcement
+
+The same anchor is enforced automatically by `skf-test-skill` and by gap-driven `skf-update-skill`. Before either workflow reads source at a recorded `source_line`, it runs `git rev-parse HEAD` on the local workspace and compares it to `metadata.source_commit`. If the workspace has drifted, the workflow halts with a `halted-for-workspace-drift` status and tells you the exact `git checkout {source_ref}` to re-sync — so spot-checks can never silently verify against the wrong tree. Pass `--allow-workspace-drift` to opt in to reading the current HEAD anyway; the override is recorded in the final report rather than hidden.
+
+---
+
+## Where to look for what
+
+Every file in the per-skill output carries a specific job. Here's the lookup table for the really skeptical:
+
+| Question | File |
+|---|---|
+| What commit was the source pinned to? | `skills/{name}/{version}/{name}/metadata.json` → `source_commit` |
+| Which symbols are documented and where did each come from? | `forge-data/{name}/{version}/provenance-map.json` |
+| What AST patterns were used for extraction? | `forge-data/{name}/{version}/extraction-rules.yaml` |
+| What signatures, types, and examples did the extractor actually capture? | `forge-data/{name}/{version}/evidence-report.md` |
+| How was the skill scored? Show me the math. | `forge-data/{name}/{version}/test-report-{name}.md` |
+| How was the skill scoped, and what was deliberately left out? | `forge-data/{name}/skill-brief.yaml` |
+
+Everything a reader needs to reconstruct the compilation is in the two sibling directories: `skills/` ships to consumers, `forge-data/` is the audit trail.
+
+---
+
+## The scores, including the ones we lose
+
+Completeness scoring is never 100%. The [scoring formula](#how-the-score-is-computed) is deterministic and the pass threshold is **80%** — but every test report also logs the specific edges where a skill falls short, so the numbers aren't marketing.
+
+Take oh-my-skills' four reference skills as an example. Their scores range from **99.0% to 99.49%** — none are perfect, and every test report names the specific drift it found:
+
+| Skill | Score | What the report discloses |
+|---|---|---|
+| [oms-cocoindex](https://github.com/armelhbobdad/oh-my-skills/blob/main/forge-data/oms-cocoindex/0.3.37/test-report-oms-cocoindex.md) | **99.0%** | 114/114 provenance entries; 55 public-API denominator from `__init__.py` `__all__`; 20/20 sampled signatures matched. Two denominators (barrel vs. full surface) both disclosed with rationale. |
+| [oms-cognee](https://github.com/armelhbobdad/oh-my-skills/blob/main/forge-data/oms-cognee/1.0.0/test-report-oms-cognee.md) | **99.0%** | 34/34 exports documented; denominator is the `cognee/__init__.py` barrel (61 lines, 34 public re-exports) at pinned commit `3c048aa4` (v1.0.0). |
+| [oms-storybook-react-vite](https://github.com/armelhbobdad/oh-my-skills/blob/main/forge-data/oms-storybook-react-vite/10.3.5/test-report-oms-storybook-react-vite.md) | **99.49%** | 215/216 documented — the missing 1 entry is logged openly as **GAP-004**, a canonical surface count drift from the stated denominator. |
+| [oms-uitripled](https://github.com/armelhbobdad/oh-my-skills/blob/main/forge-data/oms-uitripled/0.1.0/test-report-oms-uitripled.md) | **99.45%** | 34-entry denominator (not 11, not 25) with the full reconciliation reasoning in the report. |
+
+Perfection is suspicious. Visible fallibility is trustworthy. SKF writes down the edges it can't score cleanly — so you can read them and decide for yourself whether the remaining coverage is enough for your use case.
+
+### GAP-004: a worked example of the 1% that fails
+
+The [`oms-storybook-react-vite` test report](https://github.com/armelhbobdad/oh-my-skills/blob/main/forge-data/oms-storybook-react-vite/10.3.5/test-report-oms-storybook-react-vite.md) scores **215/216** — not 216/216. The missing 1 entry is logged as **GAP-004**: a canonical export surface count (via the provenance map) diverges from the stated denominator in metadata.json. The report names the gap, shows the math, and leaves the drift visible for the next recompilation pass. Nothing was hidden.
+
+That's the pattern SKF asks you to trust: when scoring can't reach 100%, the report says so, cites the line, and leaves a fingerprint for the next audit.
+
+---
+
+## How the Score Is Computed
+
+The Test Skill workflow (`@Ferris TS`) calculates the completeness score — a weighted measure of how thoroughly and accurately a skill documents its target. This score is the quality gate: pass and the skill is ready for export; fail and it routes to update-skill for remediation.
+
+### Categories and weights
+
+The score is the weighted sum of five categories:
+
+| Category | Weight | What it measures |
+|---|---|---|
+| **Export Coverage** | 36% | Percentage of source exports documented in `SKILL.md` |
+| **Signature Accuracy** | 22% | Documented function signatures match actual source signatures (parameter names, types, order, return types) |
+| **Type Coverage** | 14% | Types and interfaces referenced in exports are fully documented |
+| **Coherence** | 18% | Cross-references resolve, integration patterns are complete (contextual mode only) |
+| **External Validation** | 10% | Average of skill-check quality score (0–100) and tessl content score (0–100%) |
+
+### Formula
+
+```
+total_score = sum(category_weight × category_score)
+```
+
+Each category score is a percentage: `(items_passing / items_total) × 100`.
+
+**Coherence** (contextual mode) combines two sub-scores:
+
+```
+coherence = (reference_validity × 0.6) + (integration_completeness × 0.4)
+```
+
+If no integration patterns exist, coherence equals reference validity alone.
+
+**External validation** averages the two tools when both are available. When only one tool is available, that tool's score is used. When neither is available, the 10% weight is redistributed proportionally to the other active categories.
+
+### Deterministic scoring
+
+The weight redistribution and score aggregation are computed by a deterministic Python script ([`compute-score.py`](https://github.com/armelhbobdad/bmad-module-skill-forge/blob/main/src/skf-test-skill/scripts/compute-score.py)). The LLM extracts category scores from the test report, constructs a JSON input, invokes the script, and uses its output for the final score. Same inputs always produce the same score. If the script is unavailable, the LLM falls back to manual calculation using the same formulas.
+
+### Naive vs contextual mode
+
+Test Skill runs in one of two modes, detected automatically:
+
+- **Contextual mode** (stack skills) — all five categories scored with the default weights above.
+- **Naive mode** (individual skills) — Coherence is not scored. Its 18% weight is redistributed:
+
+| Category | Naive Weight |
+|---|---|
+| Export Coverage | 45% |
+| Signature Accuracy | 25% |
+| Type Coverage | 20% |
+| External Validation | 10% |
+
+### Tier adjustments
+
+Your forge tier determines which categories can be scored:
+
+| Tier | Skipped Categories | Reason |
+|---|---|---|
+| **Quick** | Signature Accuracy, Type Coverage | No AST parsing available |
+| **Docs-only** | Signature Accuracy, Type Coverage | No source code to compare against |
+| **Provenance-map** (State 2) | Signature Accuracy, Type Coverage | String comparison only, no semantic AST verification |
+| **Forge / Forge+ / Deep** | None | Full AST-backed scoring |
+
+When categories are skipped, their combined weight is redistributed proportionally to the remaining active categories. A Quick-tier skill and a Deep-tier skill both pass at the same 80% threshold — the score reflects what your tier can actually measure.
+
+### Pass/fail
+
+```
+threshold = custom_threshold OR 80% (default)
+
+score >= threshold  →  PASS  →  Recommend export-skill
+score <  threshold  →  FAIL  →  Recommend update-skill
+```
+
+The default is 80%. You can override it by specifying a custom threshold when invoking the workflow (e.g., "test this skill with a 70% threshold").
+
+### Gap severities
+
+When the score is calculated, each finding is classified by severity to guide remediation:
+
+| Severity | Examples |
+|---|---|
+| **Critical** | Missing exported function/class documentation |
+| **High** | Signature mismatch between source and `SKILL.md` |
+| **Medium** | Missing type/interface documentation; scripts/assets directory inconsistencies |
+| **Low** | Missing optional metadata or examples; description optimization opportunities |
+| **Info** | Style suggestions; discovery testing recommendations |
+
+### Score report output
+
+The test report includes a score breakdown table showing each category's raw score, weight, and weighted contribution:
+
+| Category | Score | Weight | Weighted |
+|---|---|---|---|
+| Export Coverage | 92% | 36% | 33.1% |
+| Signature Accuracy | 85% | 22% | 18.7% |
+| Type Coverage | 100% | 14% | 14.0% |
+| Coherence | 80% | 18% | 14.4% |
+| External Validation | 78% | 10% | 7.8% |
+| **Total** | | **100%** | **88.0%** |
+
+The report also records `analysisConfidence` (full, provenance-map, metadata-only, remote-only, or docs-only) and includes a degradation notice when source access was limited.
+
+---
+
+## Build-time drift detection (for docs themselves)
+
+The SKF docs you're reading right now are themselves verified against oh-my-skills. A `docs/_data/pinned.yaml` anchor file records the exact version, commit SHA, and confidence tier of every reference skill. A Node validator (`tools/validate-docs-drift.js`) runs as part of `npm run quality` and:
+
+1. **Confirms canonical truth** — every anchor in `pinned.yaml` is cross-checked against the actual `metadata.json` in oh-my-skills. Version, commit, tier, and authority must match.
+2. **Scans docs for stale prose** — every `.md` file is grepped for `<library> v?<x.y.z>` patterns and any version that disagrees with `pinned.yaml` is flagged with file + line number.
+
+If the validator flags drift, the CI fails before the docs get merged. It's the same "nothing is made up" contract SKF applies to skills, applied to the docs that describe SKF. When the anchor file is updated to reflect a new oh-my-skills release, the prose must update too — otherwise `npm run docs:validate-drift` blocks the merge.
+
+You can run it yourself from the SKF repo root:
+
+```bash
+npm run docs:validate-drift
+```
+
+Or point it at a different local copy of oh-my-skills:
+
+```bash
+OMS=/path/to/your/oh-my-skills npm run docs:validate-drift
+```
+
+Clean output looks like this:
+
+```
+OK: 4 skills checked against /home/you/oh-my-skills, no drift.
+```
+
+Dirty output cites exact file:line locations so the fix is mechanical.
+
+---
+
+## Reference output: oh-my-skills
+
+Every example in this page points at [**oh-my-skills**](https://github.com/armelhbobdad/oh-my-skills), the SKF reference portfolio. Four Deep-tier skills (cocoindex, cognee, Storybook v10, uitripled), each shipping its full audit trail alongside the compiled skill. Both the worked example for this page and the continuing proof that the pipeline does what it says. If you want to see what SKF produces when you run it on real libraries, that's the answer.

package/docs/why-skf.md

@@ -0,0 +1,93 @@
+---
+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.
+
+---
+
+## The problem you're hiring SKF to solve
+
+Your AI agents read your codebase through the lens of whatever happened to be in their training data. When that training data is wrong, stale, or incomplete, your agent invents — function names that don't exist, parameter types that don't match, config options removed two versions ago. You catch some of it in review. You ship some of it by accident. Every sprint, your team spends hours untangling code that only compiles in the AI's imagination.
+
+SKF treats this as a citation problem, not a model problem. If a skill claims `cognee.search()` takes `query_text` as its first parameter, SKF points to `cognee/api/v1/search/search.py:L26` at commit `3c048aa4` in the upstream repo. That's the whole pitch: **nothing is made up, and everything is falsifiable in 60 seconds.**
+
+---
+
+## How SKF compares
+
+<div class="comparison-table">
+
+| Approach | What it does well | Where it falls short |
+|----------|-------------------|----------------------|
+| Skill scaffolding (`npx skills init`) | Generates a spec-compliant skill file | The file is empty — you still have to write every instruction by hand |
+| LLM summarization | Understands context and intent | Generates plausible-sounding content that may not match the actual API |
+| 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).** |
+
+</div>
+
+---
+
+## What "falsifiable in 60 seconds" actually means
+
+Pick any symbol in any SKF-compiled skill. Three clicks:
+
+1. Open the skill's `metadata.json` — it names the upstream repo and the exact commit SHA.
+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.
+
+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.
+
+---
+
+## Who's this for?
+
+### The curious developer
+
+Your agent just hallucinated a method that doesn't exist, again. You want this to stop, and you don't want to read a 569-line architecture page before running your first command.
+→ Start with [Getting Started](../getting-started/).
+
+### The BMAD user
+
+You already use BMAD Method, BMM phases, TEA, or BMB, and you want to know where SKF fits.
+→ Read [BMAD Synergy](../bmad-synergy/) for the phase-by-phase integration playbook.
+
+### The skeptic
+
+"AI docs for AI" sounds like the problem pretending to be the solution. You want receipts before you install anything.
+→ Start with [Verifying a Skill](../verifying-a-skill/) — the three-step audit on real skills, including the 1% that fails.
+
+### The OSS maintainer
+
+You want to ship verified skills alongside your library releases — `npx skills publish`-ready, drift-detectable, version-pinned.
+→ See [Examples → OSS Maintainer Publishing Official Skills](../examples/#scenario-h-oss-maintainer-publishing-official-skills).
+
+### The team lead evaluating adoption
+
+You're considering running SKF across a brownfield platform. You need to know about rollback safety, `[MANUAL]` section preservation, and the health-check feedback loop before committing.
+→ Start with [Architecture](../architecture/), then [Workflows → Workflow Health Check](../workflows/#terminal-step-health-check).
+
+---
+
+## 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.
+
+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.
+
+---
+
+## Next
+
+- **[Install SKF](../getting-started/#install)** — Node ≥ 22, Python ≥ 3.10, `uv`, one `npx` command
+- **[Audit a skill in 60 seconds](../verifying-a-skill/)** — see the receipts before you install
+- **[Browse real skills](https://github.com/armelhbobdad/oh-my-skills)** — four Deep-tier skills, all shipping their audit trails

package/docs/workflows.md

@@ -3,9 +3,7 @@ title: Workflows
 description: All 14 SKF workflows with commands, steps, and connection diagram
 ---
 
-# Workflows Reference
-
-SKF has 14 workflows. You trigger them by typing commands to [Ferris](../agents/), the AI agent that runs everything. Each workflow handles a specific part of the skill lifecycle — from analyzing source code to packaging for distribution, plus management operations for renaming and dropping skills. If any terms are unfamiliar, see the [Concepts](../concepts/) page for definitions.
+Trigger workflows by typing commands to [Ferris](../agents/). See [Concepts](../concepts/) for definitions.
 
 > Already using BMAD? See [BMAD Synergy](../bmad-synergy/) for when to invoke each SKF workflow during BMM phases and alongside TEA, BMB, and GDS.
 
@@ -59,7 +57,7 @@ SKF has 14 workflows. You trigger them by typing commands to [Ferris](../agents/
 
 **Command:** `@Ferris US`
 
-**Purpose:** Smart regeneration preserving `[MANUAL]` sections. Detects individual vs stack internally.
+**Purpose:** Regenerates the skill while preserving `[MANUAL]` sections. Detects individual vs stack internally.
 
 **When to Use:** After source code changes when an existing skill needs updating.
 
@@ -77,7 +75,7 @@ SKF has 14 workflows. You trigger them by typing commands to [Ferris](../agents/
 
 **Purpose:** Brief-less fast skill with package-to-repo resolution.
 
-**When to Use:** When you need a skill quickly — no brief needed. Accepts package names or GitHub URLs. Append `@version` to target a specific version (e.g., `@Ferris QS cognee@0.5.0`).
+**When to Use:** When you need a skill quickly — no brief needed. Accepts package names or GitHub URLs. Append `@version` to target a specific version (e.g., `@Ferris QS cognee@1.0.0`).
 
 **Key Steps:** Resolve target → Ecosystem check → Quick extract → Compile → Validate → Write
 
@@ -105,7 +103,7 @@ SKF has 14 workflows. You trigger them by typing commands to [Ferris](../agents/
 
 **Command:** `@Ferris AN`
 
-**Purpose:** Decomposition engine — discover what to skill, recommend stack skill.
+**Purpose:** Decomposes a repo to discover what's worth skilling, and recommends a stack skill.
 
 **When to Use:** Brownfield onboarding of large repos or multi-service projects.
 
@@ -123,10 +121,12 @@ SKF has 14 workflows. You trigger them by typing commands to [Ferris](../agents/
 
 **Purpose:** Drift detection between skill and current source.
 
-**When to Use:** To check if a skill has fallen out of date with its source code.
+**When to Use:** To check if a skill has fallen out of date with its source code. Works for both individual skills and stack skills.
 
 **Key Steps:** Load skill → Re-index source → Structural diff (incl. script/asset drift) → Semantic diff (Deep) → Classify severity → Report
 
+**Stack skill support:** Code-mode stacks are audited per-library against their sources. Compose-mode stacks check constituent freshness via metadata hash comparison — if a constituent skill was updated after the stack was composed, audit flags it as constituent drift. Stack skills that need updating are redirected to `@Ferris SS` for re-composition (surgical update is not supported for stacks).
+
 **Agent:** Ferris (Audit mode)
 
 ---
@@ -135,13 +135,13 @@ SKF has 14 workflows. You trigger them by typing commands to [Ferris](../agents/
 
 **Command:** `@Ferris TS`
 
-**Purpose:** Cognitive completeness verification. Naive and contextual modes. Quality gate before export.
+**Purpose:** Verifies whether a skill covers its target completely and accurately. Naive and contextual modes. Quality gate before export.
 
 **When to Use:** After creating or updating a skill, before exporting.
 
 **Key Steps:** Load skill → Detect mode → Coverage check → Coherence check → External validation (skill-check, tessl) → Score → Gap report
 
-**Scored Categories:** Export Coverage (36%), Signature Accuracy (22%), Type Coverage (14%), Coherence (18%), External Validation (10%). Default pass threshold: **80%**. Pass routes to Export Skill; fail routes to Update Skill with a gap report. See [Completeness Scoring](../how-it-works/#completeness-scoring) for the full formula and tier adjustments.
+**Scored Categories:** Export Coverage (36%), Signature Accuracy (22%), Type Coverage (14%), Coherence (18%), External Validation (10%). Default pass threshold: **80%**. Pass routes to Export Skill; fail routes to Update Skill with a gap report. See [Completeness Scoring](../verifying-a-skill/#how-the-score-is-computed) for the full formula and tier adjustments.
 
 **Agent:** Ferris (Audit mode)
 
@@ -167,7 +167,7 @@ SKF has 14 workflows. You trigger them by typing commands to [Ferris](../agents/
 
 **Command:** `@Ferris RA`
 
-**Purpose:** Evidence-backed architecture improvement. Takes the original architecture doc + generated skills + optional VS report, fills gaps, flags contradictions, and suggests improvements — all citing specific APIs.
+**Purpose:** Improves an architecture document using verified skill data as evidence. Takes the original architecture doc + generated skills + optional VS report, fills gaps, flags contradictions, and suggests improvements — all citing specific APIs.
 
 **When to Use:** After VS confirms feasibility, before running SS in compose-mode. Produces a refined architecture ready for stack skill composition.
 
@@ -217,7 +217,7 @@ SKF has 14 workflows. You trigger them by typing commands to [Ferris](../agents/
 
 **Purpose:** Drop a specific skill version or an entire skill. Soft drop (default) marks the version as deprecated in the manifest and keeps files on disk. Hard drop (`--purge`) also deletes the files.
 
-**When to Use:** Retire a deprecated version (e.g., drop `cognee 0.1.0` because it's obsolete), free disk space, or remove a skill you no longer need.
+**When to Use:** Retire a deprecated version (e.g., drop an older cognee skill version because it's obsolete), free disk space, or remove a skill you no longer need.
 
 **Key Steps:** Select skill → Select version(s) + mode → Update manifest → Rebuild context files → Delete files (if purge)
 
@@ -262,7 +262,7 @@ flowchart TD
     TS --> EX[Export Skill]
 ```
 
-> **One workflow per session.** Each arrow in the diagrams above represents a new conversation session. Clear your context between workflows for best results — this prevents leftover step files and extraction data from interfering with the next workflow. See [Session Context](../concepts/#session-context).
+> **One workflow per session** (unless using pipeline mode). Each arrow in the diagrams above represents a new conversation session. Clear your context between workflows for best results — or use pipeline mode to chain them automatically. See [Pipeline Mode](#pipeline-mode) below.
 
 ---
 
@@ -272,7 +272,113 @@ flowchart TD
 |----------|-----------|-------------|
 | 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 | Audit skill completeness and test skill accuracy |
+| 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) |
+
+---
+
+## Pipeline Mode
+
+Instead of running one workflow per session, you can chain multiple workflows in a single command. Ferris executes them left to right, passing data (brief path, skill name) between each workflow automatically.
+
+### Syntax
+
+```
+@Ferris BS CS TS EX                    — space-separated codes
+@Ferris QS[cocoindex] TS EX            — with target argument in brackets
+@Ferris CS TS[min:80] EX               — with circuit breaker threshold override
+@Ferris forge-quick cognee             — named alias with target
+```
+
+### 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 |
+
+**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.
+
+### How It Works
+
+- Pipelines **automatically activate headless mode** — all confirmation gates auto-proceed with their default action
+- **Data flows automatically** — once the first workflow completes, the brief path or skill name becomes the input for downstream workflows
+- **Circuit breakers** halt the pipeline if quality drops below a threshold (e.g., test score < 60 blocks export)
+- **Anti-pattern warnings** — Ferris warns if you chain workflows in a problematic order (e.g., exporting before testing)
+- **Progress reporting** — Ferris reports completion of each workflow before starting the next
+- **Safe halt on ambiguity** — headless mode won't guess. If the initial target doesn't satisfy the first workflow's contract (e.g., `forge cognee` — ambiguous, not a URL or path), the pipeline halts at step 1 before any work happens and suggests concrete next steps.
+
+### Examples
+
+```
+@Ferris forge-quick @tanstack/query                                  — QS + TS + EX for TanStack Query
+@Ferris forge https://github.com/topoteretes/cognee cognee           — BS + CS + TS + EX, explicit URL + name
+@Ferris forge https://github.com/topoteretes/cognee cognee "public API only"   — with scope hint
+@Ferris maintain cocoindex                                           — AS + US + TS + EX for an existing cocoindex skill
+@Ferris onboard                                                      — AN + CS + TS + EX on the current project
+```
+
+---
+
+## Headless Mode
+
+Add `--headless` or `-H` to any workflow command to skip all confirmation gates. Ferris auto-proceeds with default actions (typically "Continue") and logs each auto-decision. Progress output is still shown — headless skips interaction, not reporting.
+
+```
+@Ferris QS cocoindex --headless  — quick skill with no interaction gates
+@Ferris TS --headless             — test a skill without the review pause
+@Ferris EX -H                    — export with auto-approved context update
+```
+
+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.
+
+---
+
+## Terminal Step: Health Check
+
+All 14 workflows above share the same final step — a **health check** defined in [`src/shared/health-check.md`](https://github.com/armelhbobdad/bmad-module-skill-forge/blob/main/src/shared/health-check.md). This isn't a workflow you invoke directly; there's no command code and no menu entry. Each workflow ends with a dedicated local `step-NN-health-check.md` whose `nextStepFile` points at the shared file, so the health check fires automatically once the main work is done. After the main work is done, Ferris reflects internally on the execution:
+
+- Did any step instruction lead the agent astray or cause unnecessary back-and-forth?
+- Was any step ambiguous, forcing the agent to guess?
+- Did a scenario arise that the workflow didn't account for?
+- Were any instructions wrong or contradictory?
+
+If the answer to all of these is "no", the health check exits in one line (`Clean run. No workflow issues to report.`). If real friction was observed, Ferris presents structured findings, waits for your review, and — on your approval — routes them to this repo.
+
+**Zero overhead for clean runs. High leverage when something breaks.** The health check is honest-by-default: zero findings is the expected outcome. Fabricated issues would hurt the signal, so Ferris only reports what the agent actually experienced.
+
+### How findings are routed
+
+- **Severity gate.** Only `bug` findings submit live as GitHub issues by default. `friction` and `gap` findings — the most subjective categories — go to a **local queue** at `{output_folder}/improvement-queue/` unless you explicitly opt in to submit them live during the review gate. This keeps the high-signal reports (real defects) flowing to maintainers while the softer observations sit safely on your disk for you to batch or revisit.
+- **Fingerprint dedup.** Every finding gets a deterministic 7-hex fingerprint computed from `sha1(severity|workflow|step_file|section)` — no LLM similarity judgment, just a tuple hash. Before Ferris opens a new issue, it searches the repo for an existing open issue with the same `fp-*` label. If one exists, you're offered a choice: add a 👍 reaction (silent upvote), react + post a one-sentence environment delta, open a new issue anyway (if you're certain it's distinct), or skip. Re-reporting the same fingerprint is safe — it just adds to the signal-count on the canonical issue.
+- **Global seen-cache.** Once you've submitted or reacted for a given fingerprint, it's recorded at `~/.skf/health-check-seen.json` so the same user never re-reports the same defect across sessions or across different projects on the same machine.
+- **Server-side safety net.** If two users race past the client-side search and both open issues with the same fingerprint, a GitHub Action on this repo catches it: the later issue is auto-closed as a duplicate, linked to the canonical (lowest-numbered) issue, and a 👍 is added there to preserve the signal-count. Manual filers using the [issue template](https://github.com/armelhbobdad/bmad-module-skill-forge/issues/new/choose) feed the same pipeline.
+
+**Net effect:** 1,000 users hitting the same bug produce **one canonical issue** with a reaction-count of roughly 1,000 — not 1,000 duplicate issues or a 1,000-comment thread. The maintainer sees population impact at a glance, and your report is never lost.
+
+### Please let workflows run to completion
+
+If you cancel a workflow early, or interrupt the agent before the terminal step, the health check doesn't run — and any friction from that session is lost. When you have time, let each workflow reach its natural end. The health check is how SKF learns to do better.
+
+### If the health check didn't run
+
+You have two recovery options:
+
+1. **Ask Ferris to run it now** — while the session context is still fresh:
+
+   ```
+   @Ferris please run the workflow health check for this session
+   ```
+
+   Ferris will load `shared/health-check.md` and reflect on what just happened, exactly as if the workflow had reached its natural end.
+
+2. **Open an issue directly** — use the [Workflow Health Check issue template](https://github.com/armelhbobdad/bmad-module-skill-forge/issues/new/choose) on this repo. Any concrete, evidence-based report helps — cite the specific step file and section where the friction occurred, and describe what you actually observed (not what you think the problem is).
+
+Both paths feed the same improvement queue.
+
+> **Note:** Some gates cannot be skipped even in headless mode — for example, merge conflicts in Update Skill always require human judgment.

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "bmad-module-skill-forge",
-  "version": "0.9.0",
+  "version": "0.10.1-alpha.0",
   "description": "BMAD module — Turn code and docs into instructions AI agents can actually follow. Progressive capability tiers (Quick/Forge/Forge+/Deep).",
   "keywords": [
     "bmad",
@@ -9,9 +9,15 @@
     "bmad-module",
     "agent-skills",
     "agentskills",
+    "agents",
+    "skills",
     "skill-forge",
+    "compilation",
+    "forge",
     "ast-grep",
     "qmd",
+    "cocoindex",
+    "cocoindex-code",
     "provenance",
     "code-analysis"
   ],
@@ -30,6 +36,7 @@
     "docs:dev": "npm run --prefix website docs:dev",
     "docs:fix-links": "node tools/fix-doc-links.js --write",
     "docs:preview": "npm run --prefix website preview",
+    "docs:validate-drift": "node tools/validate-docs-drift.js",
     "docs:validate-links": "node tools/validate-doc-links.js",
     "format:check": "prettier --check \"**/*.{js,cjs,mjs,json,yaml}\"",
     "format:fix": "prettier --write \"**/*.{js,cjs,mjs,json,yaml}\"",
@@ -37,17 +44,26 @@
     "lint:fix": "eslint . --ext .js,.cjs,.mjs,.yaml --fix",
     "lint:md": "markdownlint-cli2 \"**/*.md\"",
     "prepare": "husky || exit 0",
+    "quality": "npm run format:check && npm run lint && npm run lint:md && npm run test:schemas && npm run test:install && npm run test:cli && npm run test:workflow && npm run test:python && npm run test:knowledge && npm run validate:schemas && npm run validate:skills && npm run validate:refs && npm run docs:validate-drift",
     "release": "npm run release:patch",
     "release:major": "npm version major && git push --follow-tags",
     "release:minor": "npm version minor && git push --follow-tags",
     "release:patch": "npm version patch && git push --follow-tags",
     "release:prerelease": "npm version prerelease && git push --follow-tags",
-    "test": "npm run test:schemas && npm run test:install && npm run test:cli && npm run test:knowledge && npm run validate:schemas && npm run lint && npm run lint:md && npm run format:check",
+    "skf:install": "node tools/cli/skf-cli.js install",
+    "skf:status": "node tools/cli/skf-cli.js status",
+    "skf:uninstall": "node tools/cli/skf-cli.js uninstall",
+    "skf:update": "node tools/cli/skf-cli.js update",
+    "test": "npm run test:schemas && npm run test:install && npm run test:cli && npm run test:workflow && npm run test:python && npm run test:knowledge && npm run validate:schemas && npm run validate:skills && npm run validate:refs && npm run lint && npm run lint:md && npm run format:check",
     "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:schemas": "node test/test-agent-schema.js",
-    "validate:schemas": "node test/validate-agent-schema.js"
+    "test:workflow": "node test/test-workflow-state.js",
+    "validate:refs": "node tools/validate-file-refs.js --strict",
+    "validate:schemas": "node test/validate-agent-schema.js",
+    "validate:skills": "node tools/validate-skills.js --strict"
   },
   "lint-staged": {
     "*.{js,cjs,mjs}": [
@@ -63,6 +79,9 @@
     ],
     "*.md": [
       "markdownlint-cli2"
+    ],
+    "*.astro": [
+      "prettier --write --ignore-unknown"
     ]
   },
   "dependencies": {
@@ -80,6 +99,7 @@
     "archiver": "^7.0.1",
     "astro": "^5.16.0",
     "c8": "^10.1.3",
+    "conventional-changelog-cli": "^5.0.0",
     "csv-parse": "^6.1.0",
     "eslint": "^9.33.0",
     "eslint-config-prettier": "^10.1.8",
@@ -100,7 +120,8 @@
     "xml2js": "^0.6.2",
     "yaml": "^2.7.0",
     "yaml-eslint-parser": "^1.2.3",
-    "yaml-lint": "^1.7.0"
+    "yaml-lint": "^1.7.0",
+    "zod": "^3.25.0"
   },
   "engines": {
     "node": ">=22.0.0"