bmad-module-skill-forge 0.5.0 → 0.7.0

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
 
@@ -102,8 +102,9 @@ SKF builds on these excellent open-source tools:
 |--------------------------------------------------------------|--------------------------------------------------------------------|
 | [agentskills.io](https://github.com/agentskills/agentskills) | Skill specification and ecosystem standard                         |
 | [GitHub CLI](https://cli.github.com/)                        | Source code access and repository intelligence (all tiers)         |
-| [ast-grep](https://github.com/ast-grep/ast-grep)             | AST-based structural code extraction (Forge/Deep tiers)            |
+| [ast-grep](https://github.com/ast-grep/ast-grep)             | AST-based structural code extraction (Forge/Forge+/Deep tiers)     |
 | [ast-grep MCP](https://github.com/ast-grep/ast-grep-mcp)     | MCP server for memory-efficient AST queries (recommended)          |
+| [cocoindex-code](https://github.com/cocoindex-io/cocoindex-code) | Semantic code search and file discovery pre-ranking (Forge+ tier)  |
 | [QMD](https://github.com/tobi/qmd)                           | Local hybrid search engine for knowledge indexing (Deep tier)      |
 | [skill-check](https://github.com/thedaviddias/skill-check)   | Skill validation, auto-fix, quality scoring, and security scanning |
 | [Snyk Agent Scan](https://github.com/snyk/agent-scan)   | Security scanning for prompt injection and data exposure (optional) |

package/docs/agents.md

@@ -22,18 +22,21 @@ Ferris handles all SKF workflows. You always interact with Ferris — he switche
 
 **Key Capabilities:**
 - AST analysis via ast-grep for structural truth
+- Semantic code discovery via cocoindex-code for intelligent file pre-ranking
 - QMD knowledge search for temporal context and evidence
 - agentskills.io specification compliance and validation
 - GitHub source navigation and package-to-repo resolution
 - Cross-knowledge synthesis for stack skills and integration patterns
+- Skill authoring best practices enforcement (third-person voice, consistent terminology, discovery optimization)
+- Source-derived scripts and assets extraction with provenance tracking
 
 **Workflow-Driven Modes:**
 
 | 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:**
@@ -55,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
@@ -65,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,34 +24,40 @@ 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)
 
 ---
 
-## Confidence Tiers (T1/T2/T3)
+## 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.
-- **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 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.
 
 ---
 
-## Capability Tiers (Quick/Forge/Deep)
+## Capability Tiers (Quick/Forge/Forge+/Deep)
 
 Your capability tier depends on which tools you have installed. Each tier builds on the previous one:
 
-- **Quick** — GitHub CLI only. SKF reads source files and builds best-effort skills. Works in under a minute.
+- **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.
-- **Deep** — Adds [QMD](https://github.com/tobi/qmd). SKF indexes knowledge for semantic search. Skills get enriched with historical context, deprecation warnings, and cross-reference intelligence.
+- **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.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.
 
 ---
 
@@ -94,3 +100,19 @@ Ferris switches between four modes depending on which workflow is active: Archit
 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.
+
+---
+
+## 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.

package/docs/examples.md

@@ -44,7 +44,25 @@ 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:**
+
+```
+skills/cognee/
+├── SKILL.md              # What your agent reads
+├── context-snippet.md    # Compressed index for CLAUDE.md
+├── 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
+```
+
+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.
 
 ---
 
@@ -95,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
@@ -150,11 +183,11 @@ The brief's `doc_urls` field drives the doc_fetcher step. The agent uses whateve
 
 ### Progressive Capability
 
-Start with Quick mode (no setup required), upgrade to Forge (install ast-grep), then Deep (install QMD). Each tier builds on the previous — you never lose 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.
 
 ### 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
 
@@ -164,14 +197,22 @@ Stack skills focus on integration patterns. Individual skills focus on API surfa
 
 After each sprint's refactor, run `@Ferris US` to regenerate changed components. Export updates CLAUDE.md automatically. Skill generation becomes routine — like running tests.
 
+### Best Practices Built In
+
+Generated skills automatically follow authoring best practices: third-person descriptions for reliable agent discovery, consistent terminology, degrees-of-freedom matching (prescriptive for fragile operations, flexible for creative tasks), and table-of-contents headers in large reference files. Discovery testing recommendations are included in test reports.
+
+### Scripts & Assets
+
+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 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.
@@ -182,6 +223,9 @@ An official skill already exists for this package. Consider installing it with `
 **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).
 
+**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.
+
 ---
 
 ## Getting More Help

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.
@@ -194,13 +209,24 @@ Your existing skill is now out of date. Audit detects the drift, Update regenera
 @Ferris TS    # Verify the update
 ```
 
+### I want scripts and assets included in my skills
+
+Your source repo has CLI tools, setup scripts, or config templates that agents should use. SKF detects and packages them automatically.
+
+```
+@Ferris BS    # Brief — scripts/assets auto-detected by default
+@Ferris CS    # Create — scripts/ and assets/ auto-detected
+```
+
+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
 
 ---