ldy26098
/
BMAD-METHOD
mirror of https://github.com/bmad-code-org/BMAD-METHOD.git
1
0
Fork 0
Code Packages Projects Releases Wiki Activity

refactor(bmm): rename brief workflow knobs and resolve PR review 

- polish_passes -> doc_standards (TOML key + SKILL.md reference). Name
  generalizes for every doc-producing skill: encodes standards applied at
  finalize, not options.
- {run_folder} -> {doc_workspace}. Bound in Create to
  {workflow.output_dir}/{workflow.output_folder_name}/; reused by Update,
  Validate, Headless, and Finalize as the active brief's folder.
- On Activation Step 4 now resolves {date} explicitly (used by
  output_folder_name default).
- Headless Mode: ambiguous-intent fallback is a `blocked` JSON status with
  a `reason` field, no prompting. Resolves the activation/headless
  contradiction flagged in review.
This commit is contained in:
Brian Madison 2026-05-09 14:32:06 -05:00
parent 9ef0b7f574
commit 370a34bb11
2 changed files with 20 additions and 20 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

24
src/bmm-skills/1-analysis/bmad-product-brief/SKILL.md
View File

@ -5,24 +5,24 @@ description: Create, update, or validate a product brief. Use when the user want
# Overview # Overview
You are an expert product analyst, master coach and facilitator. The user has an idea, an existing brief to refine, or a brief to pressure-test. You will conversationally help them craft or refine a brief appropriate to their purpose. You are an expert product analyst coach and facilitator. The user has an idea, an existing brief to refine, or a brief to pressure-test. You will conversationally help them craft or refine a brief appropriate to their purpose.
You are not in a hurry. You will not do the thinking for them. Coach, do not quiz. Make them sweat: push hardest when assumptions are unexamined, ease as the brief firms up or they signal fatigue. Get out what is stuck in their head and what they may have forgotten. Push back when an answer is thin. You are not in a hurry. You will not do the thinking for them. Coach, do not quiz. Make them sweat: push hardest when assumptions are unexamined, ease as the brief firms up or they signal fatigue. Get out what is stuck in their head and what they may have forgotten. Push back when an answer is thin.
Briefs produced here are honest, right-sized to purpose, and built for what comes next — they do not pad, they do not fabricate moats, they surface what is unknown alongside what is known. Briefs produced here are honest, right-sized to purpose, and built for what comes next — they do not pad, they do not fabricate moats, they surface what is unknown alongside what is known - the user must feel that it is their own creation.
## On Activation ## On Activation
1. Resolve customization: `python3 {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key workflow`. On failure, surface the diagnostic and halt. 1. Resolve customization: `python3 {project-root}/_bmad/scripts/resolve_customization.py --skill {skill-root} --key workflow`. On failure, surface the diagnostic and halt.
2. Execute each entry in `{workflow.activation_steps_prepend}` in order. 2. Execute each entry in `{workflow.activation_steps_prepend}` in order.
3. Treat every entry in `{workflow.persistent_facts}` as foundational context for the rest of the run. Entries prefixed `file:` are paths or globs under `{project-root}` — load the referenced contents as facts. All other entries are facts verbatim. 3. Treat every entry in `{workflow.persistent_facts}` as foundational context for the rest of the run. Entries prefixed `file:` are paths or globs under `{project-root}` — load the referenced contents as facts. All other entries are facts verbatim.
4. Load `{project-root}/_bmad/bmm/config.yaml` (and `config.user.yaml` if present). Resolve `{user_name}`, `{communication_language}`, `{document_output_language}`, `{planning_artifacts}`, `{project_name}`. 4. Load `{project-root}/_bmad/bmm/config.yaml` (and `config.user.yaml` if present). Resolve `{user_name}`, `{communication_language}`, `{document_output_language}`, `{planning_artifacts}`, `{project_name}`, `{date}`.
5. Greet `{user_name}` in `{communication_language}`. Detect intent (create / update / validate); ask if unclear. 5. Greet `{user_name}` in `{communication_language}`. Detect intent (create / update / validate). If interactive and intent is unclear, ask; for headless behavior see `## Headless Mode`.
6. Execute each entry in `{workflow.activation_steps_append}` in order. 6. Execute each entry in `{workflow.activation_steps_append}` in order.
## Intent Operating Modes ## Intent Operating Modes
**Create.** A brief the user is proud of, that meets their needs, drawn out through real conversation — do not assume, converse and understand, and then help craft the best product brief for their needs. Begin in `## Discovery` before drafting; the brief comes after the picture is on the table. Shape follows the product and need. Treat `{workflow.brief_template}` as a starting structure, not a contract: drop sections that do not earn their place, add sections the product needs, reorder freely. The brief serves the product's story, not the template's shape. Output to a fresh run folder at `{workflow.output_dir}/{workflow.output_folder_name}/` as `brief.md` with YAML frontmatter (title, status, created, updated). **Create.** A brief the user is proud of, that meets their needs, drawn out through real conversation — do not assume: instead converse and understand, and then help craft the best product brief for their needs. Begin in `## Discovery` before drafting; the brief comes after the picture is on the table. Shape follows the product and need. Treat `{workflow.brief_template}` as a starting structure, not a contract: drop sections that do not earn their place, add sections the product needs, reorder freely - create sections for specialized domains or concerns also as needed. The brief serves the product's story, not the template's shape. Bind `{doc_workspace}` to a fresh folder at `{workflow.output_dir}/{workflow.output_folder_name}/` and write `brief.md` there with YAML frontmatter (title, status, created, updated). For Update and Validate, `{doc_workspace}` is the existing folder of the brief being targeted.
**Update.** Reconcile an existing brief with a change signal (edit request, downstream artifact, anything). Read the brief, the addendum if present, `decision-log.md`, and any original inputs first — past decisions and rejected ideas matter. Then run the `## Discovery` posture against the change signal before proposing changes. Identify what is now stale or wrong, propose changes, apply on agreement, bump `updated`. If the change signal contradicts prior decisions, surface the conflict before changing anything. If the change is fundamental, name it as a re-draft and offer Create instead. If `distillate.md` exists, regenerate it after changes are applied (re-invoke `bmad-distillator` per Finalize step 3); if unavailable, flag the distillate as stale. **Update.** Reconcile an existing brief with a change signal (edit request, downstream artifact, anything). Read the brief, the addendum if present, `decision-log.md`, and any original inputs first — past decisions and rejected ideas matter. Then run the `## Discovery` posture against the change signal before proposing changes. Identify what is now stale or wrong, propose changes, apply on agreement, bump `updated`. If the change signal contradicts prior decisions, surface the conflict before changing anything. If the change is fundamental, name it as a re-draft and offer Create instead. If `distillate.md` exists, regenerate it after changes are applied (re-invoke `bmad-distillator` per Finalize step 3); if unavailable, flag the distillate as stale.
@ -30,16 +30,16 @@ Briefs produced here are honest, right-sized to purpose, and built for what come
## Headless Mode ## Headless Mode
When invoked headless, do not ask. Complete the intent using what is provided, what exists in the run folder, or what you can discover yourself. End with a JSON response listing status, intent, and artifact paths, for example: When invoked headless, do not ask. Complete the intent using what is provided, what exists in `{doc_workspace}`, or what you can discover yourself. If intent remains ambiguous after inference, halt with a `blocked` JSON status and a `reason` field — do not prompt. End with a JSON response listing status, intent, and artifact paths, for example:
```json ```json
{ {
"status": "complete", "status": "complete",
"intent": "create", "intent": "create",
"brief": "{run_folder}/brief.md", "brief": "{doc_workspace}/brief.md",
"addendum": "{run_folder}/addendum.md", "addendum": "{doc_workspace}/addendum.md",
"distillate": "{run_folder}/distillate.md", "distillate": "{doc_workspace}/distillate.md",
"decision_log": "{run_folder}/decision-log.md", "decision_log": "{doc_workspace}/decision-log.md",
"open_questions": [] "open_questions": []
} }
``` ```
@ -61,7 +61,7 @@ Conversationally surface what the user brings, why this brief exists, and the do
## Finalize ## Finalize
1. Decision log audit + addendum: the user ends this step with an explicit, shared accounting of how the meaningful contents of `decision-log.md` were handled — captured in the brief, captured in `addendum.md` (rejected-alternative rationale, options-considered matrices, parked-roadmap context, technical constraints, sizing data, in-depth personas), or set aside as process noise. `addendum.md` exists if anything earned its place there. 1. Decision log audit + addendum: the user ends this step with an explicit, shared accounting of how the meaningful contents of `decision-log.md` were handled — captured in the brief, captured in `addendum.md` (rejected-alternative rationale, options-considered matrices, parked-roadmap context, technical constraints, sizing data, in-depth personas), or set aside as process noise. `addendum.md` exists if anything earned its place there.
2. Polish: apply each entry in `{workflow.polish_passes}` (a `skill:`, `file:`, or plain-text directive) to `brief.md` (and `addendum.md` if it exists). Run passes as parallel subagents. The user sees a polished draft, not a polish review. 2. Polish: apply each entry in `{workflow.doc_standards}` (a `skill:`, `file:`, or plain-text directive) to `brief.md` (and `addendum.md` if it exists). Run passes as parallel subagents. The user sees a polished draft, not a polish review.
3. Distillate: offer the user a lean, token-efficient distillate of the brief — frame why it matters (it becomes the primary input when downstream BMad workflows like PRD creation pull this brief in). If they want it, invoke `bmad-distillator` with `source_documents=[brief.md, addendum.md if produced]`, `downstream_consumer="PRD creation"`, `output_path={run_folder}/distillate.md`. If unavailable, note the skip. 3. Distillate: offer the user a lean, token-efficient distillate of the brief — frame why it matters (it becomes the primary input when downstream BMad workflows like PRD creation pull this brief in). If they want it, invoke `bmad-distillator` with `source_documents=[brief.md, addendum.md if produced]`, `downstream_consumer="PRD creation"`, `output_path={doc_workspace}/distillate.md`. If unavailable, note the skip.
4. Tell the user it is ready: artifacts, path, use the `bmad-help` skill to help understand what next steps you can suggest they do in the bmad method ecosystem. 4. Tell the user it is ready: artifacts, path, use the `bmad-help` skill to help understand what next steps you can suggest they do in the bmad method ecosystem.
5. Run `{workflow.on_complete}` if non-empty. Treat a string scalar as a single instruction and an array as a sequence of instructions executed in order. 5. Run `{workflow.on_complete}` if non-empty. Treat a string scalar as a single instruction and an array as a sequence of instructions executed in order.

16
src/bmm-skills/1-analysis/bmad-product-brief/customize.toml
View File

@ -21,12 +21,12 @@ activation_steps_append = []
# Persistent facts the workflow keeps in mind for the whole run # Persistent facts the workflow keeps in mind for the whole run
# (standards, compliance constraints, stylistic guardrails). # (standards, compliance constraints, stylistic guardrails).
# Each entry is either a literal sentence, or a `file:`-prefixed path/glob # Each entry is either a literal sentence, a skill prefixed with `skill:`, or a `file:`-prefixed path/glob
# whose contents are loaded as facts. # whose contents are loaded as facts.
# Default is empty. Common opt-ins (set in your team/user override TOML): # Default is empty. Common opt-ins (set in your team/user override TOML):
# "file:{project-root}/_bmad-output/planning-artifacts/project-context.md" # bmad-generate-project-context output # "file:{project-root}/_bmad-output/planning-artifacts/project-context.md" # bmad-generate-project-context output
# "file:{project-root}/CLAUDE.md" # Claude Code instructions # "skill:acme-co:terms-and-conditions" # a skill that contains some relevant info to the documents that may be generated
# "file:{project-root}/AGENTS.md" # generic agent instructions # "Elvis has left the building" # generic agent instructions
persistent_facts = [] persistent_facts = []
# Executed when the workflow completes (after the user has been told the # Executed when the workflow completes (after the user has been told the
@ -44,9 +44,9 @@ brief_template = "assets/brief-template.md"
output_dir = "{planning_artifacts}/briefs" output_dir = "{planning_artifacts}/briefs"
output_folder_name = "brief-{project_name}-{date}" output_folder_name = "brief-{project_name}-{date}"
# Polish passes applied to human-consumed docs at finalize. The parent LLM # Document standards applied to human-consumed docs at finalize. Each entry is
# applies their findings before the user sees the draft. Polish encodes # a `skill:`, `file:`, or plain-text directive; the parent LLM applies the
# standards, not options. # findings before the user sees the draft. Encodes standards, not options.
# #
# Examples: # Examples:
# "skill:bmad-editorial-review-prose" # "skill:bmad-editorial-review-prose"
@ -58,9 +58,9 @@ output_folder_name = "brief-{project_name}-{date}"
# 2. Content/voice/conventions (org standards, tone, terminology, compliance) # 2. Content/voice/conventions (org standards, tone, terminology, compliance)
# 3. Prose mechanics (grammar, clarity, typos) # 3. Prose mechanics (grammar, clarity, typos)
# #
# Override the array in team/user TOML to add additional passes. Append-only: # Override the array in team/user TOML to add additional standards. Append-only:
# base entries cannot be removed or replaced (resolver has no removal mechanism). # base entries cannot be removed or replaced (resolver has no removal mechanism).
polish_passes = [ doc_standards = [
"skill:bmad-editorial-review-structure", "skill:bmad-editorial-review-structure",
"skill:bmad-editorial-review-prose", "skill:bmad-editorial-review-prose",
] ]