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.5 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 + 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 m

---

Content truncated.