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. In Codex App or plain outside-tmux sessions, do not present $team / omx team as directly available; launch OMX CLI from shell first, or stay on the nearest app-safe surface until the user explicitly wants the tmux runtime.

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.6 Guidance Alignment

Use the shared workflow guidance pattern: outcome-first framing, concise visible updates for multi-step work, local overrides for the active workflow branch, validation proportional to risk, explicit stop rules, and automatic continuation for safe reversible steps. Ask only for material, destructive, credentialed, external-production, or preference-dependent branches.

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.

Team Big Five / ATEM coordination gate

$team keeps simple independent fan-out lightweight. For isolated tasks (for example per-file sweeps, typo/copy edits, or explicitly independent lanes with no shared files/dependencies), workers use the normal concise protocol: startup ACK, claim-safe task lifecycle, status, verification, and completion evidence.

Activate the lightweight Team Big Five + ATEM-inspired coordination layer when the task or task graph has dependencies, shared files/surfaces/contracts, cross-boundary ownership, handoffs, integration/merge work, blocked lanes, or changed assumptions. The protocol is not a separate ceremony; it is a concise boundary checklist:

• Shared mental model / single source of truth: task JSON, inbox, mailbox, approved handoff, and leader updates are canonical.
• Closed-loop communication / ACK-readback handoffs: acknowledge handoffs with understood scope, affected artifact/path, owner, and next action.
• Mutual performance monitoring at boundaries: check upstream/downstream contracts, shared files, and verification evidence before completion.
• Backup/reassignment behavior: blocked workers report the smallest needed help/reassignment request and continue safe unblocked slices.
• Adaptability checkpoints: changed assumptions, dependencies, or verification results trigger a brief leader-facing update before widening scope.
• Team orientation: workers optimize for the integrated team outcome, not local-optimum-only task summaries; report integration risks, missing tests, and peer impacts.

ATEM fit: treat this as agile teamwork support for transition/action/interpersonal moments around boundaries, not as a heavyweight process model. Do not copy provider-specific plugin implementations; keep the protocol in OMX/Codex prompts, inboxes, state, and tests.

Team + Ultragoal bridge

Use $ultragoal for durable leader-owned goal/ledger tracking and $team for parallel execution lanes. When Team is launched with an active .omx/ultragoal/goals.json, worker inboxes/status may include leader-owned Ultragoal context: .omx/ultragoal/goals.json, .omx/ultragoal/ledger.jsonl, the active goal id, Codex goal mode, and the fresh_leader_get_goal_required checkpoint policy.

Workers provide task status and verification evidence only. They do not own Ultragoal goal state, create worker ledgers, mutate .omx/ultragoal, auto-launch Team from Ultragoal, or perform hidden Codex goal mutation. The leader uses terminal Team evidence plus a fresh get_goal snapshot to run omx ultragoal checkpoint --goal-id <id> --status complete --evidence "<team evidence mentioning .omx/ultragoal and <id>>" --codex-goal-json <fresh-get_goal-json-or-path>.

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 $ultragoal as the default durable follow-up/ledger path; mention a later separate Ralph follow-up only when explicitly requested or genuinely needed as a fallback
• 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 sends lifecycle-driven leader nudges (for example resolved native worker Stop/all-idle or stale-leader evidence) during active team mode; deprecated worker stall/progress heuristics are not operator-facing guidance.
• 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 (for example spark, high-capability, or mini).
• OMX-owned agentReasoning accepts exactly low, medium, high, xhigh, and max; configured values are case-normalized.
• Without explicit raw reasoning, Team selects the resolved role default or valid agentReasoning override for each worker.
• max is passed to Codex unchanged. Its support is capability-dependent on the selected Codex version, model, and provider; preserve authoritative downstream errors.
• ultra is unsupported in OMX-owned agentReasoning and is not an alias for configured max. Other invalid configured values retain the built-in role-default fallback.
• Explicit raw -c model_reasoning_effort=... is opaque and wins over configured and built-in role defaults, including ultra and future values. Preserve the selected raw token exactly.
• When both sources provide explicit raw reasoning, inherited Team reasoning wins over environment reasoning. Explicit raw reasoning always wins over the role default.
• Do not downgrade or retry max as xhigh; built-in role defaults remain unchanged.

Normalization requirements:

• Parse both --model <value> and --model=<value>.
• Remove duplicate/conflicting model flags.
• Emit exactly one final canonical flag: --model <value>.
• Preserve unrelated args in worker launch config.
• Preserve the selected explicit raw -c model_reasoning_effort=... token exactly; otherwise inject the worker role's default or agentReasoning-overridden reasoning level.

Required Lifecycle (Operator Contract)

Follow this exact lifecycle when running $team:

1. Start team and verify startup evidence (team line, tmux target, panes, ACK mailbox)
2. Monitor task and worker progress with runtime/state tools first (omx team status <team>, omx team resume <team>, mailbox/state files)
3. Wait for terminal task state before shutdown:
   • pending=0
   • in_progress=0
   • failed=0 (or explicitly acknowledged failure path)
4. Only then run omx team shutdown <team>
5. Verify shutdown evidence and state cleanup

Do not run shutdown while workers are actively writing updates unless user explicitly requested abort/cancel. Do not treat ad-hoc pane typing as primary control flow when runtime/state evidence is available.

Active leader monitoring rule

While a team is ON/running, the leader must not go blind. Keep checking live team state until terminal completion.

Minimum acceptable loop:

sleep 30 && omx team status <team-name>

Repeat that check while the team stays active, or use omx team await <team-name> --timeout-ms 30000 --json when event-driven waiting is a better fit.

If the leader gets a stale, lifecycle, or all-idle nudge, immediately run omx team status <team-name> before taking any manual intervention. Deprecated worker stall/progress nudges should not be treated as an active runtime contract.