bmad-module-skill-forge 0.5.0 → 0.7.0

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`          | 10 reusable fragments — cross-cutting principles and patterns (e.g., `zero-hallucination.md`, `confidence-tiers.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,39 +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.
 
-| 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.)** |
+Several approaches exist to address this, but each has a gap:
 
-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).
+| 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 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. |
-| **Deep** | + `qmd_bridge` | 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:
 
@@ -105,10 +112,10 @@ Setup detects your installed tools and sets your tier automatically:
 ```
 
 ```
-Forge initialized. Tools: gh, ast-grep, QMD. Tier: Deep. Ready.
+Forge initialized. Tools: gh, ast-grep, ccc, QMD. Tier: Deep. Ready.
 ```
 
-Don't have ast-grep or QMD yet? No problem — Quick mode works with just the GitHub CLI. Install tools later; your tier upgrades automatically.
+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
 
@@ -128,10 +135,13 @@ This is useful for comparing skill quality across tiers for the same target:
 # 2. Change to tier_override: Forge
 @Ferris CS                # recompile at Forge tier — compare output
 
-# 3. Reset to tier_override: ~ (auto-detect)
+# 3. Change to tier_override: Forge+
+@Ferris CS                # recompile with semantic discovery — compare coverage
+
+# 4. Reset to tier_override: ~ (auto-detect)
 ```
 
-Set `tier_override` to `Quick`, `Forge`, or `Deep`. Set to `~` (null) to return to auto-detection. The override is respected by all tier-aware workflows (CS, SS, US, AS, TS).
+Set `tier_override` to `Quick`, `Forge`, `Forge+`, or `Deep`. Set to `~` (null) to return to auto-detection. The override is respected by all tier-aware workflows (CS, SS, US, AS, TS).
 
 ---
 
@@ -142,7 +152,8 @@ Every claim in a generated skill carries a confidence tier that traces to its so
 | Tier | Source | Tool | What It Means |
 |------|--------|------|---------------|
 | **T1** | AST extraction | `ast_bridge` | Current code, structurally verified. Immutable for that version. |
-| **T2** | QMD evidence / source reading | `qmd_bridge` / `gh_bridge` | Historical + planned context (issues, PRs, changelogs, docs). |
+| **T1-low** | Source reading | `gh_bridge` | Source-read without AST verification. Location correct, signature may be inferred. |
+| **T2** | QMD evidence | `qmd_bridge` | Historical + planned context (issues, PRs, changelogs, docs). |
 | **T3** | External documentation | `doc_fetcher` | External, untrusted. Quarantined. |
 
 ### Temporal Provenance
@@ -157,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 |
 
@@ -165,11 +176,12 @@ Progressive disclosure controls how much context surfaces at each level:
 
 Your forge tier limits what authority claims a skill can make:
 
-| Forge Tier | AST? | QMD? | Max Authority | Accuracy Guarantee |
-|-----------|------|------|---------------|-------------------|
-| Quick | No | No | `community` | Best-effort |
-| Forge | Yes | No | `official` | Structural (AST-verified) |
-| Deep | Yes | Yes | `official` | Full (structural + contextual + temporal) |
+| Forge Tier | AST? | CCC? | QMD? | Max Authority | Accuracy Guarantee |
+|-----------|------|------|------|---------------|-------------------|
+| Quick | No | No | No | `community` | Best-effort |
+| Forge | Yes | No | No | `official` | Structural (AST-verified) |
+| Forge+ | Yes | Yes | No | `official` | Structural + semantic discovery |
+| Deep | Yes | opt. (enhances when installed) | Yes | `official` | Full (structural + contextual + temporal) |
 
 ---
 
@@ -184,32 +196,42 @@ skills/{name}/
 ├── SKILL.md              # Active skill (loaded on trigger)
 ├── context-snippet.md    # Passive context (compressed, always-on)
 ├── metadata.json         # Machine-readable provenance
-└── references/           # Progressive disclosure
-    ├── {function-a}.md
-    ├── {function-b}.md
-    └── integrations/     # Stack skills only
-        ├── auth-db.md
-        └── pwa-auth.md
+├── references/           # Progressive disclosure
+│   ├── {function-a}.md
+│   └── {function-b}.md
+├── scripts/              # Executable automation (when detected in source)
+│   └── {script-name}.sh
+└── assets/               # Templates, schemas, configs (when detected in source)
+    └── {asset-name}.json
 ```
 
+The `scripts/` and `assets/` directories are optional — only created when the source repository contains executable scripts or static assets matching detection heuristics. Each file traces to its source via `[SRC:file:L1]` provenance citations with SHA-256 content hashes for drift detection. User-authored files go in `scripts/[MANUAL]/` or `assets/[MANUAL]/` subdirectories and are preserved during updates.
+
 ### SKILL.md Format
 
 Skills follow the [agentskills.io specification](https://agentskills.io/specification) with frontmatter:
 
 ```yaml
 ---
-name: payment-service
-version: 2.1.0
-description: Payment processing API skill — 23 verified functions
-author: org/payment-team
+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) 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
@@ -218,26 +240,32 @@ 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
+    "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
   }
 }
 ```
 
+`scripts` and `assets` arrays are optional — omitted entirely (not empty) when the source has no scripts or assets.
+
 ### Stack Skill Output
 
 Stack skills map how your dependencies interact — shared types, co-import patterns, integration points:
@@ -261,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 -->
 ```
 
@@ -301,7 +320,7 @@ Export injects a managed section between markers:
 
 ## Tool Ecosystem
 
-### 6 Tools
+### 7 Tools
 
 | Tool | Wraps | Purpose |
 |------|-------|---------|
@@ -309,6 +328,7 @@ Export injects a managed section between markers:
 | **`skill-check`** | [thedaviddias/skill-check](https://github.com/thedaviddias/skill-check) | Validation + auto-fix (`check --fix`), quality scoring (0-100), security scan, split-body, diff comparison |
 | **`tessl`** | [tessl](https://tessl.io) | Content quality review, actionability scoring, progressive disclosure evaluation, AI judge with suggestions |
 | **`ast_bridge`** | ast-grep CLI | Structural extraction, custom AST queries, co-import detection |
+| **`ccc_bridge`** | cocoindex-code | Semantic code search, project indexing, file discovery pre-ranking |
 | **`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. |
 
@@ -319,6 +339,7 @@ When tools disagree, higher priority wins for instructions. Lower priority is pr
 | Priority | Source | Tool |
 |----------|--------|------|
 | 1 (highest) | AST extraction | `ast_bridge` |
+| 1b | CCC discovery (pre-ranking) | `ccc_bridge` |
 | 2 | QMD evidence | `qmd_bridge` |
 | 3 | Source reading (non-AST) | `gh_bridge` |
 | 4 | External documentation | `doc_fetcher` |
@@ -344,6 +365,8 @@ forge-data/{skill-name}/
 └── extraction-rules.yaml   # Language-specific ast-grep schema
 ```
 
+The `provenance-map.json` includes a `file_entries` array for script/asset file-level provenance (SHA-256 hashes, source paths) alongside the export-level `entries` array.
+
 `skills/` and `forge-data/` are committed. Agent memory (`_bmad/_memory/forger-sidecar/`) is gitignored.
 
 ---
@@ -366,10 +389,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. |
 
 ---
 
@@ -396,7 +419,7 @@ src/
 │   └── README.md
 ├── knowledge/
 │   ├── skf-knowledge-index.csv
-│   └── *.md (10 fragments)
+│   └── *.md (12 knowledge fragments + overview.md index)
 └── workflows/
     ├── setup-forge/
     ├── analyze-source/
@@ -404,6 +427,8 @@ src/
     ├── create-skill/
     ├── quick-skill/
     ├── create-stack-skill/
+    ├── verify-stack/
+    ├── refine-architecture/
     ├── update-skill/
     ├── audit-skill/
     ├── test-skill/

package/docs/index.md

@@ -17,7 +17,7 @@ hero:
 
 ## What does Skill Forge do?
 
-AI agents hallucinate API calls. They invent function names, guess parameter types, and produce code that doesn't compile. Skill Forge fixes this by analyzing code repositories, documentation, and developer discourse — extracting real signatures and patterns and compiling them into verified instruction files that any AI agent can follow. Every instruction traces back to where it came from.
+AI agents hallucinate API calls. They invent function names, guess parameter types, and produce code that doesn't compile. Skill Forge fixes this by analyzing code repositories, documentation, and developer discourse — extracting real signatures and patterns and compiling them into verified instruction files that any AI agent can follow. Every instruction traces back to where it came from. Generated skills can also include executable scripts and static assets extracted from the source repository, each with full provenance tracking.
 
 ## Quick Install
 
@@ -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
 

package/docs/workflows.md

@@ -1,11 +1,11 @@
 ---
 title: Workflows
-description: All 10 SKF workflows with commands, steps, and connection diagram
+description: All 12 SKF workflows with commands, steps, and connection diagram
 ---
 
 # Workflows Reference
 
-SKF has 10 workflows. You trigger them by typing commands to [Ferris](../agents.md), the AI agent that runs everything. Each workflow handles a specific part of the skill lifecycle — from analyzing source code to packaging for distribution. If any terms are unfamiliar, see the [Concepts](../concepts.md) page for plain-English definitions.
+SKF has 12 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. If any terms are unfamiliar, see the [Concepts](../concepts/) page for definitions.
 
 ---
 
@@ -15,11 +15,11 @@ SKF has 10 workflows. You trigger them by typing commands to [Ferris](../agents.
 
 **Command:** `@Ferris SF`
 
-**Purpose:** Initialize forge environment, detect tools, set capability tier, verify QMD collection health.
+**Purpose:** Initialize forge environment, detect tools (ast-grep, ccc, gh, qmd), set capability tier, index project in CCC (Forge+), verify QMD collection health (Deep).
 
 **When to Use:** First time using SKF in a project. Run once per project.
 
-**Key Steps:** Detect tools → Determine tier → Write forge-tier.yaml → QMD hygiene (Deep)
+**Key Steps:** Detect tools + Determine tier → CCC index check (Forge+) → Write forge-tier.yaml → QMD + CCC registry hygiene (Deep/Forge+) → Status report
 
 **Agent:** Ferris (Architect mode)
 
@@ -33,7 +33,7 @@ SKF has 10 workflows. You trigger them by typing commands to [Ferris](../agents.
 
 **When to Use:** Before `Create Skill` when you want maximum control over what gets compiled.
 
-**Key Steps:** Gather intent → Analyze target → Define scope → Write skill-brief.yaml
+**Key Steps:** Gather intent → Analyze target → Define scope → Confirm brief → Write skill-brief.yaml
 
 **Agent:** Ferris (Architect mode)
 
@@ -47,7 +47,7 @@ SKF has 10 workflows. You trigger them by typing commands to [Ferris](../agents.
 
 **When to Use:** After Brief Skill, or with an existing skill-brief.yaml.
 
-**Key Steps:** Load brief → Ecosystem check → AST extract → QMD enrich → Compile → Validate → Generate
+**Key Steps:** Load brief → Ecosystem check → Extract (AST + scripts/assets) → QMD enrich (Deep) → Compile → Validate → Generate
 
 **Agent:** Ferris (Architect mode)
 
@@ -61,7 +61,7 @@ SKF has 10 workflows. You trigger them by typing commands to [Ferris](../agents.
 
 **When to Use:** After source code changes when an existing skill needs updating.
 
-**Key Steps:** Load existing → Detect changes → Re-extract → Merge (preserve MANUAL) → Validate → Write
+**Key Steps:** Load existing → Detect changes (incl. scripts/assets) → Re-extract → Merge (preserve MANUAL) → Validate → Write → Report
 
 **Agent:** Ferris (Surgeon mode)
 
@@ -87,11 +87,13 @@ SKF has 10 workflows. You trigger them by typing commands to [Ferris](../agents.
 
 **Command:** `@Ferris SS`
 
-**Purpose:** Consolidated project stack skill with integration patterns.
+**Purpose:** Consolidated project stack skill with integration patterns. Supports two modes: **code-mode** (analyzes a codebase) and **compose-mode** (synthesizes from existing skills + architecture document, no codebase required).
 
-**When to Use:** When you want your agent to understand your entire project stack — not just individual libraries.
+**When to Use:** When you want your agent to understand your entire project stack — not just individual libraries. Use code-mode for existing projects; compose-mode activates automatically after the VS → RA verification path when skills exist but no codebase is present.
 
-**Key Steps:** Detect manifests → Rank dependencies → Scope confirmation → Parallel extract → Detect integrations → Compile stack → Generate references
+**Key Steps (code-mode):** Detect manifests → Rank dependencies → Scope confirmation → Parallel extract → Detect integrations → Compile stack → Generate references
+
+**Key Steps (compose-mode):** Load existing skills → Confirm scope → Detect integrations from architecture doc → Compile stack → Generate references
 
 **Agent:** Ferris (Architect mode)
 
@@ -105,7 +107,9 @@ SKF has 10 workflows. You trigger them by typing commands to [Ferris](../agents.
 
 **When to Use:** Brownfield onboarding of large repos or multi-service projects.
 
-**Key Steps:** Scan project → Identify units → Map exports → Detect integrations → Recommend → Generate briefs
+**Key Steps:** Init → Scan project → Identify units → Map exports & detect integrations → Recommend → Generate briefs
+
+**Note:** Supports resume — if the session is interrupted mid-analysis, re-run `@Ferris AN` and Ferris will resume from where it left off.
 
 **Agent:** Ferris (Architect mode)
 
@@ -119,7 +123,7 @@ SKF has 10 workflows. You trigger them by typing commands to [Ferris](../agents.
 
 **When to Use:** To check if a skill has fallen out of date with its source code.
 
-**Key Steps:** Load skill → Re-index source → Structural diff → Semantic diff (Deep) → Classify severity → Report
+**Key Steps:** Load skill → Re-index source → Structural diff (incl. script/asset drift) → Semantic diff (Deep) → Classify severity → Report
 
 **Agent:** Ferris (Audit mode)
 
@@ -133,23 +137,53 @@ SKF has 10 workflows. You trigger them by typing commands to [Ferris](../agents.
 
 **When to Use:** After creating or updating a skill, before exporting.
 
-**Key Steps:** Load skill → Detect mode → Coverage check → Coherence check → Score → Gap report
+**Key Steps:** Load skill → Detect mode → Coverage check → Coherence check → External validation (skill-check, tessl) → Score → Gap report
+
+**Agent:** Ferris (Audit mode)
+
+---
+
+## Architecture Verification Workflows
+
+### Verify Stack (VS)
+
+**Command:** `@Ferris VS`
+
+**Purpose:** Pre-code stack feasibility verification. Cross-references generated skills against architecture and PRD documents with three passes: coverage, integration compatibility, and requirements.
+
+**When to Use:** After generating individual skills with CS/QS, before building a stack skill — to verify the tech stack can support the architecture.
+
+**Key Steps:** Load skills + docs → Coverage analysis → Integration verification → Requirements check → Synthesize verdict → Present report
 
 **Agent:** Ferris (Audit mode)
 
 ---
 
+### Refine Architecture (RA)
+
+**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.
+
+**When to Use:** After VS confirms feasibility, before running SS in compose-mode. Produces a refined architecture ready for stack skill composition.
+
+**Key Steps:** Load inputs → Gap analysis → Issue detection → Improvement detection → Compile refined doc → Present report
+
+**Agent:** Ferris (Architect mode)
+
+---
+
 ## Utility Workflows
 
 ### Export Skill (EX)
 
 **Command:** `@Ferris EX`
 
-**Purpose:** Package for distribution + platform-aware context injection into CLAUDE.md/AGENTS.md.
+**Purpose:** Validate package structure, generate context snippets, and inject managed sections into CLAUDE.md/AGENTS.md/.cursorrules.
 
-**When to Use:** When a skill is ready for distribution or CLAUDE.md integration.
+**When to Use:** When a skill is ready for CLAUDE.md/AGENTS.md integration. Also provides distribution instructions for `npx skills publish`.
 
-**Key Steps:** Load skill → Package → Generate snippet → Update CLAUDE.md → Token report → Summary
+**Key Steps:** Load skill → Validate package → Generate snippet → Update context file (CLAUDE.md/AGENTS.md/.cursorrules) → Token report → Summary
 
 **Agent:** Ferris (Delivery mode)
 
@@ -157,34 +191,48 @@ SKF has 10 workflows. You trigger them by typing commands to [Ferris](../agents.
 
 ## Workflow Connections
 
+**Standard path (code-mode):**
+
+```mermaid
+flowchart TD
+    SF[Setup Forge — one-time] --> AN[Analyze Source]
+    SF --> QS[Quick Skill]
+    SF --> SS_code[Stack Skill — code-mode]
+
+    AN --> BS[Brief Skill]
+    BS --> CS[Create Skill]
+    AN -->|direct| CS
+
+    CS --> TS[Test Skill — quality gate]
+    QS --> TS
+    SS_code --> TS
+
+    TS --> EX[Export Skill]
+    TS --> AS[Audit Skill]
+    AS --> US[Update Skill]
+    US --> TS
 ```
-                    setup-forge (one-time)
-                         │
-          ┌──────────────┼──────────────┐
-          │              │              │
-     analyze-source  quick-skill  create-stack-skill
-          │              │              │
-     brief-skill         │              │
-          │              │              │
-     create-skill        │              │
-          │              │              │
-          └──────┬───────┘──────────────┘
-                 │
-            test-skill (quality gate)
-                 │
-          ┌──────┼──────┐
-          │             │
-     export-skill  audit-skill
-                        │
-                   update-skill (loops back to test)
+
+**Pre-code verification path (compose-mode):**
+
+```mermaid
+flowchart TD
+    GEN["Create Skill | Quick Skill ×N<br/>(per library)"] --> VS[Verify Stack — feasibility report]
+    VS --> RA[Refine Architecture — refined doc]
+    RA --> SS_compose[Stack Skill — compose-mode]
+    SS_compose --> TS[Test Skill]
+    TS --> EX[Export Skill]
 ```
 
 ---
 
-## Build Priority
+## Workflow Categories
 
-| Phase | Workflows | Notes |
-|-------|-----------|-------|
-| 1a (Core Engine) | setup-forge, create-skill, test-skill, export-skill | Must build first |
-| 1b (Entry Points) | quick-skill, brief-skill, create-stack-skill | Complete v1.0 |
-| 2 (Lifecycle) | audit-skill, update-skill, analyze-source | Post-launch |
+| Category | Workflows | Description |
+|----------|-----------|-------------|
+| 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 |
+| Architecture Verification | VS, RA | Pre-code architecture feasibility and refinement |
+| 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) |