design gap: support nested TaskMaestro + Claude Teams execution for specialist orchestration

[JeremyDev87]

Background

CodingBuddy currently supports three specialist execution strategies at the MCP layer:

• subagent
• taskmaestro
• teams

However, the current implementation treats these as mutually exclusive alternatives.

The intended product behavior is more powerful:

• Outer layer: TaskMaestro manages tmux-based parallel Claude sessions / panes
• Inner layer: each pane may use Claude native team-style coordination to further delegate specialist work inside that pane

In other words, the desired model is not taskmaestro OR teams.
It is taskmaestro as the outer parallel transport + teams as the inner coordination model.

Problem

The current codebase does not implement that nested model.

Today:

• taskmaestro returns pane assignments and stops there
• teams is a separate dispatch branch
• parse_mode does not expose teams as a normal main-path strategy
• docs describe Teams-preferred behavior that is stronger than the current implementation
• there is no runtime capability check proving that the expected Claude Code Teams primitives are actually available before promising that flow

This creates a mismatch between product intent, docs, and implementation.

Goal

Make nested execution a first-class design:

• TaskMaestro remains the default outer parallel execution strategy
• Teams becomes an optional inner coordination strategy inside each pane when supported
• the contract is explicit in MCP responses
• documentation matches the real implementation and capability gating

Scope

In scope:

• MCP dispatch model and response types
• TaskMaestro assignment payload design
• nested execution strategy selection
• Claude Code adapter documentation
• runtime capability / feature gating for Teams-specific behavior

Out of scope:

• unrelated command namespace migration
• TUI-specific execution features
• replacing TaskMaestro as the default outer execution strategy

Acceptance criteria

This parent issue is complete when all of the following are true:

• TaskMaestro and Teams are modeled as composable layers rather than mutually exclusive top-level choices
• TaskMaestro assignments can carry enough structured data to bootstrap an inner Teams workflow when enabled
• parse_mode / MCP responses can describe the nested execution plan to clients
• Teams-specific behavior is gated behind an explicit capability check or experimental flag
• docs no longer promise Teams behavior beyond what the code can actually support

Sub-issues

• feat(mcp): model TaskMaestro and Teams as composable execution layers #1309 Model TaskMaestro and Teams as composable execution layers
• feat(mcp): extend TaskMaestro pane assignments to bootstrap inner Teams workflows #1313 Extend TaskMaestro pane assignments to bootstrap inner Teams workflows
• feat(mcp): expose nested execution metadata in parse_mode and MCP responses #1312 Expose nested execution metadata in parse_mode and MCP responses
• feat(mcp): add runtime capability detection and experimental gating for Teams coordination #1311 Add runtime capability detection and experimental gating for Teams coordination
• docs: align Claude Code adapter guidance with the real nested TaskMaestro plus Teams model #1310 Align Claude Code adapter guidance with the real nested TaskMaestro plus Teams model

Recommended order

1. feat(mcp): model TaskMaestro and Teams as composable execution layers #1309
2. feat(mcp): extend TaskMaestro pane assignments to bootstrap inner Teams workflows #1313
3. feat(mcp): expose nested execution metadata in parse_mode and MCP responses #1312
4. feat(mcp): add runtime capability detection and experimental gating for Teams coordination #1311
5. docs: align Claude Code adapter guidance with the real nested TaskMaestro plus Teams model #1310

[JeremyDev87]

All 5 sub-issues completed and merged:

• feat(mcp): model TaskMaestro and Teams as composable execution layers #1309 Composable execution layers (PR feat(mcp): model TaskMaestro and Teams as composable execution layers (#1309) #1319) ✅
• docs: align Claude Code adapter guidance with the real nested TaskMaestro plus Teams model #1310 Docs alignment (PR docs: align Claude Code adapter guidance with nested TaskMaestro+Teams model (#1310) #1317) ✅
• feat(mcp): add runtime capability detection and experimental gating for Teams coordination #1311 Teams capability detection (PR feat(mcp): add runtime capability detection for Teams coordination (#1311) #1318) ✅
• feat(mcp): expose nested execution metadata in parse_mode and MCP responses #1312 parse_mode nested metadata (PR feat(mcp): expose nested execution metadata in parse_mode (#1312) #1327) ✅
• feat(mcp): extend TaskMaestro pane assignments to bootstrap inner Teams workflows #1313 Pane inner Teams bootstrap (PR feat(mcp): extend TaskMaestro pane assignments for inner Teams bootstrap (#1313) #1321) ✅

Nested TaskMaestro + Teams execution model fully implemented.