bmad-module-skill-forge 0.9.0 → 0.10.1-alpha.0

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

@@ -0,0 +1,206 @@
+# Skill Brief Schema
+
+## Required Fields
+
+| Field       | Type   | Constraint                                       | Description                                                                 |
+|-------------|--------|--------------------------------------------------|-----------------------------------------------------------------------------|
+| name        | string | kebab-case `[a-z0-9-]+`                          | Unique skill identifier                                                     |
+| version     | string | Semantic version (`X.Y.Z` or `X.Y.Z-prerelease`) | Auto-detect from source (see Version Detection below), fall back to `1.0.0`. **Side effect on remote sources:** `skf-create-skill` treats `version` as an **implicit** `target_version` hint when `target_version` itself is absent — it will try to resolve `{version}` or `v{version}` to a git tag before cloning and fall back to HEAD with a warning if no tag matches. See `skf-create-skill/references/source-resolution-protocols.md` → "Implicit Tag Resolution". |
+| source_repo | string | GitHub URL or local path                         | Repository or project root (optional when `source_type: "docs-only"`)       |
+| language    | string | Recognized language                              | Primary programming language                                                |
+| scope       | object | See Scope Object below                           | Boundary definition                                                         |
+| description | string | 1-3 sentences                                    | What the skill covers                                                       |
+| forge_tier  | string | `Quick` / `Forge` / `Forge+` / `Deep`            | Inherited from forge-tier.yaml (Title Case)                                 |
+| created     | string | ISO date `YYYY-MM-DD`                            | Generation date                                                             |
+| created_by  | string | user_name from config                            | Who generated the brief                                                     |
+
+## Optional Fields
+
+| Field              | Type   | Constraint                                       | Description                                                                                                                                                                                                                    |
+|--------------------|--------|--------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| source_type        | string | `source` or `docs-only`                          | Default `source`. When `docs-only`: `source_repo` optional, `doc_urls` required                                                                                                                                                |
+| doc_urls           | array  | `{url, label}` objects                           | Documentation URLs for T3 content. Required when `source_type: "docs-only"`                                                                                                                                                    |
+| `scripts_intent`   | string | `detect` / `none` / free-text                    | Describes whether scripts should be extracted. Values: `detect` (auto-detect from source — default when absent), `none` (skip scripts), or a free-text description of expected scripts (e.g., "CLI validation tools in bin/"). |
+| `assets_intent`    | string | `detect` / `none` / free-text                    | Describes whether assets should be extracted. Values: `detect` (auto-detect from source — default when absent), `none` (skip assets), or a free-text description of expected assets (e.g., "JSON schemas in schemas/").        |
+| `target_version`   | string | Semantic version (`X.Y.Z` or `X.Y.Z-prerelease`) | User-specified target version. When present, overrides auto-detection and becomes the skill's version. Recommended for docs-only skills where auto-detection is unavailable.                                                   |
+| `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                                 | Optional. Narrower tier-A include list for stratified-scope monorepo skills. 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. See `skf-test-skill/references/source-access-protocol.md` stratified-scope resolution. |
+
+When `source_type: "docs-only"`:
+- `source_repo` becomes optional (set to doc site URL for reference)
+- `doc_urls` must have at least one entry
+- `source_authority` is forced to `community` (T3 external documentation cannot be `official`)
+- All extracted content gets `[EXT:{url}]` citations
+
+## 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:
+
+- **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"`.
+
+The create-skill workflow (step-03-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.
+
+**Target version override:** When `target_version` is present in the brief, it takes precedence over auto-detection. Auto-detection still runs for informational purposes (displayed as "Detected version" alongside the user-specified "Target version"), but the `target_version` value is used as the brief's `version` field. This is particularly useful for docs-only skills (where no package manifest exists) and when the user wants to compile a skill for a specific older version.
+
+**Pre-release handling:** If the detected version contains a pre-release tag (e.g., `1.0.0-beta.0`, `2.0.0-rc.1`), preserve it as-is. Pre-release tags are valid semver and must not be stripped. When comparing versions during reconciliation, use semver-aware comparison that respects pre-release ordering.
+
+## Scope Object Structure
+
+```yaml
+scope:
+  type: full-library | specific-modules | public-api | component-library | reference-app | docs-only
+  include:
+    - "src/**/*.ts"           # Glob patterns for included files/directories
+  exclude:
+    - "**/*.test.*"           # Glob patterns for excluded files
+    - "**/node_modules/**"
+  # Optional: narrower tier-A include list for stratified-scope monorepos
+  # tier_a_include:
+  #   - "code/core/src/manager-api/**"
+  #   - "code/core/src/preview-api/**"
+  notes: "Optional notes about scope decisions"
+  # Optional: amendment log for scope decisions made during create-skill §2a
+  # amendments:
+  #   - path: "apps/docs/public/llms.txt"
+  #     action: "promoted"          # "promoted" | "skipped"
+  #     reason: "authoritative AI docs — only source for canonical install command"
+  #     heuristic: "llms.txt"
+  #     date: "2026-04-11"
+  #     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
+  #   - name: "shadcnui"
+  #     package: "packages/components/react-shadcn"
+  # demo_patterns:                         # Optional — auto-detected if omitted
+  #   - "**/demo/**"
+  #   - "**/*.stories.*"
+```
+
+### Scope Amendments (Optional)
+
+`scope.amendments[]` is an additive, optional audit log of scope decisions made by workflows after the brief was first authored. Its primary writer is `skf-create-skill` §2a (Discovered Authoritative Files Protocol), which appends entries when extraction discovers authoritative AI documentation files (`llms.txt`, `AGENTS.md`, etc.) that the original scope patterns excluded.
+
+**Entry fields:**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path` | string | yes | Relative path from source root to the file being amended. Matches the literal path added to `scope.include` (for `promoted` actions). |
+| `action` | string | yes | One of: `promoted` (file added to scope with a literal `scope.include` entry), `skipped` (user declined promotion; file remains out of scope, decision recorded to prevent re-prompting). |
+| `reason` | string | yes | Human-readable sentence explaining the decision. Either user-provided at prompt time or auto-generated ("authoritative AI docs — matched heuristic {basename}"). |
+| `heuristic` | string | yes | The basename heuristic that matched (`llms.txt`, `AGENTS.md`, etc.) so future audits can verify the file still matches its original classification. |
+| `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's §2a-equivalent made the decision. |
+
+**Promotion write-through:** When `action: "promoted"`, the workflow also appends the literal path to `scope.include`. This is a belt-and-suspenders design: future `skf-create-skill` runs read `scope.include` during §2 and include the file in the filtered list automatically, so §2a finds no candidate and does not re-prompt. The `amendments[]` entry is the human-readable audit trail of *why* the path was added.
+
+**Skip recording:** When `action: "skipped"`, the workflow does NOT modify `scope.include` or `scope.exclude`. The amendment entry alone is enough to prevent re-prompting, because §2a checks `amendments[]` before prompting.
+
+**Backward compatibility:** `scope.amendments` is optional. Briefs without this field validate unchanged. Treat missing as an empty list.
+
+**Who reads `amendments[]`:**
+
+- `skf-create-skill` §2a consults it to avoid re-prompting on decided files.
+- `skf-update-skill` §1b (mirror of §2a) consults it for the same reason.
+- `skf-audit-skill` may optionally report on stale promotions (promoted files 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.
+
+**Who writes `amendments[]`:**
+
+- `skf-create-skill` §2a (Discovered Authoritative Files Protocol)
+- `skf-update-skill` §1b (mirror of §2a applied during change detection)
+- Manual edits by the brief author are permitted but should include all required fields above.
+
+## YAML Template
+
+```yaml
+---
+name: "{skill-name}"
+version: "{detected-version or 1.0.0}"  # Auto-detect from source, fall back to 1.0.0
+source_type: "source"                    # "source" (default) or "docs-only"
+source_repo: "{github-url-or-local-path}"
+language: "{detected-language}"
+description: "{brief-description}"
+forge_tier: "{Quick|Forge|Forge+|Deep}"
+created: "{date}"
+created_by: "{user_name}"
+scope:
+  type: "{full-library|specific-modules|public-api|component-library|reference-app|docs-only}"
+  include:
+    - "{pattern}"
+  exclude:
+    - "{pattern}"
+  notes: "{optional-scope-notes}"
+# target_version: "X.Y.Z"       # Optional: overrides auto-detection when specified
+# source_ref: "v0.5.0"          # Auto-resolved — do not set manually
+# Optional: documentation URLs for T3 content (required when source_type: "docs-only")
+# doc_urls:
+#   - url: "https://docs.example.com/api"
+#     label: "API Reference"
+# scripts_intent: detect         # Optional: detect | none | description
+# assets_intent: detect          # Optional: detect | none | description
+# source_authority: community    # Optional: official | community | internal
+---
+```
+
+## Human-Readable Presentation Format
+
+When presenting the brief for confirmation (brief-skill step 04 only — not applicable to analyze-source batch generation), display as:
+
+```
+Skill Brief: {name}
+====================
+
+Target:      {source_repo}
+Language:    {language}
+Forge Tier:  {forge_tier}
+Description: {description}
+
+Scope: {scope.type}
+  Include: {scope.include patterns, one per line}
+  Exclude: {scope.exclude patterns, one per line}
+  Notes:   {scope.notes}
+
+{If source_type is "docs-only":}
+Source Type: docs-only
+Doc URLs:
+  {doc_urls, one per line with labels}
+
+{If source_type is "source" AND supplemental doc_urls collected:}
+Supplemental Docs:
+  {doc_urls, one per line with labels}
+
+{If scripts_intent or assets_intent was explicitly set (not default "detect"):}
+Scripts:    {scripts_intent}
+Assets:     {assets_intent}
+
+Source Authority: {source_authority}
+
+{If target_version is set:}
+Target Version:   {target_version} (user-specified)
+Detected Version: {detected_version or "N/A"}
+{Else:}
+Version:    {version}
+{End if}
+Created:    {created}
+Created by: {created_by}
+```
+
+## 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)
+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)
+6. `forge_tier` must be one of: Quick, Forge, Forge+, Deep (Title Case, must match the tier from forge-tier.yaml, or default to Quick)
+7. When `source_type: "docs-only"`: `doc_urls` must have >= 1 entry, `source_repo` becomes optional
+8. Each `doc_urls` entry must have a valid `url` field

package/src/{workflows/brief-skill → skf-brief-skill}/steps-c/step-01-gather-intent.md

@@ -1,7 +1,4 @@
 ---
-name: 'step-01-gather-intent'
-description: 'Initialize brief-skill workflow, discover forge tier, and gather user intent for skill creation'
-
 nextStepFile: './step-02-analyze-target.md'
 forgeTierFile: '{sidecar_path}/forge-tier.yaml'
 ---
@@ -12,45 +9,11 @@ forgeTierFile: '{sidecar_path}/forge-tier.yaml'
 
 To initialize the brief-skill workflow by discovering the forge tier configuration, then gathering the user's target repository, intent, and any upfront scope hints for skill creation.
 
-## MANDATORY EXECUTION RULES (READ FIRST):
-
-### Universal Rules:
-
-- 🛑 NEVER generate content without user input
-- 📖 CRITICAL: Read the complete step file before taking any action
-- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read
-- 📋 YOU ARE A FACILITATOR, not a content generator
-- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
-- ⚙️ TOOL/SUBPROCESS FALLBACK: If any instruction references a subprocess, subagent, or tool you do not have access to, you MUST still achieve the outcome in your main context thread
-
-### Role Reinforcement:
-
-- ✅ You are a skill scoping architect in Ferris Architect mode (exploratory, collaborative)
-- ✅ If you already have been given a name, communication_style and identity, continue to use those while playing this new role
-- ✅ We engage in collaborative dialogue, not command-response
-- ✅ You bring source code analysis and skill design expertise, user brings their domain knowledge and use case
-- ✅ Maintain a warm, guiding tone — this is a discovery conversation
-
-### Step-Specific Rules:
-
-- 🎯 Focus only on gathering intent — do not analyze the repo yet (that's step 02)
-- 🚫 FORBIDDEN to examine source code or list exports in this step
-- 💬 Approach: Open-ended discovery facilitation — "What interests you about this library?"
-- 📋 Collect: target repo, user intent, scope hints, skill name
-
-## EXECUTION PROTOCOLS:
-
-- 🎯 Follow the MANDATORY SEQUENCE exactly
-- 💾 Accumulate gathered information conversationally for use in subsequent steps
-- 📖 This is the init step — sets up everything that follows
-- 🚫 FORBIDDEN to proceed without a confirmed target repository
+## Rules
 
-## CONTEXT BOUNDARIES:
-
-- Available context: Module config (forge_data_folder, user_name), forge-tier.yaml (if available)
-- Focus: Understanding WHAT the user wants to skill and WHY
-- Limits: Do not analyze source code, detect language, or list exports — that's step 02
-- Dependencies: None — this is the first step
+- Focus only on gathering intent — do not analyze the repo yet (Step 02)
+- Do not examine source code or list exports in this step
+- Open-ended discovery facilitation — collect target repo, user intent, scope hints, skill name
 
 ## MANDATORY SEQUENCE
 
@@ -67,7 +30,7 @@ Attempt to load `{forgeTierFile}`:
 **Apply tier override:** Read `{sidecar_path}/preferences.yaml`. If `tier_override` is set and is a valid tier value (Quick, Forge, Forge+, or Deep), use it instead of the detected tier.
 
 **If not found:**
-- "**Cannot proceed.** forge-tier.yaml not found at `{forgeTierFile}`. Please run the **setup-forge** workflow first to configure your forge tier (Quick/Forge/Forge+/Deep)."
+- "**Cannot proceed.** forge-tier.yaml not found at `{forgeTierFile}`. Please run the **setup** workflow first to configure your forge tier (Quick/Forge/Forge+/Deep)."
 - HALT — do not proceed.
 
 ### 2. Welcome and Explain
@@ -207,34 +170,10 @@ Display: "**Select:** [C] Continue to Target Analysis"
 #### EXECUTION RULES:
 
 - ALWAYS halt and wait for user input after presenting menu
+- **GATE [default: use args]** — If `{headless_mode}`: consume pre-supplied arguments (target_repo, skill_name, scope_hint, language_hint) and auto-proceed. If required args missing, HALT: "headless mode requires target_repo and skill_name arguments."
 - ONLY proceed to next step when user selects 'C'
 
 ## CRITICAL STEP COMPLETION NOTE
 
 ONLY WHEN C is selected and target repository is confirmed will you load and read fully `./step-02-analyze-target.md` to execute target analysis.
 
----
-
-## 🚨 SYSTEM SUCCESS/FAILURE METRICS
-
-### ✅ SUCCESS:
-
-- Forge tier discovered (HALT if missing), override applied if set in preferences.yaml
-- Target repository confirmed (GitHub URL or local path)
-- User intent captured with enough context for scoping
-- Skill name derived and confirmed
-- Scope hints noted (if provided)
-- Source type and source authority captured
-- Target version captured (if provided)
-- User ready to proceed to analysis
-
-### ❌ SYSTEM FAILURE:
-
-- Analyzing source code in this step (too early)
-- Proceeding without a confirmed target repository
-- Not halting when forge tier is missing
-- Not attempting to discover forge tier
-- Generating a skill name without user confirmation
-- Skipping the intent gathering conversation
-
-**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.

package/src/{workflows/brief-skill → skf-brief-skill}/steps-c/step-02-analyze-target.md

@@ -1,7 +1,4 @@
 ---
-name: 'step-02-analyze-target'
-description: 'Analyze target repository structure, detect language, and list modules and exports'
-
 nextStepFile: './step-03-scope-definition.md'
 ---
 
@@ -11,45 +8,11 @@ nextStepFile: './step-03-scope-definition.md'
 
 To analyze the target repository by resolving its location, reading its structure, detecting the primary language, and listing top-level modules and exports — providing the user with a factual foundation for scoping decisions.
 
-## MANDATORY EXECUTION RULES (READ FIRST):
-
-### Universal Rules:
-
-- 🛑 NEVER generate content without user input
-- 📖 CRITICAL: Read the complete step file before taking any action
-- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read
-- 📋 YOU ARE A FACILITATOR, not a content generator
-- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
-- ⚙️ TOOL/SUBPROCESS FALLBACK: If any instruction references a subprocess, subagent, or tool you do not have access to, you MUST still achieve the outcome in your main context thread
-
-### Role Reinforcement:
-
-- ✅ You are a source code analyst in Ferris Architect mode
-- ✅ If you already have been given a name, communication_style and identity, continue to use those while playing this new role
-- ✅ Report ONLY what is found — zero hallucination tolerance
-- ✅ You bring structural analysis expertise, user brings their domain understanding
-
-### Step-Specific Rules:
-
-- 🎯 Focus only on analysis — do not define scope yet (that's step 03)
-- 🚫 FORBIDDEN to make scoping decisions or recommendations in this step
-- 🚫 FORBIDDEN to hallucinate or guess about repository contents
-- 💬 Approach: Prescriptive — exact analysis instructions, factual reporting
-- 📋 Report everything found; let the user interpret for scoping
-
-## EXECUTION PROTOCOLS:
-
-- 🎯 Follow the MANDATORY SEQUENCE exactly
-- 💾 Analysis results are accumulated conversationally for use in step 03
-- 📖 This step is autonomous — minimal user interaction required
-- 🚫 FORBIDDEN to proceed if target is inaccessible — halt with actionable error
+## Rules
 
-## CONTEXT BOUNDARIES:
-
-- Available context: Target repo (URL or path), user intent, skill name, forge tier — all from step 01
-- Focus: Structural analysis of the repository
-- Limits: Do not read file contents deeply — only structure, exports, and metadata
-- Dependencies: Confirmed target repository from step 01
+- Focus only on analysis — do not define scope yet (Step 03)
+- Do not make scoping decisions or recommendations
+- Do not hallucinate or guess about repository contents
 
 ## MANDATORY SEQUENCE
 
@@ -148,7 +111,7 @@ If `tools.ccc` is true in forge-tier.yaml, supplement the module listing with a
 - **Cursor:** Use `ccc` MCP server `search` tool with query `"{repo_name} public API exports modules"` and path `{source_path}`
 - **CLI fallback:** `ccc search "{repo_name} public API exports modules" --path {source_path} --limit 10`
 
-See [knowledge/tool-resolution.md](../../../knowledge/tool-resolution.md) for full bridge-to-tool mapping.
+See `knowledge/tool-resolution.md` for full bridge-to-tool mapping.
 
 If results are returned, display:
 
@@ -168,7 +131,7 @@ If CCC is unavailable or returns no results: skip this subsection silently.
 Attempt to auto-detect the source version using the rules from the skill-brief-schema.md Version Detection section:
 
 **For Python:** Check `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`
-**For JavaScript/TypeScript:** Check `package.json` `"version"` field
+**For JavaScript/TypeScript:** Check root `package.json` `"version"` field → 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.
 **For Rust:** Check `Cargo.toml` `[package] version` (static) → if `version = { workspace = true }`, resolve from workspace root `Cargo.toml` → `git describe --tags --abbrev=0`
 **For Go:** Check `go.mod` or `git describe --tags --abbrev=0`
 
@@ -239,26 +202,3 @@ Pause briefly for user input. If the user provides corrections or asks questions
 
 ONLY WHEN the analysis is complete and the summary has been presented to the user will you load and read fully `./step-03-scope-definition.md` to begin scope definition.
 
----
-
-## 🚨 SYSTEM SUCCESS/FAILURE METRICS
-
-### ✅ SUCCESS:
-
-- Target repository resolved and accessible
-- Repository structure listed clearly
-- Primary language detected with confidence level
-- Top-level modules and exports identified
-- Source version detected (or default noted)
-- Analysis summary presented factually
-- Auto-proceeded to scope definition (with pause for corrections)
-
-### ❌ SYSTEM FAILURE:
-
-- Hallucinating or guessing about repository contents
-- Making scoping recommendations (too early — that's step 03)
-- Proceeding when target is inaccessible (must halt with error)
-- Not detecting or reporting the primary language
-- Skipping the analysis summary
-
-**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.

package/src/{workflows/brief-skill → skf-brief-skill}/steps-c/step-03-scope-definition.md

@@ -1,9 +1,6 @@
 ---
-name: 'step-03-scope-definition'
-description: 'Collaboratively define skill scope boundaries using analysis findings and scope templates'
-
 nextStepFile: './step-04-confirm-brief.md'
-scopeTemplatesFile: '../data/scope-templates.md'
+scopeTemplatesFile: 'assets/scope-templates.md'
 advancedElicitationSkill: '/bmad-advanced-elicitation'
 partyModeSkill: '/bmad-party-mode'
 ---
@@ -14,45 +11,11 @@ partyModeSkill: '/bmad-party-mode'
 
 To collaboratively define the skill's inclusion and exclusion boundaries using the analysis findings from step 02, scope templates, and the user's intent from step 01.
 
-## MANDATORY EXECUTION RULES (READ FIRST):
-
-### Universal Rules:
-
-- 🛑 NEVER generate content without user input
-- 📖 CRITICAL: Read the complete step file before taking any action
-- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read
-- 📋 YOU ARE A FACILITATOR, not a content generator
-- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
-- ⚙️ TOOL/SUBPROCESS FALLBACK: If any instruction references a subprocess, subagent, or tool you do not have access to, you MUST still achieve the outcome in your main context thread
-
-### Role Reinforcement:
-
-- ✅ You are a skill boundary architect in Ferris Architect mode (collaborative, exploratory)
-- ✅ If you already have been given a name, communication_style and identity, continue to use those while playing this new role
-- ✅ We engage in collaborative dialogue, not command-response
-- ✅ You bring API surface design expertise, user brings their domain knowledge of what's valuable
-- ✅ Maintain warm, guiding tone — help the user make informed scoping decisions
-
-### Step-Specific Rules:
-
-- 🎯 Focus only on defining scope boundaries — do not write the brief yet (that's step 05)
-- 🚫 FORBIDDEN to make scope decisions unilaterally — user drives all scope choices
-- 💬 Approach: Intent-based discovery — "Which parts are most relevant to your use case?"
-- 📋 Produce: scope type, include patterns, exclude patterns
-
-## EXECUTION PROTOCOLS:
-
-- 🎯 Follow the MANDATORY SEQUENCE exactly
-- 💾 Accumulate scope decisions conversationally for use in subsequent steps
-- 📖 Reference analysis findings from step 02 throughout
-- 🚫 FORBIDDEN to proceed without user confirmation of scope boundaries
+## Rules
 
-## CONTEXT BOUNDARIES:
-
-- Available context: Target repo, user intent, skill name, forge tier (step 01), repo structure, detected language, modules, exports (step 02)
-- Focus: Defining WHAT is in scope and what is NOT
-- Limits: Do not generate the brief — only define boundaries
-- Dependencies: Analysis findings from step 02
+- Focus only on defining scope boundaries — do not write the brief yet (Step 05)
+- Do not make scope decisions unilaterally — user drives all scope choices
+- Produce: scope type, include patterns, exclude patterns
 
 ## MANDATORY SEQUENCE
 
@@ -104,9 +67,11 @@ Wait for confirmation. Record any changes to `doc_urls`.
 
 **If no supplemental doc_urls were collected:** Skip this subsection.
 
+**Scope guidance for first-time users:** A well-scoped skill covers one cohesive capability with 3-8 primary functions. If the scope includes unrelated concerns (e.g., authentication AND data visualization), suggest splitting into separate briefs. If the scope is too narrow (single utility function), suggest expanding to the surrounding capability surface.
+
 ### 2c. Offer Scope Templates
 
-Load `{scopeTemplatesFile}` for the scope type options ([F], [M], [P], [C]) and their descriptions.
+Load `{scopeTemplatesFile}` for the scope type options ([F], [M], [P], [C], [R]) and their descriptions.
 
 Present: "**How broadly should this skill cover the library?**" followed by the scope type options from the loaded reference.
 
@@ -116,7 +81,7 @@ Wait for user selection.
 
 ### 3. Define Boundaries Based on Selection
 
-Using the boundary definitions from `{scopeTemplatesFile}`, present the appropriate flow for the user's selected scope type ([F], [M], [P], or [C]). Follow each type's prompts and wait for user input at each phase before proceeding.
+Using the boundary definitions from `{scopeTemplatesFile}`, present the appropriate flow for the user's selected scope type ([F], [M], [P], [C], or [R]). Follow each type's prompts and wait for user input at each phase before proceeding.
 
 ### 4. Handle Language Override
 
@@ -132,7 +97,7 @@ Wait for confirmation or override.
 
 "**Scope Summary:**
 
-**Type:** {Full Library / Specific Modules / Public API / Component Library}
+**Type:** {Full Library / Specific Modules / Public API / Component Library / Reference App}
 
 **Include:**
 {bulleted list of include patterns}
@@ -151,7 +116,7 @@ Wait for confirmation. Make adjustments if requested.
 
 ### 5b. Scripts & Assets Intent (Optional)
 
-**Only ask when `scope.type` is `full-library`, `specific-modules`, or `component-library` (skip for `public-api` and `docs-only`).**
+**Only ask when `scope.type` is `full-library`, `specific-modules`, `component-library`, or `reference-app` (skip for `public-api` and `docs-only`). Reference apps routinely ship wiring scripts and build-config assets — prompt for them.**
 
 "Does this library include executable scripts (CLI tools, validation scripts, setup helpers) or static assets (config templates, JSON schemas, example configs) that should be packaged with the skill?"
 
@@ -175,6 +140,7 @@ Display: **Select an Option:** [A] Advanced Elicitation [P] Party Mode [C] Conti
 #### EXECUTION RULES:
 
 - ALWAYS halt and wait for user input after presenting menu
+- **GATE [default: C]** — If `{headless_mode}`: accept auto-detected scope (full-repo or manifest-based) and auto-proceed, log: "headless: using auto-detected scope"
 - ONLY proceed to next step when user selects 'C'
 - After other menu items execution, return to this menu
 - User can chat or ask questions — always respond and then redisplay menu
@@ -183,25 +149,3 @@ Display: **Select an Option:** [A] Advanced Elicitation [P] Party Mode [C] Conti
 
 ONLY WHEN C is selected and scope boundaries are confirmed will you load and read fully `./step-04-confirm-brief.md` to present the complete brief for confirmation.
 
----
-
-## 🚨 SYSTEM SUCCESS/FAILURE METRICS
-
-### ✅ SUCCESS:
-
-- Scope type selected by user (Full Library, Specific Modules, Public API, or Component Library)
-- Include patterns defined and confirmed
-- Exclude patterns defined and confirmed
-- Language confirmed (or overridden if detection was low confidence)
-- User confirmed the scope summary
-- Menu presented and user input handled correctly
-
-### ❌ SYSTEM FAILURE:
-
-- Making scope decisions without user input
-- Not presenting the scope templates for user selection
-- Skipping the scope summary confirmation
-- Not handling language override when detection confidence was low
-- Writing the brief in this step (too early — that's step 05)
-
-**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.

package/src/{workflows/brief-skill → skf-brief-skill}/steps-c/step-04-confirm-brief.md

@@ -1,10 +1,7 @@
 ---
-name: 'step-04-confirm-brief'
-description: 'Present complete skill brief for user review and confirmation before writing'
-
 nextStepFile: './step-05-write-brief.md'
 reviseStepFile: './step-03-scope-definition.md'
-briefSchemaFile: '../data/skill-brief-schema.md'
+briefSchemaFile: 'assets/skill-brief-schema.md'
 advancedElicitationSkill: '/bmad-advanced-elicitation'
 partyModeSkill: '/bmad-party-mode'
 ---
@@ -15,44 +12,10 @@ partyModeSkill: '/bmad-party-mode'
 
 To present the complete skill brief in human-readable format, highlighting all fields that will be written to skill-brief.yaml, and obtain explicit user approval before writing.
 
-## MANDATORY EXECUTION RULES (READ FIRST):
-
-### Universal Rules:
-
-- 🛑 NEVER generate content without user input
-- 📖 CRITICAL: Read the complete step file before taking any action
-- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read
-- 📋 YOU ARE A FACILITATOR, not a content generator
-- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
-- ⚙️ TOOL/SUBPROCESS FALLBACK: If any instruction references a subprocess, subagent, or tool you do not have access to, you MUST still achieve the outcome in your main context thread
-
-### Role Reinforcement:
-
-- ✅ You are a quality reviewer in Ferris Architect mode
-- ✅ If you already have been given a name, communication_style and identity, continue to use those while playing this new role
-- ✅ Present information precisely and clearly — this is a confirmation gate
-- ✅ Highlight anything with low confidence or defaults that the user should verify
-
-### Step-Specific Rules:
-
-- 🎯 Focus only on presenting and confirming — do not write files yet (that's step 05)
-- 🚫 FORBIDDEN to proceed without explicit user approval
-- 💬 Approach: Prescriptive — exact presentation format showing all YAML fields
-- 📋 This is a P2 confirmation gate — the user MUST approve before continuing
-
-## EXECUTION PROTOCOLS:
-
-- 🎯 Follow the MANDATORY SEQUENCE exactly
-- 💾 Load the schema to ensure all required fields are presented
-- 📖 This is a mandatory checkpoint — no auto-proceed
-- 🚫 FORBIDDEN to write skill-brief.yaml in this step
+## Rules
 
-## CONTEXT BOUNDARIES:
-
-- Available context: All gathered data from steps 01-03 (target, intent, name, tier, language, scope)
-- Focus: Presenting the complete brief for final review
-- Limits: Do not write files — only present for approval
-- Dependencies: Confirmed scope boundaries from step 03
+- Focus only on presenting and confirming — do not write files yet (Step 05)
+- Do not proceed without explicit user approval (P2 confirmation gate)
 
 ## MANDATORY SEQUENCE
 
@@ -182,6 +145,7 @@ Display: **Select an Option:** [R] Revise Scope [A] Advanced Elicitation [P] Par
 #### EXECUTION RULES:
 
 - ALWAYS halt and wait for user input after presenting menu
+- **GATE [default: C]** — If `{headless_mode}`: auto-proceed with [C] Confirm, log: "headless: auto-confirm brief"
 - ONLY proceed to write step when user selects 'C'
 - After other menu items execution, return to this menu
 - User can chat, request field changes, or ask questions — always respond and then redisplay menu
@@ -190,25 +154,3 @@ Display: **Select an Option:** [R] Revise Scope [A] Advanced Elicitation [P] Par
 
 ONLY WHEN C is selected and the user has explicitly approved the brief will you load and read fully `./step-05-write-brief.md` to write the skill-brief.yaml file.
 
----
-
-## 🚨 SYSTEM SUCCESS/FAILURE METRICS
-
-### ✅ SUCCESS:
-
-- Schema loaded for field reference
-- Complete brief assembled from all gathered data
-- Brief presented in human-readable format
-- Low-confidence or defaulted fields highlighted
-- User explicitly approved the brief
-- Menu presented with revise option
-
-### ❌ SYSTEM FAILURE:
-
-- Writing skill-brief.yaml in this step (too early)
-- Proceeding without explicit user approval
-- Not presenting all required fields
-- Not highlighting defaulted or low-confidence values
-- Not offering the [R] Revise option
-
-**Master Rule:** Skipping steps, optimizing sequences, or not following exact instructions is FORBIDDEN and constitutes SYSTEM FAILURE.