33 Commits

Include renames

Author	SHA1	Message	Date
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>	2026-08-08 23:03:12 -05:00
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	2026-08-02 23:41:34 -05:00
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	2026-08-01 16:21:38 -05:00
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>	2026-07-31 19:35:25 -07:00
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	2026-07-29 19:40:05 -07:00
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.	2026-07-28 22:30:22 -07:00
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	2026-07-28 19:41:29 -07:00
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	2026-07-22 21:49:24 -05:00
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.	2026-07-18 23:49:22 -05:00
Alex Verkhovsky	6cbada8689	docs: retitle dev auto integration reference (#2521)	2026-06-27 08:25:20 -07:00
Alex Verkhovsky	53d1bf7fb9	docs: add dev auto integration reference (#2519)	2026-06-27 07:42:53 -07:00
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>	2026-06-24 19:42:10 -07:00
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.	2026-06-23 04:53:11 -07:00
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	2026-06-21 21:55:58 -05:00
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.	2026-06-20 17:47:12 -05:00
Brian	ee47e30cf6	refactor(bmad-ux): spine-based UX skill (DESIGN.md + EXPERIENCE.md) (#2413) ... * refactor(bmad-ux): replace bmad-create-ux-design with lean spine-based bmad-ux * refactor(bmad-ux): adopt DESIGN.md spec, split into two-file spine, align prd/brief DESIGN.md (visual identity per the Google Labs spec) and EXPERIENCE.md (behavior, flow, IA) replace the single design.md spine. EXPERIENCE.md cross-references DESIGN.md tokens via the spec's {path.to.token} syntax. Example suite restructure - 3 DESIGN.md examples: editorial (Stitch source / Linen & Logic), calm native mobile (Quill), shadcn-on-Tailwind web SaaS (Drift) - 2 paired EXPERIENCE.md examples (Quill, Drift); Linen & Logic unpaired to model the Stitch handoff scenario - Replaces the prior 2-example combined spine set Discovery additions (outcome-driven, one line each) - Source scan: glob {planning_artifacts}/ for candidates, parent never reads - Form-factor: resolve before IA closes; journeys often derive it - Surface closure: every stated need has a surface, every surface a journey - Named-protagonist journeys (Mary, not "the user") - Design handoff working mode (extensible producer registry, default: Stitch) PRD and brief alignment with same insights - bmad-prd: dropped standalone Primary Persona section from template; renamed "Personas + Journeys" entry to "Journey-led"; named-protagonist rule on UJs; form-factor probe; validation checklist updated - bmad-product-brief: form-factor surfaced in Discovery topics Quality scan fixes - Added ## Overview heading; renamed ## Activation to ## On Activation - Replaced ../ paths in example assets with {planning_artifacts}/ - Sources section compressed (abstract delta-only rule) - Working mode aligned to "Fast path" / "Coaching path" BMad-wide convention New - references/design-md-spec.md: working summary of the spec for the LLM - customize.toml: design_md_examples, experience_md_examples, design_handoffs registries - .prettierignore: ignore .analysis/ quality-scan artifacts repo-wide * refactor(bmad-ux): activation parity with prd/brief, opt-in reviewer gate, no headline grade - Restructure On Activation as numbered six-step list mirroring bmad-prd and bmad-product-brief, restoring the explicit key-resolution list that earlier crammed-paragraph form had dropped (planning_artifacts and friends were silently unresolved at Create). - Make Reviewer Gate opt-in and lens-selectable. At Finalize, ask before spending tokens on parallel reviewer subagents; at Validate intent, skip that question but still confirm lens picks. Stops the auto-run WCAG audit on hobby-stakes work. - Drop the overall validation grade. Per-category verdicts and severity counts already say what is true; a single headline grade conflated design rigor with release readiness and led "POOR" pills landing on reports whose own bodies described the work as strong. Removed from references/validate.md (ladder rule + markdown twin), HTML template (grade pill div + CSS vars + classes). - Trim creative-tools.md: drop the Custom entries section. Runtime prompt files should only carry what the LLM needs to act in this moment; how-to-extend-via-TOML is setup-time human documentation already covered by customize.toml comments. * fix(bmad-ux): align validation report template with 8-category rubric Template placeholders referenced 'Decision-readiness' and 'seven dimensions' from the prior rubric. Replace with TEMPLATE_CATEGORY_NAME and inline the eight canonical categories from references/validate.md so the synthesis pass names them verbatim. * fix(validate-skills): remove stale WF-01/WF-02 rules WF-01/WF-02 were originally scoped to workflow.md files (now mostly gone) but had been generalized to flag name/description in any non-SKILL.md markdown. That over-captured legitimate spec files — e.g. DESIGN.md examples in bmad-ux/assets/ that carry name/description per the Google Labs DESIGN.md spec. Step files are already covered by STEP-06. Rule count: 14 → 12. * fix(bmad-ux): address PR review followups - validation-report-template.html: severity badge class is badge-sev-*, not sev-* (the comment misled the synthesis pass). - Sweep dangling bmad-create-ux-design references: module-help.csv, bmad-agent-ux-designer/customize.toml, bmad-prd/SKILL.md handoff list, workflow-map.md (en + 4 translations), getting-started.md (en + 4 translations). Workflow-map output column updated to DESIGN.md + EXPERIENCE.md. - references/validate.md: Markdown capitalized as a proper noun.	2026-05-22 23:16:06 -05:00
BrianandClaude Opus 4.7	c52c9b5b0e	feat(bmad-prd): new PRD skill + product-brief updates (#2378) ... * feat(bmm): add bmad-prd skill and extend product-brief with external integrations Consolidates the legacy create-prd/edit-prd/validate-prd trio into a single lean facilitator with create/update/validate intent modes, following the bmad-product-brief pattern. Both skills gain external_sources and external_handoffs customize.toml fields for routing through corporate MCP tools (Confluence, Jira, etc.) with graceful degradation, plus a File roles constraint clarifying decision-log (audit trail) vs addendum (preserved depth for downstream docs). * refactor(bmad-prd): tighten SKILL.md and operationalize source-extractor pattern - Compress Overview to remove coaching prose duplicated in Discovery - Operationalize "Extract, don't ingest" with explicit subagent return contract; reference from Update, Validate, and Finalize input reconciliation instead of inline "read N documents" - Fix Overview H1 -> H2 (was breaking pre-pass tooling) - Move full headless JSON schemas to assets/headless-schemas.md; keep minimal example inline - Compress File roles bullet; tighten Finalize step 1 SKILL.md: 124 -> 105 lines, ~4729 -> ~4467 tokens * feat(bmad-prd): open-items gate, drop distillate, persona discipline, decision-log metadata - Add Finalize "Open-items review" step (new step 4): counts OQs / [ASSUMPTION] / [NOTE FOR PM], walks them with user, flags high density as red flag against agreed stakes - Validate now treats open-items density as a first-class finding category - Resume / continuity surfaces open items deterministically as the first orientation step - Drop the PRD's own distillate output and the bmad-distillator finalize step. Downstream workflows (UX, architecture, story creation) source-extract from prd.md directly via the canonical source-extractor pattern. Headless schemas, customize.toml comments, and template updated accordingly. - Drop "status: draft" from PRD frontmatter and template; version/state transitions logged to decision-log.md instead. Finalize step 7 records the version transition entry. - Add PRD Discipline bullet: personas must be research-grounded or marked [ILLUSTRATIVE]; must drive decisions; 2-4 personas max. Discipline pass enforces. - Expand File roles bullet: competitive-analysis detail beyond a one-line landscape and operational/cost mechanics (rate-limiting, compression) belong in addendum * feat(bmad-prd): outcome-driven trim, swappable validation checklist, HTML report SKILL.md trim (4.7K -> ~3.2K tokens, 124 -> 93 lines): - Cut anchor enumerations (HIPAA/PCI/NIST list, API/Mobile/Web list, hobby->regulated list, "fast/easy/scalable/intuitive", input enumerations, etc.) the LLM already knows - Cut derivable reasoning (synonyms-cause-drift explanation, hobby-vs-enterprise examples, etc.) - Cut good/bad examples that anchor LLM attention (password/SendGrid example, persona quote, "let me also add this nearby thing") - Drop SMART-ceremony language from Measurable bullet (keep judgment-not-ritual; SMART principles fine) Progressive disclosure to references/: - Headless mode rules + JSON minimal example moved to references/headless.md (loaded only when invoked headless) - On Activation step 6 gates mode detection: headless -> read references/headless.md and follow Swappable validation checklist: - New assets/prd-validation-checklist.md (15 items: Quality / Discipline / Structural / Stakes-gated, each one line) - New customize.toml field validation_checklist (override per org) - Used by Validate intent AND Finalize Step 3 -- same subagent, same checklist, two moments - Replaces bmad-validate-prd's 13-step micro-file architecture; kept the valuable check dimensions (density, measurability, traceability, implementation leakage, etc.) and dropped the ceremony HTML validation report: - New scripts/render-validation-html.py (PEP 723, stdlib only, ~175 lines) renders structured findings JSON into a styled HTML report with pass/warn/fail grade, inline SVG score bar, category grouping - New assets/validation-report-template.html (inline CSS, native <details>, no JS, no external deps) -- swappable via customize.toml validation_report_template - New references/validation-render.md documents the subagent output contract and renderer invocation; loaded only when validate flow runs - Auto-opens browser on interactive runs; headless skips the open Mode flow consistency: - Create and Update both now explicitly "proceed to ## Finalize" - Validate / analyze is standalone -- explicit "does NOT enter ## Finalize"; renderer auto-opens the HTML - analyze is a synonym for validate; intent detection routes both - Update mode no longer has its own light-close validation step (Finalize Step 3 covers it) * refactor(product-brief,bmad-prd): remove distillation from brief and PRD workflows Drop bmad-distillator integration from bmad-product-brief (finalize step, update mode, headless JSON, constraints) and clean up customize.toml comments. Distillation is the wrong layer — story self-containment via epic solution design docs is the right answer for downstream context. Also commit pending bmad-prd changes: working mode selector (Express vs Facilitative), open-items triage into phase-blocking/resolvable/deferred buckets, persistence wording fix, and facilitation-guide reference. * refactor(bmad-prd): aggressive SKILL.md compression, remove LLM-obvious content * feat(bmad-prd,bmad-product-brief): surface party-mode and advanced-elicitation at opening * refactor(bmm): retire bmad-create-prd/edit/validate, point docs and PM agent at bmad-prd Removes the three separate PRD skills (create, edit, validate) in favor of the unified bmad-prd skill. Updates module-help.csv, PM agent menu, workflow map, getting-started tutorial, commands reference, customize/help SKILL.md examples, and the website workflow-map diagram. Adds Recipe 6 (Advanced Integration Patterns) to expand-bmad-for-your-org.md covering external_sources, external_handoffs, doc_standards, and swappable templates. * test(bmad-product-brief): drop distillate from evals Distillate was removed from the product-brief workflow in 1a88f001 but the eval suite still checked for distillate.md artifacts, the bmad-distillator subagent invocation, and the polish→distillate phase ordering. Strip all distillate references from A1/A5/B1/B2/B3/B5/B6, remove B4 (phase-ordering eval centered on distillate) and B8 (pure distillate eval), update _design_notes, and delete the orphan distillate.md fixture from the forkbird-brief input set. IDs preserved (gaps at B4, B8) so existing references stay stable. * fix(bmad-prd): validation report only on explicit analysis request Reconciles a contradiction across SKILL.md, validation-render.md, headless.md, and headless-schemas.md about when validation-report.{html,md} gets written. Rule: a report file is only written when the user has specifically asked for analysis — Validate intent, or a mid-session "produce a report" request. The Finalize discipline pass during Create/Update keeps findings in-conversation: autofix obvious issues, ask on ambiguous ones, never write a file. - SKILL.md: Finalize step 3 no longer renders a report; Validate intent wording softened from "HTML report" to "validation report". - references/validation-render.md: drops the severity-based conditional for markdown emission. Script now always writes both HTML and MD side-by-side when invoked; trigger gating happens upstream. - assets/headless-schemas.md: drops the "may be omitted in interactive mode" caveat; validation_report is required for Validate intent. - scripts/render-validation-html.py: adds render_markdown_report() emitting a severity-grouped markdown companion at output_path.with_suffix('.md'). Returns markdown path in the stdout JSON summary alongside HTML path. * fix(bmm-skills): address remaining PR review nits - headless-schemas.md: Update schema gains `external_handoffs` to match SKILL.md which routes Update through Finalize (handoffs execute there). - bmad-product-brief/SKILL.md: "Use the bmad-help skill" → "Invoke bmad-help" to align with REF-03 and the bmad-prd phrasing. - bmad-product-brief/SKILL.md: hyphenate "high-quality draft". * feat(bmm): add deprecation shims for retired PRD skills Re-adds bmad-create-prd, bmad-edit-prd, bmad-validate-prd as thin compatibility shims so existing invocations by name and _bmad/custom/bmad-{create,edit,validate}-prd.toml override files keep working post-consolidation. Each shim contains only SKILL.md and customize.toml — no steps, data, or templates. On activation, each shim: 1. Resolves customization via resolve_customization.py, picking up any legacy override files for the four legacy fields (activation_steps_*, persistent_facts, on_complete). 2. Emits a one-time deprecation notice in {communication_language}, pointing at bmad-prd and the migration path for override files. 3. Invokes bmad-prd with the appropriate intent (create / update / validate), passes through the resolved legacy customization with instruction to use these values instead of re-resolving from bmad-prd's own customize.toml, and forwards the original user input verbatim. bmad-prd continues to read its own customize.toml + bmad-prd.toml overrides for the new-only fields (prd_template, validation_checklist, doc_standards, output_dir, output_folder_name, external_sources, external_handoffs, validation_report_template). Users wanting those fields must migrate to invoking bmad-prd directly. * polish(bmm): refine PRD deprecation shim wording Three small revisions applied uniformly to all three shims (bmad-create-prd, bmad-edit-prd, bmad-validate-prd): - Tighten the frontmatter description to a single sentence naming the intent and signaling v7 removal. - Drop the redundant "On failure, surface the diagnostic and halt." trailer from the resolve-customization step; resolve_customization.py surfaces errors itself. - Extend the user-facing deprecation notice to clarify that legacy override fields still resolve under bmad-prd, so migration is for unlocking new fields rather than restoring lost functionality. * fix(bmad-prd): normalize status casing and add friendly file errors - compute_stats: lower-case `status` before bucketing so findings with any casing (e.g. "Pass") feed the stat buckets and the score bar fills correctly. Matches the .lower() pattern already used in render_finding and render_finding_md. - main: wrap findings/template read_text calls; emit a one-line error to stderr and return 1 on FileNotFoundError or JSONDecodeError instead of dumping a raw traceback. Script is LLM-invoked, so a clean diagnostic is the contract. Addresses augmentcode review comments 3235100013 and 3235100018. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * docs(expand): refresh "five recipes" copy to reflect Recipe 6 Recipe 6 (Advanced Integration Patterns) was added but three earlier mentions still said "five": the frontmatter description, the intro sentence at line 8, and the "Combining Recipes" paragraph. Update all three to "six" and extend the Combining-Recipes example to call out Recipe 6 (external_sources / external_handoffs) alongside the others. Addresses coderabbitai review comment 3235107194 and the two outside-diff observations on lines 3 and 8. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * fix(bmad-prd): utf-8 encoding on render script, correct workflow-map outputs - render-validation-html.py reads findings/template and writes HTML/MD with explicit utf-8 encoding so non-ASCII content (smart quotes, em-dashes, non-English text under {document_output_language}) does not break on platforms whose default encoding is not utf-8. - workflow-map.md 'Produces' column for bmad-prd now distinguishes Create/Update outputs from the Validate intent's validation-report artifacts. --------- Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>	2026-05-13 16:45:17 -05:00
AJ Côté	380590aa8b	feat(bmm): add bmad-investigate skill ... Forensic case investigation under Amelia's menu (IN). Evidence-graded findings (Confirmed / Deduced / Hypothesized), hypothesis discipline, structured case-file artifact. Single procedure that calibrates between defect-chasing and area-exploration based on the input. Wires bmad-create-prd discovery to pick up case files as PRD input. Public explainer doc, workflow-map Phase 4 row, EN + FR.	2026-05-08 12:53:00 -04:00
Brian	abfc56bd2c	feat: add bmad-prfaq skill as alternative analysis path (#2157) ... * feat: add bmad-prfaq skill as alternative to product brief Add Working Backwards PRFAQ challenge skill for stress-testing product concepts through Amazon's PRFAQ methodology. Includes press release drafting, customer FAQ, internal FAQ, and verdict stages with subagent support for artifact scanning and web research. - New bmad-prfaq skill with 5-stage interactive gauntlet and headless mode - Subagents for artifact analysis and web research (graceful degradation) - Research-grounded output directive for current market/competitive data - Always produces distillate for downstream PRD consumption - Fix manifest array syntax in both prfaq and product-brief manifests - Drop number prefixes from reference files - Update docs: getting-started, workflow-map, agents, skills reference - Add analysis-phase explainer doc with comparison table and decision guide - Update workflow-map-diagram.html with prfaq card - Add -H and -A args to CSV for both skills - Add unist-util-visit as devDependency (was imported but undeclared) * fix: harden bmad-prfaq for compaction resilience and context efficiency Add coaching persona re-anchors to all stage prompts so the behavioral directive survives context compaction. Add do-not-read guards at resume detection, headless mode, and input gathering to prevent parent agent context bloat. Add Stage 1 coaching notes capture. Adapt template and press release stage for non-commercial concept types. Cap subagent response token budgets. * fix: add config.user.yaml to file-ref validator allowlist Also update PRFAQ config path to use correct _config/bmm/ prefix.	2026-03-28 17:16:41 -05:00
Alex Verkhovsky	b3cf338118	refactor(quick-dev): rename tech-spec prefix to spec (#2109) ... * refactor(quick-dev): rename tech-spec prefix to spec * docs: update tech-spec references to spec	2026-03-23 00:09:05 -06:00
Brian	0380656de6	refactor: consolidate agents into phase-based skill directories (#2050) ... * refactor: consolidate agents into phase-based skill directories Remove separate agent/workflow/skill directories (src/bmm/agents, src/bmm/workflows, src/core/skills, src/utility/agent-components) and reorganize all content into phase-based structures under src/bmm-skills (1-analysis, 2-plan-workflows, 3-solutioning, 4-implementation) and src/core-skills. Eliminates the agent/skill distinction by treating agents as skills within their workflow phase. * fix: update broken file references to use new bmm-skills paths * docs: update all references for unified bmad-quick-dev workflow Remove all references to the old separate bmad-quick-spec and bmad-quick-dev-new-preview workflows. The new bmad-quick-dev is a unified workflow that handles intent clarification, planning, implementation, review, and presentation in a single run. Updated files across English docs, Chinese translations, source skill manifests, website diagram, and build tooling.	2026-03-18 01:01:33 -05:00
Alex Verkhovsky	db8f856fce	docs: update terminology from commands to skills across all documentation (#1850) ... Align documentation with the skills-based architecture migration by replacing references to "commands", "slash commands", and legacy command names with the new "skills" terminology and skill names.	2026-03-07 16:14:25 -07:00
Brian Madison	9247146397	docs: update workflow names and standardize table formatting ... - Prefix all workflows with 'bmad-bmm-' for clarity - Standardize table column alignment - Update workflow path references to use relative paths - Clarify project-context documentation - Simplify workflow loading information	2026-02-18 00:00:54 -06:00
Brian Madison	d4b4bdfa12	docs: improve project-context documentation and fix folder structure ... - Add explanation/how-to docs for project-context.md feature - Update workflow-map Context Management section with comprehensive guidance - Fix folder structure examples to show proper nested subdirectories (planning-artifacts/ and implementation-artifacts/ under _bmad-output/) - Update established-projects.md with project-context creation step - Standardize terminology: use "existing projects" instead of "brownfield"	2026-02-15 17:32:05 -06:00
Alex VerkhovskyandClaude Opus 4.6	a1101534b2	fix(docs): comprehensive documentation site review fixes (#1578) ... * fix(docs): comprehensive documentation site review fixes Rehype plugins: - Rewrite rehype-markdown-links for correct relative .md resolution - Handle raw HTML base paths and bare .md links in rehype-base-paths - Guard protocol-relative URLs (//...) in all link processors - Use file.path instead of file.history[0] for vfile compatibility - Fail build when content directory cannot be detected - Export helpers for testability; add 107 unit tests Build & CI: - Revert cancel-in-progress to false to avoid mid-deploy cancellation - Remove redundant link-validation CI step (build validates internally) - Remove unnecessary fetch-depth:0 from docs deploy workflow - Refuse docs build on Windows (platform guard) - Remove dead build scripts and stale references Tooling: - Add DOCS_ROOT boundary check in validate-doc-links.js - Handle directory paths and prefix stripping in link validator - Remove dead regex and add // guard in fix-doc-links.js Accessibility & CSS: - Darken caution/danger aside title colors for WCAG AA 4.5:1 contrast - Fix 100vw scrollbar overflow (banner width:100%, html overflow-x:clip) - Add :focus-visible ring to banner link for keyboard navigation - Remove dead CSS declaration and add missing code block lang Documentation content: - Convert /docs/ absolute links to relative paths and fix llms.txt URLs - Correct command file paths and naming in commands reference - Update stale shard-doc command to current /bmad-shard-doc format - Fix incomplete sentence in install-bmad.md - Add Quick Flow next steps and fix 404 link path - Expand thin content pages with substantive detail - Add sidebar ordering frontmatter to all content pages - Remove BMGD docs (moved to dedicated repo) - Remove unused assets and misleading diagram caption - Add non-iframe fallback link to workflow map diagram - Remove dead noscript block from workflow-map - Standardize BMAD to BMad, fix spelling/grammar, normalize headings Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * fix(docs): add non-interactive installation to sidebar, rewrite and reorder how-to guides - Move non-interactive-installation.md into how-to/ directory so it appears in the sidebar navigation (was orphaned at docs root) - Rewrite the page based on editorial review: consolidate redundant sections, add missing how-to structure (prerequisites, "What You Get"), condense installation modes from 5 subsections to a table, cut speculative examples - Reorder how-to sidebar: Install (1), Non-Interactive (2), Upgrade to v6 (3), then the rest following user journey order - Fix README link to point to docs site instead of repo-internal markdown path Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * fix(docs): address documentation review findings Fix broken directory tree, grammar errors, inconsistent naming, missing admonition/headings, enable lastUpdated timestamps in CI, and remove footer CSS that misapplied to the content footer. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> * fix(docs): move bleeding-edge install command out of Verify Installation The alternative npx command for installing from main was misplaced inside the "Verify Installation" section. Move it to a tip admonition under Step 1 where users look for install options. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>	2026-02-08 11:58:22 -06:00
Alex Verkhovsky	2aab028f96	docs: rename brownfield to established projects (#1539) ... * docs: rename brownfield to established projects Flatten how-to/brownfield/ subdirectory and replace jargon term "brownfield" with more accessible "established projects" throughout. - brownfield/index.md → established-projects.md - brownfield/quick-fix-in-brownfield.md → quick-fixes.md - brownfield-faq.md → established-projects-faq.md - Update all internal links and references * docs: remove redundant phrase from quick-fixes description * docs: restore natural language in established-projects body	2026-02-05 18:57:40 -06:00
Murat K OzcanandBrian	7ecae1d000	test: quinn to qa (#1508) ... * test: quinn to qa * Removed the TEA sidebar section from the main docs nav --------- Co-authored-by: Brian <bmadcode@gmail.com>	2026-02-03 13:23:37 -06:00
Murat K Ozcan	98bce75905	feat: removed tea module, added sdet with 1 workflow for automate (#1443) ... * feat: removed tea module, added sdet with 1 workflow for automate * fix: addressed PR comments * fix: addressed Alex's comments * fix: addressed Brian 2nd round of comments	2026-01-28 22:26:04 -08:00
Brian Madison	8719d828d0	fix width and responsiveness of diagram	2026-01-26 00:06:17 -06:00
BrianandBrian Madison	3abcefe1fb	feat: make workflow diagram iframe full-width (#1409) ... - Add CSS to break workflow diagram iframe out of content container - iframe now spans full viewport width instead of max-width constraint - Adjust iframe height to 700px for better fit - Remove border/border-radius for seamless full-width look Co-authored-by: Brian Madison <brianmadison@Brians-MacBook-Pro.local>	2026-01-25 23:00:04 -06:00
Brian Madison	c352e03d18	add interactive diagram to test final doc build and layout	2026-01-25 22:12:23 -06:00
Brian Madison	9b12f6f86c	docs updates	2026-01-25 21:18:09 -06:00
Alex VerkhovskyandClaude Opus 4.5	91f6c41be1	docs: radical reduction of documentation scope for v6 beta (#1406) ... * docs: radical reduction of documentation scope for v6 beta Archive and basement unreviewed content to ship a focused, minimal doc set. Changes: - Archive stale how-to workflow guides (will rewrite for v6) - Archive outdated explanation and reference content - Move unreviewed content to basement for later review - Reorganize TEA docs into dedicated /tea/ section - Add workflow-map visual reference page - Simplify getting-started tutorial and sidebar navigation - Add explanation pages: brainstorming, adversarial-review, party-mode, quick-flow, advanced-elicitation - Fix base URL handling for subdirectory deployments (GitHub Pages forks) The goal is a minimal, accurate doc set for beta rather than comprehensive but potentially misleading content. Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> * refactor: restructure BMM and agents documentation by consolidating and flattening index files. --------- Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>	2026-01-25 14:00:26 -06:00