From 1e420bb83cb8c14b87815c4a4731bbb78437be03 Mon Sep 17 00:00:00 2001 From: Brian Madison Date: Tue, 26 May 2026 10:05:24 -0500 Subject: [PATCH] refactor: move builder output config from install prompts to per-skill customize.toml MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Remove the two install-time prompts (`bmad_builder_output_folder` and `bmad_builder_reports`) from `skills/module.yaml` and the bmb-setup install copy. They were a poor fit for module-level config: `bmad_builder_reports` collapsed many distinct artifact destinations into one bucket, and `bmad_builder_output_folder` belongs to the individual builder skills, not the module. New shape per builder skill (`bmad-agent-builder`, `bmad-workflow-builder`, `bmad-module-builder`, `bmad-eval-runner`): [workflow] builder_output_folder = "{project-root}/skills" Override per-skill via `_bmad/custom/.toml` / `.user.toml`. Reports and analyses now land next to whatever's being analyzed: - quality-analysis → {target-skill-path}/reports/quality-analysis// - validate-module → {target-module-path}/reports/validation-.md - convert → {target-skill-path}/reports/convert/ - ideate-module → {output_folder}/module-plans/ (planning, not build) - create-module tmp → `mktemp -d` (ephemeral, not user-visible) - eval-runner → {builder_output_folder}/eval-runs/ else ~/bmad-evals/ SKILL.md config-load preamble in all 4 skills updated to point at config.toml + per-skill customize.toml instead of legacy config.yaml. Module-help CSV `output-location` column carries `builder_output_folder` or `output_folder` for rows with a central scan target, blank for rows whose output is per-invocation (analysis/validate/convert) where completion detection via central scan doesn't apply. Validator (`tools/validate-file-refs.mjs`) updated to recognize the new runtime placeholders ({builder_output_folder}, {target-skill-path}, {target-module-path}, {tmp-dir}). --- AGENTS.md | 2 +- docs/explanation/module-configuration.md | 2 +- docs/how-to/run-evals-against-a-skill.md | 2 +- docs/reference/builder-commands.md | 6 +++--- skills/bmad-agent-builder/SKILL.md | 6 +++--- skills/bmad-agent-builder/customize.toml | 12 ++++++++++++ .../references/build-process.md | 2 +- .../references/quality-analysis.md | 2 +- .../references/standard-fields.md | 4 ++-- skills/bmad-bmb-setup/assets/module-help.csv | 16 ++++++++-------- skills/bmad-bmb-setup/assets/module.yaml | 13 +++---------- skills/bmad-eval-runner/SKILL.md | 4 ++-- skills/bmad-eval-runner/customize.toml | 14 ++++++++++++++ skills/bmad-module-builder/SKILL.md | 2 +- skills/bmad-module-builder/customize.toml | 14 ++++++++++++++ .../references/create-module.md | 9 ++++++--- .../references/ideate-module.md | 4 ++-- .../references/validate-module.md | 2 +- skills/bmad-workflow-builder/SKILL.md | 5 +++-- skills/bmad-workflow-builder/customize.toml | 14 ++++++++++++++ .../references/build-process.md | 2 +- skills/module-help.csv | 16 ++++++++-------- skills/module.yaml | 13 +++---------- tools/validate-file-refs.mjs | 7 +++++-- 24 files changed, 110 insertions(+), 63 deletions(-) create mode 100644 skills/bmad-agent-builder/customize.toml create mode 100644 skills/bmad-eval-runner/customize.toml create mode 100644 skills/bmad-module-builder/customize.toml create mode 100644 skills/bmad-workflow-builder/customize.toml diff --git a/AGENTS.md b/AGENTS.md index 2e8da29..eec1045 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -102,7 +102,7 @@ your-module/ ### Path Variables - `{project-root}/_bmad/bmb/` — Installation path (in repo, maps to `src/`) -- `{bmad_builder_output_folder}` — User's custom content output +- `{builder_output_folder}` — User's custom content output (per-skill, resolved from each builder skill's `customize.toml`) - Runtime variables: `{output_folder}`, `{project-root}` from Core config ## Development Notes diff --git a/docs/explanation/module-configuration.md b/docs/explanation/module-configuration.md index 94b83f5..6918527 100644 --- a/docs/explanation/module-configuration.md +++ b/docs/explanation/module-configuration.md @@ -127,7 +127,7 @@ module,skill,display-name,menu-code,description,action,args,phase,preceded-by,fo | **preceded-by** | Capabilities that should complete before this one (this capability is preceded by them): format `skill-name:action`, comma-separated for multiple | | **followed-by** | Capabilities that should run after this one (this capability is followed by them), same format as `preceded-by` | | **required** | `true` if this is a blocking gate for phase progression, `false` otherwise | -| **output-location** | Config variable name (e.g., `output_folder`, `bmad_builder_reports`); `bmad-help` resolves from config to scan for completion artifacts | +| **output-location** | Config variable name (e.g., `output_folder`, `builder_output_folder`); `bmad-help` resolves from config to scan for completion artifacts. Leave blank when output is per-invocation (e.g., reports that land next to whatever's being analyzed) — completion detection is skipped for those rows. | | **outputs** | File patterns `bmad-help` looks for in the output location to detect completion (e.g., "quality report", "agent skill") | ### How bmad-help Uses These Entries diff --git a/docs/how-to/run-evals-against-a-skill.md b/docs/how-to/run-evals-against-a-skill.md index 1d4371e..0ca713d 100644 --- a/docs/how-to/run-evals-against-a-skill.md +++ b/docs/how-to/run-evals-against-a-skill.md @@ -76,7 +76,7 @@ The runner stages each eval's workspace, executes `claude -p` against the prompt When the run finishes, the runner emits two paths: -- The run folder, at `~/bmad-evals//` (or your configured `bmad_builder_reports` location) +- The run folder, at `~/bmad-evals//` (or `{builder_output_folder}/eval-runs//` if `bmad-eval-runner`'s `customize.toml` is resolvable) - An HTML report at `/report.html` Open the report for the summary view. Drop into the run folder for full transcripts, artifacts, and grading details for any eval you want to examine. diff --git a/docs/reference/builder-commands.md b/docs/reference/builder-commands.md index 2485e01..12626d1 100644 --- a/docs/reference/builder-commands.md +++ b/docs/reference/builder-commands.md @@ -248,7 +248,7 @@ The optimizer runs three tiers of analysis. ### Report Synthesis -After all scanners complete, the optimizer synthesizes results into a unified report saved to `{bmad_builder_reports}/{skill-name}/quality-scan/{timestamp}/`. +After all scanners complete, the optimizer synthesizes results into a unified report saved to `{target-skill-path}/reports/quality-scan/{timestamp}/` — reports always land next to the skill being analyzed. In interactive mode, it presents a summary with severity counts and offers next steps: @@ -299,7 +299,7 @@ The HTML report includes: | **What survived** | Content that earns its place: instructions the LLM wouldn't follow correctly without being told | | **Verdict** | One-sentence summary of the conversion | -Reports are saved to `{bmad_builder_reports}/convert-{skill-name}/`. +Reports are saved to `{target-skill-path}/reports/convert/` — next to the skill being converted. ### When to Use Convert vs Build Process @@ -331,7 +331,7 @@ A brainstorming session that helps you plan your module from scratch. The builde | --------------- | ----------------------------------------------- | | **Interaction** | Interactive only; no headless mode | | **Input** | An idea or rough description | -| **Output** | Plan document saved to `{bmad_builder_reports}` | +| **Output** | Plan document saved to `{output_folder}/module-plans/` | **What it covers:** diff --git a/skills/bmad-agent-builder/SKILL.md b/skills/bmad-agent-builder/SKILL.md index 9a79282..034c991 100644 --- a/skills/bmad-agent-builder/SKILL.md +++ b/skills/bmad-agent-builder/SKILL.md @@ -19,12 +19,12 @@ Act as an architect guide — walk users through conversational discovery to und 1. Detect user's intent. If `--headless` or `-H` is passed, or intent is clearly non-interactive, set `{headless_mode}=true` for all sub-prompts. -2. Load available config from `{project-root}/_bmad/config.yaml` and `{project-root}/_bmad/config.user.yaml` (root and bmb section). If neither exists, fall back to `{project-root}/_bmad/bmb/config.yaml` (legacy per-module format). If still missing, and the `bmad-builder-setup` skill is available, let the user know they can run it at any time to configure. Resolve and apply throughout the session (defaults in parens): +2. Load core config from `{project-root}/_bmad/config.toml` (and `config.user.toml`) for shared identity values. Resolve this skill's `customize.toml` (merged with any `{project-root}/_bmad/custom/bmad-agent-builder.toml` and `.user.toml` overrides) for skill-local knobs. Apply throughout the session (defaults in parens): - `{user_name}` (default: null) — address the user by name - `{communication_language}` (default: user or system intent) — use for all communications - `{document_output_language}` (default: user or system intent) — use for generated document content - - `{bmad_builder_output_folder}` (default: `{project-root}/skills`) — save built agents here - - `{bmad_builder_reports}` (default: `{project-root}/skills/reports`) — save reports (quality, eval, planning) here + - `{builder_output_folder}` (default: `{project-root}/skills`) — save built agents here + - Quality / analysis reports always land next to the skill being analyzed: `/reports///`. 3. Route by intent — see Quick Reference below. diff --git a/skills/bmad-agent-builder/customize.toml b/skills/bmad-agent-builder/customize.toml new file mode 100644 index 0000000..19d05f2 --- /dev/null +++ b/skills/bmad-agent-builder/customize.toml @@ -0,0 +1,12 @@ +# DO NOT EDIT -- overwritten on every update. +# +# Workflow customization surface for bmad-agent-builder. +# +# Override files (not edited here): +# {project-root}/_bmad/custom/bmad-agent-builder.toml (team) +# {project-root}/_bmad/custom/bmad-agent-builder.user.toml (personal) + +[workflow] + +# Where built agent skills land. Override in team/user TOML to redirect. +builder_output_folder = "{project-root}/skills" diff --git a/skills/bmad-agent-builder/references/build-process.md b/skills/bmad-agent-builder/references/build-process.md index 5833533..5ea624e 100644 --- a/skills/bmad-agent-builder/references/build-process.md +++ b/skills/bmad-agent-builder/references/build-process.md @@ -208,7 +208,7 @@ Load `./references/sample-capability-prompt.md` as a quality reference for capab - `./references/skill-best-practices.md` — outcome-driven authoring, patterns, anti-patterns - `./references/quality-dimensions.md` — build quality checklist -Build the agent using templates from `./assets/` and rules from `./references/template-substitution-rules.md`. Output to `{bmad_builder_output_folder}`. +Build the agent using templates from `./assets/` and rules from `./references/template-substitution-rules.md`. Output to `{builder_output_folder}`. ### Emit `customize.toml` (always, every archetype) diff --git a/skills/bmad-agent-builder/references/quality-analysis.md b/skills/bmad-agent-builder/references/quality-analysis.md index e66c6c6..f87e380 100644 --- a/skills/bmad-agent-builder/references/quality-analysis.md +++ b/skills/bmad-agent-builder/references/quality-analysis.md @@ -64,7 +64,7 @@ Each scanner writes a free-form analysis document: ## Execution -First create output directory: `{bmad_builder_reports}/{skill-name}/quality-analysis/{date-time-stamp}/` +First create output directory: `{target-skill-path}/reports/quality-analysis/{date-time-stamp}/` — reports always land next to the skill being analyzed, never in a central bucket. ### Step 1: Run All Scripts (Parallel) diff --git a/skills/bmad-agent-builder/references/standard-fields.md b/skills/bmad-agent-builder/references/standard-fields.md index 3213486..4509d11 100644 --- a/skills/bmad-agent-builder/references/standard-fields.md +++ b/skills/bmad-agent-builder/references/standard-fields.md @@ -194,5 +194,5 @@ Use `{project-root}/...` for any path relative to the project root: Use directly — they already contain `{project-root}` in their resolved values: - `{output_folder}/file.md` -- Correct: `{bmad_builder_output_folder}/agent.md` -- Wrong: `{project-root}/{bmad_builder_output_folder}/agent.md` (double-prefix) +- Correct: `{builder_output_folder}/agent.md` +- Wrong: `{project-root}/{builder_output_folder}/agent.md` (double-prefix) diff --git a/skills/bmad-bmb-setup/assets/module-help.csv b/skills/bmad-bmb-setup/assets/module-help.csv index 0f052a9..ea31172 100644 --- a/skills/bmad-bmb-setup/assets/module-help.csv +++ b/skills/bmad-bmb-setup/assets/module-help.csv @@ -1,10 +1,10 @@ module,skill,display-name,menu-code,description,action,args,phase,preceded-by,followed-by,required,output-location,outputs BMad Builder,bmad-bmb-setup,Setup Builder Module,SB,"Install or update BMad Builder module config and help entries.",configure,"{-H: headless mode}|{inline values: skip prompts with provided values}",anytime,,,false,{project-root}/_bmad,config.yaml and config.user.yaml -BMad Builder,bmad-agent-builder,Build an Agent,BA,"Create, edit, or rebuild an agent skill through conversational discovery.",build-process,"{-H: headless mode}|{description: initial agent concept}|{path: existing agent to edit or rebuild}",anytime,,bmad-agent-builder:quality-analysis,false,bmad_builder_output_folder,agent skill -BMad Builder,bmad-agent-builder,Analyze an Agent,AA,"Run quality analysis on an existing agent — structure, cohesion, prompt craft, and enhancement opportunities.",quality-analysis,"{-H: headless mode}|{path: agent to analyze}",anytime,bmad-agent-builder:build-process,,false,bmad_builder_reports,quality report -BMad Builder,bmad-workflow-builder,Build a Workflow,BW,"Create, edit, or rebuild a workflow or utility skill.",build-process,"{-H: headless mode}|{description: initial skill concept}|{path: existing skill to edit or rebuild}",anytime,,bmad-workflow-builder:quality-analysis,false,bmad_builder_output_folder,workflow skill -BMad Builder,bmad-workflow-builder,Analyze a Workflow,AW,"Run quality analysis on an existing workflow/skill — structure, efficiency, and enhancement opportunities.",quality-analysis,"{-H: headless mode}|{path: skill to analyze}",anytime,bmad-workflow-builder:build-process,,false,bmad_builder_reports,quality report -BMad Builder,bmad-workflow-builder,Convert a Skill,CW,"Convert any skill to BMad-compliant, outcome-driven equivalent with before/after HTML comparison report.",convert-process,"{--convert: path or URL to source skill}|{-H: headless mode}",anytime,,,false,bmad_builder_reports,converted skill + comparison report -BMad Builder,bmad-module-builder,Ideate Module,IM,"Brainstorm and plan a BMad module — explore ideas, decide architecture, and produce a build plan.",ideate-module,"{description: initial module idea}",anytime,,bmad-module-builder:create-module,false,bmad_builder_reports,module plan -BMad Builder,bmad-module-builder,Create Module,CM,"Scaffold module infrastructure into built skills, making them an installable BMad module.",create-module,"{-H: headless mode}|{path: skills folder or single SKILL.md}",anytime,bmad-module-builder:ideate-module,,false,bmad_builder_output_folder,setup skill -BMad Builder,bmad-module-builder,Validate Module,VM,"Check that a module's structure is complete, accurate, and all capabilities are properly registered.",validate-module,"{-H: headless mode}|{path: module or skill to validate}",anytime,bmad-module-builder:create-module,,false,bmad_builder_reports,validation report +BMad Builder,bmad-agent-builder,Build an Agent,BA,"Create, edit, or rebuild an agent skill through conversational discovery.",build-process,"{-H: headless mode}|{description: initial agent concept}|{path: existing agent to edit or rebuild}",anytime,,bmad-agent-builder:quality-analysis,false,builder_output_folder,agent skill +BMad Builder,bmad-agent-builder,Analyze an Agent,AA,"Run quality analysis on an existing agent — structure, cohesion, prompt craft, and enhancement opportunities.",quality-analysis,"{-H: headless mode}|{path: agent to analyze}",anytime,bmad-agent-builder:build-process,,false,,quality report (lands next to analyzed skill) +BMad Builder,bmad-workflow-builder,Build a Workflow,BW,"Create, edit, or rebuild a workflow or utility skill.",build-process,"{-H: headless mode}|{description: initial skill concept}|{path: existing skill to edit or rebuild}",anytime,,bmad-workflow-builder:quality-analysis,false,builder_output_folder,workflow skill +BMad Builder,bmad-workflow-builder,Analyze a Workflow,AW,"Run quality analysis on an existing workflow/skill — structure, efficiency, and enhancement opportunities.",quality-analysis,"{-H: headless mode}|{path: skill to analyze}",anytime,bmad-workflow-builder:build-process,,false,,quality report (lands next to analyzed skill) +BMad Builder,bmad-workflow-builder,Convert a Skill,CW,"Convert any skill to BMad-compliant, outcome-driven equivalent with before/after HTML comparison report.",convert-process,"{--convert: path or URL to source skill}|{-H: headless mode}",anytime,,,false,,converted skill + comparison report (next to source) +BMad Builder,bmad-module-builder,Ideate Module,IM,"Brainstorm and plan a BMad module — explore ideas, decide architecture, and produce a build plan.",ideate-module,"{description: initial module idea}",anytime,,bmad-module-builder:create-module,false,output_folder,module plan +BMad Builder,bmad-module-builder,Create Module,CM,"Scaffold module infrastructure into built skills, making them an installable BMad module.",create-module,"{-H: headless mode}|{path: skills folder or single SKILL.md}",anytime,bmad-module-builder:ideate-module,,false,builder_output_folder,setup skill +BMad Builder,bmad-module-builder,Validate Module,VM,"Check that a module's structure is complete, accurate, and all capabilities are properly registered.",validate-module,"{-H: headless mode}|{path: module or skill to validate}",anytime,bmad-module-builder:create-module,,false,,validation report (lands next to analyzed module) diff --git a/skills/bmad-bmb-setup/assets/module.yaml b/skills/bmad-bmb-setup/assets/module.yaml index 439f7de..314fbfa 100644 --- a/skills/bmad-bmb-setup/assets/module.yaml +++ b/skills/bmad-bmb-setup/assets/module.yaml @@ -5,16 +5,9 @@ module_version: 1.0.0 default_selected: false module_greeting: > Enjoy making your dream creations with the BMad Builder Module! - Run this again at any time if you want to reconfigure a setting or have updated the module, (or optionally just update _bmad/config.yaml and config.user.yaml to change existing values) - For questions, suggestions and support - check us on Discord at https://discord.gg/gk8jAdXWmj -bmad_builder_output_folder: - prompt: "Where should your custom output (agent, workflow, module config) be saved?" - default: "{project-root}/skills" - result: "{project-root}/{value}" + Each builder skill carries its own `customize.toml` with sane defaults (built artifacts land in `{project-root}/skills`). Override per-skill in `_bmad/custom/{skill-name}.toml` if you want a different home; reports and analyses always land next to whatever's being analyzed. + -bmad_builder_reports: - prompt: "Output for Evals, Test, Quality and Planning Reports?" - default: "{project-root}/skills/reports" - result: "{project-root}/{value}" + For questions, suggestions and support - check us on Discord at https://discord.gg/gk8jAdXWmj diff --git a/skills/bmad-eval-runner/SKILL.md b/skills/bmad-eval-runner/SKILL.md index 911dbc9..7142b98 100644 --- a/skills/bmad-eval-runner/SKILL.md +++ b/skills/bmad-eval-runner/SKILL.md @@ -23,13 +23,13 @@ You are an experienced eval engineer. The user wants signal, not theatre. Cite s - `--mode artifact|trigger|both` — which eval kind to run. Default: `both` if both files are found, else whichever exists. - `--isolation docker|local|auto` — sandbox strategy. Default: `auto` (Docker when available, otherwise local). - `--project-root ` — root of the project the skill belongs to. Default: walk up from skill path looking for `_bmad/` or `.git/`. -- `--output-dir ` — where run folders are written. Default: `{bmad_builder_reports}/eval-runs/` if configured, else `~/bmad-evals/`. +- `--output-dir ` — where run folders are written. Default: `{builder_output_folder}/eval-runs/` if `customize.toml` is resolvable, else `~/bmad-evals/`. - `--workers ` — parallel evals. Default: 4. - `--headless` / `-H` — non-interactive; emit final JSON only. ## On Activation -1. Resolve config the same way `bmad-workflow-builder` does (`{project-root}/_bmad/config.yaml` then `config.user.yaml`, falling back to `bmb/config.yaml`). Resolve `{user_name}`, `{communication_language}`, `{bmad_builder_reports}`. Apply throughout the session. +1. Resolve core config from `{project-root}/_bmad/config.toml` (and `config.user.toml`) for `{user_name}` and `{communication_language}`. Resolve this skill's `customize.toml` (merged with any `{project-root}/_bmad/custom/bmad-eval-runner.toml` and `.user.toml` overrides) for `{builder_output_folder}`. Apply throughout the session. 2. If `--headless` was passed, set `{headless_mode}=true` and skip every confirmation below; pick the safest defaults and proceed. diff --git a/skills/bmad-eval-runner/customize.toml b/skills/bmad-eval-runner/customize.toml new file mode 100644 index 0000000..b1eabca --- /dev/null +++ b/skills/bmad-eval-runner/customize.toml @@ -0,0 +1,14 @@ +# DO NOT EDIT -- overwritten on every update. +# +# Workflow customization surface for bmad-eval-runner. +# +# Override files (not edited here): +# {project-root}/_bmad/custom/bmad-eval-runner.toml (team) +# {project-root}/_bmad/custom/bmad-eval-runner.user.toml (personal) + +[workflow] + +# Fallback for --output-dir when no flag is passed and ~/bmad-evals/ is not +# desired. Eval runs land under {builder_output_folder}/eval-runs//. +# Override in team/user TOML to redirect, or pass --output-dir per invocation. +builder_output_folder = "{project-root}/skills" diff --git a/skills/bmad-module-builder/SKILL.md b/skills/bmad-module-builder/SKILL.md index b735e6c..42d1b65 100644 --- a/skills/bmad-module-builder/SKILL.md +++ b/skills/bmad-module-builder/SKILL.md @@ -17,7 +17,7 @@ This skill helps you bring BMad modules to life — from the first spark of an i ## On Activation -Load available config from `{project-root}/_bmad/config.yaml` and `{project-root}/_bmad/config.user.yaml` (root level and `bmb` section). If neither exists, fall back to `{project-root}/_bmad/bmb/config.yaml` (legacy per-module format). If still missing, let the user know `bmad-builder-setup` can configure the module at any time. Use sensible defaults for anything not configured. +Load core config from `{project-root}/_bmad/config.toml` (and `config.user.toml`) for shared identity values. Resolve this skill's `customize.toml` (merged with any `{project-root}/_bmad/custom/bmad-module-builder.toml` and `.user.toml` overrides) for skill-local knobs — most importantly `{builder_output_folder}` (default `{project-root}/skills`), where created modules land. Ideate plan documents land under `{output_folder}/module-plans/`. Validation reports land next to the module being validated. Use sensible defaults for anything not configured. Detect user's intent: diff --git a/skills/bmad-module-builder/customize.toml b/skills/bmad-module-builder/customize.toml new file mode 100644 index 0000000..07facd0 --- /dev/null +++ b/skills/bmad-module-builder/customize.toml @@ -0,0 +1,14 @@ +# DO NOT EDIT -- overwritten on every update. +# +# Workflow customization surface for bmad-module-builder. +# +# Override files (not edited here): +# {project-root}/_bmad/custom/bmad-module-builder.toml (team) +# {project-root}/_bmad/custom/bmad-module-builder.user.toml (personal) + +[workflow] + +# Where created modules and their scaffolded skills land. Override in +# team/user TOML to redirect. Ideate plan documents land under +# {output_folder}/module-plans/ (the core BMad planning area), not here. +builder_output_folder = "{project-root}/skills" diff --git a/skills/bmad-module-builder/references/create-module.md b/skills/bmad-module-builder/references/create-module.md index 0905caf..3184370 100644 --- a/skills/bmad-module-builder/references/create-module.md +++ b/skills/bmad-module-builder/references/create-module.md @@ -167,15 +167,18 @@ Iterate until the user confirms everything is correct. #### Multi-skill modules (setup skill approach) -Write the confirmed module.yaml and module-help.csv content to temporary files at `{bmad_builder_reports}/{module-code}-temp-module.yaml` and `{bmad_builder_reports}/{module-code}-temp-help.csv`. Run the scaffold script: +Write the confirmed module.yaml and module-help.csv content to a freshly-created temp directory (e.g. via `mktemp -d`) — these are ephemeral scaffolding inputs, not user-visible artifacts. Bind the path to `{tmp-dir}` and run the scaffold script: ```bash +TMP_DIR=$(mktemp -d) +# Write {tmp-dir}/{module-code}-temp-module.yaml and {tmp-dir}/{module-code}-temp-help.csv ... python3 ./scripts/scaffold-setup-skill.py \ --target-dir "{skills-folder}" \ --module-code "{code}" \ --module-name "{name}" \ - --module-yaml "{bmad_builder_reports}/{module-code}-temp-module.yaml" \ - --module-csv "{bmad_builder_reports}/{module-code}-temp-help.csv" + --module-yaml "$TMP_DIR/{module-code}-temp-module.yaml" \ + --module-csv "$TMP_DIR/{module-code}-temp-help.csv" +rm -rf "$TMP_DIR" ``` This creates `{code}-setup/` in the user's skills folder containing: diff --git a/skills/bmad-module-builder/references/ideate-module.md b/skills/bmad-module-builder/references/ideate-module.md index 25f799a..37bef45 100644 --- a/skills/bmad-module-builder/references/ideate-module.md +++ b/skills/bmad-module-builder/references/ideate-module.md @@ -8,7 +8,7 @@ You are a creative collaborator and module architect — part brainstorming part ## Session Resume -On activation, check `{bmad_builder_reports}` for an existing plan document matching the user's intent. If one exists with `status: ideation` or `status: in-progress`, load it and orient from its current state: identify which phase was last completed based on which sections have content, briefly summarize where things stand, and ask the user where they'd like to pick up. This prevents re-deriving state from conversation history after context compaction or a new session. +On activation, check `{output_folder}/module-plans` for an existing plan document matching the user's intent. If one exists with `status: ideation` or `status: in-progress`, load it and orient from its current state: identify which phase was last completed based on which sections have content, briefly summarize where things stand, and ask the user where they'd like to pick up. This prevents re-deriving state from conversation history after context compaction or a new session. ## Facilitation Principles @@ -40,7 +40,7 @@ This is a phased process. Each phase has a clear purpose and should not be skipp ### Phase 1: Vision and Module Identity -Initialize the plan document by copying `./assets/module-plan-template.md` to `{bmad_builder_reports}` with a descriptive filename — use a `cp` command rather than reading the template into context. Set `created` and `updated` timestamps. Then immediately write "Not ready — complete in Phase 3+" as placeholder text in all structured sections (Architecture, Memory Architecture, Memory Contract, Cross-Agent Patterns, Skills, Configuration, External Dependencies, UI and Visualization, Setup Extensions, Integration, Creative Use Cases, Build Roadmap). This makes the writing discipline constraint visible in the document itself — only Ideas Captured and frontmatter should be written during Phases 1-2. This document is your cache — update it progressively as the conversation unfolds so work survives context compaction. +Initialize the plan document by copying `./assets/module-plan-template.md` to `{output_folder}/module-plans` with a descriptive filename — use a `cp` command rather than reading the template into context. Set `created` and `updated` timestamps. Then immediately write "Not ready — complete in Phase 3+" as placeholder text in all structured sections (Architecture, Memory Architecture, Memory Contract, Cross-Agent Patterns, Skills, Configuration, External Dependencies, UI and Visualization, Setup Extensions, Integration, Creative Use Cases, Build Roadmap). This makes the writing discipline constraint visible in the document itself — only Ideas Captured and frontmatter should be written during Phases 1-2. This document is your cache — update it progressively as the conversation unfolds so work survives context compaction. **First: capture the spark.** Let the user talk freely — this is where the richest context comes from: diff --git a/skills/bmad-module-builder/references/validate-module.md b/skills/bmad-module-builder/references/validate-module.md index 398eac2..78ac7e6 100644 --- a/skills/bmad-module-builder/references/validate-module.md +++ b/skills/bmad-module-builder/references/validate-module.md @@ -65,7 +65,7 @@ Combine script findings and quality assessment into a clear report: For each finding, explain what's wrong and suggest the fix. Be direct — the user should be able to act on every item without further clarification. -After presenting the report, offer to save findings to a durable file: "Save validation report to `{bmad_builder_reports}/module-validation-{module-code}-{date}.md`?" This gives the user a reference they can share, track as a checklist, and review in future sessions. +After presenting the report, offer to save findings to a durable file: "Save validation report to `{target-module-path}/reports/validation-{date}.md`?" The report lands next to the module being validated, never in a central bucket. This gives the user a reference they can share, track as a checklist, and review in future sessions. **Completion:** After presenting results, explicitly state: "Validation complete." If findings exist, offer to walk through fixes. If the module passes cleanly, confirm it's ready for use. Do not continue the conversation beyond what the user requests — the session is done once results are delivered and any follow-up questions are answered. diff --git a/skills/bmad-workflow-builder/SKILL.md b/skills/bmad-workflow-builder/SKILL.md index c861248..a8b1ee0 100644 --- a/skills/bmad-workflow-builder/SKILL.md +++ b/skills/bmad-workflow-builder/SKILL.md @@ -20,11 +20,12 @@ You are a creative agent skills workflow builder and facilitator. Your job: turn 1. Detect intent. If `--headless` or `-H`, set `{headless_mode}=true` for all sub-prompts. -2. Load config from `{project-root}/_bmad/config.yaml` and `{project-root}/_bmad/config.user.yaml` (root and bmb section). Fall back to `{project-root}/_bmad/bmb/config.yaml` (legacy per-module format). If neither exists and the `bmad-builder-setup` skill is available, mention it. Resolve and apply throughout the session (defaults in parens): +2. Load core config from `{project-root}/_bmad/config.toml` (and `config.user.toml`) for shared identity values. Resolve this skill's `customize.toml` (merged with any `{project-root}/_bmad/custom/bmad-workflow-builder.toml` and `.user.toml` overrides) for skill-local knobs. Apply throughout the session (defaults in parens): - `{user_name}` (default: null) — address the user by name - `{communication_language}` (default: user or system intent) — for all communications - `{document_output_language}` (default: user or system intent) — for generated document content - - `{bmad_builder_output_folder}` (default: `{project-root}/skills`) — where new skills are created. Existing skills use their own path. + - `{builder_output_folder}` (default: `{project-root}/skills`) — where new skills are created. Existing skills use their own path. + - Quality / analysis reports always land next to the skill being analyzed: `/reports///`. 3. **Open the floor (interactive only).** Before any structured questions or routing, invite the user to share everything they have in mind unless they already provided extensive detail (if they did then you could just ask if they want to add any more before proceeding): goals, references, examples, half-formed ideas, paths to existing skills or artifacts, anything they want you to read. Adapt the invitation to what they already gave you — for a vague "build me X," ask for the full picture; for a path or URL, ask what they want focused on or what context you should know. After they share, one soft "anything else?" surfaces what they almost forgot. The dump replaces most structured Q&A downstream; let it run. Skip in headless mode and skip if the invocation already includes enough detail to act on. diff --git a/skills/bmad-workflow-builder/customize.toml b/skills/bmad-workflow-builder/customize.toml new file mode 100644 index 0000000..4464bc0 --- /dev/null +++ b/skills/bmad-workflow-builder/customize.toml @@ -0,0 +1,14 @@ +# DO NOT EDIT -- overwritten on every update. +# +# Workflow customization surface for bmad-workflow-builder. +# +# Override files (not edited here): +# {project-root}/_bmad/custom/bmad-workflow-builder.toml (team) +# {project-root}/_bmad/custom/bmad-workflow-builder.user.toml (personal) + +[workflow] + +# Where new workflow / utility skills land. Existing skills are edited in +# place at their own path; this only applies when creating a fresh skill. +# Override in team/user TOML to redirect. +builder_output_folder = "{project-root}/skills" diff --git a/skills/bmad-workflow-builder/references/build-process.md b/skills/bmad-workflow-builder/references/build-process.md index 900136e..1992797 100644 --- a/skills/bmad-workflow-builder/references/build-process.md +++ b/skills/bmad-workflow-builder/references/build-process.md @@ -62,7 +62,7 @@ Present a plan. Point out vague areas. Iterate with the user until the outcome a - `references/standard-fields.md` — field-by-field schema reference for frontmatter, customize.toml, and the Overview formula - `references/complex-workflow-patterns.md` (Complex Workflow only) — config integration, compaction survival, document-as-cache -Load `assets/SKILL-template.md` and `references/template-substitution-rules.md`. Default to writing the entire workflow inline in SKILL.md as named sections. Carve out to `references/` ONLY when SKILL.md would otherwise be too big to scan; when you do, use descriptive filenames (`press-release.md`), never numbered prefixes (`01-discover.md`). Output to `{bmad_builder_output_folder}`. +Load `assets/SKILL-template.md` and `references/template-substitution-rules.md`. Default to writing the entire workflow inline in SKILL.md as named sections. Carve out to `references/` ONLY when SKILL.md would otherwise be too big to scan; when you do, use descriptive filenames (`press-release.md`), never numbered prefixes (`01-discover.md`). Output to `{builder_output_folder}`. **If the SKILL.md references multiple internal files** (anything in `references/`, `assets/`, `scripts/`, `agents/`), stamp the Conventions block at the top of SKILL.md (after Overview, before On Activation): diff --git a/skills/module-help.csv b/skills/module-help.csv index 81fca91..c1a0fad 100644 --- a/skills/module-help.csv +++ b/skills/module-help.csv @@ -1,11 +1,11 @@ module,skill,display-name,menu-code,description,action,args,phase,preceded-by,followed-by,required,output-location,outputs BMad Builder,_meta,,,,,,,,,false,https://bmad-builder-docs.bmad-method.org/llms.txt, BMad Builder,bmad-bmb-setup,Setup Builder Module,SB,"Install or update BMad Builder module config and help entries.",configure,"{-H: headless mode}|{inline values: skip prompts with provided values}",anytime,,,false,{project-root}/_bmad,config.yaml and config.user.yaml -BMad Builder,bmad-agent-builder,Build an Agent,BA,"Create, edit, or rebuild an agent skill through conversational discovery.",build-process,"{-H: headless mode}|{description: initial agent concept}|{path: existing agent to edit or rebuild}",anytime,,bmad-agent-builder:quality-analysis,false,bmad_builder_output_folder,agent skill -BMad Builder,bmad-agent-builder,Analyze an Agent,AA,"Run quality analysis on an existing agent — structure, cohesion, prompt craft, and enhancement opportunities.",quality-analysis,"{-H: headless mode}|{path: agent to analyze}",anytime,bmad-agent-builder:build-process,,false,bmad_builder_reports,quality report -BMad Builder,bmad-workflow-builder,Build a Workflow,BW,"Create, edit, or rebuild a workflow or utility skill.",build-process,"{-H: headless mode}|{description: initial skill concept}|{path: existing skill to edit or rebuild}",anytime,,bmad-workflow-builder:quality-analysis,false,bmad_builder_output_folder,workflow skill -BMad Builder,bmad-workflow-builder,Analyze a Workflow,AW,"Run quality analysis on an existing workflow/skill — structure, efficiency, and enhancement opportunities.",quality-analysis,"{-H: headless mode}|{path: skill to analyze}",anytime,bmad-workflow-builder:build-process,,false,bmad_builder_reports,quality report -BMad Builder,bmad-workflow-builder,Convert a Skill,CW,"Convert any skill to BMad-compliant, outcome-driven equivalent with before/after HTML comparison report.",convert-process,"{--convert: path or URL to source skill}|{-H: headless mode}",anytime,,,false,bmad_builder_reports,converted skill + comparison report -BMad Builder,bmad-module-builder,Ideate Module,IM,"Brainstorm and plan a BMad module — explore ideas, decide architecture, and produce a build plan.",ideate-module,"{description: initial module idea}",anytime,,bmad-module-builder:create-module,false,bmad_builder_reports,module plan -BMad Builder,bmad-module-builder,Create Module,CM,"Scaffold module infrastructure into built skills, making them an installable BMad module.",create-module,"{-H: headless mode}|{path: skills folder or single SKILL.md}",anytime,bmad-module-builder:ideate-module,,false,bmad_builder_output_folder,setup skill -BMad Builder,bmad-module-builder,Validate Module,VM,"Check that a module's structure is complete, accurate, and all capabilities are properly registered.",validate-module,"{-H: headless mode}|{path: module or skill to validate}",anytime,bmad-module-builder:create-module,,false,bmad_builder_reports,validation report +BMad Builder,bmad-agent-builder,Build an Agent,BA,"Create, edit, or rebuild an agent skill through conversational discovery.",build-process,"{-H: headless mode}|{description: initial agent concept}|{path: existing agent to edit or rebuild}",anytime,,bmad-agent-builder:quality-analysis,false,builder_output_folder,agent skill +BMad Builder,bmad-agent-builder,Analyze an Agent,AA,"Run quality analysis on an existing agent — structure, cohesion, prompt craft, and enhancement opportunities.",quality-analysis,"{-H: headless mode}|{path: agent to analyze}",anytime,bmad-agent-builder:build-process,,false,,quality report (lands next to analyzed skill) +BMad Builder,bmad-workflow-builder,Build a Workflow,BW,"Create, edit, or rebuild a workflow or utility skill.",build-process,"{-H: headless mode}|{description: initial skill concept}|{path: existing skill to edit or rebuild}",anytime,,bmad-workflow-builder:quality-analysis,false,builder_output_folder,workflow skill +BMad Builder,bmad-workflow-builder,Analyze a Workflow,AW,"Run quality analysis on an existing workflow/skill — structure, efficiency, and enhancement opportunities.",quality-analysis,"{-H: headless mode}|{path: skill to analyze}",anytime,bmad-workflow-builder:build-process,,false,,quality report (lands next to analyzed skill) +BMad Builder,bmad-workflow-builder,Convert a Skill,CW,"Convert any skill to BMad-compliant, outcome-driven equivalent with before/after HTML comparison report.",convert-process,"{--convert: path or URL to source skill}|{-H: headless mode}",anytime,,,false,,converted skill + comparison report (next to source) +BMad Builder,bmad-module-builder,Ideate Module,IM,"Brainstorm and plan a BMad module — explore ideas, decide architecture, and produce a build plan.",ideate-module,"{description: initial module idea}",anytime,,bmad-module-builder:create-module,false,output_folder,module plan +BMad Builder,bmad-module-builder,Create Module,CM,"Scaffold module infrastructure into built skills, making them an installable BMad module.",create-module,"{-H: headless mode}|{path: skills folder or single SKILL.md}",anytime,bmad-module-builder:ideate-module,,false,builder_output_folder,setup skill +BMad Builder,bmad-module-builder,Validate Module,VM,"Check that a module's structure is complete, accurate, and all capabilities are properly registered.",validate-module,"{-H: headless mode}|{path: module or skill to validate}",anytime,bmad-module-builder:create-module,,false,,validation report (lands next to analyzed module) diff --git a/skills/module.yaml b/skills/module.yaml index 439f7de..314fbfa 100644 --- a/skills/module.yaml +++ b/skills/module.yaml @@ -5,16 +5,9 @@ module_version: 1.0.0 default_selected: false module_greeting: > Enjoy making your dream creations with the BMad Builder Module! - Run this again at any time if you want to reconfigure a setting or have updated the module, (or optionally just update _bmad/config.yaml and config.user.yaml to change existing values) - For questions, suggestions and support - check us on Discord at https://discord.gg/gk8jAdXWmj -bmad_builder_output_folder: - prompt: "Where should your custom output (agent, workflow, module config) be saved?" - default: "{project-root}/skills" - result: "{project-root}/{value}" + Each builder skill carries its own `customize.toml` with sane defaults (built artifacts land in `{project-root}/skills`). Override per-skill in `_bmad/custom/{skill-name}.toml` if you want a different home; reports and analyses always land next to whatever's being analyzed. + -bmad_builder_reports: - prompt: "Output for Evals, Test, Quality and Planning Reports?" - default: "{project-root}/skills/reports" - result: "{project-root}/{value}" + For questions, suggestions and support - check us on Discord at https://discord.gg/gk8jAdXWmj diff --git a/tools/validate-file-refs.mjs b/tools/validate-file-refs.mjs index fd897da..a8e9b8e 100644 --- a/tools/validate-file-refs.mjs +++ b/tools/validate-file-refs.mjs @@ -17,7 +17,7 @@ * - Relative refs resolving outside src/ (../../../../core/) * - Install-generated files (config.yaml, docs/ KBs) * - Template placeholders ([N], [name], [template]) - * - Runtime variables ({output_folder}, {bmad_builder_output_folder}, etc.) + * - Runtime variables ({output_folder}, {builder_output_folder}, etc.) * - {{mustache}} template variables * - Lines with comment * - Lines after comment @@ -70,7 +70,10 @@ const UNRESOLVABLE_VARS = [ '{research_topic}', '{user_name}', '{communication_language}', - '{bmad_builder_output_folder}', + '{builder_output_folder}', + '{target-skill-path}', + '{target-module-path}', + '{tmp-dir}', '{new_workflow_name}', '{module_code}', '{workflow_name}',