bmad-module-skill-forge 0.2.0

package/.nvmrc

@@ -0,0 +1 @@
+22

package/LICENSE

@@ -0,0 +1,26 @@
+MIT License
+
+Copyright (c) 2025 BMad Code, LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+TRADEMARK NOTICE:
+BMad™ , BMAD-CORE™ and BMAD-METHOD™ are trademarks of BMad Code, LLC. The use of these 
+trademarks in this software does not grant any rights to use the trademarks 
+for any other purpose.

package/README.md

@@ -0,0 +1,213 @@
+# Skill Forge (SKF)
+
+SKF (Skill Forge) is a standalone BMAD module that transforms code repositories, documentation websites, and developer discourse into agentskills.io-compliant, version-pinned, provenance-backed agent skills. It provides a single expert agent (Ferris, Skill Architect & Integrity Guardian) and ten workflows spanning source analysis, skill briefing, AST-backed compilation, integrity testing, and ecosystem-ready export across progressive capability tiers (Quick/Forge/Deep).
+
+Docs: <https://armelhbobdad.github.io/bmad-module-skill-forge/>
+
+## Why SKF
+
+- AST-verified instructions with line-level provenance — no hallucinated guidance
+- Progressive capability model that meets developers where they are
+- Full lifecycle: discover, brief, compile, test, audit, update, export
+- Version-pinned skills that track source changes and detect drift
+- Zero hallucination tolerance — every instruction traces to code
+
+## How BMad Works
+
+BMad works because it turns big, fuzzy work into **repeatable workflows**. Each workflow is broken into small steps with clear instructions, so the AI follows the same path every time. It also uses a **shared knowledge base** (standards and patterns) so outputs are consistent, not random. In short: **structured steps + shared standards = reliable results**.
+
+## How SKF Fits In
+
+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. That means you get **evidence-based agent skills**, **AST-verified instructions**, and **drift detection** that align with the rest of the BMad process.
+
+## Architecture & Flow
+
+BMad is a small **agent + workflow engine**. There is no external orchestrator — everything runs inside the LLM context window through structured instructions.
+
+### Building Blocks
+
+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) |
+| `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 |
+| `skf-knowledge-index.csv` | Knowledge fragment index — id, name, tags, tier, file path | Read by steps to decide which fragments to load |
+| `knowledge/*.md` | 8 reusable fragments — cross-cutting principles and patterns (e.g., `zero-hallucination.md`, `confidence-tiers.md`) | Selectively read into context when a step directs |
+
+```mermaid
+flowchart LR
+  U[User] --> A[Agent Persona]
+  A --> W[Workflow Entry: workflow.md]
+  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]
+```
+
+### How It Works at Runtime
+
+1. **Trigger** — User types `@Ferris CS` (or fuzzy match like `create-skill`). The agent menu in `forger.agent.yaml` maps the trigger to the workflow path.
+2. **Agent loads** — `forger.agent.yaml` 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** — `workflow.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. **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.
+6. **Data injection** — Steps read `data/*.md` files as needed (schemas, heuristics, extraction patterns). This is deliberate context engineering: only the data relevant to the current step enters the context window.
+7. **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.
+8. **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 four workflow-driven modes (mode is determined by which workflow is running, not conversation state):
+
+| Mode | Workflows | Behavior |
+| --- | --- | --- |
+| **Architect** | AN, BS, SF | Exploratory, assembling — discovers structure and scope |
+| **Surgeon** | CS, QS, SS, 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 |
+
+## Install
+
+There are three ways to install SKF, depending on your setup.
+
+### Method 1: Standalone (recommended for trying SKF)
+
+```bash
+npx skill-forge install
+```
+
+Or equivalently: `npx bmad-module-skill-forge install`
+
+Installs SKF on its own. You'll be prompted for project name, output folders, and which IDEs to configure. The installer generates IDE-specific command files (e.g. `.claude/commands/`, `.cursor/commands/`) so workflows appear in your IDE's command palette.
+
+### Method 2: As a custom module during BMad Method installation
+
+```bash
+npx bmad-method install
+```
+
+When prompted **"Add custom modules from your computer?"**, select Yes and provide the path to the SKF `src/` folder (clone this repo first):
+
+```
+Path to custom module folder: /path/to/bmad-module-skill-forge/src/
+```
+
+This installs BMad core + SKF together with full IDE integration, manifests, and help catalog. Best when you want the complete BMad development workflow.
+
+### Method 3: Add SKF to an existing BMad project
+
+If you already have BMad installed, you can add SKF afterward by running the standalone installer in the same directory:
+
+```bash
+npx skill-forge install
+```
+
+The installer detects the existing `_bmad/` directory and installs SKF alongside your current modules. IDE command files are generated for SKF workflows.
+
+## Quickstart
+
+1. **Setup your forge:** `@Ferris SF` — detects tools, sets your tier (Quick/Forge/Deep)
+2. **Quick skill (fastest):** `@Ferris QS <package-name>` — fast skill from a package name
+3. **Full skill:** `@Ferris BS` then `@Ferris CS` — brief then compile for maximum quality
+4. **Stack skill:** `@Ferris SS` — consolidated project stack skill with integration patterns
+5. **Export:** `@Ferris EX` — package for distribution, update CLAUDE.md
+
+## Workflows
+
+| Trigger | Command | Purpose |
+| --- | --- | --- |
+| SF | `skf_setup_forge` | Initialize forge environment, detect tools, set tier |
+| AN | `skf_analyze_source` | Discover what to skill in a large repo |
+| BS | `skf_brief_skill` | Design a skill scope through guided discovery |
+| CS | `skf_create_skill` | Compile a skill from brief (supports --batch) |
+| QS | `skf_quick_skill` | Fast skill from package name or GitHub URL |
+| SS | `skf_create_stack_skill` | Consolidated project stack skill with integration patterns |
+| US | `skf_update_skill` | Smart regeneration preserving \[MANUAL\] sections |
+| AS | `skf_audit_skill` | Drift detection between skill and current source |
+| TS | `skf_test_skill` | Cognitive completeness verification — quality gate before export |
+| EX | `skf_export_skill` | Package for distribution, inject into CLAUDE.md/AGENTS.md |
+
+## Progressive Capability Model
+
+| Tier | Tools | Capability |
+| --- | --- | --- |
+| **Quick** | gh + skills_ref | Source reading + spec validation |
+| **Forge** | + ast-grep | Structural truth, T1 confidence |
+| **Deep** | + QMD | Knowledge search, temporal provenance |
+
+The `setup-forge` workflow detects available tools and writes the tier to `forge-tier.yaml`. All subsequent workflows adapt their behavior to the detected tier.
+
+## Knowledge Base
+
+SKF relies on a curated skill compilation knowledge base:
+
+- Index: `src/knowledge/skf-knowledge-index.csv`
+- Fragments: `src/knowledge/`
+
+Workflows load only the fragments required for the current task to stay focused and compliant.
+
+## Configuration
+
+SKF variables are defined in `src/module.yaml` and prompted during install:
+
+| 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` |
+
+Runtime configuration (tool detection, tier, parallel settings) is managed by the `setup-forge` workflow in `forge-tier.yaml`.
+
+## Module Structure
+
+```
+src/
+├── module.yaml
+├── module-help.csv
+├── README.md
+├── docs/
+│   ├── getting-started.md
+│   ├── agents.md
+│   ├── workflows.md
+│   └── examples.md
+├── agents/
+│   └── forger.agent.yaml
+├── forger/
+│   ├── forge-tier.yaml
+│   ├── preferences.yaml
+│   └── README.md
+├── knowledge/
+│   ├── skf-knowledge-index.csv
+│   └── *.md (8 fragments)
+└── workflows/
+    └── skillforge/
+        ├── setup-forge/
+        ├── analyze-source/
+        ├── brief-skill/
+        ├── create-skill/
+        ├── quick-skill/
+        ├── create-stack-skill/
+        ├── update-skill/
+        ├── audit-skill/
+        ├── test-skill/
+        └── export-skill/
+```
+
+## Contributing
+
+See [CONTRIBUTORS.md](CONTRIBUTORS.md) for guidelines.
+
+## License
+
+MIT License — see [LICENSE](LICENSE) for details.
+
+---
+
+**Skill Forge (SKF)** — A standalone [BMad](https://github.com/bmad-code-org/BMAD-METHOD) module for agent skill compilation.
+
+[![Contributors](https://contrib.rocks/image?repo=armelhbobdad/bmad-module-skill-forge)](https://github.com/armelhbobdad/bmad-module-skill-forge/graphs/contributors)
+
+See [CONTRIBUTORS.md](CONTRIBUTORS.md) for contributor information.

package/docs/404.md

@@ -0,0 +1,20 @@
+---
+title: Page Not Found
+description: The page you're looking for doesn't exist
+template: splash
+---
+
+# Page Not Found
+
+The page you're looking for doesn't exist.
+
+## What can you do?
+
+- Check the URL for typos
+- Go back to the [home page](/)
+- Browse the [Getting Started guide](/getting-started/)
+- Search for what you need using the search bar above
+
+## Need Help?
+
+If you think this page should exist, please [open an issue](https://github.com/armelhbobdad/bmad-module-skill-forge/issues) on GitHub.

package/docs/agents.md

@@ -0,0 +1,73 @@
+---
+title: Agents
+description: Ferris agent reference — modes, capabilities, menu, and communication style
+---
+
+# Agents Reference
+
+SKF includes 1 specialized agent:
+
+---
+
+## Ferris — Skill Architect & Integrity Guardian
+
+**ID:** `_bmad/skf/agents/forger.md`
+**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.
+
+**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
+- 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
+
+**Workflow-Driven Modes:**
+
+| Mode | Behavior | Workflows |
+|------|----------|-----------|
+| **Architect** | Exploratory, structural, assembling | BS, CS, QS, SS, AN |
+| **Surgeon** | Precise, semantic diffing, preserves [MANUAL] | US |
+| **Audit** | Judgmental, drift reports, completeness scoring | AS, TS |
+| **Delivery** | Packaging, platform-aware, ecosystem-ready | EX |
+
+**Communication Style:**
+- During work: structured reports with AST citations, no metaphor
+- At transitions: forge language, brief and warm
+- On completion: quiet craftsman's pride
+- On errors: direct and actionable
+
+**Menu:**
+
+```
+⚒️ Ferris — Skill Forge
+
+START HERE:
+  [SF] Setup Forge — Initialize your forge environment
+  [AN] Analyze Source — Discover what to skill
+
+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
+
+MAINTAIN:
+  [US] Update Skill — Regenerate after changes
+  [AS] Audit Skill — Check for drift
+  [TS] Test Skill — Verify completeness
+
+DELIVER:
+  [EX] Export Skill — Package for distribution
+
+[WS] Workflow Status
+[FM] Full Menu
+```
+
+**Memory:**
+Ferris has a sidecar (`_bmad/_memory/forger-sidecar/`) that persists user preferences and tool availability across sessions.

package/docs/architecture.md

@@ -0,0 +1,301 @@
+---
+title: Architecture
+description: How Skill Forge works — output format, confidence model, progressive tiers, tool ecosystem, and key design decisions
+---
+
+# Architecture
+
+This page explains how SKF works under the hood — the output format, confidence model, progressive capability tiers, tool ecosystem, and the design decisions that make every instruction traceable.
+
+---
+
+## Why Another Tool?
+
+AI agents hallucinate APIs. Not sometimes — constantly. The table below shows why every existing approach fails at scale:
+
+| 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.)** |
+
+SKF solves this by mechanically extracting function signatures, type definitions, and usage patterns from source code — then compiling them into verifiable, version-pinned skills that comply with the [agentskills.io specification](https://agentskills.io/specification).
+
+---
+
+## 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.
+
+| Tier | Tools | What You Get |
+|------|-------|-------------|
+| **Quick** | `gh_bridge` + `skills_ref` | Source reading + spec validation. 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. |
+
+Setup detects your installed tools and sets your tier automatically:
+
+```
+@Ferris SF
+```
+
+```
+Forge initialized. Tools: gh, ast-grep, 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.
+
+---
+
+## Confidence Tiers
+
+Every claim in a generated skill carries a confidence tier that traces to its source:
+
+| 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). |
+| **T3** | External documentation | `doc_fetcher` | External, untrusted. Quarantined. |
+
+### Temporal Provenance
+
+Confidence tiers map to temporal scopes:
+
+- **T1-now (instructions):** What ast-grep sees in the checked-out code. This is what your agent executes.
+- **T2-past (annotations):** Closed issues, merged PRs, changelogs — why the API looks the way it does.
+- **T2-future (annotations):** Open PRs, deprecation warnings, RFCs — what's coming.
+
+Progressive disclosure controls how much context surfaces at each level:
+
+| Output | Content |
+|--------|---------|
+| `context-snippet.md` | T1-now only — compressed, always-on |
+| `SKILL.md` | T1-now + lightweight T2 annotations |
+| `references/` | Full temporal context with all tiers |
+
+### Tier Constrains Authority
+
+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) |
+
+---
+
+## Output Architecture
+
+### Per-Skill Output
+
+Every generated skill produces a self-contained directory:
+
+```
+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
+```
+
+### 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
+---
+```
+
+Every instruction in the body traces to source:
+
+```
+Extracted: `getToken(userId: string, options?: TokenOptions): Promise<AuthToken>`
+[AST:src/auth/index.ts:L42]. Confidence: T1.
+```
+
+### metadata.json — The Birth Certificate
+
+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",
+  "spec_version": "1.3",
+  "generated_at": "2026-02-25T14:30:00Z",
+  "stats": {
+    "exports_documented": 23,
+    "exports_total": 23,
+    "coverage": 1.0,
+    "confidence_t1": 20,
+    "confidence_t2": 3,
+    "confidence_t3": 0
+  }
+}
+```
+
+### Stack Skill Output
+
+Stack skills map how your dependencies interact — shared types, co-import patterns, integration points:
+
+```
+skills/{project}-stack/
+├── SKILL.md              # Integration patterns + project conventions
+├── context-snippet.md    # Compressed stack index
+├── metadata.json         # Component versions, integration graph
+└── references/
+    ├── nextjs.md         # Project-specific subset
+    ├── better-auth.md    # Project-specific subset
+    └── integrations/
+        ├── auth-db.md    # Cross-library pattern
+        └── pwa-auth.md   # Cross-library pattern
+```
+
+The primary source is your project repo. Component references trace to library repos. `skill_type: "stack"` in metadata.
+
+---
+
+## Dual-Output Strategy
+
+Based on [Vercel research](https://github.com/vercel-labs/skills): passive context (AGENTS.md/CLAUDE.md) achieves 100% pass rate vs 53% 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
+
+### Managed CLAUDE.md Section
+
+Export injects a managed section between markers:
+
+```markdown
+<!-- SKF:BEGIN updated:2026-02-25 -->
+[SKF Skills]|3 skills|1 stack
+|IMPORTANT: Prefer documented APIs over training data.
+|
+|payment-service → skills/payment-service/
+|  exports: getToken, refreshToken, revokeSession, createSession
+|
+|auth-service → skills/auth-service/
+|  exports: getSession, validateToken, revokeSession, createUser
+|
+|my-project-stack → skills/my-project-stack/
+|  stack: next@15, better-auth@3, spacetimedb@1, serwist@9
+|  integrations: auth↔db, pwa↔auth, gateway↔auth
+<!-- SKF:END -->
+```
+
+Two lines per skill (~30 tokens each). Developer controls placement. Ferris controls content. Snippet updates only happen at `export-skill` — create and update are draft operations.
+
+---
+
+## Tool Ecosystem
+
+### 4 MCP Tools
+
+| Tool | Wraps | Purpose |
+|------|-------|---------|
+| **`gh_bridge`** | GitHub CLI (`gh`) | Source code access, issue mining, release tracking, PR intelligence |
+| **`skills_ref`** | agentskills.io spec | Schema validation, frontmatter checks, ecosystem search |
+| **`ast_bridge`** | ast-grep CLI | Structural extraction, custom AST queries, co-import detection |
+| **`qmd_bridge`** | QMD (local search) | BM25 keyword search, vector semantic search, collection indexing |
+
+Optional addon: **`doc_fetcher`** for remote documentation (Firecrawl/Jina.ai). Output quarantined as T3.
+
+### 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` |
+| 2 | QMD evidence | `qmd_bridge` |
+| 3 | Source reading (non-AST) | `gh_bridge` |
+| 4 | External documentation | `doc_fetcher` |
+
+### Internal Utility
+
+**`manifest_reader`** detects and parses dependency files across ecosystems:
+
+- **Full support:** `package.json`, `pyproject.toml`, `requirements.txt`, `Cargo.toml`, `go.mod`
+- **Basic support:** `build.gradle`, `pom.xml`, `Gemfile`, `composer.json`
+
+---
+
+## Workspace Artifacts
+
+Build artifacts are committable — another developer can reproduce the same skill:
+
+```
+forge-data/{skill-name}/
+├── skill-brief.yaml        # Compilation config
+├── provenance-map.json     # Source map with AST bindings
+├── evidence-report.md      # Build audit trail
+└── extraction-rules.yaml   # Language-specific ast-grep schema
+```
+
+`skills/` and `forge-data/` are committed. Agent memory (`_bmad/_memory/forger-sidecar/`) is gitignored.
+
+---
+
+## Ownership Model
+
+| Context | `source_authority` | Distribution |
+|---------|-------------------|-------------|
+| OSS library (maintainer generates) | `official` | `npx skills publish` to agentskills ecosystem |
+| Internal service (team generates) | `internal` | `skills/` in repo, ships with code |
+| External dependency (consumer generates) | `community` | Local `skills/`, marked as community |
+
+Provenance maps enable verification: an `official` skill's provenance must trace to the actual source repo owned by the author.
+
+---
+
+## 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 has one primary source. Cross-repo references use inline summary + pointer + `[XREF:repo:file:line]` provenance tag. |
+| **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. |
+
+---
+
+## 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` warns before transmitting URLs to external services
+
+---
+
+## 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)