• 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, build-fixer, designer). Optional; defaults to stage-aware routing (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.

explore

planner

analyst

architect

analyst

architect

analyst

product-manager

critic

product-manager

critic

executor

deep-executor

build-fixer

designer

writer

test-engineer

deep-executor

designer

build-fixer

writer

test-engineer

verifier

test-engineer

security-reviewer

code-reviewer

quality-reviewer

performance-reviewer

verifier

security-reviewer

code-reviewer

performance-reviewer

executor

build-fixer

debugger

deep-executor

build-fixer

debugger

deep-executor

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. MCP providers complement Claude agents. Route analysis/review to Codex (

   ask_codex

   ) and UI/large-context work to Gemini (

   ask_gemini

   ) when available. MCP workers are one-shot and don't participate in team communication.
3. Cost mode affects model tier. In ecomode, 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

   .

• 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

    product-manager

    /

    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

    /

    build-fixer

    /

    debugger

    depending on defect type.
  • Exit: fixes are complete and flow returns to

    team-exec

    then

    team-verify

    .

team-exec -> team-verify -> team-fix

1. verification passes and no required fix tasks remain, or
2. work reaches an explicit terminal blocked/failed outcome with evidence.

team-fix

failed

• Resume: restart from the last non-terminal stage using staged state + live task status.
• 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.
• Terminal states are

  complete

  ,

  failed

  , and

  cancelled

  .

• Extract N (agent count), validate 1-20
• Extract agent-type, validate it maps to a known OMC subagent
• Extract task description

explore

architect

• 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")

TeamCreate

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

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

team-lead@fix-ts-errors

state_write

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.

active

current_phase

team-plan

team-prd

team-exec

team-verify

team-fix

team_name

agent_count

agent_types

task

fix_loop_count

max_fix_loops

linked_ralph

stage_history

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"
})

state_read(mode="team")

active=true

current_phase

Task

team_name

name

{
  "subagent_type": "oh-my-claudecode:executor",
  "team_name": "fix-ts-errors",
  "name": "worker-1",
  "prompt": "<worker-preamble + assigned tasks>"
}

{
  "agent_id": "worker-1@fix-ts-errors",
  "name": "worker-1",
  "team_name": "fix-ts-errors"
}

• Teammate added to

  config.json

  members array
• An internal task is auto-created (with

  metadata._internal: true

  ) tracking the agent lifecycle
• Internal tasks appear in

  TaskList

  output -- filter them when counting real tasks

1. Inbound messages -- Teammates send

   SendMessage

   to

   team-lead

   when they complete tasks or need help. These arrive automatically as new conversation turns (no polling needed).
2. TaskList polling -- Periodically call

   TaskList

   to check overall progress:

   #1 [completed] Fix type errors in src/auth/ (worker-1)
   #3 [in_progress] Fix type errors in src/api/ (worker-2)
   #5 [pending] Fix type errors in src/utils/ (worker-3)

   Format:

   #ID [status] subject (owner)

• Unblock a teammate: Send a

  message

  with guidance or missing context
• Reassign work: If a teammate finishes early, use

  TaskUpdate

  to assign pending tasks to them and notify via

  SendMessage

• Handle failures: If a teammate reports failure, reassign the task or spawn a replacement

• Max in-progress age: If a task stays

  in_progress

  for more than 5 minutes without messages, send a status check
• Suspected dead worker: No messages + stuck task for 10+ minutes → reassign task to another worker
• Reassign threshold: If a worker fails 2+ tasks, stop assigning new tasks to it

// Entering team-exec after planning
state_write(mode="team", current_phase="team-exec", state={
  "stage_history": "team-plan:T1,team-prd:T2,team-exec:T3"
})

// Entering team-verify after execution
state_write(mode="team", current_phase="team-verify")

// Entering team-fix after verify failure
state_write(mode="team", current_phase="team-fix", state={
  "fix_loop_count": 1
})

• Resume: If the lead crashes,

  state_read(mode="team")

  reveals the last stage and team name for recovery
• Cancel: The cancel skill reads

  current_phase

  to know what cleanup is needed
• Ralph integration: Ralph can read team state to know if the pipeline completed or failed

1. Verify results -- Check that all subtasks are marked

   completed

   via

   TaskList

2. Shutdown teammates -- Send

   shutdown_request

   to each active teammate:
   json

   {
     "type": "shutdown_request",
     "recipient": "worker-1",
     "content": "All work complete, shutting down team"
   }

3. Await responses -- Each teammate responds with

   shutdown_response(approve: true)

   and terminates
4. Delete team -- Call

   TeamDelete

   to clean up:
   json

   { "team_name": "fix-ts-errors" }

   Response:
   json

   {
     "success": true,
     "message": "Cleaned up directories and worktrees for team \"fix-ts-errors\"",
     "team_name": "fix-ts-errors"
   }

5. Clean OMC state -- Remove

   .omc/state/team-state.json

6. Report summary -- Present results to the user

{
  "type": "shutdown_request",
  "recipient": "worker-1",
  "content": "All work complete, shutting down team"
}

{
  "type": "shutdown_response",
  "request_id": "shutdown-1770428632375@worker-1",
  "approve": true
}

• Teammate process terminates
• Teammate auto-removed from

  config.json

  members array
• Internal task for that teammate completes

request_id

1. Lead writes task instructions to a

   prompt_file

2. Lead calls

   ask_codex

   or

   ask_gemini

   with

   working_directory

   set to the project root
3. The CLI reads files, makes changes, runs commands -- all within the working directory
4. Results/summary are written to

   output_file

5. Lead reads the output, marks the task complete, and feeds results to dependent tasks

• MCP workers operate via CLI, not Claude Code's tool system
• They cannot use TaskList/TaskUpdate/SendMessage (no team awareness)
• They run as one-shot autonomous jobs, not persistent teammates
• The lead manages their lifecycle (spawn, monitor, collect results)

1. Call

   ToolSearch("mcp")

   to discover deferred MCP tools (required before first use)
2. Call

   ask_codex

   (planner role) with task description + codebase context
3. Use the analysis to produce better task decomposition
4. Create team and tasks with enriched context

getTeamStatus(teamName, workingDirectory, heartbeatMaxAgeMs?)

• Worker registration -- Which MCP workers are registered (from shadow registry / config.json)
• Heartbeat freshness -- Whether each worker is alive based on heartbeat age
• Task progress -- Per-worker and team-wide task counts (pending, in_progress, completed)
• Current task -- Which task each worker is actively executing
• Recent outbox messages -- New messages since the last status check

const status = getTeamStatus('fix-ts-errors', workingDirectory);

for (const worker of status.workers) {
  if (!worker.isAlive) {
    // Worker is dead -- reassign its in-progress tasks
  }
  for (const msg of worker.recentMessages) {
    if (msg.type === 'task_complete') {
      // Mark task complete, unblock dependents
    } else if (msg.type === 'task_failed') {
      // Handle failure, possibly retry or reassign
    } else if (msg.type === 'error') {
      // Log error, check if worker needs intervention
    }
  }
}

if (status.taskSummary.pending === 0 && status.taskSummary.inProgress === 0) {
  // All work done -- proceed to shutdown
}

1. Teammate sends

   SendMessage

   to lead reporting the failure
2. Lead decides: retry (reassign same task to same or different worker) or skip
3. To reassign:

   TaskUpdate

   to set new owner, then

   SendMessage

   to the new owner

1. Lead detects via

   TaskList

   -- task stuck in

   in_progress

   for too long
2. Lead sends

   SendMessage

   to the teammate asking for status
3. If no response, consider the teammate dead
4. Reassign the task to another worker via

   TaskUpdate

1. If a blocking task fails, the lead must decide whether to:
   • Retry the blocker
   • Remove the dependency (

     TaskUpdate

     with modified blockedBy)
   • Skip the blocked task entirely
2. Communicate decisions to affected teammates via

   SendMessage

1. Internal task for that teammate will show unexpected status
2. Teammate disappears from

   config.json

   members
3. Lead reassigns orphaned tasks to remaining workers
4. If needed, spawn a replacement teammate with

   Task(team_name, name)

/team ralph

• Team orchestration -- multi-agent staged pipeline with specialized agents per stage
• Ralph persistence -- retry on failure, architect verification before completion, iteration tracking

1. User invokes

   /team ralph "task"

   or

   /oh-my-claudecode:team ralph "task"

2. Keyword detector finds both

   team

   and

   ralph

   in the prompt
3. Hook detects

   MAGIC KEYWORD: RALPH

   alongside team context

1. Ralph outer loop starts (iteration 1)
2. Team pipeline runs:

   team-plan -> team-prd -> team-exec -> team-verify

3. If

   team-verify

   passes: Ralph runs architect verification (STANDARD tier minimum)
4. If architect approves: both modes complete, run

   /oh-my-claudecode:cancel

5. If

   team-verify

   fails OR architect rejects: team enters

   team-fix

   , then loops back to

   team-exec -> team-verify

6. If fix loop exceeds

   max_fix_loops

   : Ralph increments iteration and retries the full pipeline
7. If Ralph exceeds

   max_iterations

   : terminal

   failed

   state

• Cancel Ralph (linked): Cancel Team first (graceful shutdown), then clear Ralph state
• Cancel Team (linked): Clear Team, mark Ralph iteration cancelled, stop loop

1. Check

   ~/.claude/teams/

   for teams matching the task slug
2. If found, read

   config.json

   to discover active members
3. Resume monitor mode instead of creating a duplicate team
4. Call

   TaskList

   to determine current progress
5. Continue from the monitoring phase

/oh-my-claudecode:cancel

1. Read team state via

   state_read(mode="team")

   to get

   team_name

   and

   linked_ralph

2. Send

   shutdown_request

   to all active teammates (from

   config.json

   members)
3. Wait for

   shutdown_response

   from each (15s timeout per member)
4. Call

   TeamDelete

   to remove team and task directories
5. Clear state via

   state_clear(mode="team")

6. If

   linked_ralph

   is true, also clear ralph:

   state_clear(mode="ralph")

• Cancel triggered from Ralph context: Cancel Team first (graceful shutdown of all teammates), then clear Ralph state. This ensures workers are stopped before the persistence loop exits.
• Cancel triggered from Team context: Clear Team state, then mark Ralph as cancelled. Ralph's stop hook will detect the missing team and stop iterating.
• Force cancel (

  --force

  ): Clears both

  team

  and

  ralph

  state unconditionally via

  state_clear

  .

TeamDelete

~/.claude/teams/{team_name}/

~/.claude/tasks/{team_name}/

.omc-config.json

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

• maxAgents - Maximum teammates (default: 20)
• defaultAgentType - Agent type when not specified (default:

  executor

  )
• monitorIntervalMs - How often to poll

  TaskList

  (default: 30s)
• shutdownTimeoutMs - How long to wait for shutdown responses (default: 15s)

Note: Team members do not have a hardcoded model default. Each teammate is a separate Claude Code session that inherits the user's configured model. Since teammates can spawn their own subagents, the session model acts as the orchestration layer while subagents can use any model tier.

1. TeamDelete

   handles all Claude Code state:
   • Removes

     ~/.claude/teams/{team_name}/

     (config)
   • Removes

     ~/.claude/tasks/{team_name}/

     (all task files + lock)
2. OMC state cleanup via MCP tools:

   state_clear(mode="team")

   If linked to Ralph:

   state_clear(mode="ralph")

3. Or run

   /oh-my-claudecode:cancel

   which handles all cleanup automatically.

TeamDelete

TeamDelete

1. Worktree creation: Before spawning a worker, call

   createWorkerWorktree(teamName, workerName, repoRoot)

   to create an isolated worktree at

   .omc/worktrees/{team}/{worker}

   with branch

   omc-team/{teamName}/{workerName}

   .
2. Worker isolation: Pass the worktree path as the

   workingDirectory

   in the worker's

   BridgeConfig

   . The worker operates exclusively in its own worktree.
3. Merge coordination: After a worker completes its tasks, use

   checkMergeConflicts()

   to verify the branch can be cleanly merged, then

   mergeWorkerBranch()

   to merge with

   --no-ff

   for clear history.
4. Team cleanup: On team shutdown, call

   cleanupTeamWorktrees(teamName, repoRoot)

   to remove all worktrees and their branches.

• createSession()

  in

  tmux-session.ts

  does NOT handle worktree creation — worktree lifecycle is managed separately via

  git-worktree.ts

• Worktrees are NOT cleaned up on individual worker shutdown — only on team shutdown, to allow post-mortem inspection
• Branch names are sanitized via

  sanitizeName()

  to prevent injection
• All paths are validated against directory traversal

1. Internal tasks pollute TaskList -- When a teammate is spawned, the system auto-creates an internal task with

   metadata._internal: true

   . These appear in

   TaskList

   output. Filter them when counting real task progress. The subject of an internal task is the teammate's name.
2. No atomic claiming -- Unlike SQLite swarm, there is no transactional guarantee on

   TaskUpdate

   . Two teammates could race to claim the same task. Mitigation: The lead should pre-assign owners via

   TaskUpdate(taskId, owner)

   before spawning teammates. Teammates should only work on tasks assigned to them.
3. Task IDs are strings -- IDs are auto-incrementing strings ("1", "2", "3"), not integers. Always pass string values to

   taskId

   fields.
4. TeamDelete requires empty team -- All teammates must be shut down before calling

   TeamDelete

   . The lead (the only remaining member) is excluded from this check.
5. Messages are auto-delivered -- Teammate messages arrive to the lead as new conversation turns. No polling or inbox-checking is needed for inbound messages. However, if the lead is mid-turn (processing), messages queue and deliver when the turn ends.
6. Teammate prompt stored in config -- The full prompt text is stored in

   config.json

   members array. Do not put secrets or sensitive data in teammate prompts.
7. Members auto-removed on shutdown -- After a teammate approves shutdown and terminates, it is automatically removed from

   config.json

   . Do not re-read config expecting to find shut-down teammates.
8. shutdown_response needs request_id -- The teammate must extract the

   request_id

   from the incoming shutdown request JSON and pass it back. The format is

   shutdown-{timestamp}@{worker-name}

   . Fabricating this ID will cause the shutdown to fail silently.
9. Team name must be a valid slug -- Use lowercase letters, numbers, and hyphens. Derive from the task description (e.g., "fix TypeScript errors" becomes "fix-ts-errors").
10. Broadcast is expensive -- Each broadcast sends a separate message to every teammate. Use

    message

    (DM) by default. Only broadcast for truly team-wide critical alerts.
11. MCP workers are one-shot, not persistent -- Codex and Gemini CLIs have full filesystem access and CAN make code changes. However, they run as autonomous one-shot jobs -- they cannot use TaskList/TaskUpdate/SendMessage. The lead must manage their lifecycle: write prompt_file, call MCP, read output_file, mark task complete. They don't participate in team communication like Claude teammates do.