From 5b8f6af0995b630dc458fd273186b955cb918594 Mon Sep 17 00:00:00 2001 From: Brian Madison Date: Sun, 24 May 2026 10:42:51 -0500 Subject: [PATCH] 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}// 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//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. --- src/core-skills/bmad-spec/SKILL.md | 4 ++-- .../bmad-spec/assets/headless-schemas.md | 14 +++++++------- src/core-skills/bmad-spec/customize.toml | 10 ++++++---- src/core-skills/module-help.csv | 2 +- 4 files changed, 16 insertions(+), 14 deletions(-) diff --git a/src/core-skills/bmad-spec/SKILL.md b/src/core-skills/bmad-spec/SKILL.md index 1ae0b1f69..4957ac74e 100644 --- a/src/core-skills/bmad-spec/SKILL.md +++ b/src/core-skills/bmad-spec/SKILL.md @@ -27,7 +27,7 @@ Multiple skills may call to update the same spec over time. ## 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}/`. +The spec is **always a folder** named `{workflow.spec_output_path}/{workflow.run_folder_pattern}`, resolving by default to `{output_folder}/specs/spec-{slug}/`. `{slug}` describes the thing being specced, not the input shape: @@ -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 `../../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. +- `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 `../planning-artifacts/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 c9f1b149b..c8e161acc 100644 --- a/src/core-skills/bmad-spec/assets/headless-schemas.md +++ b/src/core-skills/bmad-spec/assets/headless-schemas.md @@ -16,10 +16,10 @@ The default invocation is headless: input goes in, JSON comes out. Omit keys for { "status": "complete", "intent": "create", - "spec_path": "_bmad-output/planning-artifacts/specs/spec-quarter-drop/", - "decision_log_path": "_bmad-output/planning-artifacts/specs/spec-quarter-drop/.decision-log.md", + "spec_path": "_bmad-output/specs/spec-quarter-drop/", + "decision_log_path": "_bmad-output/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"], + "companions": ["glossary.md", "../planning-artifacts/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."} @@ -30,9 +30,9 @@ The default invocation is headless: input goes in, JSON comes out. Omit keys for } ``` -- `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`). +- `spec_path` is the **spec folder**, per Workspace rules in `SKILL.md` (default: `{output_folder}/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`). +- `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., `../planning-artifacts/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." @@ -42,8 +42,8 @@ The default invocation is headless: input goes in, JSON comes out. Omit keys for { "status": "complete", "intent": "validate", - "spec_path": "_bmad-output/planning-artifacts/specs/spec-quarter-drop/", - "decision_log_path": "_bmad-output/planning-artifacts/specs/spec-quarter-drop/.decision-log.md", + "spec_path": "_bmad-output/specs/spec-quarter-drop/", + "decision_log_path": "_bmad-output/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."}, diff --git a/src/core-skills/bmad-spec/customize.toml b/src/core-skills/bmad-spec/customize.toml index 51f315254..afb71ee72 100644 --- a/src/core-skills/bmad-spec/customize.toml +++ b/src/core-skills/bmad-spec/customize.toml @@ -36,10 +36,12 @@ spec_template = "assets/spec-template.md" # Uppercase by convention to signal "the central source of truth." spec_filename = "SPEC.md" -# Output path for spec folders. Mirrors the BMad convention for PRDs -# (`prds/`) and UX runs (`ux-designs/`): one predictable location for -# downstream skills, regardless of input shape. -spec_output_path = "{planning_artifacts}/specs" +# Output path for spec folders. Lands directly under {output_folder} +# so bmad-spec works in core-only installs and matches the +# long-term BMad direction of grouping artifacts as siblings under +# {output_folder}// rather than nested inside planning vs +# implementation folders. +spec_output_path = "{output_folder}/specs" # Run-folder pattern inside spec_output_path. Resolved against the # input-derived slug at activation. Same slug = same folder, so a diff --git a/src/core-skills/module-help.csv b/src/core-skills/module-help.csv index bde348836..ea4abb043 100644 --- a/src/core-skills/module-help.csv +++ b/src/core-skills/module-help.csv @@ -9,5 +9,5 @@ Core,bmad-editorial-review-prose,Editorial Review - Prose,EP,Use after drafting Core,bmad-editorial-review-structure,Editorial Review - Structure,ES,Use when doc produced from multiple subprocesses or needs structural improvement.,,[path],anytime,,,false,report located with target document, Core,bmad-review-adversarial-general,Adversarial Review,AR,"Use for quality assurance or before finalizing deliverables. Code Review in other modules runs this automatically, but also useful for document reviews.",,[path],anytime,,,false,, Core,bmad-review-edge-case-hunter,Edge Case Hunter Review,ECH,Use alongside adversarial review for orthogonal coverage — method-driven not attitude-driven.,,[path],anytime,,,false,, -Core,bmad-spec,Spec,SP,"Use to distill any intent input (brief, PRD, transcript, brain dump, design folder, mixed multi-source) into a succinct, no-fluff SPEC.md contract + companions that downstream work derives from. Locks the WHAT before the HOW. Works for software, game design, research, editorial, policy, business, anything intent-bearing. Validation mode also available.",,[path],anytime,,,false,{planning_artifacts}/specs/spec-{slug}-{date},SPEC.md + companion files +Core,bmad-spec,Spec,SP,"Use to distill any intent input (brief, PRD, transcript, brain dump, design folder, mixed multi-source) into a succinct, no-fluff SPEC.md contract + companions that downstream work derives from. Locks the WHAT before the HOW. Works for software, game design, research, editorial, policy, business, anything intent-bearing. Validation mode also available.",,[path],anytime,,,false,{output_folder}/specs/spec-{slug},SPEC.md + companion files Core,bmad-customize,BMad Customize,BC,"Use when you want to change how an agent or workflow behaves — add persistent facts, swap templates, insert activation hooks, or customize menus. Scans what's customizable, picks the right scope (agent vs workflow), writes the override to _bmad/custom/, and verifies the merge. No TOML hand-authoring required.",,,anytime,,,false,{project-root}/_bmad/custom,TOML override files