feat: add configurable structured interaction directive to agent activation

Adds a new `interaction_style` config option (structured/open) to core module.yaml so users can choose how agents ask questions. When set to "structured" (default), agents present numbered option lists and wait for selection. When "open", agents ask questions naturally. Changes: - src/core/module.yaml: new interaction_style config with single-select - activation-rules.txt: conditional rule based on {interaction_style} - activation-steps.txt: include {interaction_style} in stored variables Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-02-27 22:56:56 +01:00 · 2026-02-27 22:56:56 +01:00 · b7f18ba28b
parent 1677d54f22
commit b7f18ba28b
37 changed files with 68 additions and 3 deletions
--- a/src/core/module.yaml
+++ b/src/core/module.yaml
@ -23,3 +23,13 @@ output_folder:
  prompt: "Where should output files be saved?"
  default: "_bmad-output"
  result: "{project-root}/{value}"
+
+interaction_style:
+  prompt: "How should agents ask you questions?"
+  default: "structured"
+  result: "{value}"
+  single-select:
+    - value: "structured"
+      label: "Structured - Numbered option lists (recommended)"
+    - value: "open"
+      label: "Open - Natural conversational questions"
--- a/src/core/tasks/workflow.xml
+++ b/src/core/tasks/workflow.xml
@ -2,6 +2,7 @@
  <objective>Execute given workflow by loading its configuration, following instructions, and producing output</objective>

  <llm critical="true">
+    <mandate>RULE: When interaction_style is "structured", EVERY question to the user MUST use the native question tool. No exceptions. No inline prompts. When interaction_style is "open", ask questions naturally in conversation.</mandate>
    <mandate>Always read COMPLETE files - NEVER use offset/limit when reading any workflow related files</mandate>
    <mandate>Instructions are MANDATORY - either as file path, steps or embedded list in YAML, XML or markdown</mandate>
    <mandate>Execute ALL steps in instructions IN EXACT ORDER</mandate>
--- a/src/utility/agent-components/activation-rules.txt
+++ b/src/utility/agent-components/activation-rules.txt
@ -1,5 +1,6 @@
  <rules>
    <r>ALWAYS communicate in {communication_language} UNLESS contradicted by communication_style.</r>
+    <r> RULE: When interaction_style is "structured", EVERY question to the user MUST use the native question tool. No exceptions. No inline prompts. When interaction_style is "open", ask questions naturally in conversation.</r>
    <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>
--- a/src/utility/agent-components/activation-steps.txt
+++ b/src/utility/agent-components/activation-steps.txt
@ -1,7 +1,7 @@
    <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}
+        - Store ALL fields as session variables: {user_name}, {communication_language}, {output_folder}, {interaction_style}
        - 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>
--- a/src/utility/agent-components/agent-command-header.md
+++ b/src/utility/agent-components/agent-command-header.md
@ -1 +1,3 @@
 You must fully embody this agent's persona and follow all activation instructions, steps and rules exactly as specified. NEVER break character until given an exit command.
+
+RULE: When interaction_style is "structured", EVERY question to the user MUST call the AskUserQuestion tool. Do NOT write questions as plain text. No exceptions.
--- a/src/utility/agent-components/handler-action.txt
+++ b/src/utility/agent-components/handler-action.txt
@ -1,4 +1,5 @@
  <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
+    RULE: When interaction_style is "structured", ALL questions to the user MUST use the AskUserQuestion tool. No plain text prompts.
  </handler>
--- a/src/utility/agent-components/handler-exec.txt
+++ b/src/utility/agent-components/handler-exec.txt
@ -3,4 +3,5 @@
      1. Read fully and follow the file at that path
      2. Process the complete file and follow all instructions within it
      3. If there is data="some/path/data-foo.md" with the same item, pass that data path to the executed file as context.
+      4. RULE: When interaction_style is "structured", ALL questions to the user MUST use the AskUserQuestion tool. No plain text prompts.
    </handler>
--- a/src/utility/agent-components/handler-multi.txt
+++ b/src/utility/agent-components/handler-multi.txt
@ -10,5 +10,5 @@
            - For workflow="path/to/workflow.yaml": follow the `handler type="workflow"` instructions
            - For action="...": Perform the specified action directly
         5. Support both exact matches and fuzzy matching based on the match attribute
-         6. If no handler matches, prompt user to choose from available options
+         6. If no handler matches, prompt user to choose from available options using the AskUserQuestion tool when interaction_style is "structured"
      </handler>
--- a/src/utility/agent-components/handler-validate-workflow.txt
+++ b/src/utility/agent-components/handler-validate-workflow.txt
@ -3,5 +3,5 @@
        1. You MUST LOAD the file at: {project-root}/_bmad/core/tasks/validate-workflow.xml
        2. READ its entire contents and EXECUTE all instructions in that file
        3. Pass the workflow, and also check the workflow yaml validation property to find and load the validation schema to pass as the checklist
-        4. The workflow should try to identify the file to validate based on checklist context or else you will ask the user to specify
+        4. The workflow should try to identify the file to validate based on checklist context or else ask the user to specify using the AskUserQuestion tool when interaction_style is "structured"
    </handler>
--- a/src/utility/agent-components/handler-workflow.txt
+++ b/src/utility/agent-components/handler-workflow.txt
@ -7,4 +7,5 @@
      4. Follow workflow.xml instructions precisely following all steps
      5. Save outputs after completing EACH workflow step (never batch multiple steps together)
      6. If workflow.yaml path is "todo", inform user the workflow hasn't been implemented yet
+      7. RULE: When interaction_style is "structured", ALL questions to the user MUST use the AskUserQuestion tool. No plain text prompts.
    </handler>
--- a/tools/cli/installers/lib/ide/templates/agent-command-template.md
+++ b/tools/cli/installers/lib/ide/templates/agent-command-template.md
@ -5,6 +5,8 @@ description: '{{description}}'

 You must fully embody this agent's persona and follow all activation instructions exactly as specified. NEVER break character until given an exit command.

+RULE: When interaction_style is "structured", EVERY question to the user MUST use structured options with a numbered list. Do NOT ask open-ended inline questions. No exceptions.
+
 <agent-activation CRITICAL="TRUE">
 1. LOAD the FULL agent file from @_bmad/{{module}}/agents/{{path}}
 2. READ its entire contents - this contains the complete agent persona, menu, and instructions
--- a/tools/cli/installers/lib/ide/templates/combined/antigravity.md
+++ b/tools/cli/installers/lib/ide/templates/combined/antigravity.md
@ -6,3 +6,5 @@ description: '{{description}}'
 Read the entire workflow file at: {project-root}/_bmad/{{workflow_path}}

 Follow all instructions in the workflow file exactly as written.
+
+RULE: When interaction_style is "structured", EVERY question to the user MUST use structured options with a numbered list. No exceptions.
--- a/tools/cli/installers/lib/ide/templates/combined/default-agent.md
+++ b/tools/cli/installers/lib/ide/templates/combined/default-agent.md
@ -5,6 +5,8 @@ description: '{{description}}'

 You must fully embody this agent's persona and follow all activation instructions exactly as specified. NEVER break character until given an exit command.

+RULE: When interaction_style is "structured", EVERY question to the user MUST call the AskUserQuestion tool. Do NOT write questions as plain text. No exceptions.
+
 <agent-activation CRITICAL="TRUE">
 1. LOAD the FULL agent file from {project-root}/_bmad/{{path}}
 2. READ its entire contents - this contains the complete agent persona, menu, and instructions
--- a/tools/cli/installers/lib/ide/templates/combined/default-task.md
+++ b/tools/cli/installers/lib/ide/templates/combined/default-task.md
@ -8,3 +8,5 @@ description: '{{description}}'
 Read the entire task file at: {project-root}/{{bmadFolderName}}/{{path}}

 Follow all instructions in the task file exactly as written.
+
+RULE: When interaction_style is "structured", EVERY question to the user MUST call the AskUserQuestion tool. Do NOT write questions as plain text. No exceptions.
--- a/tools/cli/installers/lib/ide/templates/combined/default-tool.md
+++ b/tools/cli/installers/lib/ide/templates/combined/default-tool.md
@ -8,3 +8,5 @@ description: '{{description}}'
 Read the entire tool file at: {project-root}/{{bmadFolderName}}/{{path}}

 Follow all instructions in the tool file exactly as written.
+
+RULE: When interaction_style is "structured", EVERY question to the user MUST call the AskUserQuestion tool. Do NOT write questions as plain text. No exceptions.
--- a/tools/cli/installers/lib/ide/templates/combined/default-workflow-yaml.md
+++ b/tools/cli/installers/lib/ide/templates/combined/default-workflow-yaml.md
@ -3,6 +3,8 @@ name: '{{name}}'
 description: '{{description}}'
 ---

+RULE: When interaction_style is "structured", EVERY question to the user MUST call the AskUserQuestion tool. Do NOT write questions as plain text. No exceptions.
+
 IT IS CRITICAL THAT YOU FOLLOW THESE STEPS - while staying in character as the current agent persona you may have loaded:

 <steps CRITICAL="TRUE">
--- a/tools/cli/installers/lib/ide/templates/combined/default-workflow.md
+++ b/tools/cli/installers/lib/ide/templates/combined/default-workflow.md
@ -3,4 +3,6 @@ name: '{{name}}'
 description: '{{description}}'
 ---

+RULE: When interaction_style is "structured", EVERY question to the user MUST call the AskUserQuestion tool. Do NOT write questions as plain text. No exceptions.
+
 IT IS CRITICAL THAT YOU FOLLOW THIS COMMAND: LOAD the FULL @{project-root}/{{bmadFolderName}}/{{path}}, READ its entire contents and follow its directions exactly!
--- a/tools/cli/installers/lib/ide/templates/combined/gemini-agent.toml
+++ b/tools/cli/installers/lib/ide/templates/combined/gemini-agent.toml
@ -7,6 +7,8 @@ PRE-FLIGHT CHECKLIST:
 2.  [ ] IMMEDIATE ACTION: Read and internalize the full agent definition at {project-root}/{{bmadFolderName}}/{{path}}.
 3.  [ ] CONFIRM: The user's name from config is {user_name}.

+RULE: When interaction_style is "structured", EVERY question to the user MUST use structured options with a numbered list. No exceptions.
+
 Only after all checks are complete, greet the user by name and display the menu.
 Acknowledge this checklist is complete in your first response.

--- a/tools/cli/installers/lib/ide/templates/combined/gemini-task.toml
+++ b/tools/cli/installers/lib/ide/templates/combined/gemini-task.toml
@ -6,6 +6,7 @@ TASK INSTRUCTIONS:
 1. LOAD the task file from {project-root}/{{bmadFolderName}}/{{path}}
 2. READ its entire contents
 3. FOLLOW every instruction precisely as specified
+4. RULE: When interaction_style is "structured", EVERY question to the user MUST use structured options with a numbered list. No exceptions.

 TASK FILE: {project-root}/{{bmadFolderName}}/{{path}}
 """
--- a/tools/cli/installers/lib/ide/templates/combined/gemini-tool.toml
+++ b/tools/cli/installers/lib/ide/templates/combined/gemini-tool.toml
@ -6,6 +6,7 @@ TOOL INSTRUCTIONS:
 1. LOAD the tool file from {project-root}/{{bmadFolderName}}/{{path}}
 2. READ its entire contents
 3. FOLLOW every instruction precisely as specified
+4. RULE: When interaction_style is "structured", EVERY question to the user MUST use structured options with a numbered list. No exceptions.

 TOOL FILE: {project-root}/{{bmadFolderName}}/{{path}}
 """
--- a/tools/cli/installers/lib/ide/templates/combined/gemini-workflow-yaml.toml
+++ b/tools/cli/installers/lib/ide/templates/combined/gemini-workflow-yaml.toml
@ -11,6 +11,7 @@ CRITICAL: This is a structured YAML workflow. Follow these steps precisely:
   - Dependencies between steps
 3. EXECUTE each step in order
 4. VALIDATE outputs before proceeding to next step
+5. RULE: When interaction_style is "structured", EVERY question to the user MUST use structured options with a numbered list. No exceptions.

 WORKFLOW FILE: {project-root}/{{bmadFolderName}}/{{workflow_path}}
 """
--- a/tools/cli/installers/lib/ide/templates/combined/gemini-workflow.toml
+++ b/tools/cli/installers/lib/ide/templates/combined/gemini-workflow.toml
@ -9,6 +9,7 @@ WORKFLOW INSTRUCTIONS:
 2. READ its entire contents
 3. FOLLOW every step precisely as specified
 4. DO NOT skip or modify any steps
+5. RULE: When interaction_style is "structured", EVERY question to the user MUST use structured options with a numbered list. No exceptions.

 WORKFLOW FILE: {project-root}/{{bmadFolderName}}/{{workflow_path}}
 """
--- a/tools/cli/installers/lib/ide/templates/combined/kiro-agent.md
+++ b/tools/cli/installers/lib/ide/templates/combined/kiro-agent.md
@ -6,6 +6,8 @@ inclusion: manual

 You must fully embody this agent's persona and follow all activation instructions exactly as specified. NEVER break character until given an exit command.

+RULE: When interaction_style is "structured", EVERY question to the user MUST use structured options with a numbered list. Do NOT ask open-ended inline questions. No exceptions.
+
 <agent-activation CRITICAL="TRUE">
 1. LOAD the FULL agent file from #[[file:{{bmadFolderName}}/{{path}}]]
 2. READ its entire contents - this contains the complete agent persona, menu, and instructions
--- a/tools/cli/installers/lib/ide/templates/combined/kiro-task.md
+++ b/tools/cli/installers/lib/ide/templates/combined/kiro-task.md
@ -7,3 +7,5 @@ inclusion: manual
 Read the entire task file at: #[[file:{{bmadFolderName}}/{{path}}]]

 Follow all instructions in the task file exactly as written.
+
+RULE: When interaction_style is "structured", EVERY question to the user MUST use structured options with a numbered list. No exceptions.
--- a/tools/cli/installers/lib/ide/templates/combined/kiro-tool.md
+++ b/tools/cli/installers/lib/ide/templates/combined/kiro-tool.md
@ -7,3 +7,5 @@ inclusion: manual
 Read the entire tool file at: #[[file:{{bmadFolderName}}/{{path}}]]

 Follow all instructions in the tool file exactly as written.
+
+RULE: When interaction_style is "structured", EVERY question to the user MUST use structured options with a numbered list. No exceptions.
--- a/tools/cli/installers/lib/ide/templates/combined/kiro-workflow-yaml.md
+++ b/tools/cli/installers/lib/ide/templates/combined/kiro-workflow-yaml.md
@ -4,6 +4,8 @@ inclusion: manual

 # {{name}}

+RULE: When interaction_style is "structured", EVERY question to the user MUST use structured options with a numbered list. Do NOT ask open-ended inline questions. No exceptions.
+
 IT IS CRITICAL THAT YOU FOLLOW THESE STEPS - while staying in character as the current agent persona you may have loaded:

 <steps CRITICAL="TRUE">
--- a/tools/cli/installers/lib/ide/templates/combined/kiro-workflow.md
+++ b/tools/cli/installers/lib/ide/templates/combined/kiro-workflow.md
@ -4,4 +4,6 @@ inclusion: manual

 # {{name}}

+RULE: When interaction_style is "structured", EVERY question to the user MUST use structured options with a numbered list. Do NOT ask open-ended inline questions. No exceptions.
+
 IT IS CRITICAL THAT YOU FOLLOW THIS COMMAND: LOAD the FULL #[[file:{{bmadFolderName}}/{{path}}]], READ its entire contents and follow its directions exactly!
--- a/tools/cli/installers/lib/ide/templates/combined/opencode-agent.md
+++ b/tools/cli/installers/lib/ide/templates/combined/opencode-agent.md
@ -5,6 +5,8 @@ description: '{{description}}'

 You must fully embody this agent's persona and follow all activation instructions exactly as specified. NEVER break character until given an exit command.

+RULE: When interaction_style is "structured", EVERY question to the user MUST use structured options with a numbered list. Do NOT ask open-ended inline questions. No exceptions.
+
 <agent-activation CRITICAL="TRUE">
 1. LOAD the FULL agent file from {project-root}/{{bmadFolderName}}/{{path}}
 2. READ its entire contents - this contains the complete agent persona, menu, and instructions
--- a/tools/cli/installers/lib/ide/templates/combined/opencode-task.md
+++ b/tools/cli/installers/lib/ide/templates/combined/opencode-task.md
@ -10,4 +10,6 @@ TASK INSTRUCTIONS:
 2. READ its entire contents
 3. FOLLOW every instruction precisely as specified

+RULE: When interaction_style is "structured", EVERY question to the user MUST use structured options with a numbered list. No exceptions.
+
 TASK FILE: {project-root}/{{bmadFolderName}}/{{path}}
--- a/tools/cli/installers/lib/ide/templates/combined/opencode-tool.md
+++ b/tools/cli/installers/lib/ide/templates/combined/opencode-tool.md
@ -10,4 +10,6 @@ TOOL INSTRUCTIONS:
 2. READ its entire contents
 3. FOLLOW every instruction precisely as specified

+RULE: When interaction_style is "structured", EVERY question to the user MUST use structured options with a numbered list. No exceptions.
+
 TOOL FILE: {project-root}/{{bmadFolderName}}/{{path}}
--- a/tools/cli/installers/lib/ide/templates/combined/opencode-workflow-yaml.md
+++ b/tools/cli/installers/lib/ide/templates/combined/opencode-workflow-yaml.md
@ -12,5 +12,6 @@ WORKFLOW INSTRUCTIONS:
 2. READ its entire contents
 3. FOLLOW every step precisely as specified
 4. DO NOT skip or modify any steps
+5. RULE: When interaction_style is "structured", EVERY question to the user MUST use structured options with a numbered list. No exceptions.

 WORKFLOW FILE: {project-root}/{{bmadFolderName}}/{{path}}
--- a/tools/cli/installers/lib/ide/templates/combined/opencode-workflow.md
+++ b/tools/cli/installers/lib/ide/templates/combined/opencode-workflow.md
@ -12,5 +12,6 @@ WORKFLOW INSTRUCTIONS:
 2. READ its entire contents
 3. FOLLOW every step precisely as specified
 4. DO NOT skip or modify any steps
+5. RULE: When interaction_style is "structured", EVERY question to the user MUST use structured options with a numbered list. No exceptions.

 WORKFLOW FILE: {project-root}/{{bmadFolderName}}/{{path}}
--- a/tools/cli/installers/lib/ide/templates/combined/rovodev.md
+++ b/tools/cli/installers/lib/ide/templates/combined/rovodev.md
@ -7,3 +7,5 @@
 Read the entire workflow file at: {project-root}/_bmad/{{workflow_path}}

 Follow all instructions in the workflow file exactly as written.
+
+RULE: When interaction_style is "structured", EVERY question to the user MUST use structured options with a numbered list. No exceptions.
--- a/tools/cli/installers/lib/ide/templates/combined/trae.md
+++ b/tools/cli/installers/lib/ide/templates/combined/trae.md
@ -7,3 +7,5 @@
 Read the entire workflow file at: {project-root}/_bmad/{{workflow_path}}

 Follow all instructions in the workflow file exactly as written.
+
+RULE: When interaction_style is "structured", EVERY question to the user MUST use structured options with a numbered list. No exceptions.
--- a/tools/cli/installers/lib/ide/templates/combined/windsurf-workflow.md
+++ b/tools/cli/installers/lib/ide/templates/combined/windsurf-workflow.md
@ -8,3 +8,5 @@ auto_execution_mode: "iterate"
 Read the entire workflow file at {project-root}/_bmad/{{workflow_path}}

 Follow all instructions in the workflow file exactly as written.
+
+RULE: When interaction_style is "structured", EVERY question to the user MUST use structured options with a numbered list. No exceptions.
--- a/tools/cli/installers/lib/ide/templates/workflow-command-template.md
+++ b/tools/cli/installers/lib/ide/templates/workflow-command-template.md
@ -2,6 +2,8 @@
 description: '{{description}}'
 ---

+RULE: When interaction_style is "structured", EVERY question to the user MUST use structured options with a numbered list. Do NOT ask open-ended inline questions. No exceptions.
+
 IT IS CRITICAL THAT YOU FOLLOW THESE STEPS - while staying in character as the current agent persona you may have loaded:

 <steps CRITICAL="TRUE">
--- a/tools/cli/installers/lib/ide/templates/workflow-commander.md
+++ b/tools/cli/installers/lib/ide/templates/workflow-commander.md
@ -2,4 +2,6 @@
 description: '{{description}}'
 ---

+RULE: When interaction_style is "structured", EVERY question to the user MUST use structured options with a numbered list. Do NOT ask open-ended inline questions. No exceptions.
+
 IT IS CRITICAL THAT YOU FOLLOW THIS COMMAND: LOAD the FULL @{{workflow_path}}, READ its entire contents and follow its directions exactly!