diff --git a/.claude/rules/custom-instructions.md b/.claude/rules/custom-instructions.md index 96afa347..f64899d0 100644 --- a/.claude/rules/custom-instructions.md +++ b/.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) diff --git a/packages/rules/.ai-rules/adapters/claude-code.md b/packages/rules/.ai-rules/adapters/claude-code.md index d8181c10..8ae41fdb 100644 --- a/packages/rules/.ai-rules/adapters/claude-code.md +++ b/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: "-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: "-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: