mirror of
https://github.com/bmad-code-org/BMAD-METHOD.git
synced 2026-09-19 08:11:52 +08:00
dev
365 Commits
| Author | SHA1 | Message | Date | |
|---|---|---|---|---|
 Brian
|
f033e70a2c |
feat(method): add bmad-preview-ticketing skill and tickets.py runtime (#2884)
* feat(method): add bmad-preview-ticketing skill and tickets.py runtime Ticketing at every altitude: an initiative sliced into epics, an epic incepted into a Breakdown of stories, spikes, and bugs, and tickets written, refined, published, and moved on a git-backed store or a tracker (GitHub, Jira, Linear, Notion, Trello). - Container tickets are the spec at their altitude: Requirements with stable ids, Outcome, Done when, Boundaries, Breakdown. - Thin tickets carry contribution and verification; full criteria are written when pulled (`refined: false` until approved). - scripts/tickets.py derives ready, blocked, and to-create views from the files; scripts/read_toml.py reads the store config; tests beside them. - Store configs per tracker under config/, templates per type under assets/, customization surface in customize.toml. - Listed in the bmad help catalog as a preview alternative to bmad-create-epics-and-stories plus bmad-sprint-planning. * fix(method): address review findings in bmad-preview-ticketing - tickets.py: a dropped blocker still blocks its dependents; mark clears blocked_at and blocked_reason on a status change and takes the assignee literally; --project-root finds the store config when tickets live outside the project; a numeric blocker falls back to the ticket id; duplicate Breakdown numbers and blockers naming no entry are errors. - read_toml.py: read local files only. - board.md: mark is the leaf-level write, a container's status is a file edit, and a dropped ticket is removed or repointed in its dependents. - SKILL.md: tickets are drafted under tickets.root; persistent facts load file: entries. - gh config: read children with `gh issue view --json subIssues`. - help catalog: the breakdown includes bugs. * docs: add a guide to testing v7 previews A new page under Plan Larger Work for trying proposed v7 planning changes: setting up an initiative store, configuring where tickets are tracked, and using bmad-preview-ticketing. It states early that preview stories are not wired into sprint planning, sprint-status.yaml, or status updates from bmad-build, and that a story must be refined before it is built. - Sidebar entry and a pointer from the stories-and-tracking page. - Locale coverage baseline records the new English-only page. |
||
|
Alex Verkhovsky
|
b5834a5977 |
feat(walkthrough): replace five-step walkthrough with guided block review (#2866)
The skill is still /bmad-walkthrough. It writes a review narrative and log under implementation artifacts, then walks the narrative one block at a time. Hooks are optional; empty ones are omitted. A writer subagent is used only when the host has subagents. BREAKING CHANGE: customize.toml no longer uses prepend and append. The hooks are on_activation, on_block_activation, on_block_complete, on_complete, and persistent_facts. |
||
|
Alex Verkhovsky
|
23f134e2e5 |
feat(review): add the review lever and lens sets to build-auto and code-review (#2861)
Both skills gain a `workflow.review` selector. bmad-build-auto accepts `none`, `quick`, `thorough`, and `auto`, where `auto` follows the resolved route (oneshot selects quick, full selects thorough) and is the default. bmad-code-review accepts `quick` and `thorough`, defaulting to `thorough`; a review skill with review turned off has nothing to do, so it offers no `none`. An invocation naming a selection passes it as `--set workflow.review=<value>`, and any other value halts the render. `review_layers` retires in both skills in favour of two configured, ordered lens sets. `quick_lenses` holds the new Quick lens, an informed review of acceptance criteria, applicable rules, and bugs that reads the spec, its context files, and the repository's agent instructions. `thorough_lenses` holds Blind Hunter, Edge Case Hunter, Verification Gap Reviewer, and Intent Alignment Auditor, identical in both skills; bmad-code-review's Acceptance Auditor is removed. Templates render only the selected set. Under `auto` route with `auto` review, bmad-build-auto renders both sets and the session launches the one the fixed mapping selects. Under `none`, bmad-build-auto's step-04 drops its staging, review, and classify sections. The bmad-build-auto story frontmatter gains `review`, `review_source`, and `lenses_ran`. The review docs describe the two review depths and point to bmad-customize for the rest; the customize doc's example sets the default depth. |
||
|
do-operator
|
696cef5172 |
docs(diagrams): let the delivery loop's two slogans carry the accent (#2859)
* docs(diagrams): let the delivery loop's two slogans carry the accent Alexey, on the merged version: "I would make both slogans stick out more - splash of color, bigger font". He is right, and the original backs him up: it set START ANYWHERE in gold and RIGHT-SIZED in pale blue, both larger than what replaced them. Dropping every colour from the diagrams - so one drawing could serve light and dark - took that with it, and the two lines went grey and small enough to skip. They are the only sentences in the drawing, and a reader who skips them gets four boxes and no argument. Both now take the accent at 22, up from 17.5 and 18, as a matched pair rather than the mismatched ink-700 / muted-600 they had drifted into. Two colours are not available to a theme with one accent, so the pairing the original drew - gold for the entry promise, blue for the summary - collapses into one hue used twice. The canvas grows 460 to 466 to hold the larger type at the same 40 units of clearance. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * docs(diagrams): make the slogans banners, and give the pair two hues The theme already had an answer for what a banner is here. custom.css says the masthead is "display type, a lead, then a hairline closing the band, the way every section on the marketing site closes" - so each slogan now closes on a rule, run across the drawing's own measure, 60 to 1060, so the banners sit on the boxes' grid rather than floating over it. Both ends in the same accent read as one statement made twice. They are not: the top is the invitation, the bottom the summary, and the original said so by setting them in different colours. `--dg-accent-2` is the site's copper, the nearest thing this palette holds to that gold, so the pairing survives without inventing a hue. It needs a dark value of its own - `--bmad-copper` is #8a5a00 and disappears on a dark ground - and #e0b25f is that copper lifted, the value `--dg-warn` already uses on dark. The two rules cost height: 466 to 477. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * docs(diagrams): set the banners in the site's label register, and drop copper Copper is not a palette colour on bmadcode.com. Every use of #8a5a00 there is a status: `.tag-warn`, the gate's CONCERNS heading, `.road .st`, a flagged row in the module pane. Putting it on the closing line said "this is a problem" about the diagram's own conclusion. `--dg-accent-2` is gone. Reading the live site rather than counting hexes in its stylesheet also settles what these should be. Its uppercase labels are one register - IBM Plex Mono, 11px, weight 400, tracking ~0.08em - in exactly two colours: #7c8797 when a label orients, #0f35e0 when it carries weight. No section head on the site is coloured at all. So the banners are that register, not the Archivo 700 headings they had become, and the pair is told apart the way the site tells labels apart: accent for the opening, which is also what the entry drops below it are drawn in, and muted for the closing summary. They are set at 16 units rather than the site's 11px because they span the width of a drawing rather than sitting over a paragraph - 13.3px apparent in a README, against the 9.2px Alexey objected to. Canvas back to 465 now that the type is smaller. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * docs(diagrams): light the bulbs, and rule the field the original had Two colour families ran through the original: gold for the inputs - both bulbs, the three entry drops, the opening line - and cyan for the loop. When the drops took the accent back, the bulbs were left outside a family they belong to, so the drawing had a blue arrow leaving an ink bulb. Both bulbs are lit in the accent now. The cloud stays muted, as it was there too: it was drawn in the cool colour, not the gold, and a vague notion should not glow like an idea. The ruled field returns at the original's pitch, 70 one way and 140 the other, but held between the two hairlines so it reads as what the banners enclose rather than running out under them. Drawn in the line token, not the fixed blue it was, so it survives both ramps - at two opacities, because the dark line sits further from its ground than the light one and the same value that is texture on paper becomes structure on black. No gradient. The docs page gives this drawing no ground of its own, so a gradient can only live in the README export, and the two would drift apart for it. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 5 <noreply@anthropic.com> |
||
|
Alex Verkhovsky
|
94b6727b00 |
refactor(renderer): render skill sources as Jinja2 templates (#2857)
Replace the regex token substitution and the line-parsed bmad-if directives in render_skill.py with Jinja2. Templates see config, workflow, and snapshot(); undefined names, empty entry files, and links to omitted sources halt; every value a render reaches and the Jinja2 version key the generation. Migrate the five rendered skills' sources to the new forms, keep their shipped output byte-identical, and update the validator rule and the authoring docs. |
||
|
do-operator
|
116e703d67 |
docs: refresh the README banner, restore its diagram, and fix the favicon (#2854)
* docs: refresh the README banner, restore its diagram, and fix the favicon Three things the READMEs and the site were carrying wrong. The banner is the current one from bmadcode.com: the BMad tile and wordmark over the line art, at 2x for retina. It replaces a 1408x224 crop, and is smaller on disk than what it replaces. The delivery-loop diagram in the README has been broken since the diagrams moved to `docs-site/src/diagrams`. It cannot simply be pointed at the new path: an authored diagram carries geometry and classes only, so it needs the site's stylesheet to have any colour at all, and a README loads an SVG as an `<img>` where no stylesheet can reach it. So `docs/images/` now holds exports of the source, generated by `npm run export-readme-diagrams` with the dark ramp substituted in as literal colours. Literals rather than custom properties because an export has to survive renderers thinner than a browser - resvg drops `var()` and paints the fallback black. The Korean README's copy is exported from the same geometry through the existing labels file, so the two can no longer drift apart. The favicon was a teal `B` that matched neither the header tile nor blog.bmadcode.com. It is now the BMad mark, drawn from the same path data the header already carries, on the same navy the blog uses. The .ico is generated from the SVG and stays listed for browsers that ignore `image/svg+xml`. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * docs(diagrams): draw the bulbs as bulbs, not as coloured circles The earlier version leaned on gold to say "idea". Once the diagrams lost their own colours, a circle over a rounded tab in the body ink read as neither a bulb nor anything else. So the glyph now carries its meaning in the drawing: a filament arch inside the globe, a tapered neck, and a ribbed screw base, plus a third ray overhead. The small bulb takes the same construction one size down, with a single rib rather than two, which is all that reads at that scale. Both hold up on the light and dark ramps. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * docs: give the delivery loop an English page, at the house type scale The diagram the README leads with appeared on exactly one page of the site: the Korean `how-to/choose-a-development-path`, a leftover from before the English tree was restructured into start/plan/build. An English reader never saw it. It now opens "Find Your Starting Point" on the docs index, where it says in a picture what the list underneath says in prose. Putting it in a docs column for the first time showed its type was tuned for a README: drawn at a 1120 viewBox, its labels came out at 11.0px and 8.3px against the 12.8px and 10.9px the other diagrams hold at the same 736px content width. The sizes are scaled to match; the geometry is untouched. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * docs-site: guard locale coverage, and give the footer band an edge Two unrelated things a reader can see, and one they cannot. The invisible one first. When a locale has no page at a route, Starlight serves the English one and says nothing, so a missing translation and a working one look identical from the outside — which is how all five locales ended up stranded on the pre-restructure tree unnoticed (#2855). Starlight does mark the substitution: a fallback page carries `lang="en"` on `<main>` inside a document that declares the locale. The build now checks the built site for that mismatch, which measures the symptom rather than inferring it from the sidebar. The existing backlog is far too large to fix here, so it is recorded in `locale-coverage-baseline.json` and tolerated. The build fails only when the picture changes: a route starts falling back, or a baseline entry stops. Both are one `--update` away. The second failing is deliberate — it is what keeps the baseline from outliving the problem it records. The visible one: the footer band sets its own dark ground, which on the dark ramp is the page's ground, so there was no band — only 297px of unexplained space where one should have started. It now lifts a step and takes a hairline in dark mode, and sits flush against the article instead of adding a margin on top of its own padding. The last-updated line gives up some of its air too; between them the gap is 234px, and every part of it is now doing something. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * docs-site: stack the footer columns on mobile, and add the touch icon The footer's three link groups were laid out in two columns below 32rem, so one group always dropped onto a row of its own with the space beside it left empty, and "Plan inside an organization" wrapped inside a 155px column. Three groups do not fit two columns; on a phone they get one each. The favicon already matches bmadcode.com exactly - same viewBox, same navy tile, same three paths, since the mark is the one the header carries. What was missing is the apple-touch-icon the site also ships, so an icon saved to an iOS home screen fell back to a screenshot. It is generated from the same SVG, flattened onto the tile navy because iOS applies its own mask and does not want the transparency our rounded corners would leave. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * docs(diagrams): raise the delivery loop's type, and give it back a colour Alex is right about what he saw, and wrong about it being new. His screenshot is the version before the type was scaled for a docs column, where the title rendered at 9.2px against GitHub's 16px body. That is already fixed. But the original diagram this replaced ran 14/16/21 and the fix brought it to 14.5/16.5/19.5 - a hair under where it always was, and his objection would have applied to the original too. So rather than argue the point, take it past the original: 17.5/18/21, which puts the node labels at body size and the title at 14.5px in a README. The colour is the other half of his complaint's cause. The original said "here is where each kind of work joins" in gold; when the diagrams lost their own colours that meaning went with it and nothing replaced it. The three entry drops now carry the accent, which is the vocabulary's existing job for an edge the drawing has to single out, so it works on both ramps. The marker was still called `arrow-gold`; it is `arrow-entry` now. The README export also gets a ground rather than a flat fill: a near-black lifting across the diagonal with one soft accent wash behind the row the work enters from, which is the register bmadcode.com uses - almost all ground and one blue. The wash sits high on purpose, because centred it pooled behind the boxes and their flat fill then read as darker than the ground around them. The docs site keeps a ground that follows the reader's theme, so this belongs to the export alone. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * docs(diagrams): drop the gradient ground from the README export It read as an effect rather than a surface. The drawing's colour is the accent on the three entry drops, and it says more with a flat ground behind it and nothing competing. The larger type and the accent stay. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * docs(diagrams): space the delivery loop's two band labels evenly They were not spaced at all, only placed. The title's baseline fell three units BELOW the big bulb's top ray - the two only looked separate because they are far apart horizontally - while the lower band had 35 units of air. That mismatch is what read as wrong. Both now sit 40 units clear of the nearest mark. The drawing keeps its size and shifts down inside a taller canvas, 420 to 460, with the labels lifted out of its group so the shift leaves them where they are; the remaining padding above and below the pair is 15 and 16. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 5 <noreply@anthropic.com> |
||
|
do-operator
|
87d3407873 |
feat(docs-site): align the docs with the bmadcode design system, and move diagrams to themed SVG (#2850)
* feat(website): restyle the docs in the bmadcode design system The docs carried a Ghost-blog theme: Inter and Space Grotesk, a #3b82f6 accent, 12px radii, tinted panels and hover lifts. bmadcode.com is built from the foundry ramp on paper, Archivo and IBM Plex Mono, one accent held under ~2% of the page, 2px corners and hairlines. This aligns the two so the method and its documentation read as one thing. Four type registers, and almost nothing else: Instrument Serif for the page masthead, Archivo 600 for headings, Archivo 400 at 17px for prose, and IBM Plex Mono at 11px for labels — spent once per section, never on prose or a table header. The measure comes down to 46rem so a page reads as an article. Also fixes the site title, which was the only place in the repo spelling the brand "BMAD Method"; it now matches the prose, and every page title and share card with it. The four component overrides are the parts CSS could not reach: the mark in its ink tile, the accent eyebrow naming each section, and the dark footer band. The footer renders from TwoColumnContent rather than the Footer slot because Starlight right-aligns the content column (--sl-content-margin-inline: auto 0), so a band in that column never reached the sidebar edge. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * feat(website): inline hand-authored SVG diagrams Diagrams shipped as rasters: build-diagram.png at 488 KB, plus a -fr and a -ko export of the same picture. Every translation meant re-exporting an image, three of the five locales fell back to the English one, and none of them could follow the site's light and dark themes. Diagrams are now hand-authored SVGs carrying geometry and classes only. A rehype plugin inlines them where a page links to one, so a single stylesheet themes every diagram — an <img> is opaque to page CSS, which is the whole reason for inlining. A second diagram written against the same class vocabulary matches the first without any styling work. Labels are translated rather than redrawn: each <text> carries a data-i18n key and the strings live in <name>.labels.json, so one drawing serves every language and a translation cannot drift out of shape. The integration exists because the inlined SVG lands inside Astro's content layer cache, which is keyed on the markdown file. Editing a diagram left the previous drawing on the page, through a build that reported success. It watches the diagram directory in dev and drops the content store when the drawing changes. Diagram.astro is the same behaviour for anywhere that can take a component. The docs are 193 .md files and no .mdx, where components cannot be imported, so the plugin is the path pages actually use. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * docs(build): draw the bmad-build run as a themed SVG Replaces build-diagram.png and its -fr and -ko exports with one drawing shared by all five locales: the actors in a left lane, the spine down the middle, a return channel for BAD_SPEC and INTENT_GAP, and the review lenses in a panel — the layout the original had. Gzipped, the diagram goes from 440 KB to 1 KB, and it now follows the theme. The French labels are in place; the other locales fall back to the English text in the SVG, which is what their pages showed before. The raster files stay for now: walk-through-a-change still uses walkthrough-diagram, and that conversion is a separate change. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * fix(website): let the diagram cache stamp survive a fresh checkout The stamp is written into Astro's cache directory, which does not exist until Astro creates it partway through the build. On a clean clone — CI, every time — the integration threw in astro:config:done and took the build with it. It now creates the directory, and treats any failure as a warning: a cache that cannot be stamped is a slower build, not a broken one. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * docs(walkthrough): draw the walkthrough run as a themed SVG Replaces walkthrough-diagram.png and its -fr and -ko exports with one drawing shared by all five locales, keeping the original's layout: the two inputs in a left lane, the five stages down the spine, the notes beside them, the early exit skipping the middle, and the three outcomes along the bottom. The outcome chips introduce a `chip` class in the shared stylesheet, taking the green and amber the asides already use, so a green in a diagram is the same green as a tip. Nothing else about this diagram needed styling: it inherits the vocabulary build-run established. With both diagrams converted, website/public/diagrams is empty and the six raster files are gone. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * docs(plan): fold the remaining diagrams into the themed pipeline planning-skills, development-paths and bmad-delivery-loop were already SVG, but outside the pipeline in three ways: they carried their own palettes, they were served as <img> so page CSS could not reach them, and two of them shipped a -ko twin that duplicated the geometry to translate the labels. Two were drawn dark — navy grounds, white text, cyan strokes — so on a light docs page they sat as dark panels. Their palettes are mapped onto the shared tokens, which flips them correctly in both themes, and their backdrops are dropped: a diagram sits on the page's ground rather than painting its own. The hardcoded typefaces go too, so they inherit Archivo and IBM Plex Mono like everything else. The Korean strings are lifted out of the -ko files into the label files, matched by document order, so all five diagrams are now one drawing per diagram. docs/images is empty. Also fixes the cache guard, which was clearing the wrong store: build writes to the cache directory, dev writes to .astro beside the config, and the stamp was shared between them so whichever ran first consumed the invalidation. It is now per command and build-only — deleting the store under a running dev server leaves the content layer unable to render, so dev needs a restart after a diagram edit instead. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * fix(diagrams): align the imported diagrams with the shared vocabulary Mapping the old palettes onto the theme tokens made those three diagrams theme-aware, but not part of the system. They still carried 8-16px corners, painted their own canvas panel or background grid, drew every connector in the accent, and left arrowheads baked to a colour of their own — so next to build-run and walkthrough-run they read as imports. They now use the same roles as the two authored diagrams: .node for boxes, .edge for connectors, .head for arrowheads, 2px corners, and no self-painted ground. Accent drops out of all five: it is for the one thing a drawing points at, which here is a single .node.hot on the destination box rather than a green that read as a status. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * chore(docs-site): record hast-util-from-html in the lockfile The dependency was declared in package.json during the move to docs-site but its entry never reached the lockfile's root block, so the two disagreed about what the site depends on. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * fix(diagrams): land the arrowheads on their targets in build-run Three arrows pointed at glyphs rather than at boxes, and all three fell short: DEFER stopped 10px from the document and aimed at its corner instead of its body, REJECT stopped 27px from the discard glyph, and the result returning to you stopped 21px from the person. The boxes were fine throughout — every arrow into a node already landed within 2px. What the three had in common is that a glyph sits inside a translated group, so eyeballing them against the drawing's coordinates put the endpoints in the wrong place. Measured across all twenty arrowheads in screen space afterwards: the largest remaining gap is 3px. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * fix(diagrams): move the DEFER label off its own curve, and clear the cache on a dev start too Re-aiming the DEFER arrow at the document glyph swung its curve left, straight through the label that had been sitting clear of the old path. The label moves into the pocket between Present and the curve. Checking it exposed a worse problem: dev was still serving the previous drawing after a restart, so the fix looked like it had not applied. The cache guard had been narrowed to build-only after clearing the store under a live dev server broke rendering — but that failure came from clearing on a mid-session restart, and the watch that caused those is gone. On a cold start, before the content layer loads, clearing is safe in both commands. Confirmed by probe: edit a diagram, restart dev, the edit is served, no errors. So the limitation is now what it was documented to be. Previously an edited diagram needed a full build before dev would show it. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * fix(diagrams): give every connector an arrowhead, and clear the boxes Three defects in development-paths, all inherited from the import: Connectors were written as two subpaths in one path element. A marker-end lands on the last vertex of a path, so only the second segment ever drew a head — which is why Change—Edit had none and Edit→Verify did. Four connectors are now separate paths, and all twelve carry a head. The two routed connectors ended exactly on the box they point at, so the arrowhead sat on the border. They stop 4px clear. The epic row was 140/130/130 wide with the labels centred on each box. All three are 140 now, evenly spaced, with the connectors and labels following. Band backgrounds were imported as .node, which made every check treat a connector crossing its own band as an error. They are .band now: same appearance, but the drawing says what it means. Also moves the DEFER label in build-run back alongside its curve. The previous fix pushed it clear of the line and lost the association. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * fix(diagrams): one stroke weight across all five drawings build-run and walkthrough-run carry no inline stroke-width — the stylesheet owns it, at 1.5 for a connector and 1 for a box. The three imported drawings still carried their own: 2, 3, 4 and 2.5, so their lines were twice as heavy as the authored ones. That is also what made the arrowhead into "Build × stories" look wrong. A marker scales with stroke-width by default, so a head defined at 7 units rendered at 21px on a 3px line instead of 10.5px. On a 9px final drop it overshot the corner and sat on the horizontal run above the box. Sixty inline stroke-widths are gone, and the two routed connectors get a longer final drop so the head has room to sit on. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * test(docs-site): cover rehype-inline-diagrams, and fix what it caught Twelve tests alongside the existing plugin suite, against a temporary site root: what gets inlined and what is left alone, label substitution per locale with fallback to the authored English, the accessible name, and the mtime-keyed re-read the dev server depends on. The first run failed on the accessible name, and it was right to. hast camel-cases ARIA attributes, so the guard read `aria-labelledby` and found nothing — meaning every diagram's own <title> was being replaced by the markdown alt text. build-run and walkthrough-run both title themselves with a sentence describing the whole run, and both were announcing a four-word alt instead. Now 119 assertions, and a diagram that names itself keeps its name. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * fix(diagrams): recover the Korean walkthrough labels, and correct the guide Review caught two things. The style guide sent contributors to website/src/diagrams/, the path this branch renamed. A diagram placed there would never be found by the loader or localized. The second is a regression this branch introduced and the PR described wrongly. It claimed the non-English pages "fall back to the English text in the SVG, which is what their pages showed before". That is untrue for four pages: they had localized exports, and replacing those with one drawing plus an English-only label file puts English labels in front of readers who previously had their own language. walkthrough-diagram-ko.svg was an SVG, so its Korean is recoverable and is now the ko-KR label set for walkthrough-run — all 22 keys. The other three were .webp exports, so their text cannot be lifted out: ko-kr build-a-change build-run ko-KR 0/30 keys fr explanation/build build-run fr-FR 13/30 keys fr build/walk-through walkthrough fr-FR 0/22 keys Those need a translator. The 13 French keys are mine and unreviewed. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * i18n(diagrams): complete the French and Korean diagram labels Fills the three gaps review found: build-run had no Korean and only 13 of 30 French keys, walkthrough-run had no French. All four sets are now complete. Terms come from the repository rather than fresh coinage. Korean reuses what the -ko diagrams and the Korean pages already established — 의도, 구체화, 계획, 검토, 결과, 사양 — and French follows the vocabulary of docs/fr/explanation/build.md: revue, intention, résultat, implémentation, spécification, and visite guidée from the French walkthrough page. The uppercase edge tokens stay as they are. PATCH, REJECT, BAD_SPEC, INTENT_GAP and DEFER appear in no locale's prose, so they read as protocol constants, the way bmad-build and path:line are already left alone in the Korean set. French runs longer than English and these are fixed-geometry drawings, so both French pages and the Korean one were checked for labels overflowing their box, sitting on a connector, or colliding: none. These are my translations, not a native speaker's. Worth a pass from whoever owns each locale before release. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * fix(docs-site): satisfy the repo's lint and format rules in the new tests The diagram tests used .forEach to walk the hast tree, which this repo's eslint config rejects (unicorn/no-array-for-each), and the file was not Prettier-formatted. CI had been failing on lint since the tests landed. Rewritten as for…of and formatted. Verified against every gate the workflow runs — lint, format:check, test, build — rather than the build alone. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * docs(website): describe the source of the theme without naming a private repo The comments cited the private repository and file paths it was ported from. They point at bmadcode.com instead, which is the public thing a reader can actually check. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> * fix(website): keep footer links in the reader's language The footer prefixed only BASE_URL to root-locale paths, so a French or Korean reader following any internal link landed on the English page and lost their language for the rest of the visit. The links now carry the page's locale. Every target exists under every locale — Starlight generates the untranslated ones as fallbacks — so this is safe rather than a trade of one broken link for another: all 36 routes, 6 links across 6 locales, resolve in the built site. Co-Authored-By: Claude Opus 5 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 5 <noreply@anthropic.com> |
||
|
Alex Verkhovsky
|
d7d4cfffbb |
feat(renderer): add invocation overrides and conditional sections (#2844)
Add repeatable --set key=value arguments and an --overrides <file.toml> file to render_skill.py. Shipped defaults, project TOML, user TOML, the invocation file, and command-line assignments resolve into one effective customization using the existing structural merge; persistent files are never written. Two --set paths that are equal or nested halt as a caller error. The renderer keeps no separate schema of customization keys: a --set path must exist in customize.toml, and any invocation override that reaches no token or condition halts. Values are validated where consumed. Standalone [[bmad-if:path == literal]] / [[bmad-else]] / [[bmad-endif]] lines select sections before token and link resolution. A secondary file that filters to nothing is omitted from the snapshot; workflow.md filtering to nothing is an error. Condition inputs join the generation identity so identical output from different inputs still yields distinct snapshots. Document both interfaces, ignore the per-machine skills-lock.json, and cover precedence, equivalent forms, isolation, conflicts, unused overrides, malformed input, nested conditions, and snapshot reuse. |
||
|
Alex Verkhovsky
|
78ffe4031f |
docs(customize): match the TEA catalog entry to Test Completed Work (#2839)
The modules page said TEA adds risk-based prioritization and traceability over the built-in QA skill. The page it links to compares the two generate skills instead. Say what that page says. |
||
|
Alex Verkhovsky
|
a7382aef76 |
docs(plan): correct course syncs sprint-status after approval (#2833)
The Correct Course paragraph read as if the skill only wrote a proposal and left all bookkeeping to the user. Checklist item 6.4 still updates sprint-status.yaml once the proposal is approved, so say so, and keep the story-breakdown re-run as the path for large restructures only. |
||
|
Alex Verkhovsky
|
fa1637ee40 |
build: move the Node toolchain into docs-site (#2834)
The root package.json, lockfile, .nvmrc, prettier ignore file and .npmignore are gone. docs-site has its own package.json and lockfile with the Astro, ESLint and Prettier dependencies, and its scripts run relative to that directory. tools/quality.py, both workflows and the docs all call npm inside docs-site. stamp_release.py stamps only the 29 skill manifests now; the version lives nowhere else on this branch. The tests for package stamping go with it. |
||
|
Alex Verkhovsky
|
33bdfb5132 |
feat(build): shorten completion handoff (#2822)
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. |
||
|
Alex Verkhovsky
|
b0d27c3c4a |
fix(skills): defer all-maybe-false entries only at medium-or-worse (#2809)
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. |
||
|
Brian
|
3aa110dfd3 |
fix(customization): resolve the project root from the working directory (#2802)
* 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>
|
||
|
Alex Verkhovsky
|
a2d84a39ac |
docs: give bmad-correct-course a home on Break Work into Stories (#2799)
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. |
||
|
Alex Verkhovsky
|
a0d04f7e34 |
docs: consolidate Reference and retire the Diátaxis groups (#2798)
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. |
||
|
Alex Verkhovsky
|
3bc2271260 |
docs: add Customize and Extend chapter (#2797)
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. |
||
|
Alex Verkhovsky
|
c16dc729a9 |
docs: add Existing Codebases chapter (#2793)
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. |
||
|
Alex Verkhovsky
|
0223cbd9d7 |
docs: move Finish an Epic to the Build chapter (#2791)
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. |
||
|
yeomin4242
|
f194a04939 |
docs(ko-kr): add Korean localization (#2386)
* docs(ko-kr): add Korean translation for BMAD docs * docs(ko-kr): add Korean translations for sidebar and banner components * docs(ko-kr): add Korean translations for AI banner and announcement components * docs(ko-kr): add Korean translation for workflow map diagram and update iframe references * docs(ko-kr): update sidebar order for multiple explanation and reference documents * docs(ko-kr): sync localization with latest docs * docs(ko-kr): polish web bundle wording * docs(ko-kr): polish localization wording * docs: refine Korean localization * docs(ko-kr): sync v6.9 documentation updates * docs(ko-kr): polish v6.9 wording * docs(ko-kr): sync localization with v6.10 docs * docs(ko-kr): sync core tools with unified review skill * docs(ko-kr): add Deep Recon documentation * docs(ko-kr): document project context redesign * docs(ko-kr): add delivery lifecycle guides * docs(ko-kr): migrate implementation guides to Build * docs(ko-kr): sync tool and customization references * docs(ko-kr): update project context workflow * docs(ko): sync localization with v6.11 documentation * docs(ko-kr): polish v6.11 localization * fix(website): polish localized docs behavior * docs(ko): sync localization with v6.11 documentation --------- Co-authored-by: Brian <bmadcode@gmail.com> |
||
|
Alex Verkhovsky
|
191219eadb |
docs: add Plan Larger Work chapter (#2790)
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. |
||
|
Alex Verkhovsky
|
984b990367 | docs: compare generate skills on Test Completed Work (#2788) | ||
|
Alex Verkhovsky
|
0eb32bfe78 |
docs: rewrite Build a Change wait-cost section (#2787)
* 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. |
||
|
Alex Verkhovsky
|
b023b5c9fc |
docs: add Review a Change page (#2786)
* 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 |
||
|
Alex Verkhovsky
|
6b83751711 |
chore(docs): drop llms.txt generation and site banners (#2785)
Stop generating llms.txt and llms-full.txt, remove the header banners, and point help/docs at the live site. |
||
|
Alex Verkhovsky
|
cf0d98f030 |
docs: integrate the Build chapter (#2784)
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. |
||
|
Alex Verkhovsky
|
7e571784ed |
feat(build): route after design, not before investigation (#2762)
* 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. |
||
|
Brian
|
d2b87b849b |
Rename bmad-checkpoint-preview to bmad-walkthrough (#2783)
* 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
|
||
|
Alex Verkhovsky
|
fcaac4631e |
docs: add Test Completed Work page (#2782)
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. |
||
|
Alex Verkhovsky
|
f1d8bd8bca |
docs: add Checkpoint a Change page (#2781)
* 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 |
||
|
Alex Verkhovsky
|
922c86d2c5 |
docs: add Build a Change page in plain English (#2780)
* 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. |
||
|
Alex Verkhovsky
|
4d8dec79b9 |
docs: clarify BMad development paths (#2669)
* docs: clarify BMad development paths * docs: add development path diagrams |
||
|
Alex Verkhovsky
|
22c76e8ba2 | docs: add Start documentation section (#2777) | ||
|
Alex Verkhovsky
|
11bfd36d58 |
docs: route the landing page by task (#2776)
* 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> |
||
|
Alex Verkhovsky
|
9376e1f9e5 |
docs: rewrite installation guide (#2775)
* docs: rewrite installation guide * docs: refine installation outputs and CI example |
||
|
Brian
|
eab4883caa | docs: remove roadmap page and links, tidy README footers (#2774) | ||
|
Alex Verkhovsky
|
86beb06547 |
docs: restore the ladder shape of the closing poem (#2757)
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. |
||
|
Brian
|
568365e7ff |
chore: default persistent_facts to an empty array (#2750)
* 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.
|
||
|
Brian
|
825099b2cb |
fix(installer): ask about deprecated shims during Quick Update, and report the outcome (#2746)
* 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. |
||
|
Alex Verkhovsky
|
c4ec1837b8 |
feat(project-context): adopt handwritten instructions via a ledger (#2715)
* 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 |
||
|
Alex Verkhovsky
|
db7f96dd93 | feat(installer): make compatibility shims optional (#2728) | ||
|
Alex Verkhovsky
|
890fcda760 |
docs(project-context): update stale "pitfall line" wording to "pitfall" (#2710)
Aligns the how-to and theory docs with the skill terminology change from #2709. |
||
|
Brian
|
ade7a966e9 |
fix(installer,skills): make uv a real requirement and stop assuming a system Python (#2704)
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. |
||
|
Brian
|
47bab7d15c |
refactor(project-context): conversational skill, no script, AGENTS.md block (#2698)
* 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> |
||
|
Alex Verkhovsky
|
2f8b437ea2 |
docs(review): remove the adversarial-review explanation page (#2679)
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. |
||
|
Brian
|
57e70562e3 |
feat: bmad-project-context skill — verified kernel + bundle context system (#2674)
* 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 |
||
|
Alex Verkhovsky
|
cff69a6d54 |
refactor(review): slim adversarial hunter prompt (#2675)
* 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. |
||
|
Alex Verkhovsky
|
d25a307e71 | docs: remove non-interactive installation pages (#2670) | ||
|
Alex Verkhovsky
|
49c608f782 |
chore(build-auto): remove final_revision from the contract (#2668)
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. |
||
|
Alex Verkhovsky
|
e510393b35 |
docs: define plain English writing rules (#2667)
* docs: define plain English writing rules * docs: clarify what readers need from each page |