Orchestrate parallel execution of multiple tasks via cmux workspaces. Each task gets its own git worktree + Claude Code session. The parent session acts as orchestrator, monitoring all child sessions. Dynamically discovers available agent types from .claude/agents/ and passes the list to child sessions, which select the appropriate agent themselves. Supports three layout modes: split (panes within current workspace), workspace (separate sidebar entries), and claude-teams (native Agent Teams via cmux claude-teams). Dispatches immediately without parent-side planning — each child handles its own brainstorming/planning in parallel. Use when: "parallel execution", "team dispatch", "run these at once", "run these in parallel", "dispatch tasks", "execute these simultaneously", or when 2+ independent tasks need concurrent execution.
How this skill is triggered — by the user, by Claude, or both
Slash command
/cmux-team-dispatch-task:cmux-team-dispatch-taskThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Orchestrate parallel task execution across multiple Claude Code sessions. Each task runs
Orchestrate parallel task execution across multiple Claude Code sessions. Each task runs in its own isolated git worktree while the parent session coordinates everything. Dispatches immediately — no parent-side planning. Each child session handles its own brainstorming and planning in parallel.
For the Japanese reference guide, see references/guide-ja.md.
This single step handles task collection, agent routing, and layout selection. No routing confirmation, no planning mode selection, no layout question — minimize parent-side overhead and dispatch as fast as possible.
If $ARGUMENTS is empty or not provided, ask the user what tasks to run:
What tasks would you like to run in parallel? You can specify:
- Plan file paths (e.g.,
.claude/plans/feature-a.md)- Task descriptions (e.g., "Implement login page UI")
- Separate multiple tasks by newline or comma
If $ARGUMENTS is provided, parse the input into a task list:
.md inside .claude/plans/ are recognized as plan file references--layout workspace or --layout claude-teams: override default split layout--no-grid: skip grid layout reorganization in split modeScan .claude/agents/ to find available agent definitions:
ls .claude/agents/*.md 2>/dev/null
For each .md file, read YAML frontmatter to extract name and description.
Build a reference list of all discovered agents (name + description). This list will be embedded in each child task's prompt so that each child session decides which agent to follow based on its own task content. The parent does NOT assign agents to tasks.
If .claude/agents/ is empty or doesn't exist, omit the available agents block from prompts.
Present the task list and ask the user which tasks should use the brainstorming skill:
Tasks to dispatch:
- login-page-ui
- auth-api-endpoint
- test-coverage
Available agents: backend-coding, frontend-coding (Each child session will select the appropriate agent)
Which tasks should use the brainstorming skill before planning? Select task numbers, "all", or "none".
This is the only user interaction before dispatch. Based on the selection:
--mode superpowers + MANDATORY EXECUTION SEQUENCE directive--mode plan (Claude built-in /plan mode)Default: split mode. Override via --layout workspace or --layout claude-teams in arguments.
| Mode | Description | Recommended for |
|---|---|---|
split (default) | Split panes within current workspace, auto-grid layout | 2-6 tasks, visual overview |
workspace | Each task in a separate cmux workspace (sidebar entry) | Long-running, 7+ tasks |
claude-teams | Single orchestrator via cmux claude-teams + Agent Teams | Native notifications, sidebar metadata |
split mode: workspace mode: claude-teams mode:
+----------+----------+ +----------+ +----------+ +----------+----------+
| Parent | Child 1 | | ws: t-1 | | ws: t-2 | | Orchest. | Team-1 |
+----------+----------+ | | | | +----------+----------+
| Child 2 | Child 3 | +----------+ +----------+ | Team-2 | Team-3 |
+----------+----------+ +----------+----------+
(auto-grid) (separate tabs) (native Agent Teams)
Print an informational summary (NOT a confirmation prompt) and proceed to launch immediately:
Dispatching 3 tasks (split mode):
1. login-page-ui [brainstorming]
2. auth-api-endpoint [plan]
3. test-coverage [brainstorming]
Available agents: backend-coding, frontend-coding
Launching...
The launch script writes the full prompt to a .cmux-team-dispatch-task-prompt.md file in each
child's working directory (worktree). The Claude command sent via cmux only references
this file, completely avoiding shell escaping issues with complex prompt content.
The launch script generates a .cmux-team-dispatch-task-run.sh script in each child's working
directory (worktree). Instead of sending claude ... directly to the terminal, it sends
bash .cmux-team-dispatch-task-run.sh, which:
status.json to "executing" using absolute pathsclaude command interactively (or cmux claude-teams for claude-teams layout)"done" or "error" to status.jsoncmux wait-for --signal <slug>-donecmux notifyThe signal name for each task is <task-slug>-done, returned in the signal_name field
of the launch script's output JSON.
For each task, construct the full prompt text. Order matters — put behavioral directives first, then the task content:
=== MANDATORY EXECUTION SEQUENCE ===
You are running in superpowers mode with a STRICT execution sequence.
You MUST follow these phases IN ORDER. Skipping any phase is a critical error.
PHASE 1 — BRAINSTORMING (required, do this FIRST):
Use the Skill tool to invoke "superpowers:brainstorming" immediately.
Do NOT read any files, do NOT make any plans, do NOT write any code before
completing brainstorming.
The brainstorming skill will:
- Explore the project context and understand the codebase
- Design your approach with trade-offs considered
- Naturally transition to PHASE 2 when complete
PHASE 2 — PLANNING (automatic transition from brainstorming):
After brainstorming completes, you will be in writing-plans mode.
Write a structured implementation plan.
PHASE 3 — EXECUTION:
After the plan is approved, execute it.
VIOLATION: If you start writing code or making changes without completing
Phase 1 (brainstorming) and Phase 2 (planning), you are operating incorrectly.
Stop and use the Skill tool to invoke "superpowers:brainstorming".
=== END MANDATORY EXECUTION SEQUENCE ===
=== AVAILABLE AGENTS ===
The following agent definitions are available in .claude/agents/.
Read the one that best matches your task and follow its guidelines.
If none are relevant, proceed without an agent.
- backend-coding (.claude/agents/backend-coding.md): <description from frontmatter>
- frontend-coding (.claude/agents/frontend-coding.md): <description from frontmatter>
=== END AVAILABLE AGENTS ===
The task description itself
Status protocol instructions (append to every prompt):
IMPORTANT: Status reporting protocol.
When you finish planning and begin execution, run:
echo '{"status":"executing","message":"<brief description>","timestamp":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'"}' > <project-root>/.dispatch/<task-slug>/status.json
When all work is complete:
1. Stage and commit ALL changes before reporting done:
git add -A
git commit -m "<task-slug>: <concise summary of changes>"
If there are multiple logical units of work, create separate commits for each.
Do NOT skip this step — uncommitted changes will be lost when the worktree is cleaned up.
2. Then report completion:
echo '{"status":"done","message":"<summary of changes>","timestamp":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'"}' > <project-root>/.dispatch/<task-slug>/status.json
And write a result summary to <project-root>/.dispatch/<task-slug>/result.md with sections:
# <Task Name>
## Changes Made
## Test Results
## Commits
If you encounter a blocking error, run:
echo '{"status":"error","message":"<error description>","timestamp":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'"}' > <project-root>/.dispatch/<task-slug>/status.json
Replace <project-root> with the actual project root path and <task-slug> with the task's slug.
For split mode, use launch-session-splits.sh or manual split chaining:
# Create status directories
for slug in <task-slugs>; do
mkdir -p .dispatch/$slug
done
# Build tasks JSON (set mode per task based on brainstorming selection)
# Note: agent selection is NOT done here — it's embedded in each task's prompt text
cat > /tmp/dispatch-tasks.json << 'EOF'
[
{"slug": "login-page-ui", "prompt": "<full prompt with available agents block>", "mode": "superpowers"},
{"slug": "auth-api-endpoint", "prompt": "<full prompt with available agents block>", "mode": "plan"},
...
]
EOF
# Launch all splits (or manually chain launch-workspace.sh calls)
Manual split chaining:
Detect current workspace and surface IDs:
cmux identify
Parse to get PARENT_WS and PARENT_SF. Use CMUX_WORKSPACE_ID/CMUX_SURFACE_ID env vars if set.
Launch FIRST task (split right from parent):
mkdir -p .dispatch/<task-1-slug>
RESULT=$(bash <this-skill-dir>/scripts/launch-workspace.sh \
--mode <plan|superpowers> \
--layout split \
--parent-workspace "$PARENT_WS" \
--split-from "$PARENT_SF" \
--split-direction right \
--status-dir "$(pwd)/.dispatch/<task-1-slug>" \
--parent-notify-workspace "$CMUX_WORKSPACE_ID" \
--parent-notify-surface "$CMUX_SURFACE_ID" \
<task-1-slug> \
"$TASK_1_PROMPT")
PREV_SURFACE=$(echo "$RESULT" | jq -r '.surface_id')
Launch SUBSEQUENT tasks (split down from previous child):
mkdir -p .dispatch/<task-N-slug>
RESULT=$(bash <this-skill-dir>/scripts/launch-workspace.sh \
--mode <plan|superpowers> \
--layout split \
--parent-workspace "$PARENT_WS" \
--split-from "$PREV_SURFACE" \
--split-direction down \
--status-dir "$(pwd)/.dispatch/<task-N-slug>" \
--parent-notify-workspace "$CMUX_WORKSPACE_ID" \
--parent-notify-surface "$CMUX_SURFACE_ID" \
<task-N-slug> \
"$TASK_N_PROMPT")
PREV_SURFACE=$(echo "$RESULT" | jq -r '.surface_id')
Report launched sessions:
All sessions launched:
1. login-page-ui | surface:5 | superpowers
2. auth-api-endpoint | surface:7 | plan
3. test-coverage | surface:9 | superpowers
Available agents: backend-coding, frontend-coding
Layout: split (panes in current workspace)
mkdir -p .dispatch/<task-slug>
bash <this-skill-dir>/scripts/launch-workspace.sh \
--mode <plan|superpowers> \
--status-dir "$(pwd)/.dispatch/<task-slug>" \
--parent-notify-workspace "$CMUX_WORKSPACE_ID" \
--parent-notify-surface "$CMUX_SURFACE_ID" \
<task-slug> \
"$TASK_PROMPT"
Claude Teams mode uses a fundamentally different architecture. Instead of N independent
Claude sessions, launch ONE orchestrator session via cmux claude-teams that uses
Claude's Agent Teams feature (TeamCreate + Agent tool) to dispatch teammates.
# Create status directories for all tasks
for slug in <task-slugs>; do
mkdir -p .dispatch/$slug
done
# Build the orchestrator prompt containing ALL tasks
# (see "Claude Teams Orchestrator Prompt" section below)
# Launch single orchestrator session
bash <this-skill-dir>/scripts/launch-workspace.sh \
--mode <plan|superpowers> \
--layout claude-teams \
--status-dir "$(pwd)/.dispatch" \
--parent-notify-workspace "$CMUX_WORKSPACE_ID" \
--parent-notify-surface "$CMUX_SURFACE_ID" \
team-dispatch \
"$ORCHESTRATOR_PROMPT"
The orchestrator prompt instructs the single Claude session to create a team and dispatch:
You are a team orchestrator. Dispatch the following tasks to teammates in parallel.
AVAILABLE AGENTS:
- backend-coding (.claude/agents/backend-coding.md): <description>
- frontend-coding (.claude/agents/frontend-coding.md): <description>
Each teammate should read the agent definition that best matches their task and follow its guidelines.
TASKS:
1. [slug: <slug>] [mode: <plan|brainstorming>]
<task description>
2. [slug: <slug>] [mode: <plan|brainstorming>]
<task description>
...
INSTRUCTIONS:
1. Create a team with TeamCreate (team_name: "dispatch")
2. For each task, spawn an Agent teammate:
- Use isolation: "worktree" for git isolation
- Include the AVAILABLE AGENTS block in each teammate's prompt so they can select the right agent
- For tasks with [mode: brainstorming], include the MANDATORY EXECUTION SEQUENCE in the prompt
- For tasks with [mode: plan], tell the teammate to use /plan mode
- Include the status protocol instructions in each teammate's prompt
- Run all Agent calls in a SINGLE message to maximize parallelism
3. Monitor via TaskList and SendMessage
4. When all tasks complete, collect results and write to .dispatch/<slug>/result.md
5. Report completion:
echo '{"status":"done","message":"All tasks completed","timestamp":"'$(date -u +%Y-%m-%dT%H:%M:%SZ)'"}' > <project-root>/.dispatch/status.json
IMPORTANT: Launch ALL teammates in parallel (single message with multiple Agent tool calls).
Do NOT launch them sequentially.
STATUS PROTOCOL (for each teammate):
<same status protocol as other modes, adapted for teammates>
Teammates spawned by the orchestrator appear as native cmux split panes with sidebar
metadata and notifications, thanks to the cmux claude-teams tmux shim.
Each child session sends a [dispatch] message to the parent terminal when the Claude
process exits:
[dispatch] task "<slug>" finished (status: done|error)
After launching all tasks:
Launch the background monitor script:
zsh <this-skill-dir>/scripts/monitor-dispatch.sh \
--parent-surface "$CMUX_SURFACE_ID" \
--parent-workspace "$CMUX_WORKSPACE_ID" \
--layout <split|workspace|claude-teams> \
--interval 10 \
--debug \
"$(pwd)/.dispatch"
Run this command with run_in_background so it does not block your turn.
Report the launch summary to the user (task count, slugs, surfaces).
Tell the user: "N タスクを監視中。完了通知を待ちます。"
End your turn. Do not block waiting.
When you receive a [dispatch] task "X" finished message:
.dispatch/<slug>/status.json to get the full status and message."done", also read .dispatch/<slug>/result.md if it exists.When you receive a [dispatch-monitor] message:
This is the all-done notification from the background monitor. All tasks have reached a terminal state. Proceed to Completion.
If the user asks about progress:
for f in .dispatch/*/status.json; do
task_name=$(dirname "$f" | xargs basename)
task_status=$(jq -r '.status' "$f" 2>/dev/null || echo "unknown")
message=$(jq -r '.message' "$f" 2>/dev/null || echo "")
echo "$task_name: $task_status - $message"
done
For workspace mode:
cmux read-screen --workspace <workspace-id> --scrollback
For split mode:
cmux read-screen --workspace <parent-ws> --surface <child-surface-id> --scrollback
When all tasks reach a terminal status ("done" or "error"):
Collect results: Read all .dispatch/<task-slug>/result.md files.
Generate consolidated report:
# Team Dispatch Report
## Task Results
### 1. login-page-ui [brainstorming]
<contents of .dispatch/login-page-ui/result.md>
### 2. auth-api-endpoint [plan]
<contents of .dispatch/auth-api-endpoint/result.md>
## Worktree Branches
- feat/login-page-ui
- feat/auth-api-endpoint
## Next Steps
- Review and merge branches
- Run full test suite across all changes
- Clean up worktrees when done
Ask the user whether to merge:
Present the user with two options:
Option A: Merge worktree branches
for slug in <task-slugs>; do
git merge "feat/$slug" --no-edit || echo "CONFLICT in feat/$slug"
done
# Remove worktrees
for slug in <task-slugs>; do
git worktree remove ".worktrees/$slug" --force 2>/dev/null
done
# Delete feature branches
for slug in <task-slugs>; do
git branch -D "feat/$slug" 2>/dev/null
done
# Remove dispatch directory
rm -rf .dispatch/
# Remove worktrees directory if empty
rmdir .worktrees 2>/dev/null
git log --onelineOption B: Do not merge
Remove only the dispatch directory:
rm -rf .dispatch/
Display cleanup instructions to the user:
Worktrees are preserved for manual review. To clean up later:
# List worktrees
git worktree list
# Remove individual worktree and branch
git worktree remove .worktrees/<task-slug>
git branch -D feat/<task-slug>
# Remove all at once
for slug in <task-slugs>; do
git worktree remove ".worktrees/$slug" --force
git branch -D "feat/$slug"
done
rmdir .worktrees 2>/dev/null
Child sessions communicate with the orchestrator via .dispatch/<task-slug>/:
{
"status": "launched",
"workspace_id": "workspace:N",
"surface_id": "surface:N",
"message": "Human-readable status description",
"timestamp": "2026-04-07T16:00:00Z"
}
| Status | Meaning | Written By |
|---|---|---|
launched | Session started, Claude loading | launch script |
planning | Claude is in planning phase | child session (optional) |
executing | Claude session starting / implementation in progress | runner script / child session |
done | All work complete | runner script / child session |
error | Blocked by an error or non-zero exit | runner script / child session |
Written by the child session when status becomes done:
# <Task Name>
## Changes Made
- List of files changed and what was done
## Test Results
- Test pass/fail summary
## Commits
- <hash> <commit message>
This skill integrates with superpowers:writing-plans as a third execution option in the
Execution Handoff. When a plan is complete, writing-plans presents execution choices:
writing-plans Execution Handoff:
"Plan complete. Three execution options:"
1. Subagent-Driven (recommended) → superpowers:subagent-driven-development
Sequential, one subagent per task, two-stage review after each
2. Inline Execution → superpowers:executing-plans
Batch execution in this session with checkpoints
3. Parallel (cmux split) → cmux-team-dispatch-task split mode ← THIS SKILL
Each task in its own cmux split pane + git worktree, all run concurrently
| Option | Best for |
|---|---|
| Subagent-Driven | Tasks with dependencies, review-heavy workflows, cost-conscious execution |
| Inline Execution | Simple plans, interactive execution, single-session preference |
| Parallel (cmux) | 3+ independent tasks, speed priority, visual overview of all sessions |
When the user selects option 3:
When parsing a superpowers:writing-plans plan file:
### Task N: <name> heading becomes a task entry--no-grid to preserve linear layout./Applications/cmux.app/cmux claude-teams command sets up the tmux shim and CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 environment variable.status.json is updated, cmux wait-for --signal <slug>-done fires, and a [dispatch] text message is sent to the parent terminal via cmux send when the child Claude session exits..cmux-team-dispatch-task-run.sh file is created in each worktree. It's cleaned up along with the worktree.Creates, edits, and optimizes skills for Claude Code, including drafting, evaluating with test prompts, iterating on performance, and improving skill descriptions for better triggering accuracy.
npx claudepluginhub tanaka-yui/yui-cc-plugins --plugin cmux-team-dispatch-task