From 4cb18c74602e9f90c85119164ad14cfcced2d438 Mon Sep 17 00:00:00 2001 From: Brian Madison Date: Sun, 24 May 2026 10:02:05 -0500 Subject: [PATCH] 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 --- src/core-skills/bmad-spec/SKILL.md | 12 +++++----- .../bmad-spec/assets/headless-schemas.md | 23 ++++++++++--------- .../bmad-spec/assets/spec-template.md | 2 +- src/core-skills/bmad-spec/customize.toml | 9 ++++---- 4 files changed, 24 insertions(+), 22 deletions(-) diff --git a/src/core-skills/bmad-spec/SKILL.md b/src/core-skills/bmad-spec/SKILL.md index c7e9562fa..1ae0b1f69 100644 --- a/src/core-skills/bmad-spec/SKILL.md +++ b/src/core-skills/bmad-spec/SKILL.md @@ -6,7 +6,7 @@ description: Distill any intent input into the SPEC kernel + companions — the # BMad Spec ## Overview -Canonical transformer for the BMad spec-kernel ecosystem. Takes any intent input — vague idea, brain dump, PRD, GDD, RFC, brief, Slack thread, customer email, meeting transcript, mockups, mixed multi-source — and produces **SPEC.md** carrying the five-field kernel (Why, Capabilities, Constraints, Non-goals, Success signal) plus companion files for load-bearing content that does not fit or would bloat with expansive line item details the kernel. Together they are the machine contract every downstream BMad skill consumes (UX, architecture, ticketing, quick-dev). +Canonical transformer for the BMad spec-kernel ecosystem. Takes any intent input — vague idea, brain dump, PRD, GDD, RFC, brief, Slack thread, customer email, meeting transcript, mockups, mixed multi-source — and produces **SPEC.md** carrying the five-field kernel (Why, Capabilities, Constraints, Non-goals, Success signal) plus companion files for load-bearing content that does not fit or would bloat the kernel with expansive line-item detail. Together they are the machine contract every downstream BMad skill consumes. Multiple skills may call to update the same spec over time. @@ -21,19 +21,19 @@ Multiple skills may call to update the same spec over time. 1. Resolve customization: `python3 {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key workflow`. On failure, read `{skill-root}/customize.toml` directly. 2. Run `{workflow.activation_steps_prepend}`. Treat `{workflow.persistent_facts}` as foundational context (`file:` entries are loaded). -3. Load `{project-root}/_bmad/config.yaml` (and `config.user.yaml` if present), root level and `bmm` section. Resolve `{user_name}`, `{communication_language}`, `{document_output_language}`, `{planning_artifacts}`, `{project_name}`, `{date}`. +3. Load `{project-root}/_bmad/core/config.yaml` (and `config.user.yaml` if present), root level and `bmm` section. Resolve `{user_name}`, `{communication_language}`, `{document_output_language}`, `{planning_artifacts}`, `{project_name}`, `{date}`. 4. Detect mode. **Headless** when any of: no TTY, programmatic caller (another skill or non-interactive runner), or the first message pre-supplies all inputs and asks for an artifact path back. **Interactive** otherwise. In interactive mode, greet by `{user_name}` in `{communication_language}`, stay in that language, and mention that `bmad-party-mode` and `bmad-advanced-elicitation` are available for deeper exploration on any field. 5. Run `{workflow.activation_steps_append}`. ## Workspace -The spec is **always a folder** named `{workflow.spec_output_path}/{workflow.run_folder_pattern}`, resolving by default to `{planning_artifacts}/specs/spec-{slug}-{date}/`. +The spec is **always a folder** named `{workflow.spec_output_path}/{workflow.run_folder_pattern}`, resolving by default to `{planning_artifacts}/specs/spec-{slug}/`. `{slug}` describes the thing being specced, not the input shape: - Source artifact already carries a slug (e.g., `prd-foo-bar-2026-05-23/`): inherit (`foo-bar`). - Sparse, in-chat, or multi-source input: interactive asks; headless caller provides. -- A second run on the same `{slug}` is an update: re-read the existing spec, preserve capability IDs. +- Same slug = same folder. A second invocation with the same `{slug}` lands at the existing spec folder and updates in place, preserving capability IDs. **No input.** Interactive: ask the user to share a file path, paste content, explain the idea in detail, or point to a source. Headless: respond with JSON containing error code `insufficient_intent`. @@ -86,7 +86,7 @@ Pre-existing project-wide docs (e.g. `project-context.md`) that downstream needs Every spec must satisfy these eight rules. The operation aims for them; the self-validate sweep enforces them. 1. **Each capability has both `intent` and `success`.** Missing either = not a capability. -2. **Intents describe WHAT, not HOW.** Implementation prescription belongs in a companion (stack, conventions).. +2. **Intents describe WHAT, not HOW.** Implementation prescription belongs in a companion (stack, conventions). 3. **Constraints actually bend design decisions.** A "constraint" that rules nothing out is decoration. 4. **Non-goals are explicit.** At least one. Absence means downstream skills fill the vacuum. 5. **Success signal is concrete enough to test or demonstrate against.** "Users love it" doesn't qualify. @@ -122,6 +122,6 @@ Any update to spec regarding assumptions, open questions, or other changes shoul ## Frontmatter conventions -- `companions:` array of `.md` files downstream MUST read alongside SPEC.md to have the full contract. Paths may point inside the spec folder (spec-authored companions like `glossary.md`) or outside it (adopted companions like `_bmad-output/ux-designs/foo-ux/DESIGN.md`). The split between spec-authored and adopted is implicit by path; downstream treats both the same. +- `companions:` array of `.md` files downstream MUST read alongside SPEC.md to have the full contract. Paths may point inside the spec folder (spec-authored companions like `glossary.md`) or outside it (adopted companions like `../../ux-designs/ux-foo-bar-2026-05-23/DESIGN.md`). The split between spec-authored and adopted is implicit by path; downstream treats both the same. - `sources:` array of paths to files that were **fully absorbed** into the SPEC, with no remaining downstream value (e.g., a PRD whose every load-bearing claim is now in the kernel). Listed for audit and for bmad-spec to re-read on update. Downstream does NOT read these. Files that downstream still needs to read belong in `companions:`, not here. - **Do not list** decision logs, README files, organizational artifacts, or any operational record of how upstream skills produced their artifacts. Those are not source content; they are process metadata that downstream consumers don't need. diff --git a/src/core-skills/bmad-spec/assets/headless-schemas.md b/src/core-skills/bmad-spec/assets/headless-schemas.md index 1e1638ce2..c9f1b149b 100644 --- a/src/core-skills/bmad-spec/assets/headless-schemas.md +++ b/src/core-skills/bmad-spec/assets/headless-schemas.md @@ -16,23 +16,24 @@ The default invocation is headless: input goes in, JSON comes out. Omit keys for { "status": "complete", "intent": "create", - "spec_path": "{run_folder}/prd-spec-20260518-1432.md", - "decision_log_path": "{run_folder}/.decision-log.md", - "source_artifact": "{run_folder}/prd.md", + "spec_path": "_bmad-output/planning-artifacts/specs/spec-quarter-drop/", + "decision_log_path": "_bmad-output/planning-artifacts/specs/spec-quarter-drop/.decision-log.md", + "sources": ["_bmad-output/planning-artifacts/prds/prd-quarter-drop-2026-05-22/prd.md"], + "companions": ["glossary.md", "../../ux-designs/ux-quarter-drop-2026-05-22/DESIGN.md"], "capabilities": [ {"id": "CAP-1", "intent": "User can record a voice memo pinned to current GPS coords."}, {"id": "CAP-2", "intent": "User hears memos auto-trigger when walking within range of a drop."} ], - "verdict": "Ready for downstream. All six Spec Law rules pass.", + "verdict": "Ready for downstream. All eight Spec Law rules pass.", "assumptions": [], "open_questions": [] } ``` -- `spec_path` follows the **Workspace** rules in `SKILL.md`: sibling of the source file (`{input-basename}-spec-{datetime}.md`) when input is a local file, or `{planning_artifacts}/specs/{slug}-spec-{datetime}.md` when input is chat-only or remote. -- `source_artifact` is the path consumed when distilling a ceremony doc; `null` for pure brain-dump or chat-only runs. -- `decision_log_path` is included only when a `.decision-log.md` was actually written to (the source's folder already had one). Omit the key entirely otherwise. -- `capabilities` carries IDs and one-line intents only — enough for downstream consumers to address them without re-reading the Spec. +- `spec_path` is the **spec folder**, per Workspace rules in `SKILL.md` (default: `{planning_artifacts}/specs/spec-{slug}/`). The kernel file inside is named per `customize.toml.spec_filename` (default `SPEC.md`). +- `sources` is the array of files fully absorbed into the SPEC; audit-only, downstream does NOT read these. Empty when input had no fully-absorbed source (e.g., a UX-folder-only input). +- `companions` is the array of `.md` files downstream MUST read alongside SPEC.md. Sibling-relative for spec-authored (e.g., `glossary.md`); outside-folder-relative for adopted (e.g., `../../ux-designs/{run}/DESIGN.md`). +- `capabilities` carries IDs and one-line intents only — enough for downstream consumers to address them without re-reading the spec. - `verdict` is the one-paragraph self-validate result. When `status` is `"partial"`, the verdict explains what is blocking "ready for downstream." ## Validate-only @@ -41,8 +42,8 @@ The default invocation is headless: input goes in, JSON comes out. Omit keys for { "status": "complete", "intent": "validate", - "spec_path": "{run_folder}/prd-spec-20260518-1432.md", - "decision_log_path": "{run_folder}/.decision-log.md", + "spec_path": "_bmad-output/planning-artifacts/specs/spec-quarter-drop/", + "decision_log_path": "_bmad-output/planning-artifacts/specs/spec-quarter-drop/.decision-log.md", "verdict": "Two rules weak: success signal is decorative; non-goals section empty.", "findings": [ {"rule": "Success signal is concrete", "note": "Currently reads 'users love it' — not testable."}, @@ -62,4 +63,4 @@ The default invocation is headless: input goes in, JSON comes out. Omit keys for } ``` -Always include the intent (best-guess if not certain) and a one-sentence `reason`. +Always include `intent` (best-guess if not certain). When `status` is `"blocked"`, include a one-sentence `reason`. diff --git a/src/core-skills/bmad-spec/assets/spec-template.md b/src/core-skills/bmad-spec/assets/spec-template.md index 5f4045ff5..f8127204c 100644 --- a/src/core-skills/bmad-spec/assets/spec-template.md +++ b/src/core-skills/bmad-spec/assets/spec-template.md @@ -32,7 +32,7 @@ Name which (or which combination) applies, who is affected, and the backdrop tha - {Explicit out-of-scope item. At least one. Stops downstream from filling the vacuum.} -## Success signals +## Success signal - {One or two sentences. World-change moment, not dashboard. Concrete enough to write a test or run a demonstration against.} diff --git a/src/core-skills/bmad-spec/customize.toml b/src/core-skills/bmad-spec/customize.toml index a933eeb89..51f315254 100644 --- a/src/core-skills/bmad-spec/customize.toml +++ b/src/core-skills/bmad-spec/customize.toml @@ -42,7 +42,8 @@ spec_filename = "SPEC.md" spec_output_path = "{planning_artifacts}/specs" # Run-folder pattern inside spec_output_path. Resolved against the -# input-derived slug and date at activation. A second run on the same -# slug is an update; date in the pattern keeps fresh dated folders -# only when the user explicitly intends a new spec. -run_folder_pattern = "spec-{slug}-{date}" +# input-derived slug at activation. Same slug = same folder, so a +# second invocation updates the existing spec in place (capability +# IDs preserved). Override to add {date} or other components if a +# fresh dated history is preferred. +run_folder_pattern = "spec-{slug}"