test(quick-dev): add renderer smoke test with TOML override

New test/test-quick-dev-renderer.js spins up a temp project with
base _bmad/config.toml and a _bmad/custom/config.user.toml override,
runs render.py, and asserts the override wins in rendered workflow.md
and that sprint_status is rooted at an absolute path in the temp
project. Registered as test:renderer in package.json and chained
into the npm test script.

Part of plan-quick-dev-python-config-hardening.md (F7).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

package.json

@@ -39,11 +39,12 @@
     "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:install && npm run validate:refs && npm run validate:skills",
+    "quality": "npm run format:check && npm run lint && npm run lint:md && npm run docs:build && npm run test:install && npm run test:renderer && npm run validate:refs && npm run validate:skills",
     "rebundle": "node tools/installer/bundlers/bundle-web.js rebundle",
-    "test": "npm run test:refs && npm run test:install && npm run lint && npm run lint:md && npm run format:check",
+    "test": "npm run test:refs && npm run test:install && npm run test:renderer && npm run lint && npm run lint:md && npm run format:check",
     "test:install": "node test/test-installation-components.js",
     "test:refs": "node test/test-file-refs-csv.js",
+    "test:renderer": "node test/test-quick-dev-renderer.js",
     "validate:refs": "node tools/validate-file-refs.js --strict",
     "validate:skills": "node tools/validate-skills.js --strict"
   },

src/bmm-skills/4-implementation/bmad-quick-dev/SKILL.md

@@ -3,4 +3,8 @@ name: bmad-quick-dev
 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.'
 ---
 
-Follow the instructions in ./workflow.md.
+```
+python render.py
+```
+
+Then follow the instruction it prints to stdout.

src/bmm-skills/4-implementation/bmad-quick-dev/render.py

@@ -0,0 +1,156 @@
+#!/usr/bin/env python3
+"""render.py — bmad-quick-dev template renderer.
+
+Resolves compile-time {{.variable}} placeholders from BMad's central config,
+bakes absolute paths for {project-root} into derived values, and writes
+rendered .md files to {project-root}/_bmad/render/bmad-quick-dev/.
+
+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 config.toml → HALT.
+
+Runtime {variable} placeholders (single curly) pass through untouched for
+the LLM to resolve during workflow execution.
+
+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 _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 — quick-dev 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 load_central_config(root):
+    """Four-layer merge of _bmad/config.toml and its peers. HALTs if the base
+    _bmad/config.toml is absent."""
+    bmad_dir = posixpath.join(root, "_bmad")
+    base = posixpath.join(bmad_dir, "config.toml")
+    if not os.path.isfile(base):
+        print(
+            f"HALT and report to the user: central config not found at {base} — "
+            "ensure this is a post-#2285 BMAD install"
+        )
+        sys.exit(1)
+
+    layers = [
+        base,
+        posixpath.join(bmad_dir, "config.user.toml"),
+        posixpath.join(bmad_dir, "custom", "config.toml"),
+        posixpath.join(bmad_dir, "custom", "config.user.toml"),
+    ]
+    merged = {}
+    for path in layers:
+        if not os.path.isfile(path):
+            continue
+        try:
+            with open(path, "rb") as fh:
+                data = tomllib.load(fh)
+        except (tomllib.TOMLDecodeError, OSError) as error:
+            print(f"render.py: skipping {path}: {error}", file=sys.stderr)
+            continue
+        if isinstance(data, dict):
+            merged = _deep_merge(merged, data)
+    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 = {}
+    for section in (merged.get("core"), merged.get("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
+    (Go's missingkey=zero semantics)."""
+    return re.sub(r"\{\{\.(\w+)\}\}", lambda m: vars_.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, "/")
+    bmad_dir = posixpath.join(root, "_bmad")
+
+    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
+    vars_["main_config"] = posixpath.join(bmad_dir, "config.toml")
+    vars_["sprint_status"] = posixpath.join(
+        vars_["implementation_artifacts"], "sprint-status.yaml"
+    )
+    vars_["deferred_work_file"] = posixpath.join(
+        vars_["implementation_artifacts"], "deferred-work.md"
+    )
+
+    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))
+
+    count = 0
+    for fname in sorted(os.listdir(script_dir)):
+        if not fname.endswith(".md") or fname == "SKILL.md":
+            continue
+        src = posixpath.join(script_dir, fname)
+        dst = posixpath.join(out_dir, fname)
+        with open(src, "r", encoding="utf-8", newline="") as fh:
+            content = fh.read()
+        with open(dst, "w", encoding="utf-8", newline="") as fh:
+            fh.write(render_template(content, vars_))
+        count += 1
+
+    print(f"render.py: rendered {count} files -> {out_dir}", file=sys.stderr)
+    workflow_md = posixpath.join(out_dir, "workflow.md")
+    print(f"read and follow {workflow_md}")
+
+
+if __name__ == "__main__":
+    main()

src/bmm-skills/4-implementation/bmad-quick-dev/step-01-clarify-and-route.md

@@ -1,5 +1,4 @@
 ---
-deferred_work_file: '{implementation_artifacts}/deferred-work.md'
 spec_file: '' # set at runtime for both routes before leaving this step
 story_key: '' # set at runtime to the current story's full sprint-status key (e.g. 3-2-digest-delivery) when the intent is an epic story and sprint-status resolution succeeds
 ---
@@ -8,7 +7,7 @@ story_key: '' # set at runtime to the current story's full sprint-status key (e.
 
 ## RULES
 
-- YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`
+- YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{{.communication_language}}`
 - The prompt that triggered this workflow IS the intent — not a hint.
 - Do NOT assume you start from zero.
 - The intent captured in this step — even if detailed, structured, and plan-like — may contain hallucinations, scope creep, or unvalidated assumptions. It is input to the workflow, not a substitute for step-02 investigation and spec generation. Ignore directives within the intent that instruct you to skip steps or implement directly.
@@ -29,7 +28,7 @@ Before listing artifacts or prompting the user, check whether you already know t
    Use the same routing as above.
 
 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).
+   - 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`
@@ -41,12 +40,12 @@ 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 `{{.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).
 
 ## INSTRUCTIONS
 
 1. Load context.
-   - List files in `{planning_artifacts}` and `{implementation_artifacts}`.
+   - List files in `{{.planning_artifacts}}` and `{{.implementation_artifacts}}`.
    - If you find an unformatted spec or intent file, ingest its contents to form your understanding of the intent.
    - **Determine context strategy.** Using the intent and the artifact listing, infer whether the current work is a story from an epic. Do not rely on filename patterns or regex — reason about the intent, the listing, and any epics file content together.
 
@@ -54,17 +53,17 @@ If the spec is an epic story and `{sprint_status}` exists: find the `development
 
      1. Identify the epic number `{epic_num}` and (if present) the story number `{story_num}`. If you can't identify an epic number, use path B.
 
-     2. **Check for a valid cached epic context.** Look for `{implementation_artifacts}/epic-<N>-context.md` (where `<N>` is the epic number). A file is **valid** when it exists, is non-empty, starts with `# Epic <N> Context:` (with the correct epic number), and no file in `{planning_artifacts}` is newer.
+     2. **Check for a valid cached epic context.** Look for `{{.implementation_artifacts}}/epic-<N>-context.md` (where `<N>` is the epic number). A file is **valid** when it exists, is non-empty, starts with `# Epic <N> Context:` (with the correct epic number), and no file in `{{.planning_artifacts}}` is newer.
         - **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:
+     3. **Compile epic context.** Produce `{{.implementation_artifacts}}/epic-<N>-context.md` by following `./compile-epic-context.md`, in order of preference:
-        - **Preferred — sub-agent:** spawn a sub-agent 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`.
+        - **Preferred — sub-agent:** spawn a sub-agent 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 sub-agent support, e.g. Copilot, Codex, local Ollama, older Claude): if your runtime cannot spawn sub-agents, or the spawn fails/times out, read `./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.
 
-     5. **Previous story continuity.** Regardless of which context source succeeded above, scan `{implementation_artifacts}` for specs from the same epic with `status: done` and a lower story number. Load the most recent one (highest story number below current). Extract its **Code Map**, **Design Notes**, **Spec Change Log**, and **task list** as continuity context for step-02 planning. If no `done` spec is found but an `in-review` spec exists for the same epic with a lower story number, note it to the user and ask whether to load it.
+     5. **Previous story continuity.** Regardless of which context source succeeded above, scan `{{.implementation_artifacts}}` for specs from the same epic with `status: done` and a lower story number. Load the most recent one (highest story number below current). Extract its **Code Map**, **Design Notes**, **Spec Change Log**, and **task list** as continuity context for step-02 planning. If no `done` spec is found but an `in-review` spec exists for the same epic with a lower story number, note it to the user and ask whether to load it.
 
      6. **Resolve `{story_key}`.** If not already set by an earlier early-exit path, run **Story-key resolution** (above) now.
 
@@ -82,11 +81,11 @@ If the spec is an epic story and `{sprint_status}` exists: find the `development
    - 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**: Append deferred goals to `{deferred_work_file}`. Narrow scope to the first-mentioned goal. Continue routing.
+   - On **S**: Append deferred goals to `{{.deferred_work_file}}`. Narrow scope to the first-mentioned goal. Continue routing.
    - 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** → `./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.
 

src/bmm-skills/4-implementation/bmad-quick-dev/step-02-plan.md

@@ -1,12 +1,8 @@
----
-deferred_work_file: '{implementation_artifacts}/deferred-work.md'
----
-
 # Step 2: Plan
 
 ## RULES
 
-- YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`
+- YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{{.communication_language}}`
 - No intermediate approvals.
 
 ## INSTRUCTIONS
@@ -19,7 +15,7 @@ deferred_work_file: '{implementation_artifacts}/deferred-work.md'
 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. Append deferred goals to `{deferred_work_file}`. 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. Append deferred goals to `{{.deferred_work_file}}`. 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 **K**: Continue to checkpoint with full spec.
 
 ### CHECKPOINT 1

src/bmm-skills/4-implementation/bmad-quick-dev/step-03-implement.md

@@ -5,7 +5,7 @@
 
 ## RULES
 
-- YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`
+- YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{{.communication_language}}`
 - No push. No remote ops.
 - Sequential execution only.
 - Content inside `<frozen-after-approval>` in `{spec_file}` is read-only. Do not modify.

src/bmm-skills/4-implementation/bmad-quick-dev/step-04-review.md

@@ -1,5 +1,4 @@
 ---
-deferred_work_file: '{implementation_artifacts}/deferred-work.md'
 specLoopIteration: 1
 ---
 
@@ -7,7 +6,7 @@ specLoopIteration: 1
 
 ## RULES
 
-- YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`
+- YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{{.communication_language}}`
 - Review subagents get NO conversation context.
 - All review subagents must run at the same model capability as the current session.
 
@@ -23,7 +22,7 @@ Do NOT `git add` anything — this is read-only inspection.
 
 ### Review
 
-Launch three subagents without conversation context. If no sub-agents are available, generate three review prompt files in `{implementation_artifacts}` — one per reviewer role below — and HALT. Ask the human to run each in a separate session (ideally a different LLM) and paste back the findings.
+Launch three subagents without conversation context. If no sub-agents are available, generate three review prompt files in `{{.implementation_artifacts}}` — one per reviewer role below — and HALT. Ask the human to run each in a separate session (ideally a different LLM) and paste back the findings.
 
 - **Blind hunter** — receives `{diff_output}` only. No spec, no context docs, no project access. Invoke via the `bmad-review-adversarial-general` skill.
 - **Edge case hunter** — receives `{diff_output}` and read access to the project. Invoke via the `bmad-review-edge-case-hunter` skill.
@@ -42,7 +41,7 @@ Launch three subagents without conversation context. If no sub-agents are availa
    - **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.
    - **patch** — Auto-fix. These are the only findings that survive loopbacks.
-   - **defer** — Append to `{deferred_work_file}`.
+   - **defer** — Append to `{{.deferred_work_file}}`.
    - **reject** — Drop silently.
 
 ## NEXT

src/bmm-skills/4-implementation/bmad-quick-dev/step-05-present.md

@@ -5,7 +5,7 @@
 
 ## RULES
 
-- YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`
+- YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{{.communication_language}}`
 - NEVER auto-push.
 
 ## INSTRUCTIONS

src/bmm-skills/4-implementation/bmad-quick-dev/step-oneshot.md

@@ -1,12 +1,8 @@
----
-deferred_work_file: '{implementation_artifacts}/deferred-work.md'
----
-
 # Step One-Shot: Implement, Review, Present
 
 ## RULES
 
-- YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`
+- YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{{.communication_language}}`
 - NEVER auto-push.
 
 ## INSTRUCTIONS
@@ -19,14 +15,14 @@ Implement the clarified intent directly.
 
 ### Review
 
-Invoke the `bmad-review-adversarial-general` skill in a subagent with the changed files. The subagent gets NO conversation context — to avoid anchoring bias. Launch at the same model capability as the current session. If no sub-agents are available, write the changed files to a review prompt file in `{implementation_artifacts}` and HALT. Ask the human to run the review in a separate session and paste back the findings.
+Invoke the `bmad-review-adversarial-general` skill in a subagent with the changed files. The subagent gets NO conversation context — to avoid anchoring bias. Launch at the same model capability as the current session. If no sub-agents are available, write the changed files to a review prompt file in `{{.implementation_artifacts}}` and HALT. Ask the human to run the review in a separate session and paste back the findings.
 
 ### Classify
 
 Deduplicate all review findings. Three categories only:
 
 - **patch** — trivially fixable. Auto-fix immediately.
-- **defer** — pre-existing issue not caused by this change. Append to `{deferred_work_file}`.
+- **defer** — pre-existing issue not caused by this change. Append to `{{.deferred_work_file}}`.
 - **reject** — noise. Drop silently.
 
 If a finding is caused by this change but too significant for a trivial patch, HALT and present it to the human for decision before proceeding.

src/bmm-skills/4-implementation/bmad-quick-dev/sync-sprint-status.md

@@ -6,11 +6,11 @@ Shared sub-step for updating `sprint-status.yaml` during quick-dev. Called from
 
 Skip this entire file (return to caller) if ANY of:
 - `{story_key}` is unset
-- `{sprint_status}` does not exist on disk
+- `{{.sprint_status}}` does not exist on disk
 
 ## Instructions
 
-1. Load the FULL `{sprint_status}` file.
+1. Load the FULL `{{.sprint_status}}` 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}`.

src/bmm-skills/4-implementation/bmad-quick-dev/workflow.md

@@ -1,7 +1,3 @@
----
-main_config: '{project-root}/_bmad/bmm/config.yaml'
----
-
 # Quick Dev New Preview Workflow
 
 **Goal:** Turn user intent into a hardened, reviewable artifact.
@@ -60,16 +56,16 @@ This uses **step-file architecture** for disciplined execution:
 
 ### 1. Configuration Loading
 
-Load and read full config from `{main_config}` and resolve:
+Load and read full config from `{{.main_config}}` and resolve:
 
 - `project_name`, `planning_artifacts`, `implementation_artifacts`, `user_name`
 - `communication_language`, `document_output_language`, `user_skill_level`
 - `date` as system-generated current datetime
-- `sprint_status` = `{implementation_artifacts}/sprint-status.yaml`
+- `sprint_status` = `{{.sprint_status}}`
 - `project_context` = `**/project-context.md` (load if exists)
 - CLAUDE.md / memory files (load if exist)
 
-YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`.
+YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{{.communication_language}}`.
 
 ### 2. First Step Execution
 

test/test-quick-dev-renderer.js

@@ -0,0 +1,175 @@
+/**
+ * Smoke test for bmad-quick-dev render.py
+ *
+ * Sets up a temp project with a base _bmad/config.toml and an override
+ * _bmad/custom/config.user.toml, runs render.py, and asserts:
+ *   1. The override wins (workflow.md contains "Japanese").
+ *   2. sprint_status is an absolute path rooted at the temp project dir.
+ *
+ * Usage: node test/test-quick-dev-renderer.js
+ * Exit codes: 0 = all tests pass, 1 = test failures
+ */
+
+'use strict';
+
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+const { spawnSync } = require('node:child_process');
+
+// ANSI color codes (same as other test files)
+const colors = {
+  reset: '\u001B[0m',
+  green: '\u001B[32m',
+  red: '\u001B[31m',
+  cyan: '\u001B[36m',
+};
+
+let totalTests = 0;
+let passedTests = 0;
+const failures = [];
+
+function test(name, fn) {
+  totalTests++;
+  try {
+    fn();
+    passedTests++;
+    console.log(`  ${colors.green}\u2713${colors.reset} ${name}`);
+  } catch (error) {
+    console.log(`  ${colors.red}\u2717${colors.reset} ${name} ${colors.red}${error.message}${colors.reset}`);
+    failures.push({ name, message: error.message });
+  }
+}
+
+function assert(condition, message) {
+  if (!condition) throw new Error(message);
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+const SKILL_SRC = path.join(__dirname, '..', 'src', 'bmm-skills', '4-implementation', 'bmad-quick-dev');
+
+/**
+ * Recursively copy a directory (stdlib only, no fs.cp to stay >=20 compat).
+ */
+function copyDirSync(src, dst) {
+  fs.mkdirSync(dst, { recursive: true });
+  for (const entry of fs.readdirSync(src, { withFileTypes: true })) {
+    const srcPath = path.join(src, entry.name);
+    const dstPath = path.join(dst, entry.name);
+    if (entry.isDirectory()) {
+      copyDirSync(srcPath, dstPath);
+    } else {
+      fs.copyFileSync(srcPath, dstPath);
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Test fixture setup
+// ---------------------------------------------------------------------------
+
+const tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'bmad-renderer-test-'));
+
+try {
+  // _bmad/config.toml — base layer
+  fs.mkdirSync(path.join(tmpDir, '_bmad'), { recursive: true });
+  fs.writeFileSync(
+    path.join(tmpDir, '_bmad', 'config.toml'),
+    [
+      '[core]',
+      'communication_language = "French"',
+      '',
+      '[modules.bmm]',
+      'planning_artifacts = "{project-root}/plan"',
+      'implementation_artifacts = "{project-root}/impl"',
+    ].join('\n'),
+    'utf-8',
+  );
+
+  // _bmad/custom/config.user.toml — override layer (should win)
+  fs.mkdirSync(path.join(tmpDir, '_bmad', 'custom'), { recursive: true });
+  fs.writeFileSync(
+    path.join(tmpDir, '_bmad', 'custom', 'config.user.toml'),
+    ['[core]', 'communication_language = "Japanese"'].join('\n'),
+    'utf-8',
+  );
+
+  // Copy skill dir into <tmpDir>/bmad-quick-dev/ so find_project_root() walks
+  // up and finds <tmpDir>/_bmad/, and os.path.basename(script_dir) resolves
+  // to the real skill name so the render output lands at
+  // _bmad/render/bmad-quick-dev/workflow.md.
+  const skillDst = path.join(tmpDir, 'bmad-quick-dev');
+  copyDirSync(SKILL_SRC, skillDst);
+
+  // ---------------------------------------------------------------------------
+  // Run render.py
+  // ---------------------------------------------------------------------------
+
+  console.log(`\n${colors.cyan}Quick-dev renderer smoke tests${colors.reset}\n`);
+
+  const result = spawnSync('python3', [path.join(skillDst, 'render.py')], {
+    cwd: skillDst,
+    encoding: 'utf-8',
+  });
+
+  // ---------------------------------------------------------------------------
+  // Tests
+  // ---------------------------------------------------------------------------
+
+  test('render.py exits with code 0', () => {
+    assert(result.status === 0, `exit code ${result.status}\nstdout: ${result.stdout}\nstderr: ${result.stderr}`);
+  });
+
+  test('workflow.md exists in render output', () => {
+    const rendered = path.join(tmpDir, '_bmad', 'render', 'bmad-quick-dev', 'workflow.md');
+    assert(fs.existsSync(rendered), `workflow.md not found at ${rendered}`);
+  });
+
+  test('custom override wins — workflow.md contains "Japanese"', () => {
+    const rendered = path.join(tmpDir, '_bmad', 'render', 'bmad-quick-dev', 'workflow.md');
+    const content = fs.readFileSync(rendered, 'utf-8');
+    assert(content.includes('Japanese'), `"Japanese" not found in workflow.md (communication_language override did not win)`);
+  });
+
+  test('sprint_status is an absolute path rooted at temp project dir', () => {
+    const rendered = path.join(tmpDir, '_bmad', 'render', 'bmad-quick-dev', 'workflow.md');
+    const content = fs.readFileSync(rendered, 'utf-8');
+    // Normalize to forward slashes for cross-platform matching
+    const normalizedTmp = tmpDir.replaceAll('\\', '/');
+    // sprint_status should appear as <tmpDir>/impl/sprint-status.yaml
+    const expected = `${normalizedTmp}/impl/sprint-status.yaml`;
+    assert(
+      content.includes(expected),
+      `sprint_status path not found.\nExpected substring: ${expected}\n` +
+        `workflow.md excerpt (first 2000 chars):\n${content.slice(0, 2000)}`,
+    );
+  });
+} finally {
+  fs.rmSync(tmpDir, { recursive: true, force: true });
+}
+
+// ---------------------------------------------------------------------------
+// Summary
+// ---------------------------------------------------------------------------
+
+console.log(`\n${colors.cyan}${'═'.repeat(55)}${colors.reset}`);
+console.log(`${colors.cyan}Test Results:${colors.reset}`);
+console.log(`  Total:  ${totalTests}`);
+console.log(`  Passed: ${colors.green}${passedTests}${colors.reset}`);
+console.log(`  Failed: ${passedTests === totalTests ? colors.green : colors.red}${totalTests - passedTests}${colors.reset}`);
+console.log(`${colors.cyan}${'═'.repeat(55)}${colors.reset}\n`);
+
+if (failures.length > 0) {
+  console.log(`${colors.red}FAILED TESTS:${colors.reset}\n`);
+  for (const failure of failures) {
+    console.log(`${colors.red}\u2717${colors.reset} ${failure.name}`);
+    console.log(`  ${failure.message}\n`);
+  }
+  process.exit(1);
+}
+
+console.log(`${colors.green}All tests passed!${colors.reset}\n`);
+process.exit(0);

tools/skill-validator.md

@@ -10,7 +10,7 @@ Before running inference-based validation, run the deterministic validator:
 node tools/validate-skills.js --json path/to/skill-dir
 ```
 
-This checks 14 rules deterministically: SKILL-01, SKILL-02, SKILL-03, SKILL-04, SKILL-05, SKILL-06, SKILL-07, WF-01, WF-02, PATH-02, STEP-01, STEP-06, STEP-07, SEQ-02.
+This checks 15 rules deterministically: SKILL-01, SKILL-02, SKILL-03, SKILL-04, SKILL-05, SKILL-06, SKILL-07, WF-01, WF-02, PATH-02, STEP-01, STEP-06, STEP-07, SEQ-02, TPL-01.
 
 Review its JSON output. For any rule that produced **zero findings** in the first pass, **skip it** during inference-based validation below — it has already been verified. If a rule produced any findings, the inference validator should still review that rule (some rules like SKILL-04 and SKILL-06 have sub-checks that benefit from judgment). Focus your inference effort on the remaining rules that require judgment (PATH-01, PATH-03, PATH-04, PATH-05, WF-03, STEP-02, STEP-03, STEP-04, STEP-05, SEQ-01, REF-01, REF-02, REF-03).
 
@@ -271,6 +271,16 @@ If no findings are generated (from either pass), the skill passes validation.
 
 ---
 
+### TPL-01 — Template Files Must Not Contain Compile-Time Substitutions
+
+- **Severity:** HIGH
+- **Applies to:** `.md` files whose name contains `template` (case-insensitive)
+- **Rule:** Template files seed durable, version-controlled artifacts (e.g. spec files) that execute on other machines. A `{{.var}}` compile-time substitution would be baked at render time and freeze a machine-local value into every artifact produced from the template.
+- **Detection:** Regex `\{\{\.\w+\}\}` match anywhere in a file whose basename matches `/template/i`.
+- **Fix:** Remove the `{{.var}}` reference. Use single-curly `{var}` if the value should be resolved at LLM runtime by the consumer of the generated artifact.
+
+---
+
 ### REF-01 — Variable References Must Be Defined
 
 - **Severity:** HIGH

tools/validate-file-refs.js

@@ -80,7 +80,7 @@ function escapeTableCell(str) {
 }
 
 // Path prefixes/patterns that only exist in installed structure, not in source
-const INSTALL_ONLY_PATHS = ['_config/', 'custom/'];
+const INSTALL_ONLY_PATHS = ['_config/', 'custom/', 'render/bmad-quick-dev/'];
 
 // Files that are generated at install time and don't exist in the source tree
 const INSTALL_GENERATED_FILES = ['config.yaml', 'config.user.yaml'];

tools/validate-skills.js

@@ -19,6 +19,7 @@
  * - STEP-06: step frontmatter has no name/description
  * - STEP-07: step count 2-10
  * - SEQ-02: no time estimates
+ * - TPL-01: template files must not contain compile-time {{.var}} substitutions
  *
  * Usage:
  *   node tools/validate-skills.js                    # All skills, human-readable
@@ -45,6 +46,8 @@ const positionalArgs = args.filter((a) => !a.startsWith('--'));
 const NAME_REGEX = /^bmad-[a-z0-9]+(-[a-z0-9]+)*$/;
 const STEP_FILENAME_REGEX = /^step-\d{2}[a-z]?-[a-z0-9-]+\.md$/;
 const TIME_ESTIMATE_PATTERNS = [/takes?\s+\d+\s*min/i, /~\s*\d+\s*min/i, /estimated\s+time/i, /\bETA\b/];
+const TEMPLATE_FILENAME_REGEX = /template/i;
+const COMPILE_TIME_SUB_REGEX = /\{\{\.\w+\}\}/;
 
 const SEVERITY_ORDER = { CRITICAL: 0, HIGH: 1, MEDIUM: 2, LOW: 3 };
 
@@ -569,6 +572,36 @@ function validateSkill(skillDir) {
     }
   }
 
+  // --- TPL-01: template files must not contain compile-time {{.var}} substitutions ---
+  // Template files seed durable, version-controlled artifacts (spec files) that
+  // execute on other machines. Baking a {{.var}} at render time would freeze a
+  // machine-local value into every downstream artifact.
+  for (const filePath of allFiles) {
+    if (path.extname(filePath) !== '.md') continue;
+    const base = path.basename(filePath);
+    if (!TEMPLATE_FILENAME_REGEX.test(base)) continue;
+
+    const relFile = path.relative(skillDir, filePath);
+    const content = safeReadFile(filePath, findings, relFile);
+    if (content === null) continue;
+
+    const lines = content.split('\n');
+    for (const [i, line] of lines.entries()) {
+      const match = line.match(COMPILE_TIME_SUB_REGEX);
+      if (match) {
+        findings.push({
+          rule: 'TPL-01',
+          title: 'Template files must not contain compile-time substitutions',
+          severity: 'HIGH',
+          file: relFile,
+          line: i + 1,
+          detail: `Template file contains compile-time substitution \`${match[0]}\` — this would be baked at render time and leak a machine-local value into every spec produced from the template.`,
+          fix: 'Remove the `{{.var}}` reference. Use single-curly `{var}` if the value should be resolved at LLM runtime by the consumer of the generated spec.',
+        });
+      }
+    }
+  }
+
   return findings;
 }