bmad-module-skill-forge 1.8.0 → 2.0.0

package/src/skf-analyze-source/references/step-shape-detect.md

@@ -0,0 +1,86 @@
+---
+shapeDetectProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-shape-detect.py'
+  - '{project-root}/src/shared/scripts/skf-shape-detect.py'
+---
+
+# Shape Detection Reference
+
+Reference document for invoking `skf-shape-detect.py` — the shared shape classification module. Loaded by `step-auto-scope.md` for auto-scope analysis.
+
+## Invocation Contract
+
+**Resolve `{shapeDetectHelper}`** from `{shapeDetectProbeOrder}`; first existing path wins; HALT if neither resolves.
+
+**Command:**
+```
+uv run {shapeDetectHelper} --repo-url <url> \
+  --manifests <path1,path2,...> \
+  --grammar-files <g1,g2,...> --tree-paths <d1/,d2/,file,...>
+```
+
+**Arguments:**
+
+| Arg | Required | Description |
+|-----|----------|-------------|
+| `--repo-url` | Yes | Repository URL (context only — no cloning performed) |
+| `--manifests` | Yes | Comma-separated local file paths to manifest files (may be empty when a tree-level signal carries the classification) |
+| `--grammar-files` | No | Comma-separated repo-relative grammar files (`*.y`, `*.g4`, `*.pest`, `Grammar/python.gram`, ...) — a whole-language signal |
+| `--tree-paths` | No | Comma-separated repo-relative directory (trailing `/`) and structural file signals harvested from the clone (a `compiler/` dir, a lexer+parser+ast triad) |
+
+**Supported manifests:** `package.json`, `pyproject.toml`, `Cargo.toml`, `go.mod`, `pom.xml`, `build.gradle`, `build.gradle.kts`, `Package.swift`
+
+## Output Schema
+
+JSON object on stdout:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `shape` | string | `library-API` \| `reference-app` \| `language-reference` \| `stack-compose` \| `unknown` |
+| `signals` | array[string] | Human-readable evidence strings |
+| `confidence` | float | 0.0–1.0 |
+| `export_count` | integer | Total public-facing exports detected |
+| `package_count` | integer | Distinct packages detected |
+
+## Exit Codes
+
+| Code | Meaning | Consumer Action |
+|------|---------|-----------------|
+| 0 | Shape classified (not unknown) | Use shape result for scope mapping |
+| 1 | Unknown shape (no heuristic matched) | Fall back to interactive mode |
+| 2 | Error (invalid args, missing/unreadable files, parse failure) | HARD HALT with `resolution-failure` |
+
+On exit code 2, error details are written to stderr as JSON: `{"error": "message", "code": "ERROR_CODE"}`
+
+## Shape → Scope Type Mapping
+
+| Shape | scope.type | Condition |
+|-------|------------|-----------|
+| `library-API` | `full-library` | export_count ≤ 200 |
+| `library-API` | `public-api` | export_count > 200 (surface too large for full coverage) |
+| `reference-app` | `reference-app` | Direct mapping — apps, CLIs, demos |
+| `language-reference` | `full-library` | Language tools/parsers are library-shaped from a skill perspective. **Corpora-dependent** for a *whole-language* reference (a `grammar_file:`/`tree_triad:` signal — a compiler/interpreter): its value is the language's prose (guide/Book + std/library docs), not compiler internals, so step-auto-scope.md §6b seeds companion corpora and §6/§7 record an honest DEGRADED caveat when none are found (mirrors the §3b facet-coverage guard). A parser *library* (`parser_producer:`/`parser_dep:`) is exempt — its code is the product. |
+| `stack-compose` | `full-library` | Decomposition candidate when `package_count > 3` — cohesion-checked in step-auto-scope.md §3b |
+| `unknown` | N/A | Triggers fallback to interactive mode |
+
+## Decomposition Thresholds
+
+When auto-scope detects a multi-package monorepo, it may recommend multi-skill decomposition instead of producing one unwieldy skill. The threshold is evaluated in step-auto-scope.md §3a.
+
+| Threshold | Value | Signal | Decomposition Path |
+|-----------|-------|--------|-------------------|
+| Multi-package / monorepo | `package_count > 3` | Shape detection `package_count` | Cohesion check (§3b): merge to one skill or split per package |
+
+`package_count > 3` makes a **monorepo** a decomposition candidate; step-auto-scope.md §3b then decides merge-vs-split. It is empirically validated (fires on real 15-, 38-, and 442-package workspaces). A *single* package with a large API surface is **not** decomposed — it produces one cohesive skill that `skf-create-skill`'s auto-shard splits into `references/` shards at the 400-line ceiling.
+
+When neither threshold is met, the single-scope flow proceeds unchanged.
+
+## Heuristic Ladder
+
+The five-shape heuristic ladder applies in order (first match wins):
+
+1. **language-reference** — parser/grammar/language-toolchain project. Signals, strongest first: a hand-written-compiler tree structure (a dedicated `compiler/` directory with a lexer+parser+ast triad plus a codegen/VM/type-checker member — catches rustc, TypeScript, Go); a declared grammar file (`Grammar/python.gram`, a root `parse.y`, a `*.g4` — catches CPython, Ruby); the repo's own name being a known parser/grammar tool (pest, lalrpop, lark — the producer); or a parser-generator dependency (a DSL built on antlr4/lalrpop — the consumer). Delegating consumers (formatters, linters, bundlers that depend on a parser) and markup/DSL parsers (CSS, markdown, GraphQL) are excluded.
+2. **stack-compose** — multi-ecosystem composite project. Signals: manifests from 2+ distinct ecosystems
+3. **reference-app** — application, CLI, or demo project. Signals: npm `bin` field, Rust `[[bin]]`, framework deps (next, fastapi, axum, etc.)
+4. **library-API** — library exposing a programmatic API. Signals: `main`/`module`/`exports` fields, `[lib]` target, export count
+5. **unknown** — no heuristic matched

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

@@ -40,6 +40,7 @@ These rules apply to every step in this workflow:
 | 3 | Structural Diff | references/structural-diff.md | Yes |
 | 4 | Semantic Diff | references/semantic-diff.md | Yes (skip at non-Deep) |
 | 5 | Severity Classification | references/severity-classify.md | Yes |
+| 5a | Doc Drift | references/step-doc-drift.md | Yes |
 | 6 | Report | references/report.md | Yes |
 | 7 | Workflow Health Check | references/health-check.md | Yes |
 

package/src/skf-audit-skill/assets/drift-report-template.md

@@ -52,6 +52,12 @@ previousWorkflow: 'create-skill'
 
 ---
 
+## Documentation Drift
+
+<!-- Appended by step-doc-drift -->
+
+---
+
 ## Remediation Suggestions
 
 <!-- Appended by report -->

package/src/skf-audit-skill/references/init.md

@@ -252,7 +252,7 @@ When skipping, log the reason, then set the audit-ref context variables to basel
 - **[D]:** Read the prior report's findings_list (parse the Structural/Semantic/Severity sections, or the appended findings tables) and stash as `prior_findings` in workflow context. Run the new audit normally. In step 6 (report.md), after the Remediation Suggestions section, emit a `## Diff Against Prior Report` subsection summarizing added / removed / changed findings vs `prior_findings`.
 - **[R]:** Load the prior report's frontmatter (`stepsCompleted`, `drift_score`, any intermediate state). Set `{outputFile}` to the prior report path (do NOT create a new one). Determine the next un-completed step from `stepsCompleted` and skip forward to it; downstream steps append to the existing report.
 
-  > **Note (resumability):** the existing template frontmatter captures `stepsCompleted` and `drift_score` but does not currently persist intermediate findings_list between stages. If [R] is selected and stepsCompleted indicates the prior run halted after structural-diff or semantic-diff, the appended sections in the report body (`## Structural Drift`, `## Semantic Drift`, `## Severity Classification`) serve as the implicit intermediate state — re-parse them on resume rather than re-running completed stages. **TODO:** if resumability proves unreliable in practice, extend the report frontmatter to carry an explicit `intermediate_findings` block (out of scope for this PR).
+  > **Note (resumability):** the existing template frontmatter captures `stepsCompleted` and `drift_score` but does not currently persist intermediate findings_list between stages. If [R] is selected and stepsCompleted indicates the prior run halted after structural-diff or semantic-diff, the appended sections in the report body (`## Structural Drift`, `## Semantic Drift`, `## Severity Classification`) serve as the implicit intermediate state — re-parse them on resume rather than re-running completed stages. **Design note:** explicit mid-stage resume state is intentionally not persisted today — if resumability proves unreliable in practice, a future enhancement is to extend the report frontmatter to carry an explicit `intermediate_findings` block.
 
 - **Other input:** help user, redisplay the gate.
 

package/src/skf-audit-skill/references/report.md

@@ -27,6 +27,10 @@ Update the ## Audit Summary section at the top of {outputFile} with final calcul
 - Fill in severity count table from Step 05 classification summary
 - Set overall drift score
 - Add total findings count
+- Include doc drift summary from `doc_drift_summary` context (set by step 5a):
+  - If `changed > 0`: "**Doc Drift:** {changed} of {total_tracked} tracked doc(s) have changed since compile. Consider re-running CS to update doc_sources."
+  - If `fetch_failed > 0`: "{fetch_failed} doc URL(s) could not be reached during audit."
+  - If `skipped_entirely`: no mention in summary (already noted in the doc drift section)
 
 ### 2. Generate Remediation Suggestions
 

package/src/skf-audit-skill/references/severity-classify.md

@@ -1,5 +1,5 @@
 ---
-nextStepFile: 'report.md'
+nextStepFile: 'step-doc-drift.md'
 outputFile: '{forge_version}/drift-report-{timestamp}.md'
 severityRulesFile: 'references/severity-rules.md'
 ---

package/src/skf-audit-skill/references/step-doc-drift.md

@@ -0,0 +1,147 @@
+---
+nextStepFile: 'report.md'
+outputFile: '{forge_version}/drift-report-{timestamp}.md'
+---
+
+<!-- Config: communicate in {communication_language}. -->
+
+# Step 5a: Documentation Drift
+
+## STEP GOAL:
+
+Compare documentation content hashes stored at compile time (in `doc_sources` within metadata.json) against the current upstream state. Produce a drift section that reports which tracked docs have changed, which are unreachable, and which were never hashed. This step is informational — doc drift does not affect the source code drift score.
+
+## Rules
+
+- Auto-proceed step — no user interaction
+- Graceful failure — if doc fetching fails for any URL, mark as `fetch_failed`, do not block the audit
+- Do not classify severity — doc drift is informational alongside source drift
+- If no `doc_sources` in metadata, skip with notice and auto-proceed
+- Never abort the audit pipeline on any failure in this step
+
+## MANDATORY SEQUENCE
+
+### 1. Check for doc_sources
+
+Check the skill metadata loaded at init (step 1 §3 — Load Skill Artifacts) for a `doc_sources` array.
+
+**If `doc_sources` is absent or metadata lacks the field:**
+
+Append to {outputFile}:
+
+```markdown
+## Documentation Drift
+
+No doc_sources recorded — skip doc drift check. This skill was compiled before doc tracking was available. Recompile with the current CS pipeline to enable doc drift detection.
+```
+
+Set `doc_drift_summary = { skipped_entirely: true }` in workflow context. Update {outputFile} frontmatter: append `'doc-drift'` to `stepsCompleted`. Auto-proceed to {nextStepFile}.
+
+**If `doc_sources` is present but an empty array:**
+
+Append to {outputFile}:
+
+```markdown
+## Documentation Drift
+
+No documentation sources tracked. The `doc_sources` array is empty — no drift check to perform.
+```
+
+Set `doc_drift_summary = { total_tracked: 0, skipped_entirely: false }` in workflow context. Update {outputFile} frontmatter: append `'doc-drift'` to `stepsCompleted`. Auto-proceed to {nextStepFile}.
+
+**If `doc_sources` is present and non-empty:** Continue to §2.
+
+### 2. Fetch and Hash Each Tracked Doc
+
+For each entry in `doc_sources`:
+
+1. Read `url` and `content_hash` from the entry
+2. **If `content_hash` is `null`:** Skip this entry — there is no baseline to compare against. Record it for the report as a null-hash entry. Do not attempt to fetch the URL.
+3. **If `content_hash` is non-null:** Attempt HTTP GET of the URL with a reasonable timeout (10s)
+   - **On success:** Compute `sha256:{hexdigest}` of the response body bytes (UTF-8 encoding). Compare against the stored `content_hash`. If they differ, record as drifted. If they match, record as unchanged.
+   - **On failure (network error, timeout, non-200 status):** Record the entry as `status: "fetch_failed"` with the failure reason. Do not report as drift.
+
+If URL fetching is unavailable in the current environment, skip doc drift check entirely with:
+
+```markdown
+## Documentation Drift
+
+Doc drift check skipped — URL fetching unavailable in current environment.
+```
+
+Set `doc_drift_summary = { skipped_entirely: true }` and auto-proceed.
+
+### 3. Build Drift Findings
+
+Categorize results:
+- **changed:** entries where `content_hash` differs from newly computed hash
+- **unchanged:** entries where hashes match
+- **fetch_failed:** entries where the URL could not be reached
+- **skipped_null_hash:** entries where `content_hash` was `null`
+
+Compute totals:
+- `total_tracked` = length of `doc_sources`
+- `changed` = count of drifted entries
+- `unchanged` = count of matching entries
+- `fetch_failed` = count of fetch failures
+- `skipped_null_hash` = count of null-hash entries
+
+### 4. Append to Drift Report
+
+Append the `## Documentation Drift` section to {outputFile}.
+
+**When drift detected:**
+
+```markdown
+## Documentation Drift
+
+| URL | Old Hash | New Hash | Detected At |
+|-----|----------|----------|-------------|
+| {url} | `{old_hash}` | `{new_hash}` | {ISO-8601 timestamp} |
+
+**{changed} of {total_tracked} tracked documentation source(s) have changed since compile.**
+```
+
+Include rows for ALL entries, in order:
+- Drifted entries: show old and new hash
+- Unchanged entries: omit from table (only drifted entries appear)
+- Fetch-failed entries: `| {url} | \`{old_hash}\` | _(fetch failed: {reason})_ | {timestamp} |`
+- Null-hash entries: `| {url} | _(not recorded)_ | — | — |`
+
+Fetch-failed entries are clearly marked and excluded from the drift count.
+
+**When no drift detected:**
+
+```markdown
+## Documentation Drift
+
+No documentation drift detected. All {total_tracked} tracked documentation source(s) match their compile-time hashes.
+```
+
+If some entries were fetch_failed or skipped_null_hash, append a note after the main message listing those entries.
+
+### 5. Store Context and Auto-Proceed
+
+Store `doc_drift_summary` in workflow context for report.md to reference:
+
+```
+doc_drift_summary = {
+  total_tracked: N,
+  changed: N,
+  unchanged: N,
+  fetch_failed: N,
+  skipped_null_hash: N,
+  skipped_entirely: false
+}
+```
+
+Update {outputFile} frontmatter:
+- Append `'doc-drift'` to `stepsCompleted`
+
+Display: "**Documentation drift check complete. {changed} of {total_tracked} source(s) drifted. Proceeding to report generation...**"
+
+Load, read the full file, then execute {nextStepFile}.
+
+## CRITICAL STEP COMPLETION NOTE
+
+ONLY WHEN the ## Documentation Drift section has been appended to {outputFile} and workflow context updated will you then load and read fully `{nextStepFile}` to begin final report generation.

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

@@ -73,17 +73,21 @@ These rules apply to every step in this workflow:
 | # | Step | File | Auto-proceed |
 |---|------|------|--------------|
 | 1 | Gather Intent | references/gather-intent.md | No (interactive) |
+| 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 |
 | 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 |
 | 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).
+
 ## Invocation Contract
 
 | Aspect | Detail |
 |--------|--------|
-| **Inputs** | `target_repo` [required], `skill_name` [required], `scope_hint` [optional], `language_hint` [optional], `target_version` [optional], `source_authority` [optional: official/community/internal, default community], `source_type` [optional: source/docs-only, default source], `doc_urls` [optional: list of `url[,label]` for source_type=docs-only or supplemental], `scope_type` [optional: full-library/specific-modules/public-api/component-library/reference-app/docs-only], `include` [optional: comma-separated globs], `exclude` [optional: comma-separated globs], `scripts_intent` [optional: detect/none/free-text, default detect], `assets_intent` [optional: detect/none/free-text, default detect], `intent` [optional: free-text used to derive description], `force` [optional: overwrite existing brief without prompting], `from_brief` [optional: path to a pre-authored `skill-brief.yaml` to *ratify* — when supplied it is the source of truth, `target_repo`/`skill_name` become optional/derived-from-brief, and the run mirrors the interactive §3.1a ratify path: schema-validate, skip analyze-target/scope-definition, write through the canonical writer in place] |
+| **Inputs** | `target_repo` [required], `skill_name` [required], `scope_hint` [optional], `language_hint` [optional], `target_version` [optional], `source_authority` [optional: official/community/internal, default community], `source_type` [optional: source/docs-only, default source], `doc_urls` [optional: list of `url[,label]` for source_type=docs-only or supplemental], `scope_type` [optional: full-library/specific-modules/public-api/component-library/reference-app/docs-only], `include` [optional: comma-separated globs], `exclude` [optional: comma-separated globs], `scripts_intent` [optional: detect/none/free-text, default detect], `assets_intent` [optional: detect/none/free-text, default detect], `intent` [optional: free-text used to derive description], `force` [optional: overwrite existing brief without prompting], `from_brief` [optional: path to a pre-authored `skill-brief.yaml` to *ratify* — when supplied it is the source of truth, `target_repo`/`skill_name` become optional/derived-from-brief, and the run mirrors the interactive §3.1a ratify path: schema-validate, skip analyze-target/scope-definition, write through the canonical writer in place], `[auto]` [optional: bracket modifier passed via pipeline context — when present, BS loads the upstream brief from `brief_path` in pipeline data, enriches it with doc detection, and writes through the canonical writer; requires `brief_path` from AN's `SKF_ANALYZE_RESULT_JSON`] |
 | **Gates** | step 1: Input Gate [use args] | step 3: Confirm Gate [C] | step 4: Confirm Gate [C] |
 | **Outputs** | `skill-brief.yaml` at `{forge_data_folder}/{skill-name}/skill-brief.yaml`; final `SKF_BRIEF_RESULT_JSON` line on stdout when `{headless_mode}` is true |
 | **Headless** | All gates auto-resolve with heuristic-driven or default action when `{headless_mode}` is true; pre-supplied inputs consumed at the gates that would otherwise prompt; absent `source_authority` and `scope_type` are resolved by signal-driven detection (see `references/headless-args.md`); existing briefs are preserved unless `--force` was supplied (HALT with `overwrite-cancelled` otherwise); supplying `from_brief <path>` instead routes the step 1 GATE to a ratify path that schema-validates the pre-authored brief, skips analyze-target/scope-definition, and writes through the canonical writer (overwriting in place, no `--force` needed) rather than deriving a new brief |
@@ -108,7 +112,7 @@ Every HARD HALT in this workflow exits with a stable code so headless automators
 When `{headless_mode}` is true, step 5 emits a single-line JSON envelope on **stdout** before chaining to step 6, and every HARD HALT emits the same envelope shape on **stderr** with `status: "error"`:
 
 ```
-SKF_BRIEF_RESULT_JSON: {"status":"success|error","brief_path":"…|null","skill_name":"…","version":"…|null","language":"…|null","scope_type":"…|null","exit_code":0,"halt_reason":null}
+SKF_BRIEF_RESULT_JSON: {"status":"success|error","brief_path":"…|null","skill_name":"…","version":"…|null","language":"…|null","scope_type":"…|null","exit_code":0,"halt_reason":null,"mode":"auto|null"}
 ```
 
-`status` is `"success"` on the terminal happy path, `"error"` on any HALT. `halt_reason` is one of: `null` (success), `"input-missing"`, `"input-invalid"`, `"forge-tier-missing"`, `"target-inaccessible"`, `"gh-auth-failed"`, `"write-failed"`, `"overwrite-cancelled"`, `"user-cancelled"`. `exit_code` matches the table above.
+`status` is `"success"` on the terminal happy path, `"error"` on any HALT. `halt_reason` is one of: `null` (success), `"input-missing"`, `"input-invalid"`, `"forge-tier-missing"`, `"target-inaccessible"`, `"gh-auth-failed"`, `"write-failed"`, `"overwrite-cancelled"`, `"user-cancelled"`. `exit_code` matches the table above. `mode` is `"auto"` when BS was invoked with the `[auto]` flag (pipeline auto-brief generation), `null` otherwise (interactive or headless-without-auto).

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

@@ -19,7 +19,7 @@
 | 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"`                                                                                                                                                    |
+| doc_urls           | array  | `{url, label, source?}` objects                  | Documentation URLs for T3 content. Required when `source_type: "docs-only"`. Optional `source` provenance enum: `language-registry` (registry-guaranteed corpus) \| `readme-detection` \| `homepage` \| `pages-api` \| `docs-folder` |
 | `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.                                                   |

package/src/skf-brief-skill/references/analyze-target.md

@@ -10,6 +10,9 @@ detectWorkspacesProbeOrder:
 detectLanguageProbeOrder:
   - '{project-root}/_bmad/skf/shared/scripts/skf-detect-language.py'
   - '{project-root}/src/shared/scripts/skf-detect-language.py'
+emitBriefEnvelopeProbeOrder:
+  - '{project-root}/_bmad/skf/shared/scripts/skf-emit-brief-result-envelope.py'
+  - '{project-root}/src/shared/scripts/skf-emit-brief-result-envelope.py'
 ---
 
 <!-- Config: communicate in {communication_language}. -->
@@ -56,10 +59,10 @@ To analyze the target repository by resolving its location, reading its structur
 
 **On API failure (non-200 from `gh api`):**
 
-Distinguish the failure class before reporting:
-- Auto-run `gh auth status` and capture its output. If it reports an unauthenticated state or expired token: HALT (exit code 3, `halt_reason: "gh-auth-failed"`) — "**Error:** GitHub CLI is not authenticated. `gh auth status` says: `{captured output}`. Run `gh auth login` and retry."
-- If `gh auth status` reports authenticated but the call still failed (404/403): HALT (exit code 3, `halt_reason: "target-inaccessible"`) — "**Error:** Cannot access repository at `{url}`. The CLI is authenticated but the API returned `{status}`. Check the URL and that the account has access to private repositories if applicable."
-- If `gh auth status` itself fails to run (binary missing): HALT (exit code 3, `halt_reason: "gh-auth-failed"`) — "**Error:** `gh` CLI not found on PATH. Install it from <https://cli.github.com> and re-run."
+Distinguish the failure class before reporting. In headless mode, every branch below emits the error envelope per **step 5 §4b** with its stated `halt_reason` before the HALT (pass the resolved `{skill_name}`, or the `"unknown"` placeholder documented in §4b if it is not yet set):
+- Auto-run `gh auth status` and capture its output. If it reports an unauthenticated state or expired token: emit the error envelope per **step 5 §4b** with `halt_reason: "gh-auth-failed"`, then HALT (exit code 3, `halt_reason: "gh-auth-failed"`) — "**Error:** GitHub CLI is not authenticated. `gh auth status` says: `{captured output}`. Run `gh auth login` and retry."
+- If `gh auth status` reports authenticated but the call still failed (404/403): emit the error envelope per **step 5 §4b** with `halt_reason: "target-inaccessible"`, then HALT (exit code 3, `halt_reason: "target-inaccessible"`) — "**Error:** Cannot access repository at `{url}`. The CLI is authenticated but the API returned `{status}`. Check the URL and that the account has access to private repositories if applicable."
+- If `gh auth status` itself fails to run (binary missing): emit the error envelope per **step 5 §4b** with `halt_reason: "gh-auth-failed"`, then HALT (exit code 3, `halt_reason: "gh-auth-failed"`) — "**Error:** `gh` CLI not found on PATH. Install it from <https://cli.github.com> and re-run."
 
 **For local paths:**
 - Verify the directory exists

package/src/skf-brief-skill/references/confirm-brief.md

@@ -1,7 +1,6 @@
 ---
 nextStepFile: 'write-brief.md'
 reviseStepFile: 'scope-definition.md'
-briefSchemaFile: 'assets/skill-brief-schema.md'
 advancedElicitationSkill: '/bmad-advanced-elicitation'
 partyModeSkill: '/bmad-party-mode'
 ---

package/src/skf-brief-skill/references/gather-intent.md

@@ -2,7 +2,6 @@
 nextStepFile: 'analyze-target.md'
 ratifyTargetFile: 'confirm-brief.md'
 forgeTierFile: '{sidecar_path}/forge-tier.yaml'
-descriptionVoiceExamplesFile: 'assets/description-voice-examples.md'
 headlessArgsFile: 'references/headless-args.md'
 headlessSourceAuthorityDetectionFile: 'references/headless-source-authority-detection.md'
 portfolioSimilarityCheckFile: 'references/portfolio-similarity-check.md'
@@ -61,8 +60,23 @@ Attempt to load `{forgeTierFile}`:
 
 **If not found:**
 - "**Cannot proceed.** forge-tier.yaml not found at `{forgeTierFile}`. Run the **setup** workflow first to configure your forge tier (Quick/Forge/Forge+/Deep)."
+- In headless mode, emit the error envelope per **step 5 §4b** with `halt_reason: "forge-tier-missing"` (`skill_name` is not yet resolved here — use the `"unknown"` placeholder convention documented in §4b).
 - HALT (exit code 3, `halt_reason: "forge-tier-missing"`) — do not proceed.
 
+### 1b. Auto Mode Check
+
+**Check for `[auto]` flag:** If `[auto]` was passed as a bracket modifier in the pipeline context (e.g., `BS[auto]`), set `{auto_mode}` = true.
+
+**IF `{auto_mode}` is true:**
+
+1. **Load upstream brief path:** Read `brief_path` from the pipeline data context (passed by the forger from AN's `SKF_ANALYZE_RESULT_JSON` `brief_paths[]`). If `brief_path` is not available, HARD HALT with exit code 2 (`input-missing`): "**Auto mode requires `brief_path` in pipeline context — AN must run before BS[auto].**"
+2. **Load source repo:** Read `source_repo` from the pipeline data context (the target repo URL or path, forwarded by the forger). If not available, attempt to extract it from the upstream brief at `brief_path`.
+3. "**Auto mode activated — bypassing interactive brief workflow.**"
+4. **Route to auto-brief:** Load, read fully, then execute `references/step-auto-brief.md`. **STOP HERE** — do not continue to §2 or any subsequent section.
+
+**IF `{auto_mode}` is NOT true:**
+Continue to §2 as normal — the entire interactive flow below is unchanged.
+
 ### 2. Welcome and Explain
 
 "**Welcome to Brief Skill — the skill scoping workflow.**
@@ -92,8 +106,12 @@ This section has four sub-flows. Execute exactly one branch — 3.1a *or* 3.2 *o
 
 #### 3.1 Collect target
 
+**Open-floor opening.** Lead with an open invitation so an expert can state everything in one breath rather than being walked through seven discrete prompts — costs almost nothing token-wise and sharply improves the conversational feel of this, the most question-heavy mode. A first-timer who pastes only a bare URL still gets the full guided sequence below, unchanged.
+
 "**What repository or documentation do you want to create a skill for?**
 
+Tell me everything you have — the repo or docs, what you want to skill and why, any scope or version thoughts. Or just paste a URL and we'll go from there.
+
 Provide one of:
 - A **GitHub URL** (e.g., `https://github.com/org/repo`)
 - A **local path** (e.g., `/path/to/project`)
@@ -104,7 +122,7 @@ Or type `cancel` / `exit` / `[X]` to leave without writing anything.
 
 **Target:**"
 
-Wait for user response. Branch on the response:
+Wait for user response. **Parse the response for any of the fields the later sections collect** — `target_version` (§3b), intent (§4), scope hints (§5), source authority (§3.3), a proposed name (§6) — and pre-fill every field the user covered, holding them in workflow context. Sections §3b/§4/§5/§6/§7b then **acknowledge a pre-filled field instead of re-asking** ("I noted you're targeting v4.0.0"), and prompt only for the gaps. An expert who stated it all collapses to the §3.1 target branch plus the §7b description confirmation; a bare URL falls through to the full sequence. Then branch on the response for the target itself:
 
 - Empty input, `cancel`, `exit`, `[X]`, `q`, or `:q` → Display `"Cancelled — no brief was written."` and HALT (exit code 6, `halt_reason: "user-cancelled"`). Cancellation here is non-destructive — no files have been written yet by step 1. Headless mode never reaches this branch (the GATE in §8 short-circuits the interactive sub-flows).
 - Path that resolves to an existing `skill-brief.yaml` (file path ending in `skill-brief.yaml` that exists, OR a directory containing a `skill-brief.yaml`) → §3.1a
@@ -253,6 +271,8 @@ Take your time — the more context you share, the better the brief."
 
 Wait for user response. Ask follow-up questions if intent is unclear.
 
+**Capture, don't interrupt.** If the user volunteers an out-of-scope aside while answering — "the v3 API is totally different", "we're deprecating the auth module next quarter" — do not redirect the conversation to chase it. Silently note it as a candidate `scope.notes` line (carried forward into the brief's `scope.notes` at step 3) and continue the current prompt. These unprompted asides are often the most useful scoping signal; the cost of losing them when the conversation moves on is higher than the cost of one stored line.
+
 ### 5. Capture Scope Hints
 
 If the user mentioned scope preferences in their intent response, acknowledge them:

package/src/skf-brief-skill/references/scope-definition.md

@@ -1,6 +1,5 @@
 ---
 nextStepFile: 'confirm-brief.md'
-scopeTemplatesFile: 'assets/scope-templates.md'
 recommendScopeTypeProbeOrder:
   - '{project-root}/_bmad/skf/shared/scripts/skf-recommend-scope-type.py'
   - '{project-root}/src/shared/scripts/skf-recommend-scope-type.py'
@@ -120,6 +119,8 @@ How broadly should this skill cover the library?
 
 Press Enter to accept the recommendation, or pick a different letter."
 
+**First-timer reassurance (interactive only, never-briefed user — the §4 first-timer rail fired in step 01).** Append one line so the harder scope-type call doesn't stall a first-timer: "The recommended type is almost always right — accept it and re-scope from step 4 if the analysis surprises you." Repeat users and headless skip this line.
+
 Wait for user selection. Empty input or just Enter accepts the recommendation; any of the five letters overrides.
 
 ### 3. Define Boundaries Based on Selection