diff --git a/docs/how-to/customize-bmad.md b/docs/how-to/customize-bmad.md index b6dc6e1fb..18a3a0bbb 100644 --- a/docs/how-to/customize-bmad.md +++ b/docs/how-to/customize-bmad.md @@ -258,6 +258,27 @@ on_complete = "Summarize the brief in three bullets and offer to email it via th The same field conventions cross the agent/workflow boundary: `activation_steps_prepend`/`activation_steps_append`, `persistent_facts` (with `file:` refs), and menu-style `[[…]]` tables with `code`/`id` for keyed merge. The resolver applies the same four structural rules regardless of the top-level key. SKILL.md references follow the namespace: `{workflow.activation_steps_prepend}`, `{workflow.persistent_facts}`, `{workflow.on_complete}`. Any additional fields a workflow exposes (output paths, toggles, review settings, stage flags) follow the same shape-based merge rules. Read the workflow's `customize.toml` to see what's customizable. +### Activation Order + +Customizable workflows run their activation in a fixed sequence so you know exactly when your hooks fire: + +1. Resolve the `[workflow]` block (base → team → user merge) +2. Execute `activation_steps_prepend` in order +3. Load `persistent_facts` as foundational context for the run +4. Load config (`_bmad/bmm/config.yaml`) and resolve standard variables (project name, languages, paths, date) +5. Greet the user +6. Execute `activation_steps_append` in order + +After step 6 the workflow body begins. Use `activation_steps_prepend` when you need context loaded before the greeting can be personalized; use `activation_steps_append` when the setup is heavy and you'd rather the user sees the greeting first. + +### Scope of This Initial Pass + +Customization is rolling out incrementally. The fields documented above — `activation_steps_prepend`, `activation_steps_append`, `persistent_facts`, `on_complete` — are the **baseline surface** that every customizable workflow exposes, and they will remain stable across versions. They give you broad-stroke control today: inject pre/post steps, pin foundational context, trigger follow-up actions. + +Over time, individual workflows will expose **more targeted customization points** tailored to what that workflow actually does — things like step-specific toggles, stage flags, output template paths, or review gates. When those arrive, they stack on top of the baseline fields rather than replacing them, so customizations you author today keep working. + +If you need a fine-grained knob that isn't exposed yet, either use `activation_steps_*` and `persistent_facts` to steer behavior, or open an issue describing the specific customization point you want — those requests are what drive which targeted fields get added next. + ## Central Configuration Per-skill `customize.toml` covers **deep behavior** (hooks, menus, persistent_facts, persona overrides for a single agent or workflow). A separate surface covers **cross-cutting state** — install answers and the agent roster that external skills like `bmad-party-mode`, `bmad-retrospective`, and `bmad-advanced-elicitation` consume. That surface lives in four TOML files at project root: diff --git a/src/bmm-skills/1-analysis/research/bmad-domain-research/SKILL.md b/src/bmm-skills/1-analysis/research/bmad-domain-research/SKILL.md index c2d62abbc..be364aa2f 100644 --- a/src/bmm-skills/1-analysis/research/bmad-domain-research/SKILL.md +++ b/src/bmm-skills/1-analysis/research/bmad-domain-research/SKILL.md @@ -87,8 +87,9 @@ After gathering the topic and goals: 1. Set `research_type = "domain"` 2. Set `research_topic = [discovered topic from discussion]` 3. Set `research_goals = [discovered goals from discussion]` -4. Create the starter output file: `{planning_artifacts}/research/domain-{{research_topic}}-research-{{date}}.md` with exact copy of the `./research.template.md` contents -5. Load: `./domain-steps/step-01-init.md` with topic context +4. Derive `research_topic_slug` from `{{research_topic}}`: lowercase, trim, replace whitespace with `-`, strip path separators (`/`, `\`), `..`, and any character that is not alphanumeric, `-`, or `_`. Collapse repeated `-` and strip leading/trailing `-`. If the result is empty, use `untitled`. +5. Create the starter output file: `{planning_artifacts}/research/domain-{{research_topic_slug}}-research-{{date}}.md` with exact copy of the `./research.template.md` contents +6. Load: `./domain-steps/step-01-init.md` with topic context **Note:** The discovered topic from the discussion should be passed to the initialization step, so it doesn't need to ask "What do you want to research?" again - it can focus on refining the scope for domain research. diff --git a/src/bmm-skills/1-analysis/research/bmad-market-research/SKILL.md b/src/bmm-skills/1-analysis/research/bmad-market-research/SKILL.md index 1f61f75a0..964049085 100644 --- a/src/bmm-skills/1-analysis/research/bmad-market-research/SKILL.md +++ b/src/bmm-skills/1-analysis/research/bmad-market-research/SKILL.md @@ -87,8 +87,9 @@ After gathering the topic and goals: 1. Set `research_type = "market"` 2. Set `research_topic = [discovered topic from discussion]` 3. Set `research_goals = [discovered goals from discussion]` -4. Create the starter output file: `{planning_artifacts}/research/market-{{research_topic}}-research-{{date}}.md` with exact copy of the `./research.template.md` contents -5. Load: `./steps/step-01-init.md` with topic context +4. Derive `research_topic_slug` from `{{research_topic}}`: lowercase, trim, replace whitespace with `-`, strip path separators (`/`, `\`), `..`, and any character that is not alphanumeric, `-`, or `_`. Collapse repeated `-` and strip leading/trailing `-`. If the result is empty, use `untitled`. +5. Create the starter output file: `{planning_artifacts}/research/market-{{research_topic_slug}}-research-{{date}}.md` with exact copy of the `./research.template.md` contents +6. Load: `./steps/step-01-init.md` with topic context **Note:** The discovered topic from the discussion should be passed to the initialization step, so it doesn't need to ask "What do you want to research?" again - it can focus on refining the scope for market research. diff --git a/src/bmm-skills/1-analysis/research/bmad-technical-research/SKILL.md b/src/bmm-skills/1-analysis/research/bmad-technical-research/SKILL.md index 6fb164da4..582a05c60 100644 --- a/src/bmm-skills/1-analysis/research/bmad-technical-research/SKILL.md +++ b/src/bmm-skills/1-analysis/research/bmad-technical-research/SKILL.md @@ -87,8 +87,9 @@ After gathering the topic and goals: 1. Set `research_type = "technical"` 2. Set `research_topic = [discovered topic from discussion]` 3. Set `research_goals = [discovered goals from discussion]` -4. Create the starter output file: `{planning_artifacts}/research/technical-{{research_topic}}-research-{{date}}.md` with exact copy of the `./research.template.md` contents -5. Load: `./technical-steps/step-01-init.md` with topic context +4. Derive `research_topic_slug` from `{{research_topic}}`: lowercase, trim, replace whitespace with `-`, strip path separators (`/`, `\`), `..`, and any character that is not alphanumeric, `-`, or `_`. Collapse repeated `-` and strip leading/trailing `-`. If the result is empty, use `untitled`. +5. Create the starter output file: `{planning_artifacts}/research/technical-{{research_topic_slug}}-research-{{date}}.md` with exact copy of the `./research.template.md` contents +6. Load: `./technical-steps/step-01-init.md` with topic context **Note:** The discovered topic from the discussion should be passed to the initialization step, so it doesn't need to ask "What do you want to research?" again - it can focus on refining the scope for technical research. diff --git a/src/bmm-skills/2-plan-workflows/bmad-create-prd/SKILL.md b/src/bmm-skills/2-plan-workflows/bmad-create-prd/SKILL.md index 8de23195e..1ad02d01d 100644 --- a/src/bmm-skills/2-plan-workflows/bmad-create-prd/SKILL.md +++ b/src/bmm-skills/2-plan-workflows/bmad-create-prd/SKILL.md @@ -24,7 +24,7 @@ This uses **step-file architecture** for disciplined execution: ### Core Principles -- **Micro-file Design**: Each step is a self contained instruction file that is a part of an overall workflow that must be followed exactly +- **Micro-file Design**: Each step is a self-contained instruction file that is a part of an overall workflow that must be followed exactly - **Just-In-Time Loading**: Only the current step file is in memory - never load future step files until told to do so - **Sequential Enforcement**: Sequence within the step files must be completed in order, no skipping or optimization allowed - **State Tracking**: Document progress in output file frontmatter using `stepsCompleted` array when a workflow produces a document diff --git a/src/bmm-skills/2-plan-workflows/bmad-edit-prd/SKILL.md b/src/bmm-skills/2-plan-workflows/bmad-edit-prd/SKILL.md index 0b7dd9718..e209df340 100644 --- a/src/bmm-skills/2-plan-workflows/bmad-edit-prd/SKILL.md +++ b/src/bmm-skills/2-plan-workflows/bmad-edit-prd/SKILL.md @@ -24,7 +24,7 @@ This uses **step-file architecture** for disciplined execution: ### Core Principles -- **Micro-file Design**: Each step is a self contained instruction file that is a part of an overall workflow that must be followed exactly +- **Micro-file Design**: Each step is a self-contained instruction file that is a part of an overall workflow that must be followed exactly - **Just-In-Time Loading**: Only the current step file is in memory - never load future step files until told to do so - **Sequential Enforcement**: Sequence within the step files must be completed in order, no skipping or optimization allowed - **State Tracking**: Document progress in output file frontmatter using `stepsCompleted` array when a workflow produces a document diff --git a/src/bmm-skills/2-plan-workflows/bmad-validate-prd/SKILL.md b/src/bmm-skills/2-plan-workflows/bmad-validate-prd/SKILL.md index d3cce314d..90ec68f17 100644 --- a/src/bmm-skills/2-plan-workflows/bmad-validate-prd/SKILL.md +++ b/src/bmm-skills/2-plan-workflows/bmad-validate-prd/SKILL.md @@ -24,7 +24,7 @@ This uses **step-file architecture** for disciplined execution: ### Core Principles -- **Micro-file Design**: Each step is a self contained instruction file that is a part of an overall workflow that must be followed exactly +- **Micro-file Design**: Each step is a self-contained instruction file that is a part of an overall workflow that must be followed exactly - **Just-In-Time Loading**: Only the current step file is in memory - never load future step files until told to do so - **Sequential Enforcement**: Sequence within the step files must be completed in order, no skipping or optimization allowed - **State Tracking**: Document progress in output file frontmatter using `stepsCompleted` array when a workflow produces a document diff --git a/src/bmm-skills/3-solutioning/bmad-check-implementation-readiness/SKILL.md b/src/bmm-skills/3-solutioning/bmad-check-implementation-readiness/SKILL.md index f07b298af..1d5133f90 100644 --- a/src/bmm-skills/3-solutioning/bmad-check-implementation-readiness/SKILL.md +++ b/src/bmm-skills/3-solutioning/bmad-check-implementation-readiness/SKILL.md @@ -20,7 +20,7 @@ description: 'Validate PRD, UX, Architecture and Epics specs are complete. Use w ### Core Principles -- **Micro-file Design**: Each step of the overall goal is a self contained instruction file that you will adhere too 1 file as directed at a time +- **Micro-file Design**: Each step toward the overall goal is a self-contained instruction file; adhere to one file at a time, as directed - **Just-In-Time Loading**: Only 1 current step file will be loaded and followed to completion - never load future step files until told to do so - **Sequential Enforcement**: Sequence within the step files must be completed in order, no skipping or optimization allowed - **State Tracking**: Document progress in output file frontmatter using `stepsCompleted` array when a workflow produces a document diff --git a/src/bmm-skills/3-solutioning/bmad-create-epics-and-stories/SKILL.md b/src/bmm-skills/3-solutioning/bmad-create-epics-and-stories/SKILL.md index a8d987787..a3f0f61c8 100644 --- a/src/bmm-skills/3-solutioning/bmad-create-epics-and-stories/SKILL.md +++ b/src/bmm-skills/3-solutioning/bmad-create-epics-and-stories/SKILL.md @@ -22,7 +22,7 @@ This uses **step-file architecture** for disciplined execution: ### Core Principles -- **Micro-file Design**: Each step of the overall goal is a self contained instruction file that you will adhere too 1 file as directed at a time +- **Micro-file Design**: Each step toward the overall goal is a self-contained instruction file; adhere to one file at a time, as directed - **Just-In-Time Loading**: Only 1 current step file will be loaded and followed to completion - never load future step files until told to do so - **Sequential Enforcement**: Sequence within the step files must be completed in order, no skipping or optimization allowed - **State Tracking**: Document progress in output file frontmatter using `stepsCompleted` array when a workflow produces a document diff --git a/src/bmm-skills/4-implementation/bmad-correct-course/SKILL.md b/src/bmm-skills/4-implementation/bmad-correct-course/SKILL.md index af7c1792c..934479f92 100644 --- a/src/bmm-skills/4-implementation/bmad-correct-course/SKILL.md +++ b/src/bmm-skills/4-implementation/bmad-correct-course/SKILL.md @@ -111,11 +111,11 @@ Activation is complete. Begin the workflow below. Confirm change trigger and gather user description of the issue Ask: "What specific issue or change has been identified that requires navigation?" - Verify access to required project documents: - - PRD (Product Requirements Document) - - Current Epics and Stories - - Architecture documentation - - UI/UX specifications + Verify access to project documents: + - PRD (Product Requirements Document) — required + - Current Epics and Stories — required + - Architecture documentation — optional, load if available + - UI/UX specifications — optional, load if available Ask user for mode preference: - **Incremental** (recommended): Refine each edit collaboratively - **Batch**: Present all changes at once for review @@ -123,7 +123,7 @@ Activation is complete. Begin the workflow below. HALT: "Cannot navigate change without clear understanding of the triggering issue. Please provide specific details about what needs to change and why." -HALT: "Need access to project documents (PRD, Epics, Architecture, UI/UX) to assess change impact. Please ensure these documents are accessible." +HALT: "Need access to PRD and Epics to assess change impact. Please ensure these documents are accessible. Architecture and UI/UX will be used if available." diff --git a/src/bmm-skills/4-implementation/bmad-create-story/SKILL.md b/src/bmm-skills/4-implementation/bmad-create-story/SKILL.md index dd5b44eee..5c3b27a07 100644 --- a/src/bmm-skills/4-implementation/bmad-create-story/SKILL.md +++ b/src/bmm-skills/4-implementation/bmad-create-story/SKILL.md @@ -250,8 +250,7 @@ Activation is complete. Begin the workflow below. Read fully and follow `./discover-inputs.md` to load all input files - Available content: {epics_content}, {prd_content}, {architecture_content}, {ux_content}, - {project_context} + Available content: {epics_content}, {prd_content}, {architecture_content}, {ux_content}, plus the project-context facts loaded during activation via `persistent_facts`. From {epics_content}, extract Epic {{epic_num}} complete context: **EPIC ANALYSIS:** - Epic