Merge 872ee46fd4 into ee47e30cf6

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 the kernel with expansive line-item detail. Together they are the machine contract every downstream BMad skill consumes.
+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).
 
 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/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}`.
+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}`.
 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 `{output_folder}/specs/spec-{slug}/`.
+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}/`.
 
 `{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.
-- Same slug = same folder. A second invocation with the same `{slug}` lands at the existing spec folder and updates in place, preserving capability IDs.
+- A second run on the same `{slug}` is an update: re-read the existing spec, preserve 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 `../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.
+- `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.
 - `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.

src/core-skills/bmad-spec/assets/headless-schemas.md

@@ -16,24 +16,23 @@ The default invocation is headless: input goes in, JSON comes out. Omit keys for
 {
   "status": "complete",
   "intent": "create",
-  "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", "../planning-artifacts/ux-designs/ux-quarter-drop-2026-05-22/DESIGN.md"],
+  "spec_path": "{run_folder}/prd-spec-20260518-1432.md",
+  "decision_log_path": "{run_folder}/.decision-log.md",
+  "source_artifact": "{run_folder}/prd.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 eight Spec Law rules pass.",
+  "verdict": "Ready for downstream. All six Spec Law rules pass.",
   "assumptions": [],
   "open_questions": []
 }
 ```
 
-- `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., `../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.
+- `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.
 - `verdict` is the one-paragraph self-validate result. When `status` is `"partial"`, the verdict explains what is blocking "ready for downstream."
 
 ## Validate-only
@@ -42,8 +41,8 @@ The default invocation is headless: input goes in, JSON comes out. Omit keys for
 {
   "status": "complete",
   "intent": "validate",
-  "spec_path": "_bmad-output/specs/spec-quarter-drop/",
-  "decision_log_path": "_bmad-output/specs/spec-quarter-drop/.decision-log.md",
+  "spec_path": "{run_folder}/prd-spec-20260518-1432.md",
+  "decision_log_path": "{run_folder}/.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."},
@@ -63,4 +62,4 @@ The default invocation is headless: input goes in, JSON comes out. Omit keys for
 }
 ```
 
-Always include `intent` (best-guess if not certain). When `status` is `"blocked"`, include a one-sentence `reason`.
+Always include the intent (best-guess if not certain) and a one-sentence `reason`.

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 signal
+## Success signals
 
 - {One or two sentences. World-change moment, not dashboard. Concrete enough to write a test or run a demonstration against.}
 

src/core-skills/bmad-spec/customize.toml

@@ -36,16 +36,13 @@ 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. 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}/<type>/ rather than nested inside planning vs
-# implementation folders.
-spec_output_path = "{output_folder}/specs"
+# 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"
 
 # Run-folder pattern inside spec_output_path. Resolved against the
-# 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}"
+# 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}"

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,{output_folder}/specs/spec-{slug},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,{planning_artifacts}/specs/spec-{slug}-{date},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