Build now ends with a one or two sentence summary and a one-line offer
of next steps: create a PR, use bmad-walkthrough, or make another
change. The open_spec default is empty, so no editor opens unless
customized, and Build no longer appends a Suggested Review Order to the
spec; bmad-walkthrough generates a trail in conversation when the spec
has none.
Rename the in-session route to oneshot to match the step name, and
rewrite step-oneshot in plain English. Guard sprint-status updates at
the call sites so untracked work skips the sub-step, and shorten the
sync instruction while keeping its edge cases. Resume in-progress
oneshot specs on the oneshot route instead of dispatch, which expects a
Code Map and Tasks the oneshot spec does not have.
Drop the negative code -r renderer assertions, which only pinned the
config default; the sentinel override test still covers open_spec
substitution.
Rework the walkthrough doc to open with the comprehension order a
reader should follow and why a raw diff fails at it, frame "when to
use" around understanding a change and deciding whether to ship, move
the human-versus-agentic review note into an admonition, and drop the
Review Trail section.
Today every all-maybe-false entry routes to defer, so the deferred-work
ledger accumulates low-stakes hypotheticals that later sweeps read back
as work. Dropping the bucket wholesale would go too far the other way:
maybe-false means triage could not decide, and the claims that would be
serious if true are exactly the ones worth a durable record.
So gate the route on what the claim would be if true: medium or high
defers, with that severity marked unverified and what would settle it
as the evidence; low rejects, keeping the same note in the triage log.
Applied at the four triage sites (bmad-build step-04 and oneshot,
bmad-build-auto step-04, bmad-code-review step-03), the build-auto
deferred-list severity comment, and autonomous-development-loops.md.
* fix(customization): resolve the project root from the working directory
resolve_customization.py inferred the project root by walking up from the
skill's installed directory. For a skill installed under the user's home,
that walk reaches ~ — and when a user-level install has put a ~/_bmad
there, the resolver treats home as the project, finds no override, and
returns shipped defaults. The real project's _bmad/custom/ file is never
opened, with no error and no warning.
Whether an override takes effect therefore depended on where its skill
happened to be installed, which the override's author cannot see from the
override. Every harness installs global skills under ~/<tool>/skills, so
this hits all of them identically.
Resolve from an ordered candidate list instead: the working directory
first (the project is where the user works, not where the skill lives),
then the script's own install path (skills invoke it as
{project-root}/_bmad/scripts/..., so its grandparent is a root the caller
already resolved), then the skill directory as a last resort.
Rank _bmad/ above .git at every depth while walking. A submodule or
nested repo carries .git without being the BMad project, so treating the
two as equal stopped the walk short of the root owning _bmad/custom/ —
the same silent failure, reachable by project-installed skills too.
Break the silence: when the chosen root has no override for the skill but
a rejected candidate does, write a note to stderr naming both roots.
stdout stays pure JSON.
Pass --project-root from all 44 skill and doc invocation sites, matching
resolve_config.py, which already requires it. That asymmetry was the root
cause; with the flag passed there is nothing left to infer.
Fixes#2796
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01L8Hyqmp2giAVgEAnB49zEQ
* fix(customization): pass --project-root from the party and forge wrappers
resolve_party.py and resolve_personas.py shell out to the customization
resolver with --skill only, though both already hold the project root and
both pass it to resolve_config.py two functions earlier. The resolver
therefore had to infer a root, and since these wrappers capture stderr
and discard it, the note about a masked override went nowhere.
Under the old skill-directory-first inference this happened to land on
the right root for a project-installed skill; under working-directory
-first it takes the ambient root instead, which is wrong whenever the
party runs from a nested project or an unrelated worktree. Passing the
flag removes the inference for both paths rather than trading one wrong
guess for another.
Cover each wrapper with a test that captures the resolver command and
asserts the flag carries the project root it was given.
Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01L8Hyqmp2giAVgEAnB49zEQ
---------
Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
Add a Correct Course section describing when to run the skill and how
its change proposal feeds back into story tracking, and point the
implementation-skill tables on Build a Change and Skills and Agents at
it instead of pages that only mention the skill in passing.
Move Get Answers About BMad under Start and Autonomous Development Loops
under Build. Split the Workflow Map into a planning-skills section on
Choose a Planning Path (with a new planning-skills.svg) and an
implementation-skills section on Build a Change. Consolidate Agents,
Skills, Core Tools, and Advanced Elicitation into one Skills and Agents
page whose agent codes and skill list match the shipped sources. Retire
the v4 upgrade guide and the external-modules prompt, remove the How-To
Guides and Explanation sidebar groups, and redirect every retired route.
Create the Customize and Extend chapter after Existing Codebases with five
pages under docs/customize/: Customize BMad, Adopt BMad Across a Team,
Add Modules, Use Web Bundles, Run Multi-Agent Discussions.
Retire eight English pages with redirects: how-to/customize-bmad,
explanation/named-agents, how-to/expand-bmad-for-your-org,
how-to/install-custom-modules, reference/modules, how-to/use-web-bundles,
explanation/web-bundles, explanation/party-mode.
Corrections against shipped sources: the installer has no community
catalog browser (one custom/community prompt with an unverified-module
warning); bmad-prd's checklist key is validation_checklist_template; the
brief template ships under assets/; doc_standards passes run in declared
order; the web-bundle shelf personas now match web-bundles/bundles.json.
Add a four-page chapter after Plan Larger Work: Start in an Existing
Codebase (the repo is the knowledge; size the work from the source),
Set and Maintain Project Context, Getting Deeper as the worked example,
and The Theory of Project Context as optional last reading.
Retire six English pages with redirects, drop the empty English
Tutorials sidebar group, collapse Plan Larger Work and Existing
Codebases in the sidebar, reflow how-to and explanation orders, and
retarget Welcome, README, Plan, Reference, and style-guide links.
Localized copies stay as deferred translation work.
The retrospective reads what the coding sessions produced: the diff,
the commits, the story records. That is Build-side work on built code,
so the page belongs beside Build, Review, and Test Completed Work
rather than at the end of the Plan chapter. Move the page, its sidebar
entry, and the /explanation/retrospective redirect; retarget the
inbound links.
Introduce a Plan chapter of eight pages under docs/plan/: Choose a
Planning Path, Plan Inside an Organization, Explore and Validate an
Idea, Research a Decision, Define Requirements and a Specification,
Design UX and Architecture, Break Work into Stories and Track It, and
Finish an Epic. Content is written from the current skill sources and
describes what each skill takes in, what it produces, and how to steer
it.
Retire ten English pages from how-to and explanation with redirects to
their new homes, renumber the remaining sidebar orders, migrate English
links, shrink the Welcome router bullet, and add a Plan Larger Work
sidebar group after Build. Localized copies of the retired pages are
recorded in deferred work.
* docs: rewrite Build a Change wait-cost section
Replace "Why It Works This Way" with a comparison to plan-mode-plus-agent,
and send the extra-pass cost to Review a Change.
* docs: reframe Build wait-cost around review and attention
Plan-and-implement is comparable to plan mode; the extra time is
review, triage, and auto-fix, which saves human attention.
* docs: add Review a Change page
Add the Build-chapter how-to for bmad-code-review, list it after Build a
Change, redirect the deleted adversarial-review explanation, and point
the existing disclaimers, catalog rows, and a review_layers customize
example at the new page.
* docs: rewrite Review a Change around extra passes, cost, and /code-review
Retarget remaining English first-party links to the canonical Build pages,
list the chapter in llms.txt, order Start and Build first in llms-full, and
reject superseded English routes in the published-model check.
* feat(build): route after design instead of before investigation
Move the one-shot vs full-spec decision from step-01 (a prediction made
before investigation) to a route gate in step-02 that reports three facts
about the finished design: forks, irreversibles, footprint. All clean
routes to a light spec (frontmatter + Intent + Implementation Notes)
implemented in-session; any flag produces the full spec with each fork
recorded as an Open Questions entry.
Open Questions drain at a loop before Checkpoint 1 — the spec cannot be
approved while entries remain; answers are folded into the frozen block.
The checkpoint becomes three-way: approve & continue (in-session,
no-subagent path), approve & stop (ready-for-dev for a later dispatch),
or edit. step-oneshot is repurposed as the light path with an escalation
ramp back to step-02's drain loop when implementation surfaces a fact
the gate did not see.
* feat(build): resolve intent from evidence before asking questions
Step-01 takes the invocation prompt as starting intent and no longer
interviews the user; it only resolves workflow state, loads evidence,
applies the VCS and scope gates, and selects the spec path. Step-02
investigates before any clarification, distinguishes missing evidence
from genuine decisions, and carries decisions into the route gate as
forks. Self-review turns unresolved material gaps into further
investigation or Open Questions entries; the pre-draft clarification
HALT is gone, so the Open Questions drain is the only human decision
boundary. The Build explanation now describes evidence-first intent
resolution and the post-design route gate.
* feat(build): emit conversation paths in a host-clickable form
* fix(build): restore main Checkpoint 1 choices
Drop the letter-coded continue/stop/edit menu and keep the wording already on main.
* fix(build): say the step-02 plan path in plain language
Replace route-gate metaphor with what the agent should actually do.
* refactor(build): merge the step-02 gates and keep forks out of the frozen block
The token check and Open Questions were two prescribed halts in sequence.
Fold them into one gate that must be settled before Checkpoint 1, in any
order, combinable in one message. Also forbid the frozen intent block from
assuming an answer to a question that is still open: a simulated run wrote
the tool-block format into Boundaries while asking whether results belong
in it.
* refactor(build): route on intent gaps instead of forks
A fork covered two different things: a question about what the user wants,
and a design choice the user would never notice. Only the first needs the
human. Name it an intent gap, define it as something the request does not
say and the user would notice in the result, and tell the model to decide
and record everything else itself. Forbid writing an intent gap into the
frozen block as an assumption.
* Rename bmad-checkpoint-preview to bmad-walkthrough
"Checkpoint" said nothing about what the skill does and "preview" was wrong: it is a guided human walkthrough of a change, not a preview. Its siblings bmad-code-review and bmad-review already own "review", so the new name leans on what sets this one apart. "Walk me through this change" was already its trigger phrase.
- Skill folder, SKILL.md name/description, module-help.csv (menu code CK -> WT), marketplace.json
- Trigger words are now "walkthrough", "walk me through this change", "human review"; "checkpoint" is dropped
- English how-to page moves to docs/build/walk-through-a-change.md; build-a-change link updated
- fr, vi-vn, zh-cn pages move to docs/<lang>/build/walk-through-a-change.md to mirror the English path; explanation sidebar orders renumbered to close the gap
- Redirects for the old English and localized routes; sidebar label and translations updated
- Diagram assets renamed (image contents unchanged)
* Regenerate walkthrough diagrams with the new title
Title reads Walkthrough and the input box reads bmad-build spec file (was quick-dev, stale since the Build rename). English and French, same layout and style as before.
* Add bmad-checkpoint-preview forwarding shim
Forwards to bmad-walkthrough and offers to migrate legacy _bmad/custom/bmad-checkpoint-preview{,.user}.toml files, same as the other v6 shims.
* Point test-completed-work links at the renamed walkthrough page
Replace the Testing Options catalog with a decision-oriented completed-work
guide at /build/test-completed-work/. Redirect /reference/testing/, list the
page in the Build sidebar after Checkpoint a Change, and close the Reference
sidebar-order gap. Claims are grounded in bmad-qa-generate-e2e-tests; TEA
workflow catalogs stay on the TEA site.
* docs: create Review a Completed Change page
Turn Checkpoint Preview into the Build-chapter how-to for
bmad-checkpoint-preview and redirect the old English route.
* docs: retitle checkpoint how-to as Checkpoint a Change
The Review a Completed Change title collided with bmad-code-review and
the review step in bmad-build. Name the page after the skill and say it
does not replace those reviews.
* docs: update review link format in checkpoint-a-change.md
* docs: create Build a Change page and retire Quick Fixes and Build
Consolidate how-to/quick-fixes and explanation/build into the canonical
build/build-a-change page, opening with the sizing model and Where Build
Fits table and preserving the Build diagram and intent examples. Add the
Build sidebar group after Start, redirect both old routes, retarget
first-party English links and the llms.txt entry, and close the resulting
sidebar-order gaps.
* fix(docs): track Build a Change page by scoping Astro build ignore
The bare build/ gitignore rule also matched docs/build/, so the new
canonical page never entered the prior commit.
* docs: rewrite Build a Change page in plain English
Name the skill as bmad-build instead of Build, drop the duplicated
routing tables, and explain why it spends human attention on a few
checkpoints instead of a Continue slog.
* docs: make the landing page route readers by task
* docs: frame the landing page as think then build
The first pass routed by task but still treated bmad-build as the product.
Name both skill groups, send first-time readers to Getting Started, and
split spec work from the longer planning path.
* Update docs/index.md
Co-authored-by: greptile-apps[bot] <165735046+greptile-apps[bot]@users.noreply.github.com>
---------
Co-authored-by: greptile-apps[bot] <165735046+greptile-apps[bot]@users.noreply.github.com>
The Mayakovsky-style envoi at the end of get-answers-about-bmad was
written as indented lines in one paragraph, so every renderer collapsed
it: the leading spaces were dropped and the lines were soft-wrapped into
running prose glued onto the GitHub Issues link above it.
Use hard line breaks and em-space entities so the staircase survives
Markdown rendering and Prettier, and put a blank line back between the
link and the poem. Same fix applied to the fr and zh-cn translations.
* chore: default persistent_facts to an empty array
Every customize.toml shipped with a skill seeded persistent_facts with
file:{project-root}/**/project-context.md. That made project-context an
opt-out default rather than an opt-in customization. Ship the arrays empty
so nothing is loaded unless the user adds it.
* docs: correct the persistent_facts default in comments and docs
Comments and docs still described project-context.md as loading by default.
They were wrong twice over: the array now ships empty, and bmad-project-context
no longer produces a project-context.md at all — it writes a verified block into
AGENTS.md and treats project-context.md as a legacy artifact.
Replace those claims with the actual model: repo-wide context belongs in
AGENTS.md, which every skill already sees; persistent_facts carries context only
one skill needs, loaded on demand instead of as constant memory. Each site shows
the file: entry users can add to opt back in.
* feat(installer): ask about shims during Quick Update
Quick Update returned before the shim prompt, so anyone who only ever
runs it carried their compatibility shims forward release after release
without once being offered the chance to drop them.
Quick Update now asks, defaulting to keeping the shims so pressing enter
never removes a skill in active use. It stays quiet for an installation
that already dropped its shims rather than re-asking every update. The
prompt carries the recommendation to remove them and names the one case
that justifies keeping them: a customized shim not yet migrated.
Whenever an install retains shims, it now lists every one of them and
what it forwards to. That notice is emitted where the policy is resolved
rather than at the prompt, so it also reaches the paths that never
prompt: --yes, --shims, and scripted quick updates.
* fix(installer): never prompt for shims without a TTY, and report removal
Two gaps in the Quick Update shim prompt.
The prompt could be reached by a scripted run. `--action quick-update`
is a documented scripting flag and is not tied to `--yes`, so a headless
invocation on an install that still had shims fell through to a confirm.
clack's confirm never resolves without a TTY: the process drained its
event loop and exited silently, mid-install, with status 0. It now keeps
the standing answer whenever stdin is not a TTY, leaving --shims and
--no-shims as the way to change it from a script.
Removing shims was also completely silent. Source filtering just skips
the directories, and the IDE cleanup that deletes the stale skill dirs
suppresses its logging on purpose, so nothing anywhere told the user
that a skill they may still invoke had just gone. Any run that removes
shims now lists them and says how to put them back, mirroring the
retained notice. Between the two, every run that has shims either way
reports which way it went, on interactive and headless paths alike.
* feat(installer): carry the shim outcome into the final summary
Both shim notices print before the install tasks start, so a long run
buries them well above the fold. The summary box already repeats the uv
warning for exactly this reason; the shim outcome now rides along the
same way, as a single line next to the preserved/backed-up file counts.
Retained reads "Deprecated shim skills retained: N (re-run to remove
them)" in yellow, removed reads "Deprecated shim skills removed: N" in
green, and an install with no shims either way adds no line at all.
* fix(installer): say what an empty module selection installs
The official module picker allows an empty selection on purpose: core is
always installed and is not a row in the list, so selecting nothing is a
valid core-only install. The prompt did not say so, and collapsed to a
bare "0 items selected", which reads as though the install is about to
do nothing.
autocompleteMultiselect takes an optional emptyLabel, shown while
selecting as "Nothing selected: installs core only" and on submit as
"0 items selected (core only)". Pickers that pass no emptyLabel are
unchanged. Also fixes the count to say "1 item" rather than "1 items".
* refactor(installer): trim explanatory comments to what the code cannot say
Cuts 35 comment lines added across this branch down to seven, keeping
only the non-obvious constraints: clack's confirm hanging without a TTY,
core not being a row in the module picker, and why the shim notices are
emitted where they are.
* fix(installer): report shims removed after they are retired from source
Removal reporting was derived from the shims the incoming release ships,
so a shim retired from source fell out of the report entirely: it was
absent from discovery, yet the update cleanup still deleted its installed
target using the previous manifest. The v7 cut is exactly that case, and
it would have removed every shim in silence.
Removal is now derived from what is installed, read back from
skill-manifest.csv, and the retained/removed split moves into
selectShimOutcome. This also covers the mixed run where one shim is
retired while the rest stay enabled: both notices fire, and the summary
carries both counts. The recovery line no longer offers --shims when the
release cannot reinstall them.
Raised by greptile and coderabbit on #2746.
* feat(project-context): adopt handwritten instructions via a ledger
A non-empty instruction file without a managed block now routes to a
new adopt intent — the migration form of refresh — never to setup.
Every existing instruction enters a retention ledger (retain, rewrite,
relocate, automate, delete) presented in full before anything is
written; a deletion needs one of four grounds, and one without hard
grounds is held for line-item approval that block approval never
grants.
Best practices replace the derivability test with a retrieval-cost
test, admit compact architecture and toolchain pins, and gate nested
AGENTS.md files on loading verified for every harness in use, falling
back to path-qualified root lines. The explanation and how-to docs
follow the same reframing.
* fix(project-context): scope splice preservation to the block itself
Step 5's byte-identical clause read as forbidding any change outside
the markers, which contradicted the ledger's approved rewrites,
relocations, and deletions of handwritten instructions there. The
splice still touches nothing outside the markers; outside text changes
only through a settled ledger entry or a proposed fix the user has
seen.
Also from review: the how-to routing sentence now distinguishes adopt
from refresh, template section 4 includes pyproject.toml, and the
theory doc qualifies the source-recovery claim to implementation
behavior.
* docs(project-context): plain-language pass on how-to and explanation
The reader-facing pages had absorbed the skill's internal vocabulary
— the disposition taxonomy, approval tiers, harness loading mechanics
— and metaphors that mean nothing to a casual reader. Replace them
with the user-level promise: you see what happens to every existing
instruction before anything is written, and nothing is deleted
without your sign-off. The theory page keeps its technical depth by
design.
* docs(project-context): drop behavior sentence from skill description
The description is a routing trigger; the adopt verb already carries
the cue, and the preservation behavior is documented where it runs.
* refactor(project-context): move intent-conflict rule from Args to detection
The Args line declares the interface; the guard against silently
obeying a supplied intent that contradicts the detected state belongs
in step 4, where detection happens.
* docs(project-context): trim Args platitude, mark conflict case as example
* docs(project-context): replace canonical/toolchain-pin jargon with plain terms
Right commands to use, required tool versions, cross-component rules
- same meaning, readable by anyone.
* docs(project-context): plain-language the cross-component admission rule
* docs(project-context): rewrite the adopted-content budget paragraph readably
The installer told users uv was optional while bmad-build had already made
it mandatory. uv-check.js called it "becoming the de facto standard",
install-messages.yaml led with HEADS UP, and installer.js printed a Tip
inside a box titled "BMAD is ready to use!" — while bmad-build and
bmad-build-auto HALT on activation without `uv run`. The probe's result
was discarded (`await checkUvEnvironment();`), so nothing branched on it.
Messaging now names the consequence, and the post-install summary repeats
the warning when it applies — the pre-install probe fires before every
prompt, so by then it is far up the scrollback. Still warn-don't-block:
core-only, docs-only, and CI installs never render a skill, so a missing
uv must not fail the run.
Adds a python3 probe used only when uv is absent, since that is the only
case where the interpreter on PATH matters. It reports whether the
direct-interpreter skills still work (3.11+) or nothing Python-backed will
(below 3.11, or no python3 at all).
Separately, 25 call sites still ran resolve_customization.py under a bare
`python3`. That script requires 3.11+ for tomllib, so on macOS without
Homebrew or Ubuntu 22.04 they fell through to their "if the script fails"
path and hand-merged the TOML in-context — no error surfaced. All 25 now
use `uv run`, which provisions a matching interpreter from the script's
own requires-python.
Four more spawned Python purely to open an HTML file:
python3 -c "import webbrowser, pathlib; webbrowser.open(...)"
Replaced with the platform opener bmad-brainstorming already uses — open /
xdg-open / start. src/ now contains no bare Python invocation at all, so
"Python 3.11+" leaves the user contract: uv provisions its own.
docs/how-to/customize-bmad.md described a transition that this ends.
Test suite 46 grows from 12 to 29 assertions: Python parsing, the 3.11
boundary in both directions, that uv-present skips the python3 probe, and
all three missing-uv sub-branches.
* feat(project-context): rewrite as prescriptive AGENTS.md generator
Replace the kernel+bundle context system with a single product: a short
verified agent guide (AGENTS.md). A field trial of the first version showed
repo scanning produces polished-but-useless factoids; the rewrite fills a
fixed section plan from ranked evidence channels (executable config and CI,
targeted git history, session logs, human interview) and uses the repository
only to verify claims, never as the source of knowledge.
- Intents: bootstrap, refresh, record (capture an observed agent mistake),
audit; query is gone with the bundle
- Per-fact entry files, trust frontmatter, index, placement machinery, and
the skill's context.py mechanics script are removed; accountability moves
to one plain ledger file recording every candidate claim and its
disposition
- Skill directory only; docs, forwarding husks, and shared scripts untouched
* refactor(project-context): per-section admission rules, two-tier guide
Revisions from two end-to-end trials plus review:
- Replace the global non-derivable test with per-section admission rules:
brevity (orientation), authority (policy), universal need verified by
execution (commands, verification), wrong-default-assumption (conventions),
localization value (pointers), observed failure only (pitfalls)
- Two-tier output: AGENTS.md (orientation + policy + pointer) for every
session, AGENTS-dev.md for coding sessions; single file when tiny
- Pitfalls can never be nominated by scans: sources are recorded lessons,
maintainer recall, session evidence, and the writing session's own caught
mistakes; retirement only when the guarded thing is gone or the human says
so, since a working rule erases its own evidence
- Interview ergonomics: recall questions, never review lists; testimony the
repo contradicts is surfaced with evidence, never written or dropped
- Trial-driven fixes: guide-to-filesystem link check, mutating-command
go-ahead as the interview's first question, plain-English rewrite
throughout
* fix(project-context): bidirectional coverage trace, history-evidenced pitfalls
Round-3 trial findings: an unsourced pitfall entered the guide at
composition time because coverage only checked ledger-to-guide; and
repeat-fix git history, the strongest pitfall evidence observed, was
not an explicitly admitted source.
* refactor(project-context): move Where-things-are to AGENTS.md, imperative lines
Where-things-are pointers serve planning sessions as much as coding
ones, so they belong in the always-loaded file. Shape rules now require
every line to state an action (bare facts only as justification clauses)
and stable contract headings across runs.
* docs(project-context): session-kind guides as a third structural axis
A maintainer-named frequent session kind (UX, manual testing, data
work) may earn its own AGENTS-<kind>.md behind a pointer; module-level
differences stay with scoped guides.
* refactor(project-context): action-gated dev-guide pointer, two-file example
The AGENTS-dev.md hop is the most common progressive-discovery trigger,
so it is now gated on the first hands-on action rather than session
self-classification, names its payoff, and names the exemption. The
contract's worked example shows the two-file form with the pointer in
situ. Scoped-guide discovery no longer assumes harness nearest-file
loading: the root-guide pointer is the mechanism.
* refactor(project-context): adopt shared memlog, drop unearned claims
The run record is now a standard memlog kept with the shared
memlog.py script — append-only typed entries, latest entry wins —
replacing the bespoke ledger format; stale-disposition notes become
structurally impossible. Two appeal-to-measurement assertions cut:
the operative admission and exclusion rules carry that load.
* docs(project-context): guard handwritten guides
The skill never commits — its output stays as working-tree changes for
the user. Headless runs never rewrite a guide the memlog doesn't record
writing; they leave an AGENTS.md.proposed for an interactive merge.
* docs(project-context): fold in prior-art research findings
Five adoptions from the generator prior-art survey: prohibitions name
their permitted alternative; an emphasis-marker budget; a
git-log --diff-filter=DR drift check on refresh; TODO placeholders over
guessed greenfield commands; commit and branch conventions mined from
history.
* docs(project-context): route candidates to enforcement before prose
Compose now asks, per accepted candidate, whether a hook, lint rule, or
CI check enforces it better than a guide line; the line is the fallback
and a landed check deletes it.
* docs(project-context): narrow refresh interview and contradiction flagging
Refresh interviews shrink to one recall question — what changed since the
last run. Cross-file contradictions are flagged only when they change
behavior; rewording and overlap are not contradictions.
* refactor(project-context): conversational skill, no script, AGENTS.md block
Refine the skill into an implementation-layer capability: a conversation that
produces one small verified block inside the repo's AGENTS.md. The human is in
the loop for every write; there is no autonomous mode.
- Drop src/scripts/context.py and its tests. Nothing it did is needed once the
output is a single spliced block rather than a bundle of files.
- Replace guide-contract.md and evidence.md with best-practices.md (admission,
exclusion, retirement, retrieval, maintenance) and template.md (section list
plus a worked example, no placeholders).
- Collapse the two-file AGENTS.md/AGENTS-dev.md split into one block. A pointer
the agent must choose to follow gets skipped; anything load-bearing goes in
the always-loaded file.
- Replace per-section admission rules with one test: anything derivable from
source is read live, never stored. Commands stated in package.json, a
Makefile, or CI config no longer earn a line; their caveats do.
- Ask up front whether a run covers the root only or named sub-projects, gated
on observable evidence (a workspace manifest, per-directory build manifests).
- Husk bmad-document-project and bmad-generate-project-context onto setup
intent, and say plainly that the deeper system-explanation altitude is a
separate capability rather than shipping a thin substitute.
- Align module-help.csv, bmad-correct-course, the analyst menu, and the docs
set with the block as the output.
---------
Co-authored-by: Alex Verkhovsky <alexey.verkhovsky@gmail.com>
The page is no longer needed. Drop it and its localized copies (cs,
fr, vi-vn, zh-cn), and de-link the remaining references in
forge-idea.md and the zh-cn advanced-elicitation/build pages. Drop a
stale line from lens-adversarial.md left over from the prompt slim.
Also drop a renderer test assertion that could never fail: it checked
that a deleted file wasn't in the snapshot, but the file no longer
exists anywhere in src/, so nothing could put it there.
* Add bmad-project-context skill; husk document-project and generate-project-context
- New bmad-project-context: one engine, three intents (ingest/query/audit)
building a verified kernel + bundle context system; interactive default,
auto/headless mode; works with a BMad install or standalone via bootstrap
- context.py core runtime script (validate/index/map/sweep/resolve/compass/
sync/bootstrap/config) with 52 tests; config resolution delegates to the
installed BMad resolver so script and session never disagree
- bmad-document-project and bmad-generate-project-context reduced to
10-line deprecation shims forwarding to the new skill
- Docs updated: project-context explanation/how-to rewritten, established
projects guide + FAQ, agents references, workflow map; deprecation notes
kept for old-name searches
- module-help.csv single PC row; analyst menu DP -> PC
- validate-file-refs: context.yaml is runtime-generated
* refactor: remove map command from context.py — discovery is the model's job
Real-repo testing showed map's descriptor pass grinding through large
asset trees. Discovery is judgment work the model does better with its
own tools; the script keeps only measurement, mutation, and resolution
(validate/index/sweep/resolve/compass/sync/bootstrap/config). SKILL.md
brownfield flow de-prescribed to outcome-driven wording; added a
bounding-question rule for huge external sources.
* feat: closing message when the harness may not load AGENTS.md
43+ harnesses make per-harness load verification impractical. Whenever
AGENTS.md carries the kernel, the run now closes by telling the user:
if your harness doesn't auto-load AGENTS.md, make the context file it
does load pull this one in (e.g. a CLAUDE.md containing @AGENTS.md).
Found in real-repo testing: the kernel sat unloaded under Claude Code
until a CLAUDE.md pointer was hand-made.
* docs: add The Theory of Project Context explanation
Why the skill captures so little: the evidence against generated docs,
the pruning test and what earns a place, the deliberate exclusions with
their reasons, context-as-liability, and an honest comparison with the
two replaced skills.
* fix: address PR review findings
- Force-add eval fixture files the repo gitignore silently dropped
(pnpm-lock.yaml, _bmad/context.yaml, context/.memlog.md)
- docs/reference/agents.md Analyst row: DP/Document Project -> PC/Project Context
- context.py: cmd_index no longer crashes on an empty index.md (and
allows overwriting one); inline # comments in frontmatter values are
only stripped when preceded by whitespace (C#-style values survive);
cache_lookup tolerates corrupt pointer files; pointer writes are atomic
- triggers.json: positive trigger for the query intent
* refactor(review): slim adversarial hunter prompt across build and review skills
Drop cynical-persona framing. Inline a short review prompt (≥10 findings,
look for missing, empty/zero guards) into blind-hunter layer instructions for
bmad-build, bmad-build-auto, and bmad-code-review. Delete the old
review-prompts/adversarial.md files. Align offline no-subagent dump with the
same child prompt. Update bmad-review's adversarial lens to the same method
while keeping its canonical finding fields.
* test(renderer): stop requiring deleted adversarial.md prompt file
Blind hunter is inlined; assert the inlined prompt text and remaining
file-backed review prompts instead.
* docs: align adversarial review explanation with slim hunter prompt
Document the finding floor and missing-not-only-wrong method instead of
the old cynical persona. Update core-tools lens table and localized pages.
The field recorded a commit id inside a file that had to be committed,
so Finalize took a second commit carrying nothing but one frontmatter
line. Nothing read the field.
Finalize now sets status: done before the run's commit and includes the
spec in it, then verifies the working copy is clean. A story's range end
is the next story's baseline in stories.yaml list order.
* refactor(bmm): move sprint-planning and sprint-status to plan/
They sit at the plan/ship boundary and their outputs are planning
artifacts of the dev cycle; next commit makes sprint-planning the
readiness gate, which is plan-side work.
* refactor(bmm): fold readiness gate into sprint-planning, retire check-implementation-readiness
The old skill was 1,154 lines of legacy numbered-step ceremony whose
document discovery hardcoded filename globs (*prd*, *ux*, *epic*) that
miss what current skills produce (SPEC.md, DESIGN.md) and still treated
retired sharded docs as first-class. Sprint-planning now opens with a
lean readiness gate: generic artifact discovery by content, forward/back
traceability, PASS/CONCERNS/FAIL, stop on FAIL with findings. The IR
trigger on John's and Winston's menus dispatches sprint-planning, so
'check implementation readiness' still works everywhere it used to.
* refactor(bmm): modernize sprint-planning with deterministic script core
SKILL.md drops the legacy XML step dialect for the product-brief style
(~100 lines, uv run, headless contract). New scripts/sprint_plan.py owns
the mechanical work — epic parsing, key derivation, ordering, preserve-
never-downgrade merge, story-file detection, action_items carry-over,
atomic writes, drift checks — with 11 tests wired in as
test:sprint-planning. Judgment stays with the LLM: epic discovery, the
readiness gate, and reconciling script-reported orphans and unparsed
headings. checklist.md retired (the script performs that checklist);
sprint-status-template.yaml is the single source for the status
vocabulary. Output stays byte-compatible with build's sprint sync and
retrospective's tooling.
* refactor(bmm): fold sprint-status into sprint-planning's status view
sprint_plan.py gains a status subcommand: counts (legacy values mapped),
risk flags, open action items, and a priority-ordered next-action
recommendation — the old skill's inference-driven summary, computed
deterministically and covered by 9 new tests. bmad-sprint-status becomes
a v6-shims husk that forwards with status-view intent and a deprecation
notice; its dead data/validate modes had zero callers and are gone. If
a hand-edited status file defeats the script, the skill falls back to
reading it directly and summarizing by best judgment. New explanation
page docs/explanation/sprint-planning.md covers the consolidated skill;
workflow maps and references updated across all languages.
* docs: changelog entries for skill reorg and sprint consolidation
* fix(bmm): harden sprint_plan.py per review; add validate/fix intents with full progressive disclosure
Review fixes (PR #2659 findings, bot + internal review):
- Normalize legacy v6 statuses (drafted/contexted) on every read — merged by
meaning and reported, never treated as illegal or reset
- dropped_orphans carry their old status; transplant renames via --set
- project_key/tracking_system/story_location preserved from the existing file
unless overridden; refresh round-trips custom keys and user comments
- Hardened write path: dump-to-bytes, fsync, permission-preserving atomic
write inside the guarded block, explicit checks (no asserts), atomic restore
- JSON-only argparse (errors and -h emit JSON); unicode-aware slugs with hash
fallback; fenced code blocks ignored when parsing epics
- Odd retro keys, date-typed stamps, and non-mapping YAML report cleanly
instead of crashing; unparseable timestamps warn instead of silently
disabling the staleness check; malformed action items flagged, not dropped
- Dead check subcommand removed; generate --dry-run reports drift/in_sync
- test:sprint-planning wired into quality and CI (was test-only)
- Retro tests use a vendored template fixture (PATH-05); repo-level
test-template-sync.js keeps it byte-identical to the source; template
example timestamps and story_location fixed; header block pinned to the
template by test
New capability:
- validate subcommand + reference: structural validation, never writes
- fix flow: evidence-gathering subagents -> user-confirmed state table ->
generate --fresh --set writes a pristine file (the one path allowed to
downgrade); universal script-failure fallback to inference for every intent
- SKILL.md is now a lean router: gate, tracking, status, fix, and validate
each load as progressive-disclosure references
Docs: explanation page gains Repair section; workflow-map and getting-started
across all five languages mention the status view; headless payload nests
under 'report' to avoid the status key collision; changelog updated.
Test suite grows 20 -> 37; retro suite 91/91; docs build and validators green.
* docs: mention repair in sprint-planning explanation description
* refactor(bmm): move agent skills into agents/
* refactor(bmm): collapse phase folders into planning/ and shipping/
Skills reorganize from numbered pipeline folders (1-analysis,
2-plan-workflows, 3-solutioning, 4-implementation) into two sets:
planning/ and shipping/. Path and phase-label references updated
across marketplace.json, module-help.csv, tests, and bmad-help;
also trues up two marketplace paths that were stale on main
(create-story/dev-story already lived in v6-shims).
* refactor(bmm): shorten skill folders to plan/ and ship/
* refactor(bmm): retire tech-writer agent (Paige on hiatus)
Paige's capabilities were generic LLM defaults with no domain substance;
her one real menu item (DP) dispatches bmad-document-project, which stays
directly invocable and remains on the Analyst menu. Added to removals.txt
so installs clean up, and docs (all languages) carry a hiatus notice —
she returns in the future far more capable.
* feat(bmm): rework bmad-retrospective as an evidence-based epic review
Replace the persona-meeting simulation with an evidence engine that mines
what a completed epic actually left behind — spec, full diff, per-story
commits, sprint status, and session logs — instead of simulating a team
that "remembers." Every finding carries a source reference.
- Five-phase flow: Gather -> Analyze -> Decide -> Close. Analyze derives
aggregate views (architecture delta, duplication, god-class growth,
pattern divergence, spec reconciliation) and reuses bmad-review for the
diff-scope code lenses rather than reimplementing them.
- Acceptance verdict (accepted / accepted-with-open-items / rejected); a
failing epic can never close as silently accepted.
- Team discussion is now opt-in and off by default, delegating to
bmad-party-mode seeded with the real findings.
- Add deterministic scripts: sprint_status.py (epic detection plus a
comment-preserving, force-quoting, validate-and-restore sprint-status.yaml
update) and git_evidence.py (range / commit / size-trajectory
measurement), with a pytest suite.
- The retrospective document is the working artifact: built early, filled
per phase, and resumable. Adds a headless mode (-H) with assumption
capture.
- SKILL.md drops from ~1527 lines to a lean spine plus five references.
* fix(bmm): harden retrospective scripts for orchestrator use
Address review feedback on the evidence-based retrospective (PR #2612) from
CodeRabbit and the bmad-loop maintainer. All changes are additive — no existing
JSON field or CLI argument that a consumer reads is renamed or removed.
- detect-epic: STORY_RE now matches split-story keys (2-6a-...), aligning with
bmad-loop's sprint-status detection; previously such an epic was invisible and
a headless run could retro the wrong epic.
- sprint_status/git_evidence: argparse failures now emit JSON on the documented
stdout contract instead of plain usage text.
- sprint_status: guard non-list action_items (clean JSON error, no traceback);
_restore reports success/failure so a failed rollback is surfaced, not hidden.
- action_items entries carry a stable id and a ref to the retro document, so an
orchestrator can dedupe across re-runs and dispatch each sourced finding.
- update echoes the acceptance verdict in its JSON; the retro key value stays
"done" for existing lifecycle consumers. Retro doc gains machine-readable
frontmatter, and -H <epic> is documented as the stable automation interface.
- evidence-gathering: derived range now includes the first story commit
(<first>^..<last>); aggregate-views drops the size/acceleration overclaim.
- Tests: split-story detection, non-list guard, restore reporting, argparse
JSON, and id/ref/verdict coverage (13 pass).
* docs(bmm): refine retrospective party-mode phrasing
* docs(bmm): document the reworked retrospective
- Add docs/explanation/retrospective.md — a short feature page: what the
skill does, why to run it after an epic, and what to do with its output
(retro document, action items, acceptance verdict).
- Update the workflow-map retrospective row to reflect the evidence-based
review and its actual outputs instead of "Lessons learned."
* fix(bmm): validate git_evidence --range as a strict revision range
An unvalidated --range reached the git argv unchanged: a value starting
with "-" was consumed by git as an option, a single rev logged all
history up to it, an existing path was consumed as a pathspec, and a
file named like a range (a..b) was silently logged as one — each
returning a confident, wrong evidence set with exit 0. Reject anything
that is not an explicit REV..REV form — including empty endpoints
("..", "a..", "..b"), which git silently defaults to HEAD, and
unstripped values — and terminate the git argv with "--" so a
range-shaped name is always parsed as revisions, never as a pathspec.
Drop the root-commit special case from evidence-gathering.md: its
wording steered into a bare-rev invocation now rejected, the scenario
(an epic starting at the repository's first commit) is vanishingly
rare, and an agent that ever meets it can still construct a shape-valid
range itself. Document the exit-code split (2 invalid args, 1 git
failure). Every rejected mode is covered by regression tests; git
error-string assertions are pinned to LC_ALL=C.
* fix(bmm): harden sprint_status.py input validation and atomic writes
Nine findings from the PR #2612 review of the reworked retrospective, all
reproduced against the previous behavior:
- Pin the emitter indentation so a round-trip stops de-indenting
pre-existing, untouched action_items; the sprint-status template now
survives an update byte-identical apart from last_updated.
- Keep malformed input on the documented JSON-to-stdout contract instead
of a traceback: shape-check the root document and development_status on
both subcommands, widen the file open from FileNotFoundError to
OSError, and report invalid UTF-8 as a JSON error. A non-mapping
development_status previously reported ok:true while doing nothing.
- Validate comment preservation against the whole file's comment lines
rather than only the leading block matched by substring, so a lost
mid-file comment fails the write and restores.
- Write atomically through a temp file, fsync and os.replace, resolving
symlinks and carrying the target's mode across. The rollback goes
through the same path: a truncating rewrite that died halfway used to
destroy the bytes it was restoring.
- Stop inserting an empty development_status mapping, and report
retro_key_found: null when --set-retro-done was not passed, reserving
true/false for "flag passed, key present/absent".
- Include restored:true on every update failure that precedes the write.
- Make _slugify Unicode-aware with a content-hash fallback, so non-Latin
action text no longer collapses to the literal "item".
- Reject an --add-action item whose action is empty or not a string.
- Validate --date against MM-DD-YYYY HH:MM and normalize it, since
strptime otherwise admits unpadded spellings.
Each fix is pinned by a subprocess-level regression test; the suite goes
from 18 to 49 tests.
* feat(bmm): add action-item status updates to sprint_status.py
The update subcommand could only append, and retro-document.md forbids
hand-editing sprint-status.yaml, so nothing anywhere could move an action
item off open. bmad-sprint-status renders every open and in-progress item
on every call, so retrospectives accumulated permanently-open noise.
Add --set-action-status, taking a JSON array of transitions for items
already in the file. Each entry selects one item by id, or by epic plus
exact action text for legacy entries written before ids existed, and gives
it one of open, in-progress, done. Selectors resolve against action_items
as loaded and strictly before the --add-action append, so an item added in
the same run is not addressable in that run. Validation is all-or-nothing
and entirely pre-write: a selector matching nothing, matching more than
one item, colliding with another entry, or carrying a status outside the
vocabulary aborts the whole invocation with restored: true and the file
byte-identical. After the write the file is re-parsed and every targeted
item is confirmed to carry its new status. Success reports the new
action_items_updated count.
Rewrite the contradicting paragraph in retro-document.md so the flag is
the one sanctioned path to change a status: offer the transitions when
the Phase 4 follow-through has evidence an item landed, apply only what
the user confirmed, and never touch prior statuses in a headless run.
* fix(bmm): measure renames, merges, and binary churn in git_evidence
Five ways the measurement was quietly wrong:
- Renames emitted an unopenable "src/{a => b}" pseudo-path and split one
file's churn across up to three keys; non-ASCII paths arrived octal
escaped. Both passes now run with core.quotePath=false and
--no-renames, so a rename is an honest delete + add and a path is a
real string that opens.
- Merge commits emit no numstat rows, so cross-story conflict-resolution
churn vanished with nothing saying it had been skipped. The listing
pass keeps full topology (per-story attribution is unchanged); a
second pass measures merges alone under -m --first-parent
--min-parents=2 and reports merge_files, merge_count and
merges_measured. Merge churn is never folded into files: a merge's
first-parent diff restates the churn of the commits it merged in.
- A commit naming two stories attributed to whichever id was passed
first. Every matching id is now collected, so a seam commit counts for
both stories. commits[].story becomes commits[].stories.
- A git failure with empty stderr reported "error": "". It now falls
back to the exit code.
- One binary revision of a path nulled its added/deleted/net, dropping
real measured text churn from the ranking. The text sums survive and
binary_revisions reports the exposure beside them.
log.diffMerges is pinned to separate on the command line, because a user
config of off makes the merge pass emit no rows at all. Git output is
decoded with surrogateescape rather than replace, so two distinct
non-UTF-8 paths cannot collapse into one key.
evidence-gathering.md documents the changed output. 19 subprocess-level
tests over real git fixture repos cover every case above; the suite goes
81 -> 100.
* feat(bmm): add a pending-stories gate and align the retrospective docs
`detect-epic` now also reports `pending_stories` — the selected epic's
story keys that are not `done`, scoped to that epic alone — and SKILL.md
branches on it before Phase 1: interactively the user is shown the list
and may decline, headless the run proceeds and records the list as an
assumption. An epic supplied on the invocation skips detection, so the
instructions say plainly that the check did not run rather than implying
it did.
Both scripts are built with `add_help=False`. `-h`/`--help` previously
printed argparse's usage text on stdout and exited 0, breaking the
JSON-only stdout contract the scripts sell to their machine consumer;
help is now an ordinary unrecognized argument routed through the
existing JSON error path. SKILL.md also gained the branch for a
`detect-epic` that exits non-zero, which is the normal path for a
stories-mode project with no sprint-status.yaml.
The references are brought back into agreement with what the scripts do
after the last three batches: the close-out invocation quotes its values
and pins the `--date` format that now hard-fails a non-conforming value;
the result JSON documents `retro_key_found: null` and which failures
carry `restored`; the retro key is stated to read `done` even for a
rejected epic, so a verdict-aware gate must read the document
frontmatter; Phase 3 gains an inline fallback when bmad-party-mode is
absent; Phase 4 specifies the previous-retro follow-through record the
close-out consumes; and the god-class view is rewritten for the current
git_evidence keys.
Suite goes from 100 to 111 tests.
* chore(bmm): align retrospective script conventions and test harness
Adopt the invocation convention the quick-dev and dev-auto skills settled
on, and make the git_evidence test fixtures independent of the machine
they run on.
All five documented invocations become `uv run --no-cache`: the shared
cache may be unwritable in a sandbox and may serve a stale build. Both
scripts drop their shebangs entirely — they are only ever launched via
`uv run`, so a shebang and executable bit are a false affordance; the
PEP 723 blocks stay, since that is what uv reads. The encoding audit
that change implies found one implicit site left: `_load_yaml` now pins
the ruamel emitter's encoding, which is what encodes the bytes
`_dump_bytes` writes to the user's file.
`_git` and `_git_unchecked` passed an env of only the four GIT_* identity
vars, so PATH and HOME were wiped and git resolved through os.defpath —
the fixtures ran a different binary than the script under test, and
failed outright wherever git lives only in /opt/homebrew, /usr/local or
a nix store. Both now share a `_git_env` that inherits the environment,
strips ambient GIT_* vars that would redirect or reconfigure the fixture,
and pins identity, both gitconfig sources, gitattributes and the locale.
`_run` parsed stdout bare, so a crash surfaced as JSONDecodeError with
the real traceback hidden in the discarded stderr; it now routes through
the `_json` guard the rest of the file already used. Both test files gain
the repo's established runner footer and the PEP 723 header that makes it
self-bootstrap under `uv run <file>`.
No test's assertions change; the suite holds at 111 passing, and passes
under a gitconfig setting commit.gpgsign, core.autocrlf, core.hooksPath
and init.defaultBranch against it.
* feat(bmm): aim detect-epic at a supplied epic and reject unfinished ones
Unattended retros need the unfinished-story gate on the orchestrator path
and a hard machine verdict when delivery is incomplete.
detect-epic gains optional --epic N so -H <epic> can request the same
pending_stories list auto-detect already returns for its picked epic.
Non-positive values fail as JSON (exit 1). The skill now always runs
detect-epic for a supplied epic with that flag, and the acceptance
rubric forces rejected when pending_stories is non-empty — headless
included; interactive humans may still override.
Suite 111 → 115.
* fix(bmm): harden retrospective script contracts after re-review
- reject three-dot --range values in git_evidence.py: A...B passed the
guard and silently measured a symmetric difference
- move the directory fsync in _atomic_write past the failure path so a
post-rename fsync error can no longer report "restored": true about a
write that landed
- validate --verdict against the frontmatter vocabulary and spell
accepted-with-open-items one way across every machine-read surface
- emit story_count from detect-epic so a typo'd epic number is
distinguishable from a finished epic, and teach the SKILL gate to
treat 0 as suspect
- align the dev agent's ER menu description with the reworked skill
* fix(bmm): reject typed retrospective statuses
* docs: fix retrospective sidebar order
* ci(bmm): run retrospective Python tests
* fix(bmm): harden retrospective script execution
Reject non-positive epic numbers before update processing.
Keep explicit repositories authoritative when invoked from Git hooks.
* docs(bmm): rewrite retrospective skill prose in plain language
Remove invented metaphor and jargon from the skill's prompt surface
(SKILL.md and references): witnesses/interrogates, testimony, seams,
close-out, mining, and similar phrasing are replaced with plain
equivalents. Rename Phase 5 "Close" to "Finalize" and the "Honest
degradation" section to "Missing evidence", syncing cross-references.
Industry-standard terms (god-class, churn) and BMAD vocabulary
(declared/profiled, party mode) are kept. No operational rule,
script contract, or verdict vocabulary changes.
* docs(bmm): refine retrospective prose
---------
Co-authored-by: Alex Verkhovsky <alexey.verkhovsky@gmail.com>
Rewrite published documentation and maintained translations around variable
planning depth with one Phase 4 implementation loop. Update diagrams and AI
indexes, and reject obsolete workflow terminology in deployable output.
* feat(bmm): promote quick-dev to the official Phase 4 loop
- module-help.csv: bmad-quick-dev becomes the required Phase 4 item
(sprint-planning -> quick-dev -> code-review); the deprecated
create-story/dev-story rows leave the catalog; code-review and
qa-generate-e2e-tests chain after quick-dev.
- Dev agent menu drops its DS/CS entries.
- Docs and skill recommendations point at bmad-quick-dev instead of the
legacy split (architecture, ux, sprint-status, sprint-planning,
retrospective, named-agents, project-context,
expand-bmad-for-your-org, commands, workflow-map, getting-started).
The legacy skills themselves are untouched; deprecating them in place
is a follow-up PR.
- Quick-dev's user-facing descriptions (commands, workflow-map,
getting-started, help catalog, dev menu) drop the interactive-session
phrasing ("canonical implementation loop") for plain documentation
wording.
- bmad-retrospective: story-record scan also matches
spec-{epic}-{story}-*.md and quick-dev's section names, so retros see
quick-dev output.
- bmad-quick-dev: preserve an existing baseline_commit on resumed runs
instead of overwriting it with current HEAD.
* fix(bmm): address quick-dev review findings
Record deferred review findings only in spec frontmatter and remove the
deferred-work output. Make updates safe for legacy specs and YAML-special
content, strengthen contract coverage, and synchronize the reference docs.
Alex Verkhovsky