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.
* 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.
The change's narrative (commit messages, stated description) is staged by the
main session as a file and handed to the edge case hunter alone, which reads
it only after path tracing completes, then tries to falsify each claim against
the traced code. Findings carry kind "claim". Other layers never receive the
narrative, keeping their reviews unanchored.
Parents were announcing several layers then emitting one Agent
call and ending the turn. Restating parallelism does not fix
that. Require skip announcement, then every launch before any
result, and try to run them simultaneously.
* fix(bmad-code-review): keep review layers inside their output contract
A layer running as a Claude Code subagent can see host tools the method never
asked for. One of them, ReportFindings, instructs the caller to send findings
to the host UI and NOT print them as text — which is the exact channel the
parent reads, so a layer that reaches for it returns nothing and reads as a
clean lens. Layers are now told to return findings as text in their final
message, not to route them through any host findings-reporting tool, and not
to spawn subagents of their own.
* fix(skills): keep review layers inside their output contract
Propagate the a5af8c5c closer to bmad-build, bmad-build-auto,
acceptance-auditor, and bmad-review lens spawns so a host
findings tool cannot swallow a layer's final message.
* 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.
* docs(build): add four review lenses to the Build diagram
Keep the unpublished Excalidraw source under website/diagrams/ and
refresh the published PNG so the Build page shows Blind Hunter, Edge
Case Hunter, Acceptance Criteria Audit, and Verification Gap.
* docs(build): move acceptance check off the review-lens box
Show Fits AC? as a gate between Implement and Review. Leave Blind Hunter,
Edge Case Hunter, and Verification Gap as the only review lenses.
step-oneshot and code-review step-02 told the orchestrator to launch
review subagents together, "then wait for all results" — spawn-then-wait
phrasing that reads as an invitation to detach the reviewer and improvise
the wait. Runs that drew that reading lost the in-call result delivery:
the orchestrator waited blind, and some relaunched a reviewer that was
still working, paying for the review twice.
bmad-build step-04 and bmad-build-auto already pin the contract: blocking
calls awaited in this turn, never backgrounded or detached. Port that
clause to the two remaining weak sites so every review dispatch in the
ship skills states the same contract.
* 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
* fix(build): gate one-shot patches on evidence, widen defer
The one-shot Classify contract routed findings by two criteria the model
cannot check: patch was gated on ease alone, so it filtered nothing, and
defer was scoped to provenance, so a true finding that was not
pre-existing had no home but reject. Anything true, cheap, and unwanted
therefore landed as shipped code.
Gate patch on evidence instead: the finding must show a defect that
actually occurs, missing coverage for a specific case, or a broken gate
or convention, and the remedy must be the smallest one -- no new public
surface, no guards for undemonstrated states. Widen defer to any real
finding not being fixed now, improvement ideas included, so worth
judgments reach the human as backlog lines instead of diff.
Reject keeps its wording and now works by elimination: non-substance
only. No criterion in the contract asks the model whether a change is
worth making.
* fix(build): make patch classification take precedence
Require findings that satisfy the evidence and remedy bounds to be
patched before defer is considered. This keeps specific missing coverage
from varying between immediate remediation and backlog work.
* fix(build): make one-shot triage routing exhaustive
Define patch, HALT, defer, and reject as an ordered partition. Keep
pre-existing and improvement findings out of the implementation while
escalating demonstrated change-caused findings that lack a safe trivial
fix.
* fix(review): gate routing on explicit review requests
bmad-review's description matched any review-like phrasing, so coding
agents entered the review workflow for requests that never asked for
one — install commands, git operations, summary requests, build
handovers, and questions, including a question about the review skill
itself. A week of Codex session logs showed every invocation but one
was unintentional.
Rewrite the description around an explicit ask:
- Trigger only when the user asks to review a diff, a pull request,
or an artifact — code or documents — and actually says "review".
- Acting on feedback from an earlier review is a change, not a review.
- Never volunteer, including on the agent's own just-made edits.
Validated with a 32-case routing eval, each case judged in an
isolated context, on two agent platforms; ten cases come from the
real over-trigger transcripts. The final wording scores 30/30 on
both platforms; an earlier draft's 29/30 drove the artifact clause
to name code explicitly.
* fix(review): count forwarded skill directives as review asks
Review-bot finding, confirmed by an isolated routing probe: with the
gate reading "when, and only when, the user asks", a literal reader
refuses the documented skill:bmad-review directive form that bmad-prd
and bmad-retrospective use to forward reviews.
Equate the directive with the ask instead of adding a second gate:
an explicit skill:bmad-review directive from another skill counts as
that ask.
The forwarded-directive scenario joins the routing eval as a scored
case; the full 33-case run scores 31/31 (two unscored probes), with
no previously excluded case loosened.
Alex Verkhovsky