Skip to content

OXI-717/ai-native-toolkit / plugins/agent-teams/skills/agent-teams

agent-teams

Verified

Use when facing complex tasks needing parallel collaboration between multiple agents with shared state, coordination, and direct inter-agent communication. Triggers on "создай команду", "agent team", "параллельная работа агентов", "team of agents"

Agent Teams

Coordinate multiple autonomous agents working on a shared task list with direct messaging.

Core principle: Teams for collaboration with shared state. Subagents for focused tasks returning results. Don't use teams when subagents suffice.

When to Use

digraph when_to_use {
    "Complex task?" [shape=diamond];
    "Independent subtasks?" [shape=diamond];
    "Need agents to communicate?" [shape=diamond];
    "Need shared task tracking?" [shape=diamond];
    "Single agent" [shape=box];
    "Subagents (Agent tool)" [shape=box];
    "Agent Teams" [shape=box];

    "Complex task?" -> "Single agent" [label="no"];
    "Complex task?" -> "Independent subtasks?" [label="yes"];
    "Independent subtasks?" -> "Need agents to communicate?" [label="yes"];
    "Independent subtasks?" -> "Single agent" [label="no - sequential"];
    "Need agents to communicate?" -> "Agent Teams" [label="yes"];
    "Need agents to communicate?" -> "Need shared task tracking?" [label="no"];
    "Need shared task tracking?" -> "Agent Teams" [label="yes"];
    "Need shared task tracking?" -> "Subagents (Agent tool)" [label="no - just results"];
}

Use teams:

  • Cross-layer work (frontend + backend + tests) needing coordination
  • Research with multiple competing hypotheses sharing findings
  • PR review with parallel security/performance/tests reviewers
  • Large refactoring where agents own separate modules but must align

Use subagents instead:

  • Focused tasks where you only need the result
  • No inter-agent communication needed
  • Simple parallel dispatch (use dispatching-parallel-agents)

Teams vs Subagents

AspectSubagents (plain Agent)Agent Teams (named Agent + shared tasks)
ContextOwn, returns summaryOwn, fully independent
CommunicationOnly back to callerAgents message each other
CoordinationCaller manages allShared task list + self-coordination
CostLower (summarized results)Higher (each agent = separate Claude)
File conflictsCaller integratesRisk if agents edit same files
Best forFocused tasks, results matterCollaboration, discussion matters

Lifecycle

1. The team already exists

There is no team-creation step and no Teammate tool. Every session has one implicit team: the first spawned agent joins it, the main conversation is its lead.

The runtime keeps the registry itself, keyed by session, not by a team name you choose:

  • ~/.claude/teams/session-<id>/config.json — members (lead + teammates)
  • ~/.claude/teams/session-<id>/inboxes/<agent-name>.json — per-agent mailbox

The shared task list lives in the session, not in a project directory — nothing is written under .task-runner/.

2. Create Tasks

TaskCreate(subject="Implement JWT middleware", description="...", activeForm="Implementing JWT middleware")
TaskCreate(subject="Write auth API tests", description="...", activeForm="Writing auth tests")

3. Spawn Teammates

Use the Agent tool with name — the name is what makes the agent addressable later. Do not pass team_name: it is deprecated and ignored (one implicit team per session).

Agent(
    subagent_type="general-purpose",
    name="backend-dev",
    prompt="You are a backend developer. Check TaskList for your assignments."
)
Agent(
    subagent_type="general-purpose",
    name="test-writer",
    prompt="You are a test specialist. Check TaskList for your assignments."
)

4. Assign Tasks

TaskUpdate(taskId="1", owner="backend-dev")
TaskUpdate(taskId="2", owner="test-writer")

5. Monitor & Communicate

SendMessage takes to / message / summary. There is no type field for ordinary messages and no broadcast — address teammates one by one.

SendMessage(to="backend-dev", message="Use httpOnly cookies for tokens", summary="JWT storage guidance")

Teammates auto-notify you when idle (turn ended). This is normal — idle means waiting, not done.

6. Shutdown

Teammates do not exit automatically when idle; they remain resident in the session waiting for messages. Once team work is complete or a teammate is genuinely no longer needed, send a shutdown_request to stop them:

SendMessage(to="backend-dev", message={"type": "shutdown_request", "reason": "Work complete"}, summary="stop backend-dev")

Shutting teammates down is the lead's call. A teammate never originates a shutdown_request on its own — it only answers one with shutdown_response (echo the request_id, set approve). Approving ends that teammate's process.

Best Practices

Task Sizing

  • 5-6 tasks per teammate is optimal
  • Too small → coordination overhead > value
  • Too large → no checkpoints, hard to monitor
  • Each task should have clear deliverable (file, function, test suite)

Prevent File Conflicts

Two agents editing same file = overwrites. Partition by ownership:

backend-dev  → src/auth/middleware.ts, src/auth/jwt.ts
test-writer  → tests/auth/*.test.ts

If overlap unavoidable: sequence the tasks with addBlockedBy.

Context for Teammates

Teammates DON'T inherit your conversation history. They get:

  • CLAUDE.md + rules
  • MCP servers, skills
  • Your spawn prompt

Make spawn prompts rich:

❌ "Fix the auth bug"
✅ "Fix JWT expiry bug in src/auth/jwt.ts. Token refresh fails when
    access token expires but refresh token is valid. Error: 'TokenExpiredError'
    at line 42. The refresh logic in refreshAccessToken() doesn't check
    refresh token validity before attempting renewal. Write tests first."

Communication Patterns

Lead → Teammate: Direct message with context

SendMessage(to="backend-dev",
    message="The DB schema changed - users table now has 'role' column",
    summary="Schema change notification")

Teammate → Lead: address the main conversation as main (background teammates only — a foreground agent returns its result to the caller instead)

SendMessage(to="main", message="Middleware done, tests green", summary="JWT middleware ready")

No broadcast. To reach everyone, send the same message to each teammate by name — which is a good reason to keep teams at 2-4 agents.

Plan approval: Spawn teammate in plan mode, review their plan before they implement.

Idle State

Teammates go idle after every turn. This is normal behavior, not an error:

  • Idle = waiting for input
  • Sending a message wakes them up
  • Don't react to idle notifications unless assigning new work

Common Mistakes

MistakeFix
Using teams for sequential workUse single agent or subagents
Not partitioning files by agentAssign file ownership explicitly
Sparse spawn promptsInclude full context, don't assume shared history
Messaging everyone about routine progressMark it with TaskUpdate — teammates read the list themselves
Reacting to every idle notificationIdle is normal, only respond when needed
Expecting to read results off the task listResolved tasks vanish — require a SendMessage report
Starting code before teammates finishWait for results, verify, then integrate
Too many teammates2-4 optimal, more = coordination overhead

Anti-Patterns

Pipeline anti-pattern: Don't split sequential phases into separate agents (planning → implementation → testing). One agent doing all three is cheaper and avoids handoff loss.

Manager-only lead: Don't just coordinate — the lead agent should also do work. Delegate mode is for complex orchestration only.

Over-communication: Don't message every teammate with status updates. Use TaskUpdate to mark progress — teammates check TaskList themselves.

Quick Reference

ToolPurpose
Agent(subagent_type=..., name=...)Spawn teammate (no team_name — deprecated)
TaskCreate / TaskList / TaskGet / TaskUpdateManage shared tasks
SendMessage(to=..., message=..., summary=...)Message a teammate, or to="main" for the lead
SendMessage(to=..., message={"type": "shutdown_request"})Shut down a teammate when no longer needed

Gone in the current runtime: the Teammate tool (both spawnTeam and cleanup), the team_name argument, type="message" / type="broadcast" and recipient= / content=.

Limitations (Current)

  • No /resume for in-process teammates
  • One team per session
  • No nested teams (teammates can't create sub-teams)
  • Lead is fixed for lifecycle
  • Split panes need tmux/iTerm2 (not VS Code terminal)
  • Task status may lag — teammates sometimes forget to mark completed
  • A resolved task disappears: once it is completed it drops out of TaskList and TaskGet answers "Task not found". Deleted tasks vanish the same way, so the list can't tell you whether work was finished or thrown away — ask the teammate, or have it report the result via SendMessage before resolving. Keep your own record if you need history: IDs keep counting up, so a gap means a task existed and is gone.
reverse-engineer-anythingmorluto/reaReverse engineer native, managed, Electron/JavaScript, packaged, firmware, and browser targets with REA, and build agent environments (AgentEnv bundles) of web applications from a live instance or a capture, and of Linux desktop apps with a task from a request. Use shipped-artifact or requested runtime evidence to explain features, compare versions, decompile code, or guide a reconstruction. Skip REA for ordinary source-repository architecture analysis.Stars: 468kUpdated Claude CodeCodexVerifiedInstall
diagnosing-superpowersobra/superpowersUse when a superpowers session went wrong and your human partner wants to know why — repeated work, ignored plans, stumbles, poor results, a skill that didn't fire, "it took too long", "why is it so expensive", "what is it doing" — or wants to build a bug report for the superpowers maintainers, for the current session or a past one identified by id or path, on any harness.Stars: 321kUpdated Claude CodeCodexVerifiedInstall
dispatching-parallel-agentsobra/superpowersUse when facing 2+ independent tasks that can be worked on without shared state or sequential dependenciesStars: 321kUpdated Claude CodeCodexVerifiedInstall
executing-plansobra/superpowersUse when executing an implementation plan in the current session as the implementer yourself — your human partner chose inline execution, or no subagent tool is availableStars: 321kUpdated Claude CodeCodexVerifiedInstall