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

package/docs/getting-started.md

@@ -1,55 +1,67 @@
 ---
 title: Getting Started
-description: Installation, prerequisites, first steps, and common use cases for Skill Forge
+description: Install Skill Forge and generate your first verified skill in under a minute.
 ---
 
-# Getting Started with SKF: Skill Forge
+## In 60 seconds
 
-Welcome to Skill Forge! This guide will help you get up and running.
+One command. One verified skill. Here's a real snippet from a cognee skill SKF compiled:
 
----
+```python
+await cognee.search(  # [AST:cognee/api/v1/search/search.py:L26]
+    query_text="What does Cognee do?"
+)
+```
 
-## What This Module Does
+Every instruction carries a receipt — a file, a line, and a commit SHA from the upstream repo. Your AI reads these instead of guessing from training data, and you can open the source at the pinned commit to confirm the function exists. Nothing is made up; everything is falsifiable.
 
-Skill Forge analyzes code repositories, documentation websites, and developer discourse to build verified instruction files ("skills") for AI agents. Instead of your agent guessing API calls from training data, it follows instructions where every function, type, and pattern traces back to its source — a file and line for code, a URL for documentation, an issue or PR for discourse. Skills comply with the [agentskills.io](https://agentskills.io) open standard and work across Claude, Cursor, Copilot, and other AI tools. See the [Concepts](../concepts/) page for definitions of key terms.
+Want to see the full audit on a real shipped skill before you install anything? → [Verifying a Skill](../verifying-a-skill/).
 
 ---
 
-## Installation
-
-There are three ways to install SKF, depending on your setup.
+## Install
 
-### Standalone (recommended for trying SKF)
+One command, on any platform. Requires Node.js ≥ 22, Python ≥ 3.10, and `uv` ([full tool matrix below](#prerequisites-full-reference)).
 
 ```bash
 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.
+You'll be prompted for project name, output folders, and which IDEs to configure. The installer copies skill directories to each IDE's skills folder (e.g. `.claude/skills/`, `.cursor/skills/`) so skills are available natively.
 
-### As a custom module during BMad Method installation
+### 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):
+Step through the installer prompts:
+
+- **"Would you like to browse community modules?"** — No (SKF isn't in the community catalog yet)
+- **"Would you like to install from a custom source (Git URL or local path)?"** — Yes
+- **"Git URL or local path:"** — paste the SKF repo URL:
 
 ```
-Path to custom module folder: /path/to/bmad-module-skill-forge/src/
+https://github.com/armelhbobdad/bmad-module-skill-forge
 ```
 
-This installs BMad core + SKF together with full IDE integration, manifests, and help catalog. Best when you want the complete BMad development workflow.
+Or, if you've already cloned the repo locally, provide the path to the repo root instead:
 
-### Add SKF to an existing BMad project
+```
+/path/to/bmad-module-skill-forge
+```
+
+This installs BMAD core + SKF together with full IDE integration, manifests, and help catalog. Best when you want the complete BMAD development workflow. See [BMAD Synergy](../bmad-synergy/) for how SKF workflows pair with BMM phases and other BMAD modules.
 
-If you already have BMad installed, you can add SKF afterward by running the standalone installer in the same directory:
+### 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 bmad-module-skill-forge install
 ```
 
-The installer detects the existing `_bmad/` directory and installs SKF alongside your current modules.
+The installer detects the existing `_bmad/` directory and installs SKF alongside your current modules. See [BMAD Synergy](../bmad-synergy/) for integration patterns with your existing BMM workflows.
 
 ### Updating an existing SKF installation
 
@@ -59,46 +71,15 @@ To move to a newer (or older) SKF version, run the installer again in your proje
 npx bmad-module-skill-forge@latest install
 ```
 
-The installer reads the installed version from your manifest and shows the delta in the prompt — for example `v0.8.3 → v0.8.4 available`. Pick **Update** to replace SKF files while keeping your `config.yaml` intact. The option label adapts to the direction you're moving (upgrade, reinstall the same version, or downgrade) so you always see exactly what you're about to apply. Pick **Fresh install** instead if you want to wipe everything and start clean.
+The installer reads the installed version from your manifest and shows the delta in the prompt — for example `v0.10.0 → v1.0.0 available`. Pick **Update** to replace SKF files while keeping your `config.yaml` intact. The option label adapts to the direction you're moving (upgrade, reinstall the same version, or downgrade) so you always see exactly what you're about to apply. Pick **Fresh install** instead if you want to wipe everything and start clean.
 
 > The `@latest` suffix forces npx to fetch the newest published version instead of reusing a cached copy from a previous run.
 
 ---
 
-## Prerequisites
-
-| Tool                                                                   | Required For                                     | Install                                                |
-|------------------------------------------------------------------------|--------------------------------------------------|--------------------------------------------------------|
-| [Node.js](https://nodejs.org/) >= 22                                   | Installation, npx commands                       | <https://nodejs.org>                                   |
-| `gh` (GitHub CLI)                                                      | Required for Deep mode. Optional convenience in Quick/Forge/Forge+ for source access. | <https://cli.github.com>                               |
-| `ast-grep`  (CLI tool for code structural search, lint, and rewriting) | Forge + Deep modes                               | <https://ast-grep.github.io>                           |
-| `ast-grep` MCP server (recommended alongside CLI)                      | Forge + Deep modes                               | <https://github.com/ast-grep/ast-grep-mcp>             |
-| `ccc` (cocoindex-code semantic code search)                            | Forge+ mode                                      | <https://github.com/cocoindex-io/cocoindex-code>       |
-| `qmd` (local hybrid search engine for project files)                   | Deep mode                                        | <https://github.com/tobi/qmd>                          |
-| `SNYK_TOKEN` (Snyk API token — **Enterprise plan required**)           | Optional security scan                           | <https://docs.snyk.io/snyk-api/authentication-for-api> |
-
-Don't worry if you don't have all tools — SKF detects what's available and sets your tier automatically. Security scanning via Snyk is optional and requires an Enterprise plan; it does not affect your tier level.
-
----
-
-## Configuration
-
-SKF has two install-time variables (defined in `src/module.yaml`), one Core Config variable inherited from BMad, and one runtime preference:
-
-| Variable               | Purpose                                                                                              | Default                     |
-|------------------------|------------------------------------------------------------------------------------------------------|-----------------------------|
-| `skills_output_folder` | Where generated skills are saved                                                                     | `{project-root}/skills`     |
-| `forge_data_folder`    | Where workspace artifacts are stored (VS reports, evidence)                                          | `{project-root}/forge-data` |
-| `output_folder`        | Where refined architecture documents are saved (used by RA workflow). *Inherited from BMad Core Config.* | Defined by BMad Core Config |
-| `tier_override`        | Force a specific tier for comparison or testing (in `_bmad/_memory/forger-sidecar/preferences.yaml`) | `~` (auto-detect)           |
-
-Runtime configuration (tool detection, tier, and collection state) is managed by the `setup-forge` workflow and persisted in `forge-tier.yaml`.
-
----
-
-## First Steps
+## Your first skill
 
-### 1. Setup Your Forge
+### 1. Setup your forge
 
 ```
 @Ferris SF
@@ -106,7 +87,7 @@ Runtime configuration (tool detection, tier, and collection state) is managed by
 
 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
+### 2. Generate your first skill
 
 **Fastest path (Quick Skill):**
 ```
@@ -117,10 +98,17 @@ Ferris reads the repository, extracts the public API, and generates a skill in u
 
 **Targeting a specific version:** Append `@version` to pin the skill to a library version:
 ```
-@Ferris QS cognee@0.5.0
+@Ferris QS cognee@1.0.0
 ```
 
-**Full quality path (one workflow per session):**
+**Full quality path (pipeline mode):**
+```
+@Ferris forge https://github.com/cocoindex-io/cocoindex cocoindex
+```
+
+`forge` chains Brief → Create → Test → Export. It needs an explicit repo URL **and** a skill name because it starts with Brief Skill (BS), which doesn't guess targets. If you just want a fast skill from a package name, use `@Ferris forge-quick cognee` instead — that starts with Quick Skill (QS), which resolves packages via the registry.
+
+Or one workflow per session:
 ```
 @Ferris BS    # Brief — scope and design the skill
 # — clear session —
@@ -131,9 +119,9 @@ Ferris reads the repository, extracts the public API, and generates a skill in u
 @Ferris EX    # Export — package for distribution
 ```
 
-> Start a fresh conversation before each workflow. SKF workflows load significant context — clearing between them prevents interference. See [Session Context](../concepts/#session-context).
+> **One workflow per session.** Each SKF workflow loads step files, knowledge fragments, and extraction data into the LLM's context as it executes. Running a second workflow in the same session can cause leftover context to interfere — stale references, mode confusion, or degraded output. Clear your session (start a new conversation) before invoking a new workflow. Pipeline mode chains workflows automatically with headless mode; for manual control, start fresh between each one. Sidecar state (forge tier, preferences) persists across sessions, so no configuration is lost.
 
-### 3. Stack Skill (for full projects)
+### 3. Stack skill (for full projects)
 
 ```
 @Ferris SS
@@ -141,122 +129,72 @@ Ferris reads the repository, extracts the public API, and generates a skill in u
 
 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.
+> **After every workflow:** Ferris runs a **health check** — a reflection step that captures any friction, bugs, or gaps from the session. Clean runs exit in one line; when something breaks, Ferris offers to file structured findings as GitHub issues (with your approval). **Please let workflows run to completion** so the health check can fire. If it was skipped, ask Ferris to run it (`@Ferris please run the workflow health check for this session`) or [open an issue directly](https://github.com/armelhbobdad/bmad-module-skill-forge/issues/new/choose). See [Workflow Health Check](../workflows/#terminal-step-health-check).
 
-```
-@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
+---
 
-Each tier builds on the previous one. Quick mode reads source files directly. Forge adds `ast-grep` for AST-verified structural truth. Forge+ adds `ccc` (cocoindex-code) to semantically rank source regions before AST extraction — on large codebases, this ensures the most relevant exports are discovered first. Deep adds `gh` + `qmd` for GitHub exploration and QMD knowledge search with historical context enrichment.
+## Common use cases
 
-```
-@Ferris SF    # Setup detects your tools and sets tier automatically
-```
+> **Looking for end-to-end examples?** See [Examples](../examples/) for eleven real-world scenarios with full command transcripts — from Quick Skill under a minute, to brownfield onboarding, stack verification, release-prep drift remediation, and SaaS docs-only skills.
 
-Ferris detects your tools and sets the highest tier where all required tools pass verification. With `ast-grep` + `gh` + `qmd`, you get Deep mode — every skill gets AST-verified signatures (T1) enriched with temporal context from issues, PRs, and changelogs (T2). Add `ccc` alongside those three for maximum capability: semantic discovery plus full knowledge search.
+---
 
-### I maintain an OSS library and want official skills
+## Prerequisites (full reference)
 
-You want maximum quality with full provenance for distribution. Use the full pipeline with Deep mode for the richest output.
+Most users only need Node.js, Python, and `uv` — the rest unlock additional capabilities but SKF detects what's available and sets your tier automatically. You can install them later; your tier upgrades when you do.
 
-```
-@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.
+| Tool                                                                   | Required For                                                                          | Install                                                   |
+|------------------------------------------------------------------------|---------------------------------------------------------------------------------------|-----------------------------------------------------------|
+| `Node.js` >= 22                                                        | Installation, npx commands                                                            | <https://nodejs.org>                                      |
+| `Python` >= 3.10                                                       | Deterministic scoring, validation, and utility scripts                                | <https://www.python.org>                                  |
+| `uv` (Python package runner)                                           | Running Python scripts with automatic dependency management                           | <https://docs.astral.sh/uv/getting-started/installation/> |
+| `gh` (GitHub CLI)                                                      | Required for Deep mode. Optional convenience in Quick/Forge/Forge+ for source access. | <https://cli.github.com>                                  |
+| `ast-grep`  (CLI tool for code structural search, lint, and rewriting) | Forge + Deep modes                                                                    | <https://ast-grep.github.io>                              |
+| `ast-grep` MCP server (recommended alongside CLI)                      | Forge + Deep modes                                                                    | <https://github.com/ast-grep/ast-grep-mcp>                |
+| `ccc` (cocoindex-code semantic code search)                            | Forge+ mode                                                                           | <https://github.com/cocoindex-io/cocoindex-code>          |
+| `qmd` (local hybrid search engine for project files)                   | Deep mode                                                                             | <https://github.com/tobi/qmd>                             |
+| `SNYK_TOKEN` (Snyk API token — **Enterprise plan required**)           | Optional security scan                                                                | <https://docs.snyk.io/snyk-api/authentication-for-api>    |
 
-### I'm planning a new project and want to verify my tech stack works together
+Security scanning via Snyk is optional and requires an Enterprise plan; it does not affect your tier level.
 
-You have an architecture document and want to verify feasibility before writing code. Generate skills for each library, run Verify Stack to check compatibility, refine the architecture with skill evidence, then compose a stack skill.
+### Platform support
 
-```
-@Ferris CS    # or QS — generate a skill per library
-@Ferris VS    # Verify Stack — feasibility check against architecture
-@Ferris RA    # Refine Architecture — fill gaps with API evidence
-@Ferris SS    # Stack Skill — compose-mode activates automatically
-```
+**Linux and Windows** are exercised in CI on every PR (`ubuntu-latest` + `windows-latest` matrix on `validate` and `python` jobs). **macOS** works in practice — POSIX-equivalent to Linux — but isn't CI-gated; if you hit a macOS-specific bug, please [file an issue](https://github.com/armelhbobdad/bmad-module-skill-forge/issues).
 
-VS produces a feasibility report (FEASIBLE / CONDITIONALLY FEASIBLE / NOT FEASIBLE). RA enriches your architecture doc with verified API details. SS compose-mode synthesizes a stack skill from existing skills + architecture — no codebase needed.
+On Windows, SKF transparently falls back to NTFS junctions when symlink privilege isn't held, so no Developer Mode or admin rights are required. Git Bash (bundled with [Git for Windows](https://git-scm.com/download/win)), PowerShell, and WSL2 all work.
 
-### 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
-```
+---
 
-### I want scripts and assets included in my skills
+## Configuration
 
-Your source repo has CLI tools, setup scripts, or config templates that agents should use. SKF detects and packages them automatically.
+SKF has two install-time variables (defined in `src/module.yaml`), one Core Config variable inherited from BMAD, and one runtime preference:
 
-```
-@Ferris BS    # Brief — scripts/assets auto-detected by default
-@Ferris CS    # Create — scripts/ and assets/ auto-detected
-```
+| Variable               | Purpose                                                                                                  | Default                     |
+|------------------------|----------------------------------------------------------------------------------------------------------|-----------------------------|
+| `skills_output_folder` | Where generated skills are saved                                                                         | `{project-root}/skills`     |
+| `forge_data_folder`    | Where workspace artifacts are stored (VS reports, evidence)                                              | `{project-root}/forge-data` |
+| `output_folder`        | Where refined architecture documents are saved (used by RA workflow). *Inherited from BMAD Core Config.* | Defined by BMAD Core Config |
+| `tier_override`        | Force a specific tier for comparison or testing (in `_bmad/_memory/forger-sidecar/preferences.yaml`)     | `~` (auto-detect)           |
+| `headless_mode`        | Skip confirmation gates in all workflows (in `_bmad/_memory/forger-sidecar/preferences.yaml`)            | `false`                     |
 
-Scripts from `scripts/`, `bin/`, `tools/`, and `cli/` directories are copied with provenance. Config templates and schemas from `assets/`, `templates/`, `schemas/`, `configs/`, and `examples/` are included. Custom files you add to `scripts/[MANUAL]/` survive updates.
+Runtime configuration (tool detection, tier, and collection state) is managed by the `setup` workflow and persisted in `forge-tier.yaml`.
 
 ---
 
-## What's Next?
+## What's next?
 
-- Check out the [Agents Reference](../agents/) to learn about Ferris
-- Browse the [Workflows Reference](../workflows/) to see all available commands
-- See [Examples](../examples/) for real-world usage scenarios
+- [Agents](../agents/) — learn about Ferris
+- [Workflows](../workflows/) — the full command reference
+- [Examples](../examples/) — real-world scenarios with transcripts
 
 ---
 
-## Need Help?
+## 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?`)
-   *Provided by the [BMad Method](https://github.com/bmad-code-org/BMAD-METHOD) — not available in standalone SKF installations.*
+   *Provided by the [BMAD Method](https://github.com/bmad-code-org/BMAD-METHOD) — not available in standalone SKF installations.*
 2. Run `@Ferris SF` to check your tool availability and tier
 3. Check `forge-tier.yaml` in your forger sidecar for your current configuration
+4. If a workflow gave you friction, ask Ferris to run the health check for that session, or [open an issue](https://github.com/armelhbobdad/bmad-module-skill-forge/issues/new/choose) — see [Workflow Health Check](../workflows/#terminal-step-health-check)