bmad-module-skill-forge 0.6.0 → 0.7.1

package/README.md

@@ -76,7 +76,7 @@ You'll be prompted for project name, output folders, and IDE configuration. See
 2. **Generate your first skill:** `@Ferris QS <package-name>` — creates a verified skill in under a minute
 3. **Full quality path:** `@Ferris BS` then `@Ferris CS` — brief first, then compile for maximum accuracy
 
-See the [workflows docs](https://armelhbobdad.github.io/bmad-module-skill-forge/workflows/) for all 10 available workflows.
+See the [workflows docs](https://armelhbobdad.github.io/bmad-module-skill-forge/workflows/) for all 12 available workflows.
 
 ## Who Is This For?
 
@@ -90,7 +90,7 @@ See the [workflows docs](https://armelhbobdad.github.io/bmad-module-skill-forge/
 - **[Getting Started](https://armelhbobdad.github.io/bmad-module-skill-forge/getting-started/)** — Installation, prerequisites, and your first skill
 - **[Concepts](https://armelhbobdad.github.io/bmad-module-skill-forge/concepts/)** — Plain-English definitions of all key terms
 - **[How It Works](https://armelhbobdad.github.io/bmad-module-skill-forge/how-it-works/)** — Architecture, capability tiers, output format, and design decisions
-- **[Workflows](https://armelhbobdad.github.io/bmad-module-skill-forge/workflows/)** — All 10 workflows with commands and connection diagrams
+- **[Workflows](https://armelhbobdad.github.io/bmad-module-skill-forge/workflows/)** — All 12 workflows with commands and connection diagrams
 - **[Agents](https://armelhbobdad.github.io/bmad-module-skill-forge/agents/)** — Ferris: the AI agent that runs all SKF workflows
 - **[Examples](https://armelhbobdad.github.io/bmad-module-skill-forge/examples/)** — Real-world scenarios, tips, and troubleshooting
 

package/docs/agents.md

@@ -34,9 +34,9 @@ Ferris handles all SKF workflows. You always interact with Ferris — he switche
 
 | Mode | Behavior | Workflows |
 |------|----------|-----------|
-| **Architect** | Exploratory, structural, assembling | SF, AN, BS, CS, QS, SS |
+| **Architect** | Exploratory, structural, assembling | SF, AN, BS, CS, QS, SS, RA |
 | **Surgeon** | Precise, semantic diffing, preserves [MANUAL] | US |
-| **Audit** | Judgmental, drift reports, completeness scoring | AS, TS |
+| **Audit** | Judgmental, drift reports, completeness scoring | AS, TS, VS |
 | **Delivery** | Packaging, platform-aware, ecosystem-ready | EX |
 
 **Communication Style:**
@@ -58,7 +58,11 @@ CREATE:
   [BS] Brief Skill — Design a skill scope
   [CS] Create Skill — Compile a skill from brief
   [QS] Quick Skill — Fast skill, no brief needed
-  [SS] Stack Skill — Consolidated project stack skill
+  [SS] Stack Skill — Consolidated project stack skill (code-mode or compose-mode)
+
+VERIFY:
+  [VS] Verify Stack — Pre-code architecture feasibility check
+  [RA] Refine Architecture — Improve architecture with skill evidence
 
 MAINTAIN:
   [US] Update Skill — Regenerate after changes
@@ -68,8 +72,8 @@ MAINTAIN:
 DELIVER:
   [EX] Export Skill — Package for distribution
 
-[WS] Workflow Status
-[FM] Full Menu
+[WS] Workflow Status — Show current lifecycle position
+[KI] Knowledge Index — List available knowledge fragments
 ```
 
 **Memory:**

package/docs/concepts.md

@@ -5,7 +5,7 @@ description: Plain-English definitions of key Skill Forge terms — agent skills
 
 # Concepts
 
-This page defines the key terms you'll encounter in Skill Forge. Each one is explained in plain English with a concrete example.
+This page defines the key terms you'll encounter in Skill Forge, with concrete examples.
 
 ---
 
@@ -15,7 +15,7 @@ An agent skill is an instruction file that tells an AI agent how to use your cod
 
 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 `better-auth` tells your agent: "The function is `authClient.signIn.email()`, it takes `{ email: string, password: string }`, and it returns a `Promise<Session>`. Here's the source: `src/client.ts:L47`."
+**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.
 
 ---
 
@@ -24,10 +24,10 @@ Skills follow the [agentskills.io](https://agentskills.io) open standard, so the
 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
-- `[SRC:cognee/api/v1/session/__init__.py:L8]` — read from source code without AST verification
-- `[EXT:docs.cognee.ai/getting-started/quickstart]` — sourced from external documentation
-- `[QMD:cognee-temporal:issues.md]` — surfaced from indexed developer discourse
+- `[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)
+- `[QMD:cognee-temporal:issues.md]` — surfaced from indexed developer discourse (T2)
+- `[EXT:docs.cognee.ai/getting-started/quickstart]` — sourced from external documentation (T3)
 
 ---
 
@@ -35,12 +35,16 @@ Provenance means every instruction in a skill traces back to where it came from.
 
 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.
-- **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/Deep when ast-grep cannot parse a specific file.
-- **T2 — Evidence:** Found in issues, PRs, changelogs, or documentation within the repository. Reliable context, but not as definitive as code.
-- **T3 — External:** Pulled from external documentation or websites. Treated with caution and clearly marked.
+- **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-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-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]`.
 
-**Example:** A function signature is T1. A source-read export without AST verification is T1-low. A deprecation warning from a closed GitHub issue is T2. A usage example from a blog post is T3.
+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.
 
 ---
 
@@ -51,9 +55,9 @@ Your capability tier depends on which tools you have installed. Each tier builds
 - **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 [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** — Adds [GitHub CLI](https://cli.github.com) + [QMD](https://github.com/tobi/qmd). Requires ast-grep, gh, and QMD. SKF indexes knowledge for semantic search and performs GitHub repository exploration. Skills get enriched with historical context, deprecation warnings, and cross-reference intelligence.
+- **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.md) for the full technical treatment.
+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.
 
 ---
 

package/docs/examples.md

@@ -44,7 +44,7 @@ Provenance tags trace each instruction to its source:
 - `[EXT:url]` — sourced from external documentation
 - `[QMD:collection:doc]` — surfaced from indexed developer discourse (issues, PRs, changelogs)
 
-See [How It Works](../how-it-works.md) for the full output structure.
+See [How It Works](../how-it-works/) for the full output structure.
 
 **Full skill directory structure:**
 
@@ -113,6 +113,21 @@ Armel's full-stack project: Next.js + Serwist + SpacetimeDB + better-auth.
 
 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.
 
+### 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.
+
+```
+@Ferris QS hono          # Quick Skill per library
+@Ferris QS drizzle-orm
+@Ferris QS spacetimedb-sdk
+@Ferris VS               # Verify Stack — feasibility report
+@Ferris RA               # Refine Architecture — enrich with API evidence
+@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.
+
 ---
 
 ## Common Scenarios
@@ -172,7 +187,7 @@ Start with Quick mode (no setup required), upgrade to Forge (install ast-grep),
 
 ### Batch Operations
 
-Use `--batch` with `create-skill` and `test-skill` to process multiple skills at once. Progress is checkpointed — use `--continue` to resume if interrupted.
+Use `--batch` with `create-skill` to process multiple briefs at once. Progress is checkpointed — if interrupted, re-run `@Ferris CS --batch` and Ferris will resume automatically from where it left off.
 
 ### Stack Skills + Individual Skills
 
@@ -196,8 +211,8 @@ If your source repo includes executable scripts (`scripts/`, `bin/`) or static a
 
 ### Common Issues
 
-**"Forge halted: ast-grep not found"**
-Install ast-grep to unlock Forge mode: <https://ast-grep.github.io>
+**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.

package/docs/getting-started.md

@@ -11,7 +11,7 @@ Welcome to Skill Forge! This guide will help you get up and running.
 
 ## What This Module Does
 
-Skill Forge analyzes code repositories, documentation websites, and developer discourse to build verified instruction files ("skills") for AI agents. Instead of your agent guessing API calls from training data, it follows instructions where every function, type, and pattern traces back to its source — a file and line for code, a URL for documentation, an issue or PR for discourse. Skills comply with the [agentskills.io](https://agentskills.io) open standard and work across Claude, Cursor, Copilot, and other AI tools. See the [Concepts](../concepts.md) page for definitions of key terms.
+Skill Forge analyzes code repositories, documentation websites, and developer discourse to build verified instruction files ("skills") for AI agents. Instead of your agent guessing API calls from training data, it follows instructions where every function, type, and pattern traces back to its source — a file and line for code, a URL for documentation, an issue or PR for discourse. Skills comply with the [agentskills.io](https://agentskills.io) open standard and work across Claude, Cursor, Copilot, and other AI tools. See the [Concepts](../concepts/) page for definitions of key terms.
 
 ---
 
@@ -55,14 +55,15 @@ The installer detects the existing `_bmad/` directory and installs SKF alongside
 
 ## Prerequisites
 
-| 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> |
+| Tool                                                                   | Required For                                     | Install                                                |
+|------------------------------------------------------------------------|--------------------------------------------------|--------------------------------------------------------|
+| [Node.js](https://nodejs.org/) >= 22                                   | Installation, npx commands                       | <https://nodejs.org>                                   |
+| `gh` (GitHub CLI)                                                      | Required for Deep mode. Optional convenience in Quick/Forge/Forge+ for source access. | <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>             |
+| `ccc` (cocoindex-code semantic code search)                            | Forge+ mode                                      | <https://github.com/cocoindex-io/cocoindex-code>       |
+| `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. Security scanning via Snyk is optional and requires an Enterprise plan; it does not affect your tier level.
 
@@ -70,15 +71,16 @@ Don't worry if you don't have all tools — SKF detects what's available and set
 
 ## Configuration
 
-SKF has two install-time variables (defined in `src/module.yaml`) and one runtime preference:
+SKF has two install-time variables (defined in `src/module.yaml`), one Core Config variable inherited from BMad, and one runtime preference:
 
 | 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` |
+| `forge_data_folder`    | Where workspace artifacts are stored (VS reports, evidence)                                          | `{project-root}/forge-data` |
+| `output_folder`        | Where refined architecture documents are saved (used by RA workflow). *Inherited from BMad Core Config.* | Defined by BMad Core Config |
 | `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`.
+Runtime configuration (tool detection, tier, and collection state) is managed by the `setup-forge` workflow and persisted in `forge-tier.yaml`.
 
 ---
 
@@ -163,13 +165,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 — 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.
+Each tier builds on the previous one. Quick mode reads source files directly. Forge adds `ast-grep` for AST-verified structural truth. Forge+ adds `ccc` (cocoindex-code) to semantically rank source regions before AST extraction — on large codebases, this ensures the most relevant exports are discovered first. Deep adds `gh` + `qmd` for GitHub exploration and QMD knowledge search with historical context enrichment.
 
 ```
 @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 searching across your indexed skill artifacts.
+Ferris detects your tools and sets the highest tier where all required tools pass verification. With `ast-grep` + `gh` + `qmd`, you get Deep mode — every skill gets AST-verified signatures (T1) enriched with temporal context from issues, PRs, and changelogs (T2). Add `ccc` alongside those three for maximum capability: semantic discovery plus full knowledge search.
 
 ### I maintain an OSS library and want official skills
 
@@ -184,6 +186,19 @@ You want maximum quality with full provenance for distribution. Use the full pip
 
 Export with `source_authority: official`. Consumers get verified skills that update with each release.
 
+### I'm planning a new project and want to verify my tech stack works together
+
+You have an architecture document and want to verify feasibility before writing code. Generate skills for each library, run Verify Stack to check compatibility, refine the architecture with skill evidence, then compose a stack skill.
+
+```
+@Ferris CS    # or QS — generate a skill per library
+@Ferris VS    # Verify Stack — feasibility check against architecture
+@Ferris RA    # Refine Architecture — fill gaps with API evidence
+@Ferris SS    # Stack Skill — compose-mode activates automatically
+```
+
+VS produces a feasibility report (FEASIBLE / CONDITIONALLY FEASIBLE / NOT FEASIBLE). RA enriches your architecture doc with verified API details. SS compose-mode synthesizes a stack skill from existing skills + architecture — no codebase needed.
+
 ### A dependency shipped breaking changes
 
 Your existing skill is now out of date. Audit detects the drift, Update regenerates while preserving your manual additions.
@@ -199,19 +214,19 @@ Your existing skill is now out of date. Audit detects the drift, Update regenera
 Your source repo has CLI tools, setup scripts, or config templates that agents should use. SKF detects and packages them automatically.
 
 ```
-@Ferris BS    # Brief — set scripts_intent: detect
+@Ferris BS    # Brief — scripts/assets auto-detected by default
 @Ferris CS    # Create — scripts/ and assets/ auto-detected
 ```
 
-Scripts from `scripts/`, `bin/`, and `tools/` directories are copied with provenance. Config templates and schemas from `assets/`, `templates/`, and `schemas/` are included. Custom files you add to `scripts/[MANUAL]/` survive updates.
+Scripts from `scripts/`, `bin/`, `tools/`, and `cli/` directories are copied with provenance. Config templates and schemas from `assets/`, `templates/`, `schemas/`, `configs/`, and `examples/` are included. Custom files you add to `scripts/[MANUAL]/` survive updates.
 
 ---
 
 ## What's Next?
 
-- Check out the [Agents Reference](../agents.md) to learn about Ferris
-- Browse the [Workflows Reference](../workflows.md) to see all available commands
-- See [Examples](../examples.md) for real-world usage scenarios
+- Check out the [Agents Reference](../agents/) to learn about Ferris
+- Browse the [Workflows Reference](../workflows/) to see all available commands
+- See [Examples](../examples/) for real-world usage scenarios
 
 ---
 

package/docs/how-it-works.md

@@ -5,7 +5,7 @@ description: How Skill Forge works — the BMad framework, architecture, output
 
 # How It Works
 
-This page is for people who want to understand how SKF works under the hood. It covers the BMad framework, workflow architecture, capability tiers, output format, tool ecosystem, and key design decisions. For plain-English definitions of key terms, see [Concepts](../concepts.md).
+This page is for people who want to understand how SKF works under the hood. It covers the BMad framework, workflow architecture, capability tiers, output format, tool ecosystem, and key design decisions. For definitions of key terms, see [Concepts](../concepts/).
 
 ---
 
@@ -29,13 +29,18 @@ 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)                      |
+| `workflow.md`             | Human-readable entry point — goals, role definition, initialization sequence, routes to first step                   | Entry point per workflow                          |
+| `steps-c/*.md`            | **Create** steps — primary execution, 5–11 sequential files per workflow                                            | 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              |
+
+**Module-level shared files** (not per-workflow — loaded by the agent or referenced across workflows):
+
+| File                      | What it does                                                                                                        | When it loads                                     |
+|---------------------------|---------------------------------------------------------------------------------------------------------------------|---------------------------------------------------|
+| `forger.agent.yaml`       | Expert persona — identity, principles, critical actions, menu of triggers                                           | First — always in context                         |
 | `skf-knowledge-index.csv` | Knowledge fragment index — id, name, tags, tier, file path                                                          | Read by steps to decide which fragments to load   |
-| `knowledge/*.md`          | 12 reusable fragments — cross-cutting principles and patterns (e.g., `zero-hallucination.md`, `confidence-tiers.md`, `ccc-bridge.md`) | Selectively read into context when a step directs |
+| `knowledge/*.md`          | 12 reusable fragments + overview.md index — cross-cutting principles and patterns (e.g., `zero-hallucination.md`, `confidence-tiers.md`, `ccc-bridge.md`) | Selectively read into context when a step directs |
 
 ```mermaid
 flowchart LR
@@ -44,7 +49,7 @@ flowchart LR
   W --> S[Step Files: steps-c/]
   S --> K[Knowledge Fragments<br/>skf-knowledge-index.csv → knowledge/*.md]
   S --> D[Data & Templates<br/>data/*.md, templates/*.md]
-  S --> O[Outputs: skills/reports<br/>when a step writes output]
+  S --> O[Outputs: skills/, forge-data/, sidecar<br/>when a step writes output]
 ```
 
 ### How It Works at Runtime
@@ -64,40 +69,41 @@ Ferris operates in four workflow-driven modes (mode is determined by which workf
 
 | 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       |
+| **Architect** | SF, AN, BS, CS, QS, SS, RA | Exploratory, assembling, refining — discovers structure, scopes skills, and improves architecture |
+| **Surgeon**   | US                 | Precise, semantic diffing — preserves [MANUAL] sections during regeneration |
+| **Audit**     | AS, TS, VS         | Judgmental, scoring — evaluates quality and detects drift   |
+| **Delivery**  | EX                 | Validates package, generates snippets, injects into context files |
 
 ---
 
 ## Why Another Tool?
 
-AI agents hallucinate APIs. Not sometimes — constantly. The table below shows why every existing approach fails at scale:
+AI agents guess API calls from training data. When the training data is wrong, outdated, or incomplete, they hallucinate — inventing function names, guessing parameter types, producing code that fails at runtime.
+
+Several approaches exist to address this, but each has a gap:
 
-| Approach | Strength | Fatal Flaw |
-|----------|----------|------------|
-| `npx skills init` | Format compliant | Empty shell. 0% intelligence. |
-| LLM Summarization | High semantic context | Hallucination. Guesses parameters. No grounding. |
-| RAG / Context stuffing | Good retrieval | Fragmented. Finds snippets, fails to synthesize. |
-| Manual Authoring | High initial quality | Drift. Doesn't scale. |
-| Copilot/Cursor built-in | Convenient | Generic. Doesn't know YOUR integration patterns. |
-| **Skill Forge** | **Structural truth + automation** | **Rigid. (Feature, not bug.)** |
+| 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 |
 
-SKF solves this by mechanically extracting function signatures, type definitions, and usage patterns from code repositories — and enriching them with documentation and developer discourse — then compiling everything into verifiable, version-pinned skills that comply with the [agentskills.io specification](https://agentskills.io/specification).
+SKF takes a different approach: it mechanically extracts function signatures, type definitions, and usage patterns from source code via AST parsing, enriches them with documentation and developer discourse, then compiles everything into version-pinned skills that comply with the [agentskills.io specification](https://agentskills.io/specification). Every instruction traces to its source — nothing is generated from training data.
 
 ---
 
 ## Progressive Capability Model
 
-SKF uses an additive tier model. Each tier is the previous tier plus one tool. You never lose capability by adding a tool.
+SKF uses an additive tier model. You never lose capability by adding a tool.
 
-| Tier | Tools | What You Get |
-|------|-------|-------------|
-| **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. |
-| **Forge+** | + `ccc_bridge` | Semantic discovery. CCC pre-ranks files by meaning before AST extraction. Better coverage on large codebases. |
-| **Deep** | + `gh_bridge` + `qmd_bridge` | Requires ast-grep + gh + QMD. Knowledge search. Temporal provenance. Drift detection. Full intelligence. |
+| Tier | Required Tools | What You Get |
+|------|---------------|-------------|
+| **Quick** | None (`gh_bridge`, `skill-check`, `tessl` used when available) | Source reading + spec validation + content quality review. Best-effort skills in under a minute. **Note:** Quick Skill (QS) is tier-unaware by design — it always runs at community tier regardless of installed tools. |
+| **Forge** | + `ast_bridge` (ast-grep) | Structural truth. AST-verified signatures. Co-import detection. T1 confidence. |
+| **Forge+** | + `ccc_bridge` (cocoindex-code) | Semantic discovery. CCC pre-ranks files by meaning before AST extraction. Better coverage on large codebases. |
+| **Deep** | `ast_bridge` + `gh_bridge` (gh) + `qmd_bridge` (QMD). CCC optional — enhances when installed. | Knowledge search. Temporal provenance. Drift detection. Full intelligence. |
 
 Setup detects your installed tools and sets your tier automatically:
 
@@ -109,7 +115,7 @@ Setup detects your installed tools and sets your tier automatically:
 Forge initialized. Tools: gh, ast-grep, ccc, QMD. Tier: Deep. Ready.
 ```
 
-Don't have ast-grep, cocoindex-code, or QMD yet? No problem — Quick mode works with just the GitHub CLI. Install tools later; your tier upgrades automatically.
+Don't have ast-grep, cocoindex-code, or QMD yet? No problem — Quick mode works with no additional tools. Optional GitHub CLI improves source access. Install tools later; your tier upgrades automatically.
 
 ### Tier Override — Comparing Output Across Tiers
 
@@ -162,7 +168,7 @@ Progressive disclosure controls how much context surfaces at each level:
 
 | Output | Content |
 |--------|---------|
-| `context-snippet.md` | T1-now only — compressed, always-on |
+| `context-snippet.md` | T1-now + T2-future gotchas (breaking changes, deprecation warnings) — compressed, always-on |
 | `SKILL.md` | T1-now + lightweight T2 annotations |
 | `references/` | Full temporal context with all tiers |
 
@@ -207,19 +213,25 @@ Skills follow the [agentskills.io specification](https://agentskills.io/specific
 
 ```yaml
 ---
-name: payment-service
+name: cognee
 description: >
-  Processes payments via REST API with token-based auth. Use when writing
-  payment integration code. NOT for: billing dashboards or reporting.
-  23 verified functions from github.com/org/payment-service.
+  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) or
+  integrating cognee-mcp. Covers the full public API, SearchType modes,
+  DataPoint custom models, pipeline tasks, and configuration for
+  LLM/embedding/vector/graph providers. Do NOT use for general knowledge graph
+  theory or unrelated Python libraries.
 ---
 ```
 
 Every instruction in the body traces to source:
 
-```
-Extracted: `getToken(userId: string, options?: TokenOptions): Promise<AuthToken>`
-[AST:src/auth/index.ts:L42]. Confidence: T1.
+```python
+await cognee.search(  # [AST:cognee/api/v1/search/search.py:L26]
+    query_text="What does Cognee do?"
+)
 ```
 
 ### metadata.json — The Birth Certificate
@@ -228,31 +240,27 @@ Machine-readable provenance for every skill:
 
 ```json
 {
-  "name": "payment-service",
-  "version": "2.1.0",
-  "skill_type": "individual",
-  "source_authority": "official",
-  "source_repo": "github.com/org/payment-service",
-  "source_commit": "a1b2c3d",
-  "forge_tier": "forge",
+  "name": "cognee",
+  "version": "0.5.5",
+  "skill_type": "single",
+  "source_authority": "community",
+  "source_repo": "https://github.com/topoteretes/cognee",
+  "source_root": "cognee/",
+  "source_commit": null,
+  "confidence_tier": "Deep",
   "spec_version": "1.3",
-  "generated_at": "2026-02-25T14:30:00Z",
+  "generation_date": "2026-03-20T16:55:00+04:00",
   "stats": {
-    "exports_documented": 23,
-    "exports_total": 23,
-    "coverage": 1.0,
-    "confidence_t1": 20,
-    "confidence_t2": 3,
-    "confidence_t3": 0,
-    "scripts_count": 1,
-    "assets_count": 1
-  },
-  "scripts": [
-    { "file": "scripts/validate.sh", "purpose": "Validates config schema", "confidence": "T1-low" }
-  ],
-  "assets": [
-    { "file": "assets/config-schema.json", "purpose": "Configuration JSON schema", "confidence": "T1-low" }
-  ]
+    "exports_documented": 22,
+    "exports_public_api": 22,
+    "exports_internal": 815,
+    "exports_total": 837,
+    "public_api_coverage": 1.0,
+    "total_coverage": 0.026,
+    "confidence_t1": 837,
+    "confidence_t2": 14,
+    "confidence_t3": 10
+  }
 }
 ```
 
@@ -281,37 +289,28 @@ The primary source is your project repo. Component references trace to library r
 
 ## Dual-Output Strategy
 
-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.
+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 79% for active skills alone.
 
 Every skill generates both:
 
 1. **SKILL.md** — Active skill loaded on trigger with full instructions
-2. **context-snippet.md** — Passive context, compressed index injected into CLAUDE.md
+2. **context-snippet.md** — Passive context, compressed index; injected into CLAUDE.md/AGENTS.md only when `export-skill` is run
 
 ### Managed CLAUDE.md Section
 
 Export injects a managed section between markers:
 
 ```markdown
-<!-- SKF:BEGIN updated:2026-02-25 -->
-[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:BEGIN updated:2026-03-20 -->
+[SKF Skills]|1 skill
+|IMPORTANT: Prefer documented APIs over training data.
+|
+[cognee v0.5.5]|root: skills/cognee/
+|IMPORTANT: cognee v0.5.5 — read SKILL.md before writing cognee code. Do NOT rely on training data.
+|quick-start:{SKILL.md#quick-start} — add → cognify → search async workflow
+|api: add(), cognify(), search(), memify(), config, datasets, prune, update(), session, SearchType, run_custom_pipeline(), visualize_graph()
+|key-types:{SKILL.md#key-types} — SearchType(14 modes: GRAPH_COMPLETION default, RAG_COMPLETION, CHUNKS, CYPHER, TEMPORAL...), Task, DataPoint
+|gotchas: all core functions are async (must await); delete() deprecated since v0.3.9 — use datasets.delete_data(); memify default pipeline changed to triplet embedding (Mar 2026)
 <!-- SKF:END -->
 ```
 
@@ -333,6 +332,8 @@ Export injects a managed section between markers:
 | **`qmd_bridge`** | QMD (local search) | BM25 keyword search, vector semantic search, collection indexing |
 | **`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. |
 
+Bridge names are **conceptual interfaces** used throughout workflow steps. Each bridge resolves to concrete MCP tools, CLI commands, or fallback behavior depending on the IDE environment. See [`src/knowledge/tool-resolution.md`](https://github.com/armelhbobdad/bmad-module-skill-forge/blob/main/src/knowledge/tool-resolution.md) for the complete resolution table.
+
 ### Conflict Resolution
 
 When tools disagree, higher priority wins for instructions. Lower priority is preserved as annotations:
@@ -390,10 +391,10 @@ Provenance maps enable verification: an `official` skill's provenance must trace
 |----------|-----------|
 | **Solo agent (Ferris), not multi-agent** | One domain (skill compilation) doesn't benefit from handoffs. Shared knowledge base (AST patterns, provenance maps) is the core asset. |
 | **Workflows drive modes, not conversation** | Ferris doesn't auto-switch based on question content. Invoke a workflow to change mode. Predictable behavior. |
-| **Hub-and-spoke cross-knowledge** | Each skill has one primary source. Cross-repo references use inline summary + pointer + `[XREF:repo:file:line]` provenance tag. |
+| **Hub-and-spoke cross-knowledge** | Each skill covers one source repository. Stack skills compose cross-library integration patterns in `references/integrations/`, citing each library's own skill. |
 | **Stack skill = compositional** | SKILL.md is the integration layer. references/ contains per-library + integration pairs. Partial regeneration on dependency updates. |
-| **Snippet updates only at export** | Create/update are draft operations. Export publishes to skills/ and CLAUDE.md. No half-baked snippets. |
-| **Bundle spec with opt-in update** | Offline-capable. 90-day staleness warning. `setup-forge --update-spec` fetches latest. |
+| **Snippet updates only at export** | Create/update write a draft `context-snippet.md` to `skills/`. Export regenerates the final `context-snippet.md` and publishes it to the platform context file (CLAUDE.md/AGENTS.md/.cursorrules). No managed-section updates in draft workflows. |
+| **Bundle spec with opt-in update** | Offline-capable. Run `@Ferris SF --update-spec` to fetch the latest agentskills.io spec on demand. |
 
 ---
 
@@ -420,7 +421,7 @@ src/
 │   └── README.md
 ├── knowledge/
 │   ├── skf-knowledge-index.csv
-│   └── *.md (12 fragments)
+│   └── *.md (12 knowledge fragments + overview.md index)
 └── workflows/
     ├── setup-forge/
     ├── analyze-source/
@@ -428,6 +429,8 @@ src/
     ├── create-skill/
     ├── quick-skill/
     ├── create-stack-skill/
+    ├── verify-stack/
+    ├── refine-architecture/
     ├── update-skill/
     ├── audit-skill/
     ├── test-skill/

package/docs/index.md

@@ -41,7 +41,7 @@ See the [Getting Started](./getting-started/) guide for full installation and us
 - **[Getting Started](./getting-started/)** — Installation, prerequisites, and your first skill
 - **[Concepts](./concepts/)** — Plain-English definitions of key terms (provenance, tiers, drift, and more)
 - **[How It Works](./how-it-works/)** — Architecture, capability model, output format, and design decisions
-- **[Workflows](./workflows/)** — All 10 workflows with commands and connection diagrams
+- **[Workflows](./workflows/)** — All 12 workflows with commands and connection diagrams
 - **[Agents](./agents/)** — Ferris: the AI agent that runs all SKF workflows
 - **[Examples](./examples/)** — Real-world scenarios, tips, and troubleshooting