squad-execute
/squad-execute
Spawn a full squad of worktree-isolated Claude Code agents to execute a spec or epic. Includes staff engineers, QA sentinel, optional Product/UIUX reviewer, and optional code reviewer. The invoking agent stays in coordinator mode. Use when the user says "spin up a team", "squad execute", "execute this epic with a team", "spawn engineers for this", "staff up", "build a team for this", "run this with agents", "deploy a squad", "get engineers on this", "execute with a crew", or wants parallel multi-agent execution of planned work. Also matches "launch team", "start squad", "kick off execution", a
- Author
- lupusdei ↗
- Repository
- adjutant ↗
- Licence
- MIT
- Last repository change
- 02.09.2026
Assessment and security
- Files in this package
- 2
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 0
No signals detected. Repository changed on 02.09.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
Spawn a full squad of worktree-isolated Claude Code agents to execute a spec or epic. Includes staff engineers, QA sentinel, optional Product/UIUX reviewer, and optional code reviewer. The invoking agent stays in coordinator mode. Use when the user says "spin up a team", "squad execute", "execute this epic with a team", "spawn engineers for this", "staff up", "build a team for this", "run this with agents", "deploy a squad", "get engineers on this", "execute with a crew", or wants parallel multi-agent execution of planned work. Also matches "launch team", "start squad", "kick off execution", a
Triggers from the description
Original author description
Spawn a full squad of worktree-isolated Claude Code agents to execute a spec or epic. Includes staff engineers, QA sentinel, optional Product/UIUX reviewer, and optional code reviewer. The invoking agent stays in coordinator mode. Use when the user says "spin up a team", "squad execute", "execute this epic with a team", "spawn engineers for this", "staff up", "build a team for this", "run this with agents", "deploy a squad", "get engineers on this", "execute with a crew", or wants parallel multi-agent execution of planned work. Also matches "launch team", "start squad", "kick off execution", a
How it works
- Usage
- Pre-Requisites
- Instructions
- Key Rules
- Spawn Sequencing
- Squad Size Guidelines
SKILL.md preview
---
name: squad-execute
description: Spawn a full squad of worktree-isolated Claude Code agents to execute a spec or epic. Includes staff engineers, QA sentinel, optional Product/UIUX reviewer, and optional code reviewer. The invoking agent stays in coordinator mode. Use when the user says "spin up a team", "squad execute", "execute this epic with a team", "spawn engineers for this", "staff up", "build a team for this", "run this with agents", "deploy a squad", "get engineers on this", "execute with a crew", or wants parallel multi-agent execution of planned work. Also matches "launch team", "start squad", "kick off execution", and any request involving multiple agents working on an epic or spec simultaneously.
---
# 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
```bash
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:
```bash
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:
```bash
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:
```bash
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):
```bash
# 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:
```bash
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>" })
```
6. 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 |
Files in this package (2)
- SKILL.md 18 KB
- squad-member-context.md 5 KB
Versions
| Repository | Score | Licence |
|---|---|---|
| This page · lupusdei/adjutant | 98 | MIT |
| lupusdei/adjutant | 98 | MIT |
Database snapshot: 13.11.2026 · package version c7defe6e48ab (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100wizard
Goal-first squad setup and launch for amq-squad 3.0 through the squad.yaml digest flow. Use when creating a squad for a repository, writing the workstream brief, previewing the files a squad needs, approving that exact digest, or launching the seats. Triggers include \"set up a… - 100build-agent-team
Designs a long-running, autonomous Claude Code agent team for the current project, then writes a /start-<team>-team skill that spawns it. Use when the user asks to build an agent team, multi-agent system, agent crew, agent squad, agent fund, agent org, or wants multiple agents… - 90virtual-engineering-team
Run a product-engineering squad of agents from spec to shipped change with a PM, an architect, two engineers, a reviewer, and QA. Use when a task is too large for one agent and needs both division of labor and an independent quality gate. - 100squad-agents
Build AI agent teams that collaborate on projects using Squad framework. Use when: orchestrating multiple specialized agents, building collaborative AI workflows, delegating complex tasks across agent teams. - 100wizard
Goal-first setup and launch through the deterministic amq-squad wizard verb. Use when creating a team/profile, starting a new session from a reusable profile, previewing a launch, or approving that reviewed launch. Triggers include \"set up a squad for X\", \"show me the launch… - 100cross-squad
Coordinating work across multiple Squad instances — discovery, delegation, and disambiguation when the user says 'squad' (the product) vs casual English 'group of agents'.