bmad-plus 0.7.4 → 0.8.0

package/src/bmad-plus/packs/pack-dev-studio/categories/utilities/bmad-help.md

@@ -1,75 +1,75 @@
----
-name: bmad-help
-description: 'Analyzes current state and user query to answer BMad questions or recommend the next skill(s) to use. Use when user asks for help, bmad help, what to do next, or what to start with in BMad.'
----
-
-# BMad Help
-
-## Purpose
-
-Help the user understand where they are in their BMad workflow and what to do next, and also answer broader questions when asked that could be augmented with remote sources such as module documentation sources.
-
-## Desired Outcomes
-
-When this skill completes, the user should:
-
-1. **Know where they are** — which module and phase they're in, what's already been completed
-2. **Know what to do next** — the next recommended and/or required step, with clear reasoning
-3. **Know how to invoke it** — skill name, menu code, action context, and any args that shortcut the conversation
-4. **Get offered a quick start** — when a single skill is the clear next step, offer to run it for the user right now rather than just listing it
-5. **Feel oriented, not overwhelmed** — surface only what's relevant to their current position; don't dump the entire catalog
-6. **Get answers to general questions** — when the question doesn't map to a specific skill, use the module's registered documentation to give a grounded answer
-
-## Data Sources
-
-- **Catalog**: `{project-root}/_config/bmad-help.csv` — assembled manifest of all installed module skills
-- **Config**: `config.yaml` and `user-config.yaml` files in `{project-root}/` and its subfolders — resolve `output-location` variables, provide `communication_language` and `project_knowledge`
-- **Artifacts**: Files matching `outputs` patterns at resolved `output-location` paths reveal which steps are possibly completed; their content may also provide grounding context for recommendations
-- **Project knowledge**: If `project_knowledge` resolves to an existing path, read it for grounding context. Never fabricate project-specific details.
-- **Module docs**: Rows with `_meta` in the `skill` column carry a URL or path in `output-location` pointing to the module's documentation (e.g., llms.txt). Fetch and use these to answer general questions about that module.
-
-## CSV Interpretation
-
-The catalog uses this format:
-
-```
-module,skill,display-name,menu-code,description,action,args,phase,preceded-by,followed-by,required,output-location,outputs
-```
-
-**Phases** determine the high-level flow:
-- `anytime` — available regardless of workflow state
-- Numbered phases (`1-analysis`, `2-planning`, etc.) flow in order; naming varies by module
-
-**Sequencing** determines recommended ordering within and across phases (these are soft suggestions, not hard gates — see `required` for gating):
-- `preceded-by` — skills that should ideally complete before this one
-- `followed-by` — skills that should ideally run after this one
-- Format: `skill-name` for single-action skills, `skill-name:action` for multi-action skills
-
-**Required gates**:
-- `required=true` items must complete before the user can meaningfully proceed to later phases
-- A phase with no required items is entirely optional — recommend it but be clear about what's actually required next
-
-**Completion detection**:
-- Search resolved output paths for `outputs` patterns
-- Fuzzy-match found files to catalog rows
-- User may also state completion explicitly, or it may be evident from the current conversation
-
-**Descriptions carry routing context** — some contain cycle info and alternate paths (e.g., "back to DS if fixes needed"). Read them as navigation hints, not just display text.
-
-## Response Format
-
-For each recommended item, present:
-- `[menu-code]` **Display name** — e.g., "[PR] PRD"
-- Skill name in backticks — e.g., `bmad-prd`
-- For multi-action skills: action invocation context — e.g., "tech-writer lets create a mermaid diagram!"
-- Description if present in CSV; otherwise your existing knowledge of the skill suffices
-- Args if available
-
-**Ordering**: Show optional items first, then the next required item. Make it clear which is which.
-
-## Constraints
-
-- Present all output in `{communication_language}`
-- Recommend running each skill in a **fresh context window**
-- Match the user's tone — conversational when they're casual, structured when they want specifics
-- If the active module is ambiguous, retrieve all meta rows remote sources to find relevant info also to help answer their question
+---
+name: bmad-help
+description: 'Analyzes current state and user query to answer BMad questions or recommend the next skill(s) to use. Use when user asks for help, bmad help, what to do next, or what to start with in BMad.'
+---
+
+# BMad Help
+
+## Purpose
+
+Help the user understand where they are in their BMad workflow and what to do next, and also answer broader questions when asked that could be augmented with remote sources such as module documentation sources.
+
+## Desired Outcomes
+
+When this skill completes, the user should:
+
+1. **Know where they are** — which module and phase they're in, what's already been completed
+2. **Know what to do next** — the next recommended and/or required step, with clear reasoning
+3. **Know how to invoke it** — skill name, menu code, action context, and any args that shortcut the conversation
+4. **Get offered a quick start** — when a single skill is the clear next step, offer to run it for the user right now rather than just listing it
+5. **Feel oriented, not overwhelmed** — surface only what's relevant to their current position; don't dump the entire catalog
+6. **Get answers to general questions** — when the question doesn't map to a specific skill, use the module's registered documentation to give a grounded answer
+
+## Data Sources
+
+- **Catalog**: `{project-root}/_config/bmad-help.csv` — assembled manifest of all installed module skills
+- **Config**: `config.yaml` and `user-config.yaml` files in `{project-root}/` and its subfolders — resolve `output-location` variables, provide `communication_language` and `project_knowledge`
+- **Artifacts**: Files matching `outputs` patterns at resolved `output-location` paths reveal which steps are possibly completed; their content may also provide grounding context for recommendations
+- **Project knowledge**: If `project_knowledge` resolves to an existing path, read it for grounding context. Never fabricate project-specific details.
+- **Module docs**: Rows with `_meta` in the `skill` column carry a URL or path in `output-location` pointing to the module's documentation (e.g., llms.txt). Fetch and use these to answer general questions about that module.
+
+## CSV Interpretation
+
+The catalog uses this format:
+
+```
+module,skill,display-name,menu-code,description,action,args,phase,preceded-by,followed-by,required,output-location,outputs
+```
+
+**Phases** determine the high-level flow:
+- `anytime` — available regardless of workflow state
+- Numbered phases (`1-analysis`, `2-planning`, etc.) flow in order; naming varies by module
+
+**Sequencing** determines recommended ordering within and across phases (these are soft suggestions, not hard gates — see `required` for gating):
+- `preceded-by` — skills that should ideally complete before this one
+- `followed-by` — skills that should ideally run after this one
+- Format: `skill-name` for single-action skills, `skill-name:action` for multi-action skills
+
+**Required gates**:
+- `required=true` items must complete before the user can meaningfully proceed to later phases
+- A phase with no required items is entirely optional — recommend it but be clear about what's actually required next
+
+**Completion detection**:
+- Search resolved output paths for `outputs` patterns
+- Fuzzy-match found files to catalog rows
+- User may also state completion explicitly, or it may be evident from the current conversation
+
+**Descriptions carry routing context** — some contain cycle info and alternate paths (e.g., "back to DS if fixes needed"). Read them as navigation hints, not just display text.
+
+## Response Format
+
+For each recommended item, present:
+- `[menu-code]` **Display name** — e.g., "[PR] PRD"
+- Skill name in backticks — e.g., `bmad-prd`
+- For multi-action skills: action invocation context — e.g., "tech-writer lets create a mermaid diagram!"
+- Description if present in CSV; otherwise your existing knowledge of the skill suffices
+- Args if available
+
+**Ordering**: Show optional items first, then the next required item. Make it clear which is which.
+
+## Constraints
+
+- Present all output in `{communication_language}`
+- Recommend running each skill in a **fresh context window**
+- Match the user's tone — conversational when they're casual, structured when they want specifics
+- If the active module is ambiguous, retrieve all meta rows remote sources to find relevant info also to help answer their question

package/src/bmad-plus/packs/pack-dev-studio/categories/utilities/brainstorming.md

@@ -1,6 +1,6 @@
----
-name: bmad-brainstorming
-description: 'Facilitate interactive brainstorming sessions using diverse creative techniques and ideation methods. Use when the user says help me brainstorm or help me ideate.'
----
-
-Follow the instructions in ./workflow.md.
+---
+name: bmad-brainstorming
+description: 'Facilitate interactive brainstorming sessions using diverse creative techniques and ideation methods. Use when the user says help me brainstorm or help me ideate.'
+---
+
+Follow the instructions in ./workflow.md.

package/src/bmad-plus/packs/pack-dev-studio/categories/utilities/customize.md

@@ -1,111 +1,111 @@
----
-name: bmad-customize
-description: Authors and updates customization overrides for installed BMad skills. Use when the user says 'customize bmad', 'override a skill', 'change agent behavior', or 'customize a workflow'.
----
-
-# BMad Customize
-
-Translate the user's intent into a correctly-placed TOML override file under `{project-root}/custom/` for a customizable agent or workflow skill. Discover, route, author, write, verify.
-
-Scope v1: per-skill `[agent]` overrides (`bmad-agent-<role>.toml` / `.user.toml`) and per-skill `[workflow]` overrides (`bmad-<workflow>.toml` / `.user.toml`). Central config (`{project-root}/custom/config.toml`) is out of scope — point users at the [How to Customize BMad guide](https://docs.bmad-method.org/how-to/customize-bmad/).
-
-When the target's `agent configuration` doesn't expose what the user wants, say so plainly. Don't invent fields.
-
-## Preflight
-
-- No `{project-root}/` → BMad isn't installed. Say so, stop.
-- `{project-root}/scripts/resolve_customization.py` missing → continue, but Step 6 verify falls back to manual merge.
-- Both present → proceed.
-
-## Activation
-
-Load `config.toml` and `config.user.toml` from `{project-root}` for `user_name` (default `BMad`) and `communication_language` (default `English`). Greet. If the user's invocation already names a target skill AND a specific change, jump to Step 3.
-
-## Step 1: Classify intent
-
-- **Directed** — specific skill + specific change → Step 3.
-- **Exploratory** — "what can I customize?" → Step 2.
-- **Audit/iterate** — wants to review or change something already customized → Step 2, lead with skills that have existing overrides; read the existing override in Step 3 before composing.
-- **Cross-cutting** — could live on multiple surfaces → Step 3, choose agent vs workflow explicitly with the user.
-
-## Step 2: Discovery
-
-```
-List all installed BMAD+ agents and skills from your project directory
-```
-
-Use `--extra-root <path>` (repeatable) if the user has skills installed in additional locations.
-
-Group the returned `agents` and `workflows` for the user; for each show name, description, whether `has_team_override` or `has_user_override` is true. Surface any `errors[]`. For audit/iterate intents, lead with already-overridden entries.
-
-Empty list: show `scanned_roots`, ask whether skills live elsewhere (offer `--extra-root`); otherwise stop.
-
-## Step 3: Determine the right surface
-
-Read the target's `agent configuration`. Top-level `[agent]` or `[workflow]` block defines the surface.
-
-If a team or user override already exists, read it first and summarize what's already overridden before composing.
-
-**Cross-cutting intent — walk both surfaces with the user:**
-- Every workflow a given agent runs → agent surface (e.g. `bmad-agent-pm.toml` with `persistent_facts`, `principles`).
-- One workflow only → workflow surface (e.g. `bmad-prd.toml` with `activation_steps_prepend`).
-- Several specific workflows → multiple workflow overrides in sequence, not an agent override.
-
-**Single-surface heuristic:**
-- Workflow-level: template swap, output path, step-specific behavior, or a named scalar already exposed (`*_template`, `on_complete`). Surgical, reliable.
-- Agent-level: persona, communication style, org-wide facts, menu changes, behavior that should apply to every workflow the agent dispatches.
-
-When ambiguous, present both with tradeoff, recommend one, let the user decide.
-
-Intent outside the exposed surface (step logic, ordering, anything not in `agent configuration`): say so; offer `activation_steps_prepend`/`append` or `persistent_facts` as approximations, or recommend `bmad-builder` to create a custom skill.
-
-## Step 4: Compose the override
-
-Translate plain-English into TOML against the target's `agent configuration` fields. If an existing override was read, frame the change as additive.
-
-Merge semantics:
-- **Scalars** (`icon`, `role`, `*_template`, `on_complete`) — override wins.
-- **Append arrays** (`persistent_facts`, `activation_steps_prepend`/`append`, `principles`) — team/user entries append in order.
-- **Keyed arrays of tables** (menu items with `code` or `id`) — matching keys replace, new keys append.
-
-Overrides are sparse: only the fields being changed. Never copy the whole `agent configuration`.
-
-**Template swap** (`*_template` scalar): offer to copy the default template to `{project-root}/custom/{skill-name}-{purpose}-template.md`, point the override at the new path, offer to help edit it.
-
-## Step 5: Team or user placement
-
-Under `{project-root}/custom/`:
-- `{skill-name}.toml` — team, committed. Policies, org conventions, compliance.
-- `{skill-name}.user.toml` — user, gitignored. Personal tone, private facts, shortcuts.
-
-Default by character (policy → team, personal → user), confirm before writing.
-
-## Step 6: Show, confirm, write, verify
-
-1. Show the full TOML. If the file exists, show a diff. Never silently overwrite.
-2. Wait for explicit yes.
-3. Write. Create `{project-root}/custom/` if needed.
-4. Verify:
-   ```
-<!-- Adapted for BMAD+: original script dependency removed -->
-   ```
-   Show the merged output, point out the changed fields.
-
-   **Resolver missing or fails:** read whichever layers exist — `<install-path>/agent configuration` (base), `{project-root}/custom/{skill-name}.toml` (team), `{project-root}/custom/{skill-name}.user.toml` (user) — apply base → team → user with the same merge rules (scalars override, tables deep-merge, `code`/`id`-keyed arrays merge by key, all other arrays append), describe how the changed fields resolve.
-
-   **Verify shows override didn't land** (field unchanged, merge conflict, file not picked up): re-enter Step 4 with the verify output as context. Usually wrong field name, wrong merge mode (scalar vs array), or wrong scope.
-5. Summarize what changed, where the file lives, how to iterate. Remind the user to commit team overrides.
-
-## Complete when
-
-- Override file written (or user explicitly aborted).
-- User has seen resolver output (or manual fallback merge summary).
-- User has acknowledged the summary.
-
-Otherwise the skill isn't done — finish or tell the user they're exiting incomplete.
-
-## When this skill can't help
-
-- **Central config** (`{project-root}/custom/config.toml`) — see the [How to Customize BMad guide](https://docs.bmad-method.org/how-to/customize-bmad/).
-- **Step logic, ordering, behavior not in `agent configuration`** — open a feature request, or use `bmad-builder` to create a custom skill. Offer to help with either.
+---
+name: bmad-customize
+description: Authors and updates customization overrides for installed BMad skills. Use when the user says 'customize bmad', 'override a skill', 'change agent behavior', or 'customize a workflow'.
+---
+
+# BMad Customize
+
+Translate the user's intent into a correctly-placed TOML override file under `{project-root}/custom/` for a customizable agent or workflow skill. Discover, route, author, write, verify.
+
+Scope v1: per-skill `[agent]` overrides (`bmad-agent-<role>.toml` / `.user.toml`) and per-skill `[workflow]` overrides (`bmad-<workflow>.toml` / `.user.toml`). Central config (`{project-root}/custom/config.toml`) is out of scope — point users at the [How to Customize BMad guide](https://docs.bmad-method.org/how-to/customize-bmad/).
+
+When the target's `agent configuration` doesn't expose what the user wants, say so plainly. Don't invent fields.
+
+## Preflight
+
+- No `{project-root}/` → BMad isn't installed. Say so, stop.
+- `{project-root}/scripts/resolve_customization.py` missing → continue, but Step 6 verify falls back to manual merge.
+- Both present → proceed.
+
+## Activation
+
+Load `config.toml` and `config.user.toml` from `{project-root}` for `user_name` (default `BMad`) and `communication_language` (default `English`). Greet. If the user's invocation already names a target skill AND a specific change, jump to Step 3.
+
+## Step 1: Classify intent
+
+- **Directed** — specific skill + specific change → Step 3.
+- **Exploratory** — "what can I customize?" → Step 2.
+- **Audit/iterate** — wants to review or change something already customized → Step 2, lead with skills that have existing overrides; read the existing override in Step 3 before composing.
+- **Cross-cutting** — could live on multiple surfaces → Step 3, choose agent vs workflow explicitly with the user.
+
+## Step 2: Discovery
+
+```
+List all installed BMAD+ agents and skills from your project directory
+```
+
+Use `--extra-root <path>` (repeatable) if the user has skills installed in additional locations.
+
+Group the returned `agents` and `workflows` for the user; for each show name, description, whether `has_team_override` or `has_user_override` is true. Surface any `errors[]`. For audit/iterate intents, lead with already-overridden entries.
+
+Empty list: show `scanned_roots`, ask whether skills live elsewhere (offer `--extra-root`); otherwise stop.
+
+## Step 3: Determine the right surface
+
+Read the target's `agent configuration`. Top-level `[agent]` or `[workflow]` block defines the surface.
+
+If a team or user override already exists, read it first and summarize what's already overridden before composing.
+
+**Cross-cutting intent — walk both surfaces with the user:**
+- Every workflow a given agent runs → agent surface (e.g. `bmad-agent-pm.toml` with `persistent_facts`, `principles`).
+- One workflow only → workflow surface (e.g. `bmad-prd.toml` with `activation_steps_prepend`).
+- Several specific workflows → multiple workflow overrides in sequence, not an agent override.
+
+**Single-surface heuristic:**
+- Workflow-level: template swap, output path, step-specific behavior, or a named scalar already exposed (`*_template`, `on_complete`). Surgical, reliable.
+- Agent-level: persona, communication style, org-wide facts, menu changes, behavior that should apply to every workflow the agent dispatches.
+
+When ambiguous, present both with tradeoff, recommend one, let the user decide.
+
+Intent outside the exposed surface (step logic, ordering, anything not in `agent configuration`): say so; offer `activation_steps_prepend`/`append` or `persistent_facts` as approximations, or recommend `bmad-builder` to create a custom skill.
+
+## Step 4: Compose the override
+
+Translate plain-English into TOML against the target's `agent configuration` fields. If an existing override was read, frame the change as additive.
+
+Merge semantics:
+- **Scalars** (`icon`, `role`, `*_template`, `on_complete`) — override wins.
+- **Append arrays** (`persistent_facts`, `activation_steps_prepend`/`append`, `principles`) — team/user entries append in order.
+- **Keyed arrays of tables** (menu items with `code` or `id`) — matching keys replace, new keys append.
+
+Overrides are sparse: only the fields being changed. Never copy the whole `agent configuration`.
+
+**Template swap** (`*_template` scalar): offer to copy the default template to `{project-root}/custom/{skill-name}-{purpose}-template.md`, point the override at the new path, offer to help edit it.
+
+## Step 5: Team or user placement
+
+Under `{project-root}/custom/`:
+- `{skill-name}.toml` — team, committed. Policies, org conventions, compliance.
+- `{skill-name}.user.toml` — user, gitignored. Personal tone, private facts, shortcuts.
+
+Default by character (policy → team, personal → user), confirm before writing.
+
+## Step 6: Show, confirm, write, verify
+
+1. Show the full TOML. If the file exists, show a diff. Never silently overwrite.
+2. Wait for explicit yes.
+3. Write. Create `{project-root}/custom/` if needed.
+4. Verify:
+   ```
+<!-- Adapted for BMAD+: original script dependency removed -->
+   ```
+   Show the merged output, point out the changed fields.
+
+   **Resolver missing or fails:** read whichever layers exist — `<install-path>/agent configuration` (base), `{project-root}/custom/{skill-name}.toml` (team), `{project-root}/custom/{skill-name}.user.toml` (user) — apply base → team → user with the same merge rules (scalars override, tables deep-merge, `code`/`id`-keyed arrays merge by key, all other arrays append), describe how the changed fields resolve.
+
+   **Verify shows override didn't land** (field unchanged, merge conflict, file not picked up): re-enter Step 4 with the verify output as context. Usually wrong field name, wrong merge mode (scalar vs array), or wrong scope.
+5. Summarize what changed, where the file lives, how to iterate. Remind the user to commit team overrides.
+
+## Complete when
+
+- Override file written (or user explicitly aborted).
+- User has seen resolver output (or manual fallback merge summary).
+- User has acknowledged the summary.
+
+Otherwise the skill isn't done — finish or tell the user they're exiting incomplete.
+
+## When this skill can't help
+
+- **Central config** (`{project-root}/custom/config.toml`) — see the [How to Customize BMad guide](https://docs.bmad-method.org/how-to/customize-bmad/).
+- **Step logic, ordering, behavior not in `agent configuration`** — open a feature request, or use `bmad-builder` to create a custom skill. Offer to help with either.
 - **Skills without a `agent configuration`** — not customizable.