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

package/docs/concepts.md

@@ -1,51 +1,49 @@
 ---
 title: Concepts
-description: Plain-English definitions of key Skill Forge terms — agent skills, provenance, confidence tiers, drift, and more
+description: Seven load-bearing terms for using and understanding Skill Forge — agent skills, provenance, confidence tiers, capability tiers, drift, version pinning, and the BMAD module.
 ---
 
-# Concepts
-
-This page defines the key terms you'll encounter in Skill Forge, with concrete examples.
+These are the seven terms you'll meet in every other page of this site. Each one names something SKF does differently from generic docs tooling. For the full mechanism behind them, see [Architecture](../architecture/) and [Skill Model](../skill-model/).
 
 ---
 
 ## Agent Skills
 
-An agent skill is an instruction file that tells an AI agent how to use your code. Instead of the agent guessing your API from its training data, it reads the skill and gets real function names, real parameter types, and real usage patterns.
+An agent skill is an instruction file that tells an AI agent how to use your code. Instead of guessing your API from its training data, the agent reads the skill and gets the actual function names, parameter types, and usage patterns.
 
 Skills follow the [agentskills.io](https://agentskills.io) open standard, so they work across Claude, Cursor, Copilot, and other AI tools.
 
-**Example:** A skill for [cognee](https://github.com/armelhbobdad/oh-my-skills) tells your agent: "The function is `cognee.search()`, it takes `query_text`, `query_type`, `top_k`, and `session_id`, and it's defined at `cognee/api/v1/search/search.py:L26`." Every parameter and location is AST-verified from the actual source code.
+**Example:** A skill for [cognee](https://github.com/topoteretes/cognee) tells your agent: "The function is `cognee.search()`, its first parameters are `query_text`, `query_type`, `user`, `datasets`, and `dataset_ids`, and it's defined at `cognee/api/v1/search/search.py:L26` (v1.0.0, commit `3c048aa4`)." Every parameter and location is AST-verified from the actual source code.
 
 ---
 
 ## Provenance
 
-Provenance means every instruction in a skill traces back to where it came from. For code, that's a file and line number. For documentation, it's a URL. For developer discourse, it's an issue or PR reference. If SKF can't point to a source, it doesn't include the instruction.
+Provenance means every instruction in a skill traces back to where it came from. For code, that's a file and line number. For documentation, it's a URL. For developer discourse, it's an issue or PR reference. **If SKF can't point to a source, it doesn't include the instruction.**
 
 **Examples** (from a [real generated skill](https://github.com/armelhbobdad/oh-my-skills)):
 - `[AST:cognee/api/v1/search/search.py:L26]` — extracted from source code via AST parsing (T1)
-- `[SRC:cognee/api/v1/session/__init__.py:L8]` — read from source code without AST verification (T1-low)
+- `[SRC:cognee/api/v1/session/__init__.py:L7]` — read from source code without AST verification (T1-low)
 - `[QMD:cognee-temporal:issues.md]` — surfaced from indexed developer discourse (T2)
 - `[EXT:docs.cognee.ai/getting-started/quickstart]` — sourced from external documentation (T3)
 
+This is the opposite of how most AI tools work. They generate plausible-sounding content from training data; SKF only includes what it can cite. Quick-tier skills rely on best-effort source reading rather than AST verification — but even Quick skills cite their sources, and nothing ships without a citation.
+
 ---
 
 ## Confidence Tiers (T1/T1-low/T2/T3)
 
 Each piece of information in a skill carries a confidence level based on where it came from:
 
-- **T1 — AST extraction:** Pulled directly from source code via AST parsing. This is structural truth — the function signature actually exists in the code right now. Cited as `[AST:file:Lnn]`.
+- **T1 — AST extraction:** Pulled directly from source code via AST parsing. The function signature exists in the code at the pinned commit. Cited as `[AST:file:Lnn]`.
 - **T1-low — Source reading:** Found by reading source files directly without AST parsing. The location is correct but the type signature may be inferred. Produced by Quick tier and by Forge/Forge+/Deep when ast-grep cannot parse a specific file. Cited as `[SRC:file:Lnn]`.
-- **T2 — Evidence (Deep tier only):** Surfaced by QMD knowledge search from issues, PRs, changelogs, or documentation within the repository. Available only when QMD is installed (Deep tier). Reliable context, but not as definitive as code. Cited as `[QMD:collection:document]`. T2 has two temporal subtypes:
+- **T2 — Evidence (Deep tier only):** Surfaced by QMD knowledge search from issues, PRs, changelogs, or documentation within the repository. Available only when QMD is installed (Deep tier). Reliable context, but less definitive than source code itself. Cited as `[QMD:collection:document]`. T2 has two temporal subtypes:
   - **T2-past** — Historical context (closed issues, merged PRs, changelogs) explaining API design decisions. Surfaces in the skill's `references/` directory.
   - **T2-future** — Forward-looking context (open PRs, deprecation warnings, RFCs) about upcoming changes. Surfaces in SKILL.md Section 4b (Migration & Deprecation Warnings) and `references/`.
 - **T3 — External:** Pulled from external documentation or websites. Treated with caution and clearly marked. Cited as `[EXT:url]`.
 
 Forge+ semantic discovery (via cocoindex-code) does not introduce a new confidence tier — it influences *which* files are extracted, not *how* they're cited. Discovered files are verified by ast-grep (T1) or source reading (T1-low).
 
-See the [Provenance](#provenance) examples above for real citations at each tier.
-
 ---
 
 ## Capability Tiers (Quick/Forge/Forge+/Deep)
@@ -53,33 +51,21 @@ See the [Provenance](#provenance) examples above for real citations at each tier
 Your capability tier depends on which tools you have installed. Each tier builds on the previous one:
 
 - **Quick** — No tools required. SKF reads source files and builds best-effort skills. Works in under a minute. GitHub CLI used when available.
-- **Forge** — Adds [ast-grep](https://ast-grep.github.io). SKF uses AST parsing for structural truth. Instructions are verified against the actual code structure.
+- **Forge** — Adds [ast-grep](https://ast-grep.github.io). SKF uses AST parsing to verify instructions against the actual code structure.
 - **Forge+** — Adds [cocoindex-code](https://github.com/cocoindex-io/cocoindex-code). SKF uses semantic code search to discover relevant source regions before AST extraction, improving coverage on large codebases.
 - **Deep** — Full pipeline: requires [ast-grep](https://ast-grep.github.io) + [GitHub CLI](https://cli.github.com) + [QMD](https://github.com/tobi/qmd) (all three). SKF indexes knowledge for semantic search and performs GitHub repository exploration. Skills get enriched with historical context, deprecation warnings, and cross-reference intelligence. CCC (cocoindex-code) enhances Deep tier when installed — ast-grep + gh + qmd + ccc gives maximum capability.
 
-You don't need all tools to start. SKF detects what you have and sets your tier automatically. See [How It Works](../how-it-works/) for the full technical treatment.
+You don't need all tools to start. SKF detects what you have and sets your tier automatically. See [Skill Model → Progressive Capability Model](../skill-model/#progressive-capability-model) for the full technical treatment.
 
 ---
 
 ## Drift
 
-Drift happens when the source code changes but the skill instructions haven't been updated to match. A skill might still reference a function that was renamed, removed, or had its signature changed.
+Drift happens when the source code changes but the skill instructions haven't been updated to match. A skill might still reference a function that was renamed, removed, or had its signature changed upstream.
 
-SKF detects drift by comparing the skill's recorded provenance against the current code. The `audit-skill` workflow (`@Ferris AS`) scans for these mismatches.
+SKF detects drift by comparing the skill's recorded provenance against the current code. The `audit-skill` workflow (`@Ferris AS`) scans for these mismatches — for both individual skills and stack skills. Stack skills track per-library provenance and, in compose-mode, constituent freshness via metadata hash comparison.
 
-**Example:** Your skill says `createUser(name: string)` but the function was renamed to `registerUser(name: string, email: string)` in the last release. That's drift.
-
----
-
-## Completeness Score
-
-The completeness score is a weighted measure of how thoroughly a skill documents its target. The Test Skill workflow (`@Ferris TS`) calculates it across five categories: **Export Coverage** (are all source exports documented?), **Signature Accuracy** (do documented signatures match the actual code?), **Type Coverage** (are referenced types complete?), **Coherence** (do cross-references and integration patterns resolve?), and **External Validation** (do skill-check and tessl confirm quality?).
-
-The default pass threshold is **80%**, overridable by specifying a custom threshold when invoking `@Ferris TS`. Skills that pass are ready for export (`@Ferris EX`); skills that fail route to update (`@Ferris US`) with a gap report showing what to fix.
-
-**Example:** A skill scores 92% export coverage, 85% signature accuracy, 100% type coverage, 80% coherence, and 78% external validation. With the default weights (36/22/14/18/10), the weighted total is 88.0% — a pass.
-
-Your forge tier determines which categories are scored. Quick-tier skills skip signature accuracy and type coverage (no AST available), and the weights redistribute proportionally. See [How It Works](../how-it-works/#completeness-scoring) for the full formula and tier adjustments.
+**Example:** Your skill says `createUser(name: string)` but the function was renamed to `registerUser(name: string, email: string)` in the last release. That's drift. For stack skills, constituent drift occurs when an individual skill is updated but the stack hasn't been re-composed to reflect the changes.
 
 ---
 
@@ -87,90 +73,14 @@ Your forge tier determines which categories are scored. Quick-tier skills skip s
 
 Every skill records the exact version (or commit) of the source code it was built from. This means you always know which version of the library the instructions apply to.
 
-By default, the version is auto-detected from the source (package.json, pyproject.toml, etc.). You can also target a specific version — either by specifying it during `@Ferris BS` (brief-skill) or by appending `@version` to a quick skill command (`@Ferris QS cognee@0.5.0`). This is especially useful for docs-only skills where no source code is available for auto-detection. When targeting a specific version on a remote repository, SKF resolves the matching git tag and clones from it — so the extracted API signatures actually reflect the target version's code, not just the label applied to whatever happens to be on the default branch.
+By default, the version is auto-detected from the source (package.json, pyproject.toml, etc.). You can also target a specific version — either by specifying it during `@Ferris BS` (brief-skill) or by appending `@version` to a quick skill command (`@Ferris QS cognee@1.0.0`). This is especially useful for docs-only skills where no source code is available for auto-detection. When targeting a specific version on a remote repository, SKF resolves the matching git tag and clones from it — so the extracted API signatures actually reflect the target version's code, not just the label applied to whatever happens to be on the default branch.
 
 When the source updates, you can re-run `@Ferris US` (update-skill) to regenerate the skill for the new version while preserving any manual additions you've made.
 
 ---
 
-## Skill Management
-
-Two workflows let you rename and retire skills without manually editing files:
-
-**Rename (`@Ferris RS`)** — Change a skill's name across all its versions. Transactional: copies to the new name, verifies every reference, then deletes the old name only after verification succeeds. If anything fails mid-rename, the old skill stays intact. Use it to graduate quick-skills to formal names, or to add a suffix like `-community`.
-
-**Drop (`@Ferris DS`)** — Retire a specific version (e.g., drop `cognee 0.1.0` because it's deprecated) or an entire skill. Two modes:
-- **Soft drop (default)** marks the version as deprecated in the manifest and keeps files on disk. It stops appearing in CLAUDE.md/AGENTS.md/.cursorrules immediately but is reversible by editing the manifest.
-- **Hard drop (purge)** also deletes the files from disk. Irreversible.
-
-Both operations automatically rebuild platform context files so your AI agents see the updated state on the next session.
-
----
-
 ## BMAD Module
 
-SKF is a plugin (called a "module") for [BMad Method](https://docs.bmad-method.org/), a framework for running structured AI workflows. You don't need to know BMad to use SKF — the standalone installer sets everything up.
-
-→ If you already use BMAD, see [BMAD Synergy](../bmad-synergy/) for how SKF workflows pair with BMM phases and optional modules like TEA, BMB, and GDS.
-
----
-
-## Ferris
-
-Ferris is the AI agent persona that runs all SKF workflows. When you type `@Ferris CS`, you're telling Ferris to run the create-skill workflow.
-
-Ferris switches between four modes depending on which workflow is active: Architect (exploring and building), Surgeon (precise updates), Audit (quality checks), and Delivery (packaging for distribution).
-
----
-
-## Zero Hallucination
-
-SKF's core principle: if an instruction can't be traced back to actual source code, it doesn't get included in the skill. This is the opposite of how most AI tools work — they generate plausible-sounding content from training data. SKF only includes what it can verify.
-
-This doesn't mean skills are perfect. Quick-tier skills read source files without AST verification, so they rely on best-effort extraction. But even Quick skills cite their sources, and no tier includes invented information.
-
----
-
-## Scripts & Assets
-
-Skills can include executable scripts and static assets alongside the main SKILL.md instructions. Scripts handle deterministic operations (validation, setup, data processing) while assets provide templates, schemas, and configuration examples. Both are extracted from the source repository with provenance tracking — SKF copies them, it doesn't fabricate them.
-
-**Example:** A database library skill might include `scripts/migrate.sh` (copied from the library's `bin/` directory) and `assets/config-schema.json` (copied from the library's `schemas/` directory). Each file carries a `[SRC:file:L1]` citation and SHA-256 hash for drift detection.
-
----
-
-## Session Context
-
-Each SKF workflow should run in a clean conversation session. Workflows load step files, knowledge fragments, and extraction data into the LLM's context as they execute. If you run a second workflow in the same session, leftover context from the first workflow can interfere with the second — causing stale references, mode confusion, or degraded output quality.
-
-**Best practice:** Clear your session context (start a new conversation) before invoking a new workflow. For example, after `@Ferris CS` completes a skill, start a fresh session before running `@Ferris TS` to test it.
-
-This applies to sequential workflows in the same session. Sidecar state (forge tier, preferences) persists across sessions automatically — you don't lose any configuration by clearing context.
-
----
-
-## Full Control Over Scope
-
-You can compile multiple skills from the same target (repo or docs) with different scopes, intents, and audiences. Each brief defines what to extract and why, producing a distinct skill from the same source.
-
-**Example:** From a single library like [cognee](https://github.com/topoteretes/cognee), you could compile:
-
-- `cognee-core` — public API surface for general usage
-- `cognee-graph-types` — type system and data model for schema work
-- `cognee-migration` — upgrade patterns and breaking changes for version transitions
-
-Each skill serves a different use case. You decide the scope — SKF compiles exactly what you specify.
-
----
-
-## Best Practices
-
-SKF integrates skill authoring best practices from the Claude platform and community guidelines. Generated skills use third-person descriptions for reliable agent discovery, consistent terminology throughout, and appropriate degrees of freedom (prescriptive for fragile operations like database migrations, flexible for creative tasks like code reviews). These practices are enforced during compilation and verified during testing.
-
-**Example:** A skill description reads "Processes payments via REST API with token-based auth. NOT for: billing dashboards" — third-person voice, specific keywords, and negative triggers help agents select the right skill.
-
-**Operational best practices:**
+SKF is a plugin (called a "module") for [BMAD Method](https://docs.bmad-method.org/), a framework for running structured AI workflows. You don't need to know BMAD to use SKF — the standalone installer sets everything up.
 
-- **One workflow per session** — clear context between workflows to prevent stale state from affecting results
-- **Multiple skills per target** — compile different skills from the same repo or docs for different use cases and audiences
-- **Progressive capability** — start with Quick mode, upgrade tiers as you install more tools
+If you already use BMAD, see [BMAD Synergy](../bmad-synergy/) for how SKF workflows pair with BMM phases and optional modules like TEA, BMB, and GDS.

package/docs/examples.md

@@ -1,26 +1,29 @@
 ---
 title: Examples
-description: Real-world scenarios, tips, and troubleshooting for Skill Forge
----
-
-# Examples & Use Cases
-
-This section provides practical examples for using SKF: Skill Forge.
-
+description: Real-world scenarios and operational tips for Skill Forge. For common errors, see Troubleshooting.
 ---
 
 ## What the Output Looks Like
 
-When SKF generates a skill, you get a `SKILL.md` file with machine-readable frontmatter and provenance-backed instructions. Here's a trimmed example from a real skill generated for [cognee](https://github.com/topoteretes/cognee) (browse the full output at [oh-my-skills](https://github.com/armelhbobdad/oh-my-skills)):
+When SKF generates a skill, you get a `SKILL.md` file with machine-readable frontmatter and provenance-backed instructions. Below is a trimmed example from the real [`oms-cognee` SKILL.md](https://github.com/armelhbobdad/oh-my-skills/blob/main/skills/oms-cognee/1.0.0/oms-cognee/SKILL.md) generated for [cognee](https://github.com/topoteretes/cognee) (full portfolio at [oh-my-skills](https://github.com/armelhbobdad/oh-my-skills)):
 
 **Frontmatter (tells AI agents when to load this skill):**
 
 ```yaml
-name: cognee
-description: Use when cognee is a Python AI memory engine that transforms
-  documents into knowledge graphs with vector and graph storage for semantic
-  search and reasoning. Use this skill when writing code that calls cognee's
-  Python API (add, cognify, search, memify, config, datasets, prune, session).
+name: oms-cognee
+description: >
+  Builds apps on top of cognee v1.0.0, the knowledge-graph memory engine for AI agents.
+  Use when ingesting text/files/URLs into persistent memory, building knowledge graphs,
+  searching graph-backed memory with multiple SearchType modes, enriching graphs with
+  memify/improve, scoping memory with datasets and node_sets, configuring LLM/embedding/
+  graph/vector backends, running custom task pipelines, tracing operations, decorating
+  agent entrypoints with `agent_memory`, connecting to Cognee Cloud with `serve`, or
+  visualizing the graph. Covers cognee/__init__.py exports: the V1 API (add, cognify,
+  search, memify, datasets, prune, update, run_custom_pipeline, config, SearchType,
+  visualize_graph, pipelines, Drop, run_startup_migrations, tracing) and the V2
+  memory-oriented API (remember, RememberResult, recall, improve, forget, serve,
+  disconnect, visualize, agent_memory). Do NOT use for: cognee internals, the HTTP
+  REST API (use cognee-mcp or the FastAPI server), non-cognee memory/RAG libraries.
 ```
 
 **Body (what your AI agent reads):**
@@ -31,47 +34,53 @@ description: Use when cognee is a Python AI memory engine that transforms
 | Function | Purpose | Key Params | Source |
 |----------|---------|------------|--------|
 | add() | Ingest text, files, binary data | data, dataset_name | [AST:cognee/api/v1/add/add.py:L22] |
-| cognify() | Build knowledge graph | datasets, graph_model | [AST:cognee/api/v1/cognify/cognify.py:L47] |
+| cognify() | Build knowledge graph | datasets, graph_model | [AST:cognee/api/v1/cognify/cognify.py:L44] |
 | search() | Query knowledge graph | query_text, query_type | [AST:cognee/api/v1/search/search.py:L26] |
-| memify() | Enrich graph with custom tasks | extraction_tasks, data | [AST:cognee/modules/memify/memify.py:L27] |
-| session.* | Session history and feedback | get_session(), add_feedback() | [SRC:cognee/api/v1/session/__init__.py:L8] |
+| memify() | Enrich graph with custom tasks | extraction_tasks, data | [AST:cognee/modules/memify/memify.py:L25] |
+| remember() | V2 one-shot memory ingest | data, dataset_name | [AST:cognee/api/v1/remember/remember.py:L339] |
 | DataPoint | Base class for custom graph nodes | inherit and add fields | [EXT:docs.cognee.ai/guides/custom-data-models] |
 ```
 
+Every line number above is verbatim from the real [`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) shipped with oh-my-skills — not illustrative.
+
 Provenance tags trace each instruction to its source:
 - `[AST:file:line]` — extracted from code via AST parsing (highest confidence)
 - `[SRC:file:line]` — read from source code without AST verification
 - `[EXT:url]` — sourced from external documentation
 - `[QMD:collection:doc]` — surfaced from indexed developer discourse (issues, PRs, changelogs)
 
-See [How It Works](../how-it-works/) for the full output structure.
+See [Skill Model → Output Architecture](../skill-model/#output-architecture) for the full output structure.
 
-**Full skill directory structure:**
+**Full skill directory structure** (real layout from [`oh-my-skills/skills/oms-cognee/`](https://github.com/armelhbobdad/oh-my-skills/tree/main/skills/oms-cognee)):
 
 ```
-skills/cognee/
-├── active -> 0.5.5
-└── 0.5.5/
-    └── cognee/
-        ├── SKILL.md              # What your agent reads
+skills/oms-cognee/
+├── active -> 1.0.0
+├── 0.5.8/
+│   └── oms-cognee/
+│       ├── SKILL.md              # Archived: v0.5.8, pinned to b51dcce1
+│       ├── context-snippet.md
+│       ├── metadata.json
+│       └── references/
+└── 1.0.0/
+    └── oms-cognee/
+        ├── SKILL.md              # Active: pinned to cognee v1.0.0 (3c048aa4)
         ├── context-snippet.md    # Compressed index for platform context files
         ├── metadata.json         # Machine-readable provenance
-        ├── references/           # Progressive disclosure detail
-        │   ├── api-core.md
-        │   └── graph-types.md
-        ├── scripts/              # Executable utilities (when detected)
-        │   └── setup-graphdb.sh
-        └── assets/               # Templates and schemas (when detected)
-            └── config-schema.json
+        └── references/           # Progressive disclosure detail
+            ├── config.md
+            ├── core-workflow.md
+            ├── full-api-reference.md
+            └── pipelines-and-datapoints.md
 ```
 
-Skills are stored per-version — updating cognee to v0.6.0 creates a new version directory without overwriting v0.5.5. The `active` symlink always points to the current version. The `scripts/` and `assets/` directories appear only when the source repository contains them. Each file traces back to its source with provenance citations and SHA-256 hashes.
+This is the real directory listing from [`oh-my-skills/skills/oms-cognee/`](https://github.com/armelhbobdad/oh-my-skills/tree/main/skills/oms-cognee) after cognee shipped v1.0.0 upstream. SKF recompiled the skill from the v1.0.0 commit and wrote it next to the existing 0.5.8 tree — the older version stays pinned to its original commit (`b51dcce1`) and is still installable by any project that hasn't bumped its `CLAUDE.md` pin yet. The `active` symlink and the [`.export-manifest.json`](https://github.com/armelhbobdad/oh-my-skills/blob/main/skills/.export-manifest.json) both point at the current version. Some skills also include `scripts/` and `assets/` directories when the source repository contains executable scripts or static assets — oms-cognee doesn't have either, but see [Skill Model → Per-Skill Output](../skill-model/#per-skill-output) for the full schema.
 
 ---
 
 ## Example Workflows
 
-### Quick Skill — 47 Seconds
+### Quick Skill — Under a minute
 
 Developer adds [cognee](https://github.com/topoteretes/cognee) to a Python project for AI memory management. Agent keeps hallucinating method signatures and config options.
 
@@ -79,32 +88,44 @@ Developer adds [cognee](https://github.com/topoteretes/cognee) to a Python proje
 @Ferris QS https://github.com/topoteretes/cognee
 ```
 
-Ferris reads the repository, extracts the public API via source reading, validates against spec. Skill appears in `skills/cognee/0.5.5/cognee/`. Agent stops hallucinating. Forty-seven seconds. Done.
+Ferris reads the repository, extracts the public API, and validates against the agentskills.io spec. The skill is written to `skills/cognee/<version>/cognee/` (auto-detected from the source manifest). The agent now reads the real signatures from the skill instead of guessing.
 
 Need a specific version? Append `@version`:
 
 ```
-@Ferris QS cognee@0.5.0
+@Ferris QS cognee@1.0.0
 ```
 
-### Brownfield Platform — 8 Minutes
+### Brownfield Platform — Pipeline or per-workflow
 
-Alex's team adopts BMAD for 10 microservices (TypeScript, Go, Rust).
+Alex, a platform engineer, adopts BMAD for 10 microservices spanning TypeScript, Go, and Rust.
+
+```
+@Ferris SF          # Setup — Deep tier detected
+# — clear session —
+@Ferris onboard     # Analyze → Create → Test → Export in one pipeline
+```
 
+Or one workflow per session:
 ```
-@Ferris SF          # Setup — Deep mode detected
+@Ferris SF          # Setup — Deep tier detected
 # — clear session —
 @Ferris AN          # Analyze — 10 services mapped
 # — clear session —
 @Ferris CS --batch  # Create — batch generation
 ```
 
-10 individual skills + 1 platform stack skill. [BMM](../bmad-synergy/#skf-and-bmm-phase-by-phase-playbook) architect navigates cross-service flows with verified knowledge.
+10 individual skills + 1 platform stack skill. The [BMM](../bmad-synergy/#skf-and-bmm-phase-by-phase-playbook) architect then navigates cross-service flows using verified knowledge.
 
 ### Release Prep — Trust Builder
 
-Sarah prepares v3.0.0 with breaking changes.
+Jin, a Rust library maintainer, is preparing v1.0.0 with breaking changes she wants consumers' agents to pick up automatically.
 
+```
+@Ferris maintain cocoindex
+```
+
+Or one workflow per session:
 ```
 @Ferris AS    # Audit — finds 3 renames, 1 removal, 1 addition
 # — clear session —
@@ -115,21 +136,21 @@ Sarah prepares v3.0.0 with breaking changes.
 @Ferris EX    # Export — package for npm release
 ```
 
-Ships with npm release. Consumers upgrade — their agents use the correct function names. Zero hallucination tickets.
+Ships with the npm release. Consumers upgrade and their agents use the correct function names — no more "wrong signature" support tickets.
 
 ### Stack Skill — Integration Intelligence
 
-Armel's full-stack project: Next.js + Serwist + SpacetimeDB + better-auth.
+Armel, building a full-stack side project on Next.js + Serwist + SpacetimeDB + better-auth.
 
 ```
 @Ferris SS
 ```
 
-Ferris detects 8 significant dependencies, finds 5 co-import integration points. Generates a consolidated stack skill. The agent now knows: "When you modify the auth flow, update the Serwist cache exclusion at `src/sw.ts:L23`." Integration intelligence no other tool provides.
+Ferris detects 8 significant dependencies, finds 5 co-import integration points. Generates a consolidated stack skill. The agent now knows: "When you modify the auth flow, update the Serwist cache exclusion at `src/sw.ts:L23`." That integration detail isn't available from any other tool in the [comparison table](/#how-skf-compares).
 
 ### Pre-Code Architecture Verification — Greenfield Confidence
 
-Jordan is designing a new TypeScript backend with Hono + Drizzle + SpacetimeDB. Architecture doc written, but no code yet. Wants to verify the stack works before building.
+Gery, a backend architect, is designing a new TypeScript service on Hono + Drizzle + SpacetimeDB. Architecture doc is written but no code exists yet — he wants to verify the stack holds together before anyone starts building.
 
 ```
 @Ferris QS hono          # Quick Skill per library
@@ -140,7 +161,7 @@ Jordan is designing a new TypeScript backend with Hono + Drizzle + SpacetimeDB.
 @Ferris SS               # Stack Skill — compose-mode (no codebase needed)
 ```
 
-VS finds a Risky integration between Drizzle and SpacetimeDB (incompatible query models) and returns CONDITIONALLY FEASIBLE. Jordan adds a bridge layer to the architecture, re-runs VS → FEASIBLE. RA fills in verified API signatures. SS compose-mode synthesizes the stack skill from existing skills + refined architecture. The agent now has integration intelligence for a project that doesn't have code yet.
+VS flags the Drizzle↔SpacetimeDB integration as incompatible (query-model mismatch) and returns CONDITIONALLY FEASIBLE. Gery adds a bridge layer to the architecture, re-runs VS → FEASIBLE. RA fills in verified API signatures. SS compose-mode synthesizes the stack skill from existing skills + refined architecture. The agent now has integration intelligence for a project that doesn't have code yet.
 
 ---
 
@@ -157,17 +178,17 @@ BMAD user starts a new project. [BMM](../bmad-synergy/#skf-and-bmm-phase-by-phas
 @Ferris EX    # Export — inject into platform context files
 ```
 
-Skills accumulate over sprints. Agent gets smarter every iteration.
+Skills accumulate over sprints. The agent's coverage improves each iteration.
 
 ### Scenario B: Multi-Repo Platform
 
-Alex needs cross-service knowledge for 10 microservices.
+Blondin, a platform lead, needs cross-service knowledge for 10 microservices so agents can navigate shared types and cross-calls.
 
 One forge project, multiple QMD collections, hub-and-spoke skills with integration patterns.
 
 ### Scenario C: External Dependency
 
-Developer needs skills for a library that doesn't have official skills.
+Kossi, a developer integrating an uncommon library, needs a skill for it — nothing official exists yet.
 
 ```
 @Ferris QS better-auth
@@ -177,21 +198,23 @@ Checks ecosystem first. If no official skill exists: generates from source. `sou
 
 ### Scenario D: Docs-Only (SaaS/Closed Source)
 
-No source code available — only documentation.
+No source code to clone — only API documentation. Example: you're integrating the [Stripe API](https://docs.stripe.com/api) and want your agent to know the real endpoints, parameters, and error codes instead of hallucinating from training data.
 
 ```
 @Ferris BS
 # When asked for target, provide documentation URLs:
-# https://docs.cognee.ai/v2/api/
+# https://docs.stripe.com/api/charges
+# https://docs.stripe.com/api/payment_intents
+# https://docs.stripe.com/api/errors
 # Ferris sets source_type: "docs-only" and collects doc_urls
-# When asked for target version, specify: 2.0.0
-# Ferris confirms your doc URLs match that version
+# When asked for target version, specify: 2025-04-30.basil
+# Ferris confirms your doc URLs match that API version
 @Ferris CS
-# step-03 skips (no source), step-03c fetches docs via doc_fetcher
+# step-03 skips (no source to clone), 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.
+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 `[EXT:url]` citations. No AST parsing is possible without source code — every instruction carries T3 provenance instead of T1, and the skill is tagged `source_authority: community` regardless of tier.
 
 ### Scenario E: Rename a Skill
 
@@ -222,13 +245,53 @@ You have `cognee` with versions 0.1.0, 0.5.0, and 0.6.0 (active). Version 0.1.0
 
 Version 0.6.0 remains active. Version 0.5.0 is untouched. The managed sections in CLAUDE.md/AGENTS.md no longer reference 0.1.0.
 
+### Scenario G: Maximum Accuracy for a High-Stakes Library
+
+You're building skills for a production payments library and need maximum citation density. Every signature must be AST-verified, and you want historical context (deprecations, migration notes) baked into the skill.
+
+**Workflow:**
+
+```
+@Ferris SF
+# Ferris detects installed tools and sets your tier automatically:
+# - Quick: no tools required (best-effort, source-read only)
+# - Forge: + ast-grep (T1 AST-verified signatures)
+# - Forge+: + cocoindex-code (semantic pre-ranking for large repos)
+# - Deep: + gh + qmd (T2 evidence — issues, PRs, changelogs)
+# Install the missing tools, then re-run @Ferris SF to promote your tier.
+@Ferris BS    # Scope — confirm the forge tier is Deep (+ ccc if installed)
+@Ferris CS    # Extract — AST + QMD enrichment
+@Ferris TS    # Completeness score — 80%+ threshold
+```
+
+**What you get:** Every signature carries `[AST:file:Lnn]` at T1. Deprecation warnings and design rationale carry `[QMD:collection:doc]` at T2. Install tooling once, every downstream skill benefits. See [Capability Tiers](../concepts/#capability-tiers-quickforgeforgedeep).
+
+### Scenario H: OSS Maintainer Publishing Official Skills
+
+You maintain an OSS library and want to ship official agent skills alongside each release — distributed via [skills.sh](https://skills.sh) or [oh-my-skills](https://github.com/armelhbobdad/oh-my-skills) so consumers install them with `npx skills add`.
+
+**Workflow:**
+
+```
+@Ferris BS    # Scope the skill — set source_authority: official in the brief
+@Ferris CS    # Compile — AST extraction + QMD enrichment (Deep tier recommended)
+@Ferris TS    # Verify completeness before publishing (target: 90%+)
+@Ferris EX    # Package for distribution — emits npx skills publish instructions
+```
+
+**What you get:** A verified skill pinned to the release commit, with `source_authority: official` surfaced in metadata as a trust signal so downstream tooling (and the ecosystem check in `@Ferris QS`) recognize it as maintainer-published rather than community-forged. Re-run `@Ferris maintain <skill>` (AS → US → TS → EX) on every release to keep published skills current.
+
 ---
 
 ## Tips & Tricks
 
+### Skip Permissions for Faster Forging
+
+> **Tip from Armel:** When forging skills with Claude Code, I run `claude --dangerously-skip-permissions` to bypass all permission prompts. SKF workflows only read source code, write to `skills/` and `forge-data/`, and call local tools (ast-grep, qmd, gh) — every step is auditable in the [open source](https://github.com/armelhbobdad/bmad-module-skill-forge). Skipping permissions drastically reduces forge time: I start a pipeline, go [grab one of those coffees ☕ you keep offering](https://buymeacoffee.com/armelhbobdad), and come back to a completed workflow. Review the output at the end, not at every gate.
+
 ### Progressive Capability
 
-Start with Quick mode (no setup required), upgrade to Forge (install ast-grep), then Forge+ (install cocoindex-code for semantic discovery), then Deep (install QMD). Each tier builds on the previous — you never lose capability.
+Start with the Quick tier (no setup required), upgrade to Forge (install ast-grep), then Forge+ (install cocoindex-code for semantic discovery), then Deep (install QMD). Each tier builds on the previous — you never lose capability.
 
 ### Batch Operations
 
@@ -258,34 +321,12 @@ Generated skills automatically follow authoring best practices: third-person des
 
 If your source repo includes executable scripts (`scripts/`, `bin/`) or static assets (`templates/`, `schemas/`), SKF detects and packages them automatically with provenance tracking. Custom scripts you add to `scripts/[MANUAL]/` are preserved during updates — just like `<!-- [MANUAL] -->` markers in SKILL.md.
 
----
-
-## Troubleshooting
-
-### Common Issues
-
-**Forge reports ast-grep is unavailable**
-If setup-forge reports that ast-grep was not detected, install it to unlock Forge mode: <https://ast-grep.github.io>
-
-**"No brief found"**
-Run `@Ferris BS` first to create a skill brief, or use `@Ferris QS` for brief-less generation.
-
-**"Ecosystem check: official skill exists"**
-An official skill already exists for this package. Consider installing it with `npx skills add` instead of generating your own.
-
-**Quick mode skills have lower confidence**
-Quick mode reads source without AST analysis. Install ast-grep to upgrade to Forge mode for structural truth (T1 confidence).
+### Let the Health Check Run
 
-**Want semantic discovery for large codebases?**
-Install [cocoindex-code](https://github.com/cocoindex-io/cocoindex-code) to unlock Forge+ mode. CCC indexes your codebase and pre-ranks files by semantic relevance before AST extraction, improving coverage on projects with 500+ files.
+Every SKF workflow ends with a shared **health check** step where Ferris reflects on the session and offers to file friction, bugs, or gaps as GitHub issues (with your approval). Clean runs exit in one line — zero overhead. When something breaks, it's SKF's primary feedback channel, so **please let workflows run to completion**. If you had to cancel before the health check fired, ask Ferris to run it (`@Ferris please run the workflow health check for this session`) or [open an issue directly](https://github.com/armelhbobdad/bmad-module-skill-forge/issues/new/choose). See [Workflow Health Check](../workflows/#terminal-step-health-check) for details.
 
 ---
 
-## Getting More Help
+## Something not working?
 
-- 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-tier.yaml` in your forger sidecar for runtime configuration
-- Check module configuration in your BMAD settings
+See [Troubleshooting](../troubleshooting/) for common errors (ast-grep unavailable, "no brief found", ecosystem check messages) and how to resolve them. For general setup help, see [Getting Started → Need help?](../getting-started/#need-help).