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.
Replace the flat "find at least ten issues" with a floor the hunter
computes from the content it already reads: N = min(floor(sqrt(kB) + 1),
10) over the staged diff's size (the oneshot layer computes it from the
changed content's size), stating the arithmetic in one line so the floor
is auditable. The flat ten over-asks small diffs — a 2 kB change owes 3
findings, not 10 — and the cap keeps today's demand on large diffs,
where the constant already binds.
Benchmarked as an isolated-hunter A/B on a three-commit size ladder
(1.65/10.1/30.4 kB, 3 runs per arm per commit): the scaled floor
self-computes correctly in 9/9 runs, cuts hunter volume ~40% and cost
16-31% at the two lower tiers, keeps every Minor-or-worse finding at
those tiers (union recall loss is Nit-tier only), and matches the flat
quota at the cap.
The adversarial lens in the core bmad-review skill keeps its flat floor;
it reviews arbitrary content where a byte-size denominator is untested.
The catalog had drifted from the code it describes. Corrections, each
verified against src/ and src/scripts/:
- REF-01 cited a `config.yaml` config source. The central config is
`_bmad/config.toml` plus its user/custom overlays (config_utils.py).
- REF-01's double-curly exception was stated for all `{{...}}`, which
contradicted TPL-01. The two forms differ: plain `{{name}}` is an
artifact placeholder that survives rendering, while dotted `{{.key}}`
and `{{config.key}}` are compile-time substitutions consumed by
render_skill.py. Split the exception by form.
- PATH-05 told authors to replace cross-skill file paths with
`skill:skill-name`, while REF-03 forbade that prefix. Prose uses
invoke language; `skill:` is the customize.toml value form. Recorded
the split as a REF-03 exception.
- WF-03 governed workflow.md frontmatter variables. Neither of the two
workflow.md files carries frontmatter, and no WF-01/WF-02 exist.
Removed.
- SKILL-04's stated regex rejected the bare name `bmad`, which
validate_skills.py accepts. Matched it to the implementation.
- Replaced dead example paths (`core/data`, `bmm/data`,
`core/workflows`) and `{installed_path}` examples already covered by
PATH-02.
Drop STEP-02 and STEP-03: step goal sections and next-step references
are structure, and the validator no longer takes a position on it.
STEP-04 and STEP-05 stay, being execution safety rather than shape.
Add a Token Forms table and a Skill Layouts section so the token
grammar and the three coexisting step layouts are stated once, and
extend REF-01 to cover `{workflow.key}`, `{agent.key}`, and
`[[bmad-snapshot:]]`. Compile-time tokens are predicated on the skill
actually invoking render_skill.py, which only bmad-build and
bmad-build-auto do.
Details the catalog now states precisely: render_skill.py substitutes
`{workflow.key}` but not `{agent.key}`, whose only source is
resolve_customization.py output; a `[[bmad-snapshot:]]` target must be
a Markdown file other than SKILL.md, which _load_sources excludes;
workflow.md is the renderer's entry point, not a property of any
layout; config keys are declared in module.yaml, which exists in a
checkout, rather than the installed config.toml, which does not; and
`{project-root}` and `{skill-root}` are named as sources so REF-01
does not flag the two most common tokens in the corpus. SKILL-04
claims no character limit, since NAME_REGEX does not bound length and
a passing deterministic rule is skipped by the inference pass.
Drop the Skill Spec Cheatsheet. Its path-resolution notes duplicated
PATH-01 and the rest (loading levels, 500-line tip, discovery
keywords) was read on every run and used by no rule; the intro now
links the specification instead. The How to Use steps no longer
restate the first-pass skip rule, and backslash-escaped backticks
inside code spans are replaced with double-backtick spans so they
render.
Verified across all 50 skills: every `{workflow.*}` and `{agent.*}`
resolves in its own customize.toml, every snapshot target exists, and
no unrendered skill uses a compile-time token.
The verification-gap layer's evidence rules already make it read the
tests and run the searches behind every gap claim, and triage then
re-derived that same evidence from a colder position. Split by claim
type instead: a gap finding is self-certified — the block must stand on
its own evidence and now carries a required disposition (patch naming
the test to add, or defer with why) in place of the optional suggested
test shape — while a claim that code misbehaves is a defect and goes
under Other findings for standard triage, however the layer found it.
Triage in bmad-build, bmad-build-auto, and bmad-code-review takes a gap
finding as pre-verified: skip verification, render the verdict from the
filed evidence, weigh the filed disposition when routing. Other
findings from that layer are verified like everything else.
In A/B forks of a warmed triage session, self-certification held layer
cost flat and cut parent triage from 109K to 77K real tokens with no
recall loss against the judged finding set.
The patch route told the orchestrator to describe each fix to the
step-03 implementation subagent in its own words. Composed fresh every
run, that message drifts: it grows into a lecture, and nothing stops
the subagent from re-running the full verification it was taught in
step-03 — which step-04 then runs again itself.
Now the message is fixed text in the step file, filled in with the
findings. It tells the patcher to make the smallest change that does
the job, run only the tests covering the files it edits, and return —
full verification stays on the orchestrator's side.
Two more sentences on the orchestrator: re-engage means continuing the
same subagent by the name or id its launch returned — a fresh launch is
not re-engagement; and after patching, rewrite the diff file to match
the patched tree, so nothing later in the pass reads a stale diff.
Adapted from #2805 by pbean.
Co-authored-by: pbean <paulbeanjr@gmail.com>
* feat(build): carry forward triage verdicts on re-review
A second look at the same work — a loopback after failed layers, a
follow-up pass on a done spec — makes the review layers re-report the
same findings, and triage pays full price to re-verify each one, then
re-defers items already in the ledger.
Now triage checks each finding against the existing Review Triage Log
first. Same location, same claim, and the code there still reads as the
row describes: the finding keeps the recorded verdict and route, its row
is written again marked carried — no re-verification, no second patch,
no duplicate defer. Anything else is verified as before, and a code
change at the cited spot voids the match.
Applies to bmad-build and bmad-build-auto, the flows where re-review is
part of the loop. Standalone bmad-code-review is left out: it usually
runs without a spec, where nothing is persisted between runs, so there
is nothing to carry.
Adapted from #2805 by pbean.
Co-authored-by: pbean <paulbeanjr@gmail.com>
* chore(code-review): curlies only where a value expands
The step files mixed two spellings of the same variable: {spec_file}
and spec_file, with no rule for which appears where. Convention now:
curly braces mean "substitute the value here" (paths in commands,
printed values); a bare name refers to the variable itself
(assignments, clears, set/unset and equality tests). Also drop the
decorative quotes around mode literals: full and no-spec are values,
not strings in any language.
No behavior change intended.
---------
Co-authored-by: pbean <paulbeanjr@gmail.com>
Re-running the skill against a done spec starts a follow-up review, but
step-04 grades its recommendation by the first-pass rule, so a pass that
patched two mediums recommends yet another pass and the loop keeps
scheduling reviews of work that has converged.
Step-01 now sets followup_pass when it routes a done spec, and step-04
splits the rule: a first pass recommends a follow-up for a patched high
or two patched mediums, a follow-up pass only for a patched high — and
any true recommendation must name the specific unverified risk, or it
is false. Patch volume is never grounds.
Adapted from #2805 (2bafb3fb) by pbean, minus that branch's
carry-forward machinery.
Co-authored-by: pbean <paulbeanjr@gmail.com>
Replaces tools/validate-skills.js with tools/validate_skills.py, taken from the
flat-tree work on feat/npx-skills-distribution rather than written afresh, so
the two do not diverge again. Discovery is repointed from that branch's flat
skills/ tree to src/. Behaviour is otherwise unchanged: same rule IDs, same
JSON shape, same --strict and --json flags, and the tests come across as
unittest cases run through uv, matching how the other Python tests are wired.
The three step-structure rules go away with it. STEP-01 (filename format),
STEP-06 (step frontmatter) and STEP-07 (step count) all key off a literal
steps/ directory that only two of fifty skills have — everywhere else step
files sit at the skill root — so they validated almost nothing. The catalog's
first-pass list drops from 13 rules to 10 to match, and their rule sections
are removed.
CI is unaffected: quality.yaml already provisions uv and invokes the npm
script rather than the file.
* chore(review): swap Augment for Greptile and repair CodeRabbit config
Augment is no longer in use, so its guidelines file goes away in favour of
greptile.json. Rather than paraphrasing the repo's conventions, both bots are
now pointed at the same source files: AGENTS.md and tools/skill-validator.md,
plus docs/_STYLE_GUIDE.md scoped to docs.
Four CodeRabbit path instructions had gone stale and matched no tracked files:
src/**/skills/**, src/**/workflows/**, src/**/tasks/** and src/**/*.agent.yaml.
The skill-validator catalog was consequently applied to nothing. Retarget them
at src/*-skills/** and src/bmm-skills/agents/**, and drop the two describing
layouts the repo no longer has. Three further fixes: `walkthrough: false` is
not a schema v2 key, so use collapse_walkthrough; the media filters were
root-only globs and left docs/images under review; and the validation-report
filter named .md where those files are .html.
AGENTS.md gains the prompt-length and testing conventions, which were until
now written down nowhere in the repo. CLAUDE.md is unignored and imports it.
* chore(review): align catalog scoping and narrow the ignore lists
Greptile's global instructions named tools/skill-validator.md and
docs/_STYLE_GUIDE.md, but customContext.files supplies those only for skill and
documentation paths. Reviewing anything else, Greptile was told to apply
catalogs it had not been given — an invitation to invent rules from the
filenames. The global clause now names only AGENTS.md, which is loaded on every
review; the two scoped catalogs keep their scopes and their own descriptions.
website/** was excluding 18 hand-written source files along with the assets —
the Astro components and pages, both rehype plugins, the locale and site-url
helpers, the i18n JSON. Exclude website/public/** and website/diagrams/**
instead, so generated and editor-authored artifacts stay out while the source
is reviewed.
tools/tests/fixtures/** joins test/fixtures/** ahead of the validator port that
moves the skill fixtures there. Those fixtures encode defects deliberately, so
any review comment on them is wrong by construction.
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.
Private vulnerability reporting is now enabled on the repo, so the
advisory link in this policy resolves. Adds security@bmadcode.com as a
second channel, replaces the unmet response SLA with best-effort
language, and adds a Security Model section so scope decisions rest on a
stated trust boundary rather than case-by-case argument.
Claude-Session: https://claude.ai/code/session_014nrWo411353cGjRBpMLpfV
Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
* 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>
Two path-analysis bullets, added to all four copies of the prompt
(bmad-build, bmad-build-auto, bmad-code-review, and the bmad-review
lens):
- Handle lifetime: a re-check of something the code already held exists
because an intervening call can invalidate it — identify that call,
what it does to the thing held, and what is silently skipped when the
re-check fails. Targets use-after-invalidation bugs the hunter's
branch walk slides past because the guarded exit reads as handled.
- Call vs declaration: for each call site the diff adds or changes,
tests included, check the call against the callee's declaration.
Gives arity/type mismatches an owning layer; previously no layer was
chartered to notice a call that cannot compile.
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 Windows branch of ABS_PATH_LEAK used `\\\\`, which in a regex literal
is two backslashes, so it only matched the escaped `C:\\Users` form and let a
plain `C:\Users\...` or `C:/Users/...` through. Match a drive letter of
either case followed by one separator, with a word boundary so URL schemes
like https:// stay unflagged.
Fixes#2487
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.
Replaces the two-judgment review triage (assign severity, then keep or
dismiss) with a single verdict per finding across bmad-build-auto,
bmad-build (incl. one-shot), and bmad-code-review:
- high / medium / low: the verified consequence occurs, graded by how much
it hurts end users or developers; developer-only harm must name where
it will bite.
- false: the claimed consequence does not occur at the named site;
requires a recorded refutation of the finding's own claim.
- maybe-false: verification could not establish whether it occurs;
records what would settle it, goes through root-cause grouping, and
defers only when a whole entry is maybe-false.
Every finding gets one row in a per-pass triage ledger, reconciled against
what the layers reported. Low findings are rejected when unlikely to be
met in everyday use and the fix adds complexity. Findings are judged on
whether the problem is real, not whether the proposed fix is plausible; a
loud failure on an undemonstrated state is handling, not a defect. The
patch route requires the smallest fix to be trivial, add no public
surface, and guard no undemonstrated state — otherwise it routes to
intent_gap or bad_spec. A finding excluded only by the spec's scope
section, the plan, or the diff's shape (not by the intent) routes to
intent_gap or bad_spec, never patch or defer.
Supersedes #2729.
* 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 full-config dump writes ensure_ascii=False JSON to a stdout still
bound to the platform default. On Windows that is cp1252, which cannot
encode the emoji icons carried by the shipped agent configs, so the
script raises UnicodeEncodeError and exits having produced no output.
Adopts write_json_stdout() from the sibling resolve_customization.py,
and adds the stdout regression test the suite was missing - it fails
against the unpatched script.
Fixes#2682
Co-authored-by: abobdadjimo <abobdadjimo@iqera.com>
Co-authored-by: Claude Fable 5 <noreply@anthropic.com>
brain.py prints two kinds of arbitrary user text: --extra overlay
techniques (customize.toml additional_techniques) and, on stderr, the
technique name echoed back by `show NAME` when it is not found. Either
can carry a character the platform default cannot encode, and print()
then raises UnicodeEncodeError. The shipped catalog is cp1252-safe (its
only non-ASCII is U+2014), so this is an overlay/argv path, not a
default-catalog crash.
pin_utf8() passes errors= through rather than letting it default:
reconfigure(encoding=...) alone resets the handler to strict, which
would silently downgrade stderr's POSIX default of backslashreplace
and turn a diagnostic about an undecodable path into a traceback.
Thanks to @armelhbobdad for catching that on #2693.
Four regression tests, all four red against the unpatched script.
Co-authored-by: Claude Opus 5 (1M context) <noreply@anthropic.com>
Confirmed against real session logs across bmad-build and
bmad-build-auto: zero fires, ever, including a session built
specifically to test it. The tier produces boilerplate at
spec-authoring time and gets silently fantasized past at execution
time, so it does nothing but add noise.
Boundaries & Constraints drops from three tiers to two: Always,
Never. No replacement mechanism — a real judgment call that turns
out to matter surfaces at step-04 review like everything else does.
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.
The triage rule 'A finding whose fix edits {spec_file}: dismiss' gets
quoted verbatim into Review Triage Logs, leaking the unresolved
placeholder into story specs (observed in three consecutive unattended
runs). Name the file by its role instead — 'the spec this build is
implementing' / 'the spec under review' — so quoting the rule is
harmless, mark the defer clause's other-spec distinction explicit,
and make its document list read as examples (e.g.), not an enumeration.
* fix(skills): judge each review finding on its own before grouping
Triage in bmad-build, bmad-build-auto, bmad-code-review, and the one-shot
route previously deduplicated and grouped findings first and judged the
groups. A false finding merged into a group could dilute or sink a true
one, and a true finding could be dismissed on facts about its neighbors.
Now, once every layer has reported, each finding gets its own verdict
before any grouping: verify its claimed consequence at the site it names
(reading past the diff hunk into callers and guards), assign severity from
the verified consequence, and keep or dismiss on that verification alone.
A dismissal must dispose of the finding's own claim — an adjacent fact
that leaves the claim standing is not a dismissal — and every dismissal
is recorded with its reason, never dropped silently. Grouping applies
only to survivors, by shared root cause; same location or a shared fix
alone does not qualify.
Presentation reports the dismissed count in conversation, with the full
reasons preserved in the spec trace / report as the audit trail.
* fix(skills): route paperwork findings out of the patch lane
A review finding whose fix edits the story spec is dismissed; one whose
fix edits an agent-context document (CLAUDE.md, AGENTS.md, rules files,
specs) is deferred. An unattended run rewrote a repo's CLAUDE.md and its
own story spec through the legal patch chain; the triage had no concept
of documents that are not the run's to change.
* fix(bmad-build-auto): state subagent launches as one batched message
The Subagents section led with 'launch it, wait for it to return, then
continue with its result' — a serial recipe that contradicts step-04's
'launch every active layer before handling any layer's result'. An
unattended run followed the recipe and serialized all thirteen of its
subagent launches, including both four-reviewer fan-outs. The lead
sentence now prescribes the batched shape directly and covers
single-subagent steps, so no serial reading survives.
The content under review is staged exactly once as a file, and layer and
lens prompts carry its absolute path instead of the diff bytes. The parent
no longer regenerates the diff into every child prompt, which is what made
launch prompts large and staggered their dispatch.
bmad-build and bmad-build-auto stage the diff in step-03, before the
acceptance/verification check, and read it there so that check judges the
diff rather than the implementation subagent's report; a code change during
the check rewrites and re-reads it. Step-04 restages and hands the layers
the path. Staged files are uniquely named in the system temp directory so
concurrent runs cannot collide — bmad-code-review's staged diff moves there
too, off the fixed path it shared between runs.
bmad-review states the same contract once in its dispatch, covering every
lens: stage a branch, uncommitted work, or a commit range to one file and
pass the path. A branch means the diff against the merge base; uncommitted
work includes untracked files.
Inlining survives only in bmad-build's no-subagents fallback, where the
prompt is pasted into a session that shares no filesystem with this one. It
inlines every file the prompt points to and leaves every other line alone,
so the reviewer constraints that follow the content label survive.
Also carries the claims falsification pass to the build skills, adapted
rather than copied. In bmad-code-review the claims mechanism recovers a
narrative the skill does not own, so it guards on whether a claims file was
supplied. Build wrote the spec and ran the implementer, so there is no such
asymmetry: {claims_file} is {spec_file}, the check is unconditional, and it
reads only the Intent and Tasks & Acceptance sections. The reviewer's own
asymmetry survives — it is context-free by design and still opens the spec
for the first time after its independent path tracing.
bmad-code-review defined {diff_output} as holding diff text, so the
parent regenerated the whole diff into every layer launch prompt. On a
~31 KB diff that is roughly 8k output tokens per prompt, which staggered
the layer launches by minutes.
Rename the placeholder to {diff_file} and redefine it as a path. Step-01
writes the diff once to {implementation_artifacts}/code-review.diff,
creating that directory since artifact dirs are made lazily, and every
layer prompt now carries the path instead of the bytes. The two
review-prompt files accept either a path or inline content, matching the
contract core bmad-review already gives its lenses.
Inlining survives only in the no-subagents fallback, whose prompts are
pasted into a session that may not share this filesystem; that exception
is now stated where it applies so it stops reading as the general rule.
github-actions[bot]