From adjutant-agent
Spawns squad of worktree-isolated Claude Code agents including staff engineers, QA sentinel, and optional reviewers to execute planned epics or specs in parallel. Use for multi-agent coordination.
npx claudepluginhub lupusdei/adjutant --plugin adjutant-agentThis skill uses the workspace's default tool permissions.
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.
Guides Next.js Cache Components and Partial Prerendering (PPR): 'use cache' directives, cacheLife(), cacheTag(), revalidateTag() for caching, invalidation, static/dynamic optimization. Auto-activates on cacheComponents: true.
Processes PDFs: extracts text/tables/images, merges/splits/rotates pages, adds watermarks, creates/fills forms, encrypts/decrypts, OCRs scans. Activates on PDF mentions or output requests.
Share bugs, ideas, or general feedback.
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.
/squad-execute <epic-id-or-spec-path>
Examples:
/squad-execute adj-072/squad-execute specs/041-proposal-project-scoping/Before invoking this skill, the work MUST already be planned:
bd show <epic-id>)tasks.md and beads-import.mdIf neither exists, tell the user to run /epic-planner first. Do NOT plan and execute in the same skill invocation.
bd show <epic-id> to see the full hierarchy, dependencies, and statusbd ready to see unblocked taskstasks.md for [P] markers indicating parallelizable tasksBased on the work assessment, determine how many agents to spawn:
Always spawn exactly one QA sentinel. They:
type=bug) under the epic for anything foundSpawn when the epic includes:
Skip when the work is purely backend, infrastructure, or internal tooling.
Spawn by default unless:
They:
type=task) for improvements under the epicbd 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." })
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.
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:
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:
## 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>
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.
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>
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.
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>
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>
While the squad works, the coordinator (you) must:
bd list --status=in_progress and agent statuses via list_agents()send_message({ to: "user", body: "Squad update: <what happened>" })
report_progress({ task: "<epic-id>", percentage: N, description: "<status>" })
bd close <sub-epic-id>
When QA, Product, or Code Review agents create bug/task beads:
bd update <bug-id> --assignee=<engineer-name>
Then notify the engineer via send_message({ to: "<engineer-name>", body: "New fix assigned: <bug-id> — <description>" })When all engineer tasks are closed and reviewer findings are either fixed or documented:
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
git merge origin/<engineer-branch>
npm run build && npm test # Verify after each merge
git push origin main
Use git branch -r --no-merged main to confirm no agent branches are left unmerged.
Close the root epic if all children are done:
bd close <epic-id> --reason="All phases complete"
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." })
Final announcement:
announce({ type: "completion", title: "Squad complete: <title>", body: "<summary>", beadId: "<epic-id>" })
set_status({ status: "done", task: "Squad complete: <epic-title>" })
Clean up worktrees — verify all agent branches are merged (git branch -r --no-merged main should return empty), then remove stale worktrees
spawn_worker (Adjutant MCP)isolation: "worktree" for every agent that edits files — no exceptionsnpm run build, npm test, and npm run test:coverage before every pushFor epics with dependencies between phases:
This prevents stale-branch conflicts (adj-yzvk: agents branching before dependencies land).
| 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 |