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>/worke

Content truncated.