docs: align Claude Code adapter guidance with nested TaskMaestro+Teams model (#1310)

.claude/rules/custom-instructions.md

@@ -157,11 +157,12 @@ Examples:
 
 **When `parse_mode` returns `dispatchReady`, use it directly with the Task tool — no extra calls needed.**
 
-**Strategy Selection (before dispatch):**
-- [ ] Check `availableStrategies` in `parse_mode` response
-- [ ] If `["subagent", "taskmaestro"]` → AskUserQuestion to choose
+**Outer Transport Selection (before dispatch):**
+- [ ] Check `availableStrategies` in `parse_mode` response (outer transport options)
+- [ ] If `["subagent", "taskmaestro"]` → AskUserQuestion to choose outer strategy
 - [ ] If `taskmaestroInstallHint` present and user wants taskmaestro → guide installation
 - [ ] Pass chosen strategy to `dispatch_agents(executionStrategy: ...)`
+- [ ] Teams (inner coordination, experimental) may be used within a session if APIs are available
 
 **Quick Checklist (Auto-Dispatch - Preferred):**
 - [ ] Check `dispatchReady` in `parse_mode` response
@@ -186,8 +187,9 @@ Examples:
 | **EVAL** | 🔒 security, ♿ accessibility, ⚡ performance, 📏 code-quality, 📨 event-architecture, 🔗 integration, 📊 observability, 🔄 migration |
 | **AUTO** | 🏛️ architecture, 🧪 test-strategy, 🔒 security, 📏 code-quality, 📨 event-architecture, 🔗 integration, 📊 observability, 🔄 migration |
 
-> **Note:** All modes support both SubAgent and TaskMaestro execution strategies.
-> The strategy is selected per-invocation via user choice.
+> **Note:** SubAgent and TaskMaestro are **outer transport** strategies (one per invocation, user choice).
+> Teams is an **inner coordination** layer (experimental) that can optionally run within either outer strategy.
+> See the [Execution Model](../../packages/rules/.ai-rules/adapters/claude-code.md#execution-model-outer-transport-vs-inner-coordination) for details.
 
 **📖 Full Guide:** [Parallel Specialist Agents Execution](../../packages/rules/.ai-rules/adapters/claude-code.md#parallel-specialist-agents-execution)
 
@@ -203,8 +205,9 @@ Examples:
 
 If the `parse_mode` response contains `dispatch="auto"` or `dispatchReady` with specialist agents:
 1. **MUST** dispatch every listed specialist — skipping any is a protocol violation
-2. **Teams preferred** over Agent tool for specialist dispatch (use `TeamCreate` + `SendMessage`)
-3. **Report results** via `SendMessage` back to team lead, not just text output
+2. Use the selected **outer transport** (SubAgent or TaskMaestro) to dispatch specialists
+3. **Optionally** use Teams as inner coordination within a session (experimental, requires runtime API availability)
+4. **Report results** via the dispatch mechanism (TaskOutput for SubAgent, SendMessage for Teams)
 
 ### Red Flags (STOP if you think these)
 

packages/rules/.ai-rules/adapters/claude-code.md

@@ -529,67 +529,57 @@ When `parse_mode` returns `dispatch="auto"` or `dispatchReady` with specialist a
 
 **Rule:** Every listed specialist MUST be dispatched. Skipping any specialist is a protocol violation.
 
-#### Teams-Based Specialist Dispatch (Preferred)
+#### Red Flags
 
-Teams are preferred over the Agent tool for specialist dispatch because they enable structured coordination and message-based reporting:
+| Thought | Reality |
+|---------|---------|
+| "I can handle this analysis myself" | Specialists have domain expertise. Dispatch them. |
+| "It's just a small change" | dispatch="auto" means the system determined specialists are needed. |
+| "I'll save time by skipping" | Skipping causes missed issues that cost more later. |
+| "I'll dispatch later" | Dispatch IMMEDIATELY when dispatch="auto" is returned. |
 
-```
-1. TeamCreate({ team_name: "<task>-specialists" })
-2. Spawn specialists as teammates:
-   Agent({ team_name, name: "security-specialist", subagent_type: "general-purpose", prompt: ... })
-   Agent({ team_name, name: "code-quality-specialist", subagent_type: "general-purpose", prompt: ... })
-3. Create and assign tasks:
-   TaskCreate({ subject: "Security review of auth module" })
-   TaskUpdate({ taskId, owner: "security-specialist" })
-4. Specialists work autonomously, report via SendMessage:
-   SendMessage({ to: "team-lead", message: "## Security Findings\n- ...", summary: "Security review done" })
-5. Team lead collects all findings
-6. Shutdown: SendMessage({ to: "security-specialist", message: { type: "shutdown_request" } })
-```
+### Execution Model: Outer Transport vs Inner Coordination
 
-#### SendMessage-Based Reporting
+CodingBuddy uses a **nested execution model** with two distinct layers:
 
-Specialists report findings through `SendMessage` to the team lead. This enables:
-- Structured collection of all specialist outputs
-- Consolidated summary for the user
-- Clear audit trail of what each specialist found
+| Layer | Role | Tool | Scope |
+|-------|------|------|-------|
+| **Outer transport** | Parallel task execution across isolated environments | **TaskMaestro** (tmux + git worktree) or **SubAgent** (background agents) | One pane/agent per issue or task |
+| **Inner coordination** | Specialist collaboration within a single session | **Teams** (experimental) | Multiple specialists within one pane/session |
 
-**Report format:**
-```markdown
-## [Specialist Name] Findings
+> **Key distinction:** TaskMaestro and SubAgent are alternatives for the *outer* layer. Teams is an *inner* layer that can optionally run inside either outer strategy.
 
-### Critical
-- [finding]
+#### Nested Execution Examples
 
-### High
-- [finding]
+**Example 1: TaskMaestro (outer) + Teams (inner)**
 
-### Medium
-- [finding]
-
-### Recommendations
-- [recommendation]
+```
+TaskMaestro session (outer)
+├── Pane 1: Issue #101 (auth feature)
+│   └── Teams session (inner, optional)
+│       ├── security-specialist → reviews auth impl
+│       └── test-strategy-specialist → validates test coverage
+├── Pane 2: Issue #102 (dashboard UI)
+│   └── Single agent (no inner Teams needed)
+└── Pane 3: Issue #103 (API refactor)
+    └── Teams session (inner, optional)
+        ├── architecture-specialist → validates API design
+        └── performance-specialist → checks query efficiency
 ```
 
-#### Fallback: Agent Tool
-
-If Teams-based dispatch fails, fall back to the Agent tool:
-- Use `run_in_background: true` for each specialist
-- Collect results via `TaskOutput`
-- Document the fallback reason in your response
-
-#### Red Flags
+**Example 2: SubAgent (outer) without inner Teams**
 
-| Thought | Reality |
-|---------|---------|
-| "I can handle this analysis myself" | Specialists have domain expertise. Dispatch them. |
-| "It's just a small change" | dispatch="auto" means the system determined specialists are needed. |
-| "I'll save time by skipping" | Skipping causes missed issues that cost more later. |
-| "I'll dispatch later" | Dispatch IMMEDIATELY when dispatch="auto" is returned. |
+```
+SubAgent dispatch (outer)
+├── Agent 1: security-specialist (run_in_background)
+├── Agent 2: accessibility-specialist (run_in_background)
+└── Agent 3: performance-specialist (run_in_background)
+→ Collect results via TaskOutput
+```
 
 ### Execution Strategy Selection (MANDATORY)
 
-When `parse_mode` returns `availableStrategies`:
+When `parse_mode` returns `availableStrategies`, select the **outer transport** strategy:
 
 1. **Check `availableStrategies`** in the response
 2. **If both strategies available** (`["subagent", "taskmaestro"]`), ask user with AskUserQuestion:
@@ -600,8 +590,8 @@ When `parse_mode` returns `availableStrategies`:
    - Yes → invoke `/taskmaestro` skill to guide installation, then re-check
    - No → proceed with subagent
 4. **Call `dispatch_agents`** with chosen `executionStrategy` parameter:
-   - `dispatch_agents({ mode, specialists, executionStrategy: "subagent" })` — existing Agent tool flow
-   - `dispatch_agents({ mode, specialists, executionStrategy: "taskmaestro" })` — returns tmux assignments
+   - `dispatch_agents({ mode, specialists, executionStrategy: "subagent" })` — Agent tool flow
+   - `dispatch_agents({ mode, specialists, executionStrategy: "taskmaestro" })` — tmux pane assignments
 5. **Execute** based on strategy:
    - **subagent**: Use `dispatchParams` with Agent tool (`run_in_background: true`)
    - **taskmaestro**: Follow `executionHint` — start panes, assign prompts, monitor, collect results
@@ -626,6 +616,71 @@ When `executionStrategy: "taskmaestro"` is chosen, `dispatch_agents` returns:
 
 Execute by following the `executionHint` commands sequentially.
 
+### Teams as Inner Coordination Layer (Experimental)
+
+> **Capability gate:** Teams-based coordination is experimental and depends on Claude Code native Teams support being available at runtime. If Teams APIs (`TeamCreate`, `SendMessage`, etc.) are not available, fall back to the SubAgent dispatch pattern.
+
+Teams provide structured specialist coordination **within** a single session or TaskMaestro pane. Use Teams when a task benefits from multiple specialists collaborating and reporting back to a coordinator, rather than running independently.
+
+#### When to Use Inner Teams
+
+- A single task (or pane) needs input from 2+ specialists who should coordinate
+- Specialist findings need to be collected and consolidated by a team lead
+- The task requires structured message-based reporting between specialists
+
+#### When NOT to Use Inner Teams
+
+- Each specialist can run independently with no cross-specialist dependencies
+- You are dispatching specialists across separate issues/tasks (use outer transport instead)
+- Teams APIs are not available at runtime
+
+#### Teams Workflow (within a session)
+
+```
+1. TeamCreate({ team_name: "<task>-specialists" })
+2. Spawn specialists as teammates:
+   Agent({ team_name, name: "security-specialist", subagent_type: "general-purpose", prompt: ... })
+   Agent({ team_name, name: "code-quality-specialist", subagent_type: "general-purpose", prompt: ... })
+3. Create and assign tasks:
+   TaskCreate({ subject: "Security review of auth module" })
+   TaskUpdate({ taskId, owner: "security-specialist" })
+4. Specialists work autonomously, report via SendMessage:
+   SendMessage({ to: "team-lead", message: "## Security Findings\n- ...", summary: "Security review done" })
+5. Team lead collects all findings
+6. Shutdown: SendMessage({ to: "security-specialist", message: { type: "shutdown_request" } })
+```
+
+#### SendMessage-Based Reporting
+
+Specialists report findings through `SendMessage` to the team lead. This enables:
+- Structured collection of all specialist outputs
+- Consolidated summary for the user
+- Clear audit trail of what each specialist found
+
+**Report format:**
+```markdown
+## [Specialist Name] Findings
+
+### Critical
+- [finding]
+
+### High
+- [finding]
+
+### Medium
+- [finding]
+
+### Recommendations
+- [recommendation]
+```
+
+#### Fallback: SubAgent Dispatch
+
+If Teams APIs are unavailable or Teams-based dispatch fails:
+- Use SubAgent with `run_in_background: true` for each specialist
+- Collect results via `TaskOutput`
+- Document the fallback reason in your response
+
 ## PR All-in-One Skill
 
 Unified commit and PR workflow that: