// Multi-agent team workflow for implementing tickets with peer-to-peer communication inside a single shared team. Used by chat-orchestrator for COMPLEX requests only (planner → wave → teardown). Single source of truth for cross-agent messaging.
How and when to write a post-implementation reflection. Used by DEVELOPER after reviews are complete.
Domain-by-domain interview to produce /app/docs/project-context.json. Invoked once by the orchestrator; the orchestrator then conducts all turns directly using Read/Write/Edit — no agent dispatching.
Shadcn/ui theming and component customization — CSS variables, OKLCH colors, dark mode, variants, wrappers. Load for any ticket involving colors, theme, UI layout, or component styling.
Playwright E2E testing patterns — web-first assertions, user-visible locators, network interception, fixtures, authentication, and parallel execution. Use when building or reviewing E2E tests with Playwright, when setting up browser testing for a web app, or when migrating from Cypress or Selenium.
When to write e2e tests, where to put them, and how to verify them. Apply to any task touching UI, filters, forms, or interactions.
How to find a Git worktree by task number without hardcoding paths. Use in hooks or scripts that need to locate a specific task's worktree.
| name | agent-team |
| description | Multi-agent team workflow for implementing tickets with peer-to-peer communication inside a single shared team. Used by chat-orchestrator for COMPLEX requests only (planner → wave → teardown). Single source of truth for cross-agent messaging. |
Invoked by chat-orchestrator (team-lead) for COMPLEX requests.
Runtime constraint: one team per lead, no nested teams. So all members of a wave live in one shared team tickets, with deterministic suffixed names.
Out of scope: SIMPLE requests (1-file cosmetic). Those bypass this skill — orchestrator dispatches one developer agent without team_name.
TeamCreate({team_name: "tickets"}) (once per wave).merger = 3N + 1.SendMessage(GO) to each developer-TASK-XXX (one message per dev, in one assistant turn).tickets.Multi-wave: repeat 2→6 (TeamDelete then TeamCreate again).
Every ticket in a wave gets the same trio:
developer-TASK-XXXquality-reviewer-TASK-XXXtest-validator-TASK-XXXPlus one shared merger for the whole wave.
tickets, bare names)| Recipient | to: value | Scope |
|---|---|---|
| Lead (orchestrator) | team-lead | singleton |
| Developer of ticket X | developer-TASK-X | per ticket |
| Quality reviewer of ticket X | quality-reviewer-TASK-X | per ticket |
| Test validator of ticket X | test-validator-TASK-X | per ticket |
| Merger | merger | shared singleton across the wave |
Rules:
TASK-X counterparts + shared merger + team-lead.merger only initiates to team-lead (merge reports).Why one shared merger: git merge against /app holds .git/index.lock. Parallel mergers serialise on the lock anyway — single merger eliminates retry-on-lock complexity.
Pre-condition: PLANNER produced N tickets.
In one assistant message:
TeamCreate({team_name: "tickets", description: "Wave of N tickets"})
// Per ticket (one trio per ticket, all in this same message):
Agent({subagent_type: "developer", name: "developer-TASK-001", team_name: "tickets", model: "opus", description: "Implement TASK-001", prompt: "<see Spawn prompt frames below>"})
Agent({subagent_type: "quality-reviewer", name: "quality-reviewer-TASK-001", team_name: "tickets", model: "sonnet", description: "Quality review TASK-001", prompt: "<see Spawn prompt frames below>"})
Agent({subagent_type: "test-validator", name: "test-validator-TASK-001", team_name: "tickets", model: "sonnet", description: "Test validation TASK-001", prompt: "<see Spawn prompt frames below>"})
// (... repeat trio for TASK-002, TASK-003, ...)
// ONE shared merger (last):
Agent({subagent_type: "merger", name: "merger", team_name: "tickets", model: "haiku", description: "Merge all tickets", prompt: "<see Spawn prompt frames below>"})
Then in a second message: one SendMessage(GO, …) per developer:
SendMessage({to: "developer-TASK-001", message: "GO — Implement TASK-001 (worktree=/app/worktrees/<SESSION_SHORT_ID>/TASK-001, branch=<SESSION_SHORT_ID>/<branch>). Ticket spec at <path>. COUNTERPARTS: reviewers=[quality-reviewer-TASK-001, test-validator-TASK-001], merger=merger."})
After GO: lead enters passive wait. It receives N final SendMessages from merger (one per ticket: merged TASK-XXX, commit=<sha> or TASK-XXX merge failed: <reason>). When count == N → Phase 3.
The WORKFLOW for each role is defined in their own agent file (developer.md, quality-reviewer.md, test-validator.md, merger.md). Spawn prompts only carry the per-ticket inputs; agents read their own file for the workflow.
developer-TASK-XXX
ROLE: developer
TASK_ID: TASK-XXX
TEAM: tickets
WORKTREE_PATH: /app/worktrees/<SESSION_SHORT_ID>/TASK-XXX
BRANCH_NAME: <SESSION_SHORT_ID>/feature/<branch>
TICKET_FILE: <session_dir>/TASK-XXX.json
COUNTERPARTS:
- reviewers: [quality-reviewer-TASK-XXX, test-validator-TASK-XXX]
- merger: merger (shared singleton — bare name)
TEAM_LEAD: team-lead
Follow the WORKFLOW in your agent file (developer.md). Do NOT call
`Skill({skill: "agent-team"})` — that's for the team-lead, not you.
quality-reviewer-TASK-XXX and test-validator-TASK-XXX share the same frame:
ROLE: <quality-reviewer | test-validator>
TASK_ID: TASK-XXX
TEAM: tickets
WORKTREE_PATH: /app/worktrees/<SESSION_SHORT_ID>/TASK-XXX
TICKET_FILE: <session_dir>/TASK-XXX.json
COUNTERPART: developer-TASK-XXX
TEAM_LEAD: team-lead
Follow the WORKFLOW in your agent file. Do NOT call any tool until
`developer-TASK-XXX` sends you a "ready" message. Do NOT call
`Skill({skill: "agent-team"})`.
merger (singleton, no suffix):
ROLE: merger
NAME: merger (no suffix — single shared merger for the whole wave)
TEAM: tickets
TICKETS_DIR: <session_dir> (passed at spawn)
TEAM_LEAD: team-lead
Follow the WORKFLOW in your agent file (merger.md). Do NOT call any tool
until you receive a SendMessage from a developer-TASK-XXX. Do NOT call
`Skill({skill: "agent-team"})` — it's for the team-lead, not you.
SendMessage({to: "developer-TASK-001", message: {type: "shutdown_request"}})
SendMessage({to: "quality-reviewer-TASK-001", message: {type: "shutdown_request"}})
SendMessage({to: "test-validator-TASK-001", message: {type: "shutdown_request"}})
// ... (repeat trio per ticket)
SendMessage({to: "merger", message: {type: "shutdown_request"}}) // last
Total: 3N + 1 SendMessages.
Emit a brief assistant text (e.g. "Wrapping up...") and stop. No other tool calls. The runtime delivers shutdown_approved on the next user turn — being read in the lead's stream marks them read, preventing embryos.
Scan incoming <teammate-message> blocks for shutdown_approved:
/home/developer/.claude/projects/-app/$CLAUDE_SESSION_ID/subagents/agent-<task_id>.jsonl.TeamDelete({})
{} = "the only team this session has open". teamdelete-gate.sh blocks if any non-lead member hasn't acknowledged. If blocked: yield first, retry next turn — do not retry in same turn.
teamdelete-cleanup.sh (PostToolUse) silently removes residual ~/.claude/teams/tickets/. Lead does nothing.
Subagent transcripts (subagents/agent-<task_id>.{jsonl,meta.json}) are kept for stats/debugging — removed at chat-service session end.
Reply to user, one line per ticket:
<sha>."<reason>. Branch retained at <branch>."If next wave: go to Phase 4. Else end.
Some tickets depend on others. PLANNER groups them into waves.
After Phase 3 completes for wave 1: recompute deps, start a new Phase 1 for wave 2 — same tickets team_name (previous was deleted), new dispatches.
TeamDelete is mandatory between waves.
Stop when no pending tickets remain.
| Scenario | Detected by | Reaction |
|---|---|---|
| Reviewer silent > 180s | dev (timeout) | dev → team-lead "TASK-XXX stuck on ". Lead pings or aborts ticket. |
| Dev fix-cycle > 5 | dev (counter) | dev → team-lead "TASK-XXX stuck: cycles". Lead reformulates or aborts. |
| Merger merge conflict | merger | merger → team-lead "TASK-XXX merge failed: ". Lead resumes dev or marks failed. |
Hook stop-hook-error | system event in lead's stream | Lead reads, decides. Validation crash → "validation skipped", warn user. |
| User STOP | chat-service cancelled | chat-service does brutal cleanup of subagents/*, doesn't wait for lead. |
If one ticket fails but others are healthy — abort only its trio. Never shut down the shared merger (others still need it).
SendMessage({to: "developer-TASK-001", message: {type: "shutdown_request", reason: "ABORT"}})
SendMessage({to: "quality-reviewer-TASK-001", message: {type: "shutdown_request", reason: "ABORT"}})
SendMessage({to: "test-validator-TASK-001", message: {type: "shutdown_request", reason: "ABORT"}})
// yield, verify shutdown_approved from these 3 only.
// Do NOT TeamDelete. Do NOT shutdown merger.
Mark TASK-001 failed in ${TICKETS_DIR}/TASK-001.json. Other tickets keep going. When the wave's remaining tickets all merged, do standard Phase 3 (already-stopped members are skipped, shared merger goes last).
Same protocol as Phase 3 (3a→3d), but tag every shutdown_request with reason: "ABORT". Worktrees are left intact for manual recovery.