* 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.
* Rework solutioning architecture skill into bmad-architecture (spine)
- Rename canonical skill bmad-tech-plan -> bmad-architecture; output is ARCHITECTURE-SPINE.md
- Convert bmad-create-architecture to a deprecated husk forwarding to bmad-architecture (create intent); strip steps/data/template
- Finalize: spine is the default, then offers fuller renderings + a self-contained HTML view; doc_standards polish applies to prose docs only
- Reviewer Gate: add adversarial divergence-hunter, on by default at high/regulated/cross-team stakes
- Fix references in module-help.csv, bmad-prd, bmad-ux, bmad-agent-architect; reword help entry for when-to-offer
- bmad-spec: flag recognized-but-unaddressed domain implications as open_questions
* bmad-architecture: extract Finalize/reviewer-menu to references, add grade_spine script
- Move the Finalize sequence out of SKILL.md into references/finalize.md
- Make references/validate.md own the canonical reviewer menu and prompts
- Add scripts/grade_spine.py (+ tests) so validation grade is computed
deterministically instead of derived by hand
- Tighten SKILL.md spine/memlog framing
* bmad-architecture: outcome-driven rewrite + spawned reviewer gate
Re-express SKILL.md as goals/outcomes rather than procedure: intent is read
from the input (raw idea, large doc, codebase, feature slice, existing spine)
instead of a Create/Update/Validate x mode matrix. Restore the counter-default
coaching invariants that over-compression had stripped — Guided is the default,
load-bearing calls are shown with alternatives and the user chooses, recommend a
known starter when the stack is open, investigate brownfield before deciding.
Adopt the bmad-prd/product-brief shape: a dedicated Reviewer Gate that always
spawns finalize_reviewers as parallel subagents against the spine (lint floor
first; ad-hoc lenses scaled to rigor/altitude/criticality), and a numbered
Finalize that calls it. Headless runs the full gate non-interactively.
Reframe the structural seed as the living source of truth for shape (code owns
detail; evolve on shape change; memlog keeps history). Fix template mermaid
(C4 -> flowchart, valid one-attr-per-line erDiagram). Ship two default
finalize_reviewers (currency/reality check, adversarial divergence hunter).
Remove grade_spine.py and the inlined discovery/inputs/validate/finalize refs.
* bmad-architecture: review fixes — shared memlog, epic altitude, lint hardening
Pre-PR review fixes for the new architecture-spine skill:
- Adopt the shared canonical memlog (#2462); drop the vendored copy and the
status-flag lifecycle in favor of `event` entries
- Wire epic-altitude inheritance: parent-spine load+bind, Inherited Invariants
template section, epic-scoped run folder, parent-contradiction lens; state
that per-story detail is deferred to bmad-create-story
- Add the Update intent; honor a forwarded-activation handoff from the
deprecated bmad-create-architecture shim
- Rename modes to Coaching path / Fast path (suite-consistent with prd/brief)
and sequence the offer as an activation step
- Fix the brownfield project-context.md default path ({output_folder} no-op)
- lint_spine: line-exact frontmatter, fence-blanking (AD-in-fence + accurate
line numbers), map-form key_deps, AD-0 fix; soften template-token severity;
add 8 tests
- Carve the Reviewer Gate to references/ to stay under the SKILL.md token budget
- Template: entities-only ERD, scale-down guidance, softened seed framing;
gitignore .memlog.md
* bmad-architecture: address PR review (augment + coderabbit)
- REF-03: use canonical "invoke the `skill` skill" language for all cross-skill
references in SKILL.md (was "route to / offer / hand to / Next:")
- lint_spine: scan frontmatter for unfilled template tokens / TBD (paradigm,
scope, date were uncatchable in the body-only pass)
- lint_spine: guard read_text() so a bad-encoding/unreadable spine returns error
JSON and exit 0, honoring the documented contract
- reviewer-gate: resolve the "always run" vs "may skip" ambiguity — the gate
scales/skips by stakes, but finalize_reviewers always run once it does
- tests: +3 (frontmatter token, frontmatter TBD, unreadable spine); use next()
* bmad-architecture: align finalize-reviewers wording + headless blocked output
- customize.toml: reword finalize_reviewers comment to match reviewer-gate.md —
the gate is stakes-gated, but its reviewers always run once it does (coderabbit)
- headless.md: state explicitly that a blocked run omits spine/memlog/companions,
matching the "omit keys for artifacts not produced" contract (coderabbit)
* bmad-architecture: ask deliverable purpose up front, offer presentable renderings, lead next-steps with bmad-spec
* bmad-spec: make the memlog canonical, SPEC.md a derived view
Replace the bespoke .decision-log.md with the shared memlog script
(_bmad/scripts/memlog.py, same location as resolve_customization.py).
The append-only memlog becomes the single source of truth; SPEC.md and
spec-authored companions are re-derived from it (plus cited sources for
raw content) on each run instead of hand-patched. This makes bmad-spec
the sole writer of the spec and lets the surrounding steps (PRD, UX,
architecture, epics) feed one spec in any order without merge drift.
- New "Memory and derivation" section: memlog canonical, SPEC.md a
projection, single-writer rule, append/init via the shared script,
no status field (terminal moments are event entries).
- Operation reads the prior memlog (not the rendered SPEC.md) as the
authority on decisions and capability IDs on update.
- Conflict-surfacing: live sources/companions that disagree on a field
are raised to the user, resolution logged as a new entry.
- Rename .decision-log.md -> .memlog.md across SKILL.md and assets.
* core: add shared canonical memlog.py in src/scripts
Single source-of-truth memlog: append-only, chronological working-memory
log for skills. Installs to _bmad/scripts/memlog.py via the existing
src/scripts sync (beside resolve_customization.py), so any skill can call
it at runtime — bmad-spec is the first consumer.
Merges the neutral API (--workspace, free-form --type/--by, generic set)
with crash-safe fsync atomic writes. No lifecycle status by design: a
memory log records completion as an event entry, never a frontmatter flag.
Also accepts --path for callers that hold the file path directly. 30 tests.
* bmad-spec: include event in memlog --type list
The documented append --type set omitted event while the next line
requires --type event for terminal moments. Align the list.
* Fix memlog Python floor and exclude tests from install
- memlog.py: add 'from __future__ import annotations' so PEP 585/604
hints stay lazy; the script runs on Python 3.8+ instead of crashing
below 3.10. Correct the requires-python header to >=3.8.
- installer.js: filter tests/, __pycache__/, .pytest_cache/, and *.pyc
out of _installSharedScripts so dev-only files never ship to users.
* fix(skills): strengthen activation guardrails for all workflow skills
Add explicit "Activation is complete" boundary markers that require
confirming activation_steps_prepend and activation_steps_append were
fully executed before beginning the main workflow.
Previously, the guardrail was either missing (bmad-product-brief,
bmad-prd, bmad-investigate) or too weak ("Begin the workflow below").
LLM agents would short-circuit complex activation sequences (INCLUDE →
READ → RUN → CHECK → FILTER → CD) by guessing variables instead of
executing steps in order, causing append steps and on_complete hooks
to be silently skipped.
The new guardrail explicitly names both prepend and append steps,
requiring confirmation before proceeding. This prevents agents from
starting the main workflow in parallel with activation.
23 skills updated: bmad-product-brief, bmad-prd, bmad-prfaq,
bmad-investigate, bmad-create-story, bmad-dev-story,
bmad-quick-dev, bmad-code-review, bmad-correct-course,
bmad-sprint-planning, bmad-sprint-status, bmad-retrospective,
bmad-qa-generate-e2e-tests, bmad-checkpoint-preview,
bmad-check-implementation-readiness, bmad-create-architecture,
bmad-create-epics-and-stories, bmad-generate-project-context,
bmad-create-ux-design, bmad-document-project, bmad-market-research,
bmad-technical-research, bmad-domain-research.
* fix(skills): extend activation gate to agent + new skills, refine placement
- bmad-product-brief / bmad-prd: pull activation_steps_append out of
the numbered list so the sentinel reads as a paragraph break, not
as the next list item.
- bmad-investigate: move the sentinel above Step 7 (routing) — Step 7
is workflow routing, not activation; the gate must fire first.
- bmad-agent-{analyst,tech-writer,pm,ux-designer,architect,dev}: add
the same gate between Step 7 (append) and Step 8 (menu dispatch).
Persona skills had the same short-circuit risk but no sentinel.
- bmad-ux, bmad-spec: new skills introduced on main after this branch
forked; apply the same gate so the pattern stays consistent.
- removals.txt: register bmad-create-ux-design as renamed to bmad-ux.
---------
Co-authored-by: Brian Madison <bmadcode@gmail.com>
* feat(bmad-spec): add Spec kernel distiller skill
New 2-plan-workflows skill that distills any intent input (brain dump,
PRD, transcript, brief) into a spec.md carrying the five-field kernel:
Problem, Capabilities, Constraints, Non-goals, Success signal. Headless
callers receive JSON; interactive runs close conversationally with the
spec path and gap-coverage invitations.
Includes:
- SKILL.md with activation contract and conventions
- customize.toml exposing template path, output path, run-folder pattern
- assets/spec-template.md (five-field skeleton)
- assets/headless-schemas.md (JSON IO contracts)
* remove brain-dump fallback config from bmad-spec customize.toml
* refactor(bmad-spec): companions+sources model, routing tilt, flat output path
- Collapse `related:` into `companions:`; companion paths may point inside the spec folder (spec-authored) or outside it (adopted from an upstream skill), distinguished implicitly by path
- `sources:` reserved for fully-absorbed inputs; downstream does NOT read these
- Soften mutation contract: bmad-spec owns SPEC.md and spec-authored companions; adopted companions belong to their originating skill
- Add "when to spawn a companion" tilt: multi-item catalogs, tables, diagrams (always), editorial voice rules; sub-bullets in a kernel field signal it has outgrown the kernel
- Fix Spec Law rule 7 and Pass 2: load-bearing content lands in SPEC.md or a companion, not the decision log (the log records wrapper-drops only)
- Flatten output path to `{planning_artifacts}/specs/spec-{slug}-{date}/`, mirroring `prds/` and `ux-designs/`; drop `spec_folder_name` (no longer used)
- Extract Load-bearing definition into its own section above Spec Law
* chore(core): retire bmad-distillator, promote bmad-spec to core
- Delete bmad-distillator/ and all registry + doc references (superseded by bmad-spec; no skill or workflow in any BMad module invoked it)
- Add bmad-distillator to removals.txt so installer cleans it from existing IDE skill directories on update
- Move bmad-spec from bmm-skills/2-plan-workflows/ to core-skills/ (universal scope: game design, research hypotheses, editorial briefs, policy, business plans, not just software)
- Register bmad-spec in core module-help.csv and bmad-pro-skills marketplace plugin
- Drop bmad-distillator section from core-tools.md (en, vi-vn, cs, fr, zh-cn) and vi-vn dev guide; renumber subsequent sections
* refactor(bmad-spec): add lean-prose discipline + generalize help text
- Add Spec Law rule 8: lean prose. Every sentence carries load-bearing content; cut decoration, hedges, backstory, throat-clearing. Applies to SPEC.md, companions, and decision log.
- Update Self-Validate Pass 1 to enforce rules 1-6 and 8 (rule 7 stays in Pass 2)
- Prime the operation up-front: write lean from the first pass, every sentence must earn its place
- Note in Companions section that companions follow the same lean discipline
- Generalize core module-help.csv entry: domain-agnostic framing (software, game design, research, editorial, policy, business, anything intent-bearing); call out succinct, no-fluff and "locks the WHAT before the HOW" as the value props
* fix(bmad-spec): address PR review findings (CodeRabbit + Augment)
- headless-schemas.md: rewrite spec_path examples to point at the spec folder (not a file), rename source_artifact to sources[] array, add companions[] array, update verdict from "six rules" to "eight rules", disambiguate reason requirement (only when status=blocked)
- SKILL.md activation: fix config path from {project-root}/_bmad/config.yaml to {project-root}/_bmad/core/config.yaml (matches other BMM skills)
- customize.toml + SKILL.md Workspace: drop {date} from default run_folder_pattern (spec-{slug}); same slug = same folder = trivial in-place update, no glob-and-pick-most-recent needed. Override available for users who want dated history.
- spec-template.md: rename "## Success signals" (plural) to "## Success signal" (singular) to match SKILL.md kernel naming
- SKILL.md Frontmatter conventions: fix adopted-companion example path from _bmad-output/ux-designs/foo-ux/DESIGN.md to ../../ux-designs/ux-foo-bar-2026-05-23/DESIGN.md (matches actual flat-output convention)
- SKILL.md Spec Law: fix double-period typo in rule 2 ((stack, conventions)..)
- SKILL.md Overview: fix awkward "bloat with expansive line item details the kernel" phrasing; drop software-flavored downstream consumer list since bmad-spec is now a core skill serving any domain
* fix(bmad-spec): drop {planning_artifacts} dependency; output to {output_folder}/specs
bmad-spec is a core skill but its default path used {planning_artifacts}, a bmm-module variable. Core-only installs (no bmm) would fail at activation when the resolver tried to expand the path.
Land specs directly under {output_folder}/specs/spec-{slug}/ instead. Works in any install regardless of installed modules, and aligns with the long-term BMad direction of grouping artifacts as siblings under {output_folder}/<type>/ rather than nested under planning vs implementation parents.
In bmm installs, adopted-companion paths from spec to UX/PRD pick up one extra .. (e.g., ../planning-artifacts/ux-designs/<run>/DESIGN.md) since the spec folder is now one level up from planning-artifacts. Examples in SKILL.md and headless-schemas.md updated. module-help.csv output-location updated and stale -{date} fragment removed.
* docs(bmad-spec): add reference docs, trim headless schema, tighten defaults
- Add full bmad-spec entry to docs/reference/core-tools.md and table-row
stubs to cs/fr/vi-vn/zh-cn (full translation pending).
- Strip headless-schemas.md to a minimal {status, files} success response
and {status, error_code, reason} blocked response. Drop spec_path,
capabilities, verdict, decision_log_path — all derivable from the files
themselves.
- Narrow customize.toml persistent_facts default from recursive glob to
single {project-root}/project-context.md; document override path.
- Drop unused {doc_workspace} convention line from SKILL.md.
- Clarify Self-Validate verdict handling for interactive vs headless.
- Document missing_slug error code in SKILL.md + headless schema.
Brian
Jérôme Revillard