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

package/docs/STABILITY.md

@@ -0,0 +1,123 @@
+---
+title: SKF Stability & Public API Contract
+description: What SemVer covers at v1.0.0 — the surfaces downstream consumers may pin against, and the surfaces explicitly excluded.
+---
+
+> **Status:** DRAFT — locks at v1.0.0 cut (Story 5.1 pre-flight audit). Review-window open until then.
+
+This document is the public API contract for `bmad-module-skill-forge` at v1.0.0. It enumerates exactly which SKF surfaces [Semantic Versioning 2.0.0](https://semver.org/) covers and which are explicitly `@internal`. The goal is that a downstream consumer pinning `"bmad-module-skill-forge": "^1.0.0"` can identify — unambiguously — whether a given SKF change is breaking, additive, or internal. Breaking changes to covered surfaces require a major-version bump; additive changes to covered surfaces are minor bumps; changes to `@internal` surfaces are free to land in any release.
+
+## Covered Surfaces
+
+The five buckets below are the entirety of the v1.0.0 public surface. Anything not explicitly listed here is `@internal` (see [§ @internal — Not Covered by SemVer](#internal--not-covered-by-semver)).
+
+### CLI Command Surface
+
+The CLI is invoked via `npx bmad-module-skill-forge <subcommand>` (one-shot) or `npm run skf:<subcommand>` (post-install). Covered:
+
+- **Subcommands**: `install`, `update`, `status`, `uninstall`. Renaming, removing, or changing the semantics of any subcommand is breaking.
+- **Options**: `-V, --version` (top-level; prints the installed package version), `-h, --help` (top-level and per-subcommand; prints help output — commander-provided). Both are covered.
+- **Per-subcommand flags (other than `-h/--help`)**: none are currently part of the v1.0.0 surface. Adding a new flag is additive (minor); removing or renaming a flag once added would be breaking.
+- **Exit codes**: `0` on success — including user-cancel of `install` (Ctrl-C at a prompt or explicit decline at a confirm step) and "nothing to do" paths on `uninstall`; `1` on unhandled failure. Only `0` and `1` are reserved today; introducing additional exit-code values in the future is additive (minor) and will be called out in `CHANGELOG.md`.
+- **`npm run skf:*` script aliases**: `skf:install`, `skf:update`, `skf:status`, `skf:uninstall` in `package.json` are the post-install convenience entry points. Renaming or removing any `skf:*` script is breaking. (Note: `release:*` scripts are NOT part of this contract — they are internal-to-maintainers and are being retired across Epic 4 and Epic 6.)
+
+### Programmatic API of `tools/cli/skf-cli.js`
+
+`tools/cli/skf-cli.js` is the CLI logic for `npx bmad-module-skill-forge` (invoked via a thin `bin` wrapper at `tools/skf-npx-wrapper.js` that execs `skf-cli.js`) and for `npm run skf:<subcommand>`. Though `package.json`'s `main` field points at `skf-cli.js`, it has **no programmatic export surface**. The file runs commander setup and calls `program.parse(process.argv)` as top-level side effects; it has no `module.exports` block. A `require('bmad-module-skill-forge')` from Node runs the CLI parser against the caller's `process.argv` — not a supported usage.
+
+Programmatic embedding of SKF is explicitly `@internal` at v1.0.0. If a programmatic API is ever added, it will be introduced via an explicit `module.exports` block and a minor version bump (additive).
+
+### Skill Manifest & Frontmatter Contract
+
+**`SKILL.md` frontmatter.** SKF-shipped `SKILL.md` files conform to the [agentskills.io minimal frontmatter spec](https://github.com/agentskills/agentskills). Required fields are `name` (kebab-case) and `description` (one-line natural-language summary that terminates with an explicit trigger phrase — see the `src/skf-*/SKILL.md` files in this repo for live examples). SKF does NOT extend the agentskills.io spec; there are no SKF-specific frontmatter fields. If the agentskills.io spec evolves, SKF tracks upstream rather than forking.
+
+**`bmad-skill-manifest.yaml` schema.** The agent-type skill manifest shape SKF uses is validated by a zod schema. A simplified transcription (see the live source on GitHub for exact error-map options and inline comments):
+
+```js
+const manifestSchema = z
+  .object({
+    type: z.enum(['agent', 'workflow', 'tool']),   // required
+    name: createNonEmptyString('name'),            // required
+    displayName: createNonEmptyString('displayName').optional(),
+    title: createNonEmptyString('title').optional(),
+    icon: z.string().optional(),
+    capabilities: z.string().optional(),
+    role: createNonEmptyString('role').optional(),
+    identity: createNonEmptyString('identity').optional(),
+    communicationStyle: createNonEmptyString('communicationStyle').optional(),
+    principles: createNonEmptyString('principles').optional(),
+    module: createNonEmptyString('module'),        // required
+  })
+  .strict();
+```
+
+The schema is strict — unknown keys are rejected. Renaming or removing a required field, changing an enum value, or tightening an optional field into required is breaking. Adding a new optional field is additive. The `module` field identifies the owning module — consumers writing agent-type manifests that ship with SKF set it to `skf`; the field is required and its expected value for SKF-owned manifests is part of the contract.
+
+### Installation Layout
+
+When a consumer runs `skf install` in a project, SKF creates or modifies the following on-disk paths (some names are configurable at install time; defaults are shown). Renaming any path, changing a path's semantics, or removing a path from this list is breaking.
+
+- `_bmad/skf/` — SKF module files.
+- `_bmad/_config/skf-manifest.yaml` — install manifest. Format per `tools/cli/lib/manifest.js`; covered top-level keys: `version` (equals the SKF package version at install time — downstream tooling may read it to detect the installed SKF version), `installed_at`, `action`, `module`, `skf_folder`, `ides`, `skills_output_folder`, `forge_data_folder`, `directories[]`, `files.{skf,sidecar,ide_skills,learning,output}`. Downstream tooling that introspects an SKF install (e.g. to detect installed IDEs or list installed skills) reads this file; its top-level shape is the v1.0.0 contract.
+- `_bmad/_memory/forger-sidecar/` — Ferris agent runtime state directory. The directory's existence and location are covered. File formats inside are `@internal` (not a downstream-consumable schema); `skf update` round-trips sidecar state between SKF versions — see `skf update` in [§ User-Facing Command Output Formats](#user-facing-command-output-formats) for the state-preservation commitment.
+- `_skf-learn/` — optional learning material; created only when the user opts into learning at install time.
+- `{skills_output_folder}/` — default `skills/`, configurable via install prompt and persisted to `skf-manifest.yaml`.
+- `{forge_data_folder}/` — default `forge-data/`, configurable via install prompt and persisted to `skf-manifest.yaml`.
+- `.gitignore` at project root — SKF appends `_bmad/_memory/` as an ignore entry (or creates the file if absent). Existing content is preserved; if the entry is already present, the file is left untouched. The appended entry name is part of the contract.
+- **Per-IDE skill directories.** SKF installs skills to each configured IDE's conventional skills directory. The IDE → directory mapping is enumerated in `tools/cli/lib/platform-codes.yaml` under `platforms.<ide>.installer.target_dir`; the `platforms.<ide>.installer.target_dir` mapping is part of the v1.0.0 contract (other keys in that file are `@internal`). Renaming `platforms.*` or `installer.target_dir` is breaking; removing a platform's `target_dir` is breaking for consumers of that IDE; adding a new platform entry is additive (minor).
+
+### User-Facing Command Output Formats
+
+The v1.0.0 contract commits to the **information each command outputs** and to **exit-code semantics**, not to exact human-readable wording, ANSI color choices, or console layout. Downstream tooling that needs structured introspection of an install should read `_bmad/_config/skf-manifest.yaml` directly (see [§ Installation Layout](#installation-layout)), which IS committed verbatim.
+
+- **`skf status`** SHALL convey: installation-present boolean, installed version string, forge-tier name (or a "not detected" equivalent), configured IDE list, workflow-skill count, sidecar state, and output-folder paths. Exit `0` on success; `1` on unhandled failure.
+- **`skf install`** SHALL exit `0` on successful install and on user-cancel (Ctrl-C at a prompt or explicit decline at a confirm step); `1` on unhandled failure. The success path SHALL emit a success confirmation.
+- **`skf update`** SHALL exit `0` on successful update and on "nothing to do" (no prior install detected); `1` on unhandled failure. `skf update` aims to preserve existing config and sidecar state across SKF versions; breaking migrations, when needed, will be called out in `CHANGELOG.md`.
+- **`skf uninstall`** SHALL exit `0` on successful removal, on "nothing to do" (no prior install detected), and on user-declined confirmation. Exit `1` on unhandled failure.
+
+Explicit non-commitments: ANSI color choices, exact prose wording, precise layout of tables or lists, and i18n prose variations are `@internal` and may change in minor releases.
+
+### Engine & Platform Compatibility
+
+SKF supports the Node.js major versions declared in `package.json` `engines.node` (currently `>=22.0.0`). Dropping a supported major is breaking; adding support for a new major is additive. Linux, macOS, and Windows are supported runtime platforms; dropping OS support is breaking. Adding support for a new platform is additive.
+
+## @internal — Not Covered by SemVer
+
+The following surfaces are explicitly excluded from the v1.0.0 contract. Changes to any of these may land in any release — patch, minor, or major — without constituting a "breaking change" from a SemVer perspective. Downstream consumers SHOULD NOT pin against these surfaces.
+
+- **`tools/cli/lib/*` internal helper modules** — implementation detail of the CLI; not a library. Any refactor that preserves the observable CLI surface and install layout above is allowed.
+- **Internal structure of workflow step files under `src/skf-*/steps-c/`** — the workflow authoring format is an SKF-internal authoring surface; step numbering, file names, and prose can change.
+- **`_bmad/_memory/forger-sidecar/*.yaml` file schemas** — Ferris sidecar state. Stable as a runtime contract between SKF versions during one install's lifetime (so `skf update` works), but not a downstream-consumable schema.
+- **Ferris agent persona prose and menu wording** — the in-product agent persona can be rephrased or restructured at any time.
+- **Exact chalk styling / ANSI color choices in command output** — stylistic; see the output-format bucket above for what IS committed.
+- **Internal logic of the `Installer` class in `tools/cli/lib/installer.js`** — private implementation; what's covered is the observable install layout, not how the files get there.
+- **Workflow `{communication_language}` / `{document_output_language}` template substitution** — an authoring convenience for workflow prose; the mechanism is internal.
+- **Knowledge-base contents under `src/knowledge/` and `src/skf-*/references/`** — evolving reference material, not a schema.
+- **Test fixtures and test file layout under `test/`** — test organization is internal (except `test/schema/**`, which defines schemas covered by [§ Skill Manifest & Frontmatter Contract](#skill-manifest--frontmatter-contract)).
+- **Build and docs tooling (`tools/build-docs.js`, `website/`)** — internal build pipeline for the Starlight docs site; not a consumer surface.
+- **`_bmad-output/` planning-artifact layout** — gitignored and never distributed; not shipped in the npm package.
+
+## How to Use This Contract
+
+Pin SKF as a dependency with caret-range major-version pinning to get minor and patch updates automatically:
+
+```json
+"bmad-module-skill-forge": "^1.0.0"
+```
+
+The caret range covers additive changes and internal refactors on covered surfaces, and any change on `@internal` surfaces. If you find that an SKF release broke a covered surface listed in this document, please open an issue at <https://github.com/armelhbobdad/bmad-module-skill-forge/issues> citing the relevant section — it is either a bug in SKF that needs reverting or a missed major-version bump.
+
+If a surface you depend on is NOT explicitly enumerated in [§ Covered Surfaces](#covered-surfaces), treat it as `@internal` — if in doubt, it is `@internal`. If you believe a surface should be promoted from `@internal` to covered, open an issue with a use-case description; promotion is additive and can land in a minor release.
+
+## Changes to This Contract
+
+Shrinking the covered surface (removing a commitment) is a breaking change and requires a major-version bump. Expanding the covered surface (promoting an `@internal` surface to covered, or adding a new commitment) is additive and ships in a minor release. This document is versioned alongside the package; historical versions are visible via `git log docs/STABILITY.md`.
+
+## References
+
+- [agentskills.io spec](https://github.com/agentskills/agentskills) — external canonical source for the `SKILL.md` frontmatter grammar.
+- [Semantic Versioning 2.0.0](https://semver.org/) — the SemVer semantics this contract commits to.
+- [`CHANGELOG.md`](https://github.com/armelhbobdad/bmad-module-skill-forge/blob/main/CHANGELOG.md) — release-by-release history; breaking changes are called out there.
+- [`docs/RELEASING.md`](RELEASING.md) — maintainer reference for the release pipeline (companion document: this file is about what ships, `RELEASING.md` is about how).
+- [`tools/cli/lib/platform-codes.yaml`](https://github.com/armelhbobdad/bmad-module-skill-forge/blob/main/tools/cli/lib/platform-codes.yaml) — source of truth for the IDE → skills-directory mapping covered under [§ Installation Layout](#installation-layout).
+- [`test/schema/agent.js`](https://github.com/armelhbobdad/bmad-module-skill-forge/blob/main/test/schema/agent.js) — zod schema definitions for `bmad-skill-manifest.yaml` covered under [§ Skill Manifest & Frontmatter Contract](#skill-manifest--frontmatter-contract).

package/docs/_data/pinned.yaml

@@ -0,0 +1,98 @@
+# Skill Forge — Pinned Canonical Anchors
+#
+# This file is the SINGLE SOURCE OF TRUTH for every version number, commit
+# SHA, and library reference that the docs cite about oh-my-skills, the
+# canonical SKF reference output.
+#
+# Every time a skill is recompiled in oh-my-skills, update the matching
+# entry here and then run `npm run validate:docs-drift` from the SKF repo
+# root. The script will:
+#
+#   1. Verify every skill below actually exists at the claimed version and
+#      commit in $OMS/skills/<name>/<version>/<name>/metadata.json
+#   2. Grep every docs/*.md for stale version strings and flag any that
+#      disagree with the anchors
+#
+# If the drift check fails after a recompilation, update this file first,
+# then fix the docs until the check is clean.
+#
+# Do NOT edit docs/*.md version references without updating this file
+# first — the drift check will catch you. That's the point.
+#
+# File ignored by Astro/Starlight content collections because the parent
+# directory starts with `_`. It is purely a build-time / CI-time anchor.
+
+# SKF package version — matches the `version` field in package.json
+skf_version: "0.10.0"
+
+# Path to the oh-my-skills repo, resolved relative to this repo's root.
+# Override at runtime with the OMS environment variable if oh-my-skills
+# lives elsewhere on your machine.
+oh_my_skills_path: "../oh-my-skills"
+
+# Every oms-* skill currently shipped in oh-my-skills. The library key
+# (e.g. cognee) is the user-facing library name; the entry key is the
+# skill package name (oms-<library>).
+skills:
+  oms-cognee:
+    library: cognee
+    version: "1.0.0"
+    source_repo: "https://github.com/topoteretes/cognee"
+    source_commit: "3c048aa4147776f14d4546704f986242554a9ef3"
+    source_ref: "v1.0.0"
+    upstream_commit_date: "2026-04-11"
+    test_score: 99.00
+    test_mode: "naive"
+    confidence_tier: "Deep"
+    source_authority: "community"
+    language: "python"
+
+  oms-cocoindex:
+    library: cocoindex
+    version: "0.3.37"
+    source_repo: "https://github.com/cocoindex-io/cocoindex"
+    source_commit: "87c5dbf087bfccca83791861db0d33519ef09677"
+    source_ref: "v0.3.37"
+    upstream_commit_date: "2026-03-31"
+    test_score: 99.0
+    test_mode: "naive"
+    confidence_tier: "Deep"
+    source_authority: "community"
+    language: "python"
+
+  oms-storybook-react-vite:
+    library: storybook
+    version: "10.3.5"
+    source_repo: "https://github.com/storybookjs/storybook"
+    source_commit: "e486d3826bcd40c52db1c766966d1c8ec16df6cb"
+    source_ref: "v10.3.5"
+    upstream_commit_date: "2026-04-07"
+    test_score: 99.49
+    test_mode: "naive"
+    confidence_tier: "Deep"
+    source_authority: "community"
+    language: "typescript"
+
+  oms-uitripled:
+    library: uitripled
+    version: "0.1.0"
+    source_repo: "https://github.com/moumen-soliman/uitripled"
+    source_commit: "a5ffb45be05335d2c547436664cfbfb8c22d04df"
+    source_ref: "HEAD"
+    upstream_commit_date: "2026-03-22"
+    test_score: 99.45
+    test_mode: "naive"
+    confidence_tier: "Deep"
+    source_authority: "community"
+    language: "typescript"
+
+# Libraries that are mentioned in docs as illustrative examples but don't
+# have a corresponding oms-* skill. The drift check IGNORES version
+# mentions for these libraries — they're allowed to drift because they're
+# illustration, not canonical.
+illustrative_libraries:
+  - better-auth
+  - hono
+  - drizzle-orm
+  - spacetimedb-sdk
+  - serwist

package/docs/agents.md

@@ -3,32 +3,28 @@ title: Agents
 description: Ferris agent reference — modes, capabilities, menu, and communication style
 ---
 
-# Agents Reference
-
-Ferris is the AI agent that runs all SKF workflows. You always interact with Ferris — he switches modes based on which workflow you invoke.
-
----
-
 ## Ferris — Skill Architect & Integrity Guardian
 
-**ID:** `_bmad/skf/agents/forger.md`
+**ID:** `skf-forger`
 **Icon:** ⚒️
 
 **Role:**
-Sole agent managing the entire skill compilation lifecycle. Ferris extracts, compiles, validates, and packages agent skills from code repositories, documentation, and developer discourse.
+The only agent in SKF. Manages the entire skill compilation lifecycle. Ferris extracts, compiles, validates, and packages agent skills from code repositories, documentation, and developer discourse.
 
 **When to Use:**
 Ferris handles all SKF workflows. You always interact with Ferris — he switches modes based on which workflow you invoke.
 
 **Key Capabilities:**
-- AST analysis via ast-grep for structural truth
+- AST-backed code extraction via ast-grep
 - 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
+- Cross-library 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
+- **Pipeline orchestration** — chain multiple workflows with automatic data forwarding and circuit breakers
+- **Headless mode** — skip confirmation gates for power users and batch operations (`--headless` or `-H`)
 
 **Workflow-Driven Modes:**
 
@@ -38,6 +34,7 @@ Ferris handles all SKF workflows. You always interact with Ferris — he switche
 | **Surgeon** | Precise, semantic diffing, preserves [MANUAL] | US |
 | **Audit** | Judgmental, drift reports, completeness scoring | AS, TS, VS |
 | **Delivery** | Packaging, platform-aware, ecosystem-ready | EX |
+| **Management** | Transactional rename/drop with platform context rebuild | RS, DS |
 
 **Communication Style:**
 - During work: structured reports with AST citations, no metaphor
@@ -72,9 +69,17 @@ MAINTAIN:
 DELIVER:
   [EX] Export Skill — Package for distribution
 
+MANAGE:
+  [RS] Rename Skill — Rename across all versions (transactional)
+  [DS] Drop Skill — Deprecate or purge a skill version
+
 [WS] Workflow Status — Show current lifecycle position
 [KI] Knowledge Index — List available knowledge fragments
 ```
 
+**Pipeline Aliases:**
+
+Ferris chains multiple workflows in one command via named aliases (`forge`, `forge-quick`, `onboard`, `maintain`). The full alias table, expansion rules, and target-resolution contract live in [Workflows → Pipeline Mode](../workflows/#pipeline-mode) — the canonical source. Example: `@Ferris forge-quick cognee` chains Quick → Test → Export with automatic data forwarding.
+
 **Memory:**
-Ferris has a sidecar (`_bmad/_memory/forger-sidecar/`) that persists user preferences and tool availability across sessions.
+Ferris has a sidecar (`_bmad/_memory/forger-sidecar/`) that persists user preferences and tool availability across sessions. Set `headless_mode: true` in preferences to make headless the default.

package/docs/architecture.md

@@ -0,0 +1,221 @@
+---
+title: Architecture
+description: How Skill Forge runs — the BMAD-backed agent and workflow engine, tool ecosystem, workspace artifacts, security, and the design decisions behind them.
+---
+
+Skill Forge runs entirely inside the LLM context window through structured instructions. There is no external orchestrator — just an agent persona (Ferris), a set of workflows, and a curated knowledge base. This page covers the machinery. For an end-to-end walkthrough, see [How It Works](../how-it-works/). For what a skill contains, see [Skill Model](../skill-model/).
+
+---
+
+## How BMAD Works
+
+[BMAD](https://docs.bmad-method.org/) tackles complex, open-ended work by decomposing it into **repeatable workflows**. Every workflow is a sequence of small, explicit steps, so the AI takes the same route on every run. A **shared knowledge base** of standards and patterns backs those steps, keeping outputs consistent instead of improvised. The formula is simple: **structured steps + shared standards = reliable results**.
+
+SKF plugs into BMAD the same way a specialist plugs into a team. It uses the same step-by-step workflow engine and shared standards, but focuses exclusively on skill compilation and quality assurance.
+
+---
+
+## Building Blocks
+
+Each workflow directory contains these files, and each has a specific job:
+
+| File                      | What it does                                                                                                        | When it loads                                     |
+|---------------------------|---------------------------------------------------------------------------------------------------------------------|---------------------------------------------------|
+| `SKILL.md`                | Human-readable entry point — goals, role definition, initialization sequence, invocation contract, routes to first step | Entry point per workflow                          |
+| `steps-c/*.md`            | **Create** steps — primary execution, 4–10 sequential files per workflow (the last one always chains to the shared health check) | One at a time (just-in-time)                      |
+| `references/*.md`         | Workflow-specific reference data — rules, patterns, protocols                                                       | Read by steps on demand                           |
+| `assets/*.md`             | Workflow-specific output formats — schemas, templates, heuristics                                                   | 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              |
+| `scripts/*.py`            | Deterministic Python scripts — scoring, validation, structural diffing, manifest operations                         | Invoked by steps via `uv run` for reproducible computation |
+
+**Module-level shared files** (not per-workflow — loaded by the agent or referenced across workflows):
+
+| File                      | What it does                                                                                                        | When it loads                                     |
+|---------------------------|---------------------------------------------------------------------------------------------------------------------|---------------------------------------------------|
+| `skf-forger/SKILL.md`     | Expert persona — identity, principles, critical actions, menu of triggers                                           | First — always in context                         |
+| `knowledge/skf-knowledge-index.csv` | Knowledge fragment index — id, name, tags, tier, file path                                                          | Read by steps to decide which fragments to load   |
+| `knowledge/*.md`          | 14 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 |
+| `shared/scripts/*.py`     | 7 cross-workflow Python scripts — preflight checks, manifest ops, managed-section rebuilds, frontmatter validation, severity classification, structural diffing, skill inventory | Invoked by any workflow that needs deterministic computation |
+
+```mermaid
+flowchart LR
+  U[User] --> A[Agent Persona]
+  A --> W[Workflow Entry: SKILL.md]
+  W --> S[Step Files: steps-c/]
+  S --> K[Knowledge Fragments<br/>skf-knowledge-index.csv → knowledge/*.md]
+  S --> D[References & Assets<br/>references/*.md, assets/*.md, templates/*.md]
+  S --> P[Scripts<br/>scripts/*.py, shared/scripts/*.py]
+  S --> O[Outputs: skills/, forge-data/, sidecar<br/>when a step writes output]
+```
+
+## Runtime flow
+
+1. **Trigger** — User types `@Ferris CS` (or fuzzy match like `create-skill`). The agent menu in `skf-forger/SKILL.md` maps the trigger to the workflow path.
+2. **Agent loads** — `skf-forger/SKILL.md` injects the persona (identity, principles, critical actions) into the context window. Sidecar files (`forge-tier.yaml`, `preferences.yaml`) are loaded for persistent state.
+3. **Workflow loads** — `SKILL.md` presents the mode choice and routes to the first step file.
+4. **Step-by-step execution** — Only the current step file is in context (just-in-time loading). Each step explicitly names the next one. The LLM reads, executes, saves output, then loads the next step. No future steps are ever preloaded.
+5. **Sub-agent delegation** — When a step needs to process large files (full `SKILL.md` documents, multiple `references/*.md` files, parallel per-library extraction), it spawns sub-agents via the Agent tool instead of loading the content into the parent context. Each sub-agent receives a file path, extracts a compact JSON summary, and returns it. Up to 8 sub-agents run concurrently. The parent collects JSON summaries without ever loading the full source — context isolation by design, preventing one step's data from bloating the window for the next. Used in TS (coverage check), RA (gap analysis), VS (integration verification), AS (structural diff), and SS (parallel extraction).
+6. **Knowledge injection** — Steps consult `skf-knowledge-index.csv` and selectively load fragments from `knowledge/` by tags and relevance. Cross-cutting principles (zero hallucination, confidence tiers, provenance) are loaded only when a step directs — not preloaded.
+7. **Reference and asset injection** — Steps read `references/*.md` and `assets/*.md` files as needed (rules, patterns, schemas, heuristics). This is deliberate context engineering: only the data relevant to the current step enters the context window.
+8. **Script execution** — Steps invoke deterministic Python scripts (`scripts/*.py`, `shared/scripts/*.py`) via `uv run` for computation that must be reproducible: scoring, structural diffing, manifest operations, frontmatter validation. The LLM prepares inputs, the script computes, the LLM uses the output. Same inputs always produce the same result.
+9. **Templates** — When a step produces output (e.g., a skill brief or test report), it reads the template file and fills in placeholders with computed results. The template provides consistent structure; the step provides the content.
+10. **Progress tracking** — Each step appends to an output file with state tracking. Resume mode reads this state and routes to the next incomplete step.
+
+## Ferris Operating Modes
+
+Ferris operates in five workflow-driven modes (mode is determined by which workflow is running, not conversation state):
+
+| Mode          | Workflows          | Behavior                                                    |
+|---------------|--------------------|-------------------------------------------------------------|
+| **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 |
+| **Management** | RS, DS            | Transactional rename/drop — copy-verify-delete with platform context rebuild |
+
+---
+
+## Tool Ecosystem
+
+### 7 Tools
+
+| Tool | Wraps | Purpose |
+|------|-------|---------|
+| **`gh_bridge`** | GitHub CLI (`gh`) | Source code access, issue mining, release tracking, PR intelligence |
+| **`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. |
+
+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:
+
+| 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` |
+
+### Manifest Detection
+
+Stack skill workflows detect project dependencies by scanning for manifest files. This isn't a tool — it's a reference pattern ([`skf-create-stack-skill/references/manifest-patterns.md`](https://github.com/armelhbobdad/bmad-module-skill-forge/blob/main/src/skf-create-stack-skill/references/manifest-patterns.md)) consulted by workflow steps:
+
+| Ecosystem | Manifest Files |
+|-----------|----------------|
+| JavaScript / TypeScript | `package.json` |
+| Python | `requirements.txt`, `setup.py`, `pyproject.toml`, `Pipfile` |
+| Rust | `Cargo.toml` |
+| Go | `go.mod` |
+| Java | `pom.xml`, `build.gradle` |
+| Ruby | `Gemfile` |
+| PHP | `composer.json` |
+| .NET | `*.csproj` |
+
+Detection runs at depth 0-1 from project root, excluding dependency trees (`node_modules/`, `.venv/`, `vendor/`), build output (`dist/`, `target/`, `__pycache__/`), and VCS directories.
+
+---
+
+## Workspace Artifacts
+
+Build artifacts are committable — another developer can reproduce the same skill:
+
+```
+forge-data/{skill-name}/
+├── skill-brief.yaml        # Compilation config (version-independent)
+└── {version}/
+    ├── provenance-map.json     # Source map with AST bindings
+    ├── evidence-report.md      # Build audit trail
+    └── extraction-rules.yaml   # Language-specific ast-grep schema
+```
+
+The `provenance-map.json` includes per-export `entries` with a `source_library` field identifying which library each export belongs to. For stack skills, it also includes an `integrations` array (cross-library patterns) and a `constituents` array (compose-mode only — tracks the compose-time snapshot of each source skill for staleness detection via metadata hash comparison). The `file_entries` array handles script/asset file-level provenance (SHA-256 hashes, source paths).
+
+### Pipeline Result Contracts
+
+Pipeline-facing workflows write a machine-readable result JSON file alongside their human-readable output. This enables reliable CI integration and pipeline chaining — downstream workflows or scripts can verify what the prior step produced without parsing markdown. Each run writes two files: a timestamped per-run record (`{skill-name}-result-{YYYYMMDD-HHmmss}.json`) that preserves the full audit trail across retries and aborts, and a stable `{skill-name}-result-latest.json` copy that pipeline consumers read without enumerating timestamps. The schema follows a consistent format: `skill`, `status` (success/failed/partial), `timestamp`, `outputs` (array of produced artifacts with type and path), and a skill-specific `summary` object.
+
+`skills/` and `forge-data/` are committed. Agent memory (`_bmad/_memory/forger-sidecar/`) is gitignored.
+
+---
+
+## Knowledge Base
+
+SKF relies on a curated skill compilation knowledge base:
+
+- Index: [`src/knowledge/skf-knowledge-index.csv`](https://github.com/armelhbobdad/bmad-module-skill-forge/blob/main/src/knowledge/skf-knowledge-index.csv)
+- Fragments: [`src/knowledge/`](https://github.com/armelhbobdad/bmad-module-skill-forge/tree/main/src/knowledge)
+
+Workflows load only the fragments required for the current task to stay focused and compliant.
+
+---
+
+## Module Structure
+
+```
+src/
+├── skf-forger/               # Agent skill (SKILL.md + manifest)
+├── skf-setup/                # Setup skill (forge initialization)
+├── skf-analyze-source/
+├── skf-brief-skill/
+├── skf-create-skill/
+├── skf-quick-skill/
+├── skf-create-stack-skill/
+├── skf-verify-stack/
+├── skf-refine-architecture/
+├── skf-update-skill/
+├── skf-audit-skill/
+├── skf-test-skill/
+├── skf-export-skill/
+├── skf-rename-skill/
+├── skf-drop-skill/
+├── forger/
+│   ├── forge-tier.yaml
+│   ├── preferences.yaml
+│   └── README.md
+├── knowledge/
+│   ├── skf-knowledge-index.csv
+│   └── *.md (14 knowledge fragments + overview.md index)
+├── shared/                   # Cross-workflow resources
+├── module.yaml               # Module metadata (code, name, config vars)
+└── module-help.csv           # Skill menu for bmad-help integration
+```
+
+---
+
+## Security
+
+- All tool wrappers use array-style subprocess execution — no shell interpolation
+- Input sanitization: allowlist characters for repo names, file paths, patterns
+- File paths validated against project root (no directory traversal)
+- **Source code never leaves the machine.** All processing is local (AST, QMD, validation).
+- `doc_fetcher` informs users which URLs will be fetched externally before processing
+
+---
+
+## Ecosystem Alignment
+
+SKF produces skills compatible with the [agentskills.io](https://agentskills.io) ecosystem:
+
+- Full [specification](https://agentskills.io/specification) compliance
+- Distribution via [`npx skills add/publish`](https://www.npmjs.com/package/skills)
+- Compatible with [agentskills/agentskills](https://github.com/agentskills/agentskills) and [vercel-labs/skills](https://github.com/vercel-labs/skills)
+
+---
+
+## Appendix: Key Design Decisions
+
+| Decision | Rationale |
+|----------|-----------|
+| **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 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 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, version-pin at release** | Offline-capable. SKF ships with a vendored agentskills.io spec pinned at release time; spec drift is a maintainer concern handled at SKF release, not a runtime concern for users. |

package/docs/bmad-synergy.md

@@ -3,17 +3,13 @@ title: BMAD Synergy
 description: How SKF workflows pair with BMAD CORE phases and optional modules (BMM, TEA, BMB, GDS, CIS) — integration patterns, entry points, and artifact flow
 ---
 
-# Using SKF with BMAD
-
-This page is for people already using [BMAD](https://docs.bmad-method.org/) who want to know where SKF workflows plug in. It assumes you know what BMM phases are, what TEA does, and what a BMAD module is. If any of that is new, start with the [BMAD docs](https://docs.bmad-method.org/) and then come back.
-
-If you're new to SKF itself, read [Getting Started](../getting-started/) first. The rest of this page assumes you have SKF installed and have run `@Ferris SF`.
+This page builds on BMAD concepts (BMM phases, TEA, modules). New to BMAD? Start with the [BMAD docs](https://docs.bmad-method.org/) first. New to SKF? Read [Getting Started](../getting-started/) instead.
 
 ---
 
 ## Launcher Skills vs Content Skills
 
-A BMAD project that also uses SKF ends up with two different kinds of `SKILL.md` files living in the same platform skills directory (`.claude/skills/` for Claude Code, `.cursor/skills/` for Cursor, `.agents/skills/` for Copilot/Codex and similar). They look similar. They are not the same thing. This is the single most durable point of confusion, so get it straight up front.
+A BMAD project that also uses SKF ends up with two different kinds of `SKILL.md` files living in the same IDE skills directory. SKF supports 23 IDEs — Claude Code (`.claude/skills/`), Cursor (`.cursor/skills/`), GitHub Copilot (`.github/skills/`), Windsurf (`.windsurf/skills/`), Cline (`.cline/skills/`), Roo Code (`.roo/skills/`), Gemini CLI (`.gemini/skills/`), and 16 others — each with its own skill directory. See the [complete IDE → Context File mapping](https://github.com/armelhbobdad/bmad-module-skill-forge/blob/main/src/skf-export-skill/assets/managed-section-format.md) for the full list. They look similar. They are not the same thing. This is the single most durable point of confusion, so get it straight up front.
 
 | | BMAD launcher skill | SKF content skill |
 |---|---|---|
@@ -23,7 +19,7 @@ A BMAD project that also uses SKF ends up with two different kinds of `SKILL.md`
 | **Provenance** | Points to a BMAD workflow file inside `_bmad/` | Points to upstream repo commits, files, and line ranges |
 | **Example** | `bmad-create-prd/SKILL.md` loads a PRD workflow | `hono-4.6.0/SKILL.md` contains verified Hono API signatures |
 
-> BMAD skills *launch workflows*. SKF skills *are the workflows' output, frozen with citations*. Both coexist in the same platform skills directory on purpose.
+> BMAD skills *launch workflows*. SKF skills *are the workflows' output, frozen with citations*. Both coexist in the same IDE skills directory on purpose.
 
 When a BMAD agent runs a workflow, that workflow can consult SKF content skills for verified API knowledge. The two kinds of skills compose — they don't compete.
 
@@ -124,7 +120,7 @@ This retrospective → update loop is the pattern that [Scenario A in Examples](
 
 ## SKF with Optional BMAD Modules
 
-BMAD ships several [optional modules](https://docs.bmad-method.org/). Synergy with SKF ranges from very high (TEA) to none at all (CIS). This section is honest about both.
+BMAD ships several [optional modules](https://github.com/orgs/bmad-code-org/repositories). Synergy with SKF ranges from very high (TEA) to narrow (CIS). This section is honest about both.
 
 ### TEA — Test Architect
 
@@ -146,9 +142,9 @@ Two concrete integrations:
 - **Before Test Design / ATDD / Automate / Framework Scaffolding** — run `@Ferris CS` on whichever test library the strategy depends on (Playwright, Vitest, Pact, etc.). TEA's test-authoring agents then work against verified API surfaces instead of training-data approximations.
 - **Before Release Gate** — run `@Ferris AS` on the skills the gate cites. If the skill has drifted from the current source, the drift report itself becomes evidence the gate can act on, and `@Ferris US` closes the loop.
 
-### BMB — BMad Builder
+### BMB — BMAD Builder
 
-BMB authors extend BMAD with new agents, workflows, or entire modules. When a new module depends on third-party libraries, ship a verified companion skill alongside it:
+BMB authors extend BMAD with new agents, workflows, or entire modules. SKF itself was built using BMB — it's a living proof-of-concept for the BMAD module architecture. When a new module depends on third-party libraries, ship a verified companion skill alongside it:
 
 - During `module-builder`, run `@Ferris SS` on the module's declared stack. The resulting stack skill becomes part of the module's distribution — downstream users get both the BMAD module BMB built and the SKF content skill you compiled as its companion in a single install.
 
@@ -162,17 +158,19 @@ For narrative, character design, world-building, or genre research — no synerg
 
 ### CIS — Creative Intelligence Suite
 
-No direct synergy. CIS covers ideation, brainstorming, innovation strategy, and storytelling — phases with no code to verify. SKF's whole value proposition is turning code and docs into evidence-backed skills, and CIS operates upstream of any of that. Use CIS for the creative work, then bring SKF in once you're producing concrete technical artifacts.
+Narrow but real synergy during the **brief-skill** phase. CIS's brainstorming coach, advanced elicitation, and party mode can sharpen scope decisions before compilation begins — especially when briefing a skill for a library you don't know well, or when multiple stakeholders disagree on what the skill should cover. The [oh-my-skills](https://github.com/armelhbobdad/oh-my-skills) repository uses BMAD Core + CIS alongside SKF: when briefing [`oms-storybook-react-vite`](https://github.com/armelhbobdad/oh-my-skills/blob/main/forge-data/oms-storybook-react-vite/skill-brief.yaml), CIS brainstorming, party mode, and advanced elicitation helped narrow a massive repo (Storybook supports Next.js, Astro, SvelteKit, and more — with extensive documentation for each) down to an accurate brief scoped specifically to React + Vite.
+
+Beyond briefing, CIS and SKF don't overlap — CIS covers ideation, storytelling, and innovation strategy where there's no code to verify. Use CIS for the creative and strategic work, then bring SKF in once you're producing concrete technical artifacts.
 
 ---
 
 ## Delivery and Lifecycle in a BMAD Project
 
-`@Ferris EX` is the **only workflow that introduces new skill context** into `CLAUDE.md`, `AGENTS.md`, and `.cursorrules`. Create-skill and update-skill produce draft artifacts that never touch those files directly — nothing reaches an agent's passive context until it has been through the EX gate. See [How It Works](../how-it-works/) for the architectural rationale.
+`@Ferris EX` is the **only workflow that introduces new skill context** into the three context files that serve all 23 IDEs: `CLAUDE.md` (Claude Code), `.cursorrules` (Cursor), and `AGENTS.md` (the remaining 21 IDEs — GitHub Copilot, Windsurf, Cline, Roo Code, Gemini CLI, and others). Each IDE also has its own skill root directory where skill files are installed (e.g., `.windsurf/skills/`, `.roo/skills/`, `.gemini/skills/`). Create-skill and update-skill produce draft artifacts that never touch those files directly — nothing reaches an agent's passive context until it has been through the EX gate. See [Skill Model → Dual-Output Strategy](../skill-model/#dual-output-strategy) for the architectural rationale.
 
 This matters specifically in a BMAD project: you may have multiple BMAD modules, each with its own launcher skills, plus SKF content skills, all trying to contribute context. The write-guard means only verified, tested SKF skills ever reach an agent's passive context — nothing half-baked sneaks in. `@Ferris EX` injects managed sections that coexist cleanly with whatever BMAD's installer wrote in the same files.
 
-For long-running BMAD projects, `@Ferris RS` (rename) and `@Ferris DS` (drop) keep the skill inventory clean as libraries get swapped, versions get deprecated, or naming conventions evolve across sprints. Both *rebuild* the existing managed sections in `CLAUDE.md`, `AGENTS.md`, and `.cursorrules` so references stay consistent after a rename or drop — they never inject previously-unpublished content, so the EX gate still governs what initially enters those files.
+For long-running BMAD projects, `@Ferris RS` (rename) and `@Ferris DS` (drop) keep the skill inventory clean as libraries get swapped, versions get deprecated, or naming conventions evolve across sprints. Both *rebuild* the existing managed sections in those context files so references stay consistent after a rename or drop — they never inject previously-unpublished content, so the EX gate still governs what initially enters those files.
 
 ---