bmad-module-skill-forge 0.2.0

package/docs/examples.md

@@ -0,0 +1,144 @@
+---
+title: Examples
+description: Real-world scenarios, tips, and troubleshooting for Skill Forge
+---
+
+# Examples & Use Cases
+
+This section provides practical examples for using SKF: Skill Forge.
+
+---
+
+## Example Workflows
+
+### Quick Skill — 47 Seconds
+
+Developer adds [cognee](https://github.com/topoteretes/cognee) to a Python project for AI memory management. Agent keeps hallucinating method signatures and config options.
+
+```
+@Ferris QS https://github.com/topoteretes/cognee
+```
+
+Ferris reads the repository, extracts the public API via source reading, validates against spec. Skill appears in `skills/cognee/`. Agent stops hallucinating. Forty-seven seconds. Done.
+
+### Brownfield Platform — 8 Minutes
+
+Alex's team adopts BMAD for 10 microservices (TypeScript, Go, Rust).
+
+```
+@Ferris SF          # Setup — Deep mode detected
+@Ferris AN          # Analyze — 10 services mapped
+@Ferris CS --batch  # Create — batch generation
+```
+
+10 individual skills + 1 platform stack skill. BMM architect navigates cross-service flows with verified knowledge.
+
+### Release Prep — Trust Builder
+
+Sarah prepares v3.0.0 with breaking changes.
+
+```
+@Ferris AS    # Audit — finds 3 renames, 1 removal, 1 addition
+@Ferris US    # Update — preserves [MANUAL] sections, adds annotations
+@Ferris TS    # Test — verify completeness
+@Ferris EX    # Export — package for npm release
+```
+
+Ships with npm release. Consumers upgrade — their agents use the correct function names. Zero hallucination tickets.
+
+### Stack Skill — Integration Intelligence
+
+Armel's full-stack project: Next.js + Serwist + SpacetimeDB + better-auth.
+
+```
+@Ferris SS
+```
+
+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.
+
+---
+
+## Common Scenarios
+
+### Scenario A: Greenfield + BMM Integration
+
+BMAD user starts a new project. BMM architect suggests skill generation after retrospective.
+
+```
+@Ferris BS    # Brief — scope the skill
+@Ferris CS    # Create — compile from brief
+@Ferris TS    # Test — verify completeness
+@Ferris EX    # Export — inject into CLAUDE.md
+```
+
+Skills accumulate over sprints. Agent gets smarter every iteration.
+
+### Scenario B: Multi-Repo Platform
+
+Alex needs cross-service knowledge for 10 microservices.
+
+One forge project, multiple QMD collections, hub-and-spoke skills with integration patterns.
+
+### Scenario C: External Dependency
+
+Developer needs skills for a library that doesn't have official skills.
+
+```
+@Ferris QS better-auth
+```
+
+Checks ecosystem first. If no official skill exists: generates from source. `source_authority: community`.
+
+### Scenario D: Docs-Only (SaaS/Closed Source)
+
+No source code available — only documentation.
+
+Generate from docs + QMD-indexed content. T2/T3 confidence only. `source_authority: community`.
+
+---
+
+## Tips & Tricks
+
+### 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.
+
+### 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.
+
+### Stack Skills + Individual Skills
+
+Stack skills focus on integration patterns. Individual skills focus on API surface. Use both together for maximum coverage.
+
+### The Loop
+
+After each sprint's refactor, run `@Ferris US` to regenerate changed components. Export updates CLAUDE.md automatically. Skill generation becomes routine — like running tests.
+
+---
+
+## Troubleshooting
+
+### Common Issues
+
+**"Forge halted: ast-grep not found"**
+Install ast-grep 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.
+
+**"Ecosystem check: official skill exists"**
+An official skill already exists for this package. Consider installing it with `npx skills add` instead of generating your own.
+
+**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).
+
+---
+
+## Getting More Help
+
+- Run `/bmad-help` — analyzes your current state and suggests what to do next
+  (e.g. `/bmad-help my batch creation failed halfway, how do I resume?`)
+- Run `@Ferris SF` to check your current tier and tool availability
+- Review `forge-config.yaml` for runtime configuration
+- Check module configuration in your BMAD settings

package/docs/getting-started.md

@@ -0,0 +1,198 @@
+---
+title: Getting Started
+description: Installation, prerequisites, first steps, and common use cases for Skill Forge
+---
+
+# Getting Started with SKF: Skill Forge
+
+Welcome to Skill Forge! This guide will help you get up and running.
+
+---
+
+## What This Module Does
+
+Skill Forge is an automated skill compiler for the AI agent ecosystem. It transforms code repositories, documentation websites, and developer discourse into agentskills.io-compliant, version-pinned, provenance-backed agent skills. Every instruction traces to actual code — zero hallucination tolerance.
+
+---
+
+## Installation
+
+There are three ways to install SKF, depending on your setup.
+
+### 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.
+
+### 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.
+
+### 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.
+
+---
+
+## Prerequisites
+
+| Tool                                                                   | Required For       | Install                     |
+|------------------------------------------------------------------------|--------------------|-----------------------------|
+| `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>  |
+| `qmd` (local hybrid search engine for markdown)                        | Deep mode          | <https://github.com/tobi/qmd> |
+
+Don't worry if you don't have all tools — SKF detects what's available and sets your tier automatically.
+
+---
+
+## First Steps
+
+### 1. Setup Your Forge
+
+```
+@Ferris SF
+```
+
+This detects your tools, sets your capability tier, and initializes the forge environment. You only need to do this once per project.
+
+### 2. Generate Your First Skill
+
+**Fastest path (Quick Skill):**
+```
+@Ferris QS https://github.com/bmad-code-org/BMAD-METHOD
+```
+
+Ferris reads the repository, extracts the public API, and generates a skill in under a minute.
+
+**Full quality path:**
+```
+@Ferris BS    # Brief — scope and design the skill
+@Ferris CS    # Create — compile from the brief
+@Ferris TS    # Test — verify completeness
+@Ferris EX    # Export — package for distribution
+```
+
+### 3. Stack Skill (for full projects)
+
+```
+@Ferris SS
+```
+
+Analyzes your project's dependencies and generates a consolidated stack skill with integration patterns.
+
+---
+
+## Common Use Cases
+
+### My agent keeps hallucinating API calls
+
+Your agent invents function signatures that don't exist. Generate a verified skill so it works from structural truth instead of guessing.
+
+```
+@Ferris QS https://github.com/org/library
+```
+
+The skill pins every function to its actual source location. Hallucinations stop.
+
+### I'm adopting a new library and need my agent to use it correctly
+
+You added a dependency but your agent doesn't know its API yet. Quick Skill resolves package names across npm, PyPI, and crates.io.
+
+```
+@Ferris QS cognee
+```
+
+Ferris resolves the package to its GitHub repo, extracts the public API, and generates a skill your agent can reference immediately.
+
+### I want my agent to understand my entire project stack
+
+Individual skills cover single libraries. Stack Skill maps how your dependencies interact — shared types, co-import patterns, integration points.
+
+```
+@Ferris SS
+```
+
+Ferris detects your manifests, ranks dependencies by significance, and generates a consolidated skill with cross-library integration patterns.
+
+### I'm onboarding a large existing codebase
+
+A brownfield repo with dozens of modules. You need to know what's worth skilling before you start.
+
+```
+@Ferris AN
+```
+
+Analyze Source scans the project, identifies skillable units, maps exports, and generates recommended briefs you can batch-create with `@Ferris CS --batch`.
+
+### I want the highest accuracy possible
+
+Quick mode reads source files. Forge mode adds AST parsing for structural truth. Deep mode goes further — QMD indexes your project's markdown (docs, changelogs, issues, migration guides) into searchable collections, then uses BM25 keyword search, vector semantic search, and LLM-powered re-ranking to surface context no other tool can find.
+
+```
+@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 hybrid search across your indexed documentation.
+
+### I maintain an OSS library and want official skills
+
+You want maximum quality with full provenance for distribution. Use the full pipeline with Deep mode for the richest output.
+
+```
+@Ferris BS    # Scope and design the skill
+@Ferris CS    # Compile — AST extraction + QMD enrichment (Deep)
+@Ferris TS    # Verify completeness before publishing
+@Ferris EX    # Package for distribution
+```
+
+Export with `source_authority: official`. Consumers get verified skills that update with each release.
+
+### A dependency shipped breaking changes
+
+Your existing skill is now out of date. Audit detects the drift, Update regenerates while preserving your manual additions.
+
+```
+@Ferris AS    # Find what changed
+@Ferris US    # Regenerate — [MANUAL] sections survive
+@Ferris TS    # Verify the update
+```
+
+---
+
+## 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
+
+---
+
+## Need Help?
+
+If you run into issues:
+1. Run `/bmad-help` — analyzes your current state and suggests what to do next
+   (e.g. `/bmad-help my quick skill has low confidence scores, how do I improve them?`)
+2. Run `@Ferris SF` to check your tool availability and tier
+3. Check `forge-config.yaml` for your current configuration

package/docs/index.md

@@ -0,0 +1,75 @@
+---
+title: Skill Forge (SKF)
+description: AST-verified, provenance-backed agent skills from code repositories, documentation, and developer discourse
+template: splash
+hero:
+  title: Skill Forge (SKF)
+  tagline: AST-verified, provenance-backed agent skills from code repositories, documentation, and developer discourse
+  actions:
+    - text: Getting Started
+      link: ./getting-started/
+      icon: right-arrow
+      variant: primary
+    - text: View on GitHub
+      link: https://github.com/armelhbobdad/bmad-module-skill-forge
+      icon: external
+---
+
+## What is Skill Forge?
+
+Skill Forge is an automated skill compiler for the AI agent ecosystem. It transforms code repositories, documentation, and developer discourse into [agentskills.io](https://agentskills.io)-compliant, version-pinned, provenance-backed agent skills. Every instruction traces to verifiable sources — zero hallucination tolerance.
+
+- **AST-Verified**: Structural truth via ast-grep — no guessing, no hallucination.
+- **Provenance-Backed**: Every claim traces to source code with file and line references.
+- **Progressive Tiers**: Quick (no setup) → Forge (ast-grep) → Deep (QMD knowledge).
+- **Ecosystem-First**: Checks for official skills before generating community ones.
+
+## Quick Install
+
+**Standalone:**
+
+```bash
+npx skill-forge install
+```
+
+**Or as a custom module with BMad Method** (for the full development workflow):
+
+```bash
+npx bmad-method install    # select "Add custom modules" and point to src/
+```
+
+Then interact with the forge agent:
+
+```
+@Ferris SF    # Setup your forge environment
+@Ferris QS    # Quick Skill — generate in under a minute
+```
+
+See the [Getting Started](./getting-started.md) guide for all installation methods.
+
+## Core Workflows
+
+| Workflow | Trigger | Purpose |
+|----------|---------|---------|
+| [Setup Forge](/workflows/#setup-forge-sf) | SF | Initialize forge, detect tools, set tier |
+| [Brief Skill](/workflows/#brief-skill-bs) | BS | Scope and design a skill |
+| [Create Skill](/workflows/#create-skill-cs) | CS | Compile a skill from a brief |
+| [Quick Skill](/workflows/#quick-skill-qs) | QS | Fast skill, no brief needed |
+| [Stack Skill](/workflows/#stack-skill-ss) | SS | Consolidated project stack skill |
+| [Update Skill](/workflows/#update-skill-us) | US | Regenerate after source changes |
+| [Audit Skill](/workflows/#audit-skill-as) | AS | Drift detection |
+| [Test Skill](/workflows/#test-skill-ts) | TS | Verify completeness |
+| [Export Skill](/workflows/#export-skill-ex) | EX | Package for distribution |
+| [Analyze Source](/workflows/#analyze-source-an) | AN | Discover what to skill |
+
+## Documentation
+
+- **[Getting Started](./getting-started.md)** — Installation, prerequisites, first steps
+- **[Architecture](./architecture.md)** — Output format, confidence model, tiers, tool ecosystem
+- **[Agents](./agents.md)** — Ferris agent: modes, capabilities, communication style
+- **[Workflows](./workflows.md)** — All 10 workflows with commands and connection diagram
+- **[Examples](./examples.md)** — Real-world scenarios, tips, and troubleshooting
+
+## Support
+
+- **Issues**: [GitHub Issues](https://github.com/armelhbobdad/bmad-module-skill-forge/issues)

package/docs/workflows.md

@@ -0,0 +1,190 @@
+---
+title: Workflows
+description: All 10 SKF workflows with commands, steps, and connection diagram
+---
+
+# Workflows Reference
+
+SKF includes 10 workflows organized by purpose:
+
+---
+
+## Core Workflows
+
+### Setup Forge (SF)
+
+**Command:** `@Ferris SF`
+
+**Purpose:** Initialize forge environment, detect tools, set capability tier, auto-index project.
+
+**When to Use:** First time using SKF in a project. Run once per project.
+
+**Key Steps:** Detect tools → Determine tier → Create forge-config.yaml → Auto-index (Deep)
+
+**Agent:** Ferris (Architect mode)
+
+---
+
+### Brief Skill (BS)
+
+**Command:** `@Ferris BS`
+
+**Purpose:** Scope and design a skill through guided discovery.
+
+**When to Use:** Before `Create Skill` when you want maximum control over what gets compiled.
+
+**Key Steps:** Gather intent → Analyze target → Define scope → Write skill-brief.yaml
+
+**Agent:** Ferris (Architect mode)
+
+---
+
+### Create Skill (CS)
+
+**Command:** `@Ferris CS`
+
+**Purpose:** Compile a skill from a brief. Supports `--batch` for multiple briefs.
+
+**When to Use:** After Brief Skill, or with an existing skill-brief.yaml.
+
+**Key Steps:** Load brief → Ecosystem check → AST extract → QMD enrich → Compile → Validate → Generate
+
+**Agent:** Ferris (Architect mode)
+
+---
+
+### Update Skill (US)
+
+**Command:** `@Ferris US`
+
+**Purpose:** Smart regeneration preserving `[MANUAL]` sections. Detects individual vs stack internally.
+
+**When to Use:** After source code changes when an existing skill needs updating.
+
+**Key Steps:** Load existing → Detect changes → Re-extract → Merge (preserve MANUAL) → Validate → Write
+
+**Agent:** Ferris (Surgeon mode)
+
+---
+
+## Feature Workflows
+
+### Quick Skill (QS)
+
+**Command:** `@Ferris QS <package-or-url>`
+
+**Purpose:** Brief-less fast skill with package-to-repo resolution.
+
+**When to Use:** When you need a skill quickly — no brief needed. Accepts package names or GitHub URLs.
+
+**Key Steps:** Resolve target → Ecosystem check → Quick extract → Compile → Validate → Write
+
+**Agent:** Ferris (Architect mode)
+
+---
+
+### Stack Skill (SS)
+
+**Command:** `@Ferris SS`
+
+**Purpose:** Consolidated project stack skill with integration patterns.
+
+**When to Use:** When you want your agent to understand your entire project stack — not just individual libraries.
+
+**Key Steps:** Detect manifests → Rank dependencies → Scope confirmation → Parallel extract → Detect integrations → Compile stack → Generate references
+
+**Agent:** Ferris (Architect mode)
+
+---
+
+### Analyze Source (AN)
+
+**Command:** `@Ferris AN`
+
+**Purpose:** Decomposition engine — discover what to skill, recommend stack skill.
+
+**When to Use:** Brownfield onboarding of large repos or multi-service projects.
+
+**Key Steps:** Scan project → Identify units → Map exports → Detect integrations → Recommend → Generate briefs
+
+**Agent:** Ferris (Architect mode)
+
+---
+
+### Audit Skill (AS)
+
+**Command:** `@Ferris AS`
+
+**Purpose:** Drift detection between skill and current source.
+
+**When to Use:** To check if a skill has fallen out of date with its source code.
+
+**Key Steps:** Load skill → Re-index source → Structural diff → Semantic diff (Deep) → Classify severity → Report
+
+**Agent:** Ferris (Audit mode)
+
+---
+
+### Test Skill (TS)
+
+**Command:** `@Ferris TS`
+
+**Purpose:** Cognitive completeness verification. Quality gate before export.
+
+**When to Use:** After creating or updating a skill, before exporting.
+
+**Key Steps:** Load skill → Detect mode → Coverage check → Coherence check → Score → Gap report
+
+**Agent:** Ferris (Audit mode)
+
+---
+
+## Utility Workflows
+
+### Export Skill (EX)
+
+**Command:** `@Ferris EX`
+
+**Purpose:** Package for distribution + platform-aware context injection into CLAUDE.md/AGENTS.md.
+
+**When to Use:** When a skill is ready for distribution or CLAUDE.md integration.
+
+**Key Steps:** Load skill → Package → Generate snippet → Update CLAUDE.md → Token report → Summary
+
+**Agent:** Ferris (Delivery mode)
+
+---
+
+## Workflow Connections
+
+```
+                    setup-forge (one-time)
+                         │
+          ┌──────────────┼──────────────┐
+          │              │              │
+     analyze-source  quick-skill  create-stack-skill
+          │              │              │
+     brief-skill         │              │
+          │              │              │
+     create-skill        │              │
+          │              │              │
+          └──────┬───────┘──────────────┘
+                 │
+            test-skill (quality gate)
+                 │
+          ┌──────┼──────┐
+          │             │
+     export-skill  audit-skill
+                        │
+                   update-skill (loops back to test)
+```
+
+---
+
+## Build Priority
+
+| Phase | Workflows | Notes |
+|-------|-----------|-------|
+| 1a (Core Engine) | setup-forge, create-skill, test-skill, export-skill | Must build first |
+| 1b (Entry Points) | quick-skill, brief-skill, create-stack-skill | Complete v1.0 |
+| 2 (Lifecycle) | audit-skill, update-skill, analyze-source | Post-launch |