Feature Request: Configurable Interaction Mode & Agent Communication Patterns

[rbcb-dev]

Feature Request: Configurable Interaction Mode & Agent Communication Patterns

Describe your idea

Add first-class support for agent interaction mode (how agents prompt users for input) and orchestrator/sub-agent communication patterns (how master agents delegate to sub-agents) to the BMAD Method installer and compile pipeline.

Relationship between the two features

Both features address the same root problem (how agents communicate), but they differ in scope:

• interaction_mode is universally applicable — every framework has some way for agents to ask users questions (tool call, chat prompt, inline dialog)
• agent_pattern is framework-dependent — not all frameworks support sub-agent spawning. Some have task() (OpenCode), some have different delegation mechanisms, and some have no orchestration capability at all

This means agent_pattern must be framework-aware: for frameworks without sub-agent support, agent_pattern would only generate role-based instructions in agent markdown (e.g., "you are an autonomous specialist") without generating a permission matrix or delegation config. For frameworks with full orchestration support (like OpenCode), it generates both instructions AND host config.

Framework capability	interaction_mode effect	agent_pattern effect
Has structured question tool	Generates tool-specific rules	N/A for this column
Has sub-agent spawning (task())	N/A for this column	Generates instructions + permission matrix + delegation config
Has sub-agents but different tool name	N/A for this column	Generates instructions with framework-specific tool name
No sub-agent support	N/A for this column	Generates role instructions only (no delegation config)
Custom MCP / private tool	Developer-provided module defines tool name + rules	Developer-provided module (if applicable)

This is why agent_pattern could also be a separate issue — it has different framework requirements than interaction_mode.

Why is this needed?

The core problem

Currently, BMAD's compiled agents contain hardcoded "menu-flow" instructions: numbered lists, STOP AND WAIT directives, <menu-handlers> blocks, and /bmad-help promotion steps. These are designed for text-based chat interfaces but break in tool-based environments like OpenCode, where interaction happens via structured tool calls (e.g., question() with typed options, single-choice/multi-choice/bundled questions).

What we had to build as workarounds

We integrated BMAD into a production monorepo (20 agents, strict orchestrator pattern, OpenCode as IDE) and required five separate customization layers to make it work correctly:

Layer	What it does	Lines	Maintenance cost
Shared interaction rules file	MUST/MAY/MUST NOT policy for question() tool, 6 interaction patterns, formatting constraints	~180	Must update on every base template change
Post-compile patch script + tests	Removes legacy menu-flow instructions from compiled agents via regex	~150 + 21 tests	Fragile; breaks when base templates change
Orchestrator wrapper markdown	Routing table, fan-out/fan-in, pre-send output gate, delegation rules	~100	Must stay in sync with compiled master
Global runtime rules file	Question policy, tool preferences, repo safety, sub-agent autonomy	~75	Parallel maintenance alongside BMAD rules
Host config permission matrix	20 agents × permissions (edit/bash/task/MCP) with 3-tier model assignment	~500	Manual update for every new agent

The patch script alone removes 5 categories of legacy instructions:

1. Legacy activation steps (greeting + numbered list menus)
2. STOP AND WAIT + dispatch-by-number patterns
3. <menu-handlers> blocks
4. "Display Menu items" rules
5. /bmad-help promotion steps

All of this is brittle workaround code that exists only because the compile pipeline doesn't support interaction mode selection. Every BMAD update requires re-validating and re-applying all five layers, because compile-agents overwrites the rendered markdown. Teams either avoid updating BMAD or accept the maintenance tax.

Current workflow vs. proposed workflow

Today (manual patching, not update-friendly):

1. npx bmad-method install --action compile-agents    → Overwrites all agent .md files
2. Run custom post-compile patch script               → Regex-removes legacy menu instructions
3. Re-validate all 20 agents                          → Did the patch break anything?
4. Re-check interaction rules file                    → Still compatible with new base templates?
5. BMAD update released? → Go to step 1               → Repeat entire process

Proposed (compile-time configuration, update-friendly):

1. Set interaction_mode: opencode-question in config   → One-time setup
2. npx bmad-method install --action compile-agents     → Correct instructions compiled automatically
3. BMAD update released? → Just re-run compile         → Interaction mode preserved

The difference is clear: one-time configuration vs. perpetual maintenance.

The update problem

Every time a new BMAD version is released and agents are recompiled, all workarounds must be re-applied and re-validated. The compile pipeline overwrites the rendered markdown files, and the post-compile patches may fail silently if the base template structure changed. This means:

• A simple npx bmad-method install --action compile-agents can break a working 20-agent setup
• There is no way to "lock" interaction behavior to survive recompilation
• Teams avoid updating BMAD to avoid re-doing their workarounds
• New framework integrations (see Feature Request: Support for Qoder IDE and Qoder QUEST Integration #1773, Use vscode #askQuestions during HILT feedback loop #1781) will face the same problem and build their own fragile workarounds

Related issues (this is a recurring theme)

Issue	Title	Relevance
#1787	Configurable interaction style	Direct match — proposes interaction_style in core module
#1788	PR for interaction style config	Unmerged implementation attempt
#1794	Update Copilot installer: remove hardcoded tool declarations	Same root cause — hardcoded assumptions break on update
#1781	Use vscode #askQuestions during HILT	Framework-specific interaction tool needed
#1773	Qoder IDE/QUEST integration	New framework needing its own interaction mode
#1702	Each CLI should have its own ask-user tool	Agent stops instead of using framework's question tool
#1616	Faster way to respond to questions	Dialog-based question UX proposal

Multiple teams are hitting the same fundamental problem: BMAD compiles interaction behavior into agent markdown, but different frameworks need different interaction patterns. The current workaround — manually editing rendered markdown — doesn't survive recompilation.

How should it work?

Part 1: interaction_mode — User ↔ Agent communication

Add a new installer config option that selects how agents interact with the user:

# In project's bmad config
interaction_mode: opencode-question # or: text-menu | copilot-ask | cursor-composer | custom

Installer prompt:

? Select interaction mode:
  > opencode-question   - Structured question() tool with typed options
    copilot-ask         - GitHub Copilot askQuestions / confirmations
    cursor-composer     - Cursor Composer inline prompts
    text-menu           - Classic text-based numbered menus (default/legacy)
    custom              - Bring your own interaction rules (custom MCP tools, etc.)

What it controls:

Mode	Compiled behavior
text-menu	Current behavior: numbered lists, STOP AND WAIT, menu-handlers
opencode-question	question() tool calls with MUST/MAY/MUST NOT policy, no menus
copilot-ask	askQuestions / confirmations tool calls
cursor-composer	Inline composer prompts
custom	Developer-provided interaction module with custom tool names and rules

Template engine integration — the engine already supports install_config variables. Interaction instructions become conditional blocks:

{{#if install_config.interaction_mode == "opencode-question"}}

## Interaction Rules

- Use the `question()` tool for all user input
- MUST use for: critical decisions, end-of-session, missing info
- MUST NOT use for: routine steps, known best practices, progress reports
- Free-text is always available (framework adds it automatically)
- NEVER add "Other" or catch-all options
  {{/if}}

{{#if install_config.interaction_mode == "text-menu"}}

## Interaction Rules

- Present numbered menus for user choices
- Wait for user selection before proceeding
  {{/if}}

{{#if install_config.interaction_mode == "custom"}}

## Interaction Rules

{{include install_config.custom_interaction_module}}
{{/if}}

This eliminates post-compile patching and separate interaction rule files entirely.

Detailed behavior per mode:

opencode-question — what the agent does

In opencode-question mode, the agent uses OpenCode's question() tool — a structured UI widget that presents typed options (single-choice, multi-choice, or bundled multi-question). The user clicks an option or types a free-text answer. This replaces all numbered lists, STOP AND WAIT directives, and text-based menus.

Example — agent needs user input on feature scope:

// Agent calls:
question({
  questions: [{
    header: "Feature Scope",
    question: "Should the login page include social OAuth providers?",
    options: [
      { label: "Yes, all major providers (Recommended)", description: "Google, GitHub, Microsoft" },
      { label: "Google only", description: "Simplest integration" },
      { label: "No OAuth", description: "Email/password only" }
    ]
  }]
})

The user sees a clean dropdown/radio UI. Free-text ("Type your own answer") is always added automatically by OpenCode — the agent must never add an "Other" option.

When the agent MUST use question():

• End of every session (mandatory next-step prompt)
• Fundamental direction decisions (architecture, scope, trade-offs)
• Missing critical information that blocks progress
• Orchestrator routing when the best sub-agent is ambiguous

When the agent MUST NOT use question():

• Routine workflow steps (just do them)
• Known best practices (apply without asking)
• Progress reports (just report)
• Sub-steps within an already-agreed task

copilot-ask — what the agent does

In copilot-ask mode, the agent uses GitHub Copilot's #askQuestions and confirmations tools. These tools present questions in Copilot's native UI without triggering additional premium requests (a key cost concern — see #1781).

Example — agent needs user confirmation:

// Agent calls Copilot's confirmation tool:
askQuestions({
  question: "Should I proceed with the database migration?",
  options: ["Yes, run migration", "No, review changes first"]
})

cursor-composer — what the agent does

In cursor-composer mode, the agent uses Cursor's inline composer prompts. Questions appear directly in the editor context. The agent keeps interactions minimal and context-aware, relying on Cursor's built-in accept/reject UX for confirmations.

text-menu (legacy/default) — what the agent does

In text-menu mode, the agent uses the current behavior: numbered lists in chat, STOP AND WAIT directives, <menu-handlers> blocks, and /bmad-help promotion. This is the default for backward compatibility.

Example — current agent behavior:

Please select an option:
1. Design the architecture
2. Review requirements
3. Start implementation
4. /bmad-help

STOP AND WAIT for user selection.

custom — what the agent does

In custom mode, the developer provides their own interaction module (a YAML file following the same schema as the built-in modules). This supports teams that use custom MCP tools, private interaction frameworks, or IDE plugins for agent-user communication.

Configuration:

# In project's bmad config
interaction_mode: custom
custom_interaction_module: _bmad/modules/interaction-my-team.yaml

Example custom interaction module:

# _bmad/modules/interaction-my-team.yaml
name: my-team-interaction
type: interaction-framework

rules:
  # Custom MCP tool for asking questions
  tool_name: my_team_ask

  must_use:
    - critical_decisions
    - end_of_session
    - missing_critical_info

  may_use:
    - scope_clarification

  must_not_use:
    - routine_steps
    - known_best_practices
    - progress_reports

  formatting:
    language: en
    # Custom formatting rules for the team's tool
    max_questions_per_batch: 3
    recommendation_position: first
    free_text: manual # Team's tool doesn't add free-text automatically

The compiler validates the module's structure against the interaction module schema and injects the rules into compiled agent markdown — exactly the same as the built-in modes, but with team-defined tool names and policies.

When to use custom:

• Your team has a proprietary MCP tool for structured communication
• You're integrating with an IDE/framework not covered by the built-in modes
• You want to customize MUST/MAY/MUST NOT rules beyond what built-in modes offer
• You're prototyping a new interaction pattern before proposing it as a built-in mode

Interaction patterns as reusable modules — each mode can be defined as a BMAD module that the compiler includes based on the config:

# _bmad/modules/interaction-opencode.yaml
#
# This file defines the interaction rules for OpenCode's question() tool.
# It is included in compiled agent markdown when interaction_mode: opencode-question.
# The compiler injects the "rules" section into each agent's instructions.
#
name: opencode-interaction
type: interaction-framework

rules:
  # The name of the tool the agent should call for user input.
  # OpenCode provides "question()" — other frameworks have their own tools.
  tool_name: question

  # MUST use: situations where the agent is REQUIRED to call question()
  # instead of just printing text. These are non-negotiable.
  must_use:
    - critical_decisions # Architecture, scope, trade-off decisions
    - end_of_session # Mandatory: always end with a next-step prompt
    - missing_critical_info # Can't continue without user input
    - orchestrator_routing # Master agent unsure which sub-agent to use

  # MAY use: situations where question() is optional but recommended.
  # The agent can choose to ask or to apply a reasonable default.
  may_use:
    - equal_options # Multiple valid approaches, no clear winner
    - scope_clarification # "Did you mean X or Y?"
    - critical_findings # "I found a security issue — how to proceed?"
    - intermediate_review # Mid-task checkpoint

  # MUST NOT use: situations where the agent should NOT ask.
  # Calling question() here wastes the user's time.
  must_not_use:
    - routine_steps # Just do the work
    - known_best_practices # Apply without asking
    - progress_reports # Just report, don't prompt
    - sub_steps # Steps within an agreed task
    - trivial_formatting # Code style, naming conventions

  # Formatting constraints for question() calls.
  # These ensure consistent, scannable UX across all agents.
  formatting:
    language: configurable # Can be set per project (e.g., "de" for German)
    header_max_chars: 30 # Keep headers scannable
    label_max_words: 5 # Option labels: concise (e.g., "Add OAuth providers")
    max_questions_per_batch: 4 # Don't overwhelm: max 4 questions in one call
    max_options_per_question: 6 # Max 6 options per question
    recommendation_position: first # Put recommended option first, mark "(Recommended)"
    free_text: automatic # Framework adds "Type your own answer" — NEVER add "Other"

Part 2: agent_pattern — Agent ↔ Agent communication

Add orchestrator/sub-agent pattern configuration that controls how the master agent interacts with sub-agents.

Framework dependency note: Not all agent frameworks support sub-agent spawning. OpenCode has task(), GitHub Copilot has agent delegation, but some frameworks have no orchestration capability. The agent_pattern config must be framework-aware:

• Full orchestration support (e.g., OpenCode with task()): generates role instructions + permission matrix + delegation config
• Partial support (e.g., framework with delegation but different tool name): generates instructions with framework-specific tool name
• No orchestration support: generates role-based instructions only (e.g., "you are an autonomous specialist") — no delegation config

agent_pattern: strict-orchestrator # or: flat | delegating | solo

Detailed behavior per pattern (for frameworks with full orchestration support):

Pattern	Master agent behavior	Sub-agent behavior	Permission model
strict-orchestrator	Routes tasks only. Never edits files or runs commands. Uses task() to delegate. Synthesizes results.	Fully autonomous. Completes assigned work independently. Cannot delegate to other agents.	Master: edit=deny, bash=deny, task=allowlist. Sub-agents: edit=allow, bash=allow, task=deny.
delegating	Can delegate via task() AND do light work directly (small edits, quick lookups).	Can be delegated to, but master may also handle simple tasks without delegation.	Master: edit=allow, bash=allow, task=allow. Sub-agents: edit=allow, bash=allow, task=deny.
flat	No master agent. All agents are peers. User interacts directly with any agent.	Each agent works independently. No orchestration layer.	All agents: edit=allow, bash=allow, task=deny.
solo	N/A — single agent handles everything (quick-flow-solo-dev).	N/A — no sub-agents.	Solo agent: edit=allow, bash=allow, task=deny.

strict-orchestrator — concrete example

User says: "Add a login page with Google OAuth"

Master agent (orchestrator):

1. Analyzes request → identifies need for architecture + implementation + testing
2. Delegates to architect: task("Design OAuth flow for login page — define endpoints, token handling, callback URL")
3. Receives architecture design from architect
4. Delegates to dev: task("Implement login page with Google OAuth per this architecture: [design]")
5. Receives implementation from dev
6. Delegates to qa: task("Write tests for the login page OAuth flow: [implementation details]")
7. Synthesizes results → presents summary to user

The master never runs git, npm, or edits files. If asked to "just fix this typo", it delegates to dev.

delegating — concrete example

User says: "Add a login page with Google OAuth"

Master agent:

1. Analyzes request → delegates architecture to architect via task()
2. While waiting, fixes a typo the user mentioned in a comment
3. Receives architecture, delegates implementation to dev
4. Reviews the diff directly (reads files)
5. Delegates testing to qa

The master can do light work alongside delegation — reading files, small edits, running quick commands.

For strict-orchestrator, the compiler would inject these instructions into agent markdown:

• Master agent instructions: "You are an orchestrator. Your ONLY job is to understand the user's intent and delegate to the right specialist agent via task(). You NEVER write code, edit files, or run commands yourself."
• Sub-agent instructions: "You are an autonomous specialist. Complete your assigned work independently. You cannot delegate to other agents — finish the work yourself."
• Permission matrix recommendations: Generated as part of the host config (see Part 3).

Part 3: Host configuration generation

For frameworks that support agent configuration, the installer generates a ready-to-use host config:

? Generate host configuration?
  > opencode.jsonc   - OpenCode agent permissions + MCP config
    .github/copilot  - GitHub Copilot agent config
    skip             - Manual configuration

This produces:

• Agent entries with correct model tiers (expensive for implementation, cheaper for research/creative)
• Permission matrix (edit/bash/task per agent role)
• MCP-specific permissions where applicable

Example: Generated opencode.jsonc (20 agents, strict-orchestrator + opencode-question)

// opencode.jsonc — Generated by BMAD Method installer
// interaction_mode: opencode-question
// agent_pattern: strict-orchestrator
{
  "$schema": "https://opencode.ai/config.json",

  // Default agent (orchestrator)
  "default_agent": "bmad-agent-bmad-master",

  // Global behavior rules (generated from interaction_mode config)
  "instructions": [".opencode/rules/bmad-opencode.md"],

  // MCP servers (project-specific, not generated)
  "mcpServers": {},

  // ─── BMAD Agents ─────────────────────────────────────────────

  "agents": {
    // ── Orchestrator ──────────────────────────────────────────
    "bmad-agent-bmad-master": {
      "model": "openai/gpt-5.3-codex",
      "description": "BMAD Master Orchestrator — routes tasks to specialized sub-agents. Never edits code or runs commands directly.",
      "mode": "primary",
      "instructions": ".opencode/agents/bmad-agent-bmad-master.md",
      "permissions": {
        "read": "allow",
        "edit": "deny",
        "glob": "allow",
        "grep": "allow",
        "bash": "deny",
        "webfetch": "allow",
        "question": "allow",
        "task": {
          // Strict orchestrator: can only delegate to BMAD sub-agents
          "*": "deny",
          "bmad-agent-bmm-analyst": "allow",
          "bmad-agent-bmm-architect": "allow",
          "bmad-agent-bmm-dev": "allow",
          "bmad-agent-bmm-pm": "allow",
          "bmad-agent-bmm-qa": "allow",
          "bmad-agent-bmm-sm": "allow",
          "bmad-agent-bmm-ux-designer": "allow",
          "bmad-agent-bmm-tech-writer": "allow",
          "bmad-agent-bmm-quick-flow-solo-dev": "allow",
          "bmad-agent-bmb-agent-builder": "allow",
          "bmad-agent-bmb-module-builder": "allow",
          "bmad-agent-bmb-workflow-builder": "allow",
          "bmad-agent-cis-brainstorming-coach": "allow",
          "bmad-agent-cis-creative-problem-solver": "allow",
          "bmad-agent-cis-design-thinking-coach": "allow",
          "bmad-agent-cis-innovation-strategist": "allow",
          "bmad-agent-cis-presentation-master": "allow",
          "bmad-agent-cis-storyteller": "allow",
          "bmad-agent-tea-tea": "allow",
        },
      },
      "prompt": "You are the BMAD Master Orchestrator. Your ONLY job is to understand the user's intent and delegate to the right specialist agent via task(). You NEVER write code, edit files, or run commands yourself.\n\nWorkflow:\n1. Analyze the user's request\n2. Select the best specialist agent(s)\n3. Delegate via task() with a concrete, actionable prompt\n4. Synthesize results and present to the user\n5. Use question() for decisions — NEVER plain text questions\n\nFor parallel work: fan-out to multiple agents in one message, then fan-in results.\nFor sequential work: chain agents, passing context from one to the next.",
    },

    // ── Implementation Agents ─────────────────────────────────
    "bmad-agent-bmm-dev": {
      "model": "github-copilot/claude-opus-4.6",
      "description": "Senior Full-Stack Developer — implements features, writes code, runs tests.",
      "mode": "subagent",
      "instructions": ".opencode/agents/bmad-agent-bmm-dev.md",
      "permissions": {
        "read": "allow",
        "edit": "allow",
        "glob": "allow",
        "grep": "allow",
        "bash": "allow",
        "webfetch": "allow",
        "websearch": "deny",
        "question": "allow",
        "task": "deny",
      },
    },
    "bmad-agent-bmm-architect": {
      "model": "github-copilot/claude-opus-4.6",
      "description": "Software Architect — designs systems, reviews architecture, creates technical specs.",
      "mode": "subagent",
      "instructions": ".opencode/agents/bmad-agent-bmm-architect.md",
      "permissions": {
        "read": "allow",
        "edit": "allow",
        "glob": "allow",
        "grep": "allow",
        "bash": "allow",
        "webfetch": "allow",
        "question": "allow",
        "task": "deny",
      },
    },
    "bmad-agent-bmm-qa": {
      "model": "github-copilot/claude-opus-4.6",
      "description": "QA Engineer — writes tests, validates quality, reviews test coverage.",
      "mode": "subagent",
      "instructions": ".opencode/agents/bmad-agent-bmm-qa.md",
      "permissions": {
        "read": "allow",
        "edit": "allow",
        "glob": "allow",
        "grep": "allow",
        "bash": "allow",
        "webfetch": "allow",
        "question": "allow",
        "task": "deny",
      },
    },
    "bmad-agent-bmm-quick-flow-solo-dev": {
      "model": "github-copilot/claude-opus-4.6",
      "description": "Quick Flow Solo Dev — rapid prototyping and small feature implementation.",
      "mode": "subagent",
      "instructions": ".opencode/agents/bmad-agent-bmm-quick-flow-solo-dev.md",
      "permissions": {
        "read": "allow",
        "edit": "allow",
        "glob": "allow",
        "grep": "allow",
        "bash": "allow",
        "webfetch": "allow",
        "question": "allow",
        "task": "deny",
      },
    },

    // ── Research / Advisory Agents (read-only) ────────────────
    "bmad-agent-bmm-analyst": {
      "model": "github-copilot/gpt-5.2-codex",
      "description": "Business Analyst — requirements gathering, user stories, acceptance criteria.",
      "mode": "subagent",
      "instructions": ".opencode/agents/bmad-agent-bmm-analyst.md",
      "permissions": {
        "read": "allow",
        "edit": "deny",
        "glob": "allow",
        "grep": "allow",
        "bash": "deny",
        "webfetch": "allow",
        "question": "allow",
        "task": "deny",
      },
    },
    "bmad-agent-bmm-pm": {
      "model": "github-copilot/gpt-5.2-codex",
      "description": "Product Manager — product strategy, roadmap, prioritization.",
      "mode": "subagent",
      "instructions": ".opencode/agents/bmad-agent-bmm-pm.md",
      "permissions": {
        "read": "allow",
        "edit": "deny",
        "glob": "allow",
        "grep": "allow",
        "bash": "deny",
        "webfetch": "allow",
        "question": "allow",
        "task": "deny",
      },
    },
    "bmad-agent-bmm-sm": {
      "model": "github-copilot/gpt-5.2-codex",
      "description": "Scrum Master — process facilitation, sprint planning, retrospectives.",
      "mode": "subagent",
      "instructions": ".opencode/agents/bmad-agent-bmm-sm.md",
      "permissions": {
        "read": "allow",
        "edit": "deny",
        "glob": "allow",
        "grep": "allow",
        "bash": "deny",
        "webfetch": "deny",
        "question": "allow",
        "task": "deny",
      },
    },
    "bmad-agent-bmm-ux-designer": {
      "model": "github-copilot/gpt-5.2-codex",
      "description": "UX Designer — user experience, wireframes, interaction design.",
      "mode": "subagent",
      "instructions": ".opencode/agents/bmad-agent-bmm-ux-designer.md",
      "permissions": {
        "read": "allow",
        "edit": "deny",
        "glob": "allow",
        "grep": "allow",
        "bash": "deny",
        "webfetch": "allow",
        "question": "allow",
        "task": "deny",
      },
    },

    // ── Writers / Builders ────────────────────────────────────
    "bmad-agent-bmm-tech-writer": {
      "model": "github-copilot/gpt-5.2-codex",
      "description": "Technical Writer — documentation, guides, API docs.",
      "mode": "subagent",
      "instructions": ".opencode/agents/bmad-agent-bmm-tech-writer.md",
      "permissions": {
        "read": "allow",
        "edit": "allow",
        "glob": "allow",
        "grep": "allow",
        "bash": "deny",
        "webfetch": "allow",
        "question": "allow",
        "task": "deny",
      },
    },
    "bmad-agent-bmb-agent-builder": {
      "model": "github-copilot/gpt-5.2-codex",
      "description": "Agent Builder — creates and configures BMAD agents.",
      "mode": "subagent",
      "instructions": ".opencode/agents/bmad-agent-bmb-agent-builder.md",
      "permissions": {
        "read": "allow",
        "edit": "allow",
        "glob": "allow",
        "grep": "allow",
        "bash": "deny",
        "webfetch": "allow",
        "question": "allow",
        "task": "deny",
      },
    },
    "bmad-agent-bmb-module-builder": {
      "model": "github-copilot/gpt-5.2-codex",
      "description": "Module Builder — creates BMAD modules and templates.",
      "mode": "subagent",
      "instructions": ".opencode/agents/bmad-agent-bmb-module-builder.md",
      "permissions": {
        "read": "allow",
        "edit": "allow",
        "glob": "allow",
        "grep": "allow",
        "bash": "deny",
        "webfetch": "allow",
        "question": "allow",
        "task": "deny",
      },
    },
    "bmad-agent-bmb-workflow-builder": {
      "model": "github-copilot/gpt-5.2-codex",
      "description": "Workflow Builder — designs and implements BMAD workflows.",
      "mode": "subagent",
      "instructions": ".opencode/agents/bmad-agent-bmb-workflow-builder.md",
      "permissions": {
        "read": "allow",
        "edit": "allow",
        "glob": "allow",
        "grep": "allow",
        "bash": "deny",
        "webfetch": "allow",
        "question": "allow",
        "task": "deny",
      },
    },

    // ── Creative / CIS Agents (read-only) ─────────────────────
    "bmad-agent-cis-brainstorming-coach": {
      "model": "github-copilot/gpt-5.2-codex",
      "description": "Brainstorming Coach — facilitates ideation sessions.",
      "mode": "subagent",
      "instructions": ".opencode/agents/bmad-agent-cis-brainstorming-coach.md",
      "permissions": {
        "read": "allow",
        "edit": "deny",
        "glob": "allow",
        "grep": "allow",
        "bash": "deny",
        "webfetch": "allow",
        "question": "allow",
        "task": "deny",
      },
    },
    "bmad-agent-cis-creative-problem-solver": {
      "model": "github-copilot/gpt-5.2-codex",
      "description": "Creative Problem Solver — lateral thinking and novel solutions.",
      "mode": "subagent",
      "instructions": ".opencode/agents/bmad-agent-cis-creative-problem-solver.md",
      "permissions": {
        "read": "allow",
        "edit": "deny",
        "glob": "allow",
        "grep": "allow",
        "bash": "deny",
        "webfetch": "allow",
        "question": "allow",
        "task": "deny",
      },
    },
    "bmad-agent-cis-design-thinking-coach": {
      "model": "github-copilot/gpt-5.2-codex",
      "description": "Design Thinking Coach — guides design thinking workshops.",
      "mode": "subagent",
      "instructions": ".opencode/agents/bmad-agent-cis-design-thinking-coach.md",
      "permissions": {
        "read": "allow",
        "edit": "deny",
        "glob": "allow",
        "grep": "allow",
        "bash": "deny",
        "webfetch": "allow",
        "question": "allow",
        "task": "deny",
      },
    },
    "bmad-agent-cis-innovation-strategist": {
      "model": "github-copilot/gpt-5.2-codex",
      "description": "Innovation Strategist — technology trends and innovation roadmaps.",
      "mode": "subagent",
      "instructions": ".opencode/agents/bmad-agent-cis-innovation-strategist.md",
      "permissions": {
        "read": "allow",
        "edit": "deny",
        "glob": "allow",
        "grep": "allow",
        "bash": "deny",
        "webfetch": "allow",
        "question": "allow",
        "task": "deny",
      },
    },
    "bmad-agent-cis-presentation-master": {
      "model": "github-copilot/gpt-5.2-codex",
      "description": "Presentation Master — slide design, storytelling, visual communication.",
      "mode": "subagent",
      "instructions": ".opencode/agents/bmad-agent-cis-presentation-master.md",
      "permissions": {
        "read": "allow",
        "edit": "deny",
        "glob": "allow",
        "grep": "allow",
        "bash": "deny",
        "webfetch": "allow",
        "question": "allow",
        "task": "deny",
      },
    },
    "bmad-agent-cis-storyteller": {
      "model": "github-copilot/gpt-5.2-codex",
      "description": "Storyteller — narrative design, content strategy.",
      "mode": "subagent",
      "instructions": ".opencode/agents/bmad-agent-cis-storyteller.md",
      "permissions": {
        "read": "allow",
        "edit": "deny",
        "glob": "allow",
        "grep": "allow",
        "bash": "deny",
        "webfetch": "allow",
        "question": "allow",
        "task": "deny",
      },
    },

    // ── TEA Agent ─────────────────────────────────────────────
    "bmad-agent-tea-tea": {
      "model": "github-copilot/gpt-5.2-codex",
      "description": "TEA — Technical Excellence Advisor.",
      "mode": "subagent",
      "instructions": ".opencode/agents/bmad-agent-tea-tea.md",
      "permissions": {
        "read": "allow",
        "edit": "deny",
        "glob": "allow",
        "grep": "allow",
        "bash": "deny",
        "webfetch": "allow",
        "question": "allow",
        "task": "deny",
      },
    },
  },
}

Relationship to existing issues

This is NOT a duplicate of #1787 — it's an extension

Issue #1787 and its PR #1788 propose a binary interaction_style toggle (structured vs open). This is a good start, but after building a production 20-agent BMAD integration, we identified several gaps that this proposal addresses:

Dimension	#1787 / PR #1788	This proposal
Granularity	Binary: structured vs open	Per-framework modes with MUST/MAY/MUST NOT policy and 6 interaction patterns
Framework support	Tool names hardcoded per template (40+ files with same rule)	Reusable interaction modules (one YAML per mode, compiled into templates)
DRY principle	Same rule duplicated in 40+ template files (claude-agent.md, opencode-agent.md, gemini-agent.toml, etc.)	Single interaction module per mode, included by compiler
Tool-name mapping	Inconsistent: shared components use AskUserQuestion, but platform templates use question/ask_user	Centralized tool_name in module, compiler resolves per platform
Agent topology	Not addressed	agent_pattern config: strict-orchestrator / delegating / flat / solo
Permission model	Not addressed	Generated permission matrices per agent pattern
Host config output	Not addressed	Generates ready-to-use opencode.jsonc / Copilot config
Formatting rules	None	Header length, label words, option counts, recommendation placement
When to ask / not ask	Not specified	MUST/MAY/MUST NOT policy (critical decisions, end-of-session, routine steps, etc.)

PR #1788 technical observations

PR #1788 (45 files changed, +164/-14) takes a template duplication approach: the same interaction rule is injected into every IDE-specific template file independently. This creates:

• Maintenance burden: Adding a new interaction mode means editing 40+ files
• Inconsistency risk: Shared components (activation-rules.txt, agent-command-header.md) reference AskUserQuestion (Claude-specific), while OpenCode templates reference question — if a shared component is included in an OpenCode build, the tool name is wrong
• Default mismatch: src/core/module.yaml defaults to open, but docs/how-to/install-bmad.md says default is structured
• No tests: PR has no test coverage for the new behavior

This proposal addresses these by:

1. Interaction modules (one YAML per mode) instead of duplicated rules per template
2. Centralized tool-name resolution in the compiler, not in each template
3. Explicit formatting constraints that ensure consistent UX across all agents

How this proposal unifies multiple issues

Issue	Problem	How this proposal addresses it
#1787	Binary interaction_style toggle is too coarse	Per-framework interaction modes with reusable modules + MUST/MAY/MUST NOT policy
#1794	Copilot installer hardcodes tool declarations	Tool names resolved per-framework from centralized interaction module, not hardcoded per template
#1781	Need #askQuestions for HILT in Copilot	copilot-ask interaction mode generates correct tool references at compile time
#1702	CLI stops instead of using framework's ask tool	Interaction module defines tool_name per mode — agent instructions always reference the correct tool
#1773	Qoder IDE integration needs its own patterns	New interaction module (qoder-dialog or similar) can be added without touching existing templates
#1616	Dialog-based Q&A UX	Interaction modules support different question UX patterns per framework

Additional context

Scope justification

This issue proposes both interaction mode (user ↔ agent) and orchestrator pattern (agent ↔ agent) because they are two sides of the same coin: how agents communicate. The interaction mode determines how an agent talks to the user; the orchestrator pattern determines how the master agent delegates to sub-agents and what permissions each role has. Both are configured at install time, both affect compiled markdown, and both use the same template engine conditionals.

That said, the orchestrator pattern could be a separate issue if the scope feels too large. The natural split would be:

• Issue A (this issue): interaction_mode — template conditionals for user ↔ agent communication
• Issue B (separate): agent_pattern — orchestrator/sub-agent routing patterns + permission matrix generation

Implementation phases

Phase	Scope	BMAD files affected
1. Interaction mode	interaction_mode config + template conditionals	src/core/module.yaml, tools/cli/lib/agent/template-engine.js, tools/cli/lib/agent/compiler.js
2. Orchestrator pattern	agent_pattern config + role-based instructions	tools/cli/lib/agent/installer.js, tools/cli/commands/install.js
3. Config generation	Host config output (opencode.jsonc, etc.)	New: tools/cli/lib/config-generators/

Production evidence

We have been running a strict-orchestrator + opencode-question setup (20 agents, 3-tier model assignment, full permission matrix) in a production monorepo for several weeks. Key findings:

• 3-tier model assignment is cost-effective: expensive models (claude-opus) for implementation agents, cheaper models (gpt-5.2-codex) for research/creative
• Strict permission enforcement catches routing errors immediately — orchestrator cannot accidentally edit files
• Task allowlisting on the orchestrator prevents sub-agents from cascade-delegating (a common confusion source)
• MUST/MAY/MUST NOT question policy gives clear guidance without over-constraining agent behavior
• Post-compile patching is the biggest pain point — regex-based removal of legacy instructions is fragile and must be re-validated on every BMAD update

Related BMAD issues

See the comprehensive table in the "Why is this needed?" section above. This proposal unifies the concerns raised in issues #1787, #1794, #1781, #1773, #1702, and #1616 into a single configurable solution at the compile pipeline level.

[coderabbitai]

🔗 Related PRs

#1151 - feat(bmgd): comprehensive BMGD module upgrade [merged]
#1263 - feat(docs): Diataxis restructure + Astro/Starlight migration [merged]
#1341 - fix: web bundler entry point [merged]
#1367 - docs: update test-design workflow to generate two documents for system-level mode [merged]
#1492 - fix(installer): Multiple installer fixes [merged]
#1578 - fix(docs): comprehensive documentation site review fixes [merged]
#1586 - refactor: Complete @clack/prompts Migration & Installer Output Consolidation [merged]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!

[rbcb-dev]

@coderabbitai plan

[coderabbitai]

Caution

CodeRabbit could not initialize plan tracking. Please try again later.

[bmadcode]

@rbcb-dev I like the idea here - will review with the team as this is a lot to consider.