bmad-module-skill-forge 2.1.0 → 3.0.0

package/docs/examples.md

@@ -35,19 +35,19 @@ description: >
 |----------|---------|------------|--------|
 | add() | Ingest text, files, binary data | data, dataset_name | [AST:cognee/api/v1/add/add.py:L22] |
 | cognify() | Build knowledge graph | datasets, graph_model | [AST:cognee/api/v1/cognify/cognify.py:L44] |
-| search() | Query knowledge graph | query_text, query_type | [AST:cognee/api/v1/search/search.py:L26] |
+| search() | Query knowledge graph | query_text, query_type | [AST:cognee/api/v1/search/search.py:L27] |
 | memify() | Enrich graph with custom tasks | extraction_tasks, data | [AST:cognee/modules/memify/memify.py:L25] |
 | remember() | V2 one-shot memory ingest | data, dataset_name | [AST:cognee/api/v1/remember/remember.py:L339] |
 | DataPoint | Base class for custom graph nodes | inherit and add fields | [EXT:docs.cognee.ai/guides/custom-data-models] |
 ```
 
-Every line number above is verbatim from the real [`forge-data/oms-cognee/1.0.0/provenance-map.json`](https://github.com/armelhbobdad/oh-my-skills/blob/main/forge-data/oms-cognee/1.0.0/provenance-map.json) shipped with oh-my-skills — not illustrative.
+Every line number above is copied from the real SKILL.md and points at the line where that function is defined in the cognee source, so none of it is illustrative. SKF also ships its extraction record for this skill in oh-my-skills: [`forge-data/oms-cognee/1.0.0/provenance-map.json`](https://github.com/armelhbobdad/oh-my-skills/blob/main/forge-data/oms-cognee/1.0.0/provenance-map.json). The tags are copied as published too, and they predate labels that follow the tool: that record lists these functions as read by eye (`source-read`), so SKF 3.0.0 would tag them `[SRC:...]` (T1-low) and keep `[AST:...]` for a definition an ast-grep rule matched. [Verifying a Skill](/docs/verifying-a-skill.md#2-open-the-skills-provenance-mapjson) walks through the `search` entry.
 
 Provenance tags trace each instruction to its source:
-- `[AST:file:line]` — extracted from code via AST parsing (highest confidence)
-- `[SRC:file:line]` — read from source code without AST verification
-- `[EXT:url]` — sourced from external documentation
-- `[QMD:collection:doc]` — surfaced from indexed developer discourse (issues, PRs, changelogs)
+- `[AST:file:Lnn]` (T1): an ast-grep rule matched the definition in the code (highest confidence)
+- `[SRC:file:Lnn]` (T1-low): read from source code by eye, without an ast-grep match, at any forge tier
+- `[QMD:collection:doc]` (T2): surfaced from indexed developer discourse (issues, PRs, changelogs)
+- `[EXT:url]` (T3): sourced from external documentation (lowest confidence)
 
 See [Skill Model → Output Architecture](/docs/skill-model.md#output-architecture) for the full output structure.
 
@@ -74,13 +74,13 @@ skills/oms-cognee/
             └── pipelines-and-datapoints.md
 ```
 
-This is the real directory listing from [`oh-my-skills/skills/oms-cognee/`](https://github.com/armelhbobdad/oh-my-skills/tree/main/skills/oms-cognee) after cognee shipped v1.0.0 upstream. SKF recompiled the skill from the v1.0.0 commit and wrote it next to the existing 0.5.8 tree — the older version stays pinned to its original commit (`b51dcce1`) and is still installable by any project that hasn't bumped its `CLAUDE.md` pin yet. The `active` symlink and the [`.export-manifest.json`](https://github.com/armelhbobdad/oh-my-skills/blob/main/skills/.export-manifest.json) both point at the current version. Some skills also include `scripts/` and `assets/` directories when the source repository contains executable scripts or static assets — oms-cognee doesn't have either, but see [Skill Model → Per-Skill Output](/docs/skill-model.md#per-skill-output) for the full schema.
+This is the real directory listing from [`oh-my-skills/skills/oms-cognee/`](https://github.com/armelhbobdad/oh-my-skills/tree/main/skills/oms-cognee) after cognee shipped v1.0.0 upstream. SKF recompiled the skill from the v1.0.0 commit and wrote it next to the existing 0.5.8 tree. The older version stays pinned to its original commit (`b51dcce1`) and is still installable by any project that hasn't bumped its `CLAUDE.md` pin yet. The `active` symlink and the [`.export-manifest.json`](https://github.com/armelhbobdad/oh-my-skills/blob/main/skills/.export-manifest.json) both point at the current version. Some skills also include `scripts/` and `assets/` directories when the source repository contains executable scripts or static assets. oms-cognee has neither; see [Skill Model → Per-Skill Output](/docs/skill-model.md#per-skill-output) for the full schema.
 
 ---
 
 ## Example Workflows
 
-### Quick Skill — Under a minute
+### Quick Skill: Under a minute
 
 Developer adds [cognee](https://github.com/topoteretes/cognee) to a Python project for AI memory management. Agent keeps hallucinating method signatures and config options.
 
@@ -88,7 +88,7 @@ Developer adds [cognee](https://github.com/topoteretes/cognee) to a Python proje
 @Ferris QS https://github.com/topoteretes/cognee
 ```
 
-Ferris reads the repository, extracts the public API, and validates against the agentskills.io spec. The skill is written to `skills/cognee/<version>/cognee/` (auto-detected from the source manifest). The agent now reads the real signatures from the skill instead of guessing.
+Ferris reads the repository, lists its public exports, and validates against the agentskills.io spec. The skill is written to `skills/cognee/<version>/cognee/` (the version is detected from the source manifest). The agent now reads the real export names and usage examples from the skill instead of guessing. Quick Skill does not extract full signatures or cite a source line for each export. When you need those, run `@Ferris forge-auto https://github.com/topoteretes/cognee` instead.
 
 Need a specific version? Append `@version`:
 
@@ -96,28 +96,30 @@ Need a specific version? Append `@version`:
 @Ferris QS cognee@1.0.0
 ```
 
-### Brownfield Platform — Pipeline or per-workflow
+### Brownfield Platform: Pipeline or per-workflow
 
 Alex, a platform engineer, adopts BMAD for 10 microservices spanning TypeScript, Go, and Rust.
 
 ```
-@Ferris SF                                              # Setup — Deep tier detected
-# — clear session —
-@Ferris forge-auto https://github.com/acme/auth-service   # one service: Analyze → Brief → Create → Test → Export
+@Ferris SF                                              # Setup: Deep tier detected
+# clear session
+@Ferris forge-auto https://github.com/acme/auth-service   # one service per run: Analyze → Brief → Create → Test → Export
 ```
 
 Or one workflow per session:
 ```
-@Ferris SF          # Setup — Deep tier detected
-# — clear session —
-@Ferris AN          # Analyze — 10 services mapped
-# — clear session —
-@Ferris CS --batch  # Create — batch generation
+@Ferris SF          # Setup: Deep tier detected
+# clear session
+@Ferris AN          # Analyze: 10 services mapped
+# clear session
+@Ferris CS --batch  # Create: batch generation
+# clear session
+@Ferris SS          # Stack Skill: one platform skill for how the services connect
 ```
 
-10 individual skills + 1 platform stack skill. The [BMM](/docs/bmad-synergy.md#skf-and-bmm-phase-by-phase-playbook) architect then navigates cross-service flows using verified knowledge.
+The result is 10 individual skills plus 1 platform stack skill, which SS builds once the individual skills exist. The [BMM](/docs/bmad-synergy.md#skf-and-bmm-phase-by-phase-playbook) architect then navigates cross-service flows using verified knowledge.
 
-### Release Prep — Trust Builder
+### Release Prep: Trust Builder
 
 Jin, a Rust library maintainer, is preparing v1.0.0 with breaking changes she wants consumers' agents to pick up automatically.
 
@@ -127,18 +129,18 @@ Jin, a Rust library maintainer, is preparing v1.0.0 with breaking changes she wa
 
 Or one workflow per session:
 ```
-@Ferris AS    # Audit — finds 3 renames, 1 removal, 1 addition
-# — clear session —
-@Ferris US    # Update — preserves [MANUAL] sections, adds annotations
-# — clear session —
-@Ferris TS    # Test — verify completeness
-# — clear session —
-@Ferris EX    # Export — package for npm release
+@Ferris AS    # Audit: finds 3 renames, 1 removal, 1 addition
+# clear session
+@Ferris US    # Update: preserves [MANUAL] sections, adds annotations
+# clear session
+@Ferris TS    # Test: verify completeness
+# clear session
+@Ferris EX    # Export: package for distribution
 ```
 
-Ships with the npm release. Consumers upgrade and their agents use the correct function names — no more "wrong signature" support tickets.
+Jin publishes the updated skill alongside the release (for an official skill, EX prints the `npx skills publish` command). Consumers upgrade and their agents use the correct function names, with no more "wrong signature" support tickets.
 
-### Stack Skill — Integration Intelligence
+### Stack Skill: Integration Intelligence
 
 Armel, building a full-stack side project on Next.js + Serwist + SpacetimeDB + better-auth.
 
@@ -148,20 +150,20 @@ Armel, building a full-stack side project on Next.js + Serwist + SpacetimeDB + b
 
 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`." That integration detail isn't available from any other tool in the [comparison table](/docs/index.md#how-skf-compares).
 
-### Pre-Code Architecture Verification — Greenfield Confidence
+### Pre-Code Architecture Verification: Greenfield Confidence
 
-Gery, a backend architect, is designing a new TypeScript service on Hono + Drizzle + SpacetimeDB. Architecture doc is written but no code exists yet — he wants to verify the stack holds together before anyone starts building.
+Gery, a backend architect, is designing a new TypeScript service on Hono + Drizzle + SpacetimeDB. The architecture doc is written but no code exists yet, and he wants to verify the stack holds together before anyone starts building.
 
 ```
 @Ferris QS hono          # Quick Skill per library
 @Ferris QS drizzle-orm
 @Ferris QS spacetimedb-sdk
-@Ferris VS               # Verify Stack — feasibility report
-@Ferris RA               # Refine Architecture — enrich with API evidence
-@Ferris SS               # Stack Skill — compose-mode (no codebase needed)
+@Ferris VS               # Verify Stack: feasibility report
+@Ferris RA               # Refine Architecture: enrich with API evidence
+@Ferris SS               # Stack Skill: compose-mode (no codebase needed)
 ```
 
-VS flags the Drizzle↔SpacetimeDB integration as incompatible (query-model mismatch) and returns CONDITIONALLY FEASIBLE. Gery adds a bridge layer to the architecture, re-runs VS → FEASIBLE. RA fills in verified API signatures. SS compose-mode synthesizes the stack skill from existing skills + refined architecture. The agent now has integration intelligence for a project that doesn't have code yet.
+VS rates the Drizzle↔SpacetimeDB pair `Risky` (a query-model mismatch that a workaround may resolve) and returns an overall verdict of `CONDITIONALLY_FEASIBLE`. Gery adds a bridge layer to the architecture and re-runs VS, which now returns `FEASIBLE`. RA fills in verified API signatures. SS compose-mode builds the stack skill from the existing skills and the refined architecture. The agent now has integration intelligence for a project that doesn't have code yet.
 
 ---
 
@@ -172,10 +174,10 @@ VS flags the Drizzle↔SpacetimeDB integration as incompatible (query-model mism
 BMAD user starts a new project. [BMM](/docs/bmad-synergy.md#skf-and-bmm-phase-by-phase-playbook) 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 platform context files
+@Ferris BS    # Brief: scope the skill
+@Ferris CS    # Create: compile from brief
+@Ferris TS    # Test: verify completeness
+@Ferris EX    # Export: inject into platform context files
 ```
 
 Skills accumulate over sprints. The agent's coverage improves each iteration.
@@ -188,21 +190,21 @@ Blondin, a platform lead, needs cross-service knowledge for 10 microservices so
 @Ferris campaign    # Orchestrate all 10 skills across sessions, in dependency order
 ```
 
-Campaign reads the dependency graph, sorts the skills topologically, and drives each one through the full pipeline (brief, generate, compile, test) with quality gates enforced. State is written to disk, so Blondin can walk away and `@Ferris campaign resume` after a context death or a session break — picking up exactly where the last session stopped. One forge project, multiple QMD collections, hub-and-spoke skills with integration patterns. See [Campaign Orchestration](/docs/campaign.md) for the full stage-by-stage flow.
+Campaign reads the dependencies you declare for each skill, orders the skills so each one comes after the skills it depends on, and drives each full-pipeline (Tier A) skill through brief, compile and test, with quality gates enforced. Libraries marked Tier B are built faster, in one Quick Skill batch. It then composes a capstone stack skill that shows how the services connect, and asks for your go-ahead before it exports the skills that clear the quality gate. State is written to disk, so Blondin can walk away and run `@Ferris campaign resume` after the conversation runs out of context or after a break, picking up exactly where the last session stopped. See [Campaign Orchestration](/docs/campaign.md) for the full stage-by-stage flow.
 
 ### Scenario C: External Dependency
 
-Kossi, a developer integrating an uncommon library, needs a skill for it — nothing official exists yet.
+Kossi, a developer integrating an uncommon library, needs a skill for it, and nothing official exists yet.
 
 ```
 @Ferris QS better-auth
 ```
 
-Checks ecosystem first. If no official skill exists: generates from source. `source_authority: community`.
+Resolves the package name to its GitHub repository and generates the skill from source, with `source_authority: community`. Quick Skill skips its check for an existing official skill until agentskills.io offers a registry API to ask.
 
 ### Scenario D: Docs-Only (SaaS/Closed Source)
 
-No source code to clone — only API documentation. Example: you're integrating the [Stripe API](https://docs.stripe.com/api) and want your agent to know the real endpoints, parameters, and error codes instead of hallucinating from training data.
+There is no source code to clone, only API documentation. Example: you're integrating the [Stripe API](https://docs.stripe.com/api) and want your agent to know the real endpoints, parameters, and error codes instead of hallucinating from training data.
 
 ```
 @Ferris BS
@@ -214,11 +216,11 @@ No source code to clone — only API documentation. Example: you're integrating
 # When asked for target version, specify: 2025-04-30.basil
 # Ferris confirms your doc URLs match that API version
 @Ferris CS
-# step 3 skips (no source to clone), step 3c fetches docs via doc_fetcher
+# step 3 finds no source to extract; step 3c (Fetch Docs) downloads the doc pages
 # All content is T3 [EXT:url] confidence. source_authority: community
 ```
 
-The brief's `doc_urls` field drives the doc_fetcher step. The agent uses whatever web fetching tool is available in its environment (Firecrawl, WebFetch, curl, etc.) to retrieve documentation as markdown and extract API information with `[EXT:url]` citations. No AST parsing is possible without source code — every instruction carries T3 provenance instead of T1, and the skill is tagged `source_authority: community` regardless of tier.
+The brief's `doc_urls` field drives the Fetch Docs step (step 3c). The agent uses whatever web fetching tool is available in its environment (Firecrawl, WebFetch, curl, etc.) to retrieve documentation as markdown and extract API information with `[EXT:url]` citations. No AST parsing is possible without source code, so every instruction carries T3 provenance (external documentation, the lowest confidence) instead of T1, and the skill is tagged `source_authority: community` regardless of tier.
 
 ### Scenario E: Rename a Skill
 
@@ -251,7 +253,7 @@ Version 0.6.0 remains active. Version 0.5.0 is untouched. The managed sections i
 
 ### Scenario G: Maximum Accuracy for a High-Stakes Library
 
-You're building skills for a production payments library and need maximum citation density. Every signature must be AST-verified, and you want historical context (deprecations, migration notes) baked into the skill.
+You're building skills for a production payments library and need maximum citation density. You want as many signatures as possible AST-verified, and historical context (deprecations, migration notes) baked into the skill.
 
 **Workflow:**
 
@@ -259,31 +261,31 @@ You're building skills for a production payments library and need maximum citati
 @Ferris SF
 # Ferris detects installed tools and sets your tier automatically:
 # - Quick: no tools required (best-effort, source-read only)
-# - Forge: + ast-grep (T1 AST-verified signatures)
-# - Forge+: + cocoindex-code (semantic pre-ranking for large repos)
-# - Deep: + gh + qmd (T2 evidence — issues, PRs, changelogs)
+# - Forge: ast-grep (T1 for each export an ast-grep rule matches)
+# - Forge+: ast-grep + cocoindex-code (semantic pre-ranking for large repos)
+# - Deep: ast-grep + gh + qmd (T2 evidence from issues, PRs, changelogs; cocoindex-code optional)
 # Install the missing tools, then re-run @Ferris SF to promote your tier.
-@Ferris BS    # Scope — confirm the forge tier is Deep (+ ccc if installed)
-@Ferris CS    # Extract — AST + QMD enrichment
-@Ferris TS    # Completeness score — 80%+ threshold
+@Ferris BS    # Scope: confirm the forge tier is Deep (+ ccc if installed)
+@Ferris CS    # Extract: AST + QMD enrichment
+@Ferris TS    # Completeness score: 80%+ threshold
 ```
 
-**What you get:** Every signature carries `[AST:file:Lnn]` at T1. Deprecation warnings and design rationale carry `[QMD:collection:doc]` at T2. Install tooling once, every downstream skill benefits. See [Capability Tiers](/docs/concepts.md#capability-tiers-quickforgeforgedeep).
+**What you get:** Every signature an ast-grep rule matched carries `[AST:file:Lnn]` at T1. An export it could not match is read by eye and carries `[SRC:file:Lnn]` at T1-low, so you know which signatures to check by hand. Deprecation warnings and design rationale carry `[QMD:collection:doc]` at T2. Install tooling once, every downstream skill benefits. See [Capability Tiers](/docs/concepts.md#capability-tiers-quickforgeforgedeep).
 
 ### Scenario H: OSS Maintainer Publishing Official Skills
 
-You maintain an OSS library and want to ship official agent skills alongside each release — distributed via [skills.sh](https://skills.sh) or [oh-my-skills](https://github.com/armelhbobdad/oh-my-skills) so consumers install them with `npx skills add`.
+You maintain an OSS library and want to ship official agent skills alongside each release, distributed via [skills.sh](https://skills.sh) or [oh-my-skills](https://github.com/armelhbobdad/oh-my-skills) so consumers install them with `npx skills add`.
 
 **Workflow:**
 
 ```
-@Ferris BS    # Scope the skill — set source_authority: official in the brief
-@Ferris CS    # Compile — AST extraction + QMD enrichment (Deep tier recommended)
-@Ferris TS    # Verify completeness before publishing (target: 90%+)
-@Ferris EX    # Package for distribution — emits npx skills publish instructions
+@Ferris BS    # Scope the skill: set source_authority: official in the brief
+@Ferris CS    # Compile: AST extraction + QMD enrichment (Deep tier recommended)
+@Ferris TS    # Verify completeness before publishing (aim for 90%+; the pass line is 80%)
+@Ferris EX    # Export: validate the package, write its context snippet, update the managed section in CLAUDE.md, AGENTS.md or .cursorrules
 ```
 
-**What you get:** A verified skill pinned to the release commit, with `source_authority: official` surfaced in metadata as a trust signal so downstream tooling (and the ecosystem check in `@Ferris QS`) recognize it as maintainer-published rather than community-forged. Re-run `@Ferris maintain <skill>` (AS → US → TS → EX) on every release to keep published skills current.
+**What you get:** A verified skill pinned to the release commit, with `source_authority: official` surfaced in metadata as a trust signal so downstream tooling recognizes it as maintainer-published rather than community-forged. For an official skill, EX also prints the `npx skills publish` command. Re-run `@Ferris maintain <skill>` (AS → US → TS → EX) on every release to keep published skills current.
 
 ---
 
@@ -291,15 +293,15 @@ You maintain an OSS library and want to ship official agent skills alongside eac
 
 ### Skip Permissions for Faster Forging
 
-> **Tip from Armel:** When forging skills with Claude Code, I run `claude --dangerously-skip-permissions` to bypass all permission prompts. SKF workflows only read source code, write to `skills/` and `forge-data/`, and call local tools (ast-grep, qmd, gh) — every step is auditable in the [open source](https://github.com/armelhbobdad/bmad-module-skill-forge). Skipping permissions drastically reduces forge time: I start a pipeline, go [grab one of those coffees ☕ you keep offering](https://buymeacoffee.com/armelhbobdad), and come back to a completed workflow. Review the output at the end, not at every gate.
+> **Tip from Armel:** When forging skills with Claude Code, I run `claude --dangerously-skip-permissions` to bypass all permission prompts. SKF workflows read source code, clone remote repositories into `~/.skf/workspace/`, write skills to `skills/` and working files to `forge-data/`, keep their state in `_bmad/_memory/forger-sidecar/`, update the SKF section of CLAUDE.md, AGENTS.md or .cursorrules when you export, and call tools such as git, ast-grep, qmd, gh and npx. Every step is auditable in the [open source](https://github.com/armelhbobdad/bmad-module-skill-forge). Skipping permissions drastically reduces forge time: I start a pipeline, go [grab one of those coffees ☕ you keep offering](https://buymeacoffee.com/armelhbobdad), and come back to a completed workflow. Review the output at the end, not at every gate.
 
 ### Progressive Capability
 
-Start with the Quick tier (no setup required), upgrade to Forge (install ast-grep), then Forge+ (install cocoindex-code for semantic discovery), then Deep (install QMD). Each tier builds on the previous — you never lose capability.
+Start with the Quick tier (no setup required). Install ast-grep to reach Forge. From there, add cocoindex-code for Forge+ (semantic discovery), or add the GitHub CLI (gh) and QMD for Deep (evidence from issues, PRs and changelogs). Deep does not need cocoindex-code, but it still uses it when installed, so adding a tool never takes a capability away. Re-run `@Ferris SF` after installing tools to update your tier.
 
 ### Batch Operations
 
-Use `--batch` with `create-skill` to process multiple briefs at once. Progress is checkpointed — if interrupted, re-run `@Ferris CS --batch` and Ferris will resume automatically from where it left off.
+Use `--batch` with `create-skill` to process multiple briefs at once. Progress is checkpointed per brief: if a batch is interrupted, re-run `@Ferris CS --batch` and Ferris resumes with the brief it was working on (that brief compiles again from the start).
 
 ### Stack Skills + Individual Skills
 
@@ -307,15 +309,15 @@ Stack skills focus on integration patterns. Individual skills focus on API surfa
 
 ### The Loop
 
-After each sprint's refactor, run `@Ferris US` to regenerate changed components. Export updates your platform context files (CLAUDE.md, AGENTS.md, .cursorrules) automatically. Skill generation becomes routine — like running tests.
+After each sprint's refactor, run `@Ferris maintain <skill>` to audit, update, test and export the skill in one go. Update changes only the skill itself; Export is the step that refreshes the skill index in your platform context files (CLAUDE.md, AGENTS.md, .cursorrules). Skill generation becomes routine, like running tests.
 
 ### One Workflow Per Session
 
-Clear your conversation context (start a new chat) before invoking a new workflow. Each SKF workflow loads step files, knowledge fragments, and extraction data into context. Starting fresh ensures the next workflow operates without interference from prior steps. Sidecar state (forge tier, preferences) persists automatically across sessions — you don't lose configuration.
+Clear your conversation context (start a new chat) before invoking a new workflow. Each SKF workflow loads step files, knowledge fragments, and extraction data into context. Starting fresh ensures the next workflow operates without interference from prior steps. A pipeline such as `forge-auto` or `maintain` counts as one invocation: Ferris chains its workflows for you. Sidecar state (forge tier, preferences) persists automatically across sessions, so you don't lose configuration.
 
 ### Full Control Over Scope
 
-You can compile multiple skills from the same target (repo or docs) with different scopes and intents. Each brief defines what to extract and why, producing a distinct skill from the same source. For example, from a single library you could compile `cognee-core` for the public API, `cognee-graph-types` for the type system, and `cognee-migration` for upgrade patterns — each serving a different use case.
+You can compile multiple skills from the same target (repo or docs) with different scopes and intents. Each brief defines what to extract and why, producing a distinct skill from the same source. For example, from a single library you could compile `cognee-core` for the public API, `cognee-graph-types` for the type system, and `cognee-migration` for upgrade patterns, each serving a different use case.
 
 ### Best Practices Built In
 
@@ -323,14 +325,14 @@ Generated skills automatically follow authoring best practices: third-person des
 
 ### Scripts & Assets
 
-If your source repo includes executable scripts (`scripts/`, `bin/`) or static assets (`templates/`, `schemas/`), SKF detects and packages them automatically with provenance tracking. Custom scripts you add to `scripts/[MANUAL]/` are preserved during updates — just like `<!-- [MANUAL] -->` markers in SKILL.md.
+If your source repo includes executable scripts (such as `scripts/`, `bin/` or `tools/`) or static assets (such as `assets/`, `templates/` or `schemas/`), SKF detects and packages them automatically with provenance tracking. Scripts and assets you add yourself under `scripts/[MANUAL]/` or `assets/[MANUAL]/` are preserved during updates, just like `<!-- [MANUAL] -->` markers in SKILL.md.
 
 ### Let the Health Check Run
 
-Every SKF workflow ends with a shared **health check** step where Ferris reflects on the session and offers to file friction, bugs, or gaps as GitHub issues (with your approval). Clean runs exit in one line — zero overhead. When something breaks, it's SKF's primary feedback channel, so **please let workflows run to completion**. If you had to cancel before the health check fired, 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](/docs/workflows.md#terminal-step-health-check) for details.
+Every SKF workflow ends with a shared **health check** step where Ferris reflects on the session and lists any bugs, friction, or gaps it hit. With your approval, it files bugs as GitHub issues; friction and gaps go to a local queue in `forge-data/improvement-queue/` unless you also agree to file them. Clean runs end with a one-line all-clear and no extra work. When something breaks, it's SKF's primary feedback channel, so **please let workflows run to completion**. If you had to cancel before the health check fired, 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](/docs/workflows.md#terminal-step-health-check) for details.
 
 ---
 
 ## Something not working?
 
-See [Troubleshooting](/docs/troubleshooting.md) for common errors (ast-grep unavailable, "no brief found", ecosystem check messages) and how to resolve them. For general setup help, see [Getting Started → Need help?](/docs/getting-started.md#need-help).
+See [Troubleshooting](/docs/troubleshooting.md) for common errors (ast-grep unavailable, "no brief found", a run lock another run holds, a campaign that stopped partway) and how to resolve them. For general setup help, see [Getting Started → Need help?](/docs/getting-started.md#need-help).

package/docs/forge-auto.md

@@ -1,43 +1,43 @@
 ---
 title: Forge-Auto
-description: Zero-ceremony skill creation — one command turns a GitHub repo, doc URL, or pinned version into a verified skill
+description: Zero-ceremony skill creation. One command turns a GitHub repo (optionally pinned to a version) or a documentation URL into a verified skill
 ---
 
-Forge-Auto is a [pipeline alias](/docs/workflows.md#pipeline-aliases) that chains five workflows into a single command. Give it a repo URL, a documentation URL, or a pinned version, and it produces a verified skill in 3–5 minutes with zero configuration.
+Forge-Auto turns a library's repo or documentation site into a verified skill with one command. Under the hood it is a [pipeline alias](/docs/workflows.md#pipeline-aliases): a short name that runs five workflows in a row. You write no brief and make no scope decisions, and a typical run takes about 3 to 5 minutes.
 
-If you're new to SKF and want to try it without reading anything else, start here.
+If you're new to SKF and want to try it without reading anything else, start here. Do one thing first: after installing SKF, run `@Ferris SF` once so SKF can detect your tools and set your forge tier (Quick, Forge, Forge+ or Deep). Without it, the first stage stops and asks you to run setup.
 
 ---
 
 ## Invocation
 
-Three input types, one command pattern:
+Two kinds of target, one command pattern. The lines below are a repo URL, a doc URL (docs-only), and a repo URL pinned to a version:
 
 ```
-@Ferris forge-auto https://github.com/honojs/hono                  — repo URL
-@Ferris forge-auto https://docs.example.com                         — doc URL (docs-only)
-@Ferris forge-auto https://github.com/honojs/hono --pin v4.6.0      — pinned version
+@Ferris forge-auto https://github.com/honojs/hono
+@Ferris forge-auto https://docs.example.com
+@Ferris forge-auto https://github.com/honojs/hono --pin v4.6.0
 ```
 
-- **Repo URL** — analyzes the full source repository, extracts exports, and compiles a skill from code + docs.
-- **Doc URL** — skips source analysis entirely and builds the skill from documentation alone. Useful for closed-source libraries or when the docs are the canonical reference.
-- **`--pin <version>`** — targets a specific release. The version tag is resolved during analysis so the resulting skill is locked to that exact API surface.
+- **Repo URL**: analyzes the source repository (GitHub, GitLab or Bitbucket; on any other host, its `.git` clone URL, its address without `https://` or its SSH address), extracts its exports, and compiles a skill from code and docs. A path to a folder on your machine works the same way.
+- **Doc URL**: any other `http://` or `https://` address that is not a clone URL (one ending in `.git` or holding `/_git/`). SKF skips source analysis and builds the skill from the documentation alone, naming it after the site (`docs.example.com` becomes `docs-example-com`). Useful for closed-source libraries or when the docs are the canonical reference. SKF first asks git about the address, and stops in three cases. When git reads the address as a repository, which on most hosts (a self-hosted GitLab, Gitea or Codeberg, for example) is the repository's main page, SKF asks for its `.git` clone URL, its address without `https://` or its SSH address. When the server asks for credentials (a private repository's page, for example), SKF stops too, since it reads no documentation behind a login. When git gets no answer from the address in 20 seconds, SKF asks for the repository's clone URL or SSH address, or a documentation URL that answers. A repository browser page that git cannot read at its address is still read as documentation: a Bitbucket Data Center `/projects/<p>/repos/<r>` page, a SourceForge or Launchpad code page, or a link to a file or folder inside a repository. Give its clone URL instead. Without git installed, SKF reads the address as documentation and warns that it was not checked.
+- **`--pin <version>`**: add it to a GitHub repo URL to target a specific release tag or branch, so the skill is locked to that exact API surface. SKF checks the pin with the GitHub CLI (`gh`), so `gh` must be installed, and it stops if no tag or branch matches. Without `--pin`, SKF pins a GitHub repo to its latest release tag, and otherwise uses the latest commit. A doc URL ignores `--pin`.
 
 ---
 
 ## Pipeline Stages
 
-forge-auto expands to `AN[auto] BS[auto] CS TS[min:90] EX`. The two analysis stages (AN, BS) run in [headless mode](/docs/workflows.md#headless-mode) via their `[auto]` flags — no confirmation gates, no interactive prompts. The compile, test, and export stages then proceed with their standard behaviors once the analysis context is ready.
+forge-auto expands to `AN[auto] BS[auto] CS TS[min:90] EX`. The `[auto]` flag on the two analysis stages (AN, BS) swaps their question-and-answer steps for automatic scoping and briefing. Like every pipeline, forge-auto also runs all five stages in [headless mode](/docs/workflows.md#headless-mode), so no stage stops to ask you anything: each confirmation takes its default answer. The compile, test, and export stages run their usual steps once the analysis context is ready.
 
 | Stage | Workflow | Mode | What Happens |
 |-------|----------|------|-------------|
-| 1 | **Analyze Source** (AN) | `[auto]` | Scans the target, detects shape (`library-API`, `reference-app`, `language-reference`, `stack-compose`, or `unknown`), discovers exports, and generates a scope + brief automatically. |
-| 2 | **Brief Skill** (BS) | `[auto]` | Enriches the auto-generated brief with doc detection results. No interactive scoping — the brief is assembled from AN's output. |
+| 1 | **Analyze Source** (AN) | `[auto]` | Scans the target, detects its shape (`library-API`, `reference-app`, `language-reference` or `stack-compose`), counts its exports, and writes a scope and brief automatically. If the shape is `unknown`, or the repo has no package manifest or language signal SKF can read, AN switches to its full step-by-step analysis instead. |
+| 2 | **Brief Skill** (BS) | `[auto]` | Enriches the auto-generated brief with doc detection results. No interactive scoping: the brief is assembled from AN's output. |
 | 3 | **Create Skill** (CS) | standard | Compiles the skill from the enriched brief. Extracts exports, resolves documentation sources, validates structure. |
-| 4 | **Test Skill** (TS) | `[min:90]` | Verifies completeness with a **90% quality threshold** (stricter than the default 80%). Fail halts the pipeline. |
+| 4 | **Test Skill** (TS) | `[min:90]` | Verifies completeness against a **90% quality threshold** (stricter than the default 80%). A score of at least 80% but under 90% still passes, with an evidence report on what kept it under 90%. A score below 80% fails and stops the pipeline before export. |
 | 5 | **Export Skill** (EX) | standard | Validates the package, generates context snippets, and injects into your IDE's context file. |
 
-Data flows automatically between stages — the brief path from AN feeds BS, the skill name from CS feeds TS, and so on. See [Pipeline Mode](/docs/workflows.md#pipeline-mode) for the general mechanics.
+Data flows automatically between stages: the brief path from AN feeds BS, the skill name from CS feeds TS, and so on. See [Pipeline Mode](/docs/workflows.md#pipeline-mode) for the general mechanics.
 
 ---
 
@@ -45,23 +45,26 @@ Data flows automatically between stages — the brief path from AN feeds BS, the
 
 forge-auto's `[auto]` flags activate several behaviors that normally require manual input:
 
-- **Auto-scope** — shape detection (`library-API`, `reference-app`, `language-reference`, `stack-compose`) drives scope decisions, mapping onto `scope.type` values like `full-library`, `public-api`, and `reference-app`. No interactive scope confirmation.
-- **Auto-brief** — the brief is generated and enriched with doc-detection results in one pass, without the interactive discovery flow that `BS` uses standalone.
-- **Coexistence detection** — if a skill for the same target already exists, forge-auto detects it and offers three options: create alongside (new version), merge into the existing skill, or skip.
-- **Auto-decomposition** — multi-package monorepos (>3 packages) flag a *decomposition candidate*; a cohesion check then decides whether to merge into one cohesive skill (the usual outcome — published monorepos are mostly cohesive) or split into N. Exceeding 500 exports also flags a candidate. The default leans toward a single skill, not one-per-package.
-- **Language-reference handling** — for compiler, interpreter, or parser repos, AN classifies the target as a `language-reference`. For a *whole-language* reference (a compiler/interpreter), the skill's value is the language's prose — the guide and standard-library docs — not compiler internals, so AN seeds the canonical corpora. If none are found it records an honest **DEGRADED** caveat: the skill is low-value as code-only until you attach the language's guide and std/library docs (re-run with a doc URL, or enrich via `US`).
+- **Auto-scope**: shape detection (`library-API`, `reference-app`, `language-reference`, `stack-compose`) decides the scope, and each shape maps to one of three scope types in the brief: `full-library`, `public-api` (a library with more than 200 exports), or `reference-app`. No interactive scope confirmation.
+- **Auto-brief**: the brief is generated and enriched with doc-detection results in one pass, without the interactive discovery flow that `BS` uses standalone.
+- **Coexistence detection**: if a skill with the same source or name already exists, forge-auto leaves it untouched and creates the new skill beside it under a new name ending in `-wiki` (for example `hono-wiki`). The new skill is separate, not a new version of the old one. forge-auto makes this choice for you, because pipelines run without prompts.
+- **Auto-decomposition**: a monorepo with more than 3 packages is a *decomposition candidate*, meaning it could become several skills. A cohesion check then decides whether to merge it into one skill (the usual outcome, since most published monorepos hang together) or split it into one skill per package. When in doubt it merges. A single package with a very large API is never split: it stays one skill, and create-skill moves the detail into `references/` files.
+- **Language-reference handling**: when the repo is a compiler, interpreter, or parser, AN classifies it as a `language-reference`. For a whole language (a compiler or interpreter), the useful content is the language's guide and standard-library docs, not the compiler's internals, so AN adds links to the language's official docs to the brief. If it finds none, the analysis report marks the skill **DEGRADED**: built from code alone, it has little value until you add the guide and standard-library docs. The report suggests enriching the skill with `US`, or running forge-auto on the docs' URL, which builds a separate docs-only skill.
 
 ---
 
 ## Expected Output
 
-A successful forge-auto run produces a complete skill package in your forge data directory, exported and ready for use. The skill includes:
+A successful forge-auto run writes a complete skill package to your skills folder (`skills/<name>/<version>/<name>/` by default), then exports it, ready for use. The package includes:
 
-- `SKILL.md` — the compiled skill with provenance-cited instructions
-- `metadata.json` — version, source, confidence tier breakdown
-- Context snippet injected into your IDE context file (CLAUDE.md, .cursorrules, AGENTS.md, etc.)
+- `SKILL.md`: the compiled skill, where each instruction cites the source it came from
+- `references/`: detail files, one per group of functions or types
+- `metadata.json`: version, source, and how many exports landed in each confidence tier
+- `context-snippet.md`: a short index of the skill, which export adds to your IDE's context file (CLAUDE.md, AGENTS.md or .cursorrules)
 
-The quality threshold is 90% — if the skill scores below that, the pipeline halts at TS with a gap report. Run `@Ferris US` to address gaps, then `@Ferris TS EX` to re-test and export.
+The working files (the brief, the test report and the evidence report) stay in your forge data folder (`forge-data/<name>/` by default). To install the skill in your project, run the `npx skills add ./skills/...` command that export prints.
+
+The quality threshold is 90%. A skill that scores at least 80% but under 90% still passes and is exported, and SKF writes `evidence-report-fallback.md` next to the test report (in `forge-data/<name>/<version>/`) listing the findings that kept it under 90%. The pipeline goes on to export only when Test Skill settles a PASS. A skill that scores below 80% fails: the pipeline stops at TS, before export, and the test report's gap report lists what is missing. Every other verdict but PASS stops it there too: a FAIL that a cap forced although the score clears 90%, INCONCLUSIVE (Test Skill had too little evidence to grade the skill) and pass-with-drift. Any Critical or High gap, such as a wrong or fabricated signature, also stops the pipeline at TS, before a score is computed: Test Skill lists each blocking gap, and the test report's Gap Report puts them first. A missing export is a Medium gap, so it lowers the score and blocks nothing on its own. To fix the gaps, run `@Ferris US <name> --from-test-report`, then `@Ferris TS[<name>] EX` to re-test and export (the brackets give Test Skill the skill's name). That chain has no alias, so Test Skill re-tests it at the default 80% bar. The next time you start Ferris, he offers that repair route himself, at the recorded 90% threshold: accept his offer to keep forge-auto's 90%, or run `@Ferris TS <name> --threshold=90`, then `@Ferris EX <name>`. A plain `@Ferris US <name>` also finds a failed or pass-with-drift test report that is newer than the skill and that no repair has applied, and offers to repair its gaps (`[G]`) or check the source (`[S]`); a headless run checks the source and adds an `unconsumed-test-report` warning.
 
 ---
 
@@ -71,20 +74,20 @@ A typical library (50–200 exports) takes **3–5 minutes** end to end. Factors
 
 - Multi-package monorepos (>3 packages) flag a decomposition candidate; if the cohesion check splits the repo into N skills, add 1–3 minutes
 - Doc-only targets depend on documentation site size and structure
-- Deep-tier projects (with QMD and CCC) spend more time on enrichment
+- The Deep tier (ast-grep, the GitHub CLI and QMD all installed) spends more time on enrichment
 
 ---
 
 ## Migration from `deepwiki` and `onboard`
 
-This pipeline was briefly named `deepwiki`. It was renamed to **`forge-auto`** to avoid confusion with the [DeepWiki MCP](https://deepwiki.com) — `forge-auto` compiles a verified skill from source and **does not** call that MCP or ingest a generated wiki. `deepwiki` still works as a **deprecated alias** (it resolves to `forge-auto` and prints a one-time notice); prefer `forge-auto` going forward.
+This pipeline was briefly named `deepwiki`. It was renamed to **`forge-auto`** to avoid confusion with the [DeepWiki MCP](https://deepwiki.com): `forge-auto` compiles a verified skill from source and **does not** call that MCP or ingest a generated wiki. `deepwiki` still works as a **deprecated alias** (it resolves to `forge-auto` and prints a one-time notice); prefer `forge-auto` going forward.
 
-Before that, the auto pipeline replaced the older `onboard` alias. `onboard` has been removed — running it returns an error directing you to `forge-auto`. The key differences from `onboard`: it ran `AN CS TS EX` with standard (interactive) modes at an 80% quality threshold, whereas `forge-auto` adds auto-scope, auto-brief, a stricter quality gate (90% vs 80%), and accepts repo URLs and doc URLs — not just project paths.
+Before that, the auto pipeline replaced the older `onboard` alias. `onboard` has been removed: running it returns an error directing you to `forge-auto`. The key differences from `onboard`: it ran `AN CS TS EX` at an 80% quality threshold, whereas `forge-auto` adds auto-scope, auto-brief, a higher quality target (90% vs 80%), and accepts doc URLs as well as repo URLs and local project paths.
 
 ---
 
 ## Related
 
-- [Workflows](/docs/workflows.md) — pipeline mode mechanics, headless mode, circuit breakers
-- [Concepts](/docs/concepts.md) — provenance, confidence tiers, drift, version pinning
-- [BMAD Synergy](/docs/bmad-synergy.md) — how forge-auto fits into BMAD phases, and standalone SKF usage
+- [Workflows](/docs/workflows.md): pipeline mode mechanics, headless mode, circuit breakers
+- [Concepts](/docs/concepts.md): provenance, confidence tiers, drift, version pinning
+- [BMAD Synergy](/docs/bmad-synergy.md): how forge-auto fits into BMAD phases, and standalone SKF usage