Team

Overview

Team is an orchestration skill that creates N Claude Code native agents and has them collaborate on a shared task list. It has built-in team management, inter-agent messaging, and task dependencies with no external dependencies required.

Work proceeds through a 5-stage pipeline: team-plan, team-prd, team-exec, team-verify, team-fix.

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 team member agents (1-20). If omitted, determined automatically based on task decomposition
• agent-type: Agent type to use in the team-exec stage (executor, debugger, designer, codex, gemini, etc.). If omitted, auto-routed per stage
• task: High-level task description to decompose and distribute
• ralph: When specified, wraps the team pipeline in Ralph's continuous loop for retries on failure and architect verification on completion

Examples

# 5 executors fixing TypeScript errors
/team 5:executor "fix all TypeScript errors across the project"

# 3 debuggers fixing build errors
/team 3:debugger "fix build errors in src/"

# Auto-sized, auto-routed
/team "refactor the auth module with security review"

# With Ralph continuous loop
/team ralph "build a complete REST API for user management"

# Using Codex CLI workers
/team 3:codex "review all API endpoints for security"

Pipeline Stages

team-plan

The explore and planner agents analyze the task and create an execution plan.

team-prd

The analyst agent analyzes requirements and defines acceptance criteria.

team-exec

Team members execute tasks in parallel. Per-stage agent routing is applied.

team-verify

The verifier and required reviewers validate the results.

team-fix

Fixes issues found during verification. Uses executor or debugger depending on the type of defect. The fix loop is bounded by a maximum number of attempts.

Team + Ralph

team ralph wraps the team pipeline in Ralph's continuous loop.

• If the team fails, Ralph retries
• Performs architect verification on completion
• Cancelling either one cancels the other

Per-Role Provider & Model Routing

Scope: Applies to /team only. Task-based delegation uses delegationRouting (separate system). The two coexist by design.

Declare which provider (claude, codex, gemini) and which model tier should back each canonical role. Routing is resolved once at team creation and persisted in TeamConfig.resolved_routing — spawn, scale-up, and restart all read from the snapshot, so a role's worker CLI and model stay stable for the lifetime of the team.

Example — .claude/omc.jsonc

{
  "team": {
    "roleRouting": {
      "orchestrator":  { "model": "inherit" },
      "planner":       { "provider": "claude", "model": "HIGH" },
      "analyst":       { "provider": "claude", "model": "HIGH" },
      "executor":      { "provider": "claude", "model": "MEDIUM" },
      "critic":        { "provider": "codex" },
      "code-reviewer": { "provider": "gemini" },
      "test-engineer": { "provider": "gemini", "model": "MEDIUM" }
    }
  }
}

Canonical roles

orchestrator, planner, analyst, architect, executor, debugger, critic, code-reviewer, security-reviewer, test-engineer, designer, writer, code-simplifier, explore, document-specialist.

Aliases are normalized at parse time — reviewer → code-reviewer, quality-reviewer → code-reviewer, harsh-critic → critic, build-fixer → debugger. Unknown roles fail validation.

Spec fields

• provider — "claude" | "codex" | "gemini". Omitted → defaults to claude.
• model — tier name ("HIGH" | "MEDIUM" | "LOW") or explicit model ID. Tiers resolve through routing.tierModels.
• agent — optional Claude agent name (e.g., "critic", "executor"). Only honored when the resolved provider is claude.

orchestrator is pinned to claude; only model is configurable for it.

Env override

OMC_TEAM_ROLE_OVERRIDES='{"critic":{"provider":"codex"},"code-reviewer":{"provider":"gemini"}}'

Precedence: OMC_TEAM_ROLE_OVERRIDES > .claude/omc.jsonc (project) > ~/.config/claude-omc/config.jsonc (user) > built-in defaults.

CLI fallback

If a configured provider's CLI is absent from PATH at spawn time, the team lead emits a visible warning and falls back deterministically to a Claude assignment with the same tier + agent. Fallback is loud by design. Probe availability via omc doctor --team-routing.

Zero-config behavior

An empty team.roleRouting preserves pre-patch behavior: every worker is Claude, model tiers follow routing.tierModels, and /team 3:executor ... still spawns three Claude Sonnet executors.

Configuration

Optional settings live in .claude/omc.jsonc (project) or ~/.config/claude-omc/config.jsonc (user):

{
  "team": {
    "ops": {
      "maxAgents": 20,
      "defaultAgentType": "claude",
      "monitorIntervalMs": 30000,
      "shutdownTimeoutMs": 15000
    }
  }
}

• ops.maxAgents — Maximum teammates (default: 20)
• ops.defaultAgentType — CLI provider when /team does not specify one (claude | codex | gemini, default: claude)
• ops.monitorIntervalMs — TaskList poll interval (default: 30s)
• ops.shutdownTimeoutMs — Shutdown response grace period (default: 15s)

Related Skills

• omc-teams - run external CLI workers (codex/gemini)
• ralph - single-agent continuous loop
• ultrawork - simple parallel execution
• ralplan - recommended to run consensus planning before team

Reference