Team Skill

Spawn N coordinated agents working on a shared task list using Claude Code's native team tools. Replaces the legacy /swarm skill (SQLite-based) with built-in team management, inter-agent messaging, and task dependencies -- no external dependencies required.

The swarm compatibility alias was removed in #1131.

Usage

/oh-my-claudecode:team N:agent-type "task description"
/oh-my-claudecode:team "task description"
/oh-my-claudecode:team ralph "task description"

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). Optional; defaults to stage-aware routing. Use codex to spawn Codex CLI workers or gemini for Gemini CLI workers (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

/team 5:executor "fix all TypeScript errors across the project"
/team 3:debugger "fix build errors in src/"
/team 4:designer "implement responsive layouts for all page components"
/team "refactor the auth module with security review"
/team ralph "build a complete REST API for user management"
# With Codex CLI workers (requires: npm install -g @openai/codex)
/team 2:codex "review architecture and suggest improvements"
# With Gemini CLI workers (requires: npm install -g @google/gemini-cli)
/team 2:gemini "redesign the UI components"
# Mixed: Codex for backend analysis, Gemini for frontend (use /ccg instead for this)

Architecture

User: "/team 3:executor fix all TypeScript errors"
              |
              v
      [TEAM ORCHESTRATOR (Lead)]
              |
              +-- TeamCreate("fix-ts-errors")
              |       -> lead becomes team-lead@fix-ts-errors
              |
              +-- Analyze & decompose task into subtasks
              |       -> explore/architect produces subtask list
              |
              +-- TaskCreate x N (one per subtask)
              |       -> tasks #1, #2, #3 with dependencies
              |
              +-- TaskUpdate x N (pre-assign owners)
              |       -> task #1 owner=worker-1, etc.
              |
              +-- Task(team_name="fix-ts-errors", name="worker-1") x 3
              |       -> spawns teammates into the team
              |
              +-- Monitor loop
              |       <- SendMessage from teammates (auto-delivered)
              |       -> TaskList polling for progress
              |       -> SendMessage to unblock/coordinate
              |
              +-- Completion
                      -> SendMessage(shutdown_request) to each teammate
                      <- SendMessage(shutdown_response, approve: true)
                      -> TeamDelete("fix-ts-errors")
                      -> rm .omc/state/team-state.json

Storage layout (managed by Claude Code):

~/.claude/
  teams/fix-ts-errors/
    config.json          # Team metadata + members array
  tasks/fix-ts-errors/
    .lock                # File lock for concurrent access
    1.json               # Subtask #1
    2.json               # Subtask #2 (may be internal)
    3.json               # Subtask #3
    ...

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: TeamCreate, TaskCreate, 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: <current-stage> → <next-stage>
- **Decided**: [key decisions made in this stage]
- **Rejected**: [alternatives considered and why they were rejected]
- **Risks**: [identified risks for the next stage]
- **Files**: [key files created or modified]
- **Remaining**: [items left for the next stage to handle]

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

## Handoff: team-plan → team-exec
- **Decided**: Microservice architecture with 3 services (auth, api, worker). PostgreSQL for persistence. JWT for auth tokens.
- **Rejected**: Monolith (scaling concerns), MongoDB (team expertise is SQL), session cookies (API-first design).
- **Risks**: Worker service needs Redis for job queue — not yet provisioned. Auth service has no rate limiting in initial design.
- **Files**: DESIGN.md, TEST_STRATEGY.md
- **Remaining**: Database migration scripts, CI/CD pipeline config, Redis provisioning.

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.

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: Create Team

Call TeamCreate with a slug derived from the task:

{
  "team_name": "fix-ts-errors",
  "description": "Fix all TypeScript errors across the project"
}

Response:

{
  "team_name": "fix-ts-errors",
  "team_file_path": "~/.claude/teams/fix-ts-errors/config.json",
  "lead_agent_id": "team-lead@fix-ts-errors"
}

The current session becomes the team lead (team-lead@fix-ts-errors).

Write OMC state using the state_write MCP tool for proper session-scoped persistence:

state_write(mode="team", active=true, current_phase="team-plan", state={
  "team_name": "fix-ts-errors",
  "agent_count": 3,
  "agent_types": "executor",
  "task": "fix all TypeScript errors",
  "fix_loop_count": 0,
  "max_fix_loops": 3,
  "linked_ralph": false,
  "stage_history": "team-plan"
})

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	Slug name for the team
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	boolean	Whether team is linked to a ralph persistence loop
stage_history	string	Comma-separated list of stage transitions with timestamps

Update state on every stage transition:

state_write(mode="team", current_phase="team-exec", state={
  "stage_history": "team-plan:2026-02-07T12:00:00Z,team-prd:2026-02-07T12:01:00Z,team-exec:2026-02-07T12:02:00Z"
})

Read state for resume detection:

state_read(mode="team")

If active=true and current_phase is non-terminal, resume from the last incomplete stage instead of creating a new team.

Phase 4: Create Tasks

Call TaskCreate for each subtask. Set dependencies with TaskUpdate using addBlockedBy.

// TaskCreate for subtask 1
{
  "subject": "Fix type errors in src/auth/",
  "description": "Fix all TypeScript errors in src/auth/login.ts, src/auth/session.ts, and src/auth/types.ts. Run tsc --noEmit to verify.",
  "activeForm": "Fixing auth type errors"
}

Response stores a task file (e.g. 1.json):