bmad-module-skill-forge 1.9.0 → 2.0.0

package/docs/index.md

@@ -60,8 +60,9 @@ npx bmad-module-skill-forge install
 Then generate your first skill:
 
 ```
-@Ferris SF              # Set up your forge
-@Ferris QS <package>    # Generate a skill in under a minute
+@Ferris SF                       # Set up your forge
+@Ferris forge-auto <repo-or-url>   # Zero-ceremony: a repo or doc URL → verified skill
+@Ferris QS <package>             # Or a fast skill from a package name in under a minute
 ```
 
-See [Getting Started](./getting-started/) for platform support, tier selection, and troubleshooting.
+[forge-auto](./forge-auto/) is the recommended starting point — one command, no configuration. See [Getting Started](./getting-started/) for platform support, tier selection, and troubleshooting.

package/docs/skill-model.md

@@ -92,7 +92,7 @@ This is useful for comparing skill quality across tiers for the same target:
 # 4. Reset to tier_override: ~ (auto-detect)
 ```
 
-Set `tier_override` to `Quick`, `Forge`, `Forge+`, or `Deep`. Set to `~` (null) to return to auto-detection. The override is respected by all tier-aware workflows (CS, SS, US, AS, TS).
+Set `tier_override` to `Quick`, `Forge`, `Forge+`, or `Deep`. Set to `~` (null) to return to auto-detection. The override is respected by all tier-aware workflows (AN, BS, CS, SS, US, AS, TS).
 
 ---
 

package/docs/troubleshooting.md

@@ -27,7 +27,7 @@ If setup reports that ast-grep was not detected, install it to unlock the Forge
 
 ### "No skill brief found"
 
-Run `@Ferris BS` first to create a skill brief, or use `@Ferris QS` for brief-less generation. `CS` requires either a brief or a direct invocation with scope arguments.
+Run `@Ferris BS` first to create a skill brief, or use `@Ferris QS` for brief-less generation. `CS` always requires a brief — either a `skill-brief.yaml` produced by `BS` (or `AN`), or pass the skill name so it resolves one from your forge-data folder. For brief-less generation use `QS`.
 
 ### "Ecosystem check: official skill exists"
 
@@ -41,6 +41,22 @@ Quick tier reads source without AST analysis, so signatures are read directly fr
 
 Install [cocoindex-code](https://github.com/cocoindex-io/cocoindex-code) to unlock the Forge+ tier. CCC indexes your codebase and pre-ranks files by semantic relevance before AST extraction, improving coverage on projects with 500+ files.
 
+### `@Ferris deepwiki` shows a deprecation notice
+
+The auto pipeline was briefly named `deepwiki`; it's now [`forge-auto`](../forge-auto/) — renamed to avoid confusion with the DeepWiki MCP, since the pipeline compiles a verified skill from source and does **not** call that MCP. `deepwiki` still works (it resolves to `forge-auto`) but prints a one-time notice. Switch your commands to `@Ferris forge-auto <repo-or-doc-url>`.
+
+### `@Ferris onboard` returns an error
+
+The `onboard` alias was removed. Its replacement is [`forge-auto`](../forge-auto/), which does everything `onboard` did plus auto-scope, auto-brief, and a stricter 90% quality gate. Run `@Ferris forge-auto <repo-or-doc-url>` instead.
+
+### forge-auto halted at the Test stage
+
+forge-auto runs Test Skill with a stricter **90% quality threshold** (vs the default 80%), so a skill that scores below 90% halts at TS with a gap report rather than exporting a weak skill. Run `@Ferris US` to address the gaps it lists, then `@Ferris TS EX` to re-test and export. If 90% is stricter than you need, run the individual workflows or `forge` instead, which use the default threshold.
+
+### My campaign stopped partway — how do I resume?
+
+Campaign is designed for exactly this. State lives in `_campaign-state.yaml` on disk, so context death, a session timeout, or a machine restart loses nothing. Run `@Ferris campaign resume` — Ferris validates the state file, skips completed skills, and picks up from the next incomplete skill in dependency order. If the state file is corrupted, Ferris falls back to the `.bak` copy automatically. To re-process one specific skill, use `@Ferris campaign resume --from=<skill>`.
+
 ---
 
 ## Still stuck?

package/docs/verifying-a-skill.md

@@ -61,7 +61,7 @@ Every file in the per-skill output carries a specific job. Here's the lookup tab
 | Which symbols are documented and where did each come from? | `forge-data/{name}/{version}/provenance-map.json` |
 | What AST patterns were used for extraction? | `forge-data/{name}/{version}/extraction-rules.yaml` |
 | What signatures, types, and examples did the extractor actually capture? | `forge-data/{name}/{version}/evidence-report.md` |
-| How was the skill scored? Show me the math. | `forge-data/{name}/{version}/test-report-{name}.md` |
+| How was the skill scored? Show me the math. | `forge-data/{name}/{version}/test-report-{name}-{run_id}.md` (per-run, run-id-suffixed — newest wins) |
 | How was the skill scoped, and what was deliberately left out? | `forge-data/{name}/skill-brief.yaml` |
 
 Everything a reader needs to reconstruct the compilation is in the two sibling directories: `skills/` ships to consumers, `forge-data/` is the audit trail.
@@ -169,7 +169,7 @@ score >= threshold  →  PASS  →  Recommend export-skill
 score <  threshold  →  FAIL  →  Recommend update-skill
 ```
 
-The default threshold is **80%**. Pipeline aliases declare their own defaults: `deepwiki` targets **90%**, `forge` and `forge-quick` target **80%**. You can override any default with a custom threshold (e.g., `TS[min:85]`).
+The default threshold is **80%**. Pipeline aliases declare their own defaults: `forge-auto` targets **90%**, `forge` and `forge-quick` target **80%**. You can override any default with a custom threshold (e.g., `TS[min:85]`).
 
 When a skill scores between 80% and its target threshold (e.g., 82% against a 90% target), the soft gate falls back to the 80% floor — the skill passes, but an evidence report is written to `forge-data/{skill}/{version}/evidence-report-fallback.md` documenting the quality compromise.
 

package/docs/why-skf.md

@@ -52,7 +52,7 @@ See the [Verifying a Skill](../verifying-a-skill/) page for the full three-step
 
 ### The curious developer
 
-Your agent just hallucinated a method that doesn't exist, again. You want this to stop, and you don't want to read a 569-line architecture page before running your first command.
+Your agent just hallucinated a method that doesn't exist, again. You want this to stop, and you don't want to read a long architecture reference before running your first command.
 → Start with [Getting Started](../getting-started/).
 
 ### The BMAD user

package/docs/workflows.md

@@ -1,6 +1,6 @@
 ---
 title: Workflows
-description: All 14 SKF workflows with commands, steps, and connection diagram
+description: All 15 SKF workflows with commands, steps, and connection diagram
 ---
 
 Trigger workflows by typing commands to [Ferris](../agents/). See [Concepts](../concepts/) for definitions.
@@ -24,7 +24,10 @@ Trigger workflows by typing commands to [Ferris](../agents/). See [Concepts](../
 **Flags:**
 
 - `--require-tier=<Quick|Forge|Forge+|Deep>` — fail-fast for CI: if the calculated tier does not satisfy the requested tier (tool-prerequisite check, not a name comparison — Deep does NOT subsume Forge+ because Deep does not require ccc), the workflow halts with a "REQUIRED TIER NOT MET" block and exits without chaining to the health check. Pipelines branch on the JSON envelope's `require_tier_satisfied` field.
-- `--headless` / `-H` — see [Headless Mode](#headless-mode) below. For `/skf-setup` specifically, headless mode emits a single-line `SKF_SETUP_RESULT_JSON: {…}` envelope to stdout (schema-locked, includes `tier`, `previous_tier`, `tier_changed`, `tools`, `tools_added`/`removed`, `files_written`, `warnings`, `error`) and SUPPRESSES the human-readable banner — the entire payload pipelines need is on one parseable line.
+- `--orphan-action=<keep|remove>` — resolve the orphan QMD-collection removal gate non-interactively, even outside `--headless`.
+- `--ccc-skip-index` — skip CCC indexing (envelope `ccc_index.status` becomes `"skipped"`) — the fast re-probe lane to refresh the detected tier without paying the full re-index cost.
+- `--quiet` — suppress the human-readable FORGE STATUS banner and emit the envelope only.
+- `--headless` / `-H` — see [Headless Mode](#headless-mode) below. For `/skf-setup` specifically, headless mode emits a single-line `SKF_SETUP_RESULT_JSON: {…}` envelope to stdout (schema-locked, includes `status` — the primary branch field — plus `tier`, `previous_tier`, `tier_changed`, `tools`, `tools_added`/`removed`, `files_written`, `warnings`, `error`) and SUPPRESSES the human-readable banner — the entire payload pipelines need is on one parseable line.
 
 **Agent:** Ferris (Architect mode)
 
@@ -80,6 +83,8 @@ Trigger workflows by typing commands to [Ferris](../agents/). See [Concepts](../
 
 **Purpose:** Brief-less fast skill with package-to-repo resolution.
 
+**Note:** QS is **tier-unaware** — it always runs at community tier and does not use ast-grep, CCC, or QMD even when your forge is configured at Forge+/Deep. For tier-aware compilation, use `BS → CS`, `forge`, or `forge-auto`. See [Skill Model](../skill-model/).
+
 **When to Use:** When you need a skill quickly — no brief needed. Accepts package names or GitHub URLs. Append `@version` to target a specific version (e.g., `@Ferris QS cognee@1.0.0`).
 
 **Key Steps:** Resolve target → Ecosystem check → Quick extract → Compile → Validate → Write
@@ -159,7 +164,7 @@ Trigger workflows by typing commands to [Ferris](../agents/). See [Concepts](../
 
 **Key Steps:** Load skill → Detect mode → Coverage check → Coherence check → External validation (skill-check, tessl) → Hard gate → Score → Gap report
 
-**Scored Categories:** Export Coverage (36%), Signature Accuracy (22%), Type Coverage (14%), Coherence (18%), External Validation (10%). Default pass threshold: **80%** (per-pipeline defaults: deepwiki 90%, forge 80%). Pass routes to Export Skill; fail routes to Update Skill with a gap report. See [Completeness Scoring](../verifying-a-skill/#how-the-score-is-computed) for the full formula and tier adjustments.
+**Scored Categories:** Export Coverage (36%), Signature Accuracy (22%), Type Coverage (14%), Coherence (18%), External Validation (10%). Default pass threshold: **80%** (per-pipeline defaults: forge-auto 90%, forge 80%). Pass routes to Export Skill; fail routes to Update Skill with a gap report. See [Completeness Scoring](../verifying-a-skill/#how-the-score-is-computed) for the full formula and tier adjustments.
 
 **Agent:** Ferris (Audit mode)
 
@@ -211,6 +216,22 @@ Trigger workflows by typing commands to [Ferris](../agents/). See [Concepts](../
 
 ---
 
+## Orchestration Workflows
+
+### Campaign Orchestration
+
+**Command:** `@Ferris campaign`
+
+**Purpose:** Orchestrate multi-library skill production across sessions with dependency tracking and resume.
+
+**When to Use:** When you need to produce 15+ coordinated skills with dependency ordering — too many for manual one-at-a-time pipeline runs.
+
+**Key Steps:** Setup → Strategy → Pin Validation → Provenance → Skill Loop → Tier B Batch → Capstone → Verify → Refine → Export → Maintenance
+
+**Agent:** Ferris (Management mode)
+
+---
+
 ## Management Workflows
 
 ### Rename Skill (RS)
@@ -280,21 +301,36 @@ flowchart TD
     TS --> EX[Export Skill]
 ```
 
-> **One workflow per session** (unless using pipeline mode). Each arrow in the diagrams above represents a new conversation session. Clear your context between workflows for best results — or use pipeline mode to chain them automatically. See [Pipeline Mode](#pipeline-mode) below.
+**Campaign orchestration path:**
+
+```mermaid
+flowchart TD
+    CAMPAIGN[Campaign Orchestration] --> SETUP[Setup + Strategy]
+    SETUP --> PINS[Pin Validation + Provenance]
+    PINS --> LOOP["Skill Loop<br/>(BS → CS → TS → EX per skill)"]
+    LOOP --> BATCH[Tier B Batch]
+    BATCH --> CAP[Capstone — Stack Skill]
+    CAP --> VER[Verify + Refine]
+    VER --> EXPORT[Export — write-gate HALT]
+    EXPORT --> MAINT[Maintenance + Campaign Report]
+```
+
+> **One workflow per session** (unless using pipeline mode or campaign). Each arrow in the standard and compose-mode diagrams represents a new conversation session. Campaign manages its own multi-session orchestration internally — see [Campaign Orchestration](../campaign/). Clear your context between workflows for best results — or use pipeline mode to chain them automatically. See [Pipeline Mode](#pipeline-mode) below.
 
 ---
 
 ## Workflow Categories
 
-| Category                  | Workflows      | Description                                                                                                                      |
-| ------------------------- | -------------- | -------------------------------------------------------------------------------------------------------------------------------- |
-| Core                      | SF, BS, CS, US | Setup, brief, create, and update skills                                                                                          |
-| Feature                   | QS, SS, AN     | Quick skill, stack skill, and analyze source — the [`deepwiki`](#pipeline-aliases) alias chains AN + BS + CS + TS + EX for zero-ceremony wiki-skill creation |
-| Quality                   | AS, TS         | Detect skill drift (AS) and verify skill completeness (TS)                                                                       |
-| Architecture Verification | VS, RA         | Pre-code architecture feasibility and refinement                                                                                 |
-| Management                | RS, DS         | Rename and drop skill versions with transactional safety                                                                         |
-| Utility                   | EX             | Package and export for consumption                                                                                               |
-| In-Agent                  | WS, KI         | WS: show lifecycle position, active briefs, and forge tier; KI: list knowledge fragments (both in-agent, no file-based workflow) |
+| Category                  | Workflows         | Description                                                                                                                      |
+| ------------------------- | ----------------- | -------------------------------------------------------------------------------------------------------------------------------- |
+| Core                      | SF, BS, CS, US    | Setup, brief, create, and update skills                                                                                          |
+| Feature                   | QS, SS, AN        | Quick skill, stack skill, and analyze source                                                                                     |
+| Quality                   | AS, TS            | Detect skill drift (AS) and verify skill completeness (TS)                                                                       |
+| Architecture Verification | VS, RA            | Pre-code architecture feasibility and refinement                                                                                 |
+| Orchestration             | Campaign          | Multi-library skill production with dependency tracking and resume                                                               |
+| Management                | RS, DS            | Rename and drop skill versions with transactional safety                                                                         |
+| Utility                   | EX                | Package and export for consumption                                                                                               |
+| In-Agent                  | WS, KI            | WS: show lifecycle position, active briefs, and forge tier; KI: list knowledge fragments (both in-agent, no file-based workflow) |
 
 ---
 
@@ -313,14 +349,13 @@ Instead of running one workflow per session, you can chain multiple workflows in
 
 ### Pipeline Aliases
 
-The `deepwiki` alias is the recommended way to create wiki skills — one command, zero configuration. It chains five workflows with auto-mode flags so you get a verified skill without touching a brief or scope file.
+The `forge-auto` alias is the recommended way to create skills — one command, zero configuration. It chains five workflows with auto-mode flags so you get a verified skill without touching a brief or scope file.
 
 | Alias         | Expands To                             | First Workflow | Required Target                              |
 | ------------- | -------------------------------------- | -------------- | -------------------------------------------- |
-| `deepwiki`    | `AN[auto] BS[auto] CS TS[min:90] EX`  | AN             | GitHub URL, doc URL, or `--pin <version>`    |
+| `forge-auto`    | `AN[auto] BS[auto] CS TS[min:90] EX`  | AN             | GitHub URL, doc URL, or `--pin <version>`    |
 | `forge`       | `BS CS TS EX`                          | BS             | GitHub URL or local path **+** skill name    |
 | `forge-quick` | `QS TS EX`                            | QS             | GitHub URL **or** package name               |
-| `onboard`     | `AN CS TS EX` *(deprecated — use deepwiki)* | AN        | Project path (defaults to current directory) |
 | `maintain`    | `AS US TS EX`                          | AS             | Existing skill name                          |
 
 **The first workflow's input contract defines what arguments the pipeline needs.** A bare package name works for `forge-quick` (QS resolves packages via the registry) but **not** for `forge` — BS requires both an unambiguous target (URL or path) and a skill name.
@@ -337,14 +372,13 @@ The `deepwiki` alias is the recommended way to create wiki skills — one comman
 ### Examples
 
 ```
-@Ferris deepwiki https://github.com/honojs/hono                     — zero-ceremony wiki skill
-@Ferris deepwiki https://docs.example.com                            — docs-only wiki skill
-@Ferris deepwiki https://github.com/honojs/hono --pin v4.6.0         — pinned version
+@Ferris forge-auto https://github.com/honojs/hono                     — zero-ceremony skill
+@Ferris forge-auto https://docs.example.com                            — docs-only skill
+@Ferris forge-auto https://github.com/honojs/hono --pin v4.6.0         — pinned version
 @Ferris forge-quick @tanstack/query                                  — QS + TS + EX for TanStack Query
 @Ferris forge https://github.com/topoteretes/cognee cognee           — BS + CS + TS + EX, explicit URL + name
 @Ferris forge https://github.com/topoteretes/cognee cognee "public API only"   — with scope hint
 @Ferris maintain cocoindex                                           — AS + US + TS + EX for an existing cocoindex skill
-@Ferris onboard                                                      — AN + CS + TS + EX on the current project
 ```
 
 ---
@@ -364,10 +398,10 @@ You can also set `headless_mode: true` in your forge preferences (`_bmad/_memory
 **Exception — `/skf-setup` headless emits a single-line JSON envelope.** Unlike other workflows, headless `/skf-setup` SUPPRESSES the human-readable status banner entirely and emits exactly one prefixed line on stdout:
 
 ```
-SKF_SETUP_RESULT_JSON: {"skf_setup":{"tier":"Deep","previous_tier":"Forge","tier_changed":true,"tools":{...},"tools_added":[...],"tools_removed":[],"config_path":"...","ccc_index":{...},"files_written":[...],"tier_override_active":false,"tier_override_invalid":false,"require_tier_satisfied":null,"warnings":[],"error":null}}
+SKF_SETUP_RESULT_JSON: {"skf_setup":{"status":"success","tier":"Deep","previous_tier":"Forge","tier_changed":true,"tools":{...},"tools_added":[...],"tools_removed":[],"config_path":"...","ccc_index":{...},"files_written":[...],"tier_override_active":false,"tier_override_invalid":false,"require_tier_satisfied":null,"warnings":[],"error":null}}
 ```
 
-Parent skills and CI pipelines `grep` one line out of the workflow log to learn the outcome — no ASCII-art parsing, no race against the [`forge-tier.yaml`](https://github.com/armelhbobdad/bmad-module-skill-forge/blob/main/src/skf-setup/references/write-config.md) writer. The envelope schema is versioned at [`src/shared/scripts/schemas/skf-setup-result-envelope.v1.json`](https://github.com/armelhbobdad/bmad-module-skill-forge/blob/main/src/shared/scripts/schemas/skf-setup-result-envelope.v1.json) and asserted against on every emit.
+Parent skills and CI pipelines `grep` one line out of the workflow log to learn the outcome — no ASCII-art parsing, no race against the [`forge-tier.yaml`](https://github.com/armelhbobdad/bmad-module-skill-forge/blob/main/src/skf-setup/references/write-config.md) writer. Branch on the top-level `status` field (`success`, `tier_failure`, `write_failure`, or `blocked`) rather than composing the outcome from `require_tier_satisfied` + `error`. The envelope schema is versioned at [`src/shared/scripts/schemas/skf-setup-result-envelope.v1.json`](https://github.com/armelhbobdad/bmad-module-skill-forge/blob/main/src/shared/scripts/schemas/skf-setup-result-envelope.v1.json) and asserted against on every emit.
 
 **Exception — `/skf-quick-skill` headless emits structured progress + result envelopes.** Headless `/skf-quick-skill` runs are first-class building blocks for batch automators. Three operational contracts beyond per-gate auto-proceed:
 
@@ -389,7 +423,7 @@ Parent skills and CI pipelines `grep` one line out of the workflow log to learn
    | 3    | resolution-failure  |
    | 4    | write-failure       |
    | 5    | overwrite-cancelled |
-   | 6    | compile-cancelled   |
+   | 6    | user-cancelled      |
    | 7    | finalize-blocked    |
 
 3. **Error-variant result contract on every HARD HALT.** A `SKF_QUICK_SKILL_RESULT_JSON: {…}` envelope is emitted on `stderr` (always) and copied to `{skill_package}/quick-skill-result-latest.json` when the skill package is known (HALTs at step 5 §1 onward). The schema and full population rules live in [`src/skf-quick-skill/SKILL.md`](https://github.com/armelhbobdad/bmad-module-skill-forge/blob/main/src/skf-quick-skill/SKILL.md) § "Result Contract on HARD HALT".
@@ -415,11 +449,17 @@ Parent skills and CI pipelines `grep` one line out of the workflow log to learn
 
 **Presets (`--preset <name>`).** Loads `{sidecar_path}/brief-presets/{name}.yaml` and merges its keys as defaults at step 1 §8; explicit headless args override preset values. The preset file is YAML containing any subset of the headless args above; unknown fields are ignored with a warning. Useful for repeated patterns — e.g. briefing 5 SaaS SDKs that all share `source_authority=community`, `scope_type=full-library`, `scripts_intent=skip`.
 
+**Exception — the management and verification workflows emit structured result envelopes too.** Beyond per-gate auto-proceed, Drop Skill, Rename Skill, and Refine Architecture each emit a single-line `SKF_*_RESULT_JSON: {…}` envelope on every terminal exit (`status: "success"` on the happy path, `status: "error"` with a typed `halt_reason` on any HARD HALT) and exit with a stable code so automators branch on the failure class without grepping message text. All three honour the universal `cancel`/`exit`/`:q` affordance at any prompt (exit `6`, `halt_reason: "user-cancelled"`).
+
+- **`/skf-drop-skill` (DS)** — exit `2` `input-missing`/`input-invalid`, `4` `write-failure` (covers manifest-write, context-rebuild, and full-purge `delete-failed`), `5` state-conflict (active-version guard). Schema and `halt_reason` list in [`src/skf-drop-skill/SKILL.md`](https://github.com/armelhbobdad/bmad-module-skill-forge/blob/main/src/skf-drop-skill/SKILL.md) § "Exit Codes" / "Result Contract (Headless)".
+- **`/skf-rename-skill` (RS)** — exit `2` `input-missing`/`input-invalid`, `4` `write-failure` (`copy-failed`, `write-failed`, `manifest-write-failed`; the §7 context rebuild is best-effort and never halts), `5` state-conflict (name-collision, source-authority, concurrent-run lock). Schema in [`src/skf-rename-skill/SKILL.md`](https://github.com/armelhbobdad/bmad-module-skill-forge/blob/main/src/skf-rename-skill/SKILL.md) § "Exit Codes" / "Result Contract (Headless)".
+- **`/skf-refine-architecture` (RA)** — exit `2` `input-missing`/`input-invalid`, `4` `write-failure`, `7` `inventory-unreliable`, `8` `recovery-failed` (durability state insufficient to reconstruct findings, or the compiled doc is missing its `## Refinement Summary`). Schema in [`src/skf-refine-architecture/SKILL.md`](https://github.com/armelhbobdad/bmad-module-skill-forge/blob/main/src/skf-refine-architecture/SKILL.md) § "Exit Codes" / "Result Contract (Headless)".
+
 ---
 
 ## Terminal Step: Health Check
 
-All 14 workflows above share the same final step — a **health check** defined in [`src/shared/health-check.md`](https://github.com/armelhbobdad/bmad-module-skill-forge/blob/main/src/shared/health-check.md). This isn't a workflow you invoke directly; there's no command code and no menu entry. Each workflow ends with a dedicated local `step-NN-health-check.md` whose `nextStepFile` points at the shared file, so the health check fires automatically once the main work is done. After the main work is done, Ferris reflects internally on the execution:
+All 15 workflows above share the same final step — a **health check** defined in [`src/shared/health-check.md`](https://github.com/armelhbobdad/bmad-module-skill-forge/blob/main/src/shared/health-check.md). This isn't a workflow you invoke directly; there's no command code and no menu entry. Each workflow ends with a dedicated local `step-NN-health-check.md` whose `nextStepFile` points at the shared file, so the health check fires automatically once the main work is done. After the main work is done, Ferris reflects internally on the execution:
 
 - Did any step instruction lead the agent astray or cause unnecessary back-and-forth?
 - Was any step ambiguous, forcing the agent to guess?

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "bmad-module-skill-forge",
-  "version": "1.9.0",
+  "version": "2.0.0",
   "description": "BMAD module — Turn code and docs into instructions AI agents can actually follow. Progressive capability tiers (Quick/Forge/Forge+/Deep).",
   "keywords": [
     "bmad",
@@ -53,7 +53,7 @@
     "test:cli": "node test/test-cli-integration.js",
     "test:install": "node test/test-installation-components.js",
     "test:knowledge": "node test/test-knowledge-base.js",
-    "test:python": "uv run --with pytest --with pyyaml --with jsonschema pytest test/test-compute-score-contract.py test/test-skf-preflight.py test/test-skf-skill-inventory.py test/test-skf-validate-output.py test/test-skf-validate-frontmatter.py test/test-skf-manifest-ops.py test/test-skf-rebuild-managed-sections.py test/test-skf-atomic-write.py test/test-skf-severity-classify.py test/test-skf-structural-diff.py test/test-skf-detect-tools.py test/test-skf-forge-tier-rw.py test/test-skf-emit-result-envelope.py test/test-skf-qmd-classify-collections.py test/test-skf-merge-ccc-exclusions.py test/test-skf-resolve-package.py test/test-skf-extract-public-api.py test/test-skf-render-quick-metadata.py test/test-skf-validate-brief-inputs.py test/test-skf-emit-brief-result-envelope.py test/test-skf-write-skill-brief.py test/test-skf-detect-workspaces.py test/test-skf-recommend-scope-type.py test/test-skf-detect-language.py test/test-skf-description-guard.py test/test-skf-detect-scripts-assets.py test/test-skf-hash-content.py test/test-skf-validate-brief-schema.py test/test-skf-check-workspace-drift.py test/test-skf-update-active-symlink.py test/test-skf-build-change-manifest.py test/test-skf-provenance-gap-dispatch.py test/test-skf-resolve-authoritative-files.py test/test-skf-scan-manifests.py test/test-skf-pair-intersect.py test/test-skf-enumerate-stack-skills.py test/test-skf-compare-file-hashes.py test/test-skf-load-provenance.py test/test-skf-scan-skill-md-structure.py test/test-skf-disqualify-candidates.py test/test-skf-chain-reachability.py test/test-skf-shape-detect.py test/test-skf-detect-docs.py test/test-skf-step-doc-sources.py test/test-skf-step-doc-drift.py test/test-skf-step-hard-gate.py test/test-skf-per-pipeline-thresholds.py test/test-skf-evidence-report-fallback.py test/test-skf-validate-pins.py test/test-skf-auto-shard.py test/test-skf-preapply.py test/test-skf-step-doc-rot.py -v",
+    "test:python": "uv run --with pytest --with pyyaml --with jsonschema pytest test/test-compute-score-contract.py test/test-skf-preflight.py test/test-skf-skill-inventory.py test/test-skf-validate-output.py test/test-skf-validate-frontmatter.py test/test-skf-manifest-ops.py test/test-skf-rebuild-managed-sections.py test/test-skf-atomic-write.py test/test-skf-severity-classify.py test/test-skf-structural-diff.py test/test-skf-detect-tools.py test/test-skf-forge-tier-rw.py test/test-skf-emit-result-envelope.py test/test-skf-qmd-classify-collections.py test/test-skf-merge-ccc-exclusions.py test/test-skf-resolve-package.py test/test-skf-extract-public-api.py test/test-skf-render-quick-metadata.py test/test-skf-validate-brief-inputs.py test/test-skf-emit-brief-result-envelope.py test/test-skf-write-skill-brief.py test/test-skf-detect-workspaces.py test/test-skf-recommend-scope-type.py test/test-skf-detect-language.py test/test-skf-language-corpora.py test/test-skf-merge-doc-urls.py test/test-skf-derive-assembly-shape.py test/test-skf-description-guard.py test/test-skf-detect-scripts-assets.py test/test-skf-hash-content.py test/test-skf-validate-brief-schema.py test/test-skf-check-workspace-drift.py test/test-skf-update-active-symlink.py test/test-skf-build-change-manifest.py test/test-skf-provenance-gap-dispatch.py test/test-skf-resolve-authoritative-files.py test/test-skf-scan-manifests.py test/test-skf-pair-intersect.py test/test-skf-enumerate-stack-skills.py test/test-skf-compare-file-hashes.py test/test-skf-load-provenance.py test/test-skf-scan-skill-md-structure.py test/test-skf-disqualify-candidates.py test/test-skf-chain-reachability.py test/test-skf-shape-detect.py test/test-skf-detect-docs.py test/test-skf-step-doc-sources.py test/test-skf-step-doc-drift.py test/test-skf-step-hard-gate.py test/test-skf-per-pipeline-thresholds.py test/test-skf-evidence-report-fallback.py test/test-skf-validate-pins.py test/test-skf-auto-shard.py test/test-skf-preapply.py test/test-skf-step-doc-rot.py test/test-skf-campaign-state.py test/test-skf-campaign-pins.py test/test-skf-campaign-deps.py test/test-skf-campaign-report.py test/test-skf-campaign-stepfiles.py test/test-skf-campaign-validate-state.py test/test-skf-campaign-provenance.py test/test-skf-campaign-parse-manifest.py test/test-skf-campaign-render-kickoff.py -v",
     "test:schemas": "node test/test-agent-schema.js",
     "test:workflow": "node test/test-workflow-state.js",
     "validate:refs": "node tools/validate-file-refs.js --strict",

package/src/module-help.csv

@@ -1,6 +1,7 @@
 module,skill,display-name,menu-code,description,action,args,phase,after,before,required,output-location,outputs
 skf,skf-forger,Ferris — Skill Forge Agent,FF,"Skill compilation specialist — the forge master. Invoke to access all SKF workflows via guided menu.",,,anytime,,,false,,
-skf,skf-setup,Setup Forge,SF,"Initialize forge environment — detect tools and set capability tier (Quick/Forge/Forge+/Deep)",,,anytime,,"skf-analyze-source,skf-brief-skill,skf-quick-skill,skf-verify-stack",false,,forge-tier.yaml
+skf,skf-setup,Setup Forge,SF,"Initialize forge environment — detect tools and set capability tier (Quick/Forge/Forge+/Deep)",,,anytime,,"skf-analyze-source,skf-brief-skill,skf-quick-skill,skf-verify-stack,skf-campaign",false,,forge-tier.yaml
+skf,skf-campaign,Campaign,CA,"Orchestrate multi-library skill production across sessions — dependency tracking, file-based state, and resume",,resume [--from=<skill>],anytime,skf-setup,,false,forge_data_folder,_campaign-state.yaml
 skf,skf-analyze-source,Analyze Source,AN,"Discover what to skill in a large repo — produces recommended skill briefs",,,anytime,skf-setup,skf-brief-skill,false,forge_data_folder,skill-brief.yaml
 skf,skf-brief-skill,Brief Skill,BS,"Design a skill scope through guided discovery",,,anytime,"skf-setup,skf-analyze-source",skf-create-skill,false,forge_data_folder,skill-brief.yaml
 skf,skf-create-skill,Create Skill,CS,"Compile a skill from a brief — supports --batch for multiple briefs",,--batch,anytime,skf-brief-skill,"skf-test-skill,skf-create-stack-skill",false,skills_output_folder,SKILL.md

package/src/shared/data/language-corpora.json

@@ -0,0 +1,32 @@
+{
+  "_comment": "Canonical companion prose corpora for whole-language skills (issue #427). A language-reference repo (a compiler/interpreter such as rust-lang/rust) carries the language's CODE; its value as a skill comes from the language's PROSE — the guide/Book, the standard/library API docs, and idioms. README detection (skf-detect-docs.py) is the primary source; this registry guarantees the canonical corpora for well-known languages even when the repo's README does not link them. Keyed by lowercase language id (as emitted by skf-detect-language.py / step-auto-scope.md). URLs are version-agnostic, point at maintained latest-stable aliases, and were verified live. Consumed by skf-language-corpora.py, which emits the brief doc_urls contract {url, label, source} with source fixed to 'language-registry' (issue #432).",
+  "rust": [
+    { "url": "https://doc.rust-lang.org/book/", "label": "The Rust Programming Language (Book)" },
+    { "url": "https://doc.rust-lang.org/std/", "label": "Rust Standard Library" },
+    { "url": "https://doc.rust-lang.org/reference/", "label": "The Rust Reference" }
+  ],
+  "python": [
+    { "url": "https://docs.python.org/3/tutorial/", "label": "The Python Tutorial" },
+    { "url": "https://docs.python.org/3/library/", "label": "Python Standard Library" },
+    { "url": "https://docs.python.org/3/reference/", "label": "Python Language Reference" },
+    { "url": "https://docs.python.org/3/howto/", "label": "Python HOWTOs (idioms)" }
+  ],
+  "go": [
+    { "url": "https://go.dev/tour/", "label": "A Tour of Go" },
+    { "url": "https://go.dev/doc/effective_go", "label": "Effective Go" },
+    { "url": "https://go.dev/ref/spec", "label": "The Go Language Specification" },
+    { "url": "https://pkg.go.dev/std", "label": "Go Standard Library" }
+  ],
+  "typescript": [
+    { "url": "https://www.typescriptlang.org/docs/handbook/intro.html", "label": "TypeScript Handbook" },
+    { "url": "https://www.typescriptlang.org/docs/", "label": "TypeScript Documentation (Reference)" }
+  ],
+  "javascript": [
+    { "url": "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide", "label": "MDN JavaScript Guide" },
+    { "url": "https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference", "label": "MDN JavaScript Reference" }
+  ],
+  "ruby": [
+    { "url": "https://www.ruby-lang.org/en/documentation/quickstart/", "label": "Ruby in Twenty Minutes" },
+    { "url": "https://docs.ruby-lang.org/en/master/", "label": "Ruby Core & Standard Library API" }
+  ]
+}

package/src/shared/references/pipeline-contracts.md

@@ -19,12 +19,15 @@ The forger also accepts common pipeline aliases:
 
 | Alias | Expands To | Description |
 |-------|-----------|-------------|
-| `deepwiki` | `AN[auto] BS[auto] CS TS[min:90] EX` | Full zero-ceremony wiki-skill pipeline |
+| `forge-auto` | `AN[auto] BS[auto] CS TS[min:90] EX` | Zero-ceremony auto-compile pipeline (bare repo/doc URL → verified skill) |
 | `forge` | `BS CS TS EX` | Full skill creation pipeline (brief through export) |
 | `forge-quick` | `QS TS EX` | Quick skill pipeline |
-| `onboard` | `AN CS TS EX` | Full brownfield onboarding (deprecated — use deepwiki) |
 | `maintain` | `AS US TS EX` | Maintenance cycle (audit → update → test → export) |
 
+**Deprecated alias:** `deepwiki` resolves to `forge-auto` (renamed to avoid collision with the DeepWiki MCP — the pipeline auto-forges a verified skill and does not call that MCP). It still works but emits a one-time deprecation notice.
+
+**Note:** `campaign` is a standalone workflow invoked via `@Ferris campaign`, not a pipeline alias. It orchestrates its own multi-stage pipeline internally with dependency tracking and resume.
+
 ## Pipeline Rules
 
 1. **Left to right execution** — each workflow completes before the next begins
@@ -36,7 +39,7 @@ The forger also accepts common pipeline aliases:
 
 ## Pipeline Arguments
 
-Pipeline-level arguments (e.g., `--pin <version>`) are passed to the first workflow's data context. The workflow decides how to consume them. For the `deepwiki` pipeline, `--pin` flows to AN, where `step-auto-scope.md §0b` uses it for pin resolution.
+Pipeline-level arguments (e.g., `--pin <version>`) are passed to the first workflow's data context. The workflow decides how to consume them. For the `forge-auto` pipeline, `--pin` flows to AN, where `step-auto-scope.md §0b` uses it for pin resolution.
 
 ## Data Flow
 

package/src/shared/scripts/schemas/skill-brief.v1.json

@@ -51,7 +51,12 @@
         "required": ["url"],
         "properties": {
           "url": { "type": "string", "minLength": 1 },
-          "label": { "type": "string" }
+          "label": { "type": "string" },
+          "source": {
+            "type": "string",
+            "enum": ["language-registry", "readme-detection", "homepage", "pages-api", "docs-folder"],
+            "description": "Optional per-corpus provenance. `language-registry` marks a registry-guaranteed companion corpus (skf-language-corpora.py); the others mark opportunistically-detected docs by detection method. Absent on legacy/hand-authored entries."
+          }
         }
       },
       "minItems": 1,

package/src/shared/scripts/skf-derive-assembly-shape.py

@@ -0,0 +1,107 @@
+# /// script
+# requires-python = ">=3.10"
+# dependencies = ["pyyaml"]
+# ///
+"""SKF Derive Assembly Shape — decide whether a brief is a whole-language reference.
+
+create-skill's SKILL.md assembly is mostly LLM-driven prose, but the BRANCH
+SELECTION — does this skill get the whole-language "Language Guide" treatment
+(prose foregrounded, compiler internals demoted) or the standard
+library-export layout? — must be deterministic. This helper computes that one
+decision from the brief so the assembler (and the doc-fetch step) branch on a
+machine value instead of grepping free-text `scope.notes`.
+
+The gate is a single, structured, schema-validated condition: the brief's
+`doc_urls` contains at least one entry with `source: "language-registry"`
+(issue #432). Registry-sourced corpora are stamped ONLY by
+skf-language-corpora.py, which is invoked ONLY for a whole-language reference
+(a grammar_file:/tree_triad: signal) in step-auto-scope.md §6b. So the gate
+fires exactly when there is registry-guaranteed prose to foreground, and never
+for an ordinary library, a parser library (pest), a component-library, a
+reference-app, or a docs-only brief — none of which carry a language-registry
+entry. A registry-miss (N==0) whole-language reference carries no such entry
+and is intentionally NOT gated: there is no canonical prose to foreground, so
+it keeps the standard layout (and its scope.notes DEGRADED caveat stands).
+
+Gating on the structured `source` field — not the operator-editable
+`scope.notes` substring — means a hand-edited or interactive brief cannot
+silently disable (or misfire) the override.
+
+CLI:
+  uv run skf-derive-assembly-shape.py <path/to/skill-brief.yaml>
+  cat brief.yaml | uv run skf-derive-assembly-shape.py -
+
+Output (JSON on stdout):
+  {
+    "assembly_shape": "whole-language-reference" | "standard",
+    "gate_signal":    "language-registry" | null
+  }
+
+Exit codes:
+  0  success (shape emitted)
+  2  error (missing/unreadable/invalid brief)
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+
+def derive_assembly_shape(brief: dict[str, Any]) -> dict[str, Any]:
+    """Return the assembly-shape decision for a parsed brief."""
+    doc_urls = brief.get("doc_urls")
+    if isinstance(doc_urls, list):
+        for entry in doc_urls:
+            if isinstance(entry, dict) and entry.get("source") == "language-registry":
+                return {
+                    "assembly_shape": "whole-language-reference",
+                    "gate_signal": "language-registry",
+                }
+    return {"assembly_shape": "standard", "gate_signal": None}
+
+
+def _die(message: str) -> None:
+    json.dump({"error": message}, sys.stderr)
+    sys.stderr.write("\n")
+    sys.exit(2)
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="skf-derive-assembly-shape",
+        description="Decide whether a skill brief is a whole-language reference.",
+    )
+    parser.add_argument(
+        "path",
+        help="path to skill-brief.yaml; pass `-` to read YAML from stdin",
+    )
+    args = parser.parse_args(argv)
+
+    if args.path == "-":
+        text = sys.stdin.read()
+    else:
+        p = Path(args.path)
+        if not p.is_file():
+            _die(f"Brief not found at {p.as_posix()}")
+        text = p.read_text(encoding="utf-8")
+
+    try:
+        brief = yaml.safe_load(text)
+    except yaml.YAMLError as exc:
+        _die(f"Brief is not valid YAML: {exc}")
+    if not isinstance(brief, dict):
+        _die("Brief must be a YAML mapping")
+
+    json.dump(derive_assembly_shape(brief), sys.stdout)
+    sys.stdout.write("\n")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

package/src/shared/scripts/skf-detect-docs.py

@@ -16,7 +16,7 @@ Detection chain (all four methods attempted, results aggregated):
   4. docs_folder    — markdown files in the repo's docs/ directory
 
 CLI:
-  uv run python src/shared/scripts/skf-detect-docs.py \\
+  uv run src/shared/scripts/skf-detect-docs.py \\
       --repo-url <url> [--local-path <path>] [--skip-pages-api]
 
 Input:
@@ -86,13 +86,18 @@ _MD_LINK_RE = re.compile(r"\[([^\]]*)\]\(([^)]+)\)")
 _HTML_LINK_RE = re.compile(r'<a\s[^>]*href=["\']([^"\']+)["\']', re.IGNORECASE)
 _BARE_URL_RE = re.compile(r"^(https?://\S+)$", re.MULTILINE)
 
+# `docs?\.` (not `docs\.`) so a `doc.` subdomain matches too — language doc
+# sites use the singular form (doc.rust-lang.org, doc.qt.io).
 _DOC_DOMAIN_RE = re.compile(
-    r"(?:docs\.|\.readthedocs\.|wiki\.|documentation\.)",
+    r"(?:docs?\.|\.readthedocs\.|wiki\.|documentation\.)",
     re.IGNORECASE,
 )
 
+# Language reference/guide path segments (a Book, a std/library API, a tutorial)
+# are doc URLs even on a bare domain (doc.rust-lang.org/book/, .../std/).
 _DOC_PATH_RE = re.compile(
-    r"(?:/docs/|/documentation/|/api/|/reference/|/guide/|/wiki/)",
+    r"(?:/docs/|/documentation/|/api/|/reference/|/guide/|/wiki/"
+    r"|/book/|/std/|/library/|/tutorial/)",
     re.IGNORECASE,
 )
 

package/src/shared/scripts/skf-detect-language.py

@@ -32,9 +32,10 @@ Detection rules (apply in order, first match wins):
   7. build.gradle (Groovy) — check tree:
        src/main/kotlin/  → kotlin (medium)
        else              → java (medium)
-  8. *.csproj | *.sln    → csharp (high)
-  9. Gemfile             → ruby (high)
- 10. Extension-frequency fallback over the full tree.
+  8. Package.swift       → swift (high)
+  9. *.csproj | *.sln    → csharp (high)
+ 10. Gemfile             → ruby (high)
+ 11. Extension-frequency fallback over the full tree.
        dominant extension >= 50% of code files → that language (medium)
        no clear winner                        → unknown (low)
 
@@ -94,6 +95,7 @@ _MANIFEST_RULES: list[tuple[str, str, str]] = [
     ("go.mod", "go", "go.mod present"),
     ("pom.xml", "java", "pom.xml present"),
     ("build.gradle.kts", "kotlin", "build.gradle.kts present"),
+    ("Package.swift", "swift", "Package.swift present"),
     ("Gemfile", "ruby", "Gemfile present"),
 ]
 

package/src/shared/scripts/skf-emit-result-envelope.py

@@ -54,9 +54,17 @@ Context payload shape (consumed by `emit`):
     "ccc_exclusion_warnings":        ["string", ...],
     "ccc_registry_stale_removed":    ["/path", ...],
     "ccc_indexing_failed_reason":    "string|null",
+    "orphan_auto_resolution":        null|{"action": "keep|remove", "count": int, "source": "headless-default|orphan-action-flag"},
     "error":                         null|{"phase","path","reason"}
   }
 
+  When the step-3 orphan-removal gate is resolved non-interactively
+  (headless default Keep, or an explicit --orphan-action), pass
+  `orphan_auto_resolution` so the audit trail lands in `warnings` —
+  most importantly when the destructive `remove` ran headlessly, which a
+  pipeline otherwise could not distinguish from a no-op by reading the
+  envelope alone.
+
 Caller does NOT need to compute warnings, tools_added/removed, or
 tier_changed — the script derives them from the inputs above.
 
@@ -176,6 +184,15 @@ def _assemble_warnings(payload: dict) -> list[str]:
         warnings.append(
             f"require_tier_failed: missing {', '.join(missing) if missing else '<none>'}"
         )
+    orphan = payload.get("orphan_auto_resolution")
+    if isinstance(orphan, dict) and orphan.get("action"):
+        action = str(orphan.get("action"))
+        count = orphan.get("count", 0)
+        source = str(orphan.get("source", "headless-default"))
+        warnings.append(
+            f"orphan_auto_resolution: {action} {count} orphaned collection(s) "
+            f"(non-interactive, {source})"
+        )
     return warnings