team
N coordinated agents on shared task list using Claude Code implicit agent teams
By yeachan-heo · 709 installs
npx skills add yeachan-heo/oh-my-claudecode --skill team
Source repository · Upstream listing
Team Skill
Spawn N coordinated agents working on a shared task list using Claude Code's implicit agent team. Claude Code 2.1.178+ removed native TeamCreate / TeamDelete ; with CLAUDE CODE EXPERIMENTAL AGENT TEAMS=1 , each session has one implicit team and teammates are spawned directly with the Agent/Task tool using distinct name values. This skill still preserves OMC's legacy tmux/CLI worker orchestration where documented ( omc team / /omc teams ).
The swarm compatibility alias was removed in 1131.
Usage
Parameters
N Number of teammate agents (1 20). Optional; defaults to auto sizing based on task decomposition.
agent type OMC agent to spawn for the team exec stage (e.g., executor, debugger, designer, codex, gemini, antigravity). Optional; defaults to stage aware routing. Use codex to spawn Codex CLI workers, gemini for Gemini CLI workers (enterprise/API key tier), or antigravity for Antigravity CLI ( agy ) workers (Google's successor to the Gemini CLI; requires respective CLIs installed). See Stage Agent Routing below.
task High level task to decompose and distribute among teammates
ralph Optional modifier. When present, wraps the team pipeline in Ralph's persistence loop (retry on failure, architect verification before completion). See Team + Ralph Composition below.
Examples
Architecture
Native Claude Code team model (2.1.178+):
Goal Workflow Relationship
Team is the OMC authority for parallel, staged execution. Use the deterministic conflict policies refuse , adopt existing , and artifact only rather than non deterministic warning handling. If a task mentions Claude Code /goal , Ralph, or artifact only Ultragoal, keep Team as the primary loop authority unless the leader explicitly hands off. Use /goal only as a documented native Claude Code handoff target or as visible evidence from the lead session; do not claim the /goal evaluator independently runs commands, reads files, or replaces team verify / team fix . Artifact only Ultragoal references should be treated as durable goal ledger/checkpoint/evidence artifacts, not as worker execution by themselves.
Staged Pipeline (Canonical Team Runtime)
Team execution follows a staged pipeline:
team plan team prd team exec team verify team fix (loop)
Stage Agent Routing
Each pipeline stage uses specialized agents not just executors. The lead selects agents based on the stage and task characteristics.
Stage Required Agents Optional Agents Selection Criteria
team plan explore (haiku), planner (opus) analyst (opus), architect (opus) Use analyst for unclear requirements. Use architect for systems with complex boundaries.
team prd analyst (opus) critic (opus) Use critic to challenge scope.
team exec executor (sonnet) executor (opus), debugger (sonnet), designer (sonnet), writer (haiku), test engineer (sonnet) Match agent to subtask type. Use executor (model=opus) for complex autonomous work, designer for UI, debugger for compilation issues, writer for docs, test engineer for test creation.
team verify verifier (sonnet) test engineer (sonnet), security reviewer (sonnet), code reviewer (opus) Always run verifier . Add security reviewer for auth/crypto changes. Add code reviewer for 20 files or architectural changes. code reviewer also covers style/formatting checks.
team fix executor (sonnet) debugger (sonnet), executor (opus) Use debugger for type/build errors and regression isolation. Use executor (model=opus) for complex multi file fixes.
Routing rules:
1. The lead picks agents per stage, not the user. The user's N:agent type parameter only overrides the team exec stage worker type. All other stages use stage appropriate specialists.
2. Specialist agents complement executor agents. Route analysis/review to architect/critic Claude agents and UI work to designer agents. Tmux CLI workers are one shot and don't participate in team communication.
3. Cost mode affects model tier. In downgrade: opus agents to sonnet , sonnet to haiku where quality permits. team verify always uses at least sonnet .
4. Risk level escalates review. Security sensitive or 20 file changes must include security reviewer + code reviewer (opus) in team verify .
Stage Entry/Exit Criteria
team plan
Entry: Team invocation is parsed and orchestration starts.
Agents: explore scans codebase, planner creates task graph, optionally analyst / architect for complex tasks.
Exit: decomposition is complete and a runnable task graph is prepared.
team prd
Entry: scope is ambiguous or acceptance criteria are missing.
Agents: analyst extracts requirements, optionally critic .
Exit: acceptance criteria and boundaries are explicit.
team exec
Entry: task list assignment and worker spawn are complete.
Agents: workers spawned as the appropriate specialist type per subtask (see routing table).
Exit: execution tasks reach terminal state for the current pass.
team verify
Entry: execution pass finishes.
Agents: verifier + task appropriate reviewers (see routing table).
Exit (pass): verification gates pass with no required follow up.
Exit (fail): fix tasks are generated and control moves to team fix .
team fix
Entry: verification found defects/regressions/incomplete criteria.
Agents: executor / debugger depending on defect type.
Exit: fixes are complete and flow returns to team exec then team verify .
Verify/Fix Loop and Stop Conditions
Continue team exec team verify team fix until:
1. verification passes and no required fix tasks remain, or
2. work reaches an explicit terminal blocked/failed outcome with evidence.
team fix is bounded by max attempts. If fix attempts exceed the configured limit, transition to terminal failed (no infinite loop).
Stage Handoff Convention
When transitioning between stages, important context — decisions made, alternatives rejected, risks identified — lives only in the lead's conversation history. If the lead's context compacts or agents restart, this knowledge is lost.
Each completing stage MUST produce a handoff document before transitioning.
The lead writes handoffs to .omc/handoffs/<stage name .md .
Handoff Format
Handoff Rules
1. Lead reads previous handoff BEFORE spawning next stage's agents. The handoff content is included in the next stage's agent spawn prompts, ensuring agents start with full context.
2. Handoffs accumulate. The verify stage can read all prior handoffs (plan → prd → exec) for full decision history.
3. On team cancellation, handoffs survive in .omc/handoffs/ for session resume. They are not deleted by native Claude Code team cleanup; no TeamDelete call exists in Claude Code 2.1.178+.
4. Handoffs are lightweight. 10 20 lines max. They capture decisions and rationale, not full specifications (those live in deliverable files like DESIGN.md).
Example
Resume and Cancel Semantics
Resume: restart from the last non terminal stage using staged state + live task status. Read .omc/handoffs/ to recover stage transition context.
Cancel: /oh my claudecode:cancel requests teammate shutdown, waits for responses (best effort), marks phase cancelled with active=false , captures cancellation metadata, then deletes team resources and clears/preserves Team state per policy. Handoff files in .omc/handoffs/ are preserved for potential resume.
Terminal states are complete , failed , and cancelled .
Windows psmux tmux compatible gate
On native Windows, do not tell users that /team requires WSL or that tmux is unavailable until the actual tmux compatible binary has been checked. Native [psmux](https://github.com/psmux/psmux) installs a tmux compatible command (often tmux / tmux.cmd ) and is a supported Team multiplexer.
Before blocking or falling back on Windows:
1. Check tmux V (or the platform equivalent such as where tmux followed by tmux V ).
2. Treat a successful psmux backed tmux V as tmux available.
3. If psmux/tmux is available, continue the normal Team flow; do not emit WSL required guidance.
4. Only when no tmux compatible binary is available, tell the user to install psmux for native Windows support or use WSL2 as an alternative.
Workflow
Phase 1: Parse Input
Extract N (agent count), validate 1 20
Extract agent type , validate it maps to a known OMC subagent
Extract task description
Phase 2: Analyze & Decompose
Use explore or architect (via MCP or agent) to analyze the codebase and break the task into N subtasks:
Each subtask should be file scoped or module scoped to avoid conflicts
Subtasks must be independent or have clear dependency ordering
Each subtask needs a concise subject and detailed description
Identify dependencies between subtasks (e.g., "shared types must be fixed before consumers")
Phase 3: Initialize Team State
Use the session's implicit Claude Code team. Do not call TeamCreate ; Claude Code 2.1.178+ removed that tool and automatically gives the session one implicit team when CLAUDE CODE EXPERIMENTAL AGENT TEAMS=1 is enabled.
Derive a slug such as fix ts errors for OMC state, prompt labels, handoffs, and human readable reporting only. Native Claude Code may accept team name as legacy metadata, but it is ignored for routing.
Write OMC state using the state write MCP tool for proper session scoped persistence:
Note: The MCP state write tool transports all values as strings. Consumers must coerce agent count , fix loop count , max fix loops to numbers and linked ralph to boolean when reading state.
State schema fields:
Field Type Description
active boolean Whether team mode is active
current phase string Current pipeline stage: team plan , team prd , team exec , team verify , team fix
team name string OMC slug for state, handoffs, and reporting; ignored by native Claude Code routing
agent count number Number of worker agents
agent types string Comma separated agent types used in team exec
task string Original task description
fix loop count number Current fix iteration count
max fix loops number Maximum fix iterations before failing (default: 3)
linked ralph boo