bmad-module-skill-forge 1.9.0 → 2.0.1

package/.claude-plugin/marketplace.json

@@ -30,7 +30,7 @@
       "name": "skill-forge",
       "source": "./",
       "description": "Evidence-based agent skills compiler with progressive capability tiers (Quick/Forge/Forge+/Deep).",
-      "version": "1.9.0",
+      "version": "2.0.1",
       "author": {
         "name": "Armel"
       },

package/.nvmrc

@@ -1 +1 @@
-22
+24

package/README.md

@@ -73,8 +73,11 @@ You'll be prompted for project name, output folders, and IDE configuration. When
 ## Quick Start
 
 1. **Set up your environment:** `@Ferris SF` _(Setup Forge)_ — detects your tools and sets your capability tier
-2. **Generate your first skill:** `@Ferris QS <package-name>` _(Quick Skill)_ — creates a verified skill in under a minute
-3. **Full quality path:** `@Ferris forge <your-library>` chains Brief → Create → Test → Export automatically — or run manually: `@Ferris BS` → clear session → `@Ferris CS` for maximum control
+2. **Zero-ceremony path:** `@Ferris forge-auto <repo-or-doc-url>` _(Forge-Auto)_ — one command turns a repo or doc URL into a verified skill (auto-scope, auto-brief, 90% quality gate, export)
+3. **Fast path:** `@Ferris QS <package-name>` _(Quick Skill)_ — creates a verified skill in under a minute
+4. **Full quality path:** `@Ferris forge <your-library>` chains Brief → Create → Test → Export automatically — or run manually: `@Ferris BS` → clear session → `@Ferris CS` for maximum control
+
+For producing **many coordinated skills** across sessions, `@Ferris campaign` _(Campaign)_ orchestrates the whole set with dependency tracking and resume.
 
 > **Tip:** Start a fresh conversation before each workflow, or use pipeline mode to chain them automatically. SKF workflows load significant context; clearing between them prevents interference.
 
@@ -111,7 +114,7 @@ SKF extracts real function signatures, types, and patterns from code, docs, and
 2. **Lifecycle tooling** — rename skills and drop deprecated versions without manual file surgery. Destructive operations are transactional.
 3. **Follows an open standard** — skills comply with the [agentskills.io](https://agentskills.io) spec and work across Claude, Cursor, Copilot, and other AI agents
 
-> **Every skill ships two files — `SKILL.md` (the full instruction set, loaded on trigger) and `context-snippet.md` (an 80–120 token always-on index injected into `CLAUDE.md` / `AGENTS.md` / `.cursorrules`). Why both?** Per Vercel's agent evals, passive context achieves a **100% pass rate vs. 79% for active skills loaded alone** (see [Skill Model → Dual-Output Strategy](https://armelhbobdad.github.io/bmad-module-skill-forge/skill-model/#dual-output-strategy)).
+> **Every skill ships two files — `SKILL.md` (the full instruction set, loaded on trigger) and `context-snippet.md` (an 80–120 token always-on index that the export step injects into `CLAUDE.md` / `AGENTS.md` / `.cursorrules`). Why both?** Per Vercel's agent evals, passive context achieves a **100% pass rate vs. 79% for active skills loaded alone** (see [Skill Model → Dual-Output Strategy](https://armelhbobdad.github.io/bmad-module-skill-forge/skill-model/#dual-output-strategy)).
 
 ## Verifying a Skill
 
@@ -129,7 +132,7 @@ If it doesn't, that's a bug — open an issue and SKF will republish the skill w
 
 ## Help SKF Improve
 
-Workflows end with a health check that can file bug or friction reports as GitHub issues (auto-deduped by fingerprint — re-reporting is safe). **Please let workflows run to completion**, or [open an issue](https://github.com/armelhbobdad/bmad-module-skill-forge/issues/new/choose) directly. [Full details →](https://armelhbobdad.github.io/bmad-module-skill-forge/workflows/#terminal-step-health-check)
+Workflows end with a health check that files bug reports as GitHub issues (auto-deduped by fingerprint — re-reporting is safe); friction notes go to a local queue you can opt in to submit live. **Please let workflows run to completion**, or [open an issue](https://github.com/armelhbobdad/bmad-module-skill-forge/issues/new/choose) directly. [Full details →](https://armelhbobdad.github.io/bmad-module-skill-forge/workflows/#terminal-step-health-check)
 
 ## Learn More
 
@@ -143,9 +146,11 @@ The docs are organized into three buckets — **Why** (start here), **Try** (do
 **Try**
 
 - **[Getting Started](https://armelhbobdad.github.io/bmad-module-skill-forge/getting-started/)** — Install, first skill, prereqs, and config
+- **[Forge-Auto](https://armelhbobdad.github.io/bmad-module-skill-forge/forge-auto/)** — The zero-ceremony path: one command from a repo or doc URL to a verified skill
+- **[Campaign](https://armelhbobdad.github.io/bmad-module-skill-forge/campaign/)** — Orchestrate many coordinated skills across sessions with dependency tracking and resume
 - **[How It Works](https://armelhbobdad.github.io/bmad-module-skill-forge/how-it-works/)** — Plain-English walkthrough of one skill being built, end to end
 - **[Examples](https://armelhbobdad.github.io/bmad-module-skill-forge/examples/)** — Real-world scenarios with full command transcripts
-- **[Workflows](https://armelhbobdad.github.io/bmad-module-skill-forge/workflows/)** — All 14 workflows with commands and connection diagrams
+- **[Workflows](https://armelhbobdad.github.io/bmad-module-skill-forge/workflows/)** — All 15 workflows with commands and connection diagrams
 
 **Reference**
 

package/docs/_data/pinned.yaml

@@ -5,7 +5,7 @@
 # canonical SKF reference output.
 #
 # Every time a skill is recompiled in oh-my-skills, update the matching
-# entry here and then run `npm run validate:docs-drift` from the SKF repo
+# entry here and then run `npm run docs:validate-drift` from the SKF repo
 # root. The script will:
 #
 #   1. Verify every skill below actually exists at the claimed version and
@@ -26,7 +26,7 @@
 # Enforced two ways: (1) release.yaml bumps this line in the same commit
 # as package.json + marketplace.json on every release; (2) validate-docs-drift.js
 # cross-checks this value against package.json.version and fails on mismatch.
-skf_version: "1.9.0"
+skf_version: "2.0.1"
 
 # Path to the oh-my-skills repo, resolved relative to this repo's root.
 # Override at runtime with the OMS environment variable if oh-my-skills

package/docs/agents.md

@@ -34,7 +34,7 @@ Ferris handles all SKF workflows. You always interact with Ferris — he switche
 | **Surgeon** | Precise, semantic diffing, preserves [MANUAL] | US |
 | **Audit** | Judgmental, drift reports, completeness scoring | AS, TS, VS |
 | **Delivery** | Packaging, platform-aware, ecosystem-ready | EX |
-| **Management** | Transactional rename/drop with platform context rebuild | RS, DS |
+| **Management** | Transactional rename/drop and multi-skill campaign orchestration with platform context rebuild | RS, DS, Campaign |
 
 **Communication Style:**
 - During work: structured reports with AST citations, no metaphor
@@ -72,14 +72,23 @@ DELIVER:
 MANAGE:
   [RS] Rename Skill — Rename across all versions (transactional)
   [DS] Drop Skill — Deprecate or purge a skill version
+  [CA] Campaign — Orchestrate many coordinated skills across sessions (@Ferris campaign)
 
 [WS] Workflow Status — Show current lifecycle position
 [KI] Knowledge Index — List available knowledge fragments
+
+PIPELINE ALIASES:
+  [forge-auto] Zero-ceremony skill from a repo or doc URL
+  [forge] Brief → Create → Test → Export
+  [forge-quick] Quick Skill → Test → Export
+  [maintain] Audit → Update → Test → Export
 ```
 
 **Pipeline Aliases:**
 
-Ferris chains multiple workflows in one command via named aliases (`forge`, `forge-quick`, `onboard`, `maintain`). The full alias table, expansion rules, and target-resolution contract live in [Workflows → Pipeline Mode](../workflows/#pipeline-mode) — the canonical source. Example: `@Ferris forge-quick cognee` chains Quick → Test → Export with automatic data forwarding.
+Ferris chains multiple workflows in one command via named aliases (`forge-auto`, `forge`, `forge-quick`, `maintain`). The full alias table, expansion rules, and target-resolution contract live in [Workflows → Pipeline Mode](../workflows/#pipeline-mode) — the canonical source. Example: `@Ferris forge-quick cognee` chains Quick → Test → Export with automatic data forwarding.
+
+`campaign` is not a chaining alias — it is a standalone orchestrator workflow (`@Ferris campaign`) that runs its own multi-stage pipeline internally, with dependency tracking and resume. See the [Campaign](../campaign/) page.
 
 **Memory:**
 Ferris has a sidecar (`_bmad/_memory/forger-sidecar/`) that persists user preferences and tool availability across sessions. Set `headless_mode: true` in preferences to make headless the default.

package/docs/architecture.md

@@ -22,8 +22,8 @@ Each workflow directory contains these files, and each has a specific job:
 | File                      | What it does                                                                                                        | When it loads                                     |
 |---------------------------|---------------------------------------------------------------------------------------------------------------------|---------------------------------------------------|
 | `SKILL.md`                | Human-readable entry point — goals, role definition, initialization sequence, invocation contract, routes to first step | Entry point per workflow                          |
-| `references/*.md`            | **Create** steps — primary execution, 4–10 sequential files per workflow (the last one always chains to the shared health check) | One at a time (just-in-time)                      |
-| `references/*.md`         | Workflow-specific reference data — rules, patterns, protocols                                                       | Read by steps on demand                           |
+| `references/*.md` (step files)    | **Create** steps — primary execution, sequential step files per workflow (the last one always chains to the shared health check) | One at a time (just-in-time)                      |
+| `references/*.md` (reference data) | Workflow-specific reference data — rules, patterns, protocols                                                       | Read by steps on demand                           |
 | `assets/*.md`             | Workflow-specific output formats — schemas, templates, heuristics                                                   | Read by steps on demand                           |
 | `templates/*.md`          | Output skeletons with placeholder vars — steps fill these in to produce the final artifact                          | Read by steps when generating output              |
 | `scripts/*.py`            | Deterministic Python scripts — scoring, validation, structural diffing, manifest operations                         | Invoked by steps via `uv run` for reproducible computation |
@@ -35,7 +35,7 @@ Each workflow directory contains these files, and each has a specific job:
 | `skf-forger/SKILL.md`     | Expert persona — identity, principles, critical actions, menu of triggers                                           | First — always in context                         |
 | `knowledge/skf-knowledge-index.csv` | Knowledge fragment index — id, name, tags, tier, file path                                                          | Read by steps to decide which fragments to load   |
 | `knowledge/*.md`          | 14 reusable fragments + overview.md index — cross-cutting principles and patterns (e.g., `zero-hallucination.md`, `confidence-tiers.md`, `ccc-bridge.md`) | Selectively read into context when a step directs |
-| `shared/scripts/*.py`     | 7 cross-workflow Python scripts — preflight checks, manifest ops, managed-section rebuilds, frontmatter validation, severity classification, structural diffing, skill inventory | Invoked by any workflow that needs deterministic computation |
+| `shared/scripts/*.py`     | Cross-workflow Python scripts — preflight checks, manifest ops, managed-section rebuilds, frontmatter/output validation, severity classification, structural diffing, skill inventory, result-envelope emission, language/docs/tools detection, content hashing, atomic writes (see [`src/shared/scripts/`](https://github.com/armelhbobdad/bmad-module-skill-forge/tree/main/src/shared/scripts)) | Invoked by any workflow that needs deterministic computation |
 
 ```mermaid
 flowchart LR
@@ -71,7 +71,7 @@ Ferris operates in five workflow-driven modes (mode is determined by which workf
 | **Surgeon**   | US                 | Precise, semantic diffing — preserves [MANUAL] sections during regeneration |
 | **Audit**     | AS, TS, VS         | Judgmental, scoring — evaluates quality and detects drift   |
 | **Delivery**  | EX                 | Validates package, generates snippets, injects into context files |
-| **Management** | RS, DS            | Transactional rename/drop — copy-verify-delete with platform context rebuild |
+| **Management** | RS, DS, CA        | Transactional rename/drop — copy-verify-delete with platform context rebuild; campaign orchestration sequences workflows and tracks per-skill state |
 
 ---
 
@@ -175,6 +175,7 @@ src/
 ├── skf-export-skill/
 ├── skf-rename-skill/
 ├── skf-drop-skill/
+├── skf-campaign/             # Multi-skill campaign orchestration (15th workflow)
 ├── forger/
 │   ├── forge-tier.yaml
 │   ├── preferences.yaml

package/docs/bmad-synergy.md

@@ -9,7 +9,7 @@ This page builds on BMAD concepts (BMM phases, TEA, modules). New to BMAD? Start
 
 ## Launcher Skills vs Content Skills
 
-A BMAD project that also uses SKF ends up with two different kinds of `SKILL.md` files living in the same IDE skills directory. SKF supports 24 IDEs — Claude Code (`.claude/skills/`), Cursor (`.cursor/skills/`), GitHub Copilot (`.github/skills/`), Windsurf (`.windsurf/skills/`), Cline (`.cline/skills/`), Roo Code (`.roo/skills/`), Gemini CLI (`.gemini/skills/`), and 17 others — each with its own skill directory. See the [complete IDE → Context File mapping](https://github.com/armelhbobdad/bmad-module-skill-forge/blob/main/src/skf-export-skill/assets/managed-section-format.md) for the full list. They look similar. They are not the same thing. This is the single most durable point of confusion, so get it straight up front.
+A BMAD project that also uses SKF ends up with two different kinds of `SKILL.md` files living in the same IDE skills directory. SKF supports 23 IDEs — Claude Code (`.claude/skills/`), Cursor (`.cursor/skills/`), GitHub Copilot (`.github/skills/`), Windsurf (`.windsurf/skills/`), Cline (`.cline/skills/`), Roo Code (`.roo/skills/`), Gemini CLI (`.gemini/skills/`), and 16 others — each with its own skill directory. See the [complete IDE → Context File mapping](https://github.com/armelhbobdad/bmad-module-skill-forge/blob/main/src/skf-export-skill/assets/managed-section-format.md) for the full list. They look similar. They are not the same thing. This is the single most durable point of confusion, so get it straight up front.
 
 | | BMAD launcher skill | SKF content skill |
 |---|---|---|
@@ -29,15 +29,15 @@ When a BMAD agent runs a workflow, that workflow can consult SKF content skills
 
 SKF works standalone — no BMAD installation required. If you found this page from a search and don't use the BMAD Method, this section is for you.
 
-The fastest way to start is [`deepwiki`](../deepwiki/). One command produces a verified wiki skill in 3–5 minutes with zero configuration:
+The fastest way to start is [`forge-auto`](../forge-auto/). One command produces a verified skill in 3–5 minutes with zero configuration:
 
 ```
-@Ferris deepwiki https://github.com/honojs/hono
+@Ferris forge-auto https://github.com/honojs/hono
 ```
 
-That's it. No brief file, no scope decisions, no multi-step pipeline to learn. deepwiki handles analysis, scoping, compilation, testing (with a 90% quality gate), and export automatically. See the [deepwiki guide](../deepwiki/) for the full syntax and input types.
+That's it. No brief file, no scope decisions, no multi-step pipeline to learn. forge-auto handles analysis, scoping, compilation, testing (with a 90% quality gate), and export automatically. See the [forge-auto guide](../forge-auto/) for the full syntax and input types.
 
-If you later adopt the BMAD Method, the skills you created via deepwiki integrate seamlessly into BMM phases — they become the verified content skills that BMAD workflows consult during planning and implementation. The [phase-by-phase playbook](#skf-and-bmm-phase-by-phase-playbook) below shows exactly where each SKF workflow fits.
+If you later adopt the BMAD Method, the skills you created via forge-auto integrate seamlessly into BMM phases — they become the verified content skills that BMAD workflows consult during planning and implementation. The [phase-by-phase playbook](#skf-and-bmm-phase-by-phase-playbook) below shows exactly where each SKF workflow fits.
 
 ---
 
@@ -45,6 +45,8 @@ If you later adopt the BMAD Method, the skills you created via deepwiki integrat
 
 BMM is BMAD's core [4-phase workflow](https://docs.bmad-method.org/) (Analysis → Planning → Solutioning → Implementation). SKF has five concrete entry points across those phases. The diagram below shows the end-to-end picture; the subsections that follow give the trigger, command, and artifact flow for each phase.
 
+> **Atomic workflows vs pipeline aliases.** The playbook below maps each phase to an *atomic* SKF workflow (`AN`, `BS`, `QS`, `VS`, `CS`…) on purpose — in BMM you often want only part of the chain (a brief to feed a risk register, a quick reference for acceptance criteria). When you instead want the *finished, exported skill* in one command, reach for a pipeline alias: [`forge-auto`](../forge-auto/) collapses `AN → BS → CS → TS → EX` for a single library, and [`campaign`](../campaign/) orchestrates that whole chain across many dependencies. Rule of thumb: **atomic when you want a stage's artifact; alias when you want the verified skill.**
+
 ```mermaid
 flowchart TD
     P1[BMM Phase 1: Analysis<br/>product-brief · research] -.->|unfamiliar deps| AN[SKF: Analyze Source]
@@ -54,12 +56,16 @@ flowchart TD
     P1 --> P2[BMM Phase 2: Planning<br/>create-prd]
     P2 -.->|uncertain API| QS[SKF: Quick Skill]
     QS -.->|verified API ref| P2
+    P2 -.->|"one command → exported skill (alias)"| DW[SKF: forge-auto]
+    DW -.->|verified skill| P2
 
     P2 --> P3[BMM Phase 3: Solutioning<br/>create-architecture]
     P3 -.->|declared stack| VS[SKF: Verify Stack]
     VS --> RA[SKF: Refine Architecture]
     RA -.->|refined arch| P3b[BMM: check-implementation-readiness]
     P3 --> P3b
+    P3 -.->|"15+ deps (alias)"| CAMP[SKF: Campaign Orchestration]
+    CAMP -.->|verified stack| P3b
 
     P3b --> P4[BMM Phase 4: Implementation<br/>create-story · dev-story]
     P4 -.->|story libs| CS[SKF: Create Skill / Stack Skill]
@@ -90,6 +96,8 @@ flowchart TD
 
 **Why now, not later:** Quick Skill is cheap insurance. It takes under a minute and prevents a whole class of "actually that function doesn't exist" moments during story writing.
 
+**Want more than a quick reference?** When the PRD leans heavily on one library and you'd rather have a thorough, doc-enriched skill behind a 90% quality gate than a fast QS pass, run [`@Ferris forge-auto <repo>`](../forge-auto/) instead — one command produces the finished, exported skill (auto-scope, auto-brief, test, export) ready for BMM workflows to consult.
+
 ### Phase 3 — Solutioning
 
 This is the highest-value integration. BMM's architect agent works from assumptions about the declared stack; SKF is how those assumptions become evidence-backed before the team commits to an implementation readiness check.
@@ -110,17 +118,30 @@ flowchart TD
     VS -->|fail / gaps| RA[SKF: Refine Architecture]
     RA -.->|refined draft| VS
     RA --> READY
+
+    ARCH -.->|15+ dependencies| CAMPAIGN[SKF: Campaign Orchestration]
+    CAMPAIGN -->|"automates the full pipeline<br/>for all dependencies"| READY
 ```
 
 The "Pre-Code Architecture Verification — Greenfield Confidence" scenario in [Examples](../examples/) walks through a concrete case of this loop.
 
+#### Campaign Orchestration
+
+**Trigger:** The architecture declares 15+ dependencies — too many for manual one-at-a-time pipeline runs.
+
+**SKF command:** `@Ferris campaign`
+
+**What flows back:** All declared dependencies are skilled in dependency order, verified for cross-skill consistency, and exported as a cohesive set. A campaign report summarizes per-skill quality scores and the overall outcome.
+
+**Why now, not later:** Campaign automates at scale what the VS → RA → SS loop does for individual libraries. Running it during Solutioning means the entire stack is verified before implementation begins — no surprise API gaps mid-sprint.
+
 ### Phase 4 — Implementation
 
 Two distinct triggers fire during Implementation, one at the start of each story and one after each retrospective.
 
 **Trigger A (before `create-story`):** The story touches a library whose API isn't already in a content skill.
 
-**SKF command:** `@Ferris CS` for a single library, or `@Ferris SS` when the story spans several dependencies.
+**SKF command:** `@Ferris CS` for a single library, or `@Ferris SS` when the story spans several dependencies. If there's no brief yet and you want the skill in one shot, [`@Ferris forge-auto <repo>`](../forge-auto/) runs the full analyze → brief → compile → test → export chain from just the repo URL.
 
 **What flows back:** A verified content skill the `dev-story` workflow can consult during implementation — no training-data guessing about function signatures.
 
@@ -182,7 +203,7 @@ Beyond briefing, CIS and SKF don't overlap — CIS covers ideation, storytelling
 
 ## Delivery and Lifecycle in a BMAD Project
 
-`@Ferris EX` is the **only workflow that introduces new skill context** into the three context files that serve all 24 IDEs: `CLAUDE.md` (Claude Code), `.cursorrules` (Cursor), and `AGENTS.md` (the remaining 22 IDEs — GitHub Copilot, Windsurf, Cline, Roo Code, Gemini CLI, and others). Each IDE also has its own skill root directory where skill files are installed (e.g., `.windsurf/skills/`, `.roo/skills/`, `.gemini/skills/`). Create-skill and update-skill produce draft artifacts that never touch those files directly — nothing reaches an agent's passive context until it has been through the EX gate. See [Skill Model → Dual-Output Strategy](../skill-model/#dual-output-strategy) for the architectural rationale.
+`@Ferris EX` is the **only workflow that introduces new skill context** into the three context files that serve all 23 IDEs: `CLAUDE.md` (Claude Code), `.cursorrules` (Cursor), and `AGENTS.md` (the remaining 21 IDEs — GitHub Copilot, Windsurf, Cline, Roo Code, Gemini CLI, and others). Each IDE also has its own skill root directory where skill files are installed (e.g., `.windsurf/skills/`, `.roo/skills/`, `.gemini/skills/`). Create-skill and update-skill produce draft artifacts that never touch those files directly — nothing reaches an agent's passive context until it has been through the EX gate. See [Skill Model → Dual-Output Strategy](../skill-model/#dual-output-strategy) for the architectural rationale.
 
 This matters specifically in a BMAD project: you may have multiple BMAD modules, each with its own launcher skills, plus SKF content skills, all trying to contribute context. The write-guard means only verified, tested SKF skills ever reach an agent's passive context — nothing half-baked sneaks in. `@Ferris EX` injects managed sections that coexist cleanly with whatever BMAD's installer wrote in the same files.
 
@@ -193,5 +214,7 @@ For long-running BMAD projects, `@Ferris RS` (rename) and `@Ferris DS` (drop) ke
 ## Where to Go Next
 
 - [BMAD docs](https://docs.bmad-method.org/) — canonical reference for BMM phases, TEA workflows, BMB / GDS / CIS details, and the full module list
+- [Forge-Auto](../forge-auto/) — the one-command alias that collapses analyze → brief → compile → test → export for a single library
+- [Campaign](../campaign/) — orchestrate the full pipeline across many declared dependencies with dependency ordering and resume
 - [Workflows](../workflows/) — complete SKF workflow reference with commands and connection diagrams
 - [Examples](../examples/) — concrete scenarios including the BMM retrospective loop and greenfield architecture verification

package/docs/campaign.md

@@ -0,0 +1,172 @@
+---
+title: Campaign Orchestration
+description: Multi-library skill production with dependency tracking, file-based state, and resume
+---
+
+Campaign orchestration drives the production of 15+ coordinated skills through the full SKF pipeline (brief, generate, compile, test, export) in dependency order. It sits at the top of the pipeline ladder — it does not produce skill artifacts directly but sequences the workflows that do.
+
+When your architecture declares many dependencies, running individual pipelines one at a time is tedious and error-prone. Campaign automates the entire loop: it reads the dependency graph, sorts skills topologically, drives each one through the pipeline, enforces quality gates, and tracks state to disk so you can resume after a context death or session break.
+
+---
+
+## Invocation
+
+```
+@Ferris campaign                           — start a new campaign
+@Ferris campaign resume                    — resume from the last active skill
+@Ferris campaign resume --from=<skill>     — resume from a specific skill
+@Ferris campaign status                    — read-only progress summary
+```
+
+- **`campaign`** starts a new campaign from stage 0 (Setup). If a `_campaign-state.yaml` already exists, Ferris offers a choice: resume the existing campaign or overwrite with a new one.
+- **`campaign resume`** picks up where the last session left off. State is validated on load — if the state file is corrupted, the `.bak` file is used as a fallback.
+- **`campaign status`** loads and validates the current state, prints the resume-detection summary plus the tail of the decision log, then stops — no backup, no mutation, no chaining. Use it to check on a long-running campaign without advancing it.
+- **`--from=<skill>`** overrides the resume point to the named skill, useful when you want to re-process a specific skill without restarting the entire campaign.
+
+### Override flags
+
+| Flag | Effect |
+|------|--------|
+| `--headless` / `-H` | Auto-proceed every gate with its default action and emit structured output (see [Headless / Automation](#headless--automation)). |
+| `--brief <file>` | Seed targets from a `campaign-brief.yaml` instead of interactive prompts. Implies `--headless`. |
+| `--manifest <file>` | Seed targets from a plain-text `name,repo_url,tier,pin` manifest (one per line; trailing `;dep1,dep2` for `depends_on`). Implies `--headless`. |
+| `--from=<skill>` | Resume override (see above). |
+
+---
+
+## Stages
+
+Campaign runs through 11 stages (0–10). All stages auto-proceed except Export, which requires explicit approval before writing skills to disk.
+
+| Stage | Name | Description | Auto-proceed |
+|-------|------|-------------|--------------|
+| 0 | Setup | Initialize campaign state, detect existing skills, and configure output paths | Yes |
+| 1 | Strategy | Generate the campaign brief from architecture and dependency analysis | Yes |
+| 2 | Pin Validation | Validate version pins for all declared dependencies | Yes |
+| 3 | Provenance | Establish provenance records for each target library | Yes |
+| 4 | Skill Loop | Drive each Tier A skill through its forge pipeline (AN → BS → CS → TS) in dependency order — export is deferred to the gated Export stage | Yes |
+| 5 | Tier B Batch | Process Tier B skills (lower-priority or transitive dependencies) in batch mode | Yes |
+| 6 | Capstone | Generate stack skill(s) that integrate individual skills into a cohesive project context | Yes |
+| 7 | Verification | Run verification passes across all produced skills for cross-skill consistency | Yes |
+| 8 | Refinement | Address gaps found during verification — re-run pipelines for skills that need improvement | Yes |
+| 9 | Export | Write all verified skills to disk and update context files — **requires user approval** | No |
+| 10 | Maintenance | Generate the campaign report and clean up temporary state | Yes |
+
+---
+
+## Key Concepts
+
+### campaign-brief.yaml
+
+A machine-generated brief that captures the full scope of the campaign: which libraries to skill, their version pins, dependency relationships, and quality targets. Created during the Strategy stage from your architecture document and dependency declarations.
+
+### _campaign-state.yaml
+
+The single source of truth for campaign progress. Every state mutation follows a read-backup-modify-write pattern — the current state is backed up before each write, so a crash during write never loses more than one operation. All progress tracking lives here, not in conversation context.
+
+### _campaign-directive.md
+
+A standing directive document that carries cross-cutting instructions for the campaign. See the [campaign directive spec](https://github.com/armelhbobdad/bmad-module-skill-forge/blob/main/src/skf-campaign/references/campaign-directive-spec.md) for the full specification and usage patterns.
+
+### Dependency Tracking
+
+Campaign sorts skills topologically by their dependency graph. If skill B depends on skill A, skill A is produced first. This ensures downstream skills can reference upstream APIs during compilation.
+
+### Tier A vs Tier B
+
+- **Tier A** — primary dependencies declared in the architecture. Each gets a full individual pipeline run (AN → BS → CS → TS) during the Skill Loop stage; the tested skills are exported collectively at the gated Export stage.
+- **Tier B** — secondary or transitive dependencies. Processed in batch during the Tier B Batch stage with lighter-touch quality requirements.
+
+### Customization
+
+Campaign ships a `customize.toml` workflow surface you can tune without forking the skill. The resolver merges three layers (scalars override, arrays append): the bundled `customize.toml`, then a committed team override at `_bmad/custom/<skill-name>.toml`, then a personal (gitignored) override at `_bmad/custom/<skill-name>.user.toml` — both under {project-root}. What you can set:
+
+- **Quality-gate scalars** — `quality_gate_hard`, `quality_gate_soft_target`, `quality_gate_soft_fallback` (the thresholds above).
+- **`campaign_workspace_path`** — relocate the entire campaign workspace (state, backup, brief, archive, decision log) to a shared volume without editing any step file; empty means the default `{forge_data_folder}/_campaign`.
+- **`persistent_facts`** — literal sentences or `file:` references (globs supported) injected into every per-skill kickoff, so house style and guardrails reach the whole campaign.
+- **Template overrides** — `report_template_path`, `kickoff_template_path`, `brief_template_path` for house-style copies.
+- **`on_complete`** — a post-completion hook invoked with `--report-path=<…>` after the report finalizes; hook failures are logged but never fail the campaign.
+- **`activation_steps_prepend` / `activation_steps_append`** — org-wide pre-flight or context-load steps around activation.
+
+See the skill's [SKILL.md](https://github.com/armelhbobdad/bmad-module-skill-forge/blob/main/src/skf-campaign/SKILL.md) for the full merge contract.
+
+---
+
+## Quality Gates
+
+Campaign enforces two types of quality gates:
+
+The bar is **campaign-wide** — one set of thresholds applied to every skill, not a per-pipeline split:
+
+- **Hard gate** (`zero-critical-high`) — zero critical or high-severity issues allowed. Any skill that fails the hard gate is flagged for manual intervention and blocks the campaign from proceeding past that skill.
+- **Soft target** (default 90%) — the score a skill should reach.
+- **Soft fallback** (default 80%) — the floor. A skill scoring at or above the fallback but below the target still proceeds; only a skill below the fallback is treated as a soft-gate miss.
+
+All three are tunable via [customization](#customization); the per-campaign brief and any directive `## Quality Overrides` still take precedence at runtime.
+
+---
+
+## Resume
+
+Campaign is designed around the assumption that context will die. File-based state (`_campaign-state.yaml`) survives context death, session timeouts, and machine restarts.
+
+When you resume:
+
+1. Ferris validates the state file against the campaign schema
+2. Completed skills are skipped automatically
+3. The campaign picks up from the next incomplete skill in dependency order
+4. All cross-skill context (dependency graph, quality scores, provenance records) is restored from disk
+
+Use `--from=<skill>` to override the resume point if you need to re-process a specific skill.
+
+### Re-invocation and recovery
+
+- **`campaign` over an existing state** prompts resume-vs-overwrite. Choosing overwrite first archives the existing `_campaign-state.yaml` and `campaign-brief.yaml` to `archive/{name}-{timestamp}/` and logs it to the decision log, so a new campaign never silently clobbers an old one. In headless mode the default is **resume** — archive-and-overwrite happens only when `--brief`/`--manifest` explicitly seeds a new campaign.
+- **Corrupt primary, valid `.bak`** — resume auto-recovers by restoring the backup over the primary and logging the recovery; if the backup is also unusable it HALTs (exit 9, `corrupt-state`) reporting both errors.
+- **Primary behind the backup** — if the primary looks older than the `.bak` (a possible crash during the last write), Ferris offers `[R]ecover` from the backup or `[K]eep` the primary (the default; headless keeps the primary).
+
+---
+
+## Expected Output
+
+A successful campaign produces:
+
+- **Individual skill packages** — one per dependency, each tested and exported
+- **Stack skill(s)** — capstone skills that integrate individual skills into a cohesive project context
+- **Campaign report** (`campaign-report.md`) — a post-campaign summary with per-skill quality scores, dependency graph visualization, and overall campaign metrics
+- **Headless envelope** (`SKF_CAMPAIGN_RESULT_JSON`) — a structured JSON result for automation consumers
+
+The Export stage (stage 9) is the only non-auto-proceed stage. Ferris presents a summary of all skills to be written and waits for explicit approval before modifying any context files. In headless mode, the write-gate auto-resolves.
+
+---
+
+## Headless / Automation
+
+Campaign is a first-class headless front door for unattended, multi-session production. Add `--headless` / `-H` (or set `headless_mode: true` in preferences); `--brief`/`--manifest` imply it and seed targets non-interactively. In headless mode every confirmation gate auto-proceeds with its default action, each step emits a single-line JSON progress event to **stderr** on entry and exit (`{"stage":N,"name":"<slug>","status":"start|done"}`), and the terminal step emits the `SKF_CAMPAIGN_RESULT_JSON` envelope on stdout.
+
+- **Cancel affordance** — at any interactive gate the operator can type `cancel`, `exit`, or `:q` to leave cleanly; the campaign HALTs with exit code 12 (`user-cancelled`), logs the cancellation, and leaves state intact and resumable. The Export gate is the exception: its own `[C]ancel` exits 11 (`export-cancelled`).
+- **Exit codes** — every HARD HALT exits with a stable, documented code so automators branch on the failure class without grepping message text: `0` success, `3` invalid-state, `4` circular-deps, `5` invalid-pin, `6` inaccessible-repo, `7` dependency-deadlock, `8` missing-brief, `9` corrupt-state, `10` report-failure (degraded — the campaign still completes), `11` export-cancelled, `12` user-cancelled.
+- **Error envelope** — on any HARD HALT the `SKF_CAMPAIGN_RESULT_JSON` envelope is emitted on stderr in its error variant, carrying `status: "error"`, `exit_code`, the `phase` (step slug), and an `error` object with `code` and `message`.
+
+The full exit-code table and envelope schema live in the skill's [SKILL.md](https://github.com/armelhbobdad/bmad-module-skill-forge/blob/main/src/skf-campaign/SKILL.md) under "Exit Codes" and "Result Contract on HARD HALT".
+
+---
+
+## Timing
+
+Campaign duration scales with the number of declared dependencies — each Tier A skill runs a full `AN → BS → CS → TS` pipeline, and Tier B skills run in batch. A campaign is explicitly designed to **span multiple sessions**: file-based state means you can stop after any skill and resume later without losing progress. Factors that affect total time:
+
+- **Skill count and tier mix** — Tier A skills (a full pipeline each) dominate; Tier B batch processing is lighter per skill.
+- **Dependency depth** — deep graphs serialize more work (downstream skills wait on upstream APIs); wide, shallow graphs spread more naturally across sessions.
+- **Capstone breadth** — stack-skill composition (stage 6) grows with the number of constituent skills.
+- **Forge tier** — Deep-tier projects (with QMD and CCC) spend more time per skill on enrichment.
+
+Plan a campaign as multi-session work rather than a single sitting — the resume design above exists precisely so that context death between skills is a non-event.
+
+---
+
+## Related
+
+- [Workflows](../workflows/) — pipeline mode mechanics, headless mode, circuit breakers
+- [forge-auto](../forge-auto/) — zero-ceremony single-skill creation (campaign orchestrates many of these)
+- [BMAD Synergy](../bmad-synergy/) — how campaign fits into BMAD Phase 3 as an orchestration layer

package/docs/examples.md

@@ -101,9 +101,9 @@ Need a specific version? Append `@version`:
 Alex, a platform engineer, adopts BMAD for 10 microservices spanning TypeScript, Go, and Rust.
 
 ```
-@Ferris SF          # Setup — Deep tier detected
+@Ferris SF                                              # Setup — Deep tier detected
 # — clear session —
-@Ferris onboard     # Analyze → Create → Test → Export in one pipeline
+@Ferris forge-auto https://github.com/acme/auth-service   # one service: Analyze → Brief → Create → Test → Export
 ```
 
 Or one workflow per session:
@@ -184,7 +184,11 @@ Skills accumulate over sprints. The agent's coverage improves each iteration.
 
 Blondin, a platform lead, needs cross-service knowledge for 10 microservices so agents can navigate shared types and cross-calls.
 
-One forge project, multiple QMD collections, hub-and-spoke skills with integration patterns.
+```
+@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](../campaign/) for the full stage-by-stage flow.
 
 ### Scenario C: External Dependency
 

package/docs/forge-auto.md

@@ -0,0 +1,90 @@
+---
+title: Forge-Auto
+description: Zero-ceremony skill creation — one command turns a GitHub repo, doc URL, or pinned version into a verified skill
+---
+
+Forge-Auto is a [pipeline alias](../workflows/#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.
+
+If you're new to SKF and want to try it without reading anything else, start here.
+
+---
+
+## Invocation
+
+Three input types, one command pattern:
+
+```
+@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
+```
+
+- **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.
+
+---
+
+## 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](../workflows/#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.
+
+| 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. |
+| 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. |
+| 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](../workflows/#pipeline-mode) for the general mechanics.
+
+---
+
+## Automatic Behaviors
+
+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`).
+
+---
+
+## 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:
+
+- `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.)
+
+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.
+
+---
+
+## Timing
+
+A typical library (50–200 exports) takes **3–5 minutes** end to end. Factors that increase time:
+
+- 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
+
+---
+
+## 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.
+
+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.
+
+---
+
+## Related
+
+- [Workflows](../workflows/) — pipeline mode mechanics, headless mode, circuit breakers
+- [Concepts](../concepts/) — provenance, confidence tiers, drift, version pinning
+- [BMAD Synergy](../bmad-synergy/) — how forge-auto fits into BMAD phases, and standalone SKF usage

package/docs/getting-started.md

@@ -89,6 +89,13 @@ This detects your tools, sets your capability tier, and initializes the forge en
 
 ### 2. Generate your first skill
 
+**Zero-ceremony path (forge-auto):**
+```
+@Ferris forge-auto https://github.com/honojs/hono
+```
+
+One command turns a repo URL (or a doc URL) into a verified skill — auto-scope, auto-brief, a 90% quality gate, and export, with no configuration. If you only read one thing, [start with forge-auto](../forge-auto/).
+
 **Fastest path (Quick Skill):**
 ```
 @Ferris QS https://github.com/bmad-code-org/BMAD-METHOD
@@ -183,6 +190,8 @@ Runtime configuration (tool detection, tier, and collection state) is managed by
 
 ## What's next?
 
+- [Forge-Auto](../forge-auto/) — the zero-ceremony path: one command from repo or doc URL to a verified skill
+- [Campaign](../campaign/) — orchestrate many coordinated skills across sessions with dependency tracking and resume
 - [Agents](../agents/) — learn about Ferris
 - [Workflows](../workflows/) — the full command reference
 - [Examples](../examples/) — real-world scenarios with transcripts

package/docs/how-it-works.md

@@ -27,7 +27,7 @@ Ferris confirms the repository exists, detects its language, finds its version f
 
 ### 3. He extracts the API
 
-He reads cognee's source code, identifies the public exports, and pulls out function signatures, parameter types, and return types. At the Forge tier (with ast-grep installed), each signature is verified against the real syntax tree of the source. At Quick tier (no extra tools), he reads the file directly. Either way, nothing is invented — if he can't cite it, he doesn't include it.
+He reads cognee's source code, identifies the public exports, and pulls out function signatures, parameter types, and return types. Quick Skill always extracts at community quality — it does the same job whatever tools you have installed, reading the source directly to ground every signature. Nothing is invented — if he can't cite it, he doesn't include it.
 
 ### 4. He writes the skill with receipts
 
@@ -41,16 +41,18 @@ await cognee.search(  # [AST:cognee/api/v1/search/search.py:L26]
 
 That tag means: *this came from AST extraction of this exact file at this exact line.* You can click through to the upstream source at the pinned commit and see it yourself.
 
-### 5. You get two files
+### 5. You get a skill package
 
-Ferris writes a `SKILL.md` (the full instruction manual your agent loads on demand) and a `context-snippet.md` (an 80–120 token index). The snippet gets injected into your platform context file (`CLAUDE.md`, `AGENTS.md`, or `.cursorrules`) as an always-on reminder: *"This skill exists; read it before writing cognee code."* Both halves are load-bearing — see the [Dual-Output Strategy](../skill-model/#dual-output-strategy) for why.
+Ferris writes a `SKILL.md` (the full instruction manual your agent loads on demand) and a `context-snippet.md` (an 80–120 token index) alongside it. The snippet is the always-on reminder — *"This skill exists; read it before writing cognee code."* — but it isn't wired in automatically: when you run `export-skill`, the snippet gets injected into your platform context file (`CLAUDE.md`, `AGENTS.md`, or `.cursorrules`). Both halves are load-bearing — see the [Dual-Output Strategy](../skill-model/#dual-output-strategy) for why.
 
 ### 6. The audit trail stays on disk
 
-Alongside the skill, Ferris leaves a `provenance-map.json` (every receipt), an `evidence-report.md` (build audit trail), and the compilation config (`skill-brief.yaml`). Commit these with the skill and any teammate — or any skeptic — can reproduce the same output from the same source.
+Alongside the skill, Ferris leaves a `metadata.json` (the pinned source, commit SHA, and export count) and a timestamped result contract recording exactly what was written. Commit these with the skill and any teammate — or any skeptic — can see what was built from which commit.
 
 That's the whole pipeline. One trigger in, one verifiable skill out, every claim traceable back to a file and a commit.
 
+Quick Skill is the fastest path, not the most thorough one. When you want a full audit trail — a `provenance-map.json` of every receipt and an `evidence-report.md` build log, both produced from a `skill-brief.yaml` — run the brief-driven [`create-skill`](../workflows/#create-skill-cs) path instead.
+
 ---
 
 ## Next