bmad-method 6.10.1-next.38 → 6.10.1-next.39

package/package.json

@@ -1,7 +1,7 @@
 {
   "$schema": "https://json.schemastore.org/package.json",
   "name": "bmad-method",
-  "version": "6.10.1-next.38",
+  "version": "6.10.1-next.39",
   "description": "Breakthrough Method of Agile AI-driven Development",
   "keywords": [
     "agile",
@@ -40,14 +40,13 @@
     "lint:fix": "eslint . --ext .js,.cjs,.mjs,.yaml --fix",
     "lint:md": "markdownlint-cli2 \"**/*.md\"",
     "prepare": "command -v husky >/dev/null 2>&1 && husky || exit 0",
-    "quality": "npm run format:check && npm run lint && npm run lint:md && npm run docs:build && npm run test:site-url && npm run test:install && npm run test:urls && npm run test:renderer && npm run test:retrospective && npm run test:build-auto-contract && npm run validate:refs && npm run validate:skills && npm run docs:validate-sidebar",
+    "quality": "npm run format:check && npm run lint && npm run lint:md && npm run docs:build && npm run test:site-url && npm run test:install && npm run test:urls && npm run test:renderer && npm run test:retrospective && npm run validate:refs && npm run validate:skills && npm run docs:validate-sidebar",
     "rebundle": "node tools/installer/bundlers/bundle-web.js rebundle",
-    "test": "npm run test:refs && npm run test:install && npm run test:urls && npm run test:site-url && npm run test:channels && npm run test:renderer && npm run test:retrospective && npm run test:build-auto-contract && npm run test:skills && npm run lint && npm run lint:md && npm run format:check",
-    "test:build-auto-contract": "node test/test-build-auto-contract.js",
+    "test": "npm run test:refs && npm run test:install && npm run test:urls && npm run test:site-url && npm run test:channels && npm run test:renderer && npm run test:retrospective && npm run test:skills && npm run lint && npm run lint:md && npm run format:check",
     "test:channels": "node test/test-installer-channels.js",
     "test:install": "node test/test-installation-components.js",
     "test:refs": "node test/test-file-refs-csv.js",
-    "test:renderer": "uv run --python 3.11 python -m unittest src/scripts/tests/test_config_utils.py src/scripts/tests/test_resolve_config.py src/scripts/tests/test_resolve_customization.py && node test/test-build-renderer.js && node test/test-build-auto-renderer.js",
+    "test:renderer": "uv run --python 3.11 python -m unittest src/scripts/tests/test_config_utils.py src/scripts/tests/test_resolve_config.py src/scripts/tests/test_resolve_customization.py && node test/test-build-auto-renderer.js",
     "test:retrospective": "uv run --python 3.11 src/bmm-skills/ship/bmad-retrospective/scripts/tests/test_git_evidence.py && uv run --python 3.11 src/bmm-skills/ship/bmad-retrospective/scripts/tests/test_sprint_status.py",
     "test:site-url": "node test/test-site-url.mjs",
     "test:skills": "node test/test-validate-skills.js",

package/src/bmm-skills/ship/bmad-build/SKILL.md

@@ -3,11 +3,11 @@ name: bmad-build
 description: 'Implements any user intent, requirement, story, bug fix or change request by producing clean working code artifacts that follow the project''s existing architecture, patterns and conventions. Use when the user wants to build, fix, tweak, refactor, add or modify any code, component or feature.'
 ---
 
-Run this, substituting `{skill-root}` with the absolute path to this skill's base directory, without changing the cwd:
+Run the following command exactly once without changing the current working directory. Replace `{project-root}` with the absolute path to the project root and `{skill-root}` with the absolute path to this skill's directory:
 
 ```bash
-uv run --no-cache {skill-root}/render.py
+uv run --no-cache "{project-root}/_bmad/scripts/render_skill.py" --project-root "{project-root}" --skill "{skill-root}"
 ```
 
-- **On success:** follow the instruction it prints to stdout; ignore stderr.
-- **On any failure** (including `uv` not being installed): report what it printed and HALT.
+- On success, read and follow the one absolute `workflow.md` instruction printed to stdout.
+- On failure (including `uv` being unavailable), report the command output and HALT. Do not run any workflow source directly.

package/src/bmm-skills/ship/bmad-build/step-01-clarify-and-route.md

@@ -20,7 +20,7 @@ Before listing artifacts or prompting the user, check whether you already know t
 
 1. Explicit argument
    Did the user pass a specific file path, spec name, or clear instruction this message?
-   - If it points to a file that matches the spec template (has `status` frontmatter with a recognized value: draft, ready-for-dev, in-progress, in-review, or done) → set `spec_file`. Before exiting, run **Story-key resolution** (below). Then **EARLY EXIT** to the appropriate step (step-02 for draft, step-03 for ready/in-progress, step-04 for review). For `done`, ingest as context and proceed to INSTRUCTIONS — do not resume.
+   - If it points to a file that matches the spec template (has `status` frontmatter with a recognized value: draft, ready-for-dev, in-progress, in-review, or done) → set `spec_file`. Before exiting, run **Story-key resolution** (below). Then **EARLY EXIT** to the appropriate step: `draft` → `[[bmad-snapshot:step-02-plan.md]]`, `ready-for-dev`/`in-progress` → `[[bmad-snapshot:step-03-implement.md]]`, `in-review` → `[[bmad-snapshot:step-04-review.md]]`. For `done`, ingest as context and proceed to INSTRUCTIONS — do not resume.
    - Anything else (intent files, external docs, plans, descriptions) → ingest it as starting intent and proceed to INSTRUCTIONS. Do not attempt to infer a workflow state from it.
 
 2. Recent conversation
@@ -29,9 +29,9 @@ Before listing artifacts or prompting the user, check whether you already know t
 
 3. Otherwise — scan artifacts and ask
    - Active specs (`draft`, `ready-for-dev`, `in-progress`, `in-review`) in `{{.implementation_artifacts}}`? → List them and HALT. Ask user which to resume (or `[N]` for new).
-     - If `draft` selected: Set `spec_file`. Run **Story-key resolution** (below). **EARLY EXIT** → `./step-02-plan.md` (resume planning from the draft)
-     - If `ready-for-dev` or `in-progress` selected: Set `spec_file`. Run **Story-key resolution** (below). **EARLY EXIT** → `./step-03-implement.md`
-     - If `in-review` selected: Set `spec_file`. Run **Story-key resolution** (below). **EARLY EXIT** → `./step-04-review.md`
+     - If `draft` selected: Set `spec_file`. Run **Story-key resolution** (below). **EARLY EXIT** → `[[bmad-snapshot:step-02-plan.md]]` (resume planning from the draft)
+     - If `ready-for-dev` or `in-progress` selected: Set `spec_file`. Run **Story-key resolution** (below). **EARLY EXIT** → `[[bmad-snapshot:step-03-implement.md]]`
+     - If `in-review` selected: Set `spec_file`. Run **Story-key resolution** (below). **EARLY EXIT** → `[[bmad-snapshot:step-04-review.md]]`
    - Unformatted spec or intent file lacking `status` frontmatter? → Suggest treating its contents as the starting intent. Do NOT attempt to infer a state and resume it.
 
 Never ask extra questions if you already understand what the user intends.
@@ -40,7 +40,7 @@ Never ask extra questions if you already understand what the user intends.
 
 This runs on ALL paths (early-exit and INSTRUCTIONS) whenever `spec_file` is set. Determine whether the spec is an epic story — use the spec's filename, frontmatter, and any loaded epics file to identify `epic_num` and `story_num`. If the spec is not an epic story, skip silently and leave `story_key` unset.
 
-If the spec is an epic story and `{{.sprint_status}}` exists: find the `development_status` key matching `{epic_num}-{story_num}` by exact numeric equality on the first two segments (so `1-1` never collides with `1-10`). Exactly one match → set `story_key` to that full key. Zero or multiple matches → leave `story_key` unset (warn on multiple).
+If the spec is an epic story and `{{.implementation_artifacts}}/sprint-status.yaml` exists: find the `development_status` key matching `{epic_num}-{story_num}` by exact numeric equality on the first two segments (so `1-1` never collides with `1-10`). Exactly one match → set `story_key` to that full key. Zero or multiple matches → leave `story_key` unset (warn on multiple).
 
 ## INSTRUCTIONS
 
@@ -57,9 +57,9 @@ If the spec is an epic story and `{{.sprint_status}}` exists: find the `developm
         - **If valid:** load it as the primary planning context. Do not load raw planning docs (PRD, architecture, UX, etc.). Skip to step 5.
         - **If missing, empty, or invalid:** continue to step 3.
 
-     3. **Compile epic context.** Produce `{{.implementation_artifacts}}/epic-<N>-context.md` by following `./compile-epic-context.md`, in order of preference:
-        - **Preferred — subagent:** spawn a subagent synchronously (wait for it to return in this turn) with `./compile-epic-context.md` as its prompt. Pass it the epic number, the epics file path, the `{{.planning_artifacts}}` directory, and the output path `{{.implementation_artifacts}}/epic-<N>-context.md`.
-        - **Fallback — inline** (for runtimes without subagent support, e.g. Copilot, Codex, local Ollama, older Claude): if your runtime cannot spawn subagents, or the spawn fails/times out, read `./compile-epic-context.md` yourself and follow its instructions to produce the same output file.
+     3. **Compile epic context.** Produce `{{.implementation_artifacts}}/epic-<N>-context.md` by following `[[bmad-snapshot:compile-epic-context.md]]`, in order of preference:
+        - **Preferred — subagent:** spawn a subagent synchronously (wait for it to return in this turn) with `[[bmad-snapshot:compile-epic-context.md]]` as its prompt. Pass it the epic number, the epics file path, the `{{.planning_artifacts}}` directory, and the output path `{{.implementation_artifacts}}/epic-<N>-context.md`.
+        - **Fallback — inline** (for runtimes without subagent support, e.g. Copilot, Codex, local Ollama, older Claude): if your runtime cannot spawn subagents, or the spawn fails/times out, read `[[bmad-snapshot:compile-epic-context.md]]` yourself and follow its instructions to produce the same output file.
 
      4. **Verify.** After compilation, verify the output file exists, is non-empty, and starts with `# Epic <N> Context:`. If valid, load it. If verification fails, HALT and report the failure.
 
@@ -81,7 +81,7 @@ If the spec is an epic story and `{{.sprint_status}}` exists: find the `developm
    - Present detected distinct goals as a bullet list.
    - Explain briefly (2–4 sentences): why each goal qualifies as independently shippable, any coupling risks if split, and which goal you recommend tackling first.
    - HALT and ask human: `[S] Split — pick first goal, defer the rest` | `[K] Keep all goals — accept the risks`
-   - On **S**: For each deferred goal, append one new entry to `{{.deferred_work_file}}` using this format. Do not modify existing entries or look for duplicates. Narrow scope to the first-mentioned goal. Continue routing.
+   - On **S**: For each deferred goal, append one new entry to `{{.implementation_artifacts}}/deferred-work.md` using this format. Do not modify existing entries or look for duplicates. Narrow scope to the first-mentioned goal. Continue routing.
      ```markdown
      - source_spec: none
        summary: <one sentence naming the deferred goal>
@@ -90,14 +90,14 @@ If the spec is an epic story and `{{.sprint_status}}` exists: find the `developm
    - On **K**: Proceed as-is.
 5. Route — choose exactly one:
 
-   Derive a valid kebab-case slug from the clarified intent. If the intent references a tracking identifier (story number, issue number, ticket ID), lead the slug with it (e.g. `3-2-digest-delivery`, `gh-47-fix-auth`). If `{{.implementation_artifacts}}/spec-{slug}.md` already exists: if its status is `draft`, treat it as the same work and resume it (set `spec_file` to that path, **EARLY EXIT** → `./step-02-plan.md`); otherwise append `-2`, `-3`, etc. Set `spec_file` = `{{.implementation_artifacts}}/spec-{slug}.md`.
+   Derive a valid kebab-case slug from the clarified intent. If the intent references a tracking identifier (story number, issue number, ticket ID), lead the slug with it (e.g. `3-2-digest-delivery`, `gh-47-fix-auth`). If `{{.implementation_artifacts}}/spec-{slug}.md` already exists: if its status is `draft`, treat it as the same work and resume it (set `spec_file` to that path, **EARLY EXIT** → `[[bmad-snapshot:step-02-plan.md]]`); otherwise append `-2`, `-3`, etc. Set `spec_file` = `{{.implementation_artifacts}}/spec-{slug}.md`.
 
    **a) One-shot** — zero blast radius: no plausible path by which this change causes unintended consequences elsewhere. Clear intent, no architectural decisions.
 
-   **EARLY EXIT** → `./step-oneshot.md`
+   **EARLY EXIT** → `[[bmad-snapshot:step-oneshot.md]]`
 
    **b) Plan-code-review** — everything else. When uncertain whether blast radius is truly zero, choose this path.
 
 ## NEXT
 
-Read fully and follow `./step-02-plan.md`
+Read fully and follow `[[bmad-snapshot:step-02-plan.md]]`

package/src/bmm-skills/ship/bmad-build/step-02-plan.md

@@ -9,13 +9,13 @@
 
 1. Draft resume check. If `{spec_file}` exists with `status: draft`, read it and capture the verbatim `<frozen-after-approval>...</frozen-after-approval>` block as `preserved_intent`. Otherwise `preserved_intent` is empty.
 2. Investigate codebase. _Isolate deep exploration in synchronous subagents/tasks where available. To prevent context snowballing, instruct subagents to give you distilled summaries only._ Decide which findings actually matter for execution — the specific files, symbols/lines, reuse points, and read-only constraints — and carry those forward for the Code Map. This is where the investigation lands: the spec preserves it so it is never re-narrated to the implementer at dispatch time.
-3. Read `./spec-template.md` fully. Fill it out based on the intent and investigation, resolving the template's `date` field to the current system date. Drain the investigation into the `## Code Map` section — annotated paths, symbol/line anchors, reuse pointers, and read-only evidence — so the spec is the implementer's investigation map and the step-03 handoff need only point at it. If `preserved_intent` is non-empty, replace the `<frozen-after-approval>` block in the spec you just filled out with `preserved_intent`, before writing. Write the result to `{spec_file}`.
+3. Read `[[bmad-snapshot:spec-template.md]]` fully. Fill it out based on the intent and investigation, resolving the template's `date` field to the current system date. Drain the investigation into the `## Code Map` section — annotated paths, symbol/line anchors, reuse pointers, and read-only evidence — so the spec is the implementer's investigation map and the step-03 handoff need only point at it. If `preserved_intent` is non-empty, replace the `<frozen-after-approval>` block in the spec you just filled out with `preserved_intent`, before writing. Write the result to `{spec_file}`.
 4. Self-review against READY FOR DEVELOPMENT standard.
 5. If intent gaps exist, do not fantasize, do not leave open questions, HALT and ask the human.
 6. Token count check (see SCOPE STANDARD). If spec exceeds 1600 tokens:
    - Show user the token count.
    - HALT and ask human: `[S] Split — carve off secondary goals` | `[K] Keep full spec — accept the risks`
-   - On **S**: Propose the split — name each secondary goal. For each deferred goal, append one new entry to `{{.deferred_work_file}}` using this format. Do not modify existing entries or look for duplicates. Rewrite the current spec to cover only the main goal — do not surgically carve sections out; regenerate the spec for the narrowed scope. Continue to checkpoint.
+   - On **S**: Propose the split — name each secondary goal. For each deferred goal, append one new entry to `{{.implementation_artifacts}}/deferred-work.md` using this format. Do not modify existing entries or look for duplicates. Rewrite the current spec to cover only the main goal — do not surgically carve sections out; regenerate the spec for the narrowed scope. Continue to checkpoint.
      ```markdown
      - source_spec: `{spec_file}`
        summary: <one sentence naming the deferred goal>
@@ -44,4 +44,4 @@ HALT and ask human: `[A] Approve` | `[E] Edit`
 
 ## NEXT
 
-Read fully and follow `./step-03-implement.md`
+Read fully and follow `[[bmad-snapshot:step-03-implement.md]]`

package/src/bmm-skills/ship/bmad-build/step-03-implement.md

@@ -24,7 +24,7 @@ Capture `baseline_commit` (current HEAD, or `NO_VCS` if version control is unava
 
 Change `{spec_file}` status to `in-progress` in the frontmatter before starting implementation.
 
-Follow `./sync-sprint-status.md` with `target_status` = `in-progress`.
+Follow `[[bmad-snapshot:sync-sprint-status.md]]` with `target_status` = `in-progress`.
 
 Execute the implementation handoff below: substitute the runtime placeholders (e.g. `{spec_file}`) into it, then follow it verbatim.
 
@@ -46,4 +46,4 @@ If `{spec_file}`'s `<frozen-after-approval>` block contains an I/O & Edge-Case M
 
 ## NEXT
 
-Read fully and follow `./step-04-review.md`
+Read fully and follow `[[bmad-snapshot:step-04-review.md]]`

package/src/bmm-skills/ship/bmad-build/step-04-review.md

@@ -39,10 +39,10 @@ If a layer's instruction requires subagents and none are available, for each suc
    - **defer** — pre-existing issue not caused by this story, surfaced incidentally by the review. Collect for later focused attention.
    - **reject** — noise. Drop silently. When unsure between defer and reject, prefer reject — only defer findings you are confident are real.
 4. Process findings in cascading order. If intent_gap or bad_spec findings exist, they trigger a loopback — lower findings are moot since code will be re-derived. If neither exists, process patch and defer normally. Before each loopback, read `{spec_file}` frontmatter `review_loop_iteration` (missing means `0`), increment it by 1, and write it back. If it exceeds 5, HALT and escalate to the human.
-   - **intent_gap** — Root cause is inside `<frozen-after-approval>`. Revert code changes. Loop back to the human to resolve. Once resolved, read fully and follow `./step-02-plan.md` to re-run steps 2–4.
-   - **bad_spec** — Root cause is outside `<frozen-after-approval>`. Before reverting code: extract KEEP instructions for positive preservation (what worked well and must survive re-derivation). Revert code changes. Read the `## Spec Change Log` in `{spec_file}` and strictly respect all logged constraints when amending the non-frozen sections that contain the root cause. Append a new change-log entry recording: the triggering finding, what was amended, the known-bad state avoided, and the KEEP instructions. Read fully and follow `./step-03-implement.md` to re-derive the code, then this step will run again.
+   - **intent_gap** — Root cause is inside `<frozen-after-approval>`. Revert code changes. Loop back to the human to resolve. Once resolved, read fully and follow `[[bmad-snapshot:step-02-plan.md]]` to re-run steps 2–4.
+   - **bad_spec** — Root cause is outside `<frozen-after-approval>`. Before reverting code: extract KEEP instructions for positive preservation (what worked well and must survive re-derivation). Revert code changes. Read the `## Spec Change Log` in `{spec_file}` and strictly respect all logged constraints when amending the non-frozen sections that contain the root cause. Append a new change-log entry recording: the triggering finding, what was amended, the known-bad state avoided, and the KEEP instructions. Read fully and follow `[[bmad-snapshot:step-03-implement.md]]` to re-derive the code, then this step will run again.
    - **patch** — Auto-fix. These are the only findings that survive loopbacks. If the step-03 implementation subagent can be re-engaged with its context intact, send it all patch findings in one synchronous message — for each: the file, what is wrong, and what the fix must do. If it cannot be re-engaged, apply the patches yourself. Then re-run the checks in `{spec_file}`'s `## Verification` section, if present; if verification fails and the failure cannot be fixed, HALT and escalate to the human.
-   - **defer** — Append one new entry to `{{.deferred_work_file}}` using this format. Do not modify existing entries or look for duplicates.
+   - **defer** — Append one new entry to `{{.implementation_artifacts}}/deferred-work.md` using this format. Do not modify existing entries or look for duplicates.
      ```markdown
      - source_spec: `{spec_file}`
        summary: <one sentence>
@@ -52,4 +52,4 @@ If a layer's instruction requires subagents and none are available, for each suc
 
 ## NEXT
 
-Read fully and follow `./step-05-present.md`
+Read fully and follow `[[bmad-snapshot:step-05-present.md]]`

package/src/bmm-skills/ship/bmad-build/step-05-present.md

@@ -52,7 +52,7 @@ When there is only one concern, omit the bold label — just list the stops dire
 
 Change `{spec_file}` status to `done` in the frontmatter.
 
-Follow `./sync-sprint-status.md` with `target_status` = `review`.
+Follow `[[bmad-snapshot:sync-sprint-status.md]]` with `target_status` = `review`.
 
 ### Commit and Complete
 

package/src/bmm-skills/ship/bmad-build/step-oneshot.md

@@ -11,7 +11,7 @@
 
 ### Implement
 
-Follow `./sync-sprint-status.md` with `target_status` = `in-progress`.
+Follow `[[bmad-snapshot:sync-sprint-status.md]]` with `target_status` = `in-progress`.
 
 Implement the clarified intent directly.
 
@@ -28,7 +28,7 @@ If a layer's instruction requires subagents and none are available, for each suc
 Deduplicate all review findings. Three categories only:
 
 - **patch** — trivially fixable. Auto-fix immediately.
-- **defer** — pre-existing issue not caused by this change. Append one new entry to `{{.deferred_work_file}}` using this format. Do not modify existing entries or look for duplicates.
+- **defer** — pre-existing issue not caused by this change. Append one new entry to `{{.implementation_artifacts}}/deferred-work.md` using this format. Do not modify existing entries or look for duplicates.
   ```markdown
   - source_spec: `{spec_file}`
     summary: <one sentence>
@@ -42,13 +42,13 @@ If a finding is caused by this change but too significant for a trivial patch, H
 
 Set `title` = a concise title derived from the clarified intent.
 
-Write `{spec_file}` using `./spec-template.md`. Fill only these sections — delete all others:
+Write `{spec_file}` using `[[bmad-snapshot:spec-template.md]]`. Fill only these sections — delete all others:
 
 1. **Frontmatter** — set `title: '{title}'`, `type`, `created`, `status: 'done'`. Add `route: 'one-shot'`.
 2. **Title and Intent** — `# {title}` heading and `## Intent` with **Problem** and **Approach** lines. Reuse the summary you already generated for the terminal.
-3. **Suggested Review Order** — append after Intent. Build using the same convention as `./step-05-present.md` § "Generate Suggested Review Order" (spec-file-relative links, concern-based ordering, ultra-concise framing).
+3. **Suggested Review Order** — append after Intent. Build using the same convention as `[[bmad-snapshot:step-05-present.md]]` § "Generate Suggested Review Order" (spec-file-relative links, concern-based ordering, ultra-concise framing).
 
-Follow `./sync-sprint-status.md` with `target_status` = `review`.
+Follow `[[bmad-snapshot:sync-sprint-status.md]]` with `target_status` = `review`.
 
 ### Commit
 

package/src/bmm-skills/ship/bmad-build/sync-sprint-status.md

@@ -6,11 +6,11 @@ Shared sub-step for updating `sprint-status.yaml` during build. Called from any
 
 Skip this entire file (return to caller) if ANY of:
 - `story_key` is unset
-- `{{.sprint_status}}` does not exist on disk
+- `{{.implementation_artifacts}}/sprint-status.yaml` does not exist on disk
 
 ## Instructions
 
-1. Load the FULL `{{.sprint_status}}` file.
+1. Load the FULL `{{.implementation_artifacts}}/sprint-status.yaml` file.
 2. Find the `development_status` entry matching `{story_key}`. If not found, warn the user once (`"{story_key} not found in sprint-status; skipping sprint sync"`) and return to caller.
 3. **Idempotency check.** If `development_status[{story_key}]` is already at `target_status` or a later state (`review` is later than `in-progress`; `done` is later than both), return to caller — no write needed. Never regress a story's status.
 4. Set `development_status[{story_key}]` to `{target_status}`.

package/src/bmm-skills/ship/bmad-build/workflow.md

@@ -2,7 +2,7 @@
 
 **Goal:** Turn user intent into a hardened, reviewable artifact.
 
-**CRITICAL:** If a step says "read fully and follow step-XX", you read and follow step-XX. No exceptions.
+**CRITICAL:** If a step directs you to another snapshot file, read it fully and follow it. No exceptions.
 
 Subagents, when the capability is available, are an important part of this workflow. Use them as directed by the workflow steps.
 If you need an explicit user instruction to run them, ask once now for the whole workflow run.
@@ -30,10 +30,8 @@ A specification should target a **single user-facing goal** within **900–1600
 
 ## Conventions
 
-- Bare paths (e.g. `step-01-clarify-and-route.md`) resolve from the skill root.
-- `{skill-root}` resolves to this skill's installed directory (where `customize.toml` lives).
+- Every operational cross-file reference in this workflow is an absolute snapshot path. Open it directly; do not resolve it relative to a skill directory.
 - `{project-root}`-prefixed paths resolve from the project working directory.
-- `{skill-name}` resolves to the skill directory's basename.
 - Whenever this workflow captures or records a version-control revision, obtain the full canonical identifier directly from version control and preserve it verbatim.
 
 ## On Activation
@@ -83,4 +81,4 @@ This uses **step-file architecture** for disciplined execution:
 
 ## FIRST STEP
 
-Read fully and follow: `./step-01-clarify-and-route.md` to begin the workflow.
+Read fully and follow: `[[bmad-snapshot:step-01-clarify-and-route.md]]` to begin the workflow.

package/src/bmm-skills/ship/bmad-build-auto/SKILL.md

@@ -3,7 +3,7 @@ name: bmad-build-auto
 description: 'One iteration of an unattended development loop. Use when invoked by name.'
 ---
 
-Run this single command exactly once, substituting the absolute project and skill roots without changing the working directory:
+Run the following command exactly once without changing the current working directory. Replace `{project-root}` with the absolute path to the project root and `{skill-root}` with the absolute path to this skill's directory:
 
 ```bash
 uv run --no-cache "{project-root}/_bmad/scripts/render_skill.py" --project-root "{project-root}" --skill "{skill-root}"

package/src/scripts/render_skill.py

@@ -177,7 +177,8 @@ def _format_review_layers(layers: list[dict[str, str]]) -> str:
 
 def _resolve_customization_value(value: Any, default: Any, label: str) -> tuple[Any, str]:
     if isinstance(default, str):
-        resolved = _require_string(value, label, allow_empty=not default.strip())
+        allow_empty = not default.strip() or label == "customization.workflow.open_spec"
+        resolved = _require_string(value, label, allow_empty=allow_empty)
         return resolved, resolved
     if isinstance(default, list):
         if default and all(isinstance(item, dict) for item in default):

package/src/bmm-skills/ship/bmad-build/render.py

@@ -1,420 +0,0 @@
-#!/usr/bin/env python3
-# /// script
-# requires-python = ">=3.11"
-# ///
-"""render.py — bmad-build template renderer.
-
-Resolves compile-time {{.variable}} placeholders from BMad's central config,
-bakes absolute paths for {project-root} into derived values, resolves and
-inlines the skill's [workflow] customization block, and writes rendered .md
-files to {project-root}/_bmad/render/bmad-build/.
-
-Config: four-layer merge of _bmad/config.toml + config.user.toml +
-custom/config.toml + custom/config.user.toml (post-#2285 installs).
-Keys surface from [core] and [modules.bmm]. Missing or unparseable
-config.toml → HALT. A {{.var}} referenced by this skill's .md sources but
-absent from the merged config → HALT (never a silent empty substitution).
-Optional layers may be missing, but one that exists and cannot be parsed
-or read → HALT.
-
-Customization: three-layer merge of {skill}/customize.toml +
-_bmad/custom/bmad-build.toml + .user.toml (same structural rules as
-resolve_customization.py). The resolved [workflow] values fill {workflow.*}
-placeholders, so this skill needs no runtime resolve_customization.py call.
-Other single-curly placeholders ({project-root}, {spec_file}, ...) pass
-through untouched for the LLM to resolve during workflow execution. The sole
-exception is {skill-root} in resolved review-layer instructions, which must be
-an absolute prompt-file path before those instructions reach the parent LLM.
-
-Every invocation rebuilds from scratch — no hash, no cache.
-Python 3.11+ stdlib only. UTF-8 I/O.
-"""
-
-import os
-import posixpath
-import re
-import sys
-import tomllib
-
-
-def find_project_root():
-    """Walk up from cwd until a _bmad/ directory is found. On failure, print a
-    HALT instruction to stdout and exit non-zero."""
-    current = os.path.abspath(os.getcwd())
-    while True:
-        candidate = os.path.join(current, "_bmad")
-        if os.path.isdir(candidate):
-            return current
-        parent = os.path.dirname(current)
-        if parent == current:
-            print(
-                f"HALT and report to the user: no _bmad/ directory found walking up from {os.getcwd()}"
-            )
-            sys.exit(1)
-        current = parent
-
-
-def load_toml(path, required=False):
-    """Load a TOML file. Only absence is negotiable: a missing optional file
-    returns {} (customization layers are optional), a missing required file
-    HALTs. A file that exists but cannot be parsed or read always HALTs —
-    stdout is how this script signals workflow halts to its LLM caller — the
-    user wrote it to be honored, and silently continuing with {} would discard
-    their customizations with no failure signal."""
-    if not os.path.isfile(path):
-        if required:
-            print(
-                f"HALT and report to the user: required config file not found: {path} — "
-                "ensure this is a post-#2285 BMAD install"
-            )
-            sys.exit(1)
-        return {}
-    try:
-        with open(path, "rb") as fh:
-            parsed = tomllib.load(fh)
-    except tomllib.TOMLDecodeError as error:
-        print(f"HALT and report to the user: failed to parse {path}: {error}")
-        sys.exit(1)
-    except OSError as error:
-        print(f"HALT and report to the user: failed to read {path}: {error}")
-        sys.exit(1)
-    if not isinstance(parsed, dict):
-        return {}
-    return parsed
-
-
-def _deep_merge(base, override):
-    """Dict-aware deep merge. Lists and scalars: override wins (we don't need
-    the full keyed-merge semantics of resolve_config.py — build only reads
-    flat scalars out of [core] and [modules.bmm])."""
-    if isinstance(base, dict) and isinstance(override, dict):
-        result = dict(base)
-        for key, value in override.items():
-            result[key] = _deep_merge(result[key], value) if key in result else value
-        return result
-    return override
-
-
-def _detect_keyed_merge_field(items):
-    """Return 'code' or 'id' if every table item carries that same field.
-    Mixed or partial arrays return None and fall through to append."""
-    if not items or not all(isinstance(item, dict) for item in items):
-        return None
-    for candidate in ("code", "id"):
-        if all(item.get(candidate) is not None for item in items):
-            return candidate
-    return None
-
-
-def _merge_by_key(base, override, key_name):
-    result = []
-    index_by_key = {}
-    for item in base:
-        if not isinstance(item, dict):
-            continue
-        if item.get(key_name) is not None:
-            index_by_key[item[key_name]] = len(result)
-        result.append(dict(item))
-    for item in override:
-        if not isinstance(item, dict):
-            result.append(item)
-            continue
-        key = item.get(key_name)
-        if key is not None and key in index_by_key:
-            result[index_by_key[key]] = dict(item)
-        else:
-            if key is not None:
-                index_by_key[key] = len(result)
-            result.append(dict(item))
-    return result
-
-
-def _merge_arrays(base, override):
-    """Shape-aware array merge: keyed merge if every item has code/id, else append."""
-    base_arr = base if isinstance(base, list) else []
-    override_arr = override if isinstance(override, list) else []
-    keyed_field = _detect_keyed_merge_field(base_arr + override_arr)
-    if keyed_field:
-        return _merge_by_key(base_arr, override_arr, keyed_field)
-    return base_arr + override_arr
-
-
-def _structural_merge(base, override):
-    """Faithful port of resolve_customization.py's deep_merge: tables deep-merge,
-    arrays-of-tables keyed by code/id replace-then-append (other arrays append),
-    scalars override. Used only for the [workflow] customization layers — the
-    central-config path keeps its own simpler _deep_merge. Duplicated rather than
-    imported to keep this skill self-contained."""
-    if isinstance(base, dict) and isinstance(override, dict):
-        result = dict(base)
-        for key, over_val in override.items():
-            result[key] = (
-                _structural_merge(result[key], over_val) if key in result else over_val
-            )
-        return result
-    if isinstance(base, list) and isinstance(override, list):
-        return _merge_arrays(base, override)
-    return override
-
-
-def resolve_workflow(root, skill_dir, skill_name):
-    """Resolve the [workflow] customization block via the three-layer merge
-    (skill defaults -> team -> user), highest priority last. Same structural
-    rules as resolve_customization.py. All three layers are optional: a missing
-    file is skipped, but an unparseable one HALTs (via load_toml)."""
-    defaults = load_toml(posixpath.join(skill_dir, "customize.toml"))
-    custom_dir = posixpath.join(root, "_bmad", "custom")
-    team = load_toml(posixpath.join(custom_dir, f"{skill_name}.toml"))
-    user = load_toml(posixpath.join(custom_dir, f"{skill_name}.user.toml"))
-    merged = _structural_merge(defaults, team)
-    merged = _structural_merge(merged, user)
-    workflow = merged.get("workflow")
-    return workflow if isinstance(workflow, dict) else {}
-
-
-def load_central_config(root):
-    """Four-layer merge of _bmad/config.toml and its peers (highest priority
-    last). HALTs if the base _bmad/config.toml is missing or unparseable."""
-    bmad_dir = posixpath.join(root, "_bmad")
-    base_team = load_toml(posixpath.join(bmad_dir, "config.toml"), required=True)
-    base_user = load_toml(posixpath.join(bmad_dir, "config.user.toml"))
-    custom_team = load_toml(posixpath.join(bmad_dir, "custom", "config.toml"))
-    custom_user = load_toml(posixpath.join(bmad_dir, "custom", "config.user.toml"))
-
-    merged = _deep_merge(base_team, base_user)
-    merged = _deep_merge(merged, custom_team)
-    merged = _deep_merge(merged, custom_user)
-    return merged
-
-
-def flatten_central_config(merged):
-    """Lift scalar keys from [core] and [modules.bmm] into a single namespace.
-    Module keys take precedence on collision (installer strips core keys from
-    module buckets, so collisions shouldn't happen in practice)."""
-    flat = {}
-    modules = merged.get("modules")
-    modules = modules if isinstance(modules, dict) else {}
-    for section in (merged.get("core"), modules.get("bmm")):
-        if not isinstance(section, dict):
-            continue
-        for key, value in section.items():
-            if isinstance(value, bool):
-                flat[key] = "true" if value else "false"
-            elif isinstance(value, (str, int, float)):
-                flat[key] = str(value)
-    return flat
-
-
-def render_template(content, vars_):
-    """Resolve {{.var}} substitutions. Unresolved references emit an empty string,
-    but main() HALTs on any missing reference before rendering starts, so this
-    fallback never fires in practice."""
-    return re.sub(r"\{\{\.(\w+)\}\}", lambda m: vars_.get(m.group(1), ""), content)
-
-
-def collect_missing_vars(sources, vars_):
-    """Map each {{.var}} name referenced by the source .md files but absent from
-    the merged config to the files that reference it. A missing key must HALT:
-    missingkey=zero rendering would bake a corrupted workflow (empty paths,
-    blank language lines) with no failure signal."""
-    missing = {}
-    for fname, content in sources:
-        for name in re.findall(r"\{\{\.(\w+)\}\}", content):
-            if name not in vars_:
-                files = missing.setdefault(name, [])
-                if fname not in files:
-                    files.append(fname)
-    return missing
-
-
-def _scalar_str(value):
-    """Stringify a scalar for inline rendering: booleans lowercase (matching
-    BMad config conventions), None as empty, everything else via str()."""
-    if value is None:
-        return ""
-    if isinstance(value, bool):
-        return "true" if value else "false"
-    return str(value)
-
-
-# [workflow] keys holding review layers ([[workflow.review_layers]] tables with
-# id/name/instruction/when fields). This renderer knows this skill's
-# customization schema outright — layer semantics are materialized here, not
-# interpreted by the LLM at run time.
-_REVIEW_LAYER_KEYS = ("review_layers", "oneshot_review_layers")
-
-
-def expand_review_layer_skill_roots(workflow, skill_root):
-    """Expand only {skill-root} inside resolved review-layer instructions.
-
-    Review layers originate in customization after regular template rendering,
-    so their prompt paths need this explicit pass. Runtime placeholders remain
-    untouched for the parent to supply to each child at dispatch time.
-    """
-    expanded_workflow = dict(workflow)
-    for key in _REVIEW_LAYER_KEYS:
-        layers = workflow.get(key)
-        if not isinstance(layers, list):
-            continue
-        expanded_layers = []
-        for layer in layers:
-            if not isinstance(layer, dict):
-                expanded_layers.append(layer)
-                continue
-            expanded_layer = dict(layer)
-            instruction = expanded_layer.get("instruction")
-            if isinstance(instruction, str):
-                expanded_layer["instruction"] = instruction.replace(
-                    "{skill-root}", skill_root
-                )
-            expanded_layers.append(expanded_layer)
-        expanded_workflow[key] = expanded_layers
-    return expanded_workflow
-
-
-def _render_review_layers(layers):
-    """Materialize review layers into direct invocation blocks. A layer with an
-    empty or missing instruction is disabled (that is how an override turns off
-    a default layer) and drops out entirely. A `when` condition is the one part
-    that stays with the LLM: it renders as a run-time guard line. No active
-    layers renders as the HALT instruction the workflow would otherwise have to
-    derive from an empty list."""
-    active = [
-        layer
-        for layer in layers
-        if isinstance(layer, dict) and _scalar_str(layer.get("instruction")).strip()
-    ]
-    if not active:
-        return (
-            "No review layers are active. HALT with status `blocked` and "
-            "blocking condition `no active review layers`."
-        )
-    blocks = []
-    for layer in active:
-        title = (
-            _scalar_str(layer.get("name")).strip()
-            or _scalar_str(layer.get("id")).strip()
-            or "Review layer"
-        )
-        lines = [f"#### {title}", ""]
-        when = _scalar_str(layer.get("when")).strip()
-        if when:
-            lines.append(
-                "Run this layer only if the following holds in the "
-                f"current context: `{when}`"
-            )
-            lines.append("")
-        lines.append(_scalar_str(layer.get("instruction")).strip("\n"))
-        blocks.append("\n".join(lines))
-    return "\n\n".join(blocks)
-
-
-def _render_workflow_value(key, value):
-    """Format a resolved [workflow] value for inline substitution. Review-layer
-    keys materialize as invocation blocks; other lists render as markdown
-    bullets (empty -> '_None._'); scalars render verbatim. Each list item uses
-    the same scalar formatting so booleans stay consistent. Entries are emitted
-    as-is so runtime placeholders like {project-root} or {diff_output} survive
-    for the LLM to resolve."""
-    if key in _REVIEW_LAYER_KEYS and isinstance(value, list):
-        return _render_review_layers(value)
-    if isinstance(value, list):
-        if not value:
-            return "_None._"
-        return "\n".join(f"- {_scalar_str(item)}" for item in value)
-    return _scalar_str(value)
-
-
-def render_workflow(content, workflow):
-    """Resolve {workflow.<key>} placeholders from the resolved [workflow] block.
-    Unknown keys emit an empty string (missingkey=zero, matching render_template).
-    Distinct regex from render_template so single-curly runtime placeholders
-    elsewhere are untouched."""
-    return re.sub(
-        r"\{workflow\.(\w+)\}",
-        lambda m: _render_workflow_value(m.group(1), workflow.get(m.group(1))),
-        content,
-    )
-
-
-def main():
-    script_dir = os.path.dirname(os.path.abspath(__file__))
-    skill_name = os.path.basename(script_dir)
-    root = find_project_root()
-    root = root.replace(os.sep, "/")
-
-    vars_ = flatten_central_config(load_central_config(root))
-
-    for key in list(vars_.keys()):
-        vars_[key] = vars_[key].replace("{project-root}", root)
-
-    vars_["project_root"] = root
-
-    # Guarded ahead of the general missing-vars scan: sprint_status and
-    # deferred_work_file derive from it below, and unlike the scan (absent
-    # keys only) this also HALTs on a present-but-empty value.
-    implementation_artifacts = vars_.get("implementation_artifacts", "").strip()
-    if not implementation_artifacts:
-        print(
-            "HALT and report to the user: config is missing `implementation_artifacts` "
-            "(expected under [core] or [modules.bmm] in _bmad/config.toml)"
-        )
-        sys.exit(1)
-
-    vars_["sprint_status"] = posixpath.join(
-        implementation_artifacts, "sprint-status.yaml"
-    )
-    vars_["deferred_work_file"] = posixpath.join(
-        implementation_artifacts, "deferred-work.md"
-    )
-
-    sources = []
-    for fname in sorted(os.listdir(script_dir)):
-        if not fname.endswith(".md") or fname == "SKILL.md":
-            continue
-        with open(
-            posixpath.join(script_dir, fname), "r", encoding="utf-8", newline=""
-        ) as fh:
-            sources.append((fname, fh.read()))
-
-    missing = collect_missing_vars(sources, vars_)
-    if missing:
-        details = "; ".join(
-            f"`{name}` (referenced by {', '.join(files)})"
-            for name, files in sorted(missing.items())
-        )
-        print(
-            f"HALT and report to the user: config is missing {details} "
-            "(expected under [core] or [modules.bmm] in _bmad/config.toml)"
-        )
-        sys.exit(1)
-
-    skill_dir = script_dir.replace(os.sep, "/")
-    workflow = resolve_workflow(root, skill_dir, skill_name)
-    open_spec = workflow.get("open_spec")
-    if not isinstance(open_spec, str):
-        print(
-            "HALT and report to the user: customization `workflow.open_spec` "
-            "must be a string"
-        )
-        sys.exit(1)
-    workflow = expand_review_layer_skill_roots(workflow, skill_dir)
-
-    out_dir = posixpath.join(root, "_bmad", "render", skill_name)
-    os.makedirs(out_dir, exist_ok=True)
-
-    for fname in os.listdir(out_dir):
-        if fname.endswith(".md"):
-            os.remove(posixpath.join(out_dir, fname))
-
-    for fname, content in sources:
-        dst = posixpath.join(out_dir, fname)
-        with open(dst, "w", encoding="utf-8", newline="") as fh:
-            fh.write(render_workflow(render_template(content, vars_), workflow))
-
-    workflow_md = posixpath.join(out_dir, "workflow.md")
-    print(f"read and follow {workflow_md}")
-
-
-if __name__ == "__main__":
-    main()