squad-execute

Squad Execute

Orchestrate a full squad of Claude Code native agents to execute a spec or epic in parallel. You are the coordinator — you spawn, monitor, and report.

Usage

/squad-execute <epic-id-or-spec-path>

Examples:

• /squad-execute adj-072
• /squad-execute specs/041-proposal-project-scoping/

Pre-Requisites

Before invoking this skill, the work MUST already be planned:

• An epic with sub-epics and tasks exists in beads (bd show <epic-id>)
• OR a spec directory exists with tasks.md and beads-import.md

If neither exists, tell the user to run /epic-planner first. Do NOT plan and execute in the same skill invocation.

Instructions

Step 1: Assess the Work

1. Load the epic — run bd show <epic-id> to see the full hierarchy, dependencies, and status
2. Identify parallel tracks — group tasks by sub-epic or phase. Tasks within different sub-epics that have no cross-dependencies are parallel tracks
3. Count ready work — run bd ready to see unblocked tasks
4. Read the spec if a spec path was provided — check tasks.md for [P] markers indicating parallelizable tasks

Step 2: Determine Squad Composition

Based on the work assessment, determine how many agents to spawn:

Staff Engineers (1-8, REQUIRED)

• 1 engineer per parallel track — never assign two engineers to the same sequential chain
• If 3 sub-epics can run in parallel, spawn 3 engineers
• If 8 independent tasks exist, spawn up to 8 engineers
• If all tasks are sequential, spawn 1 engineer
• Rule: number of engineers = number of parallel tracks, capped at 8

QA Sentinel (1, REQUIRED)

Always spawn exactly one QA sentinel. They:

• Review code being written by engineers as it merges to main
• Look for bugs, missed edge cases, and spec adherence
• Create bead bugs (type=bug) under the epic for anything found
• Run after the first engineer merges, not before

Product/UIUX Reviewer (0-1, OPTIONAL)

Spawn when the epic includes:

• Frontend components (React, CSS, UI changes)
• iOS views or SwiftUI changes
• User-facing workflow changes
• Design or usability requirements in the spec

Skip when the work is purely backend, infrastructure, or internal tooling.

Code Reviewer (0-1, OPTIONAL — default spawn)

Spawn by default unless:

• The epic has fewer than 3 tasks total
• The work is trivial (config changes, doc updates, simple wiring)

They:

• Review code quality, test coverage, and test reliability
• Focus on fundamentals: naming, structure, error handling, edge cases
• Create bead tasks (type=task) for improvements under the epic

Step 3: Self-Assign as Coordinator

bd update <epic-id> --assignee=<your-name> --status=in_progress

Report to the user:

set_status({ status: "working", task: "Coordinating squad for <epic-title>" })
send_message({ to: "user", body: "Squad Execute: <epic-title>\n\nSquad composition:\n- Engineers: N (tracks: <list>)\n- QA Sentinel: 1\n- Product/UIUX: yes/no (reason)\n- Code Reviewer: yes/no (reason)\n\nSpawning now." })

Step 4: Assign Beads Before Spawning

For each agent, assign their beads BEFORE spawning them:

bd update <bead-id> --assignee=engineer-1 --status=in_progress
bd update <bead-id> --assignee=engineer-2 --status=in_progress
# etc.

QA sentinel, product reviewer, and code reviewer don't get pre-assigned beads — they create their own as they find issues.

Step 5: Spawn Engineers

Spawn each engineer using Claude Code's native Agent tool with isolation: "worktree" and run_in_background: true.

CRITICAL: Use the Agent tool (Claude Code native teammates), NOT spawn_worker (Adjutant MCP). Adjutant's spawn_worker creates tmux-managed sessions that count against the MAX_SESSIONS cap and inherit Adjutant project context. Claude Code native agents are lightweight, isolated, and don't consume session slots.

Parallel execution: All engineers that can work in parallel MUST be spawned with run_in_background: true so they run concurrently as independent background agents. Do NOT spawn them as foreground sub-agents (which would serialize). You will be notified when each background agent completes — do not poll or sleep waiting for them.

Spawning pattern:

Agent tool call 1: { name: "engineer-1", isolation: "worktree", run_in_background: true, prompt: "..." }
Agent tool call 2: { name: "engineer-2", isolation: "worktree", run_in_background: true, prompt: "..." }
Agent tool call 3: { name: "engineer-3", isolation: "worktree", run_in_background: true, prompt: "..." }
// Send ALL parallel agents in a SINGLE message with multiple Agent tool calls

Launch all parallel-track engineers in the same message so they start simultaneously.

Every engineer spawn prompt MUST include:

1. The project constitution — read constitution.md from the project root and include its FULL TEXT in the spawn prompt. Label it:

## Project Constitution (MANDATORY — obey every rule, reject work that violates any rule)

<full contents of constitution.md>

If constitution.md does not exist, skip this step (proceed without).

Role-specific enforcement:

• Staff Engineers enforce Rules 1 (Test-First) and 3 (Build Verification) — tests before code, build before commit
• QA Sentinel enforces ALL rules — they are the constitution's guardian
• Code Reviewers enforce Rules 2 (Type Safety), 4 (Layered Architecture), and 5 (Agent Communication)

2. The Layer 4 preamble:

## Your Role (Layer 4: Squad Member)
You are <name>, a Squad Member on <squad-leader>'s team.
- Your specialization: Staff Engineer
- Your name (for --assignee): <agent-name>
- Your assigned beads: <list their bead IDs>
- Parent epic: <epic-id>

3. Read the squad member protocol file into the spawn prompt:

Read skills/squad-execute/squad-member-context.md and include its contents verbatim in the spawn prompt.

This file contains task tracking, MCP communication, verification, and question routing — all the protocol a Layer 4 agent needs in a compact format.

4. Additionally include:

• The specific task descriptions from the spec/bead
• File paths they'll be working on
• Any dependencies they must wait for (e.g., "wait until adj-072.1 merges before starting")

Step 6: Spawn QA Sentinel

Spawn after the first engineer starts merging work. Use Claude Code's native Agent tool with isolation: "worktree" and run_in_background: true.

QA Sentinel spawn prompt template:

Include the full project constitution (from constitution.md) at the top of the QA sentinel's spawn prompt, using the same label as engineers. QA sentinels enforce ALL constitutional rules.

## Project Constitution (MANDATORY — obey every rule, reject work that violates any rule)
<full contents of constitution.md>

---

You are a QA sentinel for epic <epic-id>: <title>.

Your job:
1. Wait for engineers to merge work to main
2. Pull main and review the changes against the spec
3. Run the full test suite: npm test
4. Run coverage check: npm run test:coverage — verify thresholds (80% lines, 70% branches, 60% functions)
5. Check test quality: tests must verify behavior, not implementation. No brittle mocks. Mock data must use real CLI output shapes (see 03-testing.md adj-067 lesson).
6. Check edge cases the spec mentions but tests don't cover
7. For each bug or gap found, create a bead:
   bd create --id=<epic-id>.N.M.P --title="Bug: <description>" --type=bug --priority=<1-3>
   bd dep add <parent-bead> <new-bug-id>
6. Report findings via: send_message({ to: "user", body: "QA found: <summary>" })

Spec location: <spec-path>
Epic: <epic-id>

<Include the Task Tracking and Question Routing blocks from Step 5>

Step 7: Spawn Optional Reviewers

Spawn all reviewers using Claude Code's native Agent tool with isolation: "worktree" and run_in_background: true. Launch QA + reviewers in the same message if spawning together.

Product/UIUX Reviewer

Include the full project constitution at the top (same label). Product reviewers focus on user-facing quality.

## Project Constitution (MANDATORY — obey every rule, reject work that violates any rule)
<full contents of constitution.md>

---

You are a Product/UIUX reviewer for epic <epic-id>: <title>.

Your job:
1. Read the spec at <spec-path>, focusing on user stories and acceptance criteria
2. As engineers merge UI changes, review them for:
   - Does the implementation match the spec's intent?
   - Is the UX intuitive? Are there confusing flows?
   - Does it follow the project's design system/theme?
   - Are accessibility requirements met?
3. For each issue found, create a bead:
   bd create --id=<epic-id>.N.M.P --title="UX: <description>" --type=task --priority=<1-3>
   bd dep add <parent-bead> <new-task-id>
4. Report via: send_message({ to: "user", body: "Product review: <summary>" })

<Include the Task Tracking and Question Routing blocks from Step 5>

Code Reviewer

Include the full project constitution at the top (same label). Code reviewers enforce Rules 2 (Type Safety), 4 (Layered Architecture), and 5 (Agent Communication).

## Project Constitution (MANDATORY — obey every rule, reject work that violates any rule)
<full contents of constitution.md>

---

You are a staff-level code reviewer for epic <epic-id>: <title>.

Your job:
1. As engineers merge to main, review the code with a staff engineer's eye
2. Check for:
   - Code quality: naming, structure, readability, DRY
   - Test coverage: are critical paths tested? Are edge cases covered? Run npm run test:coverage and verify thresholds (80% lines, 70% branches, 60% functions)
   - Test reliability: are tests deterministic? Do they test behavior, not implementation? Are mocks using real data shapes from CLI output (not hand-crafted from TS types — see 03-testing.md adj-067 lesson)?
   - Test quality: minimum test counts met per 03-testing.md (3 per service method, 2 per MCP tool, 3 per hook, 2 per endpoint, 1 per bug fix)?
   - Error handling: are failure modes handled gracefully?
   - Security: any injection risks, data leaks, or auth bypasses?
3. For each improvement needed, create a bead:
   bd create --id=<epic-id>.N.M.P --title="Review: <description>" --type=task --priority=<2-3>
   bd dep add <parent-bead> <new-task-id>
4. Report via: send_message({ to: "user", body: "Code review: <summary>" })

<Include the Task Tracking and Question Routing blocks from Step 5>

Step 8: Monitor and Report

While the squad works, the coordinator (you) must:

1. Check progress regularly — every 2-3 minutes, check bd list --status=in_progress and agent statuses via list_agents()
2. Report milestones — when a sub-epic completes, a phase finishes, or a reviewer finds issues:

   send_message({ to: "user", body: "Squad update: <what happened>" })
   report_progress({ task: "<epic-id>", percentage: N, description: "<status>" })
   

3. Unblock agents — if an agent reports a blocker, investigate and help resolve it
4. Close sub-epics — when all tasks under a sub-epic are closed, close the sub-epic:

   bd close <sub-epic-id>
   

5. Do NOT do implementation work yourself — your job is coordination only

Step 9: Handle Reviewer Findings

When QA, Product, or Code Review agents create bug/task beads:

1. The reviewer creates the bead under the epic with proper parent wiring

2. You (coordinator) decide: assign to an existing engineer who is finishing up, or note it for a follow-up pass

3. If an engineer is still actively running in its worktree, assign the fix:

   bd update <bug-id> --assignee=<engineer-name>
   

   Then notify the engineer via send_message({ to: "<engineer-name>", body: "New fix assigned: <bug-id> — <description>" })

   ⚠️ WORKTREE RESUME HAZARD (adj-c2bbv) — do NOT send_message/SendMessage a worktree agent that has already completed/reported done to make it edit more files. Resuming a finished background worktree agent wakes it in the main repo cwd (NOT its worktree), so its Bash file ops silently leak into the shared tree — the adj-iqyqw data-loss mode. Instead, spawn a fresh worktree agent for the follow-up fix (isolation: "worktree"). Only message agents that are still mid-task (never reported done). If you absolutely must resume a finished agent, instruct it in the message to cd <its-worktree> && before EVERY Bash command and to verify git status in the main repo stays clean.

4. If all engineers are done, spawn a fresh worktree agent for the fix, or leave the bugs open for a follow-up squad / manual fix. Do NOT resume a done agent to edit files (see the hazard above).

Step 10: Wrap Up

When all engineer tasks are closed and reviewer findings are either fixed or documented:

1. Merge all agent branches to main from the main repo (not a worktree):

   # For each engineer's branch:
   git fetch origin
   git checkout main && git pull origin main
   test "$(git branch --show-current)" = main || { echo "ABORT: not on main (adj-laz97)"; exit 1; }  # verify BEFORE merge
   git merge origin/<engineer-branch>
   npm run build && npm test              # Verify after each merge
   test "$(git branch --show-current)" = main || { echo "ABORT: not on main (adj-laz97)"; exit 1; }  # verify BEFORE push
   git push origin main
   

   Use git branch -r --no-merged main to confirm no agent branches are left unmerged.

   Why the --show-current guards (adj-laz97): a worktree agent whose cwd leaked to the main repo can run git checkout -b and silently move main's HEAD onto a stray branch. Then your git merge lands on the stray branch and git push origin main reports "up-to-date" while main is wrong. The guards catch it before the merge/push.

2. Close the root epic if all children are done:

   bd close <epic-id> --reason="All phases complete"
   

3. If reviewer bugs remain open, leave the epic open and report:

   send_message({ to: "user", body: "Squad complete for <epic-title>.\n\nResults:\n- Tasks closed: N/M\n- QA bugs found: X (Y fixed, Z remaining)\n- Code review items: X (Y fixed, Z remaining)\n- Product issues: X (Y fixed, Z remaining)\n\nRemaining items need follow-up." })
   

4. Final announcement:

   announce({ type: "completion", title: "Squad complete: <title>", body: "<summary>", beadId: "<epic-id>" })
   set_status({ status: "done", task: "Squad complete: <epic-title>" })
   

5. Clean up worktrees — verify all agent branches are merged (git branch -r --no-merged main should return empty), then remove stale worktrees

Key Rules

• Use Claude Code native Agent tool for ALL spawning — NEVER use spawn_worker (Adjutant MCP)
• ALWAYS use isolation: "worktree" for every agent that edits files — no exceptions
• NEVER SendMessage-resume a COMPLETED worktree agent to edit files (adj-c2bbv) — a resumed background worktree agent runs in the main repo cwd, so its file edits silently leak out of the worktree (data loss). Spawn a fresh worktree agent for follow-up work instead. Only message agents still mid-task. If a resume is unavoidable, the message MUST tell the agent to cd <its-worktree> && before every Bash call and verify the main-repo git status stays clean.
• Worktree agents must NEVER git checkout -b or switch branches (adj-laz97) — they are ALREADY on their worktree branch; they commit and git push -u origin HEAD. If an agent's cwd has leaked to the main repo (non-isolated spawn or a resumed turn), a stray git checkout -b moves the main repo's HEAD onto a new branch, so your later git merge lands on the stray branch and git push origin main reports "up-to-date" while main is silently wrong. Put "never create/switch branches; push HEAD" in EVERY engineer spawn prompt.
• Coordinator: verify you are on main BEFORE every merge and push (adj-laz97) — run git branch --show-current (must print main) and confirm git rev-parse HEAD is the commit you expect. This catches a silent HEAD move before it corrupts the merge target. (This is how the adj-laz97 incident was caught and recovered with zero loss.)
• NEVER do implementation work as coordinator — delegate everything
• Assign beads BEFORE spawning — agents must know their work upfront
• All communication via Adjutant MCP — not stdout, not AskUserQuestion
• QA sentinel is mandatory — never skip it, even for small epics
• Reviewers create their own beads — they wire them under the epic hierarchy
• Engineers must build + test + check coverage before merging — the spawn prompt enforces this
• All squad members must verify before pushing — run npm run build, npm test, and npm run test:coverage before every push
• Report to user at every milestone — silence is not acceptable

Spawn Sequencing

For epics with dependencies between phases:

1. Spawn Phase 1 engineers immediately
2. Spawn QA sentinel after first Phase 1 merge
3. Spawn Phase 2+ engineers only after their dependencies merge to main
4. Spawn product/code reviewers after the first substantial merge

This prevents stale-branch conflicts (adj-yzvk: agents branching before dependencies land).

Squad Size Guidelines

Epic Size	Engineers	QA	Product	Code Review
Small (1-3 tasks)	1	1	No	No
Medium (4-8 tasks, 2-3 tracks)	2-3	1	If UI	Yes
Large (9-15 tasks, 3-5 tracks)	3-5	1	If UI	Yes
XL (16+ tasks, 5+ tracks)	5-8	1	If UI	Yes