bmad-module-skill-forge 2.2.0 → 3.0.0

package/docs/agents.md

@@ -1,9 +1,9 @@
 ---
 title: Agents
-description: Ferris agent reference — modes, capabilities, menu, and communication style
+description: Ferris agent reference covering modes, capabilities, menu, and communication style
 ---
 
-## Ferris — Skill Architect & Integrity Guardian
+## Ferris: Skill Architect & Integrity Guardian
 
 **ID:** `skf-forger`
 **Icon:** ⚒️
@@ -12,29 +12,31 @@ description: Ferris agent reference — modes, capabilities, menu, and communica
 The only agent in SKF. Manages the entire skill compilation lifecycle. Ferris extracts, compiles, validates, and packages agent skills from code repositories, documentation, and developer discourse.
 
 **When to Use:**
-Ferris handles all SKF workflows. You always interact with Ferris — he switches modes based on which workflow you invoke.
+Start Ferris with his skill command: `/skf-forger` in Claude Code, Cursor and most other IDEs, `$skf-forger` in Codex, or `/skill:skf-forger` in Pi. In an IDE with no skill command, such as GitHub Copilot, ask your assistant to talk to Ferris. The installer prints the right command for each IDE you picked, and these docs write a request to Ferris as `@Ferris <code>`. He is the front door to every SKF workflow: pick one from his menu, or name it in the same message (`@Ferris QS cognee`), and he switches to the mode that fits it. You can also run a workflow skill directly by name, such as `/skf-setup`, without opening Ferris first.
 
 **Key Capabilities:**
-- AST-backed code extraction via ast-grep
-- Semantic code discovery via cocoindex-code for intelligent file pre-ranking
-- QMD knowledge search for temporal context and evidence
-- agentskills.io specification compliance and validation
+- Code extraction with ast-grep, which reads source code as a syntax tree (AST) so each extracted function cites its real file and line (Forge tier and up)
+- Semantic code search with cocoindex-code (ccc), which ranks the most relevant files before extraction starts (Forge+ tier, or Deep tier when ccc is installed)
+- Knowledge search with QMD, a local search tool, over the source repo's issues, pull requests, changelogs and release notes, for history and evidence (Deep tier)
+- Checks against the agentskills.io specification, the open format agent skills follow
 - GitHub source navigation and package-to-repo resolution
 - Cross-library synthesis for stack skills and integration patterns
 - Skill authoring best practices enforcement (third-person voice, consistent terminology, discovery optimization)
 - Source-derived scripts and assets extraction with provenance tracking
-- **Pipeline orchestration** — chain multiple workflows with automatic data forwarding and circuit breakers
-- **Headless mode** — skip confirmation gates for power users and batch operations (`--headless` or `-H`)
+- **Pipeline orchestration:** chain several workflows in one command; each workflow's output feeds the next, and the chain stops when a step fails its quality check
+- **Headless mode:** run without stopping for confirmations, taking the default answer at each one, for power users and batch runs (`--headless` or `-H`)
+
+The first three depend on your capability tier, which Setup Forge sets from the tools you have installed. See [Capability Tiers](/docs/concepts.md#capability-tiers-quickforgeforgedeep).
 
 **Workflow-Driven Modes:**
 
 | Mode | Behavior | Workflows |
 |------|----------|-----------|
 | **Architect** | Exploratory, structural, assembling | SF, AN, BS, CS, QS, SS, RA |
-| **Surgeon** | Precise, semantic diffing, preserves [MANUAL] | US |
+| **Surgeon** | Precise; finds what changed in the source, regenerates only that, and keeps the sections you wrote by hand (marked `[MANUAL]`) | US |
 | **Audit** | Judgmental, drift reports, completeness scoring | AS, TS, VS |
 | **Delivery** | Packaging, platform-aware, ecosystem-ready | EX |
-| **Management** | Transactional rename/drop and multi-skill campaign orchestration with platform context rebuild | RS, DS, Campaign |
+| **Management** | Safe renames (copy, check, then delete the old name) and drops, both of which refresh your platform context files (CLAUDE.md, AGENTS.md, .cursorrules), plus campaigns that build many skills across sessions | RS, DS, Campaign |
 
 **Communication Style:**
 - During work: structured reports with AST citations, no metaphor
@@ -44,51 +46,35 @@ Ferris handles all SKF workflows. You always interact with Ferris — he switche
 
 **Menu:**
 
-```
-⚒️ Ferris — Skill Forge
-
-START HERE:
-  [SF] Setup Forge — Initialize your forge environment
-  [AN] Analyze Source — Discover what to skill
-
-CREATE:
-  [BS] Brief Skill — Design a skill scope
-  [CS] Create Skill — Compile a skill from brief
-  [QS] Quick Skill — Fast skill, no brief needed
-  [SS] Stack Skill — Consolidated project stack skill (code-mode or compose-mode)
-
-VERIFY:
-  [VS] Verify Stack — Pre-code architecture feasibility check
-  [RA] Refine Architecture — Improve architecture with skill evidence
-
-MAINTAIN:
-  [US] Update Skill — Regenerate after changes
-  [AS] Audit Skill — Check for drift
-  [TS] Test Skill — Verify completeness
-
-DELIVER:
-  [EX] Export Skill — Package for distribution
-
-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
-```
+Ferris shows his menu as a numbered table and waits for your choice. A code, alias or chain you give with the invocation, such as `@Ferris TS cocoindex` or `@Ferris forge-quick cognee`, runs at once, after a one-line greeting. Pick a row by its code (for example `QS`), its number, or a plain request such as "quick skill". Each workflow works best in a fresh session: when you pick one after another workflow already ran in the same session, Ferris first offers the command to paste into a new session, or the remaining steps chained as a pipeline, and runs it in place only if you ask.
+
+| # | Code | What it does | Skill |
+|---|------|--------------|-------|
+| 1 | SF | Set up the forge: detect your tools and set your capability tier | `skf-setup` |
+| 2 | AN | Find what to turn into skills in a large repo, and write recommended skill briefs | `skf-analyze-source` |
+| 3 | BS | Design a skill's scope through guided questions | `skf-brief-skill` |
+| 4 | CS | Compile a skill from a brief (`--batch` compiles several briefs) | `skf-create-skill` |
+| 5 | QS | Build a skill fast from a package name or GitHub URL, no brief needed | `skf-quick-skill` |
+| 6 | SS | Build one skill for your project's stack that shows how its libraries connect | `skf-create-stack-skill` |
+| 7 | US | Regenerate a skill after its source changes, keeping your hand-written `[MANUAL]` sections | `skf-update-skill` |
+| 8 | AS | Check a skill for drift from the current source code | `skf-audit-skill` |
+| 9 | VS | Before you write code, check that your chosen libraries can deliver your architecture and product requirements (PRD) | `skf-verify-stack` |
+| 10 | RA | Improve your architecture document with verified skill data and the VS findings | `skf-refine-architecture` |
+| 11 | TS | Test a skill for completeness, the quality gate before export | `skf-test-skill` |
+| 12 | EX | Package a skill and add its context to CLAUDE.md, AGENTS.md or .cursorrules | `skf-export-skill` |
+| 13 | RS | Rename a skill across all its versions, all or nothing | `skf-rename-skill` |
+| 14 | DS | Drop a skill: deprecate it (soft) or purge it (hard) | `skf-drop-skill` |
+| 15 | CA | Run a campaign that builds many coordinated skills across sessions; start it with `@Ferris CA` or `@Ferris campaign` | `skf-campaign` |
+| 16 | KI | List the knowledge fragments, short reference notes that workflows load when a step needs them | built into Ferris |
+| 17 | WS | Show where each skill stands (briefed, compiled, tested or exported), your forge tier, and the next code to run for each skill in flight | built into Ferris |
+
+On your first run, before Setup Forge has set a capability tier, Ferris points you to five places to start: **SF** (run this first), **forge-auto `<repo-or-doc-url>`** (the one-command verified path, from source to a tested, exported skill), **QS** (the fastest trial: an uncited draft from a GitHub URL or package name), **BS** (the guided path to a high-quality skill) and **KI** (the knowledge fragments). If your project also has the BMAD Method installed, you can ask for the `bmad-help` skill at any time for advice on what to do next. A project with SKF alone does not have it. Say "dismiss" or "exit persona" to leave Ferris.
 
 **Pipeline Aliases:**
 
-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](/docs/workflows.md#pipeline-mode) — the canonical source. Example: `@Ferris forge-quick cognee` chains Quick → Test → Export with automatic data forwarding.
+Ferris can run several workflows in one command. Type their codes in order, such as `QS[cocoindex] TS EX`, or use a named alias: `forge-auto`, `forge`, `forge-quick` or `maintain`. Each workflow's output feeds the next one, the chain stops when a step fails its quality check, and every step runs in headless mode because you already chose the whole sequence. When the first code has no target and its input is not among the arguments, as in `QS TS EX`, Ferris asks for that input first and runs the chain as `QS[<input>] TS EX`. A chain of codes takes that input only in brackets. A headless run, such as one started with `--headless`, stops before any workflow runs, with a halt reason that, for an input a bracket gives, reads `<CODE> needs <input> before the pipeline can start: give it as <CODE>[<input>]` (for example `QS needs a target before the pipeline can start: give it as QS[<target>]`). SF and SS take no input: a chain that starts with SS runs as given, and Ferris looks past a leading SF, so `SF QS TS EX` asks for the target of QS. A chain led by `CS` never halts before it starts: in an interactive run Ferris asks for its skill name unless its bracket holds `auto`, and a `CS` left without one has Create Skill compile the only brief, or halt (`brief-missing`) when it finds none, or several, which it names. A bracket holds one value, so a chain led by `BS` gets its target and skill name only as `forge <repo-url-or-path> <skill-name>`: a chain of the `forge` alias's codes, such as a bare `BS CS TS EX`, with at most a target in BS's bracket and no other bracket but an ignored `min:N`, asks for what BS lacks and runs as that alias. Any other chain led by `BS`, one led by `RS` or `DS` (run those on their own), and one led by any other code but `CS` whose bracket already holds `auto`, or by AN or TS with a `min:N` in its bracket (such as `TS[min:80] EX`), have no bracket for that input: Ferris says why and asks for another invocation, and a headless run halts with that reason. A `min:N` on another code is ignored, so Ferris asks for that code's input as if its bracket were empty. Example: `@Ferris forge-quick cognee` chains Quick → Test → Export. [Workflows → Pipeline Aliases](/docs/workflows.md#pipeline-aliases) has the full alias table and what each alias needs as its target.
 
-`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](/docs/campaign.md) page.
+`campaign` is not a chaining alias. It is a separate workflow (`@Ferris CA` or `@Ferris campaign`) that runs its own pipeline for many skills, builds them in the order their dependencies need, and can resume where it stopped. `CA` cannot be chained with other codes. See the [Campaign](/docs/campaign.md) 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.
+Ferris keeps a memory folder, called the sidecar, at `_bmad/_memory/forger-sidecar/`, so he remembers your setup between sessions. It holds `forge-tier.yaml` (the tools Setup Forge found and your capability tier), `preferences.yaml` (your settings) and the result of your last pipeline run (`pipeline-result-latest.json`). A pipeline keeps its progress in a journal in its own run folder under `_bmad-output/.skf-run/`. If one stopped partway, Ferris reads that journal the next time you open him and offers to resume it, or to repair it first after a failed test, and you can tell him to drop the offer. A start with `--headless` (or `-H`) that names no code, alias or chain stops with "Nothing to run". In `preferences.yaml`, set `headless_mode: true` to make headless the default, or `compact_greeting: true` to get a short greeting without the full menu table (ask for the menu when you want it). [Getting Started → Configuration](/docs/getting-started.md#configuration) lists more preferences.

package/docs/architecture.md

@@ -1,9 +1,9 @@
 ---
 title: Architecture
-description: How Skill Forge runs — the BMAD-backed agent and workflow engine, tool ecosystem, workspace artifacts, security, and the design decisions behind them.
+description: How Skill Forge runs, covering the BMAD-backed agent and workflow engine, the tool ecosystem, workspace artifacts, security, and the design decisions behind them.
 ---
 
-Skill Forge runs entirely inside the LLM context window through structured instructions. There is no external orchestrator — just an agent persona (Ferris), a set of workflows, and a curated knowledge base. This page covers the machinery. For an end-to-end walkthrough, see [How It Works](/docs/how-it-works.md). For what a skill contains, see [Skill Model](/docs/skill-model.md).
+Skill Forge has no server or background service of its own. Your AI coding assistant does the work by following SKF's written instructions one step at a time. When a result must be exact, it runs SKF's Python helper scripts with `uv`. The pieces are an agent persona (Ferris), a set of workflows, a curated knowledge base, and those helper scripts. This page covers that machinery. For an end-to-end walkthrough, see [How It Works](/docs/how-it-works.md). For what a skill contains, see [Skill Model](/docs/skill-model.md).
 
 ---
 
@@ -17,25 +17,28 @@ SKF plugs into BMAD the same way a specialist plugs into a team. It uses the sam
 
 ## Building Blocks
 
-Each workflow directory contains these files, and each has a specific job:
+A workflow directory holds some or all of 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` (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 |
+| `SKILL.md`                | Human-readable entry point: goals, role definition, initialization sequence, invocation contract, and the route to the first step | Entry point per workflow                          |
+| `customize.toml`          | Settings a team or a person can override without editing SKF, such as facts to keep in mind for the whole run or a command to run when the workflow ends. Overrides go in `_bmad/custom/<workflow>.toml` (shared) or `_bmad/custom/<workflow>.user.toml` (personal), for example `_bmad/custom/skf-create-skill.toml`. The workflow reads them by running BMAD Method's customization script, which the BMAD Method installer adds, through `uv`. When that script cannot run, as with SKF installed alone, the workflow prints one warning, adds `customization_resolver_unavailable` to the run's warnings (an interactive Export Skill run only prints it) and applies the bundled settings | Read once, when the workflow starts |
+| `references/*.md` (step files)    | The workflow's stages, one file per step. Each names the next one in its `nextStepFile` front matter, and the last one hands off 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 variables. Steps fill these in to produce the final artifact                          | Read by steps when generating output              |
+| `scripts/*.py`            | Deterministic Python scripts for scoring, validation, structural diffing and manifest operations                         | Invoked by steps via `uv run` for reproducible computation |
 
-**Module-level shared files** (not per-workflow — loaded by the agent or referenced across workflows):
+**Module-level shared files** (not per-workflow; loaded by the agent or referenced across workflows):
 
 | File                      | What it does                                                                                                        | When it loads                                     |
 |---------------------------|---------------------------------------------------------------------------------------------------------------------|---------------------------------------------------|
-| `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`     | 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 |
+| `skf-forger/SKILL.md`     | Ferris's persona: identity, principles, critical actions, and the menu of workflow codes | Loaded when you talk to Ferris. A workflow you start directly, such as `/skf-setup`, runs without it |
+| `knowledge/skf-knowledge-index.csv` | Knowledge fragment index with columns id, name, description, tags, tier, and fragment file path                                                          | Read by steps to decide which fragments to load   |
+| `knowledge/*.md`          | 14 reusable fragments plus the overview.md index: cross-cutting principles and patterns (for example `zero-hallucination.md`, `confidence-tiers.md`, `ccc-bridge.md`) | Selectively read into context when a step directs |
+| `shared/scripts/*.py`     | Cross-workflow Python scripts: preflight checks, manifest operations, managed-section rebuilds, frontmatter and output validation, severity classification, structural diffing, skill inventory, result-envelope emission, language, docs and tools detection, content hashing, and 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 |
+| `shared/health-check.md`  | The last step of every workflow. It looks back at the run and records any problems in SKF's own instructions | After the workflow's final report |
+| `shared/references/*.md`  | Rules several workflows follow, such as pipeline contracts, the result-file format, headless gate handling and Tessl Review | Read by steps on demand |
 
 ```mermaid
 flowchart LR
@@ -50,16 +53,18 @@ flowchart LR
 
 ## Runtime flow
 
-1. **Trigger** — User types `@Ferris CS` (or fuzzy match like `create-skill`). The agent menu in `skf-forger/SKILL.md` maps the trigger to the workflow path.
-2. **Agent loads** — `skf-forger/SKILL.md` injects the persona (identity, principles, critical actions) into the context window. Sidecar files (`forge-tier.yaml`, `preferences.yaml`) are loaded for persistent state.
-3. **Workflow loads** — `SKILL.md` presents the mode choice and routes to the first step file.
-4. **Step-by-step execution** — Only the current step file is in context (just-in-time loading). Each step explicitly names the next one. The LLM reads, executes, saves output, then loads the next step. No future steps are ever preloaded.
-5. **Sub-agent delegation** — When a step needs to process large files (full `SKILL.md` documents, multiple `references/*.md` files, parallel per-library extraction), it spawns sub-agents via the Agent tool instead of loading the content into the parent context. Each sub-agent receives a file path, extracts a compact JSON summary, and returns it. Up to 8 sub-agents run concurrently. The parent collects JSON summaries without ever loading the full source — context isolation by design, preventing one step's data from bloating the window for the next. Used in TS (coverage check), RA (gap analysis), VS (integration verification), AS (structural diff), and SS (parallel extraction).
-6. **Knowledge injection** — Steps consult `skf-knowledge-index.csv` and selectively load fragments from `knowledge/` by tags and relevance. Cross-cutting principles (zero hallucination, confidence tiers, provenance) are loaded only when a step directs — not preloaded.
-7. **Reference and asset injection** — Steps read `references/*.md` and `assets/*.md` files as needed (rules, patterns, schemas, heuristics). This is deliberate context engineering: only the data relevant to the current step enters the context window.
-8. **Script execution** — Steps invoke deterministic Python scripts (`scripts/*.py`, `shared/scripts/*.py`) via `uv run` for computation that must be reproducible: scoring, structural diffing, manifest operations, frontmatter validation. The LLM prepares inputs, the script computes, the LLM uses the output. Same inputs always produce the same result.
-9. **Templates** — When a step produces output (e.g., a skill brief or test report), it reads the template file and fills in placeholders with computed results. The template provides consistent structure; the step provides the content.
-10. **Progress tracking** — Each step appends to an output file with state tracking. Resume mode reads this state and routes to the next incomplete step.
+1. **Trigger**: You type `@Ferris CS` (or a close match like `create-skill`). The menu in `skf-forger/SKILL.md` maps the code to the workflow's skill, here `skf-create-skill`.
+2. **Agent loads**: `skf-forger/SKILL.md` puts the persona (identity, principles, critical actions) into the context window. Ferris also loads its sidecar files (`forge-tier.yaml`, `preferences.yaml`), which keep your tier and preferences between sessions.
+3. **Workflow loads**: The workflow's `SKILL.md` loads your SKF settings from `_bmad/skf/config.yaml` and checks whether the run is headless (runs without asking questions). It then runs BMAD Method's customization script through `uv` to apply any team or personal overrides to the workflow's `customize.toml`, as Ferris does for his own settings when he starts. When that script cannot run (with SKF installed alone it is missing), the workflow prints one warning, adds `customization_resolver_unavailable` to the run's warnings (an interactive Export Skill run only prints it) and keeps the bundled settings. Then it opens the first step file.
+4. **Step-by-step execution**: Only the current step file is in context (just-in-time loading). Each step names the next one. The assistant reads the step, carries it out, saves its output, then loads the next step. Future steps are never loaded early.
+5. **Sub-agent delegation**: Some steps would otherwise read many large files, such as several `SKILL.md` documents or every file that imports a library. These steps hand the reading to sub-agents, which are helper AI sessions started with the Agent tool. Each sub-agent reads its share and returns a short JSON summary. The parent never loads the full text, so the next step starts with an uncluttered context window. AN (per-unit analysis), TS (coverage and coherence checks), VS (integration verification), RA (gap analysis) and SS (per-library extraction) work this way. VS and RA run at most 8 sub-agents at a time. SS runs 3 to 5 at a time in Claude Code.
+6. **Knowledge injection**: Steps consult `skf-knowledge-index.csv` and load only the fragments from `knowledge/` that match by tags and relevance. Cross-cutting principles (zero hallucination, confidence tiers, provenance) load only when a step asks for them, never in advance.
+7. **Reference and asset injection**: Steps read `references/*.md` and `assets/*.md` files as needed (rules, patterns, schemas, heuristics). This is deliberate: only the data the current step needs enters the context window.
+8. **Script execution**: Steps run deterministic Python scripts (`scripts/*.py`, `shared/scripts/*.py`), usually with `uv run`, for work that must be reproducible: scoring, structural diffing, manifest operations, frontmatter validation. The assistant prepares the inputs, the script computes, and the assistant uses the output. The same inputs always give the same result.
+9. **Templates**: When a step produces a report (for example, an analysis report or a test report), it reads the template file and fills in the placeholders with computed results. The template gives the structure, and the step supplies the content.
+10. **Progress tracking**: Most workflows run from start to finish in one session. Analyze Source records its finished steps in its report's front matter (`stepsCompleted`), so a later session can pick up where it stopped. Create Skill's `--batch` mode keeps the batch's progress in a run folder, so a batch that an ended session left goes on where it stopped when you run it again with the same briefs. Campaign keeps its progress in `_campaign-state.yaml`, so `@Ferris campaign resume` can continue it. When a chain of workflows run by Ferris stops early, Ferris offers to resume it from the chain's journal the next time you talk to him.
+
+**Chained runs**: If you give Ferris several codes at once (for example `QS[cocoindex] TS EX`) or a pipeline alias (`forge-auto`, `forge`, `forge-quick`, `maintain`), it runs those workflows one after another without stopping for questions. When the first code, past a leading `SF`, has no target and its input is not among the arguments, Ferris asks for it before the chain starts, and a headless run halts before any workflow runs. A chain led by `CS` never halts there: Ferris asks for its skill name in an interactive run unless its bracket holds `auto`, and otherwise leaves the brief to Create Skill. A bracket holds one value, so a chain led by `BS` gets its target and skill name only as `forge <repo-url-or-path> <skill-name>`, which Ferris asks for when the chain is the `forge` alias's codes with no bracket but a target on `BS` or an ignored `min:N`. `RS` and `DS` run on their own, and a chain led by any other code but `CS` whose bracket already holds `auto`, or by AN or TS with a `min:N` in its bracket, stops with a reason that names the conflict. It passes each workflow's output to the next and halts the chain if a quality check fails. It records the chain's progress in a journal, `pipeline-journal.json`, in the chain's own run folder under `_bmad-output/.skf-run/`, after every workflow, so it can offer to resume a chain that stopped early, even after a closed session. When the chain ends, it writes the chain's result to `pipeline-result-latest.json` in its sidecar folder. See [Pipeline Mode](/docs/workflows.md#pipeline-mode).
 
 ## Ferris Operating Modes
 
@@ -67,11 +72,11 @@ Ferris operates in five workflow-driven modes (mode is determined by which workf
 
 | Mode          | Workflows          | Behavior                                                    |
 |---------------|--------------------|-------------------------------------------------------------|
-| **Architect** | SF, AN, BS, CS, QS, SS, RA | Exploratory, assembling, refining — discovers structure, scopes skills, and improves architecture |
-| **Surgeon**   | US                 | Precise, semantic diffing — preserves [MANUAL] sections during regeneration |
-| **Audit**     | AS, TS, VS         | Judgmental, scoring — evaluates quality and detects drift   |
+| **Architect** | SF, AN, BS, CS, QS, SS, RA | Exploratory, assembling, refining. Discovers structure, scopes skills, and improves architecture |
+| **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, CA        | Transactional rename/drop — copy-verify-delete with platform context rebuild; campaign orchestration sequences workflows and tracks per-skill state |
+| **Management** | RS, DS, CA        | Transactional rename and drop. Rename copies, verifies, then deletes. Drop deprecates or purges. Both rebuild the platform context files afterwards. Campaign (`@Ferris campaign`) runs other workflows in order and tracks each skill's progress |
 
 ---
 
@@ -83,48 +88,49 @@ Ferris operates in five workflow-driven modes (mode is determined by which workf
 |------|-------|---------|
 | **`gh_bridge`** | GitHub CLI (`gh`) | Source code access, issue mining, release tracking, PR intelligence |
 | **`skill-check`** | [thedaviddias/skill-check](https://github.com/thedaviddias/skill-check) | Validation + auto-fix (`check --fix`), quality scoring (0-100), security scan, split-body, diff comparison |
-| **`tessl`** | [tessl](https://tessl.io) | Content quality review, actionability scoring, progressive disclosure evaluation, AI judge with suggestions |
+| **`tessl`** | [tessl](https://tessl.io) (`tessl review run`) | Opt-in Tessl Review of the skill folder: validation checks and AI judges for the description and the content, with suggestions. Off unless `tessl_review_workspace` is set in preferences; needs a Tessl account |
 | **`ast_bridge`** | ast-grep CLI | Structural extraction, custom AST queries, co-import detection |
 | **`ccc_bridge`** | cocoindex-code | Semantic code search, project indexing, file discovery pre-ranking |
 | **`qmd_bridge`** | QMD (local search) | BM25 keyword search, vector semantic search, collection indexing |
-| **`doc_fetcher`** | Environment web tools | Remote documentation fetching for T3-confidence content. Tool-agnostic — uses whatever web fetching is available (Firecrawl, WebFetch, curl, etc.). Output quarantined as T3. |
+| **`doc_fetcher`** | Environment web tools | Fetches remote documentation using whatever web tool your environment has (Firecrawl, WebFetch, curl, and so on). Everything it returns is labeled T3, the lowest confidence tier, and never overrides facts read from the code. |
 
 Bridge names are **conceptual interfaces** used throughout workflow steps. Each bridge resolves to concrete MCP tools, CLI commands, or fallback behavior depending on the IDE environment. See [`src/knowledge/tool-resolution.md`](https://github.com/armelhbobdad/bmad-module-skill-forge/blob/main/src/knowledge/tool-resolution.md) for the complete resolution table.
 
 ### Conflict Resolution
 
-When tools disagree, higher priority wins for instructions. Lower priority is preserved as annotations:
+When tools disagree, the claim with the higher confidence tier wins. Lower-tier content is kept as notes around it and never replaces it.
+
+| Priority | Source | Confidence tier | Tool |
+|----------|--------|-----------------|------|
+| 1 (highest) | AST extraction | T1 | `ast_bridge` |
+| 2 | Source reading without AST | T1-low | `gh_bridge` or local file reads |
+| 3 | QMD evidence | T2 | `qmd_bridge` |
+| 4 | External documentation | T3 | `doc_fetcher` |
 
-| Priority | Source | Tool |
-|----------|--------|------|
-| 1 (highest) | AST extraction | `ast_bridge` |
-| 1b | CCC discovery (pre-ranking) | `ccc_bridge` |
-| 2 | QMD evidence | `qmd_bridge` |
-| 3 | Source reading (non-AST) | `gh_bridge` |
-| 4 | External documentation | `doc_fetcher` |
+`ccc_bridge` is not in this order. It only suggests which files to read first. Every file or name it returns is checked by `ast_bridge` or by source reading before it can become a claim.
 
 ### Manifest Detection
 
-Stack skill workflows detect project dependencies by scanning for manifest files. This isn't a tool — it's a reference pattern ([`skf-create-stack-skill/references/manifest-patterns.md`](https://github.com/armelhbobdad/bmad-module-skill-forge/blob/main/src/skf-create-stack-skill/references/manifest-patterns.md)) consulted by workflow steps:
+Stack Skill (SS) finds a project's dependencies by looking for package manifest files, and Analyze Source (AN) runs the same scan to list a project's manifests. A shared script, [`shared/scripts/skf-scan-manifests.py`](https://github.com/armelhbobdad/bmad-module-skill-forge/blob/main/src/shared/scripts/skf-scan-manifests.py), does the scan, so every run finds the same files. It reads only runtime dependencies and skips development-only ones such as `devDependencies`:
 
 | Ecosystem | Manifest Files |
 |-----------|----------------|
 | JavaScript / TypeScript | `package.json` |
-| Python | `requirements.txt`, `setup.py`, `pyproject.toml`, `Pipfile` |
+| Python | `requirements.txt`, `setup.py`, `setup.cfg`, `pyproject.toml`, `Pipfile` |
 | Rust | `Cargo.toml` |
 | Go | `go.mod` |
-| Java | `pom.xml`, `build.gradle` |
+| Java / Kotlin | `pom.xml`, `build.gradle`, `build.gradle.kts` |
 | Ruby | `Gemfile` |
 | PHP | `composer.json` |
-| .NET | `*.csproj` |
+| Swift | `Package.swift` |
 
-Detection runs at depth 0-1 from project root, excluding dependency trees (`node_modules/`, `.venv/`, `vendor/`), build output (`dist/`, `target/`, `__pycache__/`), and VCS directories.
+The scan looks through every folder under the project root. It skips hidden folders, dependency folders (`node_modules/`, `.venv/`, `venv/`, `vendor/`, `Pods/`) and build output (`dist/`, `build/`, `out/`, `target/`, `__pycache__/`, `.next/`, `.nuxt/`, `.output/`). .NET projects (`*.csproj`) are not detected, so for those, give Stack Skill an explicit list of dependencies.
 
 ---
 
 ## Workspace Artifacts
 
-Build artifacts are committable — another developer can reproduce the same skill:
+Build artifacts are committable, so another developer can reproduce the same skill:
 
 ```
 forge-data/{skill-name}/
@@ -132,14 +138,19 @@ forge-data/{skill-name}/
 └── {version}/
     ├── provenance-map.json     # Source map with AST bindings
     ├── evidence-report.md      # Build audit trail
-    └── extraction-rules.yaml   # Language-specific ast-grep schema
+    ├── extraction-rules.yaml   # Language-specific ast-grep schema
+    ├── test-report-{skill-name}-{run_id}.md   # Written by Test Skill as .skf-test-report-{skill-name}-{run_id}.md, renamed once its checks pass
+    ├── test-findings-{run_id}.json            # Test Skill's gap ledger, which its hard gate reads
+    ├── drift-report-{timestamp}.md            # Written by Audit Skill
+    ├── .skf-audit/{timestamp}/                # The JSON each audit scored its drift from
+    └── {workflow}-result-latest.json          # Machine-readable result of the last run
 ```
 
-The `provenance-map.json` includes per-export `entries` with a `source_library` field identifying which library each export belongs to. For stack skills, it also includes an `integrations` array (cross-library patterns) and a `constituents` array (compose-mode only — tracks the compose-time snapshot of each source skill for staleness detection via metadata hash comparison). The `file_entries` array handles script/asset file-level provenance (SHA-256 hashes, source paths).
+The `provenance-map.json` includes per-export `entries` with a `source_library` field naming the library each export belongs to. For stack skills, it also includes an `integrations` array (cross-library patterns) and, in compose mode only, a `constituents` array. That array records a fingerprint (hash) of each source skill's `metadata.json` at compose time, so Audit Skill can tell when a source skill has changed since. The `file_entries` array tracks copied scripts and assets file by file (SHA-256 hashes, source paths).
 
 ### Pipeline Result Contracts
 
-Pipeline-facing workflows write a machine-readable result JSON file alongside their human-readable output. This enables reliable CI integration and pipeline chaining — downstream workflows or scripts can verify what the prior step produced without parsing markdown. Each run writes two files: a timestamped per-run record (`{skill-name}-result-{YYYYMMDD-HHmmss}.json`) that preserves the full audit trail across retries and aborts, and a stable `{skill-name}-result-latest.json` copy that pipeline consumers read without enumerating timestamps. The schema follows a consistent format: `skill`, `status` (success/failed/partial), `timestamp`, `outputs` (array of produced artifacts with type and path), and a skill-specific `summary` object.
+Pipeline-facing workflows write a machine-readable result JSON file alongside their human-readable output. This makes CI checks and chained runs reliable: a later workflow or script can check what the earlier step produced without parsing Markdown. Each run writes two files. The first is a timestamped record, `{workflow}-result-{YYYYMMDD-HHmmss}.json`, which keeps the full history across retries and aborts. The second is a copy named `{workflow}-result-latest.json`, which other tools read without sorting through timestamps. `{workflow}` names the workflow, not the skill being built. Most workflows leave off the `skf-` prefix (`create-skill`, `update-skill`), but Test Skill keeps it. Its record is `skf-test-skill-result-{YYYYMMDD-HHmmss}.json` (UTC, with `-2` appended when a run already took that second's name), no longer named after the run ID. The files sit next to what the run produced. For Create, Update, Test and Audit Skill, that is the skill's version folder in `forge-data/`. When Ferris runs a chain of workflows, he keeps its state in a journal, `pipeline-journal.json`, in the chain's run folder under `_bmad-output/.skf-run/`, and when the chain ends he writes its result from that journal: `pipeline-result-<YYYYMMDD-HHmmss>.json` and its `pipeline-result-latest.json` copy in his sidecar folder. The schema follows a consistent format: `skill`, `status` (success/failed/partial), `timestamp`, `outputs` (array of produced artifacts with type and path), and a skill-specific `summary` object.
 
 `skills/` and `forge-data/` are committed. Agent memory (`_bmad/_memory/forger-sidecar/`) is gitignored.
 
@@ -188,14 +199,17 @@ src/
 └── module-help.csv           # Skill menu for bmad-help integration
 ```
 
+The installer copies the workflow folders (`skf-*/`), `knowledge/`, `shared/`, `module.yaml` and `module-help.csv` into `_bmad/skf/` in your project. It also copies the workflows, `knowledge/` and `shared/` into the skills folder of each IDE you pick. It copies the `forger/` YAML templates into `_bmad/_memory/forger-sidecar/`, where Ferris keeps your tier and preferences, and never overwrites files already there. Paths on this page such as `knowledge/` or `shared/scripts/` are relative to `_bmad/skf/`.
+
 ---
 
 ## Security
 
-- All tool wrappers use array-style subprocess execution — no shell interpolation
+- SKF's Python helper scripts start other programs with a list of arguments, never a shell command string, so a name or path cannot slip in extra commands. Some steps have the assistant run shell commands itself. The GitHub search for a function's history, for example, first strips every character except letters, digits and underscores from the function names it inserts.
 - Input sanitization: allowlist characters for repo names, file paths, patterns
 - File paths validated against project root (no directory traversal)
-- **Source code never leaves the machine.** All processing is local (AST, QMD, validation).
+- **Source code never leaves the machine.** All processing is local (AST, QMD, validation). The one exception is opt-in: with `tessl_review_workspace` set in preferences, create-skill and test-skill send the compiled skill (its `SKILL.md`, `references/`, `scripts/` and `assets/`, which can hold copies of source files) to Tessl Review, and each review stays in that Tessl workspace's history.
+- The health check at the end of each workflow can report problems in SKF's own instructions as GitHub issues on the SKF repository. Nothing is filed until you review and confirm it. Headless runs save their findings in `forge-data/improvement-queue/` instead.
 - `doc_fetcher` informs users which URLs will be fetched externally before processing
 
 ---
@@ -217,6 +231,6 @@ SKF produces skills compatible with the [agentskills.io](https://agentskills.io)
 | **Solo agent (Ferris), not multi-agent** | One domain (skill compilation) doesn't benefit from handoffs. Shared knowledge base (AST patterns, provenance maps) is the core asset. |
 | **Workflows drive modes, not conversation** | Ferris doesn't auto-switch based on question content. Invoke a workflow to change mode. Predictable behavior. |
 | **Hub-and-spoke cross-knowledge** | Each skill covers one source repository. Stack skills compose cross-library integration patterns in `references/integrations/`, citing each library's own skill. |
-| **Stack skill = compositional** | SKILL.md is the integration layer. references/ contains per-library + integration pairs. Partial regeneration on dependency updates. |
-| **Snippet updates only at export** | Create/update write a draft `context-snippet.md` to `skills/`. Export regenerates the final `context-snippet.md` and publishes it to the platform context file (CLAUDE.md/AGENTS.md/.cursorrules). No managed-section updates in draft workflows. |
+| **Stack skill = compositional** | SKILL.md is the integration layer. `references/` holds one file per library plus one file per integration pair (in `references/integrations/`). When a dependency changes, run Stack Skill (SS) again to rebuild the whole stack skill. Update Skill (US) does not update stack skills. |
+| **New snippets reach context files only at export** | Create and update write a draft `context-snippet.md` next to the skill in `skills/`. Export regenerates the final `context-snippet.md` and writes it into the managed section of each platform context file (CLAUDE.md, AGENTS.md, .cursorrules). Create, quick, stack and update never touch that section. Rename and drop only rebuild it from skills that were already exported. |
 | **Bundle spec, version-pin at release** | Offline-capable. SKF ships with a vendored agentskills.io spec pinned at release time; spec drift is a maintainer concern handled at SKF release, not a runtime concern for users. |