Skip to content
Skills Library
AI & agents · Automation

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

Repository
adjutant ↗
Licence
MIT
Last repository change
02.09.2026

Assessment and security

98/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene13 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
2
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 02.09.2026, without references to retired models or APIs.

Licence

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

spin up a teamsquad executeexecute this epic with a teamspawn engineers for thisstaff upbuild a team for thisrun this with agentsdeploy a squad
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

  1. Usage
  2. Pre-Requisites
  3. Instructions
  4. Key Rules
  5. Spawn Sequencing
  6. Squad Size Guidelines
Original SKILL.md headings · 356 lines, 2,707 words
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

RepositoryScoreLicence
This page · lupusdei/adjutant98MIT
lupusdei/adjutant98MIT

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'.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.