Parallel Workflow Orchestrator

Announce at start: "I'm using the parallel-workflow skill to select the optimal parallelization strategy."

Strategy Selection Decision Tree

Analyze the task and follow this tree:

START: What's the task?
│
├─ Single file, < 50 lines change?
│  └─ LEVEL 0: Direct edit. No parallelization needed.
│
├─ 1-3 files, independent changes?
│  └─ LEVEL 1: Single session + Subagents
│
├─ Multi-file, needs discussion/review?
│  ├─ Same feature, needs multiple perspectives?
│  │  └─ LEVEL 2: Single Worktree + Agent Team
│  └─ Multiple independent features?
│     └─ LEVEL 3: Multi-Worktree + optional Teams
│
├─ High-risk refactoring or architecture change?
│  └─ LEVEL 4: Plan Team → Execute Team (staged)
│
└─ Large project, needs build + break cycle?
   └─ LEVEL 5: Dual-Team Adversarial

Level Definitions

LEVEL 0 — Direct Edit

When: Trivial change, single file, obvious fix Setup: None Token cost: Minimal

LEVEL 1 — Single Session + Subagents

When: 2-5 independent subtasks, only results matter, no discussion needed Setup:

# No special setup. Use Task tool with subagents in current session.

Execution pattern:

1. •Break task into independent subtasks
2. •Dispatch one subagent per subtask via Task tool
3. •Collect results, verify no conflicts
4. •Integrate

Token cost: Low-Medium

LEVEL 2 — Single Worktree + Agent Team

When: One feature needing multiple perspectives (review, security audit, implementation) Setup:

# 1. Create worktree
git worktree add ../<project>-<feature> -b feature/<name>
cd ../<project>-<feature>

# 2. Start Claude session, then create team
claude
# In session: "Create a team with 3 teammates: implementer, tester, reviewer"

Team composition patterns:

Execution pattern:

1. •Lead creates team and assigns tasks
2. •Use Delegate Mode (Shift+Tab) to keep lead as coordinator
3. •Teammates claim tasks from shared task list
4. •Teammates can message each other directly
5. •Lead synthesizes results
6. •Cleanup: shut down teammates, then clean up team

Token cost: High (N teammates = N separate Claude instances)

LEVEL 3 — Multi-Worktree + Optional Teams

When: Multiple independent features or modules that can be developed in parallel Setup:

# Create isolated worktrees per feature
git worktree add ../<project>-auth -b feature/auth
git worktree add ../<project>-api -b feature/api
git worktree add ../<project>-ui -b feature/ui

# Each worktree gets its own Claude session
# Optionally, create a team within any worktree that needs collaboration

CLAUDE.md persona injection (CRITICAL for this level):

Create per-worktree CLAUDE.md to shape behavior:

# ../<project>-auth/CLAUDE.md
You are a security-focused engineer. Every code change must be evaluated
against OWASP Top 10. All auth tokens must use httpOnly cookies.
Reject any implementation that stores secrets in localStorage.

# ../<project>-api/CLAUDE.md
You are an API design expert. Follow RESTful conventions strictly.
Every endpoint must have OpenAPI spec. Use proper HTTP status codes.
Include rate limiting considerations in all public endpoints.

# ../<project>-ui/CLAUDE.md
You are a frontend specialist. Mobile-first responsive design.
Use shadcn/ui components. Accessibility (WCAG 2.1 AA) is non-negotiable.
Every interactive element needs keyboard navigation support.

Execution pattern:

1. •Create worktrees with meaningful names
2. •Inject domain-specific CLAUDE.md per worktree
3. •Start independent Claude sessions (or teams) in each
4. •Work proceeds in parallel, zero file conflicts between worktrees
5. •Merge branches when features are complete

Token cost: High to Very High

LEVEL 4 — Plan Team then Execute Team (Staged)

When: High-risk changes, architecture decisions, major refactoring Setup:

PHASE 1: Planning (Worktree A)
└── Team "architects" — ALL in Plan Mode
    ├── Teammate A: proposes approach 1
    ├── Teammate B: proposes approach 2
    └── Teammate C: proposes approach 3
    → Lead evaluates, picks best plan, writes to docs/plans/

PHASE 2: Execution (Worktree B)
└── Team "implementers" — Lead in Delegate Mode
    ├── Teammate: implements module 1 per plan
    ├── Teammate: implements module 2 per plan
    └── Teammate: writes tests per plan

Execution pattern:

1. •Create planning worktree and team with plan_mode_required
2. •Each teammate explores and proposes a different approach
3. •Teammates challenge each other's proposals
4. •Lead picks the winning plan and saves to docs/plans/
5. •Create execution worktree and new team
6. •Implementers follow the approved plan exactly
7. •Lead in Delegate Mode ensures no scope creep

Token cost: Very High (two full teams sequentially)

LEVEL 5 — Dual-Team Adversarial (Builder vs Breaker)

When: Production-critical code, needs maximum quality assurance Setup:

Worktree A: Team "builders"        Worktree B: Team "breakers"
├── Implementer x3                  ├── Security auditor
└── Integrator x1                   ├── Performance tester
                                    └── Edge-case finder

Flow: builders push → breakers pull & review → feedback → builders fix

Execution pattern:

1. •Builders implement features in worktree A
2. •Builders push branch when ready for review
3. •Breakers pull and systematically try to break the code
4. •Breakers report issues via shared doc or git notes
5. •Builders fix and push again
6. •Iterate until breakers can't find issues

Token cost: Extremely High

Infrastructure Layer (Apply to Any Level)

Hooks — Automatic Quality Gates

Add to .claude/settings.json for any level >= 1:

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "command": "npx eslint --fix $CLAUDE_FILE_PATH 2>/dev/null || true"
      }
    ]
  }
}

This runs lint automatically after every file write by any teammate.

Skills — Unified Output Protocol

Shared skills ensure all teammates follow the same standards:

~/.claude/skills/
├── api-endpoint/SKILL.md      → Standard API endpoint creation flow
├── component-scaffold/SKILL.md → Standard component creation flow
└── test-coverage/SKILL.md     → Standard test writing flow

All teammates in all worktrees inherit these skills automatically.

CLAUDE.md — Project-Level Rules

Top-level CLAUDE.md applies to ALL sessions and teammates:

# Project rules (applies everywhere)
- Run `npm test` before declaring any task complete
- Never commit directly to main
- All new functions need JSDoc comments

Per-worktree CLAUDE.md adds domain-specific rules on top.

Quick Selection Guide

Token Budget Guide

Choose the lowest level that achieves your goal. Over-parallelizing wastes tokens without proportional benefit.

Execution Checklist

Before starting any level >= 2:

• • Verify CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS is set to 1
• • Verify tmux is installed (if using split pane mode)
• • Define clear file ownership boundaries between teammates
• • Create per-worktree CLAUDE.md if using Level 3+
• • Configure hooks for automatic quality gates
• • Set up shared skills for output consistency
• • Pre-approve common permissions to reduce interruptions

Known Limitations to Account For

1. •Agent Teams are experimental — expect rough edges
2. •No session resume — /resume won't restore in-process teammates
3. •No nested teams — teammates cannot spawn sub-teams
4. •One team per session — clean up before creating a new team
5. •Lead is permanent — cannot transfer leadership
6. •Token cost scales linearly — each teammate is a full Claude instance
7. •Split panes need tmux/iTerm2 — VS Code terminal not supported
8. •Task status may lag — manually check if tasks appear stuck

Common Mistakes

Choosing too high a level:

• •3 bugs in one file? Level 0, not Level 2
• •Simple feature add? Level 1, not Level 3

Teammates editing same files:

• •ALWAYS assign clear file ownership boundaries
• •Two teammates on src/auth.ts = guaranteed conflicts

Forgetting Delegate Mode:

• •Lead starts implementing instead of coordinating
• •Fix: Shift+Tab to enable Delegate Mode

Not cleaning up teams:

• •Always shut down teammates before cleanup
• •Always use the lead (not a teammate) to run cleanup

Skipping infrastructure layer:

• •Hooks + Skills + CLAUDE.md cost nothing but prevent many issues
• •Set these up BEFORE creating teams

Integration

Pairs with:

• •superpowers:using-git-worktrees — REQUIRED for Level 3+
• •superpowers:brainstorming — RECOMMENDED before Level 4+
• •superpowers:writing-plans — REQUIRED for Level 4
• •superpowers:dispatching-parallel-agents — Alternative to Level 1 with subagents
• •superpowers:test-driven-development — RECOMMENDED for all levels
• •superpowers:requesting-code-review — RECOMMENDED at completion

Called by:

• •Any task analysis that determines parallelization would help
• •CLAUDE.md quick decision matrix