/sc-parallel-worktree-team

name: sc-parallel-worktree-team
description: Parallelize work across agent teams using git worktrees and tmux
argument-hint: "[description of work to parallelize]"

Parallel Worktree Team

Analyze the requested work by entering Plan Mode, then decompose it into parallelizable streams, then execute them simultaneously using git worktrees for isolation and Agent Teams within Tmux for coordination.

Prerequisites

Agent Teams is an experimental feature. The user's session must have been started with `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1` set in the environment, otherwise `TeamCreate`, `SendMessage`, and team-aware `Agent` spawning will be unavailable. If team tools fail with "tool not found", stop and tell the user to relaunch Claude Code with that env var.

Input

$ARGUMENTS

Phase 1: Analyze and Decompose

Produce a **decomposition artifact** that Phase 2 and Phase 5 consume mechanically. Do this work inside Plan Mode so the user approves the artifact before any worktree or team is created.

Step 1: Read project context

1. Read the project's CLAUDE.md for conventions, the build/check/test/lint commands, and commit rules. 2. Explore the codebase enough to know — for each candidate stream — the exact paths that will be created or modified.

Step 2: Classify every cross-stream dependency

For every pair of streams where one references the other, classify the dependency as exactly one of the following types. The type determines merge ordering in Phase 5 and the `blocked_by` wiring in Phase 2.

• **type/interface** — Stream B imports types, interfaces, or generated bindings that Stream A defines (or vice versa). A must merge before B.
• **data/file-write** — Stream B reads files that Stream A writes (fixtures, schemas, generated assets, migrations). A must merge before B.
• **build/compile** — Stream B's build, bundler, or compiler resolves symbols exported by Stream A. A must merge before B.
• **test-only** — Stream B's tests reference Stream A's public API but Stream B's production code does not. Either order is acceptable **only if** the test fixtures are isolated to B's stream; otherwise treat as type/interface and sequence A first.
• **none** — Stream is foundational; no cross-stream dependency.

Step 3: Apply overlap-detection rules

Apply these rules literally. They are not heuristics.

1. **Two streams overlap if they modify the same file.** 2. **Overlap is acceptable only when one stream is strictly additive** — append-only changes such as adding new exports, new test cases, or new entries to a registry — and the other stream does not also rewrite the additive region. 3. **Otherwise, overlapping streams MUST take one of three remediations:**

• sequence them via `blocked_by` (one merges first),
• merge them into a single stream, or
• split the shared surface into a foundational stream that both depend on and that merges first.

4. **Streams that touch shared symbols** (types, constants, interfaces, public exports) **in non-additive ways MUST NOT run in parallel.** Promote the shared surface into a foundational stream.

Step 4: Emit the decomposition artifact

For each stream (target 2-4 streams), emit one fenced yaml block with exactly these fields:

- name: <short-name>                      # used for branch and worktree naming; kebab-case
  files_modified: [<path>, <path>]        # files this stream edits in place
  files_created: [<path>]                 # files this stream creates from scratch
  blocked_by: [<stream-name>, ...]        # other stream names that must merge first; [] if foundational
  dependency_type: type/interface | data/file-write | build/compile | test-only | none
  deliverables: <one line describing what ships from this stream>
  verify_cmd: <the project's check/test/lint command scoped to this stream>

Rules for the artifact:

• `blocked_by` entries reference other `name` values from this same artifact — never task IDs (those don't exist yet) and never file paths.
• If `blocked_by` is non-empty, `dependency_type` MUST be one of the non-`none` types and MUST justify the ordering (e.g. `type/interface` is why A blocks B).
• If `blocked_by` is `[]`, `dependency_type` MUST be `none`.
• Every file in `files_modified` and `files_created` is owned by exactly one stream unless overlap is justified per Step 3 rule #2.

Step 5: Present for approval

Present the full set of yaml blocks to the user inside the plan. Do not exit Plan Mode and do not proceed to Phase 2 until the user approves the decomposition.

Phase 2: Set Up Infrastructure

Create worktrees

One worktree per stream, branched from the current branch:

PARENT_BRANCH=$(git branch --show-current)
mkdir -p .worktrees
git worktree add .worktrees/<stream-name> $PARENT_BRANCH -b <stream-branch>

Symlink dependencies

Each worktree needs access to installed packages:

eg. for npm projects:

ln -sf "$(pwd)/node_modules" ".worktrees/<stream-name>/node_modules"

Other language ecosystems require appropriate and equivalent package symlinking.

Also symlink any other shared directories the project needs (check CLAUDE.md for patterns).

Create team

Call the `TeamCreate` tool with `team_name: <descriptive-name>` (required) and `description: <what we're doing>`. With `teammateMode: "tmux"` configured in the user's settings, each spawned agent gets its own tmux pane for live visibility.

Create tasks from the decomposition artifact

Walk the Phase 1 artifact in order. For each stream entry:

1. Call `TaskCreate` with `subject` set to the stream `name` and `description` set to its `deliverables` (both required). Record the returned task ID against the stream `name` so you can resolve names to IDs in the next step. 2. After every stream has a task ID, walk the artifact a second time. For each stream entry whose `blocked_by` list is non-empty, call `TaskUpdate` with `taskId` set to that stream's task ID and `addBlockedBy` se