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 reads BMad configuration from the central four-layer TOML
surface introduced in #2285 (_bmad/config.toml plus config.user.toml
and the two _bmad/custom/ overrides), with a fallback to the legacy
per-module _bmad/bmm/config.yaml for pre-#2285 installs.
Compile-time refs ({{.var}}) get substituted at render time. LLM-runtime
refs ({var}) pass through untouched.
Renderer (render.py)
- Python 3 stdlib only (tomllib, already bundled since 3.11). 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 anywhere on the path.
- load_central_config deep-merges the four TOML layers in priority
order (base-team → base-user → custom-team → custom-user) so user
overrides in _bmad/custom/config.user.toml win over installer-
regenerated base values. flatten_central_config lifts scalar keys
from [core] and [modules.bmm] into the renderer's flat namespace;
module keys beat core on collision (matches the installer's own
core-key-stripping behavior).
- When _bmad/config.toml is absent, falls through to the legacy
flat-YAML parser for _bmad/bmm/config.yaml — the renderer keeps
working across the #2285 transition.
- {{.var}} substitution; unresolved refs emit empty string (Go
missingkey=zero semantics).
- Smart defaults for planning_artifacts / implementation_artifacts /
communication_language applied after config load. Derives
sprint_status / deferred_work_file from implementation_artifacts.
{{.main_config}} points at whichever surface was actually read.
- Renders every .md in the skill dir except SKILL.md to
{project-root}/_bmad/render/bmad-quick-dev/.
- On success, stderr summary plus a single stdout line:
"read and follow {workflow_md}". On failure, stdout HALT directive —
per the Anthropic skills spec, script stdout is the defined agent-
communication channel.
Skill entry (SKILL.md)
- Two-line shim: run python render.py, follow stdout. No template
tokens in SKILL.md itself.
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).
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 and step-05;
the specLoopIteration counter init 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.
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.
- 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.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
* feat(quick-dev): sync sprint-status.yaml on epic-story implementation
When quick-dev infers the intent is an epic story, resolve the full
sprint-status key during step-01's previous-story-continuity sub-step,
then sync sprint-status.yaml at the two workflow boundaries code-review
already owns the trailing half of:
- step-03 start: flip the story to in-progress and lift the parent
epic out of backlog if needed.
- step-05 end: flip the story to review. Code-review keeps ownership
of review -> done.
Resolution uses exact numeric-segment equality on the {epic}-{story}
prefix (never string-prefix match), so 1-1 no longer collides with
1-10. Both sync blocks are idempotent so step-04 loopbacks do not
clobber human edits or bump last_updated without cause. Skips silently
when sprint-status.yaml is missing or the intent is not an epic story.
* feat(quick-dev): add sprint-status sync to one-shot route
Epic stories do get implemented via one-shot in practice. Add the same
in-progress / review sync pair that step-03 and step-05 already have,
with identical idempotency guards and skip-on-missing behavior.
* refactor(quick-dev): extract sprint-status sync into shared file
Replace inline sync blocks in step-03, step-05, and step-oneshot with
one-line callouts to sync-sprint-status.md. The shared file owns all
edge-case handling (idempotency, epic lift, missing file/key) and is
parameterized by {target_status}. Any future route picks it up with a
single Follow line.
* fix(quick-dev): resolve story_key on early-exit resume paths
Extract story-key resolution into a shared subsection referenced by
all early-exit paths and INSTRUCTIONS, ensuring sprint-status sync
works for resumed epic stories.
* refactor(quick-dev): tighten story-key resolution prompt
Remove mechanical details the LLM can infer; keep only the
collision-prevention constraint.
* feat(quick-dev): add epic context compilation to step-01
Fork step-01 context loading: epic stories get a sub-agent that
compiles planning docs into a cached epic-{N}-context.md, while
freeform intents keep the lightweight directory-listing path.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* fix(quick-dev): tighten epic context loading per PR review
- Validate cached epic-<N>-context.md is non-empty and starts with the
expected header before loading; treat invalid cache as missing.
- Replace inline {N} placeholders with <N> so the skill validator does
not flag them as unresolved workflow variables.
- Replace ambiguous "fall back to path B" with an explicit instruction
to scan/load planning artifacts using path B's procedure, with a note
not to re-evaluate path B's gating clause.
Addresses CodeRabbit and Augment review comments on PR #2218.
* refactor(quick-dev): tighten compile-epic-context prompt
- Restructure with Task/Steps opening and Exact Output Format section.
- Switch Stories template to bullet form for clarity.
- Add "no hallucination" and explicit "omit empty sections except Goal
and Stories" rules.
- Use <N> instead of {N} in the filename for consistency with step-01.
* refactor(quick-dev): restructure epic-story context loading
Reshape path A of step-01 into five explicit numbered steps and add an
inline-compilation fallback for runtimes that cannot spawn sub-agents
(Copilot, Codex, local Ollama, older Claude).
- Pull cache validity, compilation, verification, and continuity into
separate numbered steps instead of nested paragraphs.
- Define "valid cached context" upfront: non-empty and starts with
`# Epic <N> Context:`.
- Add inline-compilation fallback: runtimes without sub-agent support
read compile-epic-context.md and follow it directly.
- Make previous-story continuity run regardless of which context source
succeeded (cache hit, fresh compilation, or path-B raw fallback).
* fix(quick-dev): address review findings on epic context compilation
- Add freshness check to cached epic-N-context.md (invalidate when any
planning artifact is newer)
- Remove the silent fall-back-to-raw-planning-docs path on compile
failure; HALT and report instead
- Add explicit "ambiguous → freeform" tiebreakers for both the path A
header and the epic-number identification step
- Drop "verbatim" from compile-epic-context.md format header to resolve
the verbatim-vs-omit-empty contradiction
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* refactor(quick-dev): eliminate spec-wip.md singleton
Write directly to spec-{slug}.md with status: draft instead of using
a shared spec-wip.md file. Use draft status for resume detection in
step-01. Removes wipFile variable from all step frontmatter and
workflow initialization.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* fix(quick-dev): address PR review findings
- step-02: preserve Intent block on draft resume instead of regenerating from template (F1)
- step-01: resume existing draft on slug collision rather than creating -2 duplicate (F3)
- step-01: recognize `done` status and ingest as context instead of silently re-implementing (F4)
- step-oneshot: remove unused spec_file frontmatter declaration (F6)
---------
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
When quick-dev infers the intent is an epic story, it now scans for
completed specs from the same epic and loads the most recent one to
extract Code Map, Design Notes, Spec Change Log, and task list as
continuity context for planning.
Teach quick-dev step-01 what BMAD phase 1-3 planning artifacts are (PRD,
architecture, UX, epics, product brief) so it can selectively load relevant
docs instead of guessing from code alone. Remove hard cap of 3 on spec
context field, replacing with judgment guidance. Instruct step-03 to
explicitly pass context files to the implementation sub-agent.
* feat(quick-dev): generate spec trace file for one-shot route
One-shot changes now leave a lightweight spec file with frontmatter,
intent summary, and suggested review order — eliminating numbering
gaps when quick-dev is used as the primary dev loop.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* refactor(quick-dev): reference spec template instead of inlining structure
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* refactor(quick-dev): deduplicate slug derivation and clarify title variable
Extract shared slug derivation logic above the route fork in step-01 so
both one-shot and plan-code-review routes use a single instruction block.
Add explicit title variable assignment in step-oneshot before it is
referenced in the Generate Spec Trace section.
---------
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Short-circuit evaluation in step-01: explicit argument → conversation
context → full artifact scan. Stops prompting as soon as intent is
unambiguous. All existing scan behaviors preserved in tier 3.
Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* refactor: consolidate agents into phase-based skill directories
Remove separate agent/workflow/skill directories (src/bmm/agents,
src/bmm/workflows, src/core/skills, src/utility/agent-components) and
reorganize all content into phase-based structures under src/bmm-skills
(1-analysis, 2-plan-workflows, 3-solutioning, 4-implementation) and
src/core-skills. Eliminates the agent/skill distinction by treating
agents as skills within their workflow phase.
* fix: update broken file references to use new bmm-skills paths
* docs: update all references for unified bmad-quick-dev workflow
Remove all references to the old separate bmad-quick-spec and
bmad-quick-dev-new-preview workflows. The new bmad-quick-dev is a
unified workflow that handles intent clarification, planning,
implementation, review, and presentation in a single run.
Updated files across English docs, Chinese translations, source
skill manifests, website diagram, and build tooling.
Alex Verkhovsky
Brian