From 95009bc83e8edb27ff071a6967c01da1332a1bc5 Mon Sep 17 00:00:00 2001 From: Marcio Date: Fri, 13 Feb 2026 20:06:24 -0300 Subject: [PATCH 1/5] Add design doc for team-based plan execution feature Documents the proposal to leverage Claude Code agent teams (TeamCreate, SendMessage, shared TaskList) in the execution skills, with detection, user choice, and cross-platform fallback. Co-Authored-By: Claude Opus 4.6 --- ...-02-13-team-based-plan-execution-design.md | 79 +++++++++++++++++++ 1 file changed, 79 insertions(+) create mode 100644 docs/plans/2026-02-13-team-based-plan-execution-design.md diff --git a/docs/plans/2026-02-13-team-based-plan-execution-design.md b/docs/plans/2026-02-13-team-based-plan-execution-design.md new file mode 100644 index 000000000..e0600005c --- /dev/null +++ b/docs/plans/2026-02-13-team-based-plan-execution-design.md @@ -0,0 +1,79 @@ +# Team-Based Plan Execution + +## Problem + +The execution skills (`executing-plans`, `subagent-driven-development`, `dispatching-parallel-agents`) use a sequential subagent dispatch pattern: one subagent at a time, with the main agent as controller. Claude Code now offers an agent teams feature (`TeamCreate`, `SendMessage`, shared `TaskList`) that enables true parallel execution with persistent inter-agent coordination. + +Since superpowers is cross-platform (Claude Code, Codex, OpenCode), team support must be additive: detect availability, ask the user, and fall back to the current pattern when teams aren't available. + +## Suggested Approach + +### Detection & User Choice Flow + +When an execution skill starts, before dispatching work: + +1. **Detect** whether the environment supports teams (e.g., attempt `TeamCreate` or check for the tool's availability) +2. **If available**, ask the user: "Agent teams are available. Would you like to use a team for parallel execution, or proceed with the standard sequential approach?" +3. **If not available** (or user declines), proceed with the current subagent pattern unchanged + +This keeps superpowers fully functional on Codex, OpenCode, and Claude Code installations without teams enabled. + +### What Teams Enable + +- **True parallelism:** Multiple implementer agents working on independent tasks simultaneously, instead of one-at-a-time +- **Persistent coordination:** Team members can message each other, share findings, and coordinate through a shared task list - the controller isn't a bottleneck +- **Structured lifecycle:** Teams have explicit creation, task assignment, and shutdown phases that map naturally to plan execution + +## Per-Skill Impact + +### `subagent-driven-development` (highest value) + +Currently dispatches one implementer subagent at a time, waits for completion, runs two review stages, then moves to next task. With teams: + +- Spawn a team with implementer agents that can work on independent tasks in parallel +- Reviewer agents can be dispatched as tasks complete, without blocking other implementers +- The controller orchestrates via the shared task list and messages rather than sequential dispatch +- Constraint: tasks with dependencies still run sequentially - only independent tasks parallelize + +### `dispatching-parallel-agents` (natural fit) + +Already designed for parallel independent work, but currently uses individual `Task` tool calls without coordination. With teams: + +- Agents become team members that can share findings via `SendMessage` +- Results are collected through the shared task list rather than waiting for individual agent returns +- Better visibility into progress while agents work + +### `executing-plans` (modest benefit) + +Designed for batch execution with human review checkpoints between batches. With teams: + +- Tasks within a batch could run in parallel instead of sequentially +- Review checkpoints between batches remain unchanged (human-in-the-loop) +- Benefit is smaller here since the human review gates limit parallelism + +## Proposed Phases + +### Phase 1: Team detection and user choice infrastructure + +Add a shared pattern (usable by all three skills) that detects team availability and prompts the user. When teams aren't available or declined, the existing behavior is preserved exactly. + +### Phase 2: `subagent-driven-development` team mode + +Highest value - this skill already orchestrates multiple subagents and has the most to gain from parallelism. Implement team-based execution as an alternative path alongside the current sequential path. + +### Phase 3: `dispatching-parallel-agents` team mode + +Natural fit - upgrade from fire-and-forget parallel `Task` calls to coordinated team members with messaging and shared task tracking. + +### Phase 4: `executing-plans` team mode + +Modest benefit - parallelize tasks within a batch while preserving human review checkpoints between batches. + +## Cross-Platform Considerations + +Since superpowers supports Claude Code, Codex, and OpenCode, all team-related instructions must be gated behind detection. Skills should maintain two clear paths: + +- **Current subagent pattern** (default, works everywhere) +- **Team pattern** (Claude Code with teams enabled, user opted in) + +No skill should break or degrade on non-Claude-Code environments. From a8c48ad6576a018ea2e916d19c644de8d1101e62 Mon Sep 17 00:00:00 2001 From: Marcio Date: Fri, 13 Feb 2026 20:47:01 -0300 Subject: [PATCH 2/5] Add implementation plan for team-based plan execution 7-task plan covering: writing-plans handoff update, subagent-driven-development team mode (decision tree + process flow), dispatching-parallel-agents team mode, executing-plans within-batch parallelism, red flags, and integration review. Co-Authored-By: Claude Opus 4.6 --- ...eam-based-plan-execution-implementation.md | 382 ++++++++++++++++++ 1 file changed, 382 insertions(+) create mode 100644 docs/plans/2026-02-13-team-based-plan-execution-implementation.md diff --git a/docs/plans/2026-02-13-team-based-plan-execution-implementation.md b/docs/plans/2026-02-13-team-based-plan-execution-implementation.md new file mode 100644 index 000000000..bbdb817ed --- /dev/null +++ b/docs/plans/2026-02-13-team-based-plan-execution-implementation.md @@ -0,0 +1,382 @@ +# Team-Based Plan Execution Implementation Plan + +> **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task. + +**Goal:** Add Claude Code agent team support to the three execution skills, with detection, user choice, and cross-platform fallback. + +**Architecture:** Each execution skill gets a "Team Mode" section that activates only when Claude Code teams are detected and the user opts in. The existing sequential subagent pattern remains the default. A shared detection-and-choice pattern is documented once and referenced by all three skills. + +**Tech Stack:** Markdown skill files (SKILL.md), Claude Code tools (TeamCreate, SendMessage, TaskCreate/TaskUpdate/TaskList, Task) + +**Design doc:** `docs/plans/2026-02-13-team-based-plan-execution-design.md` + +--- + +### Task 1: Add team detection and choice pattern to `writing-plans` + +The entry point for execution mode selection is `writing-plans/SKILL.md`, which currently offers two choices (subagent-driven or parallel session). Add a third option for team-based execution and document the detection pattern. + +**Files:** +- Modify: `skills/writing-plans/SKILL.md` (Execution Handoff section, ~line 99-117) + +**Step 1: Add team detection instructions to the Execution Handoff section** + +After the current two options, add a third option and a detection preamble. Replace the Execution Handoff section with: + +```markdown +## Execution Handoff + +After saving the plan, check for team support and offer execution choice: + +**Detection:** Before presenting options, check if the `TeamCreate` tool is available in this environment. +If it is, include Option 3 below. If not, only show Options 1 and 2. + +**"Plan complete and saved to `docs/plans/.md`. Execution options:** + +**1. Subagent-Driven (this session)** - I dispatch fresh subagent per task, review between tasks, fast iteration + +**2. Parallel Session (separate)** - Open new session with executing-plans, batch execution with checkpoints + +**3. Team-Based (parallel, this session)** *(only if TeamCreate is available)* - Spawn an agent team with parallel implementers and reviewers, coordinated via shared task list + +**Which approach?"** + +**If Subagent-Driven chosen:** +- **REQUIRED SUB-SKILL:** Use superpowers:subagent-driven-development +- Stay in this session +- Fresh subagent per task + code review + +**If Parallel Session chosen:** +- Guide them to open new session in worktree +- **REQUIRED SUB-SKILL:** New session uses superpowers:executing-plans + +**If Team-Based chosen:** +- **REQUIRED SUB-SKILL:** Use superpowers:subagent-driven-development (team mode) +- Stay in this session +- TeamCreate to spawn parallel implementers +- Shared TaskList for coordination +``` + +**Step 2: Commit** + +```bash +git add skills/writing-plans/SKILL.md +git commit -m "feat(writing-plans): add team-based execution as third handoff option" +``` + +--- + +### Task 2: Add team mode to `subagent-driven-development` - When to Use decision tree + +Add team mode branching to the decision tree at the top of the skill. + +**Files:** +- Modify: `skills/subagent-driven-development/SKILL.md` (When to Use section) + +**Step 1: Update the decision tree** + +Add a new decision node after "Stay in this session?" that checks for team availability. The updated flow: + +```markdown +## When to Use + +\`\`\`dot +digraph when_to_use { + "Have implementation plan?" [shape=diamond]; + "Tasks mostly independent?" [shape=diamond]; + "Stay in this session?" [shape=diamond]; + "TeamCreate available and user opted in?" [shape=diamond]; + "subagent-driven-development (team mode)" [shape=box]; + "subagent-driven-development (standard)" [shape=box]; + "executing-plans" [shape=box]; + "Manual execution or brainstorm first" [shape=box]; + + "Have implementation plan?" -> "Tasks mostly independent?" [label="yes"]; + "Have implementation plan?" -> "Manual execution or brainstorm first" [label="no"]; + "Tasks mostly independent?" -> "Stay in this session?" [label="yes"]; + "Tasks mostly independent?" -> "Manual execution or brainstorm first" [label="no - tightly coupled"]; + "Stay in this session?" -> "TeamCreate available and user opted in?" [label="yes"]; + "Stay in this session?" -> "executing-plans" [label="no - parallel session"]; + "TeamCreate available and user opted in?" -> "subagent-driven-development (team mode)" [label="yes"]; + "TeamCreate available and user opted in?" -> "subagent-driven-development (standard)" [label="no"]; +} +\`\`\` +``` + +**Step 2: Commit** + +```bash +git add skills/subagent-driven-development/SKILL.md +git commit -m "feat(subagent-driven-dev): add team mode to When to Use decision tree" +``` + +--- + +### Task 3: Add team mode process flow to `subagent-driven-development` + +Add a "Team Mode" section describing the parallel execution flow using Claude Code teams. + +**Files:** +- Modify: `skills/subagent-driven-development/SKILL.md` (add new section after The Process) + +**Step 1: Add Team Mode section after the existing Process section** + +Insert after the current process flow and before the Prompt Templates section: + +```markdown +## Team Mode (Claude Code Only) + +When the user opts into team mode and `TeamCreate` is available, use this alternative flow instead of the standard sequential process above. + +**Core difference:** Independent tasks run in parallel via team members. Review gates remain sequential per task. + +### Team Composition + +- **Team Lead (you):** Orchestrates work, assigns tasks, reviews results +- **Implementer agents:** One per independent task, spawned as team members +- **Reviewer agents:** Dispatched per task after implementation completes (spec then quality) + +### Team Mode Process + +\`\`\`dot +digraph team_process { + rankdir=TB; + + "Read plan, extract tasks, identify independent groups" [shape=box]; + "TeamCreate with implementer agents" [shape=box]; + "Assign independent tasks to implementers via TaskCreate" [shape=box]; + "Implementers work in parallel" [shape=box]; + "As each implementer completes:" [shape=box]; + + subgraph cluster_per_task { + label="Per Completed Task (sequential)"; + "Dispatch spec reviewer for task" [shape=box]; + "Spec passes?" [shape=diamond]; + "Send fix instructions to implementer" [shape=box]; + "Dispatch code quality reviewer" [shape=box]; + "Quality passes?" [shape=diamond]; + "Send quality fix instructions" [shape=box]; + "Mark task complete" [shape=box]; + } + + "More tasks to assign?" [shape=diamond]; + "Assign next batch to idle implementers" [shape=box]; + "All tasks complete" [shape=box]; + "Shutdown team" [shape=box]; + "Final code review + finishing-a-development-branch" [shape=box]; + + "Read plan, extract tasks, identify independent groups" -> "TeamCreate with implementer agents"; + "TeamCreate with implementer agents" -> "Assign independent tasks to implementers via TaskCreate"; + "Assign independent tasks to implementers via TaskCreate" -> "Implementers work in parallel"; + "Implementers work in parallel" -> "As each implementer completes:"; + "As each implementer completes:" -> "Dispatch spec reviewer for task"; + "Dispatch spec reviewer for task" -> "Spec passes?"; + "Spec passes?" -> "Send fix instructions to implementer" [label="no"]; + "Send fix instructions to implementer" -> "Dispatch spec reviewer for task"; + "Spec passes?" -> "Dispatch code quality reviewer" [label="yes"]; + "Dispatch code quality reviewer" -> "Quality passes?"; + "Quality passes?" -> "Send quality fix instructions" [label="no"]; + "Send quality fix instructions" -> "Dispatch code quality reviewer"; + "Quality passes?" -> "Mark task complete" [label="yes"]; + "Mark task complete" -> "More tasks to assign?"; + "More tasks to assign?" -> "Assign next batch to idle implementers" [label="yes"]; + "Assign next batch to idle implementers" -> "Implementers work in parallel"; + "More tasks to assign?" -> "All tasks complete" [label="no"]; + "All tasks complete" -> "Shutdown team"; + "Shutdown team" -> "Final code review + finishing-a-development-branch"; +} +\`\`\` + +### Key Constraints in Team Mode + +- **Review gates are still sequential per task:** spec review must pass before code quality review +- **Dependent tasks must wait:** only dispatch tasks whose dependencies are complete +- **Implementers on different tasks in parallel is OK:** they work on separate files +- **Implementers on the same task is NOT OK:** one implementer per task +- **Team lead handles review dispatch:** don't delegate review scheduling to implementers +- **Use SendMessage for fix instructions:** when a reviewer finds issues, message the implementer with specific fixes needed +- **Use shared TaskList for tracking:** all task state lives in the team's task list + +### Team Lifecycle + +1. **Create:** `TeamCreate` at start of execution +2. **Staff:** Spawn implementer agents as team members via `Task` with `team_name` +3. **Assign:** Create tasks via `TaskCreate`, assign via `TaskUpdate` with `owner` +4. **Coordinate:** Use `SendMessage` for review feedback, fix instructions +5. **Shutdown:** Send `shutdown_request` to all team members when complete +6. **Cleanup:** `TeamDelete` after all members shut down +``` + +**Step 2: Commit** + +```bash +git add skills/subagent-driven-development/SKILL.md +git commit -m "feat(subagent-driven-dev): add team mode process flow and constraints" +``` + +--- + +### Task 4: Add team mode to `dispatching-parallel-agents` + +Add a team-based alternative to the current parallel Task dispatch. + +**Files:** +- Modify: `skills/dispatching-parallel-agents/SKILL.md` (add Team Mode section after The Pattern) + +**Step 1: Add Team Mode section** + +Insert after "The Pattern" section (after Step 4: Review and Integrate): + +```markdown +## Team Mode (Claude Code Only) + +If `TeamCreate` is available and the user opts in, use a coordinated team instead of individual `Task` calls. + +### Standard Mode vs Team Mode + +| Aspect | Standard (Task calls) | Team Mode | +|--------|----------------------|-----------| +| Dispatch | Individual `Task` tool calls | `TeamCreate` + team members | +| Communication | None between agents | `SendMessage` for sharing findings | +| Progress tracking | Wait for Task return | Shared `TaskList` with live status | +| Result collection | Read each Task result | Agents report via messages + TaskUpdate | +| Best for | Quick independent investigations | Longer investigations needing coordination | + +### When to Prefer Team Mode + +- Investigations may need to share context mid-flight (e.g., "I found the root cause is in module X, check if it affects your area too") +- More than 3 parallel agents (better lifecycle management) +- Agents may discover dependencies during investigation + +### Team Mode Pattern + +1. **Create team:** `TeamCreate` with descriptive name +2. **Spawn investigators:** One team member per independent domain +3. **Let them work:** Agents investigate, can message each other if relevant findings +4. **Collect results:** Team lead monitors `TaskList`, reads agent messages +5. **Integrate:** Same as standard - verify fixes don't conflict, run full suite +6. **Shutdown:** `shutdown_request` to all members, then `TeamDelete` +``` + +**Step 2: Commit** + +```bash +git add skills/dispatching-parallel-agents/SKILL.md +git commit -m "feat(dispatching-parallel): add team mode as alternative to Task dispatch" +``` + +--- + +### Task 5: Add team mode to `executing-plans` + +Add within-batch parallelism via teams. + +**Files:** +- Modify: `skills/executing-plans/SKILL.md` (add Team Mode section after Step 5) + +**Step 1: Add Team Mode section** + +Insert before "When to Stop and Ask for Help": + +```markdown +### Team Mode (Claude Code Only) + +If `TeamCreate` is available and the user opted in during the writing-plans handoff, parallelize tasks within each batch. + +**What changes:** +- Step 2 (Execute Batch): Instead of executing 3 tasks sequentially, spawn a team and assign batch tasks to team members working in parallel +- Step 3 (Report): Wait for all batch members to complete, then report combined results +- Steps 1, 4, 5: Unchanged (plan review, feedback loop, and completion stay the same) + +**What doesn't change:** +- Batch boundaries and human review checkpoints remain +- Default batch size is still 3 tasks +- "Ready for feedback" checkpoint after each batch +- The human-in-the-loop approval between batches is preserved + +**Team lifecycle per batch:** +1. `TeamCreate` for the batch +2. Assign batch tasks to team members +3. Wait for all to complete +4. Report results, wait for feedback +5. `TeamDelete` (or reuse for next batch) +``` + +**Step 2: Commit** + +```bash +git add skills/executing-plans/SKILL.md +git commit -m "feat(executing-plans): add team mode for within-batch parallelism" +``` + +--- + +### Task 6: Update Red Flags and cross-platform notes + +Add team-specific red flags and ensure cross-platform safety is documented. + +**Files:** +- Modify: `skills/subagent-driven-development/SKILL.md` (Red Flags section) +- Modify: `skills/dispatching-parallel-agents/SKILL.md` (When NOT to Use section) + +**Step 1: Add team-specific red flags to subagent-driven-development** + +Add to the existing "Never:" list: + +```markdown +**Team mode specific - Never:** +- Use team mode when `TeamCreate` is not available (fall back to standard mode) +- Assume team mode works on non-Claude-Code environments (Codex, OpenCode) +- Skip the user choice - always ask before spawning a team +- Let implementers self-assign tasks (team lead assigns via TaskUpdate) +- Forget to shutdown the team (always send shutdown_request + TeamDelete) +``` + +**Step 2: Add cross-platform note to dispatching-parallel-agents** + +Add a note in the "When NOT to Use" section: + +```markdown +**Cross-platform note:** Team mode requires Claude Code with teams enabled (beta). +On Codex, OpenCode, or Claude Code without teams, use the standard parallel Task dispatch. +Always detect capability before offering team mode. +``` + +**Step 3: Commit** + +```bash +git add skills/subagent-driven-development/SKILL.md skills/dispatching-parallel-agents/SKILL.md +git commit -m "feat: add team-specific red flags and cross-platform safety notes" +``` + +--- + +### Task 7: Final review and integration test + +Verify all changes are consistent and the skills work together. + +**Step 1: Read all modified files end-to-end** + +Verify: +- `writing-plans` offers 3 execution options (with detection) +- `subagent-driven-development` has both standard and team mode paths +- `dispatching-parallel-agents` has team mode alternative +- `executing-plans` has within-batch parallelism option +- All team features are gated behind detection +- No skill breaks when `TeamCreate` is unavailable +- Cross-platform notes are present + +**Step 2: Verify decision tree consistency** + +Trace the full flow: +1. `writing-plans` → user chooses team-based → routes to `subagent-driven-development (team mode)` +2. `subagent-driven-development` → detects TeamCreate → offers team mode → spawns team +3. `dispatching-parallel-agents` → detects TeamCreate → offers team mode → spawns team +4. `executing-plans` → detects TeamCreate → parallelizes within batch + +**Step 3: Commit any fixes found during review** + +```bash +git add -A +git commit -m "fix: address integration issues found during final review" +``` From 550bb9289cde29fac16594f2c5a74670443d5ece Mon Sep 17 00:00:00 2001 From: Marcio Date: Fri, 13 Feb 2026 21:04:00 -0300 Subject: [PATCH 3/5] feat: Add Claude Code agent team support to execution skills Add team mode as an optional execution path for all three execution skills, gated behind TeamCreate detection and user choice: - writing-plans: Third execution handoff option (team-based) - subagent-driven-development: Full team mode with parallel implementers, sequential review gates, team lifecycle management - dispatching-parallel-agents: Team mode alternative with inter-agent messaging and shared task tracking - executing-plans: Within-batch parallelism via teams All changes are additive and cross-platform safe - team features only activate on Claude Code with teams enabled, existing behavior is preserved on Codex, OpenCode, and Claude Code without teams. Relates to: https://github.com/obra/superpowers/issues/469 Co-Authored-By: Claude Opus 4.6 --- skills/dispatching-parallel-agents/SKILL.md | 31 ++++++ skills/executing-plans/SKILL.md | 24 +++++ skills/subagent-driven-development/SKILL.md | 103 +++++++++++++++++++- skills/writing-plans/SKILL.md | 14 ++- 4 files changed, 168 insertions(+), 4 deletions(-) diff --git a/skills/dispatching-parallel-agents/SKILL.md b/skills/dispatching-parallel-agents/SKILL.md index 33b14859f..8603b23fc 100644 --- a/skills/dispatching-parallel-agents/SKILL.md +++ b/skills/dispatching-parallel-agents/SKILL.md @@ -79,6 +79,37 @@ When agents return: - Run full test suite - Integrate all changes +## Team Mode (Claude Code Only) + +If `TeamCreate` is available and the user opts in, use a coordinated team instead of individual `Task` calls. + +### Standard Mode vs Team Mode + +| Aspect | Standard (Task calls) | Team Mode | +|--------|----------------------|-----------| +| Dispatch | Individual `Task` tool calls | `TeamCreate` + team members | +| Communication | None between agents | `SendMessage` for sharing findings | +| Progress tracking | Wait for Task return | Shared `TaskList` with live status | +| Result collection | Read each Task result | Agents report via messages + `TaskUpdate` | +| Best for | Quick independent investigations | Longer investigations needing coordination | + +### When to Prefer Team Mode + +- Investigations may need to share context mid-flight (e.g., "I found the root cause is in module X, check if it affects your area too") +- More than 3 parallel agents (better lifecycle management) +- Agents may discover dependencies during investigation + +### Team Mode Pattern + +1. **Create team:** `TeamCreate` with descriptive name +2. **Spawn investigators:** One team member per independent domain +3. **Let them work:** Agents investigate, can message each other if relevant findings +4. **Collect results:** Team lead monitors `TaskList`, reads agent messages +5. **Integrate:** Same as standard - verify fixes don't conflict, run full suite +6. **Shutdown:** `shutdown_request` to all members, then `TeamDelete` + +**Cross-platform note:** Team mode requires Claude Code with teams enabled (beta). On Codex, OpenCode, or Claude Code without teams, use the standard parallel `Task` dispatch. Always detect capability before offering team mode. + ## Agent Prompt Structure Good agent prompts are: diff --git a/skills/executing-plans/SKILL.md b/skills/executing-plans/SKILL.md index c1b2533f4..3e0739aa0 100644 --- a/skills/executing-plans/SKILL.md +++ b/skills/executing-plans/SKILL.md @@ -49,6 +49,30 @@ After all tasks complete and verified: - **REQUIRED SUB-SKILL:** Use superpowers:finishing-a-development-branch - Follow that skill to verify tests, present options, execute choice +### Team Mode (Claude Code Only) + +If `TeamCreate` is available and the user opted in during the writing-plans handoff, parallelize tasks within each batch. + +**What changes:** +- Step 2 (Execute Batch): Instead of executing 3 tasks sequentially, spawn a team and assign batch tasks to team members working in parallel +- Step 3 (Report): Wait for all batch members to complete, then report combined results +- Steps 1, 4, 5: Unchanged (plan review, feedback loop, and completion stay the same) + +**What doesn't change:** +- Batch boundaries and human review checkpoints remain +- Default batch size is still 3 tasks +- "Ready for feedback" checkpoint after each batch +- The human-in-the-loop approval between batches is preserved + +**Team lifecycle per batch:** +1. `TeamCreate` for the batch (or reuse existing team) +2. Assign batch tasks to team members +3. Wait for all to complete +4. Report results, wait for feedback +5. `TeamDelete` when all work is done (or reuse for next batch) + +**Cross-platform note:** Team mode requires Claude Code with teams enabled (beta). On Codex, OpenCode, or Claude Code without teams, use the standard sequential batch execution. Always detect capability before offering team mode. + ## When to Stop and Ask for Help **STOP executing immediately when:** diff --git a/skills/subagent-driven-development/SKILL.md b/skills/subagent-driven-development/SKILL.md index b578dfa48..caeabe6c1 100644 --- a/skills/subagent-driven-development/SKILL.md +++ b/skills/subagent-driven-development/SKILL.md @@ -16,7 +16,9 @@ digraph when_to_use { "Have implementation plan?" [shape=diamond]; "Tasks mostly independent?" [shape=diamond]; "Stay in this session?" [shape=diamond]; - "subagent-driven-development" [shape=box]; + "TeamCreate available and user opted in?" [shape=diamond]; + "subagent-driven-development (team mode)" [shape=box]; + "subagent-driven-development (standard)" [shape=box]; "executing-plans" [shape=box]; "Manual execution or brainstorm first" [shape=box]; @@ -24,8 +26,10 @@ digraph when_to_use { "Have implementation plan?" -> "Manual execution or brainstorm first" [label="no"]; "Tasks mostly independent?" -> "Stay in this session?" [label="yes"]; "Tasks mostly independent?" -> "Manual execution or brainstorm first" [label="no - tightly coupled"]; - "Stay in this session?" -> "subagent-driven-development" [label="yes"]; + "Stay in this session?" -> "TeamCreate available and user opted in?" [label="yes"]; "Stay in this session?" -> "executing-plans" [label="no - parallel session"]; + "TeamCreate available and user opted in?" -> "subagent-driven-development (team mode)" [label="yes"]; + "TeamCreate available and user opted in?" -> "subagent-driven-development (standard)" [label="no"]; } ``` @@ -35,6 +39,12 @@ digraph when_to_use { - Two-stage review after each task: spec compliance first, then code quality - Faster iteration (no human-in-loop between tasks) +**Team mode vs. Standard mode:** +- True parallelism (multiple implementers working simultaneously on independent tasks) +- Persistent coordination via `SendMessage` and shared `TaskList` +- Review gates remain sequential per task (spec then quality) +- Requires Claude Code with teams feature enabled (beta) + ## The Process ```dot @@ -82,6 +92,88 @@ digraph process { } ``` +## Team Mode (Claude Code Only) + +When the user opts into team mode and `TeamCreate` is available, use this alternative flow instead of the standard sequential process above. + +**Core difference:** Independent tasks run in parallel via team members. Review gates remain sequential per task. + +### Team Composition + +- **Team Lead (you):** Orchestrates work, assigns tasks, reviews results +- **Implementer agents:** One per independent task, spawned as team members +- **Reviewer agents:** Dispatched per task after implementation completes (spec then quality) + +### Team Mode Process + +```dot +digraph team_process { + rankdir=TB; + + "Read plan, extract tasks, identify independent groups" [shape=box]; + "TeamCreate with implementer agents" [shape=box]; + "Assign independent tasks to implementers via TaskCreate" [shape=box]; + "Implementers work in parallel" [shape=box]; + "As each implementer completes:" [shape=box]; + + subgraph cluster_per_task { + label="Per Completed Task (sequential)"; + "Dispatch spec reviewer for task" [shape=box]; + "Spec passes?" [shape=diamond]; + "Send fix instructions to implementer" [shape=box]; + "Dispatch code quality reviewer" [shape=box]; + "Quality passes?" [shape=diamond]; + "Send quality fix instructions" [shape=box]; + "Mark task complete" [shape=box]; + } + + "More tasks to assign?" [shape=diamond]; + "Assign next batch to idle implementers" [shape=box]; + "All tasks complete" [shape=box]; + "Shutdown team" [shape=box]; + "Final code review + finishing-a-development-branch" [shape=box]; + + "Read plan, extract tasks, identify independent groups" -> "TeamCreate with implementer agents"; + "TeamCreate with implementer agents" -> "Assign independent tasks to implementers via TaskCreate"; + "Assign independent tasks to implementers via TaskCreate" -> "Implementers work in parallel"; + "Implementers work in parallel" -> "As each implementer completes:"; + "As each implementer completes:" -> "Dispatch spec reviewer for task"; + "Dispatch spec reviewer for task" -> "Spec passes?"; + "Spec passes?" -> "Send fix instructions to implementer" [label="no"]; + "Send fix instructions to implementer" -> "Dispatch spec reviewer for task"; + "Spec passes?" -> "Dispatch code quality reviewer" [label="yes"]; + "Dispatch code quality reviewer" -> "Quality passes?"; + "Quality passes?" -> "Send quality fix instructions" [label="no"]; + "Send quality fix instructions" -> "Dispatch code quality reviewer"; + "Quality passes?" -> "Mark task complete" [label="yes"]; + "Mark task complete" -> "More tasks to assign?"; + "More tasks to assign?" -> "Assign next batch to idle implementers" [label="yes"]; + "Assign next batch to idle implementers" -> "Implementers work in parallel"; + "More tasks to assign?" -> "All tasks complete" [label="no"]; + "All tasks complete" -> "Shutdown team"; + "Shutdown team" -> "Final code review + finishing-a-development-branch"; +} +``` + +### Key Constraints in Team Mode + +- **Review gates are still sequential per task:** spec review must pass before code quality review +- **Dependent tasks must wait:** only dispatch tasks whose dependencies are complete +- **Implementers on different tasks in parallel is OK:** they work on separate files +- **Implementers on the same task is NOT OK:** one implementer per task +- **Team lead handles review dispatch:** don't delegate review scheduling to implementers +- **Use SendMessage for fix instructions:** when a reviewer finds issues, message the implementer with specific fixes needed +- **Use shared TaskList for tracking:** all task state lives in the team's task list + +### Team Lifecycle + +1. **Create:** `TeamCreate` at start of execution +2. **Staff:** Spawn implementer agents as team members via `Task` with `team_name` +3. **Assign:** Create tasks via `TaskCreate`, assign via `TaskUpdate` with `owner` +4. **Coordinate:** Use `SendMessage` for review feedback, fix instructions +5. **Shutdown:** Send `shutdown_request` to all team members when complete +6. **Cleanup:** `TeamDelete` after all members shut down + ## Prompt Templates - `./implementer-prompt.md` - Dispatch implementer subagent @@ -212,6 +304,13 @@ Done! - **Start code quality review before spec compliance is ✅** (wrong order) - Move to next task while either review has open issues +**Team mode specific - Never:** +- Use team mode when `TeamCreate` is not available (fall back to standard mode) +- Assume team mode works on non-Claude-Code environments (Codex, OpenCode) +- Skip the user choice - always ask before spawning a team +- Let implementers self-assign tasks (team lead assigns via `TaskUpdate`) +- Forget to shutdown the team (always send `shutdown_request` + `TeamDelete`) + **If subagent asks questions:** - Answer clearly and completely - Provide additional context if needed diff --git a/skills/writing-plans/SKILL.md b/skills/writing-plans/SKILL.md index 5fc45b6ff..fef35b406 100644 --- a/skills/writing-plans/SKILL.md +++ b/skills/writing-plans/SKILL.md @@ -96,14 +96,18 @@ git commit -m "feat: add specific feature" ## Execution Handoff -After saving the plan, offer execution choice: +After saving the plan, check for team support and offer execution choice: -**"Plan complete and saved to `docs/plans/.md`. Two execution options:** +**Detection:** Before presenting options, check if the `TeamCreate` tool is available in this environment. If it is, include Option 3 below. If not, only show Options 1 and 2. + +**"Plan complete and saved to `docs/plans/.md`. Execution options:** **1. Subagent-Driven (this session)** - I dispatch fresh subagent per task, review between tasks, fast iteration **2. Parallel Session (separate)** - Open new session with executing-plans, batch execution with checkpoints +**3. Team-Based (parallel, this session)** *(only if TeamCreate is available)* - Spawn an agent team with parallel implementers and reviewers, coordinated via shared task list + **Which approach?"** **If Subagent-Driven chosen:** @@ -114,3 +118,9 @@ After saving the plan, offer execution choice: **If Parallel Session chosen:** - Guide them to open new session in worktree - **REQUIRED SUB-SKILL:** New session uses superpowers:executing-plans + +**If Team-Based chosen:** +- **REQUIRED SUB-SKILL:** Use superpowers:subagent-driven-development (team mode) +- Stay in this session +- `TeamCreate` to spawn parallel implementers +- Shared `TaskList` for coordination From 053f05a26db3f7f0246555c191251457ff285ba2 Mon Sep 17 00:00:00 2001 From: Marcio Date: Fri, 13 Feb 2026 21:39:48 -0300 Subject: [PATCH 4/5] fix: Address PR review feedback from automated reviewers - executing-plans: Add self-contained team detection instead of depending on writing-plans handoff (Copilot #3) - executing-plans: Add independence constraint for within-batch parallelism to prevent file conflicts (Copilot #4) - executing-plans: Clarify team lifecycle - create once before first batch, reuse across batches, delete after final batch (Copilot #5, CodeRabbit #10) - subagent-driven-development: Clarify TaskList replaces TodoWrite in team mode to avoid split-brain state (Copilot #7) - All skills: Add note that TeamCreate/TaskCreate/etc. are Claude Code built-in runtime tools (Copilot #1, #6, #8) - Implementation plan: Fix heading hierarchy MD001 violation (CodeRabbit #9) - Implementation plan: Clarify Tech Stack tool descriptions Co-Authored-By: Claude Opus 4.6 --- ...eam-based-plan-execution-implementation.md | 4 +++- skills/dispatching-parallel-agents/SKILL.md | 2 ++ skills/executing-plans/SKILL.md | 21 +++++++++++-------- skills/subagent-driven-development/SKILL.md | 4 +++- 4 files changed, 20 insertions(+), 11 deletions(-) diff --git a/docs/plans/2026-02-13-team-based-plan-execution-implementation.md b/docs/plans/2026-02-13-team-based-plan-execution-implementation.md index bbdb817ed..da0217511 100644 --- a/docs/plans/2026-02-13-team-based-plan-execution-implementation.md +++ b/docs/plans/2026-02-13-team-based-plan-execution-implementation.md @@ -6,12 +6,14 @@ **Architecture:** Each execution skill gets a "Team Mode" section that activates only when Claude Code teams are detected and the user opts in. The existing sequential subagent pattern remains the default. A shared detection-and-choice pattern is documented once and referenced by all three skills. -**Tech Stack:** Markdown skill files (SKILL.md), Claude Code tools (TeamCreate, SendMessage, TaskCreate/TaskUpdate/TaskList, Task) +**Tech Stack:** Markdown skill files (SKILL.md), Claude Code built-in tools for team creation and messaging (TeamCreate, SendMessage, TeamDelete) and task management (TaskCreate, TaskUpdate, TaskList), plus the existing Task tool **Design doc:** `docs/plans/2026-02-13-team-based-plan-execution-design.md` --- +## Implementation Tasks + ### Task 1: Add team detection and choice pattern to `writing-plans` The entry point for execution mode selection is `writing-plans/SKILL.md`, which currently offers two choices (subagent-driven or parallel session). Add a third option for team-based execution and document the detection pattern. diff --git a/skills/dispatching-parallel-agents/SKILL.md b/skills/dispatching-parallel-agents/SKILL.md index 8603b23fc..a0416dbcd 100644 --- a/skills/dispatching-parallel-agents/SKILL.md +++ b/skills/dispatching-parallel-agents/SKILL.md @@ -83,6 +83,8 @@ When agents return: If `TeamCreate` is available and the user opts in, use a coordinated team instead of individual `Task` calls. +**Note:** `TeamCreate`, `TaskList`, `TaskUpdate`, `SendMessage`, and `TeamDelete` are Claude Code built-in tools provided by the runtime as part of the teams API (currently in beta). + ### Standard Mode vs Team Mode | Aspect | Standard (Task calls) | Team Mode | diff --git a/skills/executing-plans/SKILL.md b/skills/executing-plans/SKILL.md index 3e0739aa0..7917a3d6c 100644 --- a/skills/executing-plans/SKILL.md +++ b/skills/executing-plans/SKILL.md @@ -51,27 +51,30 @@ After all tasks complete and verified: ### Team Mode (Claude Code Only) -If `TeamCreate` is available and the user opted in during the writing-plans handoff, parallelize tasks within each batch. +Before executing the first batch, check if the `TeamCreate` tool is available. If it is, ask the user: "Agent teams are available. Would you like to parallelize tasks within batches, or proceed with standard sequential execution?" If not available or the user declines, use the standard sequential flow. + +**Note:** `TeamCreate`, `TaskCreate`, `TaskUpdate`, `TaskList`, `SendMessage`, and `TeamDelete` are Claude Code built-in tools provided by the runtime as part of the teams API (currently in beta). **What changes:** -- Step 2 (Execute Batch): Instead of executing 3 tasks sequentially, spawn a team and assign batch tasks to team members working in parallel +- Step 2 (Execute Batch): Instead of executing 3 tasks sequentially, assign batch tasks to team members working in parallel - Step 3 (Report): Wait for all batch members to complete, then report combined results - Steps 1, 4, 5: Unchanged (plan review, feedback loop, and completion stay the same) +**Independence constraint:** Only parallelize tasks within a batch if they are independent (touch different files, no implicit dependencies). If tasks in a batch may conflict, fall back to sequential execution for that batch. + **What doesn't change:** - Batch boundaries and human review checkpoints remain - Default batch size is still 3 tasks - "Ready for feedback" checkpoint after each batch - The human-in-the-loop approval between batches is preserved -**Team lifecycle per batch:** -1. `TeamCreate` for the batch (or reuse existing team) -2. Assign batch tasks to team members -3. Wait for all to complete -4. Report results, wait for feedback -5. `TeamDelete` when all work is done (or reuse for next batch) +**Team lifecycle:** +1. `TeamCreate` once before the first batch +2. For each batch: assign tasks to team members, wait for all to complete, report results, wait for feedback +3. Reuse the same team across batches (no need to recreate) +4. `TeamDelete` after the final batch completes and all work is done -**Cross-platform note:** Team mode requires Claude Code with teams enabled (beta). On Codex, OpenCode, or Claude Code without teams, use the standard sequential batch execution. Always detect capability before offering team mode. +**Cross-platform note:** Team mode requires Claude Code with teams enabled (beta). On Codex, OpenCode, or Claude Code without teams, use the standard sequential batch execution. ## When to Stop and Ask for Help diff --git a/skills/subagent-driven-development/SKILL.md b/skills/subagent-driven-development/SKILL.md index caeabe6c1..1dd5b5d89 100644 --- a/skills/subagent-driven-development/SKILL.md +++ b/skills/subagent-driven-development/SKILL.md @@ -163,10 +163,12 @@ digraph team_process { - **Implementers on the same task is NOT OK:** one implementer per task - **Team lead handles review dispatch:** don't delegate review scheduling to implementers - **Use SendMessage for fix instructions:** when a reviewer finds issues, message the implementer with specific fixes needed -- **Use shared TaskList for tracking:** all task state lives in the team's task list +- **Use shared TaskList for tracking:** in team mode, the team's `TaskList` replaces `TodoWrite` as the single source of truth for task state. Do not maintain both simultaneously to avoid split-brain state ### Team Lifecycle +**Note:** `TeamCreate`, `TaskCreate`, `TaskUpdate`, `TaskList`, `SendMessage`, and `TeamDelete` are Claude Code built-in tools provided by the runtime as part of the teams API (currently in beta). + 1. **Create:** `TeamCreate` at start of execution 2. **Staff:** Spawn implementer agents as team members via `Task` with `team_name` 3. **Assign:** Create tasks via `TaskCreate`, assign via `TaskUpdate` with `owner` From aac5ccd43f0c467835255e9509ee5d0295cf9b79 Mon Sep 17 00:00:00 2001 From: Marcio Date: Fri, 13 Feb 2026 22:08:58 -0300 Subject: [PATCH 5/5] fix: Align implementation plan Task 5 with actual executing-plans skill Update the plan doc's Task 5 to match the clarified lifecycle and detection wording already applied to skills/executing-plans/SKILL.md. Co-Authored-By: Claude Opus 4.6 --- ...-team-based-plan-execution-implementation.md | 17 +++++++++-------- 1 file changed, 9 insertions(+), 8 deletions(-) diff --git a/docs/plans/2026-02-13-team-based-plan-execution-implementation.md b/docs/plans/2026-02-13-team-based-plan-execution-implementation.md index da0217511..f02d773aa 100644 --- a/docs/plans/2026-02-13-team-based-plan-execution-implementation.md +++ b/docs/plans/2026-02-13-team-based-plan-execution-implementation.md @@ -283,25 +283,26 @@ Insert before "When to Stop and Ask for Help": ```markdown ### Team Mode (Claude Code Only) -If `TeamCreate` is available and the user opted in during the writing-plans handoff, parallelize tasks within each batch. +Before executing the first batch, check if the `TeamCreate` tool is available. If it is, ask the user: "Agent teams are available. Would you like to parallelize tasks within batches, or proceed with standard sequential execution?" If not available or the user declines, use the standard sequential flow. **What changes:** -- Step 2 (Execute Batch): Instead of executing 3 tasks sequentially, spawn a team and assign batch tasks to team members working in parallel +- Step 2 (Execute Batch): Instead of executing 3 tasks sequentially, assign batch tasks to team members working in parallel - Step 3 (Report): Wait for all batch members to complete, then report combined results - Steps 1, 4, 5: Unchanged (plan review, feedback loop, and completion stay the same) +**Independence constraint:** Only parallelize tasks within a batch if they are independent (touch different files, no implicit dependencies). If tasks in a batch may conflict, fall back to sequential execution for that batch. + **What doesn't change:** - Batch boundaries and human review checkpoints remain - Default batch size is still 3 tasks - "Ready for feedback" checkpoint after each batch - The human-in-the-loop approval between batches is preserved -**Team lifecycle per batch:** -1. `TeamCreate` for the batch -2. Assign batch tasks to team members -3. Wait for all to complete -4. Report results, wait for feedback -5. `TeamDelete` (or reuse for next batch) +**Team lifecycle:** +1. `TeamCreate` once before the first batch +2. For each batch: assign tasks to team members, wait for all to complete, report results, wait for feedback +3. Reuse the same team across batches (no need to recreate) +4. `TeamDelete` after the final batch completes and all work is done ``` **Step 2: Commit**