mirror of
https://github.com/bmad-code-org/BMAD-METHOD.git
synced 2026-11-03 05:51:59 +08:00
main
25
Commits
| Author | SHA1 | Message | Date | |
|---|---|---|---|---|
 Brian
|
499008ea97 |
feat(skills)!: rebuild advanced elicitation to start in one command with independent readers (#3162)
Advanced elicitation now starts only when named and works in the same turn. With no pointer it pushes what the last exchange was about, at its own size; a named target, methods or a direction aim it. With no methods named it runs three pushes from different directions: the method that best fits where the target looks weak, a wildcard chosen as the method whose answer is hardest to predict, and a third push, an open push to reconsider a single choice with everything the conversation holds, or a second method for a section or document. Each method runs as an independent reader with a five-part brief, and the findings merge into one revision of numbered changes tagged with their push, with premise objections shown as decisions for the user. A session is two user turns. The catalog has 48 methods in six directions, 22 recommended, each with a form line the brief quotes; renamed methods resolve by their old names through an aliases column. pick_methods.py takes the resolver output, binds the team's methods_file and rejects an unknown direction or tier. New default_methods setting; the session report records each change as applied or rejected. A new core-tools help topic, help/advanced-elicitation.md, covers how to start and aim the skill, what runs by default, what changed from the earlier version and when a plain push is enough. The reference, help table and changelog describe the rebuild, and the planning skills and agent personas mention it. Trigger queries and four quality eval cases ship in evals/. BREAKING CHANGE: the customize.toml key preferences is now persistent_facts. The catalog columns are num, direction, method_name, description, form, tier, aliases, and the catalog drops from 71 methods to 48. The skill no longer starts on a generic critique request without its name. |
||
|
Brian Madison
|
1c55fed905 |
docs: update requirements before the spine, and let spine review gate epic Requirements
The organization guide and its help topic now give the same order for a mid-flight change and the same gate for the architecture spine review. |
||
|
Brian Madison
|
ef926b60ba |
Merge remote-tracking branch 'origin/dev' into product-owner-agent
# Conflicts: # docs/build/build-a-change.md # skills/bmad-build-auto/step-01-clarify-and-route.md # skills/bmad-build/step-01-clarify-and-route.md # skills/bmad-build/step-02-plan.md # skills/bmad-code-review/step-01-gather-context.md # skills/bmad-deep-recon/SKILL.md # skills/bmad-retrospective/references/evidence-gathering.md # skills/bmad-retrospective/workflow.md # skills/bmod-method/help/existing-codebase.md # skills/bmod-method/help/ticketing-setup.md # tools/ticket-tree-rules.md |
||
|
Brian Madison
|
49fd27e452 |
feat(skills): Sofia keeps tickets in a tickets folder, refines epics, and plans parent initiatives
- A container's breakdown, child epics, leaf files and plans sit in its tickets/ folder; its own file, memlog and other skills' runs stay above. tickets.py refuses the earlier layout, and migration-2.toml moves it. - Slicing writes epics thin with refined: false. Refining an epic names what is settled, what is still open with a pick for each, and reminds the user they can add intent, design or research; PRD, UX and architecture runs on an epic land in its folder. - Default slicing rules split by outcome, deployment and slice size, not ownership. - Work bigger than one initiative gets a parent initiative whose tickets.toml lists child initiatives; status and next report them. - Sofia, prfaq, deep-recon, forge-idea and architecture tell the user they can invoke party mode or advanced elicitation at any point. - Readers, help, docs and tree rules follow the new layout. |
||
|
Brian
|
d58ae51c61 |
feat(deep-recon): research the codebase from code and git history (#3085)
* feat(deep-recon): research the codebase from code and git history Add a Codebase path to bmad-deep-recon. The ask becomes a user-approved question set at the plan gate; locator, analyzer, historian and verifier subagents then answer it from the committed tree at one commit, each claim cited to a line or a commit, and a new `anchors` subcommand checks the citations mechanically. bmad-build reads a codebase research document as evidence for its investigation, and bmad-retrospective proposes ADRs from the decisions a run froze. * docs(deep-recon): answer one-file codebase asks in chat and update the research help A codebase ask that one file answers gets a cited chat answer, with a run only if the user still wants the document. The help agent's research guide now covers the codebase path: other repositories by path, git instead of web access, and refresh and deepen not applying. * fix(deep-recon): address review findings on citations, ADR sources and docs Verifier corrections keep a history claim's own commit. anchors parses paths with spaces, resolved against the commit's tree, and subjects holding quoted phrases, resolved against git's subject. The retrospective also reads Design Notes and Implementation Notes for decisions. Docs name the decisions folder for system-wide ADRs and the cited chat answer for one-file questions. * feat(deep-recon): keep call sites whole and show where codebase answers meet From a live run on Apache Fineract: the document dropped call sites a digest cited, and facts that two answers shared sat in separate sections, so the build planner missed a shared method and the check that rejects a zero amount there. A what-touches section now keeps every cited call site, no polish pass folds citations into an uncited summary, a Where the answers meet section names the methods several answers pass through and the checks there that reject or throw, analyzers report those checks, and a ticket or goal ask also asks how that code is tested. |
||
|
Brian Madison
|
495ef6e099 |
docs(help): route by the state of the spec and talk to Sofia the Product Owner
The method help replaces its three what-next sections with one routing diagram keyed on the initiative and epic file: write the initiative first, architecture reads it and is adopted as a companion, then slice, incept, build. The situation table keeps only what the diagram does not settle. Sofia coaches sparse input; the no-coaching line is gone from her spec and the help. Every instruction to use her reads talk to Sofia the Product Owner. Topic files, the architecture skill and one docs page no longer run architecture before the initiative exists. |
||
|
Brian Madison
|
fb28c032fb |
feat(skills): readers, agents, migration, help and docs name Sofia and the ticket file
bmad-build and bmad-build-auto load the active node's ticket file as the capability contract; bmad-architecture adopts the spine into the ticket's References through Sofia; the planning skills' closing offers name her SPEC capability; John's and Amelia's menus drop the items that invoked the retired skills and Sofia joins the roster. bmad migrate renders a v6 spec into the epic file, folds a pre-release spec-<slug>/ into its ticket (memlog entries in order, companions beside the ticket, CAP ids mapped to R), turns a loose spec folder into a backlog story, and drops the retired customization keys with a note. Help and docs describe one path: the initiative, epic or story file is the spec at its level, Sofia fills its requirements from what the user has and slices from it. |
||
|
Brian Madison
|
f6ffa3533b |
feat(ticket): layer the store config, add tracker mirror, and cut bmad-ticket's prompt
Applies the nine recommendations of a quality analysis of bmad-ticket. The skill's always-loaded prompt is smaller, each rule has one home, the store config follows skill updates, and tickets.py does the mechanical work the prompt used to describe. Prompt - SKILL.md goes from 3,319 to 2,628 tokens. The autonomous-mode section is folded into the role paragraph, Intake is four bullets, the customization key table is a list, and the tree layout moves in from board.md. Terms gains Envelope and loses Opening epic. - On the repo store, "what is ready" and "what is the status" are answered from tickets.py next or status without loading a reference. A tracker store goes to board.md first. - "Refine" now means only expanding a ticket to full acceptance criteria. Going over a pulled story without writing full criteria is a "review", done only when the user asks. references/ticket.md is the one home for both, with a table of where each kind of change is written. slice.md no longer carries its own copy. - references/board.md is reorganised: reading the tree, with one table of output keys and what to do about each; Publish; Start; Status, with who writes each status and the repo store and tracker split apart; Close, drop, move; Tracker sync. It now states once the rules the six store starters each repeated. - references/slice.md holds the slicing method that was in customize.toml: what makes a good story, the tracer bullet, lanes, touch points, the platform baseline as the opening epic. Decisions are recorded as Decision: lines when they are made. - references/tree-rules.md leaves the skill and becomes tools/ticket-tree-rules.md, a maintainer page for the skills that share the tree, named in AGENTS.md. No skill loads it. - The description gains triggers for validating tickets, sizing an epic, and setting up the store. Behaviour changes - A prerequisite is met when it is done or in review. The starters said done only, against tickets.py. - drift covers hitl as well as after, wherever the file and entry rule is stated. - An entry is never deleted from an approved tickets.toml. It is marked dropped, so its id is not reused. - Among several ready tickets, the first in build order is offered. The starters said the one that unblocks the most. - On a tracker, a mirrored assignee lives in the leaf file; a plan with no assignee key no longer blanks it. - First use no longer stops for store setup, and setup no longer ends in a session restart. Store config - The project's _bmad/custom/ticketing-store-config.toml is now a layer over the skill's starter for the store, not a copy of it. It names the store and holds only what the project sets; a key it sets replaces the starter's, tables merging key by key. With no file the store is the repo store. - scripts/read_store.py replaces read_toml.py and reads the two layers as one. --starters lists the shipped stores. - The starters keep only store-specific commands and facts. gh-ticketing.toml is renamed github-ticketing.toml so every file is named for its store. - references/store-setup.md is rewritten for this: choose, write the project file, connect, prove, plus switching trackers, a status the tracker lacks, and where a house rule on a verb goes. Customization - Removed: refinement, container_definition, prose, estimation.leaf_scale, and the auto value of publication, whose default is now at_inception. The first three were method, not team choices; leaf_scale could not be replaced because arrays append. - slice_to_epics, slice_to_tickets, and ordering hold only the team's own rules. - Checks that rested on another key now name it instead of restating its default, so replacing the key changes what is checked. tickets.py - mirror writes what a tracker returned (tracker_id, remote, tracker_status, assignee, after) into leaf files, pulling a file when the entry has none. It writes nothing when a value is invalid or would leave the tree unreadable, and a tracker_id given alone matches only a ticket that already carries it. - status reports next_id, the id a new ticket in a folder takes, and estimate totals when tickets carry points. - next gives a blocked row waiting_on, its unmet prerequisites. - drift on a status row gives the file's and the entry's value of each field that differs, instead of true. - With no folder, next and status also report the backlog folder, and find, mark, and mirror look there for a ticket the initiative does not hold. - A folder may be given by name alone: it is looked up under the store, then the active initiative. - --help prints the full interface, with a description per command. Other skills and docs - bmad-build and bmad-build-auto recognise a dropped plan. Build says the ticket was dropped and halts; build-auto halts with "dropped plan supplied" and leaves the plan as it is. Both plan templates list dropped. - bmad-retrospective and the bmod-method help pages say a story file exists once it is pulled, reviewed, refined, or published, not "when refined". - The method help, docs/plan/set-up-the-ticket-tree.md, and the v6 migration describe the new store config; the migration no longer creates one. For existing installs - A project file that is a whole copy of an old starter still overrides the new verbs until it is cut down to store, the address fields, and what the team changed. - An override that sets refinement, container_definition, prose, or publication = "auto" no longer has an effect. - Anything that read drift as true, or called read_toml.py, needs updating. |
||
|
Brian Madison
|
f5412e3077 |
feat(ticket): let a ticket or epic id be letters and digits
An id was an integer only, so a v6 split story such as 2.6a could not keep its id and tickets.py refused the whole tree. An id is now a number or letters and digits, unique in its tickets.toml and never rewritten. A quoted number in after is still a tracker id. |
||
|
Brian
|
5b05098b9f |
fix(ticket): resolve the reported ticketing issues (#2986)
* fix(ticket): resolve the reported ticketing issues Closes #2963, #2964, #2972, #2976, #2980, #2939, #2933, #2973, #2969. Answers #2971 and the BOM/CRLF part of #2725. * fix(ticket): address review findings on the cross-epic checks and refined wording Report an undeclared epic once when a story's after and its epic gate both name it, and check an epic file's own gate for build order before the epic has stories. The file-name error in after now fits unpulled siblings and epic gates. estimate.md no longer reads refined in the old sense, and code review treats an empty baseline_revision as unset. * fix(ticket): give tickets whose titles slug alike their own file and plan Transliterating accents made titles such as "Café menu" and "Cafe menu" share a name. pull and the plan path now add the entry's id when a file or an earlier entry in the folder has the name. bmad-spec keeps the configured run_folder_pattern inside a caller-named folder. |
||
|
Brian
|
0d499b9b82 |
feat(bmad): setup cleans up renamed and removed skills; help loads only for help requests (#2981)
* feat(bmad): setup cleans up renamed and removed skills, updates and migrates in one flow Modules list renamed and removed skills in a retired.toml beside bmod.toml, replacing removals.txt. Setup moves _bmad/custom files of renamed skills, offers to delete retired skills in project and global folders and drop them from the skills CLI lock, and offers the new name's install. It reads every active skills root, reports duplicates and skills a module ships that are not installed. Setup, status, update, repair and doctor are one flow in setup.md: check and report, then update the skills, answer new config questions, refresh _bmad, clean up, and run a detected migration on request. bmad-preview-ticketing's forwarder is removed. * refactor: make active_initiative a core setting Initiatives are not specific to the method: core skills such as brainstorming, research and party mode write into the initiative folder too. The key moves from [modules.bmm] to [core], and core help now explains initiatives for any module; method help keeps only what the method puts in the folder. * refactor(bmad): split help out of SKILL.md and load module help only for help requests SKILL.md keeps the persona and routes setup, migrate and initiative actions to their references without loading module help. Help and conversation load every installed module's help with knowledge.py first, then follow the new references/help.md: see where the project stands, answer only from module help, and run skills or a sequence of them on request. * fix(bmad): skip tool skills folders linked outside the project; setup-run migrations verify * test(bmad): point USERPROFILE at the test home so the global cleanup test runs on Windows |
||
|
Brian
|
b5420009c4 |
refactor: rename bmad-preview-ticketing to bmad-ticket (#2979)
* refactor: rename bmad-preview-ticketing to bmad-ticket The ticketing skill is no longer a preview; it is how BMad plans and tracks work. Rename the skill, update every reference, and drop the preview wording from the docs. The setup page moves to set-up-the-ticket-tree with a redirect from the old URL. * feat: forward bmad-preview-ticketing to bmad-ticket until v7 npx skills update does not install a renamed skill. Keep the old name as a forwarder that tells preview users about the rename, gives the install command, offers to rename their custom override file, and hands the request to bmad-ticket. Add a Breaking changelog entry. |
||
|
Brian
|
561eeedf38 |
feat(skills): retire planning and implementation artifact folders for the initiative store (#2968)
* feat(skills): retire planning and implementation artifact folders for the initiative store
Every document skill now writes into the active initiative under `output_folder`, as `<type>-<slug>/<type>-<slug>.md`, where the slug is what the document is about. `planning_artifacts` and `implementation_artifacts` are no longer read or seeded; a v6 project moves its files with `bmad migrate method`. The `bmad` skill gains `references/initiative.md` to show, switch, create, or clear the active initiative, and its help view reads the initiative folder instead of the retired paths. The repo's `CLAUDE.md` shim is removed, since Claude Code reads `AGENTS.md` natively.
* fix(ticketing): tickets live in output_folder, help runs the resolver, linter names the spine
Drops the ticketing store's separate root: the ticket tree is always {output_folder}/{active_initiative}, beside the documents, so an initiative created by the bmad skill is the one ticketing finds. The bmad help view now runs resolve_config.py when _bmad/config.toml exists instead of reading the user file alone. lint_spine.py reports the spine file, not the dependency name, for an unpinned Stack row.
* fix(docs): name the loose-work location where only the initiative folder was given
The brainstorming headless return reports the configured intent document name. The party-mode help row and four build docs say where files land when no initiative is active.
* docs: bring the English docs onto the initiative layout
The planning-skills diagram names the <type>-<slug>.md files. Planning pages state the output-folder fallback. The bmad skill replaces bmad-help everywhere, and the reference page says it also runs setup, status, migrate, and the active initiative. The v6 preview page leads with bmad migrate method. Tutorials install with the skills CLI and bmad setup. Config pages say where active_initiative lives and that output_folder carries the ticket tree. Loose path slips fixed, and an Unreleased changelog entry added.
|
||
|
Alex VerkhovskyandBrian Madison
|
5e33d3c03b |
feat(ticketing): build from the ticket tree without ticket files (#2944)
* docs(ticketing): shared rules for skills that use the ticket tree
Plan file name and place, status carried by the plan and who writes each value, how skills find the tree and run tickets.py, the baseline revision, and where code review and the retrospective write.
* docs(ticketing): backlog plans join by file stem, and a leaf file's status is read when there is no plan
* feat(ticketing): entries start without a file and take their state from the plan
* chore(tools): treat _bmad/method/scripts/ as install-only in the file reference check
* feat(ticketing): tickets.py is installed for every skill and finds the active initiative
* feat(ticketing): find and mark work on an entry that has only a plan
* docs(ticketing): board rules say who moves a ticket
* docs(ticketing): drop pull-to-start and the plan section
An entry is ready to start with no file, and the build's plan is its own file beside the leaf, so the ticketing skill stops describing a ## Plan section, a to_pull group, and publishing on pull. pull is only for refining, or for writing the file a tracker receives. On the repo store the committed tickets.toml is the publish; on a tracker publication is on_start or at_inception and the whole file is sent. spec_checkpoint becomes plan_checkpoint.
* docs(ticketing): method help and docs describe the ticket tree without ticket files
* refactor(ticketing): share tickets.py checks and test setup, and fix stale tree wording
* test(ticketing): decode tickets.py output as UTF-8, and skip the undecodable-argument test on Windows
* refactor(build): the build skills call their output a plan
Rename the build's output from spec to plan in bmad-build and bmad-build-auto with no change in behavior: plan-template.md, {plan_file}, [workflow] open_plan (no alias), bad_plan, Plan Change Log, plan-{slug}.md, source_plan, and the halt strings that name it. bmad-build records baseline_revision in place of baseline_commit. bmad-spec's spec_folder and SPEC.md keep their names. The renderer's open_plan label and the render tests follow, and a test renders both build skills with each pinned route.
* feat(build): bmad-build builds the next ready entry from the ticket tree
With no argument, bmad-build takes the first ready entry from tickets.py next,
reads it through find, and plans beside tickets.toml with the entry's ticket id.
Builds now stop at a new status, built, and never write done. tickets.py rows
carry a ref that find resolves, and a prerequisite in review counts as met.
* feat(build): bmad-build takes a named ticket and offers started plans from the tree
* refactor(build): bmad-build stops reading the old files
Drop the stories.yaml route, story_key and the sprint-status sync, and the
epic context compiled from the epics file. A tree ticket reads its epic file
and References, and takes continuity from its prerequisites' plans.
* feat(build): bmad-build-auto builds one ticket from the tree
With no work named, bmad-build-auto takes the active initiative's next
ready entry through tickets.py next and find; a named ref, ticket file,
or title resolves through find. Its plan lands at find's path with
ticket and baseline_revision, continuity comes from the plans of the
entry's prerequisites, and the run ends at built, never done. The
epic-story path no longer halts on an earlier plan in review.
* refactor(build): bmad-build-auto halts into the plan and stops reading the old files
A halt on a tree ticket runs tickets.py mark, which records the blocked
status and reason in the plan and creates it when there is none. Drop the
stories.yaml folder+id dispatch and the epic context compiled from the
epics file. bmad-build shows a blocked plan's reason and halts.
* docs(build): the loop contract describes bmad-build-auto on the ticket tree
* docs(build): the build docs and diagrams name the plan and take a ticket from the tree
* refactor(build): sweep stale story wording from the build skills and drop the dead open_plan clause
* fix(build): bmad-build-auto builds only what it is dispatched
An unattended worker must not choose its own work. Given no work it now
halts unclear intent instead of taking the first ready ticket from
tickets.py next; the orchestrator names each ticket.
* fix(build): bmad-build-auto takes a ticket only when the prompt names one
A bare ref, path, or title matched by shape could be something other
than a ticket, and was sent to find. A ticket is now a reference the
prompt calls a ticket, or a file whose frontmatter type is a ticket
type; find then resolves its plan, entry, and prerequisites.
* refactor(build): bmad-build names a ticket, then resolves it with find
Separate what counts as a ticket from the find call that resolves its
plan, entry, and prerequisites, as bmad-build-auto now does. No change
in which prompts count as a ticket.
* feat: review and retrospective from the ticket tree (#2954)
* feat(code-review): find the ticket in review through the tree and write to its plan
With no argument and nothing in the conversation, bmad-code-review runs
tickets.py status, offers the tickets in review, resolves the chosen one
through find to its plan, diffs from the plan's baseline_revision with
untracked files, and takes the claims from the commits since it. Findings
go into a dated block under the plan's Code Review section, deferred
findings included. The sprint-status tier, story_key, and the status and
sprint-status update are gone: the skill never changes a ticket's status.
* refactor(code-review): call the review's input a plan and drop the story-file route
Rename {spec_file} to {plan_file} with no alias across the steps, the
customize.toml lens and comment, and the render test. Findings go to the
plan's Code Review section whenever a plan is set and to the chat
otherwise; the baseline_revision detection, the Tasks/Subtasks condition,
and the Review Findings route are gone. The no-spec review mode becomes
no-plan, and the rule in step-04 names built as the status the build
leaves.
* feat(retrospective): read an epic folder from the ticket tree and write its retrospective there
* refactor(code-review): shorten the plan-file and ticket-tree tiers
* refactor(retrospective): drop the sprint status route, its script, and its tests
* refactor(correct-course): stop reading the epics file and writing sprint status
* docs(review,retrospective): describe code review, retrospective, and correct-course on the ticket tree
* refactor(review,retrospective): sweep duplicate rules and stale references from the epic
Say the retrospective's file name, only-write rule, and unfinished-ticket
verdict once each; describe git_evidence.py's output as the range's commits;
fix cross-references that named a missing workflow.md, a Close phase, a
Document Project input, and a step where a section or item was meant; and
align the finish-an-epic doc and help row with the plan as the status record.
* fix(retrospective): end the last plan's range at the epic's own work
A retrospective run after later work has landed counted those commits as
the epic's, since the last range ran to HEAD. When later work has landed,
the range now ends at the last commit belonging to this epic's tickets,
and the cut is recorded.
* feat: retire the legacy planning route and migrate ticket state (#2955)
* feat: retire the legacy planning route and migrate ticket state
* docs: drop the ticket-tree upgrade guide and changelog entry
Remove docs/start/upgrade-to-ticket-tree.md, its inbound links, and its
locale-coverage baseline entries. Revert the Unreleased CHANGELOG section.
* docs: keep the translated workflow map diagram unchanged
Only the vi-vn, cs, and zh-cn workflow-map pages embed this diagram, and
their text still describes the previous route.
* fix(ticketing): move a leaf's plan with it, say epic tickets need no file, write test files as UTF-8
---------
Co-authored-by: Brian Madison <bmadcode@gmail.com>
|
||
|
Brian
|
a76af7f44e |
feat(ticketing): stable ids, build-owned status, plan section in the ticket (#2934)
* feat(ticketing): stable entry ids, after replaces blocked_by, table order is build order - tickets.toml: id replaces n and is never an order; table order is the build order; after lists real prerequisites only, as a sibling id, <epic id>.<entry id>, or epic-<slug> - leaf files are <type>-<slug>.md, joined to their entry by frontmatter id; no numbers in names - tracker keys move to tracker_id; the repo store drops KEY-n ids and the key prefix - pull writes only the fields the entry sets; mark adds or removes lines as needed - templates, references, store configs, help files, and the preview doc follow * feat(ticketing): status belongs to the build, tracker_status beside it A leaf's `status` is the build's (draft, ready-for-dev, in-progress, in-review, done, blocked) or dropped; a pulled file has none, so a tracker's status can never make the build skip planning. On a tracker store `query` mirrors the tracker's status into `tracker_status`, which `write` never sends back. tickets.py derives a `state` per ticket for `next`, `status`, and the store maps; containers carry status only once work starts. The `checks.set` lens on builder self-sufficiency now says a gap is fixed in the epic or the references, not by lengthening the entry. * feat(ticketing): plan section in the ticket, refine pulls the file, find by reference Every leaf file ends with `## Plan`, the coding agent's section; `pull` writes it empty and the store configs send the body only up to it. Refining an epic's story now pulls its file when none exists and reviews the file with the user; once a file exists it is truth and the entry keeps only id, type, title, after, and hitl current. `tickets.py find <dir> <ref>` resolves `2.1`, an entry id, a tracker id, a file name, or title words to one ticket with its path, so the board and the builders name tickets the same way. * fix(ticketing): validate epic ids and slugs, bare numbers are sibling ids, find prefers its folder Review follow-ups on #2934. Every epic needs an integer id and a slug, duplicates of either are errors, and an epic's after must name an id or a slug. In `after`, a bare integer is always a sibling's id and a quoted string never is, so a numeric tracker id cannot be mistaken for a sibling. `find` prefers the folder asked about when a file name exists in more than one epic. Docs: a changed `after` is written to both the file and the entry; the store configs resolve a local ticket through `find` instead of grep. |
||
|
Brian
|
ba252f1b33 |
feat(ticketing): tickets.toml, cross-epic blockers, optional refinement, dependency check before approval (#2932)
* feat(ticketing): plan epics in tickets.toml and check dependencies before approval - An epic's planned stories live in tickets.toml beside the epic file; an initiative's holds its epics in build order. Containers have no Breakdown section. - blocked_by accepts an entry or a whole epic in another epic; next and status work on an initiative and report gated_by, drift, and unpinned_after. - tickets.py pull writes the ticket file from its entry, with references and notes. - Refinement is optional: only an entry with refine = true or a ticket with no epic is refined before it starts. Spikes are added on request. - checks is one array per scope and appends across layers. checks.dependencies finds missing blockers, and the check runs on the draft before the user approves it, for epics and for stories. - Work that fits one epic is proposed as one epic. - Shared decisions go to the architecture spine or the opening epic; touch points, Source conflict notes, and a closing refactor sweep are recorded. - bmad-spec hands story breakdown to bmad-preview-ticketing and no longer writes stories.yaml. * docs(ticketing): keep an entry and its pulled ticket in step for every field * feat(ticketing): let a container name its own tracker project or team * fix(build): treat a ticket file as intent, never as a spec to resume * feat(ticketing): refining reviews the entries; full criteria only for bugs, tickets with no epic, or on request * fix(ticketing): review findings on pull output, store queries, builder intake, and preview docs * fix(ticketing): stop when an old string checks override empties the dependency checks |
||
|
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. |
||
|
do-operatorandClaude Opus 5
|
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
|
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
|
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. |
||
|
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. |