fix: restore deleted agent-component fragments that break CIS compilation#2060
fix: restore deleted agent-component fragments that break CIS compilation#2060Sallvainian wants to merge 1 commit intobmad-code-org:mainfrom
Conversation
…tion PR bmad-code-org#2050 deleted src/utility/agent-components/ during the phase-based refactor, but tools/cli/lib/activation-builder.js still references these fragment files via loadFragment(). This causes agent compilation to fail with "Fragment not found: activation-steps.txt" for any agent that uses the ActivationBuilder pipeline. Restores all 10 fragment files from their pre-deletion state. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
🤖 Augment PR SummarySummary: Restores the previously deleted Changes:
Technical Notes: This addresses agent compilation failures like 🤖 Was this summary useful? React with 👍 or 👎 |
![augmentcode[bot]](https://avatars.githubusercontent.com/in/1027498?s=60&v=4){kind=small}
| @@ -0,0 +1,6 @@ | |||
| <menu-handlers> | |||
| <extract>{DYNAMIC_EXTRACT_LIST}</extract> | |||
There was a problem hiding this comment.
ActivationBuilder.buildActivation() removes the extract line via an exact string match ('<extract>{DYNAMIC_EXTRACT_LIST}</extract>\n'), but this fragment has leading indentation before <extract>, so the line likely won’t be removed and will leak into the generated agent XML.
Severity: medium
🤖 Was this useful? React with 👍 or 👎, or 🚀 if it prevented an incident/outage.
| <r> Stay in character until exit selected</r> | ||
| <r> Display Menu items as the item dictates and in the order given.</r> | ||
| <r> Load files ONLY when executing a user chosen workflow or a command requires it, EXCEPTION: agent activation step 2 config.yaml</r> | ||
| </rules> No newline at end of file |
There was a problem hiding this comment.
A few of these restored fragments are missing a trailing newline at EOF (Git shows \ No newline at end of file), which can cause awkward concatenation when fragments are joined/indented. Consider adding the newline for consistency/safety.
Severity: low
Other Locations
src/utility/agent-components/handler-action.txt:4src/utility/agent-components/handler-exec.txt:6src/utility/agent-components/handler-multi.txt:13src/utility/agent-components/handler-tmpl.txt:5
🤖 Was this useful? React with 👍 or 👎, or 🚀 if it prevented an incident/outage.
There was a problem hiding this comment.
Pull request overview
Restores the src/utility/agent-components/ fragment templates that are still required by the CLI’s ActivationBuilder pipeline, fixing agent compilation failures (notably for CIS module agents) introduced when the directory was deleted in #2050.
Changes:
- Re-adds activation XML fragment templates (
activation-steps.txt,activation-rules.txt,menu-handlers.txt) used byActivationBuilder. - Re-adds handler fragment templates (
handler-*.txt) that are dynamically included based on agent profiles. - Restores shared agent templates used by installers (
agent-command-header.md,agent.customize.template.yaml).
Reviewed changes
Copilot reviewed 10 out of 10 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
| src/utility/agent-components/menu-handlers.txt | Restores menu-handlers fragment with dynamic extract/handler placeholders. |
| src/utility/agent-components/handler-tmpl.txt | Restores tmpl handler instructions fragment. |
| src/utility/agent-components/handler-multi.txt | Restores multi handler instructions fragment. |
| src/utility/agent-components/handler-exec.txt | Restores exec handler instructions fragment. |
| src/utility/agent-components/handler-data.txt | Restores data handler instructions fragment. |
| src/utility/agent-components/handler-action.txt | Restores action handler instructions fragment. |
| src/utility/agent-components/agent.customize.template.yaml | Restores generic agent customization template used by installers. |
| src/utility/agent-components/agent-command-header.md | Restores shared agent command header used by IDE installers. |
| src/utility/agent-components/activation-steps.txt | Restores activation steps template used by ActivationBuilder. |
| src/utility/agent-components/activation-rules.txt | Restores activation rules fragment used by ActivationBuilder. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
| @@ -0,0 +1,6 @@ | |||
| <menu-handlers> | |||
| <extract>{DYNAMIC_EXTRACT_LIST}</extract> | |||
| <r> Stay in character until exit selected</r> | ||
| <r> Display Menu items as the item dictates and in the order given.</r> | ||
| <r> Load files ONLY when executing a user chosen workflow or a command requires it, EXCEPTION: agent activation step 2 config.yaml</r> |
📝 WalkthroughWalkthroughIntroduces a comprehensive agent activation and menu handling framework by adding nine new configuration files to the agent-components utility directory. These files define rules, activation steps, command headers, customization templates, and handler types to govern agent behavior, communication patterns, and menu-driven interactions. Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~20 minutes Possibly related PRs
Suggested reviewers
🚥 Pre-merge checks | ✅ 3✅ Passed checks (3 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
📝 Coding Plan
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment Tip You can customize the high-level summary generated by CodeRabbit.Configure the |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 4
🧹 Nitpick comments (6)
src/utility/agent-components/activation-rules.txt (2)
6-6: Add trailing newline.The file is missing a trailing newline at end of file.
📝 Proposed fix
<r> Load files ONLY when executing a user chosen workflow or a command requires it, EXCEPTION: agent activation step 2 config.yaml</r> </rules> +🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@src/utility/agent-components/activation-rules.txt` at line 6, The file src/utility/agent-components/activation-rules.txt is missing a trailing newline after the final closing tag (</rules>); open the file and add a single newline character at EOF so the file ends with a newline following </rules>.
5-5: Hardcoded activation step reference.Line 5's EXCEPTION clause references "agent activation step 2 config.yaml" as a hardcoded string. If the activation step numbering changes, this exception rule would break. Consider using a more robust reference mechanism (e.g., a named constant or step identifier).
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@src/utility/agent-components/activation-rules.txt` at line 5, The rule text contains a hardcoded reference "agent activation step 2 config.yaml" which is brittle; replace that literal with a stable identifier (e.g., a named constant or step ID) and update consumers to check against that identifier instead of the numeric string; specifically change the exception clause in activation-rules.txt to reference a constant like AGENT_ACTIVATION_CONFIG_STEP or a descriptive step name (used by functions that parse/validate rules) and ensure functions/methods that read this rule (search/activation logic) compare against the identifier (not "step 2") so renumbering won't break the exception.src/utility/agent-components/agent.customize.template.yaml (1)
9-14: Clarify persona replacement semantics.Line 9's comment states "Replace entire persona (not merged)", which means any persona customization fully replaces the base agent's persona fields rather than merging with them. This could surprise users who expect additive customization.
Consider adding a more prominent warning or example demonstrating this behavior, especially since partial persona updates (e.g., only changing
communication_style) would require the user to repeat all other persona fields.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@src/utility/agent-components/agent.customize.template.yaml` around lines 9 - 14, Clarify that the persona block is a full replacement (not merged) by updating the template comment and README: explicitly state that setting persona replaces all existing persona fields and that partial updates require copying all fields; reference the persona block and fields role, identity, communication_style, principles and add a short example showing a full-replacement use case and a prominent warning (e.g., "WARNING: this replaces the base persona entirely") so users don't mistakenly expect additive updates.src/utility/agent-components/handler-exec.txt (1)
6-6: Add trailing newline.The file is missing a trailing newline at end of file.
📝 Proposed fix
3. If there is data="some/path/data-foo.md" with the same item, pass that data path to the executed file as context. </handler> +🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@src/utility/agent-components/handler-exec.txt` at line 6, The file ends with the closing XML tag "</handler>" but lacks a trailing newline; open src/utility/agent-components/handler-exec.txt and add a single newline character after the "</handler>" line (ensure the file ends with a newline) so the file conforms to POSIX text file conventions.src/utility/agent-components/handler-multi.txt (1)
12-12: Consider specifying the no-match prompt format.The instruction "prompt user to choose from available options" doesn't specify what to display (e.g., list of match patterns, example inputs, or menu item text). Adding guidance would ensure consistent user experience across implementations.
💡 Example clarification
- 6. If no handler matches, prompt user to choose from available options + 6. If no handler matches, list each nested handler's 'match' value and prompt user to choose🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@src/utility/agent-components/handler-multi.txt` at line 12, Update the "If no handler matches, prompt user to choose from available options" behavior by implementing a standardized no-match prompt template (e.g., a function makeNoMatchPrompt or constant noMatchPromptTemplate) that displays: a brief header ("No handler matched your input"), a numbered list of available handlers with their display names and match patterns/examples, a short example input for each, and footer actions ("Select number to choose, or type 'cancel'"). Use this template wherever the handler-multi flow decides on no-match handling so all implementations show the same structured menu and example inputs.src/utility/agent-components/activation-steps.txt (1)
5-5: Specify error message content for missing config.The instruction "STOP and report error to user" doesn't specify what information to include in the error. Consider adding guidance to show the expected config path and remediation steps (e.g., "Config file not found: {project-root}/_bmad/{{module}}/config.yaml. Ensure the module is properly installed.").
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@src/utility/agent-components/activation-steps.txt` at line 5, Update the "VERIFY: If config not loaded, STOP and report error to user" step to emit a clear, actionable error string that includes the expected config path, module name, and remediation steps; e.g., reference the config lookup used by the activation logic (the "config" loader that checks {project-root}/_bmad/{{module}}/config.yaml), include the missing path, suggest "Ensure the module is installed and config.yaml exists" and list next steps (create config, reinstall module, or run setup command), and surface any underlying error details returned by the loader to aid debugging.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@src/utility/agent-components/activation-steps.txt`:
- Around line 1-14: The repository documentation must be updated to document the
restored internal activation framework implemented by activation-steps.txt and
the agent-components/*.txt fragments: add a concise developer-facing section to
agents.md and commands.md explaining the activation-steps sequence (including
the IMMEDIATE config-load step), the special step tokens (MENU_STEP, HELP_STEP,
HALT_STEP, INPUT_STEP, EXECUTE_STEP), the supported template/placeholder
variables ({{module}}, {user_name}, {communication_language}, {output_folder},
etc.), and the menu-handlers semantics (exec, tmpl, data, action, multi)
including how attributes are extracted and executed; ensure the docs specify
failure behavior (stop/report when config load fails) and how session variables
are stored so developers can customize or extend the activation flow.
In `@src/utility/agent-components/agent.customize.template.yaml`:
- Around line 26-33: Update the customization docs to explicitly explain the
menu auto-injection: state that users should define the YAML "menu" array
without the "*" prefix because the system automatically prepends "*" to all
trigger names, and clarify that auto-injected items named "*menu", "*help",
"*exit", and "*dismiss" are inserted at fixed positions (the "*menu" item is
injected first, while "*help", "*exit", and "*dismiss" are appended last) and
that any custom items in the "menu" list are placed between these auto-injected
entries; add this text to the existing docs section that describes the "menu"
structure and include brief examples and a note that custom items cannot
override the auto-injected ones.
In `@src/utility/agent-components/handler-action.txt`:
- Around line 1-4: Update handler-action.txt's handler type="action" section to
explicitly document validation and fallback behavior: for action="#id" state
that the runtime must look up a prompt by id and, if not found, either log an
error and skip the menu item or use a configurable default prompt (describe the
chosen default behaviour), and for action="text" specify validation/sanitization
rules (max length, character/markup restrictions, HTML/JS escaping or rejection
of dangerous patterns) and whether the runtime should reject, escape, or
truncate invalid input; finally add a short note referencing
activation-rules.txt for canonical validation rules or point to it for rule
reuse and include an "Error / Fallback" subsection describing exact logging and
user-visible behavior.
In `@src/utility/agent-components/handler-multi.txt`:
- Line 6: Clarify that the "Exact Match of character code in brackets []" means
a single-character literal or Unicode code-point enclosed in brackets to force
exact-match matching (not a regex); update the text near the 'match' attribute
to show concrete examples such as: use "[a]" to require the literal character
"a" as an exact shortcut, and use "[\u2713]" (or "[✓]") to match a specific
Unicode character; state that multi-character strings should not be placed in
brackets and that brackets denote exact single-character matching only.
---
Nitpick comments:
In `@src/utility/agent-components/activation-rules.txt`:
- Line 6: The file src/utility/agent-components/activation-rules.txt is missing
a trailing newline after the final closing tag (</rules>); open the file and add
a single newline character at EOF so the file ends with a newline following
</rules>.
- Line 5: The rule text contains a hardcoded reference "agent activation step 2
config.yaml" which is brittle; replace that literal with a stable identifier
(e.g., a named constant or step ID) and update consumers to check against that
identifier instead of the numeric string; specifically change the exception
clause in activation-rules.txt to reference a constant like
AGENT_ACTIVATION_CONFIG_STEP or a descriptive step name (used by functions that
parse/validate rules) and ensure functions/methods that read this rule
(search/activation logic) compare against the identifier (not "step 2") so
renumbering won't break the exception.
In `@src/utility/agent-components/activation-steps.txt`:
- Line 5: Update the "VERIFY: If config not loaded, STOP and report error to
user" step to emit a clear, actionable error string that includes the expected
config path, module name, and remediation steps; e.g., reference the config
lookup used by the activation logic (the "config" loader that checks
{project-root}/_bmad/{{module}}/config.yaml), include the missing path, suggest
"Ensure the module is installed and config.yaml exists" and list next steps
(create config, reinstall module, or run setup command), and surface any
underlying error details returned by the loader to aid debugging.
In `@src/utility/agent-components/agent.customize.template.yaml`:
- Around line 9-14: Clarify that the persona block is a full replacement (not
merged) by updating the template comment and README: explicitly state that
setting persona replaces all existing persona fields and that partial updates
require copying all fields; reference the persona block and fields role,
identity, communication_style, principles and add a short example showing a
full-replacement use case and a prominent warning (e.g., "WARNING: this replaces
the base persona entirely") so users don't mistakenly expect additive updates.
In `@src/utility/agent-components/handler-exec.txt`:
- Line 6: The file ends with the closing XML tag "</handler>" but lacks a
trailing newline; open src/utility/agent-components/handler-exec.txt and add a
single newline character after the "</handler>" line (ensure the file ends with
a newline) so the file conforms to POSIX text file conventions.
In `@src/utility/agent-components/handler-multi.txt`:
- Line 12: Update the "If no handler matches, prompt user to choose from
available options" behavior by implementing a standardized no-match prompt
template (e.g., a function makeNoMatchPrompt or constant noMatchPromptTemplate)
that displays: a brief header ("No handler matched your input"), a numbered list
of available handlers with their display names and match patterns/examples, a
short example input for each, and footer actions ("Select number to choose, or
type 'cancel'"). Use this template wherever the handler-multi flow decides on
no-match handling so all implementations show the same structured menu and
example inputs.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Path: .coderabbit.yaml
Review profile: CHILL
Plan: Pro
Run ID: 12eb5956-c5ab-4713-b7be-f584e01f43cc
📒 Files selected for processing (10)
src/utility/agent-components/activation-rules.txtsrc/utility/agent-components/activation-steps.txtsrc/utility/agent-components/agent-command-header.mdsrc/utility/agent-components/agent.customize.template.yamlsrc/utility/agent-components/handler-action.txtsrc/utility/agent-components/handler-data.txtsrc/utility/agent-components/handler-exec.txtsrc/utility/agent-components/handler-multi.txtsrc/utility/agent-components/handler-tmpl.txtsrc/utility/agent-components/menu-handlers.txt
| <step n="1">Load persona from this current agent file (already in context)</step> | ||
| <step n="2">🚨 IMMEDIATE ACTION REQUIRED - BEFORE ANY OUTPUT: | ||
| - Load and read {project-root}/_bmad/{{module}}/config.yaml NOW | ||
| - Store ALL fields as session variables: {user_name}, {communication_language}, {output_folder} | ||
| - VERIFY: If config not loaded, STOP and report error to user | ||
| - DO NOT PROCEED to step 3 until config is successfully loaded and variables stored | ||
| </step> | ||
| <step n="3">Remember: user's name is {user_name}</step> | ||
| {AGENT_SPECIFIC_STEPS} | ||
| <step n="{MENU_STEP}">Show greeting using {user_name} from config, communicate in {communication_language}, then display numbered list of ALL menu items from menu section</step> | ||
| <step n="{HELP_STEP}">Let {user_name} know they can invoke the `bmad-help` skill at any time to get advice on what to do next, and that they can combine it with what they need help with <example>Invoke the `bmad-help` skill with a question like "where should I start with an idea I have that does XYZ?"</example></step> | ||
| <step n="{HALT_STEP}">STOP and WAIT for user input - do NOT execute menu items automatically - accept number or cmd trigger or fuzzy command match</step> | ||
| <step n="{INPUT_STEP}">On user input: Number → process menu item[n] | Text → case-insensitive substring match | Multiple matches → ask user to clarify | No match → show "Not recognized"</step> | ||
| <step n="{EXECUTE_STEP}">When processing a menu item: Check menu-handlers section below - extract any attributes from the selected menu item (exec, tmpl, data, action, multi) and follow the corresponding handler instructions</step> |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Description: Check docs for references to activation framework
# Search for activation and menu system documentation
rg -n -C 3 'activation.*step|menu.*handler|agent.*template|{{module}}|\{user_name\}' docs/
# Check for any migration notes about the deletion/restoration
rg -n -i 'PR.*2050|deleted.*agent-component|removed.*fragment' docs/Repository: bmad-code-org/BMAD-METHOD
Length of output: 262
🏁 Script executed:
#!/bin/bash
# Description: Check docs for references to activation framework
# Fixed: Use simpler patterns with proper escaping
echo "=== Searching for activation-related documentation ==="
rg -n 'activation' docs/ 2>/dev/null || echo "No 'activation' references found"
echo ""
echo "=== Searching for menu system documentation ==="
rg -n 'menu' docs/ 2>/dev/null || echo "No 'menu' references found"
echo ""
echo "=== Searching for agent-component documentation ==="
rg -n 'agent-component' docs/ 2>/dev/null || echo "No 'agent-component' references found"
echo ""
echo "=== Searching for step documentation ==="
rg -n 'step' docs/ | head -30 2>/dev/null || echo "No 'step' references found"
echo ""
echo "=== Checking for PR 2050 or deletion references ==="
rg -n '2050|deleted|removed' docs/ 2>/dev/null || echo "No PR/deletion references found"
echo ""
echo "=== Checking docs directory structure ==="
find docs/ -name "*.md" -o -name "*.txt" | head -20Repository: bmad-code-org/BMAD-METHOD
Length of output: 6655
Ensure documentation reflects restoration of the internal activation framework.
This file and related agent-components/*.txt fragments implement the core agent activation sequence, but the documentation does not currently cover:
- The activation-steps framework and internal step sequence
- Supported template variables (
{{module}},{user_name},{communication_language}, etc.) - Menu handler types and activation semantics
The existing documentation (e.g., docs/reference/agents.md, docs/reference/commands.md) covers agent menus at a user level, but provides no reference for developers needing to understand or customize the internal activation sequence. Per coding guidelines, source file changes should be reflected in documentation.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@src/utility/agent-components/activation-steps.txt` around lines 1 - 14, The
repository documentation must be updated to document the restored internal
activation framework implemented by activation-steps.txt and the
agent-components/*.txt fragments: add a concise developer-facing section to
agents.md and commands.md explaining the activation-steps sequence (including
the IMMEDIATE config-load step), the special step tokens (MENU_STEP, HELP_STEP,
HALT_STEP, INPUT_STEP, EXECUTE_STEP), the supported template/placeholder
variables ({{module}}, {user_name}, {communication_language}, {output_folder},
etc.), and the menu-handlers semantics (exec, tmpl, data, action, multi)
including how attributes are extracted and executed; ensure the docs specify
failure behavior (stop/report when config load fails) and how session variables
are stored so developers can customize or extend the activation flow.
| # Add custom menu items (appended to base menu) | ||
| # Don't include * prefix or help/exit - auto-injected | ||
| menu: [] | ||
| # Example: | ||
| # menu: | ||
| # - trigger: my-workflow | ||
| # workflow: "{project-root}/custom/my.yaml" | ||
| # description: My custom workflow |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Description: Search for agent customization documentation
# Look for docs covering agent customization and menu behavior
rg -l 'menu.*custom|agent.*custom|auto.*inject' docs/
# Check for references to this template file
rg -l 'agent\.customize\.template\.yaml' docs/Repository: bmad-code-org/BMAD-METHOD
Length of output: 167
🏁 Script executed:
# Read the template file to understand the full context
cat -n "src/utility/agent-components/agent.customize.template.yaml"Repository: bmad-code-org/BMAD-METHOD
Length of output: 1263
🏁 Script executed:
# Check the specific docs files for menu customization content
echo "=== docs/how-to/customize-bmad.md ===" && head -100 "docs/how-to/customize-bmad.md"Repository: bmad-code-org/BMAD-METHOD
Length of output: 3446
🏁 Script executed:
# Search for menu auto-injection logic in the codebase
rg "auto.*inject|help.*exit.*inject" --type yaml --type js src/ -A 3 -B 1 | head -100Repository: bmad-code-org/BMAD-METHOD
Length of output: 493
🏁 Script executed:
# Search for menu construction and * prefix usage
rg "\*" src/ --type yaml -B 2 -A 2 | head -80Repository: bmad-code-org/BMAD-METHOD
Length of output: 486
🏁 Script executed:
# Search for help/exit menu injection logic
rg "help|exit" src/ --type js -B 3 -A 3 | grep -i "menu\|inject" -B 3 -A 3 | head -100Repository: bmad-code-org/BMAD-METHOD
Length of output: 51
🏁 Script executed:
# Look for agent menu merging/construction code
rg "menu" src/ --type js -B 2 -A 2 | head -150Repository: bmad-code-org/BMAD-METHOD
Length of output: 51
🏁 Script executed:
# Search for agent config files with * prefix in menu
rg "^\\s*-\\s*\\*" src/ --type yaml -B 1 -A 1Repository: bmad-code-org/BMAD-METHOD
Length of output: 51
🏁 Script executed:
# Look for default agent menu structure
fd "agent\\.yaml|default.*menu" src/ --type f -x cat -n {} \;Repository: bmad-code-org/BMAD-METHOD
Length of output: 51
🏁 Script executed:
# Search for where help/exit are defined or injected
rg "help|exit" src/ --type yaml -B 2 -A 2 | head -100Repository: bmad-code-org/BMAD-METHOD
Length of output: 2328
🏁 Script executed:
# Search more broadly for menu construction logic outside src/
rg "menu" tools/ --type js --type yaml -B 2 -A 2 | head -150Repository: bmad-code-org/BMAD-METHOD
Length of output: 9588
🏁 Script executed:
# Check for any comments or code about * prefix and menu injection
rg "\\*.*prefix|prefix.*\\*|help.*exit|exit.*help" . --type js --type yaml -B 1 -A 1 | head -100Repository: bmad-code-org/BMAD-METHOD
Length of output: 4853
🏁 Script executed:
# Look for agent.yaml structure to see default menus
fd "agent\\.yaml|agents\\.yaml" . --type f -x cat -n {} \;Repository: bmad-code-org/BMAD-METHOD
Length of output: 51
Expand customization docs to explain menu auto-injection mechanism.
The existing docs at docs/how-to/customize-bmad.md show the menu structure but don't explain what the * prefix signifies, where help/exit are injected, or whether custom items can override auto-injected ones. Add a section clarifying:
- The
*prefix is automatically added to all trigger names; users should omit it - Auto-injected items (
*menu,*help,*exit,*dismiss) are added at specific positions (menu first, help/exit/dismiss last) - Custom menu items are inserted between these auto-injected items
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@src/utility/agent-components/agent.customize.template.yaml` around lines 26 -
33, Update the customization docs to explicitly explain the menu auto-injection:
state that users should define the YAML "menu" array without the "*" prefix
because the system automatically prepends "*" to all trigger names, and clarify
that auto-injected items named "*menu", "*help", "*exit", and "*dismiss" are
inserted at fixed positions (the "*menu" item is injected first, while "*help",
"*exit", and "*dismiss" are appended last) and that any custom items in the
"menu" list are placed between these auto-injected entries; add this text to the
existing docs section that describes the "menu" structure and include brief
examples and a note that custom items cannot override the auto-injected ones.
| <handler type="action"> | ||
| When menu item has: action="#id" → Find prompt with id="id" in current agent XML, follow its content | ||
| When menu item has: action="text" → Follow the text directly as an inline instruction | ||
| </handler> No newline at end of file |
There was a problem hiding this comment.
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
# Description: Examine action handler validation
# Look for action handler implementation
rg -n -A 10 'action.*handler|type.*action' --type=js tools/cli/lib/activation-builder.js
# Check for prompt ID validation or text sanitization
rg -n -P '(validate.*prompt|sanitize.*action|prompt.*id.*not.*found)' --type=js tools/cli/lib/activation-builder.jsRepository: bmad-code-org/BMAD-METHOD
Length of output: 51
🏁 Script executed:
# Find activation-builder.js or similar files
fd -e js -i activation | head -20Repository: bmad-code-org/BMAD-METHOD
Length of output: 104
🏁 Script executed:
# Look for the handler-action.txt file
find . -name "*handler-action*" -o -name "*activation-builder*" | grep -v node_modulesRepository: bmad-code-org/BMAD-METHOD
Length of output: 156
🏁 Script executed:
# Search for where action="#id" or action="text" patterns are used
rg -n 'action.*#id|action="text"' --type=js --type=txt | head -30Repository: bmad-code-org/BMAD-METHOD
Length of output: 363
🏁 Script executed:
# Check the structure of src/utility/agent-components directory
ls -la src/utility/agent-components/ 2>/dev/null || echo "Directory not found, searching for similar paths..."
fd -type d agent-componentsRepository: bmad-code-org/BMAD-METHOD
Length of output: 1060
🏁 Script executed:
cat -n src/utility/agent-components/handler-action.txtRepository: bmad-code-org/BMAD-METHOD
Length of output: 330
🏁 Script executed:
cat -n tools/cli/lib/activation-builder.js | head -100Repository: bmad-code-org/BMAD-METHOD
Length of output: 4305
🏁 Script executed:
# Search for where action="#id" is parsed and how prompt lookup is done
rg -n -A 5 'action.*=.*"#' tools/cli/lib/activation-builder.jsRepository: bmad-code-org/BMAD-METHOD
Length of output: 51
🏁 Script executed:
# Search for prompt ID validation or lookup logic
rg -n 'getElementById|getPrompt|findPrompt|prompt.*id' tools/cli/lib/activation-builder.jsRepository: bmad-code-org/BMAD-METHOD
Length of output: 51
🏁 Script executed:
# Check file size of activation-builder.js
wc -l tools/cli/lib/activation-builder.jsRepository: bmad-code-org/BMAD-METHOD
Length of output: 108
🏁 Script executed:
cat -n tools/cli/lib/activation-builder.js | tail -80Repository: bmad-code-org/BMAD-METHOD
Length of output: 3202
🏁 Script executed:
# Search for where action handlers are executed/processed
rg -n 'action.*=' tools/cli/lib/ --type=js | grep -v node_modules | head -20Repository: bmad-code-org/BMAD-METHOD
Length of output: 1679
🏁 Script executed:
# Look for files that handle menu items or process actions
fd -e js tools/cli/lib/ | xargs rg -l 'action.*handler|process.*handler|execute.*action'Repository: bmad-code-org/BMAD-METHOD
Length of output: 835
🏁 Script executed:
# Check if there are any references to handler-action or prompt ID lookups elsewhere
rg -n 'action.*#|prompt.*id|getElementById' tools/cli/lib/ --type=js | head -30Repository: bmad-code-org/BMAD-METHOD
Length of output: 1493
🏁 Script executed:
# Read the agent.customize.template.yaml to understand the data structure
cat -n src/utility/agent-components/agent.customize.template.yamlRepository: bmad-code-org/BMAD-METHOD
Length of output: 1263
🏁 Script executed:
# Search for where handlers are actually executed (not just loaded)
rg -n 'handler.*action|type.*action' --type=js --type=md | grep -v node_modules | head -40Repository: bmad-code-org/BMAD-METHOD
Length of output: 3649
🏁 Script executed:
# Look for handler processing or execution in agent runtime
fd . tools/ -name '*.js' -type f | xargs rg -l 'handler.*type|executeHandler|processHandler' | head -10Repository: bmad-code-org/BMAD-METHOD
Length of output: 638
🏁 Script executed:
# Check if handler-action.txt is referenced anywhere or if it's just a template
rg -n 'handler-action' --type=js --type=md --type=txtRepository: bmad-code-org/BMAD-METHOD
Length of output: 51
🏁 Script executed:
# Read activation-rules.txt to understand handler execution context
cat -n src/utility/agent-components/activation-rules.txtRepository: bmad-code-org/BMAD-METHOD
Length of output: 498
🏁 Script executed:
# Read activation-steps.txt to see how handlers fit into steps
cat -n src/utility/agent-components/activation-steps.txtRepository: bmad-code-org/BMAD-METHOD
Length of output: 1852
🏁 Script executed:
# Look at what the final generated activation block looks like (if there are examples)
fd -e md -e txt tools/ | xargs rg -l 'handler.*type.*action|<handler' | head -5Repository: bmad-code-org/BMAD-METHOD
Length of output: 647
🏁 Script executed:
# Check if there's any documentation about how handlers work
rg -n 'handler.*validation|validate.*action|sanitize' --type=md --type=txt | head -20Repository: bmad-code-org/BMAD-METHOD
Length of output: 2934
Document validation requirements and fallback behavior for handler-action attributes.
The action handler in handler-action.txt specifies two modes but doesn't define what happens when validation fails:
-
action="#id": If a menu item references a non-existent prompt ID, the handler behavior is undefined. Add documentation specifying the fallback (e.g., error message, skip, use default text). -
action="text": Accepts arbitrary inline instruction text without documented validation or sanitization requirements. Specify whether the agent runtime should validate, escape, or restrict this content to prevent injection.
Add an optional fallback or error-handling section to handler-action.txt, or reference the appropriate validation rules in activation-rules.txt.
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@src/utility/agent-components/handler-action.txt` around lines 1 - 4, Update
handler-action.txt's handler type="action" section to explicitly document
validation and fallback behavior: for action="#id" state that the runtime must
look up a prompt by id and, if not found, either log an error and skip the menu
item or use a configurable default prompt (describe the chosen default
behaviour), and for action="text" specify validation/sanitization rules (max
length, character/markup restrictions, HTML/JS escaping or rejection of
dangerous patterns) and whether the runtime should reject, escape, or truncate
invalid input; finally add a short note referencing activation-rules.txt for
canonical validation rules or point to it for rule reuse and include an "Error /
Fallback" subsection describing exact logging and user-visible behavior.
| 1. Display the multi item text as a single menu option | ||
| 2. Parse all nested handlers within the multi item | ||
| 3. For each nested handler: | ||
| - Use the 'match' attribute for fuzzy matching user input (or Exact Match of character code in brackets []) |
There was a problem hiding this comment.
🛠️ Refactor suggestion | 🟠 Major
Clarify "character code in brackets" syntax.
The phrase "Exact Match of character code in brackets []" is ambiguous. Does this refer to single-character shortcuts like [a] within menu item text, or a different syntax? Providing a concrete example would prevent implementation inconsistencies.
📝 Suggested clarification
- - Use the 'match' attribute for fuzzy matching user input (or Exact Match of character code in brackets [])
+ - Use the 'match' attribute for fuzzy matching user input (or Exact Match if the match attribute contains a single character in brackets like [x])📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
| - Use the 'match' attribute for fuzzy matching user input (or Exact Match of character code in brackets []) | |
| - Use the 'match' attribute for fuzzy matching user input (or Exact Match if the match attribute contains a single character in brackets like [x]) |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@src/utility/agent-components/handler-multi.txt` at line 6, Clarify that the
"Exact Match of character code in brackets []" means a single-character literal
or Unicode code-point enclosed in brackets to force exact-match matching (not a
regex); update the text near the 'match' attribute to show concrete examples
such as: use "[a]" to require the literal character "a" as an exact shortcut,
and use "[\u2713]" (or "[✓]") to match a specific Unicode character; state that
multi-character strings should not be placed in brackets and that brackets
denote exact single-character matching only.
|
I think CIS is working now without this - thank you though @Sallvainian ! |
Summary
src/utility/agent-components/during the phase-based refactor, buttools/cli/lib/activation-builder.jsstill references these fragment files vialoadFragment()Fragment not found: activation-steps.txtfor any agent using the ActivationBuilder pipeline (including 6 CIS module agents)Files restored
activation-rules.txt- XML rules block for agent activationactivation-steps.txt- Sequential activation steps template with placeholdersagent-command-header.md- Agent command header textagent.customize.template.yaml- Agent customization templatehandler-action.txt- Action handler definitionhandler-data.txt- Data handler definitionhandler-exec.txt- Exec handler definitionhandler-multi.txt- Multi handler definitionhandler-tmpl.txt- Template handler definitionmenu-handlers.txt- Menu handlers wrapper templateRoot cause
ActivationBuilder(line 10) resolves fragments viagetSourcePath('utility', 'agent-components')→src/utility/agent-components/. ThebuildActivation()method loadsactivation-steps.txt,menu-handlers.txt,activation-rules.txt, and dynamichandler-*.txtfiles. All were deleted in #2050.Test plan
activation-builder.jsloadFragment calls all resolve🤖 Generated with Claude Code
Co-Authored-By: Claude Opus 4.6 (1M context) noreply@anthropic.com