4.0 KiB

Raw Blame History

Platform Adapter: Codex (OpenAI)

Capabilities

Feature	Support
Parallel sub-agents	Yes — parallel by default, up to `agents.max_threads` (default 6)
Nested sub-agents	No — `agents.max_depth` defaults to 1
Inline prompt injection	Yes — via natural language spawning
Pre-defined agent files	Supported — `.codex/agents/*.toml` for persistent definitions
Model selection	Via TOML `model` field per agent definition
Tool access in sub-agents	Inherited from parent + per-agent overrides

Setup: Pre-Defined Agent Files (Recommended)

During Stage 1 (Initialize), generate a TOML file for each BMAD agent in .codex/agents/:

Skip if files already exist and manifest hasn't changed (same agent count and names).

Template — .codex/agents/{agent-name}.toml:

name = "{name}"
description = "{displayName} - {title}. {role}"

developer_instructions = """
You are {displayName} ({title}), a BMAD agent in a collaborative roundtable discussion.

Your Personality:
- Icon: {icon}
- Role: {role}
- Identity: {identity}
- Communication Style: {communicationStyle}
- Principles: {principles}

Instructions:
- Respond as {displayName}. Your genuine expert perspective — not a safe, hedged AI answer.
- Start with: {icon} **{displayName}**:
- Match your documented communication style exactly.
- Scale response length to the substance of your point.
- If you disagree with another agent, say so directly.
- If you have nothing substantial to add, say so in one sentence.
- Respond in {communication_language}.
"""

sandbox_mode = "read-only"

sandbox_mode = "read-only" — party agents think and respond, they don't modify files.

How to Spawn a Party Mode Agent

Option A — Reference pre-defined agents (recommended):

Spawn agent "{name}" with this context:
Discussion so far: {conversation_context_summary}
Depth: {brief | standard | deep}
User's message: {user_message}
Respond in character. Start with {icon} **{displayName}**:

Option B — Natural language spawning (dynamic):

Spawn an agent to respond as {displayName} with this context:
[conversation context summary]
User's message: {user_message}
The agent should respond in character as {displayName}, starting with {icon} **{displayName}**:

Parallel Execution

Codex runs sub-agents in parallel by default. Spawn multiple together:

Spawn these agents in parallel and wait for all results:
1. Agent "{agent_a_name}" — respond to: {user_message} with context: {context}
2. Agent "{agent_b_name}" — respond to: {user_message} with context: {context}

Executes concurrently (up to max_threads) and consolidates results.

Presentation: Always Show Pass 1

CRITICAL: Pass 1 agent responses MUST be presented to the user in full BEFORE any cross-talk. Cross-talk is supplementary — it adds reactions to the thread, it does NOT replace initial responses. The user must see:

Each agent's independent initial take (Pass 1)
Then any cross-talk reactions (Pass 2) as follow-up remarks

Never skip, summarize, or fold Pass 1 into the cross-talk output.

Cross-Talk Pass

Cross-talk is an additional pass — spawn sequentially with previous agents' responses as context:

Spawn agent "{agent_b_name}" with this additional context:
Other agents said this round:
{agent_a_response}

React briefly — agree, challenge, or build on one specific point. 2-3 sentences max.

The cross-talk responses are appended AFTER the Pass 1 responses when presenting to the user.

Constraints

agents.max_threads default 6 — more than enough for 2-3 party agents
agents.max_depth of 1 — party agents cannot delegate further (not needed)
Approval requests from sub-agents surface to user — sandbox_mode = "read-only" minimizes interruptions
Token cost proportional to agents spawned

Cleanup

Generated .codex/agents/*.toml files persist between sessions for reuse. During exit (Stage 3), note this briefly if files were created. Do NOT delete automatically.

4.0 KiB Raw Blame History