bmad-module-skill-forge 2.2.0 → 4.0.0

package/src/skf-brief-skill/SKILL.md

@@ -11,12 +11,14 @@ Helps the user define what to skill — target repo, scope, language, inclusion/
 
 A good skill brief sets a tight, cohesive boundary: one capability with 3-8 primary functions, an unambiguous public API surface, and a description short enough to fit in a registry row. Briefs that try to cover several unrelated concerns (e.g. authentication *and* data visualization) compile into skills that no agent can route to confidently — a brief covering too much is a worse failure mode than a brief covering too little, and this workflow steers toward the smaller, sharper version when scope is unclear. Scope on cheap signals — manifests, top-level exports, intent — not full AST extraction.
 
-**Ratify path.** A pre-authored `skill-brief.yaml` (typically from `skf-analyze-source`'s `generate-briefs` step) can be *ratified* — reviewed and rewritten in place — instead of re-derived from scratch. Interactively, pass its path at the first prompt; headlessly, pass `from_brief <path>`. See the `from_brief` Inputs cell in `references/invocation-contract.md` for the full ratify contract.
+**Ratify path.** A pre-authored `skill-brief.yaml` (typically from `skf-analyze-source`) can be *ratified*: reviewed and written to `{forge_data_folder}/{name}/skill-brief.yaml` (in place when it already lives there) instead of derived again. Interactively, pass its path at the first prompt; headlessly, pass `from_brief <path>`. `references/invocation-contract.md` states the full ratify contract.
 
 ## Conventions
 
 - Bare paths (e.g. `references/<name>.md`) resolve from the skill root.
-- `references/` holds prompt content carved out of SKILL.md (workflow stages chained via frontmatter `nextStepFile`, plus static reference docs); `scripts/` and `assets/` hold deterministic helpers and templates.
+- **Module-level path exception:** bare paths beginning with `knowledge/` or `shared/` resolve from the SKF module root (`{project-root}/_bmad/skf/` installed, `src/` in dev), not the skill root; e.g. `knowledge/tool-resolution.md` and `shared/health-check.md`.
+- **Sibling skills:** a path that names another SKF skill's folder (`skf-<name>/...`) resolves from the SKF module root, and that skill must be installed with this one.
+- `references/` holds prompt content carved out of SKILL.md (workflow stages chained via frontmatter `nextStepFile`, plus static reference docs); `assets/` holds the brief schema, the scope templates and the description voice examples.
 - `{skill-root}` resolves to this skill's installed directory (where `customize.toml` lives, if present).
 - `{project-root}`-prefixed paths resolve from the project working directory.
 - `{skill-name}` resolves to the skill directory's basename.
@@ -30,59 +32,68 @@ You are a skill scoping architect collaborating with a developer who wants to cr
 These rules apply to every step in this workflow:
 
 - Only load one step file at a time — never preload future steps
-- **Lazy-load references and assets:** `references/*.md` and `assets/*.md` files are loaded inside the section that needs them, not at step entry. If a section is skipped (e.g. `version-resolution.md` when `{extractPublicApiHelper}` already returned a version, `scope-templates.md` for the `docs-only` branch that bypasses §2c), do not load that file. Each unnecessary load costs context (~5-10 KB per reference) and biases the LLM toward consulting material the current path does not need.
+- **Lazy-load references and assets:** `references/*.md` and `assets/*.md` files are loaded inside the section that needs them, not at step entry. If a section is skipped (e.g. `version-resolution.md` when step 2's extractor ran, `scope-templates.md` for the `docs-only` branch that bypasses §2c), do not load that file. Each unnecessary load costs context (~5-10 KB per reference) and biases the LLM toward consulting material the current path does not need.
 - Always communicate in `{communication_language}` (the language for user-facing prose). Written artifact text — the `description`, `notes`, and other free-form fields persisted into `skill-brief.yaml` — is in `{document_output_language}`; per-step rules call this out where it applies (see step 5). The two values may be the same.
 - If `{headless_mode}` is true, auto-proceed through confirmation gates with their default action and log each auto-decision
+- Keep one list of the run's warnings, `workflow_warnings[]`, in the order they are raised: each `warn:` line a step logs, each entry of a helper's `warnings[]` that a step surfaces, and each degraded signal the run goes on past (a truncated tree listing, a failed doc detection or QMD step), one line of text each. A helper warning that is an object, such as the `{field, message}` entries skf-validate-brief-inputs.py and skf-validate-brief-schema.py return, goes in as one line, `<field>: <message>`: the emitter takes only strings, and one object in `warnings` makes it exit non-zero and print no line. The run's `SKF_BRIEF_RESULT_JSON` envelope carries the list as `warnings`, at the end of a successful run and at a halt
+
+## Halt Contract
+
+Every HALT that names a `halt_reason`, in any step file, emits the `SKF_BRIEF_RESULT_JSON` error envelope before it stops when `{headless_mode}` or `{auto_mode}` is true, through the emitter On Activation step 4 resolves:
+
+```bash
+uv run {emitBriefEnvelopeHelper} emit --target stderr <<'SKF_BRIEF_HALT'
+{"status":"error","skill_name":"<skill name>","halt_reason":"<halt_reason>","mode":<"auto" or null>,"warnings":[<workflow_warnings[] as JSON strings>]}
+SKF_BRIEF_HALT
+```
+
+Give the halt's own `halt_reason`: the helper derives `exit_code` from it. `skill_name` is the resolved skill name, or `unknown` while step 1 has not resolved one; `mode` is `"auto"` while `{auto_mode}` is true, else `null`; `warnings` holds `workflow_warnings[]` (`[]` when it is empty). The quoted heredoc hands the payload to the helper as written, so a quote inside a warning needs no shell escaping. Display the line the helper prints verbatim, then HALT. If `{emitBriefEnvelopeHelper}` has no path, or the helper exits non-zero or prints no line, display the halt message alone: a pipeline that sees no envelope line treats the run as not completed cleanly. An interactive run outside `[auto]` mode displays the halt message and emits nothing. A HALT that names no `halt_reason`, such as a helper with no installed path (an install fault: re-install SKF), emits nothing in any mode.
 
 ## On Activation
 
 1. Load config from `{project-root}/_bmad/skf/config.yaml` and resolve:
-   - `project_name`, `output_folder`, `user_name`, `communication_language`, `forge_data_folder`, `sidecar_path`
+   - `project_name`, `output_folder`, `user_name`, `communication_language`, `document_output_language`, `forge_data_folder`, `sidecar_path`
 
-2. **Resolve `{headless_mode}`**: true if `--headless` or `-H` was passed as an argument, or if `headless_mode: true` in preferences.yaml. Default: false.
+2. **Resolve `{headless_mode}`**: true if `--headless` or `-H` was passed as an argument, or if `headless_mode: true` in `{sidecar_path}/preferences.yaml`. Default: false.
+
+   **Resolve `{auto_mode}`**: true when the invocation carries the `[auto]` flag (a pipeline's `BS[auto]`, which step 1 §1b routes to the auto stages), else false.
 
 3. **Resolve workflow customization.** Run:
 
    ```bash
-   python3 {project-root}/_bmad/scripts/resolve_customization.py \
-       --skill {skill-root} --key workflow
+   uv run {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --project-root {project-root} --key workflow
    ```
 
-   The script merges the three customization layers per `bmad-customize`'s structural merge rules (scalars override, arrays append):
-
-   - `{skill-root}/customize.toml` — bundled defaults
-   - `_bmad/custom/<skill-name>.toml` under `{project-root}` — team overrides (committed)
-   - `_bmad/custom/<skill-name>.user.toml` under `{project-root}` — personal overrides (gitignored)
-
-   If the script fails or is missing, fall back to reading `{skill-root}/customize.toml` directly — the bundled defaults are an empty string for each path scalar.
+   It merges the bundled `{skill-root}/customize.toml` with `{project-root}/_bmad/custom/skf-brief-skill.toml` (team overrides, committed) and `.user.toml` (personal overrides, gitignored). When it exits non-zero, prints no JSON or is missing, print one line, `[activation/warn] customization_resolver_unavailable: <reason>` (`<reason>`: its first stderr line, `not found` when the script is missing, `no JSON` when it printed none). If the resolver cannot run, read `{skill-root}/customize.toml` alone and use its bundled defaults: the `{project-root}/_bmad/custom/` overrides do not apply to this run. In that case add `customization_resolver_unavailable: <reason>` to `workflow_warnings[]` as the run's first warning.
 
-   Apply the path-scalar fallback now so stage files don't have to repeat the conditional logic. For each of the three scalars, if the merged value is empty or absent, use the bundled default:
+   Bind the values the stage files use, taking the bundled default when the merged value is empty or absent:
 
-   - `{descriptionVoiceExamplesPath}` ← `workflow.description_voice_examples_path` if non-empty, else `assets/description-voice-examples.md`
-   - `{scopeTemplatesPath}` ← `workflow.scope_templates_path` if non-empty, else `assets/scope-templates.md`
-   - `{briefSchemaPath}` ← `workflow.brief_schema_path` if non-empty, else `assets/skill-brief-schema.md`
-   - `{onCompleteCommand}` ← `workflow.on_complete` if non-empty, else empty string (no-op — write-brief.md skips the hook invocation entirely)
+   - `{descriptionVoiceExamplesPath}` ← `workflow.description_voice_examples_path`, else `assets/description-voice-examples.md`
+   - `{scopeTemplatesPath}` ← `workflow.scope_templates_path`, else `assets/scope-templates.md`
+   - `{onCompleteCommand}` ← `workflow.on_complete`, else empty: no hook, so write-brief.md §6b and step-auto-validate.md §3, the two places it runs, skip it
 
-   Stash all four as workflow-context variables. Stage files reference `{descriptionVoiceExamplesPath}` / `{scopeTemplatesPath}` / `{briefSchemaPath}` / `{onCompleteCommand}` directly — no conditional at the usage site. Empty-string overrides cleanly fall through to the bundled default; non-empty values let orgs swap in house-style copies (or wire in a pipeline hook) without forking the skill.
+   Also apply the array surfaces so they are not silent no-ops: execute each entry in `workflow.activation_steps_prepend` in order now; treat every entry in `workflow.persistent_facts` as standing context for the whole run (`file:`-prefixed entries are paths or globs whose contents load as facts, and the bundled default loads any `project-context.md` under `{project-root}`; an entry prefixed `!` loads nothing and drops each earlier entry it names); then, after activation completes and before step 5 loads the first stage, execute each entry in `workflow.activation_steps_append` in order.
 
-   Also apply the array surfaces so they are not silent no-ops: execute each entry in `workflow.activation_steps_prepend` in order now; treat every entry in `workflow.persistent_facts` as standing context for the whole run (`file:`-prefixed entries are paths or globs whose contents load as facts — the bundled default loads any `project-context.md` under `{project-root}`); then, after activation completes and before step 4 loads the first stage, execute each entry in `workflow.activation_steps_append` in order.
+4. **Resolve the envelope emitter** before any stage can halt: `{emitBriefEnvelopeHelper}` ← `{project-root}/_bmad/skf/shared/scripts/skf-emit-brief-result-envelope.py`, else `{project-root}/src/shared/scripts/skf-emit-brief-result-envelope.py`, the first that exists (no path when neither does). It prints every `SKF_BRIEF_RESULT_JSON` line of the run: a halt's through the Halt Contract above, the success line in write-brief.md §4b or step-auto-validate.md §3. `references/invocation-contract.md` defines the envelope.
 
-4. Load, read the full file, and execute `references/gather-intent.md`.
+5. Load, read the full file, and execute `references/gather-intent.md`.
 
 ## Stages
 
 | # | Step | File | Auto-proceed |
 |---|------|------|--------------|
 | 1 | Gather Intent | references/gather-intent.md | No (interactive) |
+| 1h | Headless Input Gate (headless only) | references/headless-args.md | Yes |
+| 1r | Ratify an Existing Brief (ratify only) | references/gather-intent-ratify.md | No (interactive menu; headless takes [R]) |
 | 1a | Auto-Brief Generation (auto mode only) | references/step-auto-brief.md | Yes |
-| 1b | Auto-Brief Validation (auto mode only) | references/step-auto-validate.md | No (interactive gate — headless auto-approves) |
-| 2 | Analyze Target | references/analyze-target.md | Yes |
+| 1b | Auto-Brief Validation (auto mode only) | references/step-auto-validate.md | Yes |
+| 2 | Analyze Target | references/analyze-target.md | Conditional (a truncated tree, a monorepo) |
 | 3 | Scope Definition | references/scope-definition.md | No (interactive) |
 | 4 | Confirm Brief | references/confirm-brief.md | No (confirm) |
-| 5 | Write Brief | references/write-brief.md | Yes |
+| 5 | Write Brief | references/write-brief.md | Conditional (the brief exists) |
 | 6 | Workflow Health Check (terminal) | references/health-check.md | Yes |
 
-Stages 1a-1b are conditional — they replace stages 2-5 when BS is invoked with the `[auto]` flag via pipeline context. The routing decision is made in stage 1 (gather-intent.md §1b). In auto mode, the chain is: gather-intent.md §1 (forge tier) → §1b (auto check) → step-auto-brief.md → step-auto-validate.md → health-check.md (on [A]pprove or [E]dit) or → confirm-brief.md → write-brief.md → health-check.md (on [R]eject).
+Every run starts in gather-intent.md, whose §1 (run folder, forge tier) serves every mode; its §1b routes by mode. `[auto]` (a pipeline's `BS[auto]`): step-auto-brief.md → step-auto-validate.md → health-check.md, in place of stages 2-5 except stage 5's §3b QMD registration, which step-auto-validate.md runs at Deep tier. It stays a separate route by design: the forge-auto pipeline contract gives it doc enrichment (step-auto-brief.md §2-§3), which the ratify and derive routes do not run, and an envelope with `mode: "auto"`. Headless: headless-args.md validates the arguments before any stage uses them, then continues at stage 2. Interactive: the rest of gather-intent.md. A brief to ratify (a brief path at the first prompt, or a headless `from_brief`) goes through gather-intent-ratify.md straight to stage 4, skipping stages 2 and 3.
 
 ## Invocation Contract
 

package/src/skf-brief-skill/assets/description-voice-examples.md

@@ -1,6 +1,6 @@
 # Description Voice Examples
 
-Loaded by step 1 §7b only. The five examples below show the *range* of acceptable voices for the `description` field — they vary in lead, structure, and trigger phrasing on purpose. The point is to anchor the LLM to "two facts must come through (what the skill is, when to use it); everything else is voice — do not template-stamp."
+Loaded by step 1 only: §4 shows the examples to a first-time user, and §7b, or the headless input gate, composes the description from them. The five examples below show the *range* of acceptable voices for the `description` field: they vary in lead, structure, and trigger phrasing on purpose. The point is to anchor the LLM to "two facts must come through (what the skill is, when to use it); everything else is voice: do not template-stamp."
 
 ## Examples
 

package/src/skf-brief-skill/assets/scope-templates.md

@@ -42,8 +42,8 @@ Default inclusions:
 - All public modules: {list from analysis}
 
 Default exclusions:
-- Test files (`**/*.test.*`, `**/*.spec.*`, `**/test/`, `**/tests/`)
-- Build artifacts (`**/dist/`, `**/build/`, `**/target/`)
+- Test files (`**/*.test.*`, `**/*.spec.*`, `**/test/**`, `**/tests/**`)
+- Build artifacts (`**/dist/**`, `**/build/**`, `**/target/**`)
 - Configuration files
 - Documentation source files
 
@@ -51,12 +51,12 @@ Prompt: "Any additional exclusions you'd like to add? Or adjustments to these de
 
 ### Specific Modules Boundaries
 
-**Phase 1 — Module selection:**
+**Phase 1: Module selection**
 
 Present numbered list of modules from step 02 with brief descriptions.
 Prompt: "Which modules would you like to include? (Enter numbers, comma-separated):"
 
-**Phase 2 — Granularity within selected modules:**
+**Phase 2: Granularity within selected modules**
 
 For selected modules, ask:
 - **A)** Everything in those modules (all files)
@@ -66,30 +66,30 @@ Prompt: "Any files or patterns to explicitly exclude within these modules?"
 
 ### Public API Only Boundaries
 
-**Phase 1 — Export selection:**
+**Phase 1: Export selection**
 
 Present numbered list of exports/entry points from step 02.
 Prompt: "Which of these would you like to include? (Enter numbers, or 'all'):"
 
-**Phase 2 — Confirm exclusions:**
+**Phase 2: Confirm exclusions**
 
 Exclusions will include all internal implementation files, tests, and utilities.
 Prompt: "Any additional items you'd like to include or exclude?"
 
 ### Reference App Boundaries
 
-**Phase 1 — Pattern surface intent:**
+**Phase 1: Pattern surface intent**
 
 Ask: "What is the authored pattern surface for this skill? List the files (or directories) the user must touch to adopt the pattern — entry points, config files, lifecycle hooks, build scripts."
 
 - Record the user's list as `scope.tier_a_include` when narrower than a broad `scope.include`. Reference-app briefs benefit strongly from `tier_a_include` because the denominator is small and precise.
 - Prompt follow-up: "Any files outside that list that should still be in scope for completeness (tests, fixtures, supporting configs)?"
 
-**Phase 2 — Scope.include and exclusions:**
+**Phase 2: Scope.include and exclusions**
 
 Set `scope.include` to the pattern-surface file list (or broader union when the author flagged supporting files). Default exclusions mirror the Full Library defaults (tests, build artifacts, docs source). Record `scope.notes` with a one-sentence description of the pattern (e.g., "Embedded Python sidecar pattern for Electron apps — lifecycle orchestration, RPC proxy, build-copy wiring").
 
-**Phase 3 — Confirmation:**
+**Phase 3: Confirmation**
 
 Summary showing: pattern surface count, `tier_a_include` vs `include` distinction, notes. Prompt: "Does this reference-app scope look right? Adjust before continuing."
 
@@ -105,39 +105,32 @@ Prompt: "Any additional documentation URLs to include? Or URLs to exclude from t
 
 ### Component Library Boundaries
 
-**Phase 1 — Registry Detection:**
+On a step 4 `[R]` re-entry, `scope.registry_path`, `scope.demo_patterns` and `scope.ui_variants` hold the previous pass's answers: present each as the current answer of its phase, for the user to keep or change.
 
-Auto-detect or accept explicit `registry_path` from user. Scan source tree for files matching common registry patterns:
-- Files named `registry.ts`, `components.ts`, `index.ts` in `registry/`, `catalog/`, or `components/` directories
-- Arrays of objects with `{ id, name, component }` structure and 10+ entries
-- Files with `Component[]` type annotations
+**Phase 1: Registry Detection**
 
-Present detected registry candidate(s) to user for confirmation.
+Present the registry candidates step 3's component library detection found (`selected` first, then any other qualifying candidate, each with its score out of 9 and its entry count, and the recommender's `registry_path` when it is none of them) for the user to confirm, or accept an explicit `registry_path` from the user. Record the confirmed path as `scope.registry_path`.
 Prompt: "I found what looks like a component registry at {path} ({count} entries). Is this correct? Or provide the registry path:"
 
-**Phase 2 — Demo/Example Exclusion:**
+**Phase 2: Demo/Example Exclusion**
 
-Auto-detect demo directories and file patterns:
-- Directories: `demo/`, `demos/`, `stories/`, `examples/`, `__stories__/`, `storybook/`
-- Files: `*.stories.*`, `*.story.*`, `*.example.*`, `*.demo.*`
-
-Show detected patterns to the user for confirmation before applying them, rather than excluding files silently.
+Show the demo patterns step 3's component library detection found (each glob with its file count and sample files) to the user for confirmation before applying them, rather than excluding files silently. Record the confirmed patterns as `scope.demo_patterns` and add them to the exclusions.
 Prompt: "**Auto-detected {N} demo/example files** in {M} directories. Confirm exclusion? [Y/n] Or adjust patterns:"
 
-**Phase 3 — Variant Selection (if applicable):**
+**Phase 3: Variant Selection (if applicable)**
 
 If multiple design system variant directories detected (e.g., `react-shadcn/`, `react-baseui/`, `react-carbon/`):
 - Present detected variants with component counts per variant
 - User selects primary variant and which variants to include
-- Record as `ui_variants` in brief
+- Record them as `scope.ui_variants`, one `{name, package}` entry per variant
 
 Prompt: "I detected {count} design system variants: {list with counts}. Which is the primary variant? Include all? [Y/n]"
 
-**Phase 4 — Scope Confirmation:**
+**Phase 4: Scope Confirmation**
 
 Summary showing: component count, excluded demo count, variant summary, include/exclude patterns.
 Prompt: "Does this component library scope look right? Adjust before continuing."
 
 ## Scripts & Assets Detection (Optional Refinement)
 
-When `scripts_intent` or `assets_intent` is `detect` (default), SKF auto-detects from source directories matching: `scripts/`, `bin/`, `tools/`, `cli/` (for scripts) and `assets/`, `templates/`, `schemas/`, `configs/`, `examples/` (for assets). Detection applies to all scope types except `docs-only`.
+When `scripts_intent` or `assets_intent` is `detect` (default), SKF auto-detects from source directories matching: `scripts/`, `bin/`, `tools/`, `cli/` (for scripts; when one of these four folders is a Python package, holding `__init__.py`, only its `__main__.py` and the modules with a shebang or a `__main__` block count) and `assets/`, `templates/`, `schemas/`, `configs/`, `examples/` (for assets). Detection applies to all scope types except `docs-only`.

package/src/skf-brief-skill/assets/skill-brief-schema.md

@@ -27,6 +27,9 @@
 | `source_authority` | string | `official` / `community` / `internal`            | Default `community`. Set to `official` only when the skill creator is the library maintainer. Forced to `community` when `source_type: "docs-only"`.                                                                           |
 | `source_ref`       | string | Git ref (tag/branch/HEAD)                        | Resolved git ref used for source access. Set automatically during tag resolution — do not set manually.                                                                                                                        |
 | `scope.tier_a_include` | array | Glob patterns (min 1, non-empty)              | Optional. Narrower tier-A include list for a curated-subset skill — stratified monorepo packages, single-crate `specific-modules` scopes, and multi-entry exports-map packages. When present, `skf-test-skill` re-derives the coverage denominator from this list instead of the coarse `scope.include`, so the denominator reflects the authoring surface rather than incidentally-matched internal infrastructure. **It also exempts the brief from the denominator deflation guard**, so supply it only when it genuinely narrows the surface — never as an empty list, and never as a way to widen (listing files outside `scope.include` inverts its meaning). See `skf-test-skill/references/source-access-protocol.md` stratified-scope resolution. |
+| `scope.registry_path` | string | Path from the source root (non-empty) | Optional, for `scope.type: "component-library"`. The component registry file. `skf-create-skill` step 3d reads it instead of detecting a registry, and writes it back, with a `demo-and-registry` amendment, when the user confirms a detected registry or gives its path. |
+| `scope.ui_variants` | array | `{name, package?}` objects (`name` non-empty) | Optional, for `scope.type: "component-library"`. The design system variants, the first one primary. |
+| `scope.demo_patterns` | array | Glob patterns (non-empty strings) | Optional, for `scope.type: "component-library"`. The demo and example files `skf-create-skill` step 3d leaves out. Step 3d reads them instead of detecting demo files, and writes them back, with a `demo-and-registry` amendment per glob, when the user confirms or adjusts the detected ones. |
 
 When `source_type: "docs-only"`:
 - `source_repo` becomes optional (set to doc site URL for reference)
@@ -36,16 +39,9 @@ When `source_type: "docs-only"`:
 
 ## Version Detection
 
-During brief creation, attempt to auto-detect the source version before defaulting to `"1.0.0"`. Check the first matching file in the source:
+During brief creation, step 2 auto-detects the source version (`references/version-resolution.md`, Detection Algorithm) before defaulting to `"1.0.0"`.
 
-- **Python:** `pyproject.toml` `[project] version` (static) → if `dynamic = ["version"]`, check `__init__.py` for `__version__` → `_version.py` if exists → `setup.py` `version=` → `git describe --tags --abbrev=0`
-- **JavaScript/TypeScript:** root `package.json` (`"version"`) → if root has `"private": true` with a `"workspaces"` array or lacks a `"version"` field, fall back to a primary workspace package's `package.json` (e.g., `code/core/package.json`, or the first matching `packages/*/package.json`). For GitHub sources, prefer `gh api repos/{owner}/{repo}/releases/latest` → `tag_name` when a non-pre-release tag exists, over a default-branch pre-release. Treat a version containing `-alpha`, `-beta`, `-rc`, `-next`, or `-canary` as a pre-release.
-- **Rust:** `Cargo.toml` `[package] version` (static) → if `version = { workspace = true }`, resolve from workspace root `Cargo.toml` → `git describe --tags --abbrev=0`
-- **Go:** version tag from `go.mod` or `git describe --tags --abbrev=0`
-
-If the source is a remote GitHub repo, use `gh api repos/{owner}/{repo}/contents/{file}` to read the version file. If the source is local, read the file directly.
-
-If detection succeeds, use the detected version. If it fails or returns a non-semver value, fall back to `"1.0.0"`.
+If detection succeeds, use the detected version. If it fails or returns a non-semver value, fall back to `"1.0.0"`; the brief writer's result then carries a warning that says so.
 
 The create-skill workflow (extract) also performs version reconciliation at extraction time — if the source version has changed since the brief was created, the extraction step warns and uses the source version.
 
@@ -77,22 +73,30 @@ scope:
   #   reason: "user overrode full-library->public-api: only documented API ships"
   #   recorded: "2026-05-18"
   # Optional: amendment log for scope decisions made during create-skill §2a,
-  # update-skill §1b (auth-doc), and update-skill §1c (scope-expansion).
+  # update-skill §1b (auth-doc), update-skill §1c (scope-expansion) and
+  # create-skill step 3d (demo-and-registry).
   # amendments:
   #   - path: "apps/docs/public/llms.txt"
-  #     action: "promoted"          # "promoted" | "skipped" | "demoted-include" | "demoted-exclude"
-  #     category: "auth-doc"        # "auth-doc" (default for legacy entries) | "scope-expansion"
+  #     action: "promoted"          # "promoted" | "skipped" | "excluded" | "demoted-include" | "demoted-exclude" | "demo-excluded" | "registry-confirmed"
+  #     category: "auth-doc"        # "auth-doc" (default for legacy entries) | "scope-expansion" | "demo-and-registry"
   #     reason: "authoritative AI docs — only source for canonical install command"
-  #     heuristic: "llms.txt"        # required for auth-doc; absent for scope-expansion
+  #     heuristic: "llms.txt"        # required for auth-doc; absent for scope-expansion and demo-and-registry
   #     date: "2026-04-11"
   #     workflow: "skf-create-skill"
   #   - path: "python/cocoindex/_internal/api.py"
   #     action: "promoted"
   #     category: "scope-expansion"
-  #     reason: "out-of-scope new public API — drift report drift-report-20260424-212355.md"
+  #     reason: "out-of-scope new public API: drift report drift-report-20260424-212355.md"
   #     evidence: "~70 new exports flagged out-of-scope by audit"
   #     date: "2026-04-25"
   #     workflow: "skf-update-skill"
+  #   - path: "registry/index.ts"
+  #     action: "registry-confirmed"
+  #     category: "demo-and-registry"
+  #     reason: "user confirmed the detected registry at create-skill step 3d"
+  #     evidence: "score 8/9, 52 entries"
+  #     date: "2026-10-01"
+  #     workflow: "skf-create-skill"
   # Additional fields when scope.type is "component-library":
   # registry_path: "path/to/registry.ts"  # Optional — auto-detected if omitted
   # ui_variants:                           # Optional — design system variants
@@ -114,7 +118,7 @@ scope:
 | `recommended` | string (one of the six `scope.type` values) | yes | `skf-recommend-scope-type.py` → `scope_type` |
 | `chosen` | string (one of the six) | yes | final `scope.type` |
 | `accepted_recommendation` | bool | yes | `chosen == recommended` |
-| `heuristic` | string | yes | script `matched_heuristic` |
+| `heuristic` | string | yes | script `matched_heuristic` (values listed in `skf-recommend-scope-type.py`); `user-supplied-arg` when a headless run passed `scope_type`; older briefs may carry `reference-app-keywords` |
 | `reason` | string | yes | accepted → script `rationale` verbatim; overridden → user's stated reason, or `"user overrode {recommended}->{chosen}; reason not stated"` |
 | `recorded` | string (ISO date `YYYY-MM-DD`) | yes | current date — mirrors `amendments[].date` |
 
@@ -127,21 +131,22 @@ scope:
 
 ### Scope Amendments (Optional)
 
-`scope.amendments[]` is an additive, optional audit log of scope decisions made by workflows after the brief was first authored. Two writer paths exist today:
+`scope.amendments[]` is an additive, optional audit log of scope decisions made by workflows after the brief was first authored. Three writer paths exist today:
 
 - **Auth-doc promotions** (`category: "auth-doc"`) — `skf-create-skill` §2a and its mirror `skf-update-skill` §1b append entries when extraction discovers authoritative AI documentation files (`llms.txt`, `AGENTS.md`, etc.) that the original scope patterns excluded.
 - **Scope-expansion promotions** (`category: "scope-expansion"`) — `skf-update-skill` §1c appends entries when an audit drift report flags out-of-scope new public API paths (typically a major-version restructure where the brief's `scope.include` no longer reflects the real surface).
+- **Demo-and-registry decisions** (`category: "demo-and-registry"`): `skf-create-skill` step 3d appends one entry per demo glob and one for the registry file when the user confirms or gives them at its component-library gates, and writes the values to `scope.demo_patterns` and `scope.registry_path`. A headless run never writes one: its automatic decisions stay in the run's audit trail.
 
 **Entry fields:**
 
 | Field | Type | Required | Description |
 |---|---|---|---|
-| `path` | string | yes | Relative path (or glob, for `category: "scope-expansion"`) from source root to the file or tree being amended. For `promoted` actions this matches the literal entry added to `scope.include`. |
-| `action` | string | yes | One of: `promoted` (path added to `scope.include`), `skipped` (user declined promotion; decision recorded to prevent re-prompting), `excluded` (path added to `scope.exclude` — only valid with `category: "scope-expansion"`; used by gap-driven rescope to remove an internal / `#[doc(hidden)]` / out-of-scope export from the public surface), `demoted-include` (path removed from `scope.include` — only valid with `category: "scope-expansion"`), `demoted-exclude` (path removed from `scope.exclude` — only valid with `category: "scope-expansion"`). |
-| `category` | string | no | One of: `auth-doc` (default for entries without this field — the historical sole use case), `scope-expansion`. Distinguishes which workflow path wrote the entry and which writer-rules apply on re-runs. |
+| `path` | string | yes | Relative path (or glob, for `category: "scope-expansion"` and a `demo-and-registry` demo pattern) from source root to the file or tree being amended. For `promoted` actions this matches the literal entry added to `scope.include`. |
+| `action` | string | yes | One of: `promoted` (path added to `scope.include`), `skipped` (user declined promotion; decision recorded to prevent re-prompting), `excluded` (path added to `scope.exclude`, only valid with `category: "scope-expansion"`; used by gap-driven rescope to remove an internal / `#[doc(hidden)]` / out-of-scope export from the public surface), `demoted-include` (path removed from `scope.include`, only valid with `category: "scope-expansion"`), `demoted-exclude` (path removed from `scope.exclude`, only valid with `category: "scope-expansion"`), `demo-excluded` (the glob is written to `scope.demo_patterns`: only valid with `category: "demo-and-registry"`), `registry-confirmed` (the file is written to `scope.registry_path`: only valid with `category: "demo-and-registry"`). |
+| `category` | string | no | One of: `auth-doc` (default for entries without this field: the historical sole use case), `scope-expansion`, `demo-and-registry`. Distinguishes which workflow path wrote the entry and which writer-rules apply on re-runs. |
 | `reason` | string | yes | Human-readable sentence explaining the decision. Either user-provided at prompt time or auto-generated. |
 | `heuristic` | string | conditional | Required for `category: "auth-doc"` — the basename that matched (`llms.txt`, `AGENTS.md`, etc.). Omit for `category: "scope-expansion"`. |
-| `evidence` | string | conditional | Required for `category: "scope-expansion"` — short rationale from the source signal (e.g., a drift-report finding's evidence one-liner). Omit for `category: "auth-doc"`. |
+| `evidence` | string | conditional | Required for `category: "scope-expansion"` and `category: "demo-and-registry"`: short rationale from the source signal (a drift-report finding's evidence one-liner; the files a demo glob matched, or the registry's score and entry count). Omit for `category: "auth-doc"`. |
 | `date` | string | yes | ISO date (`YYYY-MM-DD`) when the amendment was recorded. |
 | `workflow` | string | yes | Workflow name that wrote the amendment (`skf-create-skill`, `skf-update-skill`). Identifies which workflow made the decision. |
 
@@ -151,7 +156,7 @@ scope:
 
 **Demotion (scope-expansion only):** `demoted-include` removes a previously-promoted path from `scope.include` — used when a prior `[P]` decision is reversed. `demoted-exclude` removes a path from `scope.exclude` — used when a previously excluded path needs to be re-evaluated. Both write the structural change and append the amendment so future runs see the rationale. Demotion is not valid for `category: "auth-doc"`: auth-doc skips already prevent re-prompting without scope mutation.
 
-**Exclusion (scope-expansion only):** `excluded` adds a path to `scope.exclude` — written by `skf-update-skill` gap-driven rescope (detect-changes §0 rule R1) when a coverage gap's remediation is removal (the export is internal, `#[doc(hidden)]`, or out of scope). The amendment is the audit trail; the `scope.exclude` write is what shrinks the source barrel, so the legitimate scope reduction is expressed in the brief rather than by editing `metadata.stats`. This keeps the reduction visible to `skf-test-skill`'s denominator-deflation check, which re-derives the barrel from `scope.include` filtered by `scope.exclude`. Not valid for `category: "auth-doc"`.
+**Exclusion (scope-expansion only):** `excluded` adds a path to `scope.exclude`, written by `skf-update-skill` gap-driven rescope (gap-driven.md §1 rule R1) when a coverage gap's remediation is removal (the export is internal, `#[doc(hidden)]`, or out of scope). The amendment is the audit trail; the `scope.exclude` write is what shrinks the source barrel, so the legitimate scope reduction is expressed in the brief rather than by editing `metadata.stats`. This keeps the reduction visible to `skf-test-skill`'s denominator-deflation check, which re-derives the barrel from `scope.include` filtered by `scope.exclude`. Not valid for `category: "auth-doc"`.
 
 **Backward compatibility:** `scope.amendments` is optional. Briefs without this field validate unchanged. Treat missing as an empty list. Existing entries without `category` are equivalent to `category: "auth-doc"` — readers must default the field when absent.
 
@@ -160,6 +165,7 @@ scope:
 - `skf-create-skill` §2a consults it to avoid re-prompting on decided auth-doc files.
 - `skf-update-skill` §1b (mirror of §2a) consults it for the same auth-doc reason.
 - `skf-update-skill` §1c consults it to avoid re-prompting on decided scope-expansion candidates and to honor prior `demoted-*` decisions.
+- `skf-create-skill` step 3d does not read the log: it reads `scope.demo_patterns` and `scope.registry_path`, which the same write sets. The auth-doc and scope-expansion readers act only on their own actions, so a `demo-and-registry` entry on the same path never stands in for one of their decisions.
 - `skf-audit-skill` may optionally report on stale promotions (promoted paths that no longer exist in source) as a future enhancement — not currently implemented.
 - Humans reading the brief see the audit trail of non-obvious scope decisions.
 
@@ -168,7 +174,8 @@ scope:
 - `skf-create-skill` §2a (Discovered Authoritative Files Protocol) — `category: "auth-doc"`
 - `skf-update-skill` §1b (mirror of §2a applied during change detection) — `category: "auth-doc"`
 - `skf-update-skill` §1c (Major-Version Scope Reconciliation) — `category: "scope-expansion"`
-- `skf-update-skill` gap-driven rescope (detect-changes §0 rule R1) — `category: "scope-expansion"`, `action: "excluded"`
+- `skf-update-skill` gap-driven rescope (gap-driven.md §1 rule R1): `category: "scope-expansion"`, `action: "excluded"`
+- `skf-create-skill` step 3d (component-library demo exclusion and registry detection): `category: "demo-and-registry"`, `action: "demo-excluded"` or `"registry-confirmed"`, only for an answer a user gave
 - Manual edits by the brief author are permitted but should include all required fields above (and `category` when the entry is not an auth-doc decision).
 
 ## YAML Template
@@ -211,7 +218,7 @@ The runtime template lives in `references/confirm-brief.md` §2 — that is the
 ## Validation Rules
 
 1. `name` must be unique within {forge_data_folder}
-2. `source_repo` must be accessible (gh api for GitHub, path exists for local)
+2. `source_repo` must be accessible (listed by skf-github-probe.py for a GitHub URL, which needs gh only for a private repository; path exists for local)
 3. `language` must be a recognized programming language
 4. `scope.type` must be one of the six defined types
 5. `scope.include` must have at least one pattern (exception: `docs-only` scope, where include patterns are optional since no source code is available)

package/src/skf-brief-skill/customize.toml

@@ -1,8 +1,8 @@
 # DO NOT EDIT -- overwritten on every update.
 #
 # Workflow customization surface for skf-brief-skill.
-# Team overrides:     _bmad/custom/skf-brief-skill.toml (under {project-root})
-# Personal overrides: _bmad/custom/skf-brief-skill.user.toml (under {project-root})
+# Team overrides:     {project-root}/_bmad/custom/skf-brief-skill.toml
+# Personal overrides: {project-root}/_bmad/custom/skf-brief-skill.user.toml
 
 [workflow]
 
@@ -10,15 +10,18 @@
 #   scalars: override wins • arrays (persistent_facts, activation_steps_*): append
 #   arrays-of-tables with `code`/`id`: replace matching items, append new ones.
 
-# Steps to run before the standard activation (uv probe, config load).
-# Overrides append. Use for org-wide pre-flight checks (auth, network,
-# compliance) that must precede any brief authoring work.
+# Steps SKILL.md On Activation step 3 runs once this file resolves: after
+# config.yaml is loaded and {headless_mode} and {auto_mode} are resolved, so
+# config values such as {forge_data_folder} and {sidecar_path} are available,
+# and before any stage loads. Overrides append. Use for org-wide pre-flight
+# checks (auth, network, compliance) that must precede any brief authoring
+# work.
 
 activation_steps_prepend = []
 
-# Steps to run after activation but before the first stage executes.
-# Overrides append. Use for context loads or banner customization that
-# should run once activation completes successfully.
+# Steps to run once activation completes (the envelope emitter resolved),
+# just before step 1 (references/gather-intent.md) loads. Overrides append.
+# Use for context loads or banner customization.
 
 activation_steps_append = []
 
@@ -26,11 +29,18 @@ activation_steps_append = []
 # (house style, naming conventions, description-voice guardrails).
 # Overrides append.
 #
-# Each entry is either:
+# Each entry is one of:
 #   - a literal sentence, e.g. "Skill briefs must cite an authoritative source."
 #   - a file reference prefixed with `file:`, e.g.
 #     "file:{project-root}/docs/brief-style.md" (globs supported; file
 #     contents are loaded and treated as facts).
+#   - an entry prefixed with `!`, which loads nothing and drops each earlier
+#     entry it names.
+#
+# The default below loads every project-context.md under {project-root}.
+# Overrides append, so they cannot delete it; to stop loading those files,
+# set in {project-root}/_bmad/custom/skf-brief-skill.toml:
+#   persistent_facts = ["!file:{project-root}/**/project-context.md"]
 
 persistent_facts = [
   "file:{project-root}/**/project-context.md",
@@ -38,21 +48,39 @@ persistent_facts = [
 
 # --- Optional asset overrides ---
 #
-# Lift the canonical asset paths so orgs can substitute house-style copies
-# without forking the skill. Empty string = use the bundled default.
+# Each names the file a stage loads, as a path from the skill root. To use an
+# org copy, point at it with a {project-root}/... path. An empty string means
+# the default named below.
+
+# The five voice examples step 1 shows a first-time user and composes the
+# skill description from. A copy keeps five examples, each leading a
+# different way, and the "do not template-stamp" guidance; whatever it says,
+# step 1 still requires a literal `Use when` clause in every description.
+
+description_voice_examples_path = "assets/description-voice-examples.md"
+
+# The scope types step 3 offers and the boundary flow of each. A copy keeps
+# the five letter-keyed types ([F] full-library, [M] specific-modules,
+# [P] public-api, [C] component-library, [R] reference-app), a boundary
+# section for each and the Docs-Only boundaries: step 3 maps the letters to
+# the scope types the brief writer accepts. Headless boundary defaults are
+# not read from it: step 3 states them.
 
-description_voice_examples_path = ""
-scope_templates_path = ""
-brief_schema_path = ""
+scope_templates_path = "assets/scope-templates.md"
 
-# Pipeline-integration hook invoked once the brief is written and the result
-# contract is finalized (write-brief.md, step 5), before the workflow chains to
-# the terminal health-check step. The command is called as:
+# Pipeline-integration hook: a shell command, not an instruction, invoked
+# once the brief is written (and, in a headless or [auto] run, the result
+# envelope is built), before the workflow chains to the terminal
+# health-check step. Every successful run calls it once: write-brief.md §6b
+# on the interactive, headless and ratify paths, and step-auto-validate.md §3
+# on the [auto] path, right after its envelope. The command is called as:
 #   <on_complete> --result-path=<absolute_path_to_skill-brief.yaml>
 # Useful for chaining into create-skill, Slack notifications, dashboard ingest,
-# or CI hooks. Override wins. Failures are logged to workflow_warnings[] but
-# never fail the workflow.
+# or CI hooks. Override wins. A failure never fails the workflow: the run
+# displays one line, "on_complete hook failed (exit <code>): <stderr>", which
+# the result envelope, built before the hook runs and displayed last by the
+# health check, does not carry.
 #
-# Empty string = no-op (default).
+# Empty string = no hook (default).
 
 on_complete = ""