mirror of
https://github.com/bmad-code-org/BMAD-METHOD.git
synced 2026-11-03 05:51:59 +08:00
main
96
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
|
dc9fbb14f3 |
feat(core-tools): add bmad-shard-pro and bmad-ingest (#3161)
* feat(core-tools): add bmad-shard-pro to make long documents navigable for agents
Assesses a long document and recommends leaving it, adding a contents list
with line ranges, splitting it word for word into a map and shards, or
rewriting unstructured input (transcripts, chat exports, notes) into cited
subject shards. shard_tool.py outlines, converts, builds, maps, indexes and
checks: faithful splits rebuild the source exactly, rewritten statements must
cite real source lines or cues, and maps stay within the first 200 lines.
The original is kept frozen in .source/ and updates go through the skill.
Registers the skill in bmod-core-tools and its help, updates the prfaq
artifact analyzer for the new sharded layout, and documents the skill.
* refactor(core-tools): narrow bmad-shard-pro to faithful outcomes
Shard-pro now leaves a document, adds a contents list with line ranges, or
splits it word for word; it never rewrites content. The rewrite path, its
writer and checker subagents, derived shards, citation checks and the
convert command are removed. Transcripts, chat exports and email threads go
to bmad-ingest, and other formats are converted to markdown first.
Adds trigger and baseline eval cases for the skill.
* feat(core-tools): add bmad-ingest to turn raw input into cited notes
bmad-ingest turns a transcript, a chat or email thread, a voice memo or a
long document into a note an agent can act on instead of the raw. The
original is kept unchanged in {output_folder}/raw, every item in the note
points back to where it sits in the raw, and a review pass checks the note
against the raw before it is done. Another skill can call it and link the
note it returns, so a PRD's inputs land in its own sources/ folder.
Notes follow templates chosen by their description. Core tools ship meeting,
thread, voice-memo, document and one-on-one; the method module adds standup,
retrospective, sprint-review, discovery-workshop and user-interview. Teams
add their own in _bmad/custom/ingest-templates, people in
~/.bmad/ingest-templates, or any module in an ingest-templates folder.
The template lister moves into the shared scripts as list_templates.py, with
--folder for the folder a module ships, category in its output, ~ expanded,
and missing local paths reported. Shard-pro recommends bmad-ingest.
* fix(core-tools): tell bmad-ingest to rerun setup when the template lister is missing
* fix(core-tools): address review findings in shard-pro, ingest and the template lister
shard_tool.py: a rebuild reads the frozen copy even when the main file sits
at the original path; build refuses to overwrite a file it did not write or
to give a shard a name it writes itself, and gives clashing sub-map names
distinct pages; a plan must start at the top, hold shards and fit each map
page in the reading window; a closing fence must match its opener; a
contents refresh stops when a section's first line now matches two places;
check warns about links the split moved away from their targets.
bmad-ingest gives notes for different raws distinct names. The template
lister decodes GitHub paths before encoding them, and its home-folder tests
set USERPROFILE for Windows. The ingest reference entry is split into short
sentences.
* fix(toolsmith): make eval fixtures portable and refuse absolute paths
run_evals.py accepted absolute fixture paths in its format doc but refused
them when staging, so such cases crashed, and a missing fixture only warned
before running the case without its input. Fixtures are now paths relative
to the project root or the cases file, or a GitHub file URL pinned to a ref,
fetched through gh into the run folder. Absolute and ~ paths and missing
fixtures stop the run before any case starts, with a message saying why.
scan_paths.py now checks the fixture entries in a skill's eval cases, and
leaves ~/.bmad/ alone as BMad's own per-user folder. The shard-pro cases
point at the sample-data repo at a pinned commit instead of a local path.
* fix(toolsmith): refuse fixtures that would land on one path, and lint fixtures as the runner does
Two GitHub fixtures with the same file name landed on the same workspace
path, so one silently replaced the other; the runner now stops before any
case runs. scan_paths.py checked eval fixtures with its general absolute-path
pattern, which missed /tmp paths and let ~/.bmad through; it now applies the
runner's own test, so lint catches every fixture the runner would refuse.
* fix: confine fetched eval fixtures and keep ingest from overwriting files
run_evals.py refuses a GitHub fixture URL whose path or ref holds '..', and
writes each fetched file only inside the run's fixtures folder. bmad-ingest
gives a second original with the same date and slug its own raw name, never
writes a note over a file that is not this raw's earlier note, and, when the
template lister is missing, asks the bmad skill to update the install rather
than only rerunning setup from an old copy.
* docs(core-tools): add help topics for ingest and shard-pro and how they fit together
help/ingest.md and help/shard-pro.md give the help agent what it needs to
suggest each skill and answer questions about it. help.md routes between
them: raw input to ingest, a kept document to shard-pro, preparing large
inputs before a PRD or other planning work, and giving a sharded document to
any skill as its main file. The method help says the same for planning
skills.
|
||
|
Brian
|
fc6a41c673 |
feat(toolsmith): default to a single-skill module and start prose from one sentence (#3158)
* feat(toolsmith): make a single-skill module the default for one skill Registration is settled from the registry and shown in the read-back instead of asked. A skill joins a module only when the user is working on that module, named it, or chose its prefix. A bmod-<code> record folder is never written for one skill. * fix(toolsmith): ask whether a skill is part of a module Single-skill module stays the offered guess, but discovery now asks whether the skill joins a module or more skills are planned. A planned module settles its code and prefix on the first skill, so nothing is renamed later. * feat(toolsmith): read any agent's session logs and offer customization in from-logs The agent finds its own logs and confirms the location instead of assuming Claude Code. A corrected installed skill can be offered as a bmad-customize change instead of a new skill. * refactor(toolsmith): split discover into short sections and cut what a model infers Registration gets its own section, the five things and other enumerable items become lists, and the read-back carries the consumer and bar. * feat(toolsmith): start prose from one sentence and hold one topic to a paragraph The canon, leanness lens and cut roles now default to the one-sentence version of a passage and split mixed topics. The pre-pass reports long paragraphs and sentences. * refactor(toolsmith): cut prompt files to one topic per paragraph and inline ecosystem into ship Every route, mode and shape file is split into short paragraphs, bullets and cases, with what a model would infer removed. ecosystem.md only ever loaded from ship.md, so its content now lives there. * feat(toolsmith): let a memory agent add its name to its description at First Breath * fix(toolsmith): close a Markdown fence only on its own marker in the pre-pass * fix(toolsmith): let a single-skill module grow into a multi-skill module * fix(toolsmith): write dependencies to the table the module shape uses * feat(toolsmith): restore a memory agent's name after an update and skip global installs * docs(toolsmith): bring the help up to date and route to cut mode * refactor(toolsmith): call the read-back the Smithy execution plan and add help on sharing and subagents * docs(toolsmith): write the Toolsmith docs to replace the builder site |
||
|
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
|
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
|
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
|
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>
|
||
|
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
|
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. |
||
|
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
|
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
|
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
|
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 |
||
|
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.
|
||
|
BrianandAlex Verkhovsky
|
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> |
||
|
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
|
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. |
||
|
Brian
|
cf54f4d76d |
refactor(bmm): consolidate sprint skills — one owner for the sprint-status artifact (#2659)
* refactor(bmm): move sprint-planning and sprint-status to plan/ They sit at the plan/ship boundary and their outputs are planning artifacts of the dev cycle; next commit makes sprint-planning the readiness gate, which is plan-side work. * refactor(bmm): fold readiness gate into sprint-planning, retire check-implementation-readiness The old skill was 1,154 lines of legacy numbered-step ceremony whose document discovery hardcoded filename globs (*prd*, *ux*, *epic*) that miss what current skills produce (SPEC.md, DESIGN.md) and still treated retired sharded docs as first-class. Sprint-planning now opens with a lean readiness gate: generic artifact discovery by content, forward/back traceability, PASS/CONCERNS/FAIL, stop on FAIL with findings. The IR trigger on John's and Winston's menus dispatches sprint-planning, so 'check implementation readiness' still works everywhere it used to. * refactor(bmm): modernize sprint-planning with deterministic script core SKILL.md drops the legacy XML step dialect for the product-brief style (~100 lines, uv run, headless contract). New scripts/sprint_plan.py owns the mechanical work — epic parsing, key derivation, ordering, preserve- never-downgrade merge, story-file detection, action_items carry-over, atomic writes, drift checks — with 11 tests wired in as test:sprint-planning. Judgment stays with the LLM: epic discovery, the readiness gate, and reconciling script-reported orphans and unparsed headings. checklist.md retired (the script performs that checklist); sprint-status-template.yaml is the single source for the status vocabulary. Output stays byte-compatible with build's sprint sync and retrospective's tooling. * refactor(bmm): fold sprint-status into sprint-planning's status view sprint_plan.py gains a status subcommand: counts (legacy values mapped), risk flags, open action items, and a priority-ordered next-action recommendation — the old skill's inference-driven summary, computed deterministically and covered by 9 new tests. bmad-sprint-status becomes a v6-shims husk that forwards with status-view intent and a deprecation notice; its dead data/validate modes had zero callers and are gone. If a hand-edited status file defeats the script, the skill falls back to reading it directly and summarizing by best judgment. New explanation page docs/explanation/sprint-planning.md covers the consolidated skill; workflow maps and references updated across all languages. * docs: changelog entries for skill reorg and sprint consolidation * fix(bmm): harden sprint_plan.py per review; add validate/fix intents with full progressive disclosure Review fixes (PR #2659 findings, bot + internal review): - Normalize legacy v6 statuses (drafted/contexted) on every read — merged by meaning and reported, never treated as illegal or reset - dropped_orphans carry their old status; transplant renames via --set - project_key/tracking_system/story_location preserved from the existing file unless overridden; refresh round-trips custom keys and user comments - Hardened write path: dump-to-bytes, fsync, permission-preserving atomic write inside the guarded block, explicit checks (no asserts), atomic restore - JSON-only argparse (errors and -h emit JSON); unicode-aware slugs with hash fallback; fenced code blocks ignored when parsing epics - Odd retro keys, date-typed stamps, and non-mapping YAML report cleanly instead of crashing; unparseable timestamps warn instead of silently disabling the staleness check; malformed action items flagged, not dropped - Dead check subcommand removed; generate --dry-run reports drift/in_sync - test:sprint-planning wired into quality and CI (was test-only) - Retro tests use a vendored template fixture (PATH-05); repo-level test-template-sync.js keeps it byte-identical to the source; template example timestamps and story_location fixed; header block pinned to the template by test New capability: - validate subcommand + reference: structural validation, never writes - fix flow: evidence-gathering subagents -> user-confirmed state table -> generate --fresh --set writes a pristine file (the one path allowed to downgrade); universal script-failure fallback to inference for every intent - SKILL.md is now a lean router: gate, tracking, status, fix, and validate each load as progressive-disclosure references Docs: explanation page gains Repair section; workflow-map and getting-started across all five languages mention the status view; headless payload nests under 'report' to avoid the status key collision; changelog updated. Test suite grows 20 -> 37; retro suite 91/91; docs build and validators green. * docs: mention repair in sprint-planning explanation description |
||
|
Brian
|
57ad793167 |
refactor(bmm): reorganize skills into agents / plan / ship; retire tech-writer agent (#2658)
* refactor(bmm): move agent skills into agents/ * refactor(bmm): collapse phase folders into planning/ and shipping/ Skills reorganize from numbered pipeline folders (1-analysis, 2-plan-workflows, 3-solutioning, 4-implementation) into two sets: planning/ and shipping/. Path and phase-label references updated across marketplace.json, module-help.csv, tests, and bmad-help; also trues up two marketplace paths that were stale on main (create-story/dev-story already lived in v6-shims). * refactor(bmm): shorten skill folders to plan/ and ship/ * refactor(bmm): retire tech-writer agent (Paige on hiatus) Paige's capabilities were generic LLM defaults with no domain substance; her one real menu item (DP) dispatches bmad-document-project, which stays directly invocable and remains on the Analyst menu. Added to removals.txt so installs clean up, and docs (all languages) carry a hiatus notice — she returns in the future far more capable. |
||
|
BrianandAlex Verkhovsky
|
e9f636c1f7 |
feat(bmm): rework bmad-retrospective as an evidence-based epic review (#2612)
* feat(bmm): rework bmad-retrospective as an evidence-based epic review Replace the persona-meeting simulation with an evidence engine that mines what a completed epic actually left behind — spec, full diff, per-story commits, sprint status, and session logs — instead of simulating a team that "remembers." Every finding carries a source reference. - Five-phase flow: Gather -> Analyze -> Decide -> Close. Analyze derives aggregate views (architecture delta, duplication, god-class growth, pattern divergence, spec reconciliation) and reuses bmad-review for the diff-scope code lenses rather than reimplementing them. - Acceptance verdict (accepted / accepted-with-open-items / rejected); a failing epic can never close as silently accepted. - Team discussion is now opt-in and off by default, delegating to bmad-party-mode seeded with the real findings. - Add deterministic scripts: sprint_status.py (epic detection plus a comment-preserving, force-quoting, validate-and-restore sprint-status.yaml update) and git_evidence.py (range / commit / size-trajectory measurement), with a pytest suite. - The retrospective document is the working artifact: built early, filled per phase, and resumable. Adds a headless mode (-H) with assumption capture. - SKILL.md drops from ~1527 lines to a lean spine plus five references. * fix(bmm): harden retrospective scripts for orchestrator use Address review feedback on the evidence-based retrospective (PR #2612) from CodeRabbit and the bmad-loop maintainer. All changes are additive — no existing JSON field or CLI argument that a consumer reads is renamed or removed. - detect-epic: STORY_RE now matches split-story keys (2-6a-...), aligning with bmad-loop's sprint-status detection; previously such an epic was invisible and a headless run could retro the wrong epic. - sprint_status/git_evidence: argparse failures now emit JSON on the documented stdout contract instead of plain usage text. - sprint_status: guard non-list action_items (clean JSON error, no traceback); _restore reports success/failure so a failed rollback is surfaced, not hidden. - action_items entries carry a stable id and a ref to the retro document, so an orchestrator can dedupe across re-runs and dispatch each sourced finding. - update echoes the acceptance verdict in its JSON; the retro key value stays "done" for existing lifecycle consumers. Retro doc gains machine-readable frontmatter, and -H <epic> is documented as the stable automation interface. - evidence-gathering: derived range now includes the first story commit (<first>^..<last>); aggregate-views drops the size/acceleration overclaim. - Tests: split-story detection, non-list guard, restore reporting, argparse JSON, and id/ref/verdict coverage (13 pass). * docs(bmm): refine retrospective party-mode phrasing * docs(bmm): document the reworked retrospective - Add docs/explanation/retrospective.md — a short feature page: what the skill does, why to run it after an epic, and what to do with its output (retro document, action items, acceptance verdict). - Update the workflow-map retrospective row to reflect the evidence-based review and its actual outputs instead of "Lessons learned." * fix(bmm): validate git_evidence --range as a strict revision range An unvalidated --range reached the git argv unchanged: a value starting with "-" was consumed by git as an option, a single rev logged all history up to it, an existing path was consumed as a pathspec, and a file named like a range (a..b) was silently logged as one — each returning a confident, wrong evidence set with exit 0. Reject anything that is not an explicit REV..REV form — including empty endpoints ("..", "a..", "..b"), which git silently defaults to HEAD, and unstripped values — and terminate the git argv with "--" so a range-shaped name is always parsed as revisions, never as a pathspec. Drop the root-commit special case from evidence-gathering.md: its wording steered into a bare-rev invocation now rejected, the scenario (an epic starting at the repository's first commit) is vanishingly rare, and an agent that ever meets it can still construct a shape-valid range itself. Document the exit-code split (2 invalid args, 1 git failure). Every rejected mode is covered by regression tests; git error-string assertions are pinned to LC_ALL=C. * fix(bmm): harden sprint_status.py input validation and atomic writes Nine findings from the PR #2612 review of the reworked retrospective, all reproduced against the previous behavior: - Pin the emitter indentation so a round-trip stops de-indenting pre-existing, untouched action_items; the sprint-status template now survives an update byte-identical apart from last_updated. - Keep malformed input on the documented JSON-to-stdout contract instead of a traceback: shape-check the root document and development_status on both subcommands, widen the file open from FileNotFoundError to OSError, and report invalid UTF-8 as a JSON error. A non-mapping development_status previously reported ok:true while doing nothing. - Validate comment preservation against the whole file's comment lines rather than only the leading block matched by substring, so a lost mid-file comment fails the write and restores. - Write atomically through a temp file, fsync and os.replace, resolving symlinks and carrying the target's mode across. The rollback goes through the same path: a truncating rewrite that died halfway used to destroy the bytes it was restoring. - Stop inserting an empty development_status mapping, and report retro_key_found: null when --set-retro-done was not passed, reserving true/false for "flag passed, key present/absent". - Include restored:true on every update failure that precedes the write. - Make _slugify Unicode-aware with a content-hash fallback, so non-Latin action text no longer collapses to the literal "item". - Reject an --add-action item whose action is empty or not a string. - Validate --date against MM-DD-YYYY HH:MM and normalize it, since strptime otherwise admits unpadded spellings. Each fix is pinned by a subprocess-level regression test; the suite goes from 18 to 49 tests. * feat(bmm): add action-item status updates to sprint_status.py The update subcommand could only append, and retro-document.md forbids hand-editing sprint-status.yaml, so nothing anywhere could move an action item off open. bmad-sprint-status renders every open and in-progress item on every call, so retrospectives accumulated permanently-open noise. Add --set-action-status, taking a JSON array of transitions for items already in the file. Each entry selects one item by id, or by epic plus exact action text for legacy entries written before ids existed, and gives it one of open, in-progress, done. Selectors resolve against action_items as loaded and strictly before the --add-action append, so an item added in the same run is not addressable in that run. Validation is all-or-nothing and entirely pre-write: a selector matching nothing, matching more than one item, colliding with another entry, or carrying a status outside the vocabulary aborts the whole invocation with restored: true and the file byte-identical. After the write the file is re-parsed and every targeted item is confirmed to carry its new status. Success reports the new action_items_updated count. Rewrite the contradicting paragraph in retro-document.md so the flag is the one sanctioned path to change a status: offer the transitions when the Phase 4 follow-through has evidence an item landed, apply only what the user confirmed, and never touch prior statuses in a headless run. * fix(bmm): measure renames, merges, and binary churn in git_evidence Five ways the measurement was quietly wrong: - Renames emitted an unopenable "src/{a => b}" pseudo-path and split one file's churn across up to three keys; non-ASCII paths arrived octal escaped. Both passes now run with core.quotePath=false and --no-renames, so a rename is an honest delete + add and a path is a real string that opens. - Merge commits emit no numstat rows, so cross-story conflict-resolution churn vanished with nothing saying it had been skipped. The listing pass keeps full topology (per-story attribution is unchanged); a second pass measures merges alone under -m --first-parent --min-parents=2 and reports merge_files, merge_count and merges_measured. Merge churn is never folded into files: a merge's first-parent diff restates the churn of the commits it merged in. - A commit naming two stories attributed to whichever id was passed first. Every matching id is now collected, so a seam commit counts for both stories. commits[].story becomes commits[].stories. - A git failure with empty stderr reported "error": "". It now falls back to the exit code. - One binary revision of a path nulled its added/deleted/net, dropping real measured text churn from the ranking. The text sums survive and binary_revisions reports the exposure beside them. log.diffMerges is pinned to separate on the command line, because a user config of off makes the merge pass emit no rows at all. Git output is decoded with surrogateescape rather than replace, so two distinct non-UTF-8 paths cannot collapse into one key. evidence-gathering.md documents the changed output. 19 subprocess-level tests over real git fixture repos cover every case above; the suite goes 81 -> 100. * feat(bmm): add a pending-stories gate and align the retrospective docs `detect-epic` now also reports `pending_stories` — the selected epic's story keys that are not `done`, scoped to that epic alone — and SKILL.md branches on it before Phase 1: interactively the user is shown the list and may decline, headless the run proceeds and records the list as an assumption. An epic supplied on the invocation skips detection, so the instructions say plainly that the check did not run rather than implying it did. Both scripts are built with `add_help=False`. `-h`/`--help` previously printed argparse's usage text on stdout and exited 0, breaking the JSON-only stdout contract the scripts sell to their machine consumer; help is now an ordinary unrecognized argument routed through the existing JSON error path. SKILL.md also gained the branch for a `detect-epic` that exits non-zero, which is the normal path for a stories-mode project with no sprint-status.yaml. The references are brought back into agreement with what the scripts do after the last three batches: the close-out invocation quotes its values and pins the `--date` format that now hard-fails a non-conforming value; the result JSON documents `retro_key_found: null` and which failures carry `restored`; the retro key is stated to read `done` even for a rejected epic, so a verdict-aware gate must read the document frontmatter; Phase 3 gains an inline fallback when bmad-party-mode is absent; Phase 4 specifies the previous-retro follow-through record the close-out consumes; and the god-class view is rewritten for the current git_evidence keys. Suite goes from 100 to 111 tests. * chore(bmm): align retrospective script conventions and test harness Adopt the invocation convention the quick-dev and dev-auto skills settled on, and make the git_evidence test fixtures independent of the machine they run on. All five documented invocations become `uv run --no-cache`: the shared cache may be unwritable in a sandbox and may serve a stale build. Both scripts drop their shebangs entirely — they are only ever launched via `uv run`, so a shebang and executable bit are a false affordance; the PEP 723 blocks stay, since that is what uv reads. The encoding audit that change implies found one implicit site left: `_load_yaml` now pins the ruamel emitter's encoding, which is what encodes the bytes `_dump_bytes` writes to the user's file. `_git` and `_git_unchecked` passed an env of only the four GIT_* identity vars, so PATH and HOME were wiped and git resolved through os.defpath — the fixtures ran a different binary than the script under test, and failed outright wherever git lives only in /opt/homebrew, /usr/local or a nix store. Both now share a `_git_env` that inherits the environment, strips ambient GIT_* vars that would redirect or reconfigure the fixture, and pins identity, both gitconfig sources, gitattributes and the locale. `_run` parsed stdout bare, so a crash surfaced as JSONDecodeError with the real traceback hidden in the discarded stderr; it now routes through the `_json` guard the rest of the file already used. Both test files gain the repo's established runner footer and the PEP 723 header that makes it self-bootstrap under `uv run <file>`. No test's assertions change; the suite holds at 111 passing, and passes under a gitconfig setting commit.gpgsign, core.autocrlf, core.hooksPath and init.defaultBranch against it. * feat(bmm): aim detect-epic at a supplied epic and reject unfinished ones Unattended retros need the unfinished-story gate on the orchestrator path and a hard machine verdict when delivery is incomplete. detect-epic gains optional --epic N so -H <epic> can request the same pending_stories list auto-detect already returns for its picked epic. Non-positive values fail as JSON (exit 1). The skill now always runs detect-epic for a supplied epic with that flag, and the acceptance rubric forces rejected when pending_stories is non-empty — headless included; interactive humans may still override. Suite 111 → 115. * fix(bmm): harden retrospective script contracts after re-review - reject three-dot --range values in git_evidence.py: A...B passed the guard and silently measured a symmetric difference - move the directory fsync in _atomic_write past the failure path so a post-rename fsync error can no longer report "restored": true about a write that landed - validate --verdict against the frontmatter vocabulary and spell accepted-with-open-items one way across every machine-read surface - emit story_count from detect-epic so a typo'd epic number is distinguishable from a finished epic, and teach the SKILL gate to treat 0 as suspect - align the dev agent's ER menu description with the reworked skill * fix(bmm): reject typed retrospective statuses * docs: fix retrospective sidebar order * ci(bmm): run retrospective Python tests * fix(bmm): harden retrospective script execution Reject non-positive epic numbers before update processing. Keep explicit repositories authoritative when invoked from Git hooks. * docs(bmm): rewrite retrospective skill prose in plain language Remove invented metaphor and jargon from the skill's prompt surface (SKILL.md and references): witnesses/interrogates, testimony, seams, close-out, mining, and similar phrasing are replaced with plain equivalents. Rename Phase 5 "Close" to "Finalize" and the "Honest degradation" section to "Missing evidence", syncing cross-references. Industry-standard terms (god-class, churn) and BMAD vocabulary (declared/profiled, party mode) are kept. No operational rule, script contract, or verdict vocabulary changes. * docs(bmm): refine retrospective prose --------- Co-authored-by: Alex Verkhovsky <alexey.verkhovsky@gmail.com> |
||
|
Alex Verkhovsky
|
022bcbc66d |
Rename Quick Dev to Build (#2651)
* feat(bmm): rename quick dev to build * fix: address build rename review findings * fix: clarify deprecated build shims * fix: offer legacy customization migration |
||
|
Alex Verkhovsky
|
029ba287bc |
docs: make Quick Dev the canonical implementation workflow (#2643)
Rewrite published documentation and maintained translations around variable planning depth with one Phase 4 implementation loop. Update diagrams and AI indexes, and reject obsolete workflow terminology in deployable output. |
||
|
Alex Verkhovsky
|
116d52f5e0 |
feat: promote quick-dev to the official Phase 4 loop (#2637)
* feat(bmm): promote quick-dev to the official Phase 4 loop
- module-help.csv: bmad-quick-dev becomes the required Phase 4 item
(sprint-planning -> quick-dev -> code-review); the deprecated
create-story/dev-story rows leave the catalog; code-review and
qa-generate-e2e-tests chain after quick-dev.
- Dev agent menu drops its DS/CS entries.
- Docs and skill recommendations point at bmad-quick-dev instead of the
legacy split (architecture, ux, sprint-status, sprint-planning,
retrospective, named-agents, project-context,
expand-bmad-for-your-org, commands, workflow-map, getting-started).
The legacy skills themselves are untouched; deprecating them in place
is a follow-up PR.
- Quick-dev's user-facing descriptions (commands, workflow-map,
getting-started, help catalog, dev menu) drop the interactive-session
phrasing ("canonical implementation loop") for plain documentation
wording.
- bmad-retrospective: story-record scan also matches
spec-{epic}-{story}-*.md and quick-dev's section names, so retros see
quick-dev output.
- bmad-quick-dev: preserve an existing baseline_commit on resumed runs
instead of overwriting it with current HEAD.
* fix(bmm): address quick-dev review findings
|
||
|
Alex Verkhovsky
|
cfee292715 |
fix(dev-auto): move deferred findings into the spec (#2640)
Record deferred review findings only in spec frontmatter and remove the deferred-work output. Make updates safe for legacy specs and YAML-special content, strengthen contract coverage, and synchronize the reference docs. |
||
|
Alex Verkhovsky
|
c2530ea53f |
feat: add inspectable workflow snapshots (#2601)
Render complete dev-auto workflows into root-scoped immutable snapshots using shared declarative rendering and strict TOML configuration layers. Keep generated render state out of installer module discovery and custom file preservation, preserve quick-dev behavior, and provide deterministic Python version failures for standalone resolver use. |
||
|
Brian
|
bb45db4aa4 |
feat(core): consolidate research trio into bmad-deep-recon (#2611)
* feat(bmm): consolidate research trio into bmad-deep-recon
Replace bmad-market-research, bmad-domain-research, and bmad-technical-research
(5,136 lines of near-duplicate legacy step files) with one modern skill,
bmad-deep-recon (~650 lines):
- Research-master-orchestrator persona; conclusions never rest on training
data alone; lead-following rounds with coverage/novelty-exhaustion stops
- Six type packs as ~25-line policy+craft cards (market, domain, technical,
competitive, user-voice, academic-lit) + select decision shape layering a
weighted-matrix method over any type
- Three acquisition modes: Generate (subagent fan-out), Delegate (engine
registry: CLI/MCP, engine-first strategy), Import (provenance-tracked)
- Claims-ledger verification (normal/high/max) with independence rules and
optional red-team pass; cited synthesis with staleness map
- Effort presets (quick/standard/deep) over four knobs (subagents,
sources/round, depth, validation); precedence request > knob > preset
- Plan gate with surface discovery (MCPs/CLIs/engines), routing table, and
time estimate; use_workflows and subagent_models config
- Create/Refresh/Deepen intents, memlog run-folder workspace, headless JSON
- v6 shims forward the three old IDs with type pre-set; analyst menu,
catalog, marketplace, docs and translation mirrors updated
* feat(bmm): runtime output_format for bmad-deep-recon (v7 artifact protocol)
Replace the output_formats array with output_format = auto|html|md|both
(default auto): interactive runs render the HTML briefing, headless or
skill-invoked runs present the canonical markdown only. research.md always
exists in the workspace as the machine-readable report; the briefing is its
regenerable face. First instance of the v7 artifact protocol (memlog = truth,
md = distillation under contract, html = face).
* feat(core): move bmad-deep-recon to core-skills; address review findings
Move: research is not code-project-specific — home it in core-skills
(brainstorming precedent) so CIS and core-only installs get it. Skill ID
unchanged; standalone marketplace plugin added; catalogs moved to Core;
{planning_artifacts} falls back to {output_folder} on core-only installs.
v6 shims stay in bmm-skills (the legacy trio were bmm skills).
Review fixes (CodeRabbit):
- Engine briefs are now file-based: invoke templates substitute
{brief_file} (a skill-generated path), never inline brief text — quotes
and shell metacharacters in researched content can't shape a command.
- Refresh/Deepen preserve verification statuses for out-of-scope claims.
- HTML briefing: http(s)-only source links, escape source-derived text.
- user-voice pack: redact usernames/handles/emails from verbatim quotes;
communities complement surveys (triangulate) rather than beat them.
- engine.md: explicit single-writer rule — digests return to the lead,
which alone writes research.md in plan order.
* feat(core): deep-recon v2 — draft/process/run, faster defaults, research firewall
Rework after first real-run feedback (slow, token-heavy, locally biased
report, end-pass verification degraded quality, digests stranded in
subagent contexts):
- Three modes replace the acquisition-mode machinery: Draft (build a
deep-research prompt the user runs in their own subscribed tool),
Process (file a finished report into imports/, extract to digests/,
distill research.md summary + metadata so downstream never reprocesses),
Run (native fan-out, first-class). Bare research asks get the choice up
front with the trade stated honestly.
- Engine/Delegate registry cut: the Draft->Process round-trip is the
integration with dedicated deep-research tools; engine.md -> run.md.
- Files-first: digests hit {doc_workspace}/digests/ on landing, sections
commit per dimension, synthesis reads files never conversation memory,
dead runs resume from disk.
- Research firewall: persistent_facts default now empty, assistants get
only their brief, project context frames questions but is inadmissible
as evidence.
- Verification at landing, not end-of-run: normal = spot-check
load-bearing claims only; red_team default off; heavy passes behind
high/max. Presets rescaled faster (standard 3 subagents/8 sources/
depth 2).
- Multi-agent research lessons folded into run.md and the plan gate:
decomposition topology (breadth/depth/straightforward), per-assistant
tool-call budgets, query craft with OODA pause, shared source-quality
card, stop-and-write valve, mechanical citation check at finalize.
- Ripple: v6 shims, catalogs, marketplace, docs one-liners (all five
languages), template gains source: provenance field.
* feat(core): deep-recon quality pass — carve SKILL.md, recon_kit scripts, single-source verification
- SKILL.md 3989→2091 tokens: Draft/Process/Refresh+Deepen/Finalize carved to
references/{draft,process,lifecycle,finalize}.md; Run effort knobs + plan
gate moved into run.md; Overview and pack prose trimmed
- verification.md: red-team pass is the single adversarial mechanism (max
runs it at full breadth — no double-spawn); level semantics single-sourced
- scripts/recon_kit.py + tests: citations cross-check, memlog claim tally
(ref=/status= convention, last wins), staleness date math from per-class
windows, deterministic run-folder slugs, escaped source-appendix HTML
- Draft wired with preferred/banned source policies and an open-floor opening
- external_sources examples (Tavily/Sonar/xAI X-Search MCPs); source-quality
card: answer engines are aggregators — chase their citations
* docs: Deep Recon explanation page + integration
- new docs/explanation/deep-recon.md: three modes, mode-choice guidance,
research types, native-run internals diagram, firewall/verification, refresh
- analysis-phase.md research section rewritten for bmad-deep-recon
- core-tools.md: deep-recon in thinking-skills table, full catalog entry,
migration note for the merged market/domain/technical trio
- workflow-map.md + getting-started.md link the new page
- vi-vn developer guide: last stale old-skill flow mention updated
|
||
|
Brian
|
8b4da79161 |
refactor(core): group v6 shims and merge editorial review into bmad-review as lenses (#2608)
* refactor: group v6 deprecation shims into v6-shims folders Move the nine backward-compatibility forwarders into dedicated v6-shims/ folders so the deprecation set is visible in one place and can later be made an install-time include/exclude option before removal at the v7 cut. core-skills/v6-shims/: the five review and editorial husks bmm-skills/v6-shims/: the four PRD and architecture husks Grouping only — no content changes. The installer discovers skills by a recursive walk and installs each under its own name, so installed paths and skill IDs are unchanged. Verified by diffing a full headless install against main: identical .claude/skills listing and file content, and an identical _bmad tree. The only delta is the path column in skill-manifest.csv, which now records the new source location. External module repos (gds, loop, tea, bmb, os-utils) and enterprise users still invoke these IDs, so they continue to ship by default. * refactor(core): merge editorial review into bmad-review as lenses All reviews are reviews. bmad-editorial-review's two passes become two more bmad-review lenses, leaving one lens runtime instead of two skills with overlapping trigger descriptions — "review this document" matched both before, so which one ran was close to arbitrary. Lenses now declare what they apply to. applies_to is "code", "docs", or "any", and is the first filter on a default review; `when` still refines it in prose. adversarial stays "any" — it is a stance, not a subject- matter method, and is the lens a code/doc skill split could not have placed. edge-case-hunter's `when` was "always", which is why it would have fired on prose; it now gates on having a behavioral surface. A lens may also declare `after`, naming a lens it builds on: prose runs on top of the structure findings, as it always has. The runner announces the plan, runs the independent lenses (in parallel via subagents when available), then the dependent ones on their results. Lens wording is unchanged. The three code lens files are byte-identical; the editorial passes moved verbatim into references/lens-structure.md, references/lens-prose.md, and references/editorial-common.md, which carries what both share — the content-sacrosanct rule, style guide handling, reader calibration, and the findings table. That material used to load unconditionally; as lenses it loads just-in-time, so a code review no longer pays for it. bmad-editorial-review becomes the sixth v6 shim, forwarding with the structure and prose lenses named. It keeps its customize.toml so existing team and user overrides still resolve, and forwards them as pre-resolved values. The four other husks now name bmad-review and their lens explicitly. Each still pins its own legacy output contract. bmm's four document skills point doc_standards at the merged skill with named lenses. Docs updated across all five locales. Core is 7 skills. A headless install produces the same 47-skill set as main, with all six shims resolving. * fix(core): honor forwarded customization and de-hardcode the lens set Follow-up to the editorial/review merge, from review of #2608. Contract fixes: - bmad-review gains a Forwarded activation clause matching bmad-prd and bmad-architecture, so the bmad-editorial-review shim's pre-resolved fields are honored instead of being silently overwritten by the skill's own customize.toml. Existing bmad-editorial-review overrides resolve again. - The announce step is skipped when a caller pinned an exact output contract, and a forwarder's contract now governs everything emitted rather than the findings block alone. The edge-case (raw JSON) and verification-gap (one exact line) forwarders no longer get a prose line prepended. Lens set is no longer hardcoded: - The description and body intro present the shipped lenses as examples and point at whatever {workflow.lenses} resolves to. Docs carry a matching note in all five locales. Also: - Document the `lenses=` directive form in Inputs and in the four bmm doc_standards comments that use it. - module-help.csv review row rewritten to the house "Use to..." convention, naming the reviewable content types and the situations that should trigger a suggestion. - Shim customize.toml trimmed to a lean legacy-key surface with empty defaults, so unset keys fall through to bmad-review and project-context.md is no longer loaded twice. - Redundant `when` clauses dropped where applies_to already encodes the rule. - Core skill count corrected to seven/four and the edge-case applies_to cell fixed to match its actual value, across all five locales. |
||
|
Brian
|
c23f23400d |
feat: streamline core to an 8-skill set with merged review and editorial skills (#2603)
* feat: streamline core to a 5-skill kernel with standalone skill modules
Core installs 14 -> 5 catalog-visible skills; atoms exit to standalone
modules; installer gains real dependency resolution; zero npm deps.
- Merge bmad-editorial-review-prose/-structure into bmad-editorial-review
(structure models JIT-loaded, new customize.toml)
- Merge bmad-review-adversarial-general/-edge-case-hunter/-verification-gap
into bmad-review as selectable lenses; hidden husk-forwarders remain at
the old IDs (no catalog rows) so gds/loop/os-utils keep working
- Move bmad-brainstorming, bmad-party-mode, bmad-forge-idea out of core to
src/standalone-skills/ as single-skill modules; add bmad-analysis bundle
module (curated dependency list over the atoms)
- Move bmad-spec into bmm (2-plan-workflows)
- Modernize bmad-advanced-elicitation: uv run, customize.toml, methods
pick offloaded to scripts/pick_methods.py (with tests)
- Delete bmad-index-docs, bmad-shard-doc (removes the tree's only external
npm dependency), and the four deprecation shims (bmad-create-prd,
bmad-edit-prd, bmad-validate-prd, bmad-create-architecture); all added
to removals.txt
- Installer: activate the dependencies field (recursive union into
selectedModules, cycle-guarded, warn on unknown), config-driven picker
visibility; core stays force-installed
- bmm module.yaml declares deps on the three atoms
- Docs updated across all locales; new reference/standalone-skills.md;
shard-doc how-tos removed
* Restore original critical wording lost in the review/editorial merges
The merges into bmad-review and bmad-editorial-review were meant to keep
the source skills' critical wording behind progressive disclosure, not
paraphrase it away. Restore what was lost:
- lens-adversarial: clueless-weasel framing, extreme-skepticism wording,
the at-least-ten-issues quota, and zero-findings-is-suspicious (the
merge had inverted this to zero-is-valid)
- bmad-review SKILL: zero-findings stance is now per-lens
- lens-edge-case: mandatory exact-order step enforcement
- lens-verification-gap: exact 'No verification gaps found.' clean line
- editorial-review: full Human/LLM reader principles restored to new
references/reader-principles.md; structure-pass HIGH-VALUE DENSITY
role, front-load-value, anti-patterns, pacing check, and length_target
assessment; prose-pass role sentence, analyze-style-first step, and
merge-overlapping-fixes rule; output summary block and min-3-words HALT
* feat(installer): promote bmad-analysis bundle to src/bmad-analysis-skills
Move the bmad-analysis bundle module out of src/standalone-skills/ into its
own src/bmad-analysis-skills root, teach the installer to resolve it there
(getModulePath, official-modules listing, isBuiltInModule helper), and
update the marketplace manifest and standalone-skills docs to match.
* refactor(bmad-review): rename edge-case lens to edge-case-hunter
Rename the lens code and reference file (lens-edge-case.md ->
lens-edge-case-hunter.md), add explicit when = "always" to the shipped
lenses, and tighten the lens-selection wording in SKILL.md.
* feat(bmad-editorial-review): configurable style guide + analysis-driven rework
Apply the workflow-builder analysis recommendations:
- Make the baseline style guide configurable: style_guide in customize.toml
now IS the baseline (default "Microsoft Writing Style Guide") instead of
an empty override slot; SKILL.md no longer hardcodes the guide.
- Inline reader-principles.md into SKILL.md and delete the reference (it
loaded on every run and was half-duplicated inline).
- Complete the customization surface: activation_steps_prepend/append,
persistent_facts (project-context glob), on_complete, and a
review_output_path scalar split out of output_preferences; add a
file:-load fallback convention.
- Ground word metrics: new scripts/word_metrics.py (stdlib, PEP 723, tests)
emits total/per-section word counts so impact estimates and the reduction
summary use exact numbers.
- Cross-pass dedup: prose pass skips CUT-tagged passages and re-attaches
fixes in MERGE'd ones; output ranks by impact with a long-tail rollup.
- Polish: HALT threshold replaced with plain outcome, duplicate LLM-reader
bullets merged, all-caps lowered, literal Overview heading added.
* fix(installer): stop cache-refresh git commands from escaping to the parent repo
Two compounding bugs let a pre-commit test run shallow-fetch and hard-reset
the developer's own repository:
1. Git spawns in custom-module-manager and external-manager inherited the
hook environment. Git exports GIT_DIR (absolute, in worktree checkouts)
into pre-commit hooks; a child git then targets the hook's repo regardless
of cwd, and treats its cwd — the module cache dir — as the work tree. The
cache refresh's 'git fetch --depth 1' + 'git reset --hard origin/main'
therefore shallowed the shared .bare and moved the checked-out branch.
New git-env.js strips repo-targeting GIT_* vars from every git spawn in
both managers, including calls that previously inherited process.env
implicitly.
2. Test suite 51 (quickUpdate dependency expansion) ran the real
CustomModuleManager lookup, which scans ~/.bmad/cache/custom-modules and
network-refreshes every cached clone — real user state. The suite now
stubs findModuleSourceByCode.
Verified by rerunning the suite with GIT_DIR pointed at the repo and a PATH
shim blocking fetch/reset/clone: 432 passing, zero blocked calls.
* De-scope standalone-skills mechanism: atoms return to core, shims reinstated
Shrink the PR to its heart — the skill merges — and defer the module
mechanics to a follow-up where all skills become module-driven:
- bmad-brainstorming, bmad-party-mode, bmad-forge-idea move back to
src/core-skills/ as ordinary core skills with their catalog rows
restored; src/standalone-skills/ and the bmad-analysis bundle module
are removed
- Installer reverted to main: standalone discovery, hidden-module
filtering, dependency resolution, manifest changes (test suites 49-51
removed with the code); the cache-refresh git fix is retained
- The four bmm deprecation shims (create/edit/validate-prd,
create-architecture) are reinstated so enterprise installs that
invoke the old IDs or carry _bmad/custom overrides keep working;
descriptions trimmed to the short husk style; their removals.txt
entries dropped (removal rides the v7 cut as their frontmatter
promises)
- marketplace.json keeps the five plugin entries with atom paths
pointing at src/core-skills/
- Docs (en/cs/fr/vi/zh) reframe the three skills as core thinking
skills; standalone-skills.md reference page removed
* Fix all findings from the max-effort adversarial review
Correctness:
- Finish the edge-case -> edge-case-hunter lens rename at every caller:
the forwarder husk, the code-review/dev-auto/quick-dev review layers,
the renderer test assertion, and the stale example path in
bmad-review/SKILL.md
- marketplace.json: ship the five core kernel skills with
bmad-method-lifecycle so its skills' bmad-review/bmad-editorial-review/
bmad-help/bmad-advanced-elicitation invocations resolve in a
marketplace install
- pick_methods.py / word_metrics.py: force UTF-8 stdout (Windows locale
code pages crashed on the catalog's arrows and CJK headings)
- word_metrics.py: pair fences CommonMark-style so 4-backtick fences can
embed 3-backtick examples without corrupting sections; count CJK
characters as words
- pick_methods.py: validate --extra entries are JSON objects (was an
uncaught AttributeError); read catalogs with utf-8-sig (BOM'd CSVs
silently blanked every num)
- bmad-spec: activation now resolves {output_folder} (which the
Workspace uses) instead of the unused {planning_artifacts}; drop the
stale core-only-installs comment
- Editorial husks: pin the legacy output contracts (three-column table /
Document Summary report and exact empty-state lines) like the review
husks do
- PRD shims: advertise the real bmad-prd customize keys
(validation_checklist_template, prd_output_path, run_folder_pattern,
finalize_reviewers) instead of three that don't exist
- bmad-prd: add the forwarded-activation clause its shims rely on
(ported from bmad-architecture)
- Locale workflow-maps (fr/cs/vi/zh): add the bmad-spec Phase-2 row the
English map gained, which every locale's core-tools note points at
- git-env.js: also strip GIT_CONFIG_PARAMETERS and the
GIT_CONFIG_COUNT/KEY_n/VALUE_n family; pass gitEnv() to the three npm
install spawns whose transitive git calls inherited hook vars
Consistency:
- brain.py --extra overlay now replaces-by-name like pick_methods.py
(same customize.toml additional_* semantics across sibling skills),
with a regression test
* Fix prettier formatting in marketplace.json
* Apply valid CodeRabbit findings
- brain.py: catch malformed --extra overlays (bad JSON, non-array root,
non-object entries) into the clean error path instead of a raw
traceback, with a regression test; read catalogs and overlays with
utf-8-sig; normalize ALL CSV fields (required ones were unstripped and
could arrive as None from short rows)
- brain-selector: clamp the random-technique count to what the pool can
supply so the Total badge matches the actual draw (template +
regenerated assets/brain-selector.html)
- bmad-editorial-review: word_metrics command now uses the explicit
{skill-root}/ prefix
- resolve_party.py / resolve_personas.py: custom member overrides now
start from the installed entry, so omitted fields (icon, title,
description, module, team) survive; non-string member tokens land in
unresolved instead of raising TypeError; party's member loop gains the
isinstance guards its personas twin already had
- bmad-brainstorming: fix the SKILL.md claim that headless is the only
context for self-generated ideas (autonomous mode is interactive);
autonomous mode honors user-supplied techniques before self-selecting
- Docs: drop duplicate 'only' in the spec template; align zh-cn
forge-idea's bmad-review description with the English wording
* Create only the output folder at install time
bmm no longer pre-creates planning_artifacts, implementation_artifacts,
and project_knowledge — the last of which put an empty docs/ at every
project root. Skills create those lazily on first write. core now
declares {output_folder} in its directories block, which was previously
created only as a side effect of the artifact folders nesting under it.
|
||
|
Alex Verkhovsky
|
717479bc3f |
fix(dev-auto): temporarily revert skill-entry renderer (#2598)
Back out the dev-auto render.py workflow entry change from #2587, including the follow-up renderer-only fix on top of it, so the skill returns to the pre-renderer SKILL.md flow while the longer fixes are worked separately. |
||
|
Alex Verkhovsky
|
64157d394c |
feat(dev-auto): render templates via stdlib Python at skill entry (#2587)
Propagate bmad-quick-dev's render.py pattern (#2281) to bmad-dev-auto. SKILL.md becomes the two-line stdout-dispatch shim that runs render.py via uv and follows the instruction it prints; the old SKILL.md body moves to workflow.md, rendered to _bmad/render/bmad-dev-auto/ with all compile-time values baked in. - render.py is a copy of quick-dev's, differing only in skill-name references; a test guards against the two copies drifting apart. - Compile-time config refs ({communication_language}, {planning_artifacts}, {implementation_artifacts}, {deferred_work_file}, {document_output_language}) become {{.var}} substitutions resolved from the central four-layer TOML config. Runtime refs ({spec_file}, {diff_output}, ...) pass through. - [workflow] customization resolves at render time: on_complete inlines into the HALT On Complete section, implementation_handoff into step-03, and review_layers materialize as invocation blocks in step-04 — the runtime resolve_customization.py calls and the activation-time workflow-block resolution step are gone, along with the Load Config activation step (values are baked at point of use; the language rule moves into each step's RULES). - Step files now reference workflow.md instead of SKILL.md; step-02 resolves the spec template's date field; step-04 defines {date} for the triage-log header. - tools/validate-file-refs.js whitelists render/bmad-dev-auto/; test:renderer now also runs the new test/test-dev-auto-renderer.js. - docs: the dev-auto reference's Context Inputs now names the central _bmad/config.toml surface instead of _bmad/bmm/config.yaml. |
||
|
Alex Verkhovsky
|
52e4c634ce |
feat: add stories.yaml contract between bmad-spec and bmad-dev-auto (#2549)
bmad-spec gains an optional, interactive-only Story Breakdown step that derives stories.yaml from the memlog: a fixed-name sibling of SPEC.md listing stories as a simple sequence (list order = execution order), each with id, title, description, and orchestration fields spec_checkpoint, done_checkpoint, and invoke_dev_with. Field definitions and validity rules live in assets/stories-schema.md. Ids are pinned only once a story's spec file exists; un-started stories may be renumbered on re-derive. stories.yaml never carries status. bmad-dev-auto becomes dispatchable per stories.yaml entry: invoked with a spec folder and story id, it reads only that entry's title and description, derives the slug, and creates or resumes the story spec at stories/<id>-<slug>.md just in time. All HALT write-back lands at that id-keyed path (skeletal spec for pre-planning halts). An invocation-prompt directive halts ready-for-dev after planning; re-dispatching the same folder+id resumes via existing status routing. Planning accumulates context from all prior story records in the folder. Reference docs updated to cover both halves. |
||
|
Alex Verkhovsky
|
ac25b2cb5d |
feat(dev-auto): preserve the attempted change on intent-gap halts (#2564)
The intent_gap branch reverted code changes before halting, destroying
information: the attempted diff shows the human exactly which reading
the agent implemented, which is concrete evidence for repairing the
intent — and occasionally the guessed reading is simply right.
Save the attempt as a patch file in {implementation_artifacts} before
reverting, reference it from the triage log, and include its path in
the halt output. Restart stays default-clean (blocked keeps discard
semantics; the tree is reverted as before); if the human decides the
attempted reading was correct, git apply + status in-review resumes
review on it instead of paying for a full re-run.
Also unify the blocking-condition vocabulary: 'intent gaps' (step-02)
and 'intent gap in intent contract' (step-04) both become 'intent gap'
— one condition, one meaning; the artifact shows which phase raised it.
Document the artifact, the recovery affordance, and the unified
condition in the integration reference (docs/reference/dev-auto.md).
|
||
|
Alex VerkhovskyandClaude Opus 4.8
|
33fb5a9d04 |
refactor(quick-dev): fold deletion audit into edge case hunter (#2525)
Replace the standalone bmad-review-deletion-contract-auditor layer with a self-gated deletion check inside the Edge Case Hunter. - After its edge-case pass, the hunter runs a secondary deletion check on the same diff it already holds (Step 4) and folds any deletion findings into a single JSON array, tagged kind: deletion with a confidence. - Add kind and confidence fields to the hunter output; the existing four fields are unchanged. Edge cases stay primary; deletion findings are rare and usually empty. - step-04-review invokes the hunter once — no deterministic deletion scan, no agent resume, no fallback divergence. Classify routes deletion findings through the same triage categories. - Remove the standalone skill, its module-help.csv row, and its core-tools entry; tool count back to 12. Rationale: the hunter already sees the full diff, so a separate detection pass plus a context-rebilling continuation turn bought nothing; self-gating in the existing turn is cheaper and simpler. Deletions are rare and rarely load-bearing, so the check stays secondary to the edge-case pass. Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com> |
||
|
Alex VerkhovskyandClaude Opus 4.8
|
ca6dc496d4 |
feat(dev-auto): record final_revision in spec frontmatter at exit (#2522)
Capture the post-commit HEAD as `final_revision` alongside the existing `baseline_revision`, so the orchestrator running immediately after a dev-auto session can derive the session's commit range (`baseline_revision..final_revision`) without inferring it from git state. The artifacts directory is gitignored, so the spec frontmatter is the only link from the out-of-tree spec to the in-tree commits. A single endpoint suffices: `git log baseline..final` regenerates the commit list on demand, and equal values mean no commits were made. Degrades to `NO_VCS` when version control is unavailable. Also documents both revision fields in docs/reference/dev-auto.md. Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com> |
||
|
Alex Verkhovsky
|
6cbada8689 | docs: retitle dev auto integration reference (#2521) | ||
|
Alex Verkhovsky
|
53d1bf7fb9 | docs: add dev auto integration reference (#2519) | ||
|
Alex VerkhovskyandClaude Opus 4.8
|
7b2d90a5f0 |
chore(bmm): retire bmad-investigate skill and its documentation (#2509)
* chore(bmm): retire bmad-investigate skill and its documentation
Removes the bmad-investigate skill, its case-file template, the EN/FR
forensic-investigation explainer docs, and every integration point:
Amelia's `IN` menu entry, the plugin marketplace manifest, module-help,
the workflow-map tables and HTML diagrams, and the agent-trigger tables.
EN/FR explanation sidebar orders are renumbered to close the gap left by
the removed doc.
Rationale: the skill's only non-redundant value was a durable, hand-off
case-file artifact — a workflow that is unproven in practice. Everything
else (evidence grading, hypothesis discipline, causal tracing) is
behavior a capable model already performs without a dedicated skill. The
skill also carried method-internal metaphor ("stronghold", "evidence
perimeter") that leaked into user-facing chat. Upstream signals agreed:
issue #2452 flagged the vocabulary leak and a maintainer noted the skill
should not auto-fire. Added in #2364.
Supersedes the in-flight cleanup in #2478 and resolves #2452 by removal.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
* chore(bmm): add bmad-investigate to removals.txt and note retirement
The retirement commit removed the skill source and docs but did not add
the removals.txt entry that triggers cleanup of the skill directory on
existing installs during update. Add it, plus an Unreleased CHANGELOG note.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
|
||
|
Alex Verkhovsky
|
20f7fa37e2 |
Add bmad-dev-auto unattended workflow (#2500)
* feat: add bmad dev auto skill * fix: replace dev auto approval gate * fix: remove dev auto one-shot route * fix: tighten dev auto review step * fix: inline dev auto finalization * fix: clarify dev auto sprint sync * fix: clarify dev auto epic context output * fix: structure dev auto deferred work entries * fix: remove dev auto sprint status coupling * fix: run dev auto completion hook on blocked exits * fix: persist dev auto review loop counter * fix: remove dev auto approval-era intent marker * fix: simplify dev auto final result handoff * fix: tighten dev auto workflow contract * fix: clarify dev auto verification owner * fix: strengthen dev auto verification gates Require the auto workflow to re-read its READY standard before judging the spec, and make implementation verification cover both tasks and acceptance criteria with a blocked HALT when missing work cannot be completed. * fix: tighten dev auto prompt wording Remove remaining human-interaction atavisms, make subagent wording consistent, and clarify blocked verification handling in the unattended development workflow. * docs: clarify dev auto customization comments Replace internal merge jargon and stale workflow comments with plain descriptions of the customization file behavior. |
||
|
Brian
|
005ef1104a |
feat(core): add bmad-forge-idea skill + docs (#2492)
* feat(core): add bmad-forge-idea skill
Domain-agnostic idea-forging skill for BMad core. Takes a half-formed idea
and pressure-tests it in conversation until it hardens, proves out, or dies
cheaply — the quality of thinking is the product, not an artifact. One
question at a time with an always-on anti-sycophancy stance; two opt-in gears
(adversarial attack; a persona room resolved from the installed roster,
voiced by default and spawned when a branch needs independent minds); a
memlog as durable, resumable residue. Honest exits (hardened / killed /
clearer); optional brief distilled from the memlog that can feed bmad-spec or
bmad-quick-dev. Interactive and socratic; no headless mode.
Registered in core-skills/module-help.csv (menu code FI).
* Add forge-idea documentation and finalize skill scripts/conventions
Docs (Diátaxis):
- New explanation/forge-idea.md and how-to/pressure-test-an-idea.md
- core-tools.md: catalog entry + item section for bmad-forge-idea
- workflow-map.md and getting-started.md: Phase 1 (Analysis) listing
- De-collide the "forge" verb from bmad-prfaq positioning across docs
Skill:
- forge-idea SKILL.md: add term-sharpening axis, operationalize the
existing-project ground-truth rule, and add graceful degradation
- bmad-prfaq: description de-collision; Stage 1 now redirects upstream
to bmad-forge-idea for an unsound idea
- Unbundle the core memlog.py copy (skill references the core script at
{project-root}/_bmad/scripts); keep skill-local resolve_personas.py + tests
- customize.toml: comment refresh; on_complete as array
* Fix review findings: resolve_personas crash + doc accuracy
- resolve_parties: resolve token once + coerce non-strings (fixes KeyError
on mixed-case members and TypeError on unhashable members)
- Guard malformed party-mode config shapes so discovery stays best-effort
- _brief: pass through model/capabilities; register: no name-lookup hijack
- 5 new regression tests (case-insensitivity, malformed input, rename collision)
- Docs: correct bmad-review-adversarial-general name, bmad-prfaq handoff,
recursive resume glob, broken table row, and Produces filenames across
forge-idea/brainstorming/product-brief/architecture rows
|
||
|
Brian
|
cd8ac7e9aa |
bmm: standardize memlog usage across skills (#2483)
* bmm: standardize memlog usage across skills
- Point all memlog writes at the canonical core script (uv {project-root}/_bmad/scripts/memlog.py) in bmad-spec, bmad-brainstorming, and bmad-architecture; drop the python3/{skill-root} invocations and remove the bundled memlog.py copy from bmad-brainstorming.
- Migrate bmad-prd, bmad-ux, and bmad-product-brief off the hand-authored decision-log.md onto the memlog standard: .memlog.md written only via memlog.py (init/append), distilled-toward not authored, no lifecycle status; rename the headless decision_log JSON key to memlog.
- Fix bmad-spec capability rendering: nested bullets so intent/success break onto their own lines instead of collapsing into one blob.
- Update EN + FR docs (getting-started, workflow-map, core-tools) to reference .memlog.md.
- Remove the bmad-product-brief eval suite (to be replaced with a new format).
* bmm: invoke scripts with 'uv run' instead of python3/bare uv
Bare 'uv {path}.py' does not execute (uv treats the path as a subcommand and errors); only 'uv run {path}' runs the script. Fixes the broken bare-uv memlog form shipped earlier in this branch and converts python3 script calls to 'uv run' across the 6 touched skills (memlog.py, resolve_customization.py, brain.py, lint_spine.py). Inline 'python3 -c' one-liners and .py shebangs are left as-is.
* bmm: address PR review on memlog standardization
- Delete orphaned bmad-brainstorming/scripts/tests/test_memlog.py: it
imported the bundled memlog.py removed in this PR (ModuleNotFoundError on
collection) and its unique tests asserted the now-removed status-lifecycle
behavior. The canonical src/scripts/tests/test_memlog.py is the corrected
superset, so no coverage is lost.
- Make runnable memlog command examples self-contained with the full
'uv run {project-root}/_bmad/scripts/memlog.py ... --workspace {doc_workspace}'
form across bmad-brainstorming (converge/finalize/headless), bmad-prd, and
bmad-ux. Terse checklist back-references left short by design.
- bmad-product-brief Update: init .memlog.md if missing (legacy/pre-standard
briefs), matching bmad-prd and bmad-ux; fix the --type override invocation.
|
||
|
Loic Duong
|
e74dd8040d |
docs: refresh skill metadata references (#2439)
* docs: refresh skill metadata references * docs: link BMad customization guide |