team

Team Skill

$team is the tmux-based parallel execution mode for OMX. It starts real worker Codex and/or Claude CLI sessions in split panes and coordinates them through .omx/state/team/... files plus CLI team interop (omx team api ...) and state files.

This skill is operationally sensitive. Treat it as an operator workflow, not a generic prompt pattern.

Team vs Native Subagents

• Use Codex native subagents for bounded, in-session parallelism where one leader thread can fan out a few independent subtasks and wait for them directly.
• Use omx team when you need durable tmux workers, shared task state, mailbox/dispatch coordination, worktrees, explicit lifecycle control, or long-running parallel execution that must survive beyond one local reasoning burst.
• Native subagents can complement team/ralph execution, but they do not replace the tmux team runtime's stateful coordination contract.

What This Skill Must Do

GPT-5.4 Guidance Alignment

• Default to concise, evidence-dense progress and completion reporting unless the user or risk level requires more detail.
• Treat newer user task updates as local overrides for the active workflow branch while preserving earlier non-conflicting constraints.
• If correctness depends on additional inspection, retrieval, execution, or verification, keep using the relevant tools until the team workflow is grounded.
• Continue through clear, low-risk, reversible next steps automatically; ask only when the next step is materially branching, destructive, or preference-dependent.

When user triggers $team, the agent must:

1. Invoke OMX runtime directly with omx team ...
2. Avoid replacing the flow with in-process spawn_agent fanout
3. Verify startup and surface concrete state/pane evidence
4. If active team mode state is missing, initialize/sync it from canonical team runtime state before proceeding
5. Keep team state alive until workers are terminal (unless explicit abort)
6. Handle cleanup and stale-pane recovery when needed

If omx team is unavailable, stop with a hard error.

Invocation Contract

omx team [N:agent-type] "<task description>"

Examples:

omx team 3:executor "analyze feature X and report flaws"
omx team "debug flaky integration tests"
omx team "ship end-to-end fix with verification"

Team-first launch contract

omx team ... is now the canonical launch path for coordinated execution. Team mode should carry its own parallel delivery + verification lanes without requiring a separate linked Ralph launch up front.

• Canonical launch: use plain omx team ... / $team ... for coordinated workers.
• Verification ownership: keep one lane focused on tests, regression coverage, and evidence before shutdown.
• Escalation: start a separate omx ralph ... / $ralph ... only when a later manual follow-up still needs a persistent single-owner fix/verification loop.
• Deprecation: omx team ralph ... has been removed. Use plain omx team ... for team execution or run omx ralph ... separately when you explicitly want a later Ralph loop.

Claude teammates (v0.6.0+)

Important: N:agent-type (for example 2:executor) selects the worker role prompt, not the worker CLI (codex vs claude).

To launch Claude teammates, use the team worker CLI env vars:

# Force all teammates to Claude CLI
OMX_TEAM_WORKER_CLI=claude omx team 2:executor "update docs and report"

# Mixed team (worker 1 = Codex, worker 2 = Claude)
OMX_TEAM_WORKER_CLI_MAP=codex,claude omx team 2:executor "split doc/code tasks"

# Auto mode: Claude is selected when worker launch args/model contains 'claude'
OMX_TEAM_WORKER_CLI=auto OMX_TEAM_WORKER_LAUNCH_ARGS="--model claude-..." omx team 2:executor "run mixed validation"

Preconditions

Before running $team, confirm:

1. tmux installed (tmux -V)
2. Current leader session is inside tmux ($TMUX is set)
3. omx command resolves to the intended install/build
4. If running repo-local node bin/omx.js ..., run npm run build after src changes
5. Check HUD pane count in the leader window and avoid duplicate hud --watch panes before split

Suggested preflight:

tmux list-panes -F '#{pane_id}\t#{pane_start_command}' | rg 'hud --watch' || true

If duplicates exist, remove extras before omx team to prevent HUD ending up in worker stack.

Pre-context Intake Gate

Before launching omx team, require a grounded context snapshot:

1. Derive a task slug from the request.
2. Reuse the latest relevant snapshot in .omx/context/{slug}-*.md when available.
3. If none exists, create .omx/context/{slug}-{timestamp}.md (UTC YYYYMMDDTHHMMSSZ) with:
   • task statement
   • desired outcome
   • known facts/evidence
   • constraints
   • unknowns/open questions
   • likely codebase touchpoints
4. If ambiguity remains high, run explore first for brownfield facts, then run $deep-interview --quick <task> before team launch.
5. If current correctness depends on official docs, version-aware framework guidance, best practices, or external dependency behavior, auto-delegate researcher as an evidence lane before or alongside worker launch instead of relying on repo-local recall alone.

Do not start worker panes until this gate is satisfied; if forced to proceed quickly, state explicit scope/risk limitations in the launch report.

For simple read-only brownfield lookups during intake, follow active session guidance: when USE_OMX_EXPLORE_CMD is enabled, prefer omx explore with narrow, concrete prompts; otherwise use the richer normal explore path and fall back normally if omx explore is unavailable.

Follow-up Staffing Contract

When $team is used as a follow-up mode from ralplan, carry forward the approved plan's explicit available-agent-types roster and convert it into concrete staffing guidance before launch:

• keep worker-role choices inside the known roster
• state the recommended headcount and role counts
• state the suggested reasoning level for each lane when available
• explain why each lane exists (delivery, verification, specialist support)
• include an explicit launch hint (omx team N "<task>" / $team N "<task>") for the coordinated team run; mention a later separate Ralph follow-up only when genuinely needed
• if the ideal role is unavailable, choose the closest role from the roster and say so

Current Runtime Behavior (As Implemented)

omx team currently performs:

1. Parse args (N, agent-type, task)
2. Sanitize team name from task text
3. Initialize team state:
   • .omx/state/team/<team>/config.json
   • .omx/state/team/<team>/manifest.v2.json
   • .omx/state/team/<team>/tasks/task-<id>.json
4. Compose team-scoped worker instructions file at:
   • .omx/state/team/<team>/worker-agents.md
   • Uses project AGENTS.md content (if present) + worker overlay, without mutating project AGENTS.md
5. Resolve canonical shared state root from leader cwd (<leader-cwd>/.omx/state)
6. Split current tmux window into worker panes
7. Launch workers with:
   • OMX_TEAM_WORKER=<team>/worker-<n>
   • OMX_TEAM_STATE_ROOT=<leader-cwd>/.omx/state
   • OMX_TEAM_LEADER_CWD=<leader-cwd>
   • worker CLI selected by OMX_TEAM_WORKER_CLI / OMX_TEAM_WORKER_CLI_MAP (codex or claude)
   • optional worktree metadata envs when --worktree is used
8. Wait for worker readiness (capture-pane polling)
9. Write per-worker inbox.md and trigger via tmux send-keys
10. Return control to leader; follow-up uses status / resume / shutdown

If coarse active team mode state is missing while canonical team runtime state exists, restore/sync the active team mode state before relying on hook/mode-aware behavior.

Important:

• Leader remains in existing pane
• Worker panes are independent full Codex/Claude CLI sessions
• Workers may run in separate git worktrees (omx team --worktree[=<name>]) while sharing one team state root
• Worker ACKs go to mailbox/leader-fixed.json
• Notify hook updates worker heartbeat and nudges leader during active team mode
• Submit routing uses this CLI resolution order per worker trigger:
  1. explicit worker CLI provided by runtime state (persisted on worker identity/config),
  2. OMX_TEAM_WORKER_CLI_MAP entry for that worker index,
  3. fallback OMX_TEAM_WORKER_CLI / auto detection.
• Mixed CLI-map teams are supported for both startup and trigger submit behavior.
• Trigger submit differs by CLI:
  • Codex may use queue-first Tab on busy panes (strategy-dependent).
  • Claude always uses direct Enter-only (C-m) rounds (never queue-first Tab).

Team worker model + thinking resolution (current contract)

Team mode resolves worker model flags from one shared launch-arg set (not per-worker model selection).

Model precedence (highest to lowest):

1. Explicit worker model in OMX_TEAM_WORKER_LAUNCH_ARGS
2. Inherited leader --model flag
3. Low-complexity default from OMX_DEFAULT_SPARK_MODEL (legacy alias: OMX_SPARK_MODEL) when 1+2 are absent and team agentType is low-complexity

Default-model rule:

• Do not assume a frontier or spark model from recency or model-family heuristics.
• Use OMX_DEFAULT_FRONTIER_MODEL for frontier-default guidance.
• Use OMX_DEFAULT_SPARK_MODEL for spark/low-complexity worker-default guidance.

Thinking-level rule (critical):

• No model-name heuristic mapping.
• Team runtime must not infer model_reasoning_effort from model-name substrings (e.g., spark, high-capability, mini).
• When the leader assigns teammate roles/tasks, OMX allocates per-worker reasoning effort dynamically from the resolved worker role (low, medium, high).
• Explicit launch args still win: if OMX_TEAM_WORKER_LAUNCH_ARGS already includes -c model_reasoning_effort=..., that explicit value overrides dynamic allocation for every worker.

Normalization requirements:

• Parse both --model <value> and --model=<value>
• Remove d

Content truncated.