bmad-module-skill-forge 1.4.0 → 1.5.0

package/src/shared/scripts/skf-validate-brief-inputs.py

@@ -6,8 +6,8 @@
 
 Validates and normalizes the headless argument set passed to skf-brief-skill
 before the workflow's interactive sequence runs. Catches malformed inputs at
-point of capture instead of letting them surface 5+ minutes later in step-02
-or step-05.
+point of capture instead of letting them surface 5+ minutes later in step 2
+or step 5.
 
 CLI:
   uv run skf-validate-brief-inputs.py --json '{...}'
@@ -77,7 +77,7 @@ KNOWN_FIELDS = {
     "exclude",
     "force",
 }
-# `preset` is intentionally NOT in KNOWN_FIELDS — it is consumed at the step-01 §8 GATE
+# `preset` is intentionally NOT in KNOWN_FIELDS — it is consumed at the step 1 §8 GATE
 # (the LLM merges the named preset YAML into the args dict and drops the `preset` key
 # before calling the validator). If the key leaks through, the validator's existing
 # unknown-field handling emits `"unrecognized field 'preset' — passed through unchanged"`
@@ -218,9 +218,9 @@ def validate(inp: dict[str, Any]) -> dict[str, Any]:
     normalized: dict[str, Any] = dict(inp)
     normalized.setdefault("source_type", "source")
     # `source_authority` is intentionally NOT setdefault'd here for source-type targets:
-    # step-01 §3.3's headless detection branch runs `gh api user` and may resolve to
+    # step 1 §3.3's headless detection branch runs `gh api user` and may resolve to
     # `official` for repos owned by the authenticated user. Stamping a default at
-    # validator time would pre-empt the detection because step-01 §8 GATE treats the
+    # validator time would pre-empt the detection because step 1 §8 GATE treats the
     # `normalized` object as the source of truth. Absence is the signal "run detection."
     # The docs-only branch below still forces `community` since detection cannot apply.
     normalized.setdefault("scripts_intent", "detect")

package/src/shared/scripts/skf-validate-brief-schema.py

@@ -0,0 +1,348 @@
+# /// script
+# requires-python = ">=3.10"
+# dependencies = ["pyyaml", "jsonschema>=4.0"]
+# ///
+"""SKF Validate Brief Schema — schema check for a skill-brief.yaml on disk.
+
+Loads `skill-brief.yaml` from a path (or from stdin/inline-YAML), validates
+it against `src/shared/scripts/schemas/skill-brief.v1.json`, and applies the
+two conditional rules from `skf-create-skill/references/load-brief.md §3`
+that the JSON schema doesn't express today:
+
+  - When `source_type == "docs-only"`: `doc_urls` must have ≥1 entry, and
+    `source_authority` must be `community` (the prose says it is "forced
+    to community" — we surface a warning when it disagrees rather than
+    silently rewriting).
+  - `version` must be present AND non-empty AND not whitespace-only. The
+    schema rejects empty strings via its semver pattern, but a string that
+    only contains whitespace would slip past a naive presence check; we
+    catch that case explicitly so the downstream directory-resolution code
+    doesn't produce `{name}//` paths.
+
+The script produces skill-friendly error messages — translating raw
+jsonschema diagnostics into the "Brief validation failed: ..." form the
+calling stage prose already uses. Calling stages can read `errors[]`
+directly and forward the `message` field to the user.
+
+CLI:
+  uv run skf-validate-brief-schema.py <path/to/skill-brief.yaml>
+  cat brief.yaml | uv run skf-validate-brief-schema.py -
+  uv run skf-validate-brief-schema.py --yaml '<inline yaml>'
+
+Output (JSON on stdout):
+  {
+    "valid": bool,
+    "errors":   [{"field": "...", "message": "..."}, ...],
+    "warnings": [{"field": "...", "message": "..."}, ...],
+    "halt_reason": "brief-missing" | "brief-malformed" | "brief-invalid" | null,
+    "brief": { ...parsed YAML if loadable, else null... }
+  }
+
+Exit codes:
+  0 — valid (errors empty)
+  1 — invalid (errors non-empty) OR file/yaml load failed
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from pathlib import Path
+from typing import Any
+
+import yaml
+from jsonschema import Draft202012Validator
+
+
+REPO_ROOT = Path(__file__).resolve().parent.parent.parent.parent
+SCHEMA_PATH = (
+    REPO_ROOT / "src" / "shared" / "scripts" / "schemas" / "skill-brief.v1.json"
+)
+
+
+# --------------------------------------------------------------------------
+# Loading
+# --------------------------------------------------------------------------
+
+
+def load_schema() -> dict:
+    """Read the skill-brief schema from its canonical path."""
+    return json.loads(SCHEMA_PATH.read_text(encoding="utf-8"))
+
+
+def load_brief_text(text: str) -> tuple[dict | None, str | None]:
+    """Parse YAML text. Returns (brief, error_message)."""
+    try:
+        brief = yaml.safe_load(text)
+    except yaml.YAMLError as exc:
+        return None, f"Brief is not valid YAML: {exc}"
+    if brief is None:
+        return None, "Brief is empty"
+    if not isinstance(brief, dict):
+        return None, f"Brief must be a YAML mapping; got {type(brief).__name__}"
+    return brief, None
+
+
+# --------------------------------------------------------------------------
+# Error translation
+# --------------------------------------------------------------------------
+
+
+def _field_path(error_path: tuple) -> str:
+    """Render a jsonschema error path as `a.b[0].c`."""
+    parts: list[str] = []
+    for p in error_path:
+        if isinstance(p, int):
+            parts.append(f"[{p}]")
+        else:
+            parts.append(f".{p}" if parts else str(p))
+    return "".join(parts) or "(root)"
+
+
+def _translate_jsonschema_error(err) -> dict:
+    """Produce a skill-friendly error record from a jsonschema ValidationError."""
+    field = _field_path(err.absolute_path)
+    validator = err.validator
+    inst = err.instance
+
+    if validator == "required":
+        missing = err.message.split("'")[1] if "'" in err.message else "(unknown)"
+        return {
+            "field": missing,
+            "message": (
+                f"Brief validation failed: missing required field `{missing}`. "
+                f"Update your skill-brief.yaml and re-run."
+            ),
+        }
+    if validator == "pattern":
+        return {
+            "field": field,
+            "message": (
+                f"Brief validation failed: `{field}` field `{inst}` does not "
+                f"match required pattern `{err.validator_value}`. "
+                f"Update your skill-brief.yaml and re-run."
+            ),
+        }
+    if validator == "enum":
+        return {
+            "field": field,
+            "message": (
+                f"Brief validation failed: `{field}` field `{inst}` is not one of "
+                f"{err.validator_value}. Update your skill-brief.yaml and re-run."
+            ),
+        }
+    if validator == "type":
+        expected = err.validator_value
+        actual = type(inst).__name__
+        return {
+            "field": field,
+            "message": (
+                f"Brief validation failed: `{field}` field has type `{actual}`, "
+                f"expected `{expected}`. Update your skill-brief.yaml and re-run."
+            ),
+        }
+    if validator == "minLength":
+        return {
+            "field": field,
+            "message": (
+                f"Brief validation failed: `{field}` field must be non-empty. "
+                f"Update your skill-brief.yaml and re-run."
+            ),
+        }
+    if validator == "minItems":
+        return {
+            "field": field,
+            "message": (
+                f"Brief validation failed: `{field}` field must contain at least "
+                f"{err.validator_value} item(s). Update your skill-brief.yaml and re-run."
+            ),
+        }
+    # Fallback — preserve raw message but with consistent prefix
+    return {
+        "field": field,
+        "message": f"Brief validation failed: `{field}` — {err.message}",
+    }
+
+
+# --------------------------------------------------------------------------
+# Conditional rules from §3 prose
+# --------------------------------------------------------------------------
+
+
+def _docs_only_rules(brief: dict) -> tuple[list[dict], list[dict]]:
+    """Apply the docs-only conditional rules.
+
+    Returns (errors, warnings).
+    """
+    errors: list[dict] = []
+    warnings: list[dict] = []
+    if brief.get("source_type") != "docs-only":
+        return errors, warnings
+
+    doc_urls = brief.get("doc_urls")
+    if not isinstance(doc_urls, list) or len(doc_urls) == 0:
+        errors.append(
+            {
+                "field": "doc_urls",
+                "message": (
+                    "Brief validation failed: `doc_urls` must have at least one "
+                    "entry when `source_type` is `docs-only`. "
+                    "Update your skill-brief.yaml and re-run."
+                ),
+            }
+        )
+
+    source_authority = brief.get("source_authority")
+    if source_authority not in (None, "community"):
+        warnings.append(
+            {
+                "field": "source_authority",
+                "message": (
+                    f"`source_authority` is `{source_authority}` but will be treated "
+                    f"as `community` because `source_type` is `docs-only`."
+                ),
+            }
+        )
+    return errors, warnings
+
+
+def _version_non_empty_rule(brief: dict) -> list[dict]:
+    """The §3 prose calls out version-whitespace-only as a hard error."""
+    version = brief.get("version")
+    if isinstance(version, str) and version.strip() == "" and version != "":
+        # purely whitespace — schema's minLength check on patterns won't catch
+        # leading/trailing whitespace that strips to empty
+        return [
+            {
+                "field": "version",
+                "message": (
+                    "Brief validation failed: `version` field is required and "
+                    "must be non-empty. Update your skill-brief.yaml and re-run."
+                ),
+            }
+        ]
+    return []
+
+
+# --------------------------------------------------------------------------
+# Main validate
+# --------------------------------------------------------------------------
+
+
+def validate_brief(brief: dict) -> dict:
+    """Validate a parsed brief against the schema + conditional rules."""
+    schema = load_schema()
+    validator = Draft202012Validator(schema)
+
+    errors: list[dict] = []
+    warnings: list[dict] = []
+
+    for err in sorted(validator.iter_errors(brief), key=lambda e: e.absolute_path):
+        errors.append(_translate_jsonschema_error(err))
+
+    cond_errors, cond_warnings = _docs_only_rules(brief)
+    errors.extend(cond_errors)
+    warnings.extend(cond_warnings)
+
+    errors.extend(_version_non_empty_rule(brief))
+
+    return {
+        "valid": not errors,
+        "errors": errors,
+        "warnings": warnings,
+    }
+
+
+# --------------------------------------------------------------------------
+# CLI
+# --------------------------------------------------------------------------
+
+
+def _emit(envelope: dict) -> None:
+    json.dump(envelope, sys.stdout, indent=2)
+    sys.stdout.write("\n")
+
+
+def _envelope_load_error(reason: str, message: str) -> dict:
+    return {
+        "valid": False,
+        "errors": [{"field": "(file)", "message": message}],
+        "warnings": [],
+        "halt_reason": reason,
+        "brief": None,
+    }
+
+
+def _envelope_invalid(brief: dict, errors: list[dict], warnings: list[dict]) -> dict:
+    return {
+        "valid": False,
+        "errors": errors,
+        "warnings": warnings,
+        "halt_reason": "brief-invalid",
+        "brief": brief,
+    }
+
+
+def _envelope_valid(brief: dict, warnings: list[dict]) -> dict:
+    return {
+        "valid": True,
+        "errors": [],
+        "warnings": warnings,
+        "halt_reason": None,
+        "brief": brief,
+    }
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(
+        prog="skf-validate-brief-schema",
+        description="Validate a skill-brief.yaml against the SKF brief schema.",
+    )
+    src = parser.add_mutually_exclusive_group(required=True)
+    src.add_argument(
+        "path",
+        nargs="?",
+        help="path to skill-brief.yaml; pass `-` to read from stdin",
+    )
+    src.add_argument(
+        "--yaml",
+        dest="inline_yaml",
+        help="inline YAML text to validate (alternative to a path)",
+    )
+    args = parser.parse_args(argv)
+
+    if args.inline_yaml is not None:
+        text = args.inline_yaml
+    elif args.path == "-":
+        text = sys.stdin.read()
+    else:
+        brief_path = Path(args.path)
+        if not brief_path.is_file():
+            _emit(
+                _envelope_load_error(
+                    "brief-missing",
+                    f"Brief not found at `{brief_path}`. Run [BS] Brief Skill to "
+                    "create one, or use [QS] Quick Skill for brief-less generation.",
+                )
+            )
+            return 1
+        text = brief_path.read_text(encoding="utf-8")
+
+    brief, load_err = load_brief_text(text)
+    if load_err is not None:
+        _emit(_envelope_load_error("brief-malformed", load_err))
+        return 1
+    assert brief is not None
+
+    result = validate_brief(brief)
+    if not result["valid"]:
+        _emit(_envelope_invalid(brief, result["errors"], result["warnings"]))
+        return 1
+
+    _emit(_envelope_valid(brief, result["warnings"]))
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

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

@@ -6,7 +6,7 @@
 
 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.
+inlined in `src/skf-brief-skill/references/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
@@ -56,7 +56,7 @@ Context payload shape (consumed by `write`):
 
 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.
+     precedence rule). Used by step 5 when it has confirmed values.
   2. Otherwise: target_version if non-null.
   3. Otherwise: detected_version if non-null.
   4. Otherwise: "1.0.0".
@@ -263,6 +263,36 @@ def validate_context(ctx: dict[str, Any]) -> list[str]:
     if not isinstance(scope["notes"], str):
         _die("scope.notes must be a string (use empty string when no notes)", field="scope.notes")
 
+    # scope.rationale — optional authoring-time scope-type decision record.
+    # Absent/None → field is simply not present (same null-drop path as
+    # doc_urls). When present it must be a complete six-subkey object.
+    rationale = scope.get("rationale")
+    if rationale is not None:
+        if not isinstance(rationale, dict):
+            _die("scope.rationale must be an object when present", field="scope.rationale")
+        _RATIONALE_STR_KEYS = ("recommended", "chosen", "heuristic", "reason", "recorded")
+        for rk in (*_RATIONALE_STR_KEYS, "accepted_recommendation"):
+            if rk not in rationale:
+                _die(f"scope.rationale.{rk} is required", field=f"scope.rationale.{rk}")
+        for rk in _RATIONALE_STR_KEYS:
+            if not isinstance(rationale[rk], str) or not rationale[rk]:
+                _die(
+                    f"scope.rationale.{rk} must be a non-empty string",
+                    field=f"scope.rationale.{rk}",
+                )
+        if not isinstance(rationale["accepted_recommendation"], bool):
+            _die(
+                "scope.rationale.accepted_recommendation must be a boolean",
+                field="scope.rationale.accepted_recommendation",
+            )
+        for rk in ("recommended", "chosen"):
+            if rationale[rk] not in VALID_SCOPE_TYPES:
+                _die(
+                    f"scope.rationale.{rk} must be one of {sorted(VALID_SCOPE_TYPES)}. "
+                    f"Got: {rationale[rk]!r}",
+                    field=f"scope.rationale.{rk}",
+                )
+
     # target_version semver shape (when present)
     tv = ctx.get("target_version")
     if tv is not None:
@@ -308,6 +338,21 @@ def assemble_brief(ctx: dict[str, Any], resolved_version: str) -> dict[str, Any]
         },
     }
 
+    # Conditional: scope.rationale — canonical position is after `notes` and
+    # before `amendments` (amendments is appended post-authoring by other
+    # workflows and is never emitted here, so appending after notes yields the
+    # canonical order). Absent → key omitted, matching the legacy-brief default.
+    scope_rationale = ctx["scope"].get("rationale")
+    if scope_rationale is not None:
+        brief["scope"]["rationale"] = {
+            "recommended": scope_rationale["recommended"],
+            "chosen": scope_rationale["chosen"],
+            "accepted_recommendation": scope_rationale["accepted_recommendation"],
+            "heuristic": scope_rationale["heuristic"],
+            "reason": scope_rationale["reason"],
+            "recorded": scope_rationale["recorded"],
+        }
+
     # Conditional: target_version (must equal version)
     tv = ctx.get("target_version")
     if tv is not None:
@@ -346,7 +391,7 @@ def assemble_brief(ctx: dict[str, Any], resolved_version: str) -> dict[str, Any]
 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
+    The step 5 §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
@@ -388,7 +433,13 @@ def atomic_write(target: Path, content: str) -> int:
 # 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")
+_FLAT_SCOPE_KEYS = (
+    "scope_type",
+    "scope_include",
+    "scope_exclude",
+    "scope_notes",
+    "scope_rationale",
+)
 
 
 def flat_to_nested(flat: dict[str, Any]) -> dict[str, Any]:
@@ -437,6 +488,11 @@ def flat_to_nested(flat: dict[str, Any]) -> dict[str, Any]:
             scope["exclude"] = flat["scope_exclude"]
         if "scope_notes" in flat and flat["scope_notes"] is not None:
             scope["notes"] = flat["scope_notes"]
+        # Optional authoring-time rationale. Null/absent → key dropped (same
+        # null-drop semantics as doc_urls); when present it carries the full
+        # six-subkey object validated by validate_context.
+        if "scope_rationale" in flat and flat["scope_rationale"] is not None:
+            scope["rationale"] = flat["scope_rationale"]
         nested["scope"] = scope
     return nested
 
@@ -495,7 +551,7 @@ def main() -> int:
             "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."
+            "assembly site in step 5."
         ),
     )
 

package/src/skf-analyze-source/SKILL.md

@@ -9,6 +9,14 @@ description: Discover what to skill in a large repo and produce recommended skil
 
 Analyzes a large repo or multi-service project to identify discrete skillable units, map exports and integration points, and produce recommended skill-brief.yaml files as the primary entry point for brownfield onboarding. The analysis must be thorough enough to produce actionable briefs, but scoped enough to avoid overwhelming the user with false positives. Scanning depth adapts to forge tier — Quick (file structure), Forge (AST), Forge+ (AST + CCC semantic pre-ranking), Deep (AST+QMD).
 
+## Conventions
+
+- Bare paths (e.g. `references/<name>.md`) resolve from the skill root.
+- `references/` holds prompt content carved out of SKILL.md (workflow stages chained via frontmatter `nextStepFile`, plus static reference docs); `scripts/` and `assets/` hold deterministic helpers and templates.
+- `{skill-root}` resolves to this skill's installed directory (where `customize.toml` lives, if present).
+- `{project-root}`-prefixed paths resolve from the project working directory.
+- `{skill-name}` resolves to the skill directory's basename.
+
 ## Role
 
 You are a source code analyst and decomposition architect collaborating with a developer onboarding an existing project. You bring expertise in codebase analysis, service boundary detection, and skill scoping, while the user brings their domain knowledge. Work together as equals.
@@ -17,35 +25,56 @@ You are a source code analyst and decomposition architect collaborating with a d
 
 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
-- Update `stepsCompleted` in output file frontmatter before loading next step
-- If any instruction references a subprocess or tool you lack, achieve the outcome in your main context thread
-- Always communicate in `{communication_language}`
+- Always communicate in `{communication_language}` (the language for user-facing prose). Written artifact text — the per-unit recommendation `description` and `scope.notes` persisted into `skill-brief.yaml` — is in `{document_output_language}`; per-step rules call this out where it applies. 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
 
 ## Stages
 
 | # | Step | File | Auto-proceed |
 |---|------|------|--------------|
-| 1 | Initialize | steps-c/step-01-init.md | Yes |
-| 1b | Continue (session resume) | steps-c/step-01b-continue.md | Yes |
-| 2 | Scan Project | steps-c/step-02-scan-project.md | No (confirm) |
-| 3 | Identify Units | steps-c/step-03-identify-units.md | No (confirm) |
-| 4 | Map & Detect | steps-c/step-04-map-and-detect.md | Yes |
-| 5 | Recommend | steps-c/step-05-recommend.md | No (confirm) |
-| 6 | Generate Briefs | steps-c/step-06-generate-briefs.md | Yes |
-| 7 | Workflow Health Check | steps-c/step-07-health-check.md | Yes |
+| 1 | Initialize | references/init.md | Yes |
+| 1b | Continue (session resume) | references/continue.md | Yes |
+| 2 | Scan Project | references/scan-project.md | No (confirm) |
+| 3 | Identify Units | references/identify-units.md | No (confirm) |
+| 4 | Map & Detect | references/map-and-detect.md | Yes |
+| 5 | Recommend | references/recommend.md | No (confirm) |
+| 6 | Generate Briefs | references/generate-briefs.md | Yes |
+| 7 | Workflow Health Check | references/health-check.md | Yes |
 
 ## Invocation Contract
 
 | Aspect | Detail |
 |--------|--------|
 | **Inputs** | project_path [required], scope_hint [optional] |
-| **Gates** | step-02: Confirm Gate [C] | step-03: Confirm Gate [C] | step-05: Confirm Gate [C] |
-| **Outputs** | analysis-report.md, skill-brief.yaml files (one per recommended unit) |
+| **Headless inputs** | `--project-path <path>` (skip Step 1 project-path prompt), `--scope-hint <text>` (skip Step 1 scope-hint prompt), `--intent-hint <text>` (pre-supply analysis intent; drives recommendation ranking in Step 5) |
+| **Headless flag** | `--headless` / `-H` flips every confirm gate to auto-proceed |
+| **Gates** | step 2: Confirm Gate [C] | step 3: Confirm Gate [C] | step 5: Confirm Gate [C] |
+| **Outputs** | analysis-report.md, skill-brief.yaml files (one per recommended unit); final `SKF_ANALYZE_RESULT_JSON` line on stdout when `{headless_mode}` is true |
 | **Headless** | All gates auto-resolve with default action when `{headless_mode}` is true |
+| **Exit codes** | See "Exit Codes" below |
+
+## Exit Codes
+
+Every HARD HALT in this workflow exits with a stable code so headless automators can branch on the failure class without grepping message text:
+
+| Code | Meaning              | Raised by                                                                                  |
+| ---- | -------------------- | ------------------------------------------------------------------------------------------ |
+| 0    | success              | step 7 (terminal — health check completion)                                               |
+| 2    | input-missing        | step 1 §2-3 — required config absent (config.yaml not loadable, project path empty/invalid in headless mode) |
+| 3    | resolution-failure   | step 1 §2 (`forge-tier.yaml` missing at `{sidecar_path}/forge-tier.yaml`); step 1 §3 (project path does not exist or remote URL inaccessible) |
+| 4    | write-failure        | step 1 §6 (analysis report write failed); step 6 §5 (skill-brief.yaml write failed); step 6 §9 (result contract write failed) |
+| 6    | user-cancelled       | any interactive menu in steps 2/3/5/6 (user selected `[X]` Cancel and exit)               |
+
+## Result Contract (Headless)
+
+When `{headless_mode}` is true, step 6 emits a single-line JSON envelope on **stdout** before chaining to step 7, and every HARD HALT emits the same envelope shape on **stderr** with `status: "error"`:
+
+```
+SKF_ANALYZE_RESULT_JSON: {"status":"success|error","report_path":"…|null","brief_paths":["…"],"unit_counts":{"confirmed":N,"skipped":N,"maybe":N},"exit_code":0,"halt_reason":null}
+```
+
+`status` is `"success"` on the terminal happy path, `"error"` on any HALT. `halt_reason` is one of: `null` (success), `"input-missing"`, `"forge-tier-missing"`, `"path-invalid"`, `"write-failed"`, `"user-cancelled"`. `exit_code` matches the table above. `brief_paths` is an array of absolute paths to every generated `skill-brief.yaml` (empty array if none were generated). `unit_counts` reports confirmed/skipped/maybe counts from step 5's user decisions.
 
 ## On Activation
 
@@ -54,4 +83,28 @@ These rules apply to every step in this workflow:
 
 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 then execute `./steps-c/step-01-init.md` to begin the workflow.
+3. **Resolve workflow customization.** Run:
+
+   ```bash
+   python3 {project-root}/_bmad/scripts/resolve_customization.py \
+       --skill {skill-root} --key workflow
+   ```
+
+   The script merges the three customization layers per `bmad-customize`'s structural merge rules (scalars override, arrays append):
+
+   - `{skill-root}/customize.toml` — bundled defaults
+   - `_bmad/custom/<skill-name>.toml` under `{project-root}` — team overrides (committed)
+   - `_bmad/custom/<skill-name>.user.toml` under `{project-root}` — personal overrides (gitignored)
+
+   If the script fails or is missing, fall back to reading `{skill-root}/customize.toml` directly — the bundled defaults are an empty string for each path scalar.
+
+   Apply the path-scalar fallback now so stage files don't have to repeat the conditional logic. For each scalar, if the merged value is empty or absent, use the bundled default:
+
+   - `{unitDetectionHeuristicsPath}` ← `workflow.unit_detection_heuristics_path` if non-empty, else `references/unit-detection-heuristics.md`
+   - `{briefSchemaPath}` ← `workflow.brief_schema_path` if non-empty, else `assets/skill-brief-schema.md`
+   - `{analysisReportTemplatePath}` ← `workflow.analysis_report_template_path` if non-empty, else `templates/analysis-report-template.md`
+   - `{onCompleteCommand}` ← `workflow.on_complete` if non-empty, else empty string (no-op — workflow skips the hook invocation)
+
+   Stash all four as workflow-context variables. Stage files reference `{unitDetectionHeuristicsPath}` / `{briefSchemaPath}` / `{analysisReportTemplatePath}` / `{onCompleteCommand}` directly — no conditional at the usage site. Empty-string overrides cleanly fall through to the bundled default; non-empty values let orgs swap in house-style copies (or wire in pipeline hooks) without forking the skill.
+
+4. Load, read the full file, and then execute `references/init.md` to begin the workflow.

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

@@ -49,7 +49,7 @@ If the source is a remote GitHub repo, use `gh api repos/{owner}/{repo}/contents
 
 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.
+The create-skill workflow (extract) also performs version reconciliation at extraction time — if the source version has changed since the brief was created, the extraction step warns and uses the source version.
 
 **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.