team

What this skill does

# Team (Coordinated Sub-Agent Implementation)

Spawn a coordinated sub-agent team to implement a spec or multi-task feature. The main session (you) acts strictly as coordinator — no code, no commits, only delegation and quality control.

## ⛔ Critical Architecture Rule: Coordinator Owns the SDLC

**Sub-agents CANNOT spawn their own sub-agents.** If you tell a teammate to "run the full SDLC," it will try to do implementation inline (instead of delegating to a coder sub-agent), bloat its context window, and skip later steps like Copilot review. This has been observed in production.

**Therefore: YOU (the coordinator) orchestrate each SDLC step per task.** You spawn focused, single-purpose agents for each step and handle cross-cutting concerns (Copilot review, CI, merge gates) directly.

**Never tell an agent to "load the dev skill and follow all steps." Instead, give each agent ONE focused job.**

---

## STEP 0: Understand the Work

1. **If given a spec file path:** Read it to extract all tasks.
2. **If given an issue URL:** Fetch it with `gh issue view`.
3. **If given a description:** Break it into discrete, parallelizable tasks.

Identify:
- Total tasks and their dependencies
- Which tasks can run in parallel vs. which must be sequential
- A sensible task grouping (1 coder agent can own 1-3 related tasks)

### Do NOT pause to confirm scope on clearly-scoped requests (BLOCKING)

When the user's invocation is unambiguous — e.g. `implement all pending changes fully`, `ship all of these`, `do everything in docs/changes/`, a concrete list of PR numbers, or a single spec file — **treat that as the authoritative scope and proceed immediately to Step 1**. Do NOT pause to ask "should I do all 6 now or just wave 1 first to sanity-check?" Do NOT report `failure` to the Coder dashboard asking for scope confirmation when the user already gave it. Words like "all", "fully", "every", "the whole list" are explicit scope — honor them.

**You can still split execution into waves internally.** Wave-based execution (Wave 1: independent tasks in parallel; Wave 2: their dependents once unblocked; etc.) is the correct way to run a multi-PR team, and you should plan it that way. The rule is about **not stopping to ask the user** whether to do waves or which wave to start with — just plan the waves and execute them.

> **⛔ Waves are an INTERNAL execution concept — they MUST NEVER leak into a PR title (BLOCKING).** A wave/phase/step number is not a PR or issue. A `#<number>` in a PR title (`#4`, `(#4)`, `#123`) looks like plain text in the title bar, but on squash-merge the title becomes the commit subject, where `#N` auto-links to PR/issue #N in the repo. Writing `(#4)` to mean "wave 4" wrongly cross-links the merged commit (and PR) to whatever PR/issue #4 is — this has happened repeatedly and is exactly what we are stamping out. When you spawn coders and when you author/verify titles before merge:
> - **No `#<number>` in any PR title** unless N is a real, existing PR/issue on the target repo that the PR actually references. Never pre-add a `(#N)` suffix — GitHub appends the real PR number at squash-merge time.
> - **No "Wave N", "Phase N", "Step N", batch/iteration labels, or change-doc numbers in titles.** They belong in the PR body only.
> - **Gate-check this before merge:** if a PR title contains a stray `#N` or wave/phase wording, rename it with `gh pr edit <N> --title "..."` before merging. A squash merge bakes the title into `main`'s history — a wrong cross-link there is permanent. See the `fx-dev:github` skill's "`#<number>` PR-Title Rule".

**Reserve confirmation for genuine ambiguity only:**
- Conflicting instructions ("ship 0051 — actually wait, also 0055?")
- Vague scope ("clean up the changes folder" without saying which)
- Destructive operations not implied by the request (deleting branches, force-pushing, dropping data)

If you find yourself drafting a "before I burn that compute, one quick check…" message in response to a clearly-scoped instruction, stop. Delete the draft. Spawn the team.

## STEP 1: Create the Team

```
TeamCreate tool:
  team_name: "<short-kebab-name>"  # e.g., "auth-feature", "admin-ui"
  description: "<what the team is building>"
```

## STEP 2: Create and Organize Tasks

Use `TaskCreate` for every task identified in Step 0. Set up dependencies with `TaskUpdate` (`addBlockedBy`/`addBlocks`) so work proceeds in the correct order.

**Task descriptions MUST include:**
- Exactly what to implement (files, components, endpoints)
- Acceptance criteria
- Which spec task(s) it maps to (if from a spec)

## STEP 2.5: Worktree Isolation Setup (MANDATORY for concurrent coders)

**Why this step exists:** `isolation: "worktree"` on the Agent tool does nothing for team members (it is silently ignored when `team_name` is set — see STEP 3). Without real isolation, every concurrent coder shares the coordinator's single working tree and git HEAD and they corrupt each other. The coordinator MUST pre-create one git worktree per coder that will run concurrently, each on its own branch, and pin each teammate to its worktree via a prompt preamble.

**Skip this step only if you will run coders strictly one-at-a-time** (fully sequential, never two coders alive at once). In that single-writer case the shared tree is safe. The moment you want parallelism, this step is required.

### 2.5.1 Create one worktree per concurrent coder

Worktrees **MUST** live under the repo's own `.claude/worktrees/` directory — this matches Claude Code's native worktree convention, keeps them inside the (writable) repo, and survives a read-only parent filesystem. **NEVER** put them in `/tmp`, `$HOME`, or a sibling path outside the repo.

```bash
cd <REPO_ROOT>
git fetch origin --quiet
mkdir -p .claude/worktrees
# one per coder — name the worktree after the task/change, branch off origin/main
git worktree add .claude/worktrees/<slug> -b <branch> origin/main
# e.g. git worktree add .claude/worktrees/0004 -b refactor/0004-unified-config-service origin/main
```

**Ensure `.claude/worktrees/` is ignored** before creating any (most projects already ignore `.claude/`, but verify — this one may not). A nested worktree dir otherwise shows up as untracked in the main repo and can get swept into a coder's `git add`. Use the repo-local, **untracked** `.git/info/exclude` so this scaffolding never dirties the coordinator's working tree or risks landing in a feature PR — do NOT append to the tracked `.gitignore`:

```bash
git check-ignore .claude/worktrees/x >/dev/null 2>&1 || \
  printf '\n# Claude Code team worktrees (local only)\n.claude/worktrees/\n' >> .git/info/exclude
```

`.git/info/exclude` is never committed, so there is nothing to clean up later and `git status` stays clean.

**Symlink `node_modules`** (and any other gitignored, install-only dir the toolchain needs) into each worktree so `vitest`/`biome`/`tsc` resolve — a fresh worktree has no `node_modules`:

```bash
ln -s <REPO_ROOT>/node_modules <REPO_ROOT>/.claude/worktrees/<slug>/node_modules
```

### 2.5.2 Smoke-test isolation BEFORE spawning real coders

Spawn ONE cheap probe teammate pinned to a worktree. Have it write a marker file in the worktree and confirm (a) the marker is **absent** in the main repo, (b) `pwd`/branch/toplevel are the worktree's, then clean up. Only proceed once it reports isolation OK. This catches a broken setup before any real code is written. (If the probe lands in the main repo, the workaround failed — stop and re-check paths.)

A confirmed gotcha: **the teammate's shell cwd RESETS to the main repo root after EVERY bash command** ("Shell cwd was reset to …"). That is exactly why the preamble below forces an absolute `cd` on every command — relative paths silently resolve against the MAIN repo, not the worktree.

### 2.5.3 Pin each coder to its worktree (prompt preamble)

Every coder/verify/fix teammate that must operate in a worktree **MUST** have its spawn `prompt` START with this preamble (substitute t