bmad-module-skill-forge 1.3.0 → 1.4.0

package/src/shared/scripts/skf-write-skill-brief.py

@@ -0,0 +1,509 @@
+# /// script
+# requires-python = ">=3.10"
+# dependencies = ["pyyaml"]
+# ///
+"""SKF Write Skill Brief — Schema-validated atomic writer for skill-brief.yaml.
+
+Replaces the prose-driven YAML emission, version-precedence resolution,
+conditional optional-field rendering, and non-atomic file write currently
+inlined in `src/skf-brief-skill/steps-c/step-05-write-brief.md` §3-§4.
+
+Each of those operations is purely deterministic: there is no LLM
+judgement required to render the YAML, decide which optional fields
+appear, resolve target_version vs. detected vs. default, or write the
+file atomically. Keeping that work in prose creates four schema-drift
+seams (key order, YAML formatting, conditional field inclusion rules,
+atomic-write behaviour) that the LLM cannot fully close on every
+invocation. This script is the single source of truth.
+
+Subcommand:
+
+  write   Read brief context as JSON on stdin, validate against
+          src/shared/scripts/schemas/skill-brief.v1.json, apply
+          version-precedence rules, render the canonical YAML, and
+          atomically write to --target. Emits a JSON success envelope
+          on stdout.
+
+Context payload shape (consumed by `write`):
+
+  {
+    "name":             "marked",
+    "version_resolved": "1.2.3",   # OR omit and provide:
+    "target_version":   "1.2.3" | null,
+    "detected_version": "1.2.3" | null,
+
+    "source_type":      "source" | "docs-only",
+    "source_repo":      "https://github.com/...",
+    "language":         "javascript",
+    "description":      "...",
+    "forge_tier":       "Quick" | "Forge" | "Forge+" | "Deep",
+    "created":          "2026-05-02",     # ISO date
+    "created_by":       "armel",
+
+    "scope": {
+      "type":    "full-library" | ...,
+      "include": ["src/**/*.ts"],
+      "exclude": ["**/*.test.*"],
+      "notes":   ""
+    },
+
+    # Conditionally present:
+    "doc_urls":         [{"url": "...", "label": "..."}],
+    "scripts_intent":   "detect" | "none" | free-text,
+    "assets_intent":    "detect" | "none" | free-text,
+    "source_authority": "official" | "community" | "internal"
+  }
+
+Version precedence (resolved into the rendered YAML's `version` field):
+  1. version_resolved if explicitly supplied (caller already ran the
+     precedence rule). Used by step-05 when it has confirmed values.
+  2. Otherwise: target_version if non-null.
+  3. Otherwise: detected_version if non-null.
+  4. Otherwise: "1.0.0".
+
+When target_version is set, the rendered YAML includes a `target_version`
+field whose value MUST match `version` (the script enforces this
+invariant before write — refuses to emit a brief that violates it).
+
+Flat input form (`--from-flat`):
+
+  Identical semantics, friendlier shape for prose-driven callers — scope
+  is split across four top-level keys instead of nested, and every
+  optional field can be passed as `null` without the caller deciding
+  what to omit. The script translates flat → nested and runs the same
+  validator + writer pipeline.
+
+  {
+    "name":             "marked",
+    "target_version":   "1.2.3" | null,
+    "detected_version": "1.2.3" | null,
+    "source_type":      "source",
+    "source_repo":      "https://github.com/...",
+    "language":         "javascript",
+    "description":      "...",
+    "forge_tier":       "Quick",
+    "created":          "2026-05-02",
+    "created_by":       "armel",
+    "scope_type":       "full-library",
+    "scope_include":    ["src/**/*.ts"],
+    "scope_exclude":    ["**/*.test.*"],
+    "scope_notes":      "",
+    "doc_urls":         null | [...],
+    "scripts_intent":   null | "detect" | "none" | "...",
+    "assets_intent":    null | "detect" | "none" | "...",
+    "source_authority": null | "official" | "community" | "internal"
+  }
+
+Output (success):
+
+  {
+    "status":     "ok",
+    "brief_path": "/abs/path/skill-brief.yaml",
+    "version":    "<resolved version>",
+    "bytes":      <integer>,
+    "warnings":   ["string", ...]
+  }
+
+Errors emit `{"status": "error", "message": "...", "field": "..."|null}`
+to stderr and exit non-zero.
+
+Exit codes:
+  0  — success
+  1  — validation failure (bad context, schema violation, invariant
+       violation, version-precedence underflow with no fallback path)
+  2  — I/O failure (atomic write failed, parent directory not writable)
+
+Cross-platform: pure stdlib + PyYAML. Atomic write via temp + fsync +
+rename, mirroring skf-atomic-write.py and the helper in
+skf-forge-tier-rw.py.
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import re
+import sys
+from pathlib import Path
+from typing import Any
+
+import yaml
+
+
+KEBAB_RE = re.compile(r"^[a-z0-9]([a-z0-9-]*[a-z0-9])?$")
+SEMVER_RE = re.compile(
+    r"^v?\d+\.\d+\.\d+([.\-+][0-9A-Za-z][0-9A-Za-z.\-+]*)?$"
+)
+ISO_DATE_RE = re.compile(r"^\d{4}-\d{2}-\d{2}$")
+
+VALID_SOURCE_TYPES = {"source", "docs-only"}
+VALID_SOURCE_AUTHORITIES = {"official", "community", "internal"}
+VALID_FORGE_TIERS = {"Quick", "Forge", "Forge+", "Deep"}
+VALID_SCOPE_TYPES = {
+    "full-library",
+    "specific-modules",
+    "public-api",
+    "component-library",
+    "reference-app",
+    "docs-only",
+}
+
+
+def _die(message: str, field: str | None = None, code: int = 1) -> None:
+    payload = {"status": "error", "message": message}
+    if field is not None:
+        payload["field"] = field
+    sys.stderr.write(json.dumps(payload) + "\n")
+    sys.exit(code)
+
+
+def resolve_version(ctx: dict[str, Any]) -> str:
+    """Apply the version-precedence rule. Returns the resolved version string.
+
+    Uses `is not None` checks (not truthiness) so an explicitly-supplied
+    empty string surfaces as a SEMVER_RE validation failure downstream
+    rather than silently falling through to the next precedence level.
+    """
+    vr = ctx.get("version_resolved")
+    if vr is not None:
+        return vr
+    tv = ctx.get("target_version")
+    if tv is not None:
+        return tv
+    dv = ctx.get("detected_version")
+    if dv is not None:
+        return dv
+    return "1.0.0"
+
+
+def validate_context(ctx: dict[str, Any]) -> list[str]:
+    """Validate the context payload. Raises via _die on hard errors; returns warnings."""
+    warnings: list[str] = []
+
+    # Required string fields
+    for field in ("name", "source_repo", "language", "description",
+                  "forge_tier", "created", "created_by"):
+        v = ctx.get(field)
+        if not v or not isinstance(v, str):
+            _die(f"required field {field!r} missing or not a non-empty string", field=field)
+
+    # Name must be kebab
+    if not KEBAB_RE.match(ctx["name"]):
+        _die(
+            f"name must be kebab-case (lowercase letters/digits/hyphens, no leading/trailing hyphen). "
+            f"Got: {ctx['name']!r}",
+            field="name",
+        )
+
+    # forge_tier enum
+    if ctx["forge_tier"] not in VALID_FORGE_TIERS:
+        _die(
+            f"forge_tier must be one of {sorted(VALID_FORGE_TIERS)}. Got: {ctx['forge_tier']!r}",
+            field="forge_tier",
+        )
+
+    # created ISO date
+    if not ISO_DATE_RE.match(ctx["created"]):
+        _die(
+            f"created must be an ISO date (YYYY-MM-DD). Got: {ctx['created']!r}",
+            field="created",
+        )
+
+    # source_type (default 'source') and conditional doc_urls
+    source_type = ctx.get("source_type", "source")
+    if source_type not in VALID_SOURCE_TYPES:
+        _die(
+            f"source_type must be one of {sorted(VALID_SOURCE_TYPES)}. Got: {source_type!r}",
+            field="source_type",
+        )
+
+    doc_urls = ctx.get("doc_urls")
+    if source_type == "docs-only":
+        if not doc_urls or not isinstance(doc_urls, list) or len(doc_urls) == 0:
+            _die("source_type=docs-only requires at least one entry in doc_urls", field="doc_urls")
+    if doc_urls is not None:
+        if not isinstance(doc_urls, list):
+            _die("doc_urls must be an array of objects", field="doc_urls")
+        for i, entry in enumerate(doc_urls):
+            if not isinstance(entry, dict):
+                _die(f"doc_urls[{i}] must be an object with at least a 'url' field", field="doc_urls")
+            url = entry.get("url")
+            if not url or not isinstance(url, str):
+                _die(f"doc_urls[{i}].url is required and must be a non-empty string", field="doc_urls")
+
+    # source_authority (default 'community') with docs-only force rule
+    source_authority = ctx.get("source_authority", "community")
+    if source_authority not in VALID_SOURCE_AUTHORITIES:
+        _die(
+            f"source_authority must be one of {sorted(VALID_SOURCE_AUTHORITIES)}. Got: {source_authority!r}",
+            field="source_authority",
+        )
+    if source_type == "docs-only" and source_authority != "community":
+        warnings.append(
+            f"source_authority forced to 'community' for docs-only (was {source_authority!r})"
+        )
+
+    # scope object
+    scope = ctx.get("scope")
+    if not isinstance(scope, dict):
+        _die("scope must be an object", field="scope")
+    for sf in ("type", "include", "exclude", "notes"):
+        if sf not in scope:
+            _die(f"scope.{sf} is required", field=f"scope.{sf}")
+    if scope["type"] not in VALID_SCOPE_TYPES:
+        _die(
+            f"scope.type must be one of {sorted(VALID_SCOPE_TYPES)}. Got: {scope['type']!r}",
+            field="scope.type",
+        )
+    if not isinstance(scope["include"], list):
+        _die("scope.include must be an array of glob strings", field="scope.include")
+    if not isinstance(scope["exclude"], list):
+        _die("scope.exclude must be an array of glob strings", field="scope.exclude")
+    if not isinstance(scope["notes"], str):
+        _die("scope.notes must be a string (use empty string when no notes)", field="scope.notes")
+
+    # target_version semver shape (when present)
+    tv = ctx.get("target_version")
+    if tv is not None:
+        if not isinstance(tv, str) or not SEMVER_RE.match(tv):
+            _die(
+                f"target_version must be full X.Y.Z semver (with optional v prefix and pre-release/build). "
+                f"Got: {tv!r}",
+                field="target_version",
+            )
+
+    detected = ctx.get("detected_version")
+    if detected is not None and (not isinstance(detected, str) or not SEMVER_RE.match(detected)):
+        # Warn rather than HALT — auto-detection upstream may surface odd shapes
+        warnings.append(
+            f"detected_version {detected!r} is not full X.Y.Z semver — falling through to default 1.0.0"
+        )
+
+    return warnings
+
+
+def assemble_brief(ctx: dict[str, Any], resolved_version: str) -> dict[str, Any]:
+    """Build the final brief dict that will be YAML-dumped, in canonical key order."""
+    source_type = ctx.get("source_type", "source")
+    source_authority = ctx.get("source_authority", "community")
+    if source_type == "docs-only":
+        source_authority = "community"  # forced
+
+    brief: dict[str, Any] = {
+        "name": ctx["name"],
+        "version": resolved_version,
+        "source_type": source_type,
+        "source_repo": ctx["source_repo"],
+        "language": ctx["language"],
+        "description": ctx["description"],
+        "forge_tier": ctx["forge_tier"],
+        "created": ctx["created"],
+        "created_by": ctx["created_by"],
+        "scope": {
+            "type": ctx["scope"]["type"],
+            "include": list(ctx["scope"]["include"]),
+            "exclude": list(ctx["scope"]["exclude"]),
+            "notes": ctx["scope"]["notes"],
+        },
+    }
+
+    # Conditional: target_version (must equal version)
+    tv = ctx.get("target_version")
+    if tv is not None:
+        if tv != resolved_version:
+            _die(
+                f"invariant violation: target_version ({tv!r}) must equal version "
+                f"({resolved_version!r}); see references/version-resolution.md",
+                field="target_version",
+            )
+        brief["target_version"] = tv
+
+    # Conditional: doc_urls (always emitted when present)
+    doc_urls = ctx.get("doc_urls")
+    if doc_urls:
+        brief["doc_urls"] = [
+            {"url": e["url"], "label": e.get("label", "")} for e in doc_urls
+        ]
+
+    # Conditional: scripts_intent / assets_intent — emit when explicitly non-detect
+    for intent_field in ("scripts_intent", "assets_intent"):
+        v = ctx.get(intent_field)
+        if v is not None and v != "detect":
+            brief[intent_field] = v
+
+    # Emit source_authority only when non-default — schema lists it as Optional
+    # in src/skf-brief-skill/assets/skill-brief-schema.md, and unconditional
+    # emission would inject the field into round-tripped briefs that previously
+    # omitted it (false-drift signal for diff tooling). Consumers default to
+    # "community" when the field is absent.
+    if source_authority != "community":
+        brief["source_authority"] = source_authority
+
+    return brief
+
+
+def render_yaml(brief: dict[str, Any]) -> str:
+    """Dump the brief dict as YAML in canonical key order with a leading document marker.
+
+    The step-05 §3 template shows leading and trailing `---` markers, but those were
+    wrapping the example YAML for documentation purposes — actual on-disk YAML uses
+    only the leading `---` (or none). A trailing `---` would start a second empty
+    document and break callers that use `yaml.safe_load` (which expects a single
+    document) — and skf-create-skill / audit-skill / update-skill all use
+    `yaml.safe_load`, so consistency with their loaders matters.
+    """
+    body = yaml.safe_dump(
+        brief,
+        default_flow_style=False,
+        sort_keys=False,
+        allow_unicode=True,
+    )
+    return "---\n" + body
+
+
+def atomic_write(target: Path, content: str) -> int:
+    """Crash-safe write via temp + fsync + rename. Returns bytes written."""
+    target.parent.mkdir(parents=True, exist_ok=True)
+    tmp = target.with_name(target.name + ".skf-tmp")
+    encoded = content.encode("utf-8")
+    try:
+        fd = os.open(tmp, os.O_WRONLY | os.O_CREAT | os.O_TRUNC, 0o644)
+        try:
+            os.write(fd, encoded)
+            os.fsync(fd)
+        finally:
+            os.close(fd)
+        os.replace(tmp, target)
+    except OSError as e:
+        if tmp.exists():
+            try:
+                tmp.unlink()
+            except OSError:
+                pass
+        _die(f"atomic write failed for {target}: {e}", code=2)
+    return len(encoded)
+
+
+# Top-level keys that get folded into the nested `scope` sub-object — every
+# other top-level key passes through unchanged so future additions to the
+# schema don't require a translator update.
+_FLAT_SCOPE_KEYS = ("scope_type", "scope_include", "scope_exclude", "scope_notes")
+
+
+def flat_to_nested(flat: dict[str, Any]) -> dict[str, Any]:
+    """Translate the flat brief-context shape into the nested shape consumed by validate_context.
+
+    Flat shape: scope is split across four top-level keys (`scope_type`,
+    `scope_include`, `scope_exclude`, `scope_notes`) instead of nested
+    under a `scope` object. Optional top-level fields (`doc_urls`,
+    `scripts_intent`, `assets_intent`, `source_authority`,
+    `target_version`, `detected_version`) may be absent or null —
+    they are simply dropped from the nested output, which matches the
+    existing validator's `ctx.get(...) is None` semantics.
+
+    Any unknown top-level keys are passed through unchanged so future
+    additions don't require a translator update.
+    """
+    if not isinstance(flat, dict):
+        _die("write --from-flat: payload must be a JSON object")
+
+    nested: dict[str, Any] = {}
+
+    # Pass through every top-level key that isn't part of the flat-scope
+    # split. Drop None values so optional fields behave as "absent" in
+    # the nested form (validate_context uses `is not None` checks).
+    for key, value in flat.items():
+        if key in _FLAT_SCOPE_KEYS:
+            continue
+        if value is None:
+            continue
+        nested[key] = value
+
+    # Build the nested scope object. All four scope_* keys (type, include,
+    # exclude, notes) are required at the schema level — null is
+    # intentionally treated as "absent" here (same as omitting the key)
+    # so validate_context surfaces `scope.<field> is required` rather
+    # than e.g. `scope.notes must be a string`. The `""` valid minimum
+    # for scope_notes must therefore be passed as the literal empty
+    # string, not null.
+    if any(k in flat for k in _FLAT_SCOPE_KEYS):
+        scope: dict[str, Any] = {}
+        if "scope_type" in flat and flat["scope_type"] is not None:
+            scope["type"] = flat["scope_type"]
+        if "scope_include" in flat and flat["scope_include"] is not None:
+            scope["include"] = flat["scope_include"]
+        if "scope_exclude" in flat and flat["scope_exclude"] is not None:
+            scope["exclude"] = flat["scope_exclude"]
+        if "scope_notes" in flat and flat["scope_notes"] is not None:
+            scope["notes"] = flat["scope_notes"]
+        nested["scope"] = scope
+    return nested
+
+
+def cmd_write(target: Path, from_flat: bool = False) -> int:
+    raw = sys.stdin.read()
+    if not raw or not raw.strip():
+        _die("write: empty stdin (expected JSON brief context)")
+    try:
+        ctx = json.loads(raw)
+    except json.JSONDecodeError as e:
+        _die(f"write: invalid JSON on stdin: {e}")
+    if not isinstance(ctx, dict):
+        _die("write: context payload must be a JSON object")
+
+    if from_flat:
+        ctx = flat_to_nested(ctx)
+
+    warnings = validate_context(ctx)
+    resolved_version = resolve_version(ctx)
+    if not SEMVER_RE.match(resolved_version):
+        _die(
+            f"resolved version {resolved_version!r} is not full X.Y.Z semver — "
+            f"check version_resolved / target_version / detected_version inputs",
+            field="version",
+        )
+
+    brief = assemble_brief(ctx, resolved_version)
+    content = render_yaml(brief)
+    bytes_written = atomic_write(target, content)
+
+    response = {
+        "status": "ok",
+        "brief_path": str(target.resolve()),
+        "version": resolved_version,
+        "bytes": bytes_written,
+        "warnings": warnings,
+    }
+    print(json.dumps(response))
+    return 0
+
+
+def main() -> int:
+    parser = argparse.ArgumentParser(
+        prog="skf-write-skill-brief",
+        description="Schema-validated atomic writer for skill-brief.yaml.",
+    )
+    sub = parser.add_subparsers(dest="cmd", required=True)
+    p_write = sub.add_parser("write", help="Read brief context JSON on stdin, validate, render YAML, atomic write")
+    p_write.add_argument("--target", type=Path, required=True, help="Absolute path to skill-brief.yaml")
+    p_write.add_argument(
+        "--from-flat",
+        action="store_true",
+        help=(
+            "Accept the flat brief-context shape (scope split across "
+            "scope_type/scope_include/scope_exclude/scope_notes top-level keys, "
+            "optional fields nullable) instead of the nested shape. Eliminates "
+            "the conditional-omit logic the LLM currently walks at the §3 "
+            "assembly site in step-05."
+        ),
+    )
+
+    args = parser.parse_args()
+    if args.cmd == "write":
+        return cmd_write(args.target, from_flat=args.from_flat)
+    return 2
+
+
+if __name__ == "__main__":
+    sys.exit(main())

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

@@ -1,13 +1,17 @@
 ---
 name: skf-brief-skill
-description: Design a skill scope through guided discovery. Use when the user requests to "create a skill brief" or "brief a skill."
+description: Design a skill scope through guided discovery. Use when the user requests to "create a skill brief" or "brief a skill".
 ---
 
 # Brief Skill
 
 ## Overview
 
-Helps the user define what to skill — target repo, scope, language, inclusion/exclusion patterns — and produces a skill-brief.yaml that drives create-skill. This is the first step in the skill creation pipeline. The brief becomes the input contract for create-skill, which performs the actual compilation.
+Helps the user define what to skill — target repo, scope, language, inclusion/exclusion patterns — and produces a `skill-brief.yaml` that drives create-skill. This is the first step in the skill creation pipeline; the brief is the input contract for create-skill, which performs the actual compilation.
+
+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.
+
+Brief-skill is split from create-skill so the scoping conversation runs *once*, on cheap signals (manifests, top-level exports, intent), without paying for AST extraction. Compilation is expensive; scoping decisions are cheap to revise. Keeping them in separate workflows lets a user iterate on the brief, share it for review, and re-run create-skill against the same brief whenever the upstream version moves.
 
 ## Role
 
@@ -20,9 +24,19 @@ These rules apply to every step in this workflow:
 - Read each step file completely before taking any action
 - Follow the mandatory sequence in each step exactly — do not skip, reorder, or optimize
 - Only load one step file at a time — never preload future steps
-- Always communicate in `{communication_language}`
+- **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 `{extractPublicApiScript}` 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.
+- 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-05). 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
 
+## 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`
+
+2. **Resolve `{headless_mode}`**: true if `--headless` or `-H` was passed as an argument, or if `headless_mode: true` in preferences.yaml. Default: false.
+
+3. Load, read the full file, and execute `./steps-c/step-01-gather-intent.md`.
+
 ## Stages
 
 | # | Step | File | Auto-proceed |
@@ -32,22 +46,37 @@ These rules apply to every step in this workflow:
 | 3 | Scope Definition | steps-c/step-03-scope-definition.md | No (interactive) |
 | 4 | Confirm Brief | steps-c/step-04-confirm-brief.md | No (confirm) |
 | 5 | Write Brief | steps-c/step-05-write-brief.md | Yes |
-| 6 | Workflow Health Check | steps-c/step-06-health-check.md | Yes |
+| 6 | Workflow Health Check (terminal) | steps-c/step-06-health-check.md | Yes |
 
 ## Invocation Contract
 
 | Aspect | Detail |
 |--------|--------|
-| **Inputs** | target_repo [required], skill_name [required], scope_hint [optional], language_hint [optional] |
+| **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] |
 | **Gates** | step-01: Input Gate [use args] | step-03: Confirm Gate [C] | step-04: Confirm Gate [C] |
-| **Outputs** | skill-brief.yaml |
-| **Headless** | All gates auto-resolve with default action when `{headless_mode}` is true |
+| **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) |
+| **Exit codes** | See "Exit Codes" below |
 
-## On Activation
+## Exit Codes
 
-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`
+Every HARD HALT in this workflow exits with a stable code so headless automators can branch on the failure class without grepping message text:
 
-2. **Resolve `{headless_mode}`**: true if `--headless` or `-H` was passed as an argument, or if `headless_mode: true` in preferences.yaml. Default: false.
+| Code | Meaning              | Raised by                                                                                  |
+| ---- | -------------------- | ------------------------------------------------------------------------------------------ |
+| 0    | success              | step-06 (terminal)                                                                         |
+| 2    | input-missing / input-invalid | step-01 GATE — required headless arg absent (`target_repo`, `skill_name`, or `doc_urls` when `source_type=docs-only`) → `input-missing`; enum violation, malformed semver, non-kebab `skill_name`, or step-05 brief-context schema validation failure → `input-invalid` |
+| 3    | resolution-failure   | step-01 §1 (`forge-tier.yaml` missing); step-02 §1 (target inaccessible / `gh auth` fails) |
+| 4    | write-failure        | step-01 §1 pre-flight write probe (data folder unwritable: read-only mount, disk full, permissions denied); step-05 §4 (write to `{forge_data_folder}/{skill-name}/skill-brief.yaml` failed) |
+| 5    | overwrite-cancelled  | step-05 §2 (existing brief, `force` not supplied)                                          |
+| 6    | user-cancelled       | any interactive menu in step-01/03/04 (user selected `[X]` Cancel and exit)                |
+
+## Result Contract (Headless)
+
+When `{headless_mode}` is true, step-05 emits a single-line JSON envelope on **stdout** before chaining to step-06, 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}
+```
 
-3. Load, read the full file, and then execute `./steps-c/step-01-gather-intent.md` to begin the workflow.
+`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.

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

@@ -0,0 +1,19 @@
+# Description Voice Examples
+
+Loaded by step-01 §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."
+
+## Examples
+
+> Render Markdown to HTML using the marked library. Use when the user pastes raw Markdown and wants formatted output, or asks how to convert MD files in a build pipeline.
+
+> Stripe API client for Node.js — payment intents, subscriptions, customer portal, webhooks. Triggers on tasks involving Stripe-managed payments, subscription billing, or webhook event handling.
+
+> Charts and visualizations powered by D3.js. Reach for this when the user asks to plot data, build interactive graphs, or wants bare D3 control instead of a React-charts abstraction.
+
+> Lint Python code with Ruff. Use when the user wants to add or configure Ruff in a Python project, debug rule selectors, or understand why a specific check fired.
+
+> Date and time arithmetic via Luxon — parsing, formatting, time zones, durations, intervals. Use when working with dates in ways that exceed `Date.toISOString()` but you don't want a full Moment.js footprint.
+
+## Notes on Voice
+
+Each example leads differently (verb / noun / "Charts and..." / verb / noun-phrase) and matches the trigger phrasing ("Use when...", "Triggers on...", "Reach for this when...") to the voice rather than copy-pasting a single template. Compose in that spirit using the gathered material — the target repo, the user's intent, the version if set, and any scope hints — but **do not template-stamp**.

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

@@ -7,26 +7,31 @@ Present these options to the user for selection:
 **[F] Full Library** — Include everything. Best for smaller, focused libraries.
 - All public exports, all modules
 - Exclude only tests, build artifacts, and internal utilities
+- *Looks like:* `marked` (single-purpose Markdown→HTML); `nanoid` (id generator); `zod` (validation library)
 
 **[M] Specific Modules** — Select which modules to include. Best for large libraries where only some parts are relevant.
 - You choose which modules/directories
 - Fine-grained control over what's in and out
+- *Looks like:* `lodash` skill scoped to just `lodash/array` and `lodash/string`; `aws-sdk` skill scoped to just S3 and DynamoDB
 
 **[P] Public API Only** — Include only the public-facing API surface. Best for libraries with a clear public/private boundary.
 - Entry points and exported interfaces only
 - Internal implementation excluded
+- *Looks like:* `stripe` (payment intents, subscriptions, webhooks — not internal HTTP plumbing); `redis` client (connection + commands, not protocol parsers)
 
 **[C] Component Library** — Optimized for UI component libraries with registries, props-based APIs, and design system variants.
 - Component registry as primary API surface (not individual exports)
 - Props interfaces as API contracts (not function signatures)
 - Auto-exclude demo/example/story files (with user confirmation)
 - Variant consolidation across design systems
+- *Looks like:* `shadcn-ui` (Button, Dialog, Form... 50+ components); Material-UI; Carbon Design System
 
 **[R] Reference App** — Whole-app pattern-reference skill. Use when the source is a working example app and the skill's value is **wiring patterns** (lifecycle, IPC, build-config, distribution) rather than a public library API.
 - Pattern surface as primary API slot (not individual exports)
 - Adoption Steps as primary workflow format (not API-call chains)
 - Tier 2 organized as `references/pattern-*.md` groupings (not per-function)
 - Export-count stats are pattern-surface proxies, not library exports
+- *Looks like:* a Tauri starter app (window setup + IPC bridge + build config); a Next.js auth example (route handlers + middleware + session storage wiring)
 
 ## Boundary Definitions by Scope Type