feat(quick-dev): render templates via stdlib Python at skill entry

[alexeyv]

What

Move compile-time variable substitution out of the LLM and into a deterministic Python step.

SKILL.md becomes a two-line stdout-dispatch shim that runs render.py and follows the instruction it prints. The renderer walks up to find _bmad/, loads flat-YAML config, applies smart defaults, bakes {project-root} to an absolute path, and writes rendered .md files to _bmad/render/bmad-quick-dev/.

Compile-time refs ({{.var}}) get substituted at render time. LLM-runtime refs ({var}) pass through untouched.

Why

Today the LLM resolves {project-root}, {main_config}, {implementation_artifacts}, {communication_language}, {sprint_status}, and {deferred_work_file} at runtime by reading config. That pushes substitution onto the LLM (fragile: it can misresolve or drift), leaves no place for project-level overrides beyond core BMM config, and conflates compile-time refs with LLM-runtime refs.

Moving compile-time substitution into a deterministic Python step eliminates LLM drift and opens the door for other skills to adopt the same pattern later.

How

Renderer (render.py)

• Python 3 stdlib only. UTF-8 I/O. Every invocation rebuilds from scratch — no hash, no cache.
• find_project_root walks up from cwd; HALT to stdout if no _bmad/ is found.
• Flat-YAML parser skips inline dicts/lists, indented children, and comments. Stderr on missing config; smart defaults applied.
• {{.var}} substitution; unresolved refs emit empty string (Go missingkey=zero semantics).
• Smart defaults for planning_artifacts / implementation_artifacts / communication_language. Derives sprint_status / deferred_work_file from implementation_artifacts.
• Renders every .md in the skill dir except SKILL.md.
• On success, stderr summary plus a single stdout line: read and follow {workflow_md}. On failure, stdout HALT directive.

Skill entry (SKILL.md)

• Two-line shim: python render.py, then follow stdout. No template tokens in SKILL.md itself — per the Anthropic skills spec, script stdout is the defined agent-communication channel.

Template conversions

• workflow.md, step-01..05, step-oneshot, sync-sprint-status: convert every compile-time {var} reference to {{.var}}. Runtime refs preserved.
• spec-template.md untouched (single-curly comment hint stays as documentation; protected by the new TPL-01 validator rule).

Skill-prose cleanups bundled in

• Remove dead step-file frontmatter: empty-string variable declarations (spec_file, story_key, diff_output, review_mode) in quick-dev step-01 and code-review step-01; empty ---/--- blocks in step-03/step-05. The specLoopIteration counter init was moved from step-04 frontmatter into the step body, where first-entry vs loopback semantics are explicit.
• Unify the language rule across all six quick-dev step files plus workflow.md to the canonical two-line form used by bmad-checkpoint-preview / bmad-create-story / bmad-retrospective: Speak in X. Write any file output in Y. Closes the gap where document_output_language was loaded but never enforced on file writes.
• Trim workflow.md to its load-bearing parts: drop INITIALIZATION SEQUENCE (only {date} was actually consumed downstream, and it is system-generated rather than config-sourced); drop redundant HALT meta-rules (every step file already has explicit HALT directives at every checkpoint); merge Step Processing Rules with Critical Rules into one list; drop the self-descriptive WORKFLOW ARCHITECTURE intro bullets (Micro-file Design, Just-In-Time Loading, etc.) that did not change LLM behavior. Net: 73 lines down to 38.
• Remove the now-dead main_config derivation from render.py — nothing in quick-dev still references {{.main_config}} after the workflow.md trim.

Tooling

• tools/validate-skills.js — add TPL-01 rule. Files whose name contains template must not contain compile-time {{.var}} substitutions. Template files seed durable, version-controlled artifacts that execute on other machines; baking a value at render time would freeze a machine-local path into every downstream artifact. HIGH severity.
• tools/validate-file-refs.js — add render/ to INSTALL_ONLY_PATHS so the validator recognizes the runtime-generated buffer.
• tools/skill-validator.md — document TPL-01; deterministic rule count bumped from 14 to 15.

Testing

• npm ci && npm run quality passes — full suite runs via pre-commit hook (lint, markdownlint, test:refs, test:install, format:check, validate:skills). All 242 installation tests pass. Skills validator strict-mode pass — only 2 LOW findings, both in skills not touched by this PR.
• Three adversarial review passes ran in parallel (blind hunter, edge-case hunter, acceptance auditor) at session-capable model tier on the original render.py + template-conversion change. Four patches applied in-branch: stderr on missing config, fix for silent drop of unquoted {...} values, explicit UTF-8 encoding, removal of {{if}}...{{end}} support (nested-case bug; not used by any current template). 10 findings deferred to harness-side deferred-work.md.
• Skill-prose cleanups (frontmatter, language rule, workflow.md trim) reviewed interactively; no semantic change to runtime behavior — every load-bearing reference traced and confirmed before deletion.
• Manual: python3 src/bmm-skills/4-implementation/bmad-quick-dev/render.py from a harness cwd produces expected rendered output; all {{.var}} placeholders resolved to absolute paths; runtime {var} refs preserved; spec-template.md's {project-root}/-prefix comment passes through as documentation hint.

Follow-ups deferred

• Migrate _bmad/<module>/config.yaml to TOML. The hand-rolled flat-YAML parser in render.py is the cleanest stdlib-Python option today, but it relies on the undocumented invariant that installed configs are flat scalar maps. TOML (tomllib, stdlib 3.11+) is a strict superset of the data model used today and removes the parser entirely. Blast radius and migration plan documented in harness deferred-work.md.
• Six other render.py findings (regex hyphen handling, error broadening, atomic writes, etc.) — see harness deferred-work.md.