[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M6XDX2VJCXZ5HRMFYW4S6RWA":3,"skill-same:01M6XDX2VJCXZ5HRMFYW4S6RWA":55},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":23,"publishedAt":30,"linkOnly":31,"markdownContent":32,"markdownBody":33,"frontMatter":34,"refName":35,"commitSha":36,"skillDirectory":37,"forksCount":14,"repositoryHtmlUrl":38,"repositoryHomepageUrl":6,"ownerHtmlUrl":39,"ownerBlogUrl":6,"ownerDescription":6,"updatedAt":40,"install":41,"resources":54},"01M6XDX2VJCXZ5HRMFYW4S6RWA","team",null,"N coordinated agents on shared task list using tmux-based orchestration","sapsapshen\u002Fai-memory-router","sapsapshen","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F20347959?v=4","01M6XDQEF1DP50DKF37H81J3J5","shenmian","01M6XDQEJPE41Y3DT2763X8ZJN",0,"MIT","https:\u002F\u002Fgithub.com\u002Fsapsapshen\u002Fai-memory-router\u002Fblob\u002Fmain\u002Fskills-store\u002Fcodex\u002Fteam\u002FSKILL.md",[18],{"categoryNo":19,"categoryName":20,"taxonomyType":21,"taxonomyTypeDesc":22},"01JBSEEDCAT000000000000023","Skill与智能体开发","SCENARIO","使用场景",[5,24,25,26,27,28,29],"tmux","orchestration","list","task","shared","task list","2026-11-10 10:12:30",false,"---\nname: team\ndescription: N coordinated agents on shared task list using tmux-based orchestration\n---\n\n# Team Skill\n\n`$team` is the tmux-based parallel execution mode for OMX. It starts real worker Codex and\u002For Claude CLI sessions in split panes and coordinates them through `.omx\u002Fstate\u002Fteam\u002F...` files plus CLI team interop (`omx team api ...`) and state files.\n\nThis skill is operationally sensitive. Treat it as an operator workflow, not a generic prompt pattern.\n\n## Team vs Native Subagents\n\n- 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.\n- Use **`omx team`** when you need durable tmux workers, shared task state, mailbox\u002Fdispatch coordination, worktrees, explicit lifecycle control, or long-running parallel execution that must survive beyond one local reasoning burst.\n- Native subagents can complement team\u002Fralph execution, but they do **not** replace the tmux team runtime's stateful coordination contract.\n\n## What This Skill Must Do\n\n## GPT-5.4 Guidance Alignment\n\n- Default to concise, evidence-dense progress and completion reporting unless the user or risk level requires more detail.\n- Treat newer user task updates as local overrides for the active workflow branch while preserving earlier non-conflicting constraints.\n- If correctness depends on additional inspection, retrieval, execution, or verification, keep using the relevant tools until the team workflow is grounded.\n- Continue through clear, low-risk, reversible next steps automatically; ask only when the next step is materially branching, destructive, or preference-dependent.\n\nWhen user triggers `$team`, the agent must:\n\n1. Invoke OMX runtime directly with `omx team ...`\n2. Avoid replacing the flow with in-process `spawn_agent` fanout\n3. Verify startup and surface concrete state\u002Fpane evidence\n4. Keep team state alive until workers are terminal (unless explicit abort)\n5. Handle cleanup and stale-pane recovery when needed\n\nIf `omx team` is unavailable, stop with a hard error.\n\n## Invocation Contract\n\n```bash\nomx team [N:agent-type] \"\u003Ctask description>\"\n```\n\nExamples:\n\n```bash\nomx team 3:executor \"analyze feature X and report flaws\"\nomx team \"debug flaky integration tests\"\nomx team \"ship end-to-end fix with verification\"\n```\n\n### Team-first launch contract\n\n`omx team ...` is now the canonical launch path for coordinated execution.\nTeam mode should carry its own parallel delivery + verification lanes without\nrequiring a separate linked Ralph launch up front.\n\n- **Canonical launch:** use plain `omx team ...` \u002F `$team ...` for coordinated workers.\n- **Verification ownership:** keep one lane focused on tests, regression coverage, and evidence before shutdown.\n- **Escalation:** start a separate `omx ralph ...` \u002F `$ralph ...` only when a later manual follow-up still needs a persistent single-owner fix\u002Fverification loop.\n- **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.\n\n### Claude teammates (v0.6.0+)\n\nImportant: `N:agent-type` (for example `2:executor`) selects the **worker role prompt**, not the worker CLI (`codex` vs `claude`).\n\nTo launch Claude teammates, use the team worker CLI env vars:\n\n```bash\n# Force all teammates to Claude CLI\nOMX_TEAM_WORKER_CLI=claude omx team 2:executor \"update docs and report\"\n\n# Mixed team (worker 1 = Codex, worker 2 = Claude)\nOMX_TEAM_WORKER_CLI_MAP=codex,claude omx team 2:executor \"split doc\u002Fcode tasks\"\n\n# Auto mode: Claude is selected when worker launch args\u002Fmodel contains 'claude'\nOMX_TEAM_WORKER_CLI=auto OMX_TEAM_WORKER_LAUNCH_ARGS=\"--model claude-...\" omx team 2:executor \"run mixed validation\"\n```\n\n## Preconditions\n\nBefore running `$team`, confirm:\n\n1. `tmux` installed (`tmux -V`)\n2. Current leader session is inside tmux (`$TMUX` is set)\n3. `omx` command resolves to the intended install\u002Fbuild\n4. If running repo-local `node bin\u002Fomx.js ...`, run `npm run build` after `src` changes\n5. Check HUD pane count in the leader window and avoid duplicate `hud --watch` panes before split\n\nSuggested preflight:\n\n```bash\ntmux list-panes -F '#{pane_id}\\t#{pane_start_command}' | rg 'hud --watch' || true\n```\n\nIf duplicates exist, remove extras before `omx team` to prevent HUD ending up in worker stack.\n\n## Pre-context Intake Gate\n\nBefore launching `omx team`, require a grounded context snapshot:\n\n1. Derive a task slug from the request.\n2. Reuse the latest relevant snapshot in `.omx\u002Fcontext\u002F{slug}-*.md` when available.\n3. If none exists, create `.omx\u002Fcontext\u002F{slug}-{timestamp}.md` (UTC `YYYYMMDDTHHMMSSZ`) with:\n   - task statement\n   - desired outcome\n   - known facts\u002Fevidence\n   - constraints\n   - unknowns\u002Fopen questions\n   - likely codebase touchpoints\n4. If ambiguity remains high, run `explore` first for brownfield facts, then run `$deep-interview --quick \u003Ctask>` before team launch.\n\nDo not start worker panes until this gate is satisfied; if forced to proceed quickly, state explicit scope\u002Frisk limitations in the launch report.\n\nFor 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.\n\n## Follow-up Staffing Contract\n\nWhen `$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:\n\n- keep worker-role choices inside the known roster\n- state the recommended headcount and role counts\n- state the suggested reasoning level for each lane when available\n- explain why each lane exists (delivery, verification, specialist support)\n- include an explicit launch hint (`omx team N \"\u003Ctask>\"` \u002F `$team N \"\u003Ctask>\"`) for the coordinated team run; mention a later separate Ralph follow-up only when genuinely needed\n- if the ideal role is unavailable, choose the closest role from the roster and say so\n\n## Current Runtime Behavior (As Implemented)\n\n`omx team` currently performs:\n\n1. Parse args (`N`, `agent-type`, task)\n2. Sanitize team name from task text\n3. Initialize team state:\n   - `.omx\u002Fstate\u002Fteam\u002F\u003Cteam>\u002Fconfig.json`\n   - `.omx\u002Fstate\u002Fteam\u002F\u003Cteam>\u002Fmanifest.v2.json`\n   - `.omx\u002Fstate\u002Fteam\u002F\u003Cteam>\u002Ftasks\u002Ftask-\u003Cid>.json`\n4. Compose team-scoped worker instructions file at:\n   - `.omx\u002Fstate\u002Fteam\u002F\u003Cteam>\u002Fworker-agents.md`\n   - Uses project `AGENTS.md` content (if present) + worker overlay, without mutating project `AGENTS.md`\n5. Resolve canonical shared state root from leader cwd (`\u003Cleader-cwd>\u002F.omx\u002Fstate`)\n6. Split current tmux window into worker panes\n7. Launch workers with:\n   - `OMX_TEAM_WORKER=\u003Cteam>\u002Fworker-\u003Cn>`\n   - `OMX_TEAM_STATE_ROOT=\u003Cleader-cwd>\u002F.omx\u002Fstate`\n   - `OMX_TEAM_LEADER_CWD=\u003Cleader-cwd>`\n   - worker CLI selected by `OMX_TEAM_WORKER_CLI` \u002F `OMX_TEAM_WORKER_CLI_MAP` (`codex` or `claude`)\n   - optional worktree metadata envs when `--worktree` is used\n7. Wait for worker readiness (`capture-pane` polling)\n8. Write per-worker `inbox.md` and trigger via `tmux send-keys`\n9. Return control to leader; follow-up uses `status` \u002F `resume` \u002F `shutdown`\n\nImportant:\n\n- Leader remains in existing pane\n- Worker panes are independent full Codex\u002FClaude CLI sessions\n- Workers may run in separate git worktrees (`omx team --worktree[=\u003Cname>]`) while sharing one team state root\n- Worker ACKs go to `mailbox\u002Fleader-fixed.json`\n- Notify hook updates worker heartbeat and nudges leader during active team mode\n- Submit routing uses this CLI resolution order per worker trigger:\n  1) explicit worker CLI provided by runtime state (persisted on worker identity\u002Fconfig),\n  2) `OMX_TEAM_WORKER_CLI_MAP` entry for that worker index,\n  3) fallback `OMX_TEAM_WORKER_CLI` \u002F auto detection.\n- Mixed CLI-map teams are supported for both startup and trigger submit behavior.\n- Trigger submit differs by CLI:\n  - Codex may use queue-first `Tab` on busy panes (strategy-dependent).\n  - Claude always uses direct Enter-only (`C-m`) rounds (never queue-first `Tab`).\n\n### Team worker model + thinking resolution (current contract)\n\nTeam mode resolves worker **model flags** from one shared launch-arg set (not per-worker model selection).\n\nModel precedence (highest to lowest):\n1. Explicit worker model in `OMX_TEAM_WORKER_LAUNCH_ARGS`\n2. Inherited leader `--model` flag\n3. Low-complexity default from `OMX_DEFAULT_SPARK_MODEL` (legacy alias: `OMX_SPARK_MODEL`) when 1+2 are absent and team `agentType` is low-complexity\n\nDefault-model rule:\n- Do **not** assume a frontier or spark model from recency or model-family heuristics.\n- Use `OMX_DEFAULT_FRONTIER_MODEL` for frontier-default guidance.\n- Use `OMX_DEFAULT_SPARK_MODEL` for spark\u002Flow-complexity worker-default guidance.\n\nThinking-level rule (critical):\n- **No model-name heuristic mapping.**\n- Team runtime must **not** infer `model_reasoning_effort` from model-name substrings (e.g., `spark`, `high-capability`, `mini`).\n- When the leader assigns teammate roles\u002Ftasks, OMX allocates **per-worker reasoning effort dynamically** from the resolved worker role (`low`, `medium`, `high`).\n- 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.\n\nNormalization requirements:\n- Parse both `--model \u003Cvalue>` and `--model=\u003Cvalue>`\n- Remove duplicate\u002Fconflicting model flags\n- Emit exactly one final canonical flag: `--model \u003Cvalue>`\n- Preserve unrelated args in worker launch config\n- If explicit reasoning exists, preserve canonical `-c model_reasoning_effort=\"\u003Clevel>\"`; otherwise inject the worker role's default reasoning level\n\n## Required Lifecycle (Operator Contract)\n\nFollow this exact lifecycle when running `$team`:\n\n1. Start team and verify startup evidence (team line, tmux target, panes, ACK mailbox)\n2. Monitor task and worker progress with runtime\u002Fstate tools first (`omx team status \u003Cteam>`, `omx team resume \u003Cteam>`, mailbox\u002Fstate files)\n3. Wait for terminal task state before shutdown:\n   - `pending=0`\n   - `in_progress=0`\n   - `failed=0` (or explicitly acknowledged failure path)\n4. Only then run `omx team shutdown \u003Cteam>`\n5. Verify shutdown evidence and state cleanup\n\nDo not run `shutdown` while workers are actively writing updates unless user explicitly requested abort\u002Fcancel.\nDo not treat ad-hoc pane typing as primary control flow when runtime\u002Fstate evidence is available.\n\n### Active leader monitoring rule\n\nWhile a team is **ON\u002Frunning**, the leader must not go blind. Keep checking live team state until terminal completion.\n\nMinimum acceptable loop:\n\n```bash\nsleep 30 && omx team status \u003Cteam-name>\n```\n\nRepeat that check while the team stays active, or use `omx team await \u003Cteam-name> --timeout-ms 30000 --json` when event-driven waiting is a better fit.\n\nIf the leader gets a stale\u002Fteam-stalled nudge, immediately run `omx team status \u003Cteam-name>` before taking any manual intervention.\n\n## Message Dispatch Policy (CLI-first, state-first)\n\nTo avoid brittle behavior, **message\u002Ftask delivery must not be driven by ad-hoc tmux typing**.\n\nRequired default path:\n\n1. Use `omx team ...` runtime lifecycle commands for orchestration.\n2. Use `omx team api ... --json` for mailbox\u002Ftask mutations.\n3. Verify delivery via mailbox\u002Fstate evidence (`mailbox\u002F*.json`, task status, `omx team status`).\n\nStrict rules:\n\n- **MUST NOT** use direct `tmux send-keys` as the primary mechanism to deliver instructions\u002Fmessages.\n- **MUST NOT** spam Enter\u002Ftrigger keys without first checking runtime\u002Fstate evidence.\n- **MUST** prefer durable state writes + runtime dispatch (`dispatch\u002Frequests.json`, mailbox, inbox).\n- Direct tmux interaction is **fallback-only** and only after failure checks (for example `worker_notify_failed:\u003Cworker>`) or explicit user request (for example “press enter”).\n\n## Operational Commands\n\n```bash\nomx team status \u003Cteam-name>\nomx team resume \u003Cteam-name>\nomx team shutdown \u003Cteam-name>\n```\n\nSemantics:\n\n- `status`: reads team snapshot (task counts, dead\u002Fnon-reporting workers)\n- `resume`: reconnects to live team session if present\n- `shutdown`: graceful shutdown request, then cleanup (deletes `.omx\u002Fstate\u002Fteam\u002F\u003Cteam>`)\n\n## Data Plane and Control Plane\n\n### Control Plane\n\n- tmux panes\u002Fprocesses (`OMX_TEAM_WORKER` per worker)\n- leader notifications via `tmux display-message`\n\n### Data Plane\n\n- `.omx\u002Fstate\u002Fteam\u002F\u003Cteam>\u002F...` files\n- Team mailbox files:\n- `.omx\u002Fstate\u002Fteam\u002F\u003Cteam>\u002Fmailbox\u002Fleader-fixed.json`\n- `.omx\u002Fstate\u002Fteam\u002F\u003Cteam>\u002Fmailbox\u002Fworker-\u003Cn>.json`\n- `.omx\u002Fstate\u002Fteam\u002F\u003Cteam>\u002Fdispatch\u002Frequests.json` (durable dispatch queue; hook-preferred, fallback-aware)\n\n### Key Files\n\n- `.omx\u002Fstate\u002Fteam\u002F\u003Cteam>\u002Fconfig.json`\n- `.omx\u002Fstate\u002Fteam\u002F\u003Cteam>\u002Fmanifest.v2.json`\n- `.omx\u002Fstate\u002Fteam\u002F\u003Cteam>\u002Ftasks\u002Ftask-\u003Cid>.json`\n- `.omx\u002Fstate\u002Fteam\u002F\u003Cteam>\u002Fworkers\u002Fworker-\u003Cn>\u002Fidentity.json`\n- `.omx\u002Fstate\u002Fteam\u002F\u003Cteam>\u002Fworkers\u002Fworker-\u003Cn>\u002Finbox.md`\n- `.omx\u002Fstate\u002Fteam\u002F\u003Cteam>\u002Fworkers\u002Fworker-\u003Cn>\u002Fheartbeat.json`\n- `.omx\u002Fstate\u002Fteam\u002F\u003Cteam>\u002Fworkers\u002Fworker-\u003Cn>\u002Fstatus.json`\n- `.omx\u002Fstate\u002Fteam-leader-nudge.json`\n\n\n## Team Mutation Interop (CLI-first)\n\nUse `omx team api` for machine-readable mutation\u002Freads instead of legacy `team_*` MCP tools.\n\n```bash\nomx team api \u003Coperation> --input '{\"team_name\":\"my-team\",...}' --json\n```\n\nExamples:\n\n```bash\nomx team api send-message --input '{\"team_name\":\"my-team\",\"from_worker\":\"worker-1\",\"to_worker\":\"leader-fixed\",\"body\":\"ACK\"}' --json\nomx team api claim-task --input '{\"team_name\":\"my-team\",\"task_id\":\"1\",\"worker\":\"worker-1\"}' --json\nomx team api transition-task-status --input '{\"team_name\":\"my-team\",\"task_id\":\"1\",\"from\":\"in_progress\",\"to\":\"completed\",\"claim_token\":\"\u003Ctoken>\"}' --json\n```\n\n`--json` responses include stable metadata for automation:\n- `schema_version`\n- `timestamp`\n- `command`\n- `ok`\n- `operation`\n- `data` or `error`\n\n## Team + Worker Protocol Notes\n\nLeader-to-worker:\n\n- Write full assignment to worker `inbox.md`\n- Send short trigger (\u003C200 chars) with `tmux send-keys`\n\nWorker-to-leader:\n\n- Send ACK to `leader-fixed` mailbox via `omx team api send-message --json`\n- Claim\u002Ftransition\u002Frelease task lifecycle via `omx team api \u003Coperation> --json`\n\nWorker commit protocol (critical for incremental integration):\n\n- After completing task work and before reporting completion, workers MUST commit:\n  `git add -A && git commit -m \"task: \u003Ctask-subject>\"`\n- This ensures changes are available for incremental integration into the leader branch\n- If a worker forgets to commit, the runtime auto-commits as a fallback, but explicit commits are preferred\n\nTask ID rule (critical):\n\n- File path uses `task-\u003Cid>.json` (example `task-1.json`)\n- MCP API `task_id` uses bare id (example `\"1\"`, not `\"task-1\"`)\n- Never instruct workers to read `tasks\u002F{id}.json`\n\n## Environment Knobs\n\nUseful runtime env vars:\n\n- `OMX_TEAM_READY_TIMEOUT_MS`\n  - Worker readiness timeout (default 45000)\n- `OMX_TEAM_SKIP_READY_WAIT=1`\n  - Skip readiness wait (debug only)\n- `OMX_TEAM_AUTO_TRUST=0`\n  - Disable auto-advance for trust prompt (default behavior auto-advances)\n- `OMX_TEAM_AUTO_ACCEPT_BYPASS=0`\n  - Disable Claude bypass-permissions prompt auto-accept (default behavior auto-accepts `2` + Enter)\n- `OMX_TEAM_WORKER_LAUNCH_ARGS`\n  - Extra args passed to worker launch command\n- `OMX_TEAM_WORKER_CLI`\n  - Worker CLI selector: `auto|codex|claude` (default: `auto`)\n  - `auto` chooses `claude` when worker `--model` contains `claude`, otherwise `codex`\n  - In `claude` mode, workers launch with exactly one `--dangerously-skip-permissions`\n    and ignore explicit model\u002Fconfig\u002Feffort launch overrides (uses default `settings.json`)\n- `OMX_TEAM_WORKER_CLI_MAP`\n  - Per-worker CLI selector (comma-separated `auto|codex|claude`)\n  - Length must be `1` (broadcast) or exactly the team worker count\n  - Example: `OMX_TEAM_WORKER_CLI_MAP=codex,codex,claude,claude`\n  - When present, overrides `OMX_TEAM_WORKER_CLI`\n- `OMX_TEAM_AUTO_INTERRUPT_RETRY`\n  - Trigger submit fallback (default: enabled)\n  - `0` disables adaptive queue->resend escalation\n- `OMX_TEAM_LEADER_NUDGE_MS`\n  - Leader nudge interval in ms (default 120000)\n- `OMX_TEAM_STRICT_SUBMIT=1`\n  - Force strict send-keys submit failure behavior\n\n## Failure Modes and Diagnosis\n\nOperator note (important for Claude panes):\n- Manual Enter injection (`tmux send-keys ... C-m`) can appear to \"do nothing\" when a worker is actively processing; Enter may be queued by the pane\u002Ftask flow.\n- This is not necessarily a runtime bug. Confirm worker\u002Fteam state before diagnosing dispatch failure.\n- Avoid repeated blind Enter spam; it can create noisy duplicate submits once the pane becomes idle.\n\n### Safe Manual Intervention (last resort)\n\nUse only after checking `omx team status \u003Cteam>` and mailbox\u002Fstate evidence:\n\n1. Capture pane tail to confirm current worker state:\n   - `tmux capture-pane -t %\u003Cworker-pane> -p -S -120`\n   - If a larger-tail read or bounded summary would help, prefer explicit opt-in inspection via `omx sparkshell --tmux-pane %\u003Cworker-pane> --tail-lines 400` before improvising extra tmux commands.\n2. If the pane is stuck in an interactive state, safely return to idle prompt first:\n   - optional interrupt `C-c` or escape flow (CLI-specific) once, then re-check pane capture\n3. Send one concise trigger (single line) and wait for evidence:\n   - `tmux send-keys -t %\u003Cworker-pane> \"ack + continue current task; report status\" C-m`\n4. Re-check:\n   - pane output via `capture-pane`\n   - mailbox updates (`mailbox\u002Fleader-fixed.json` or worker mailbox)\n   - `omx team status \u003Cteam>`\n\n### `worker_notify_failed:\u003Cworker>`\n\nMeaning:\n- Leader wrote inbox but trigger submit path failed\n\nChecks:\n\n1. `tmux list-panes -F '#{pane_id}\\t#{pane_start_command}'`\n2. `tmux capture-pane -t %\u003Cworker-pane> -p -S -120`\n3. Verify worker process alive and not stuck on trust prompt\n4. Rebuild if running repo-local (`npm run build`)\n\n### Team starts but leader gets no ACK\n\nChecks:\n\n1. Worker pane capture shows inbox processing\n2. `.omx\u002Fstate\u002Fteam\u002F\u003Cteam>\u002Fmailbox\u002Fleader-fixed.json` exists\n3. Worker skill loaded and `omx team api send-message --json` called\n4. Task-id mismatch not blocking worker flow\n\n### Worker logs `omx team api ... ENOENT` (or legacy `team_send_message ENOENT` \u002F `team_update_task ENOENT`)\n\nMeaning:\n- Team state path no longer exists while worker is still running.\n- Typical cause: leader\u002Fmanual flow ran `omx team shutdown \u003Cteam>` (or removed `.omx\u002Fstate\u002Fteam\u002F\u003Cteam>`) before worker finished.\n\nChecks:\n\n1. `omx team status \u003Cteam>` and confirm whether tasks were still `in_progress` when shutdown occurred\n2. Verify whether `.omx\u002Fstate\u002Fteam\u002F\u003Cteam>\u002F` exists\n3. Inspect worker pane tail for post-shutdown writes\n4. Confirm no external cleanup (`rm -rf .omx\u002Fstate\u002Fteam\u002F\u003Cteam>`) happened during execution\n\nPrevention:\n\n1. Enforce completion gate (no in-progress tasks) before shutdown\n2. Use `shutdown` only for terminal completion or explicit abort\n3. If aborting, expect late worker writes to fail and treat ENOENT as expected teardown artifact\n\n### Shutdown reports success but stale worker panes remain\n\nCause:\n- stale pane outside config tracking or previous failed run\n\nFix:\n- manual pane cleanup (see clean-slate commands)\n\n## Clean-Slate Recovery\n\nRun from leader pane:\n\n```bash\n# 1) Inspect panes\ntmux list-panes -F '#{pane_id}\\t#{pane_current_command}\\t#{pane_start_command}'\n\n# 2) Kill stale worker panes only (examples)\ntmux kill-pane -t %450\ntmux kill-pane -t %451\n\n# 3) Remove stale team state (example)\nrm -rf .omx\u002Fstate\u002Fteam\u002F\u003Cteam-name>\n\n# 4) Retry\nomx team 1:executor \"fresh retry\"\n```\n\nGuidelines:\n\n- Do not kill leader pane\n- Do not kill HUD pane (`omx hud --watch`) unless intentionally restarting HUD\n\n## Required Reporting During Execution\n\nWhen operating this skill, provide concrete progress evidence:\n\n1. Team started line (`Team started: \u003Cname>`)\n2. tmux target and worker pane presence\n3. leader mailbox ACK path\u002Fcontent check\n4. status\u002Fshutdown outcomes\n\nDo not claim success without file\u002Fpane evidence.\nDo not claim clean completion if shutdown occurred with `in_progress>0`.\nUse `omx sparkshell --tmux-pane ...` as an explicit opt-in operator aid for pane inspection and summaries; keep raw `tmux capture-pane` evidence available for manual intervention and proof.\n\n## MCP Job Lifecycle Tools\n\nFor programmatic or agent-driven team spawning (as opposed to interactive CLI use), OMX exposes four MCP tools via the `team-server`:\n\n| Tool | Description |\n|------|-------------|\n| `omx_run_team_start` | Spawn tmux CLI workers in the background; returns a `jobId` immediately |\n| `omx_run_team_status` | Non-blocking status check for a running job |\n| `omx_run_team_wait` | Block until the job completes, with automatic idle-pane nudging |\n| `omx_run_team_cleanup` | Kill worker tmux panes for a job (early stop only) |\n\n### CLI vs MCP Tools\n\n- **`omx team ...` CLI** — Primary method for interactive team orchestration. Use this when you are operating inside a live tmux session and want direct pane visibility.\n- **`omx_run_team_*` MCP tools** — For programmatic or agent-driven team spawning (analogous to OMC's `omc_run_team_*` tools). Use these when an agent needs to launch workers, poll status, and collect results without manual intervention.\n\n### Naming Distinction\n\nTwo cleanup tools exist and must not be confused:\n\n- `team_cleanup` (**state-server**): Deletes team state **files** on disk (`.omx\u002Fstate\u002Fteam\u002F\u003Cteam>\u002F`). Use after a team run is fully complete.\n- `omx_run_team_cleanup` (**team-server**): Kills tmux worker **panes** for a job. Use only when stopping workers early; otherwise `omx_run_team_wait` handles natural termination.\n\n### Basic Usage Example\n\n```\n1. omx_run_team_start({\n     teamName: \"fix-bugs\",\n     agentTypes: [\"codex\"],\n     tasks: [{ subject: \"Fix bug\", description: \"...\" }],\n     cwd: \"\u002Fpath\u002Fto\u002Fproject\"\n   })\n   → Returns { jobId: \"omx-abc123\" }\n\n2. omx_run_team_wait({ job_id: \"omx-abc123\", timeout_ms: 300000 })\n   → Blocks until done, auto-nudges idle panes\n\n3. omx_run_team_cleanup({ job_id: \"omx-abc123\" })\n   → Only needed if stopping workers early\n```\n\n`omx_run_team_status` can be called between steps 1 and 2 for a non-blocking poll if you need to interleave other work while workers run.\n\n## Limitations\n\n- Worktree provisioning requires a git repository and can fail on branch\u002Fpath collisions\n- send-keys interactions can be timing-sensitive under load\n- stale panes from prior runs can interfere until manually cleaned\n\n## Scenario Examples\n\n**Good:** The user says `continue` after the workflow already has a clear next step. Continue the current branch of work instead of restarting or re-asking the same question.\n\n**Good:** The user changes only the output shape or downstream delivery step (for example `make a PR`). Preserve earlier non-conflicting workflow constraints and apply the update locally.\n\n**Bad:** The user says `continue`, and the workflow restarts discovery or stops before the missing verification\u002Fevidence is gathered.\n","# Team Skill\n\n`$team` is the tmux-based parallel execution mode for OMX. It starts real worker Codex and\u002For Claude CLI sessions in split panes and coordinates them through `.omx\u002Fstate\u002Fteam\u002F...` files plus CLI team interop (`omx team api ...`) and state files.\n\nThis skill is operationally sensitive. Treat it as an operator workflow, not a generic prompt pattern.\n\n## Team vs Native Subagents\n\n- 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.\n- Use **`omx team`** when you need durable tmux workers, shared task state, mailbox\u002Fdispatch coordination, worktrees, explicit lifecycle control, or long-running parallel execution that must survive beyond one local reasoning burst.\n- Native subagents can complement team\u002Fralph execution, but they do **not** replace the tmux team runtime's stateful coordination contract.\n\n## What This Skill Must Do\n\n## GPT-5.4 Guidance Alignment\n\n- Default to concise, evidence-dense progress and completion reporting unless the user or risk level requires more detail.\n- Treat newer user task updates as local overrides for the active workflow branch while preserving earlier non-conflicting constraints.\n- If correctness depends on additional inspection, retrieval, execution, or verification, keep using the relevant tools until the team workflow is grounded.\n- Continue through clear, low-risk, reversible next steps automatically; ask only when the next step is materially branching, destructive, or preference-dependent.\n\nWhen user triggers `$team`, the agent must:\n\n1. Invoke OMX runtime directly with `omx team ...`\n2. Avoid replacing the flow with in-process `spawn_agent` fanout\n3. Verify startup and surface concrete state\u002Fpane evidence\n4. Keep team state alive until workers are terminal (unless explicit abort)\n5. Handle cleanup and stale-pane recovery when needed\n\nIf `omx team` is unavailable, stop with a hard error.\n\n## Invocation Contract\n\n```bash\nomx team [N:agent-type] \"\u003Ctask description>\"\n```\n\nExamples:\n\n```bash\nomx team 3:executor \"analyze feature X and report flaws\"\nomx team \"debug flaky integration tests\"\nomx team \"ship end-to-end fix with verification\"\n```\n\n### Team-first launch contract\n\n`omx team ...` is now the canonical launch path for coordinated execution.\nTeam mode should carry its own parallel delivery + verification lanes without\nrequiring a separate linked Ralph launch up front.\n\n- **Canonical launch:** use plain `omx team ...` \u002F `$team ...` for coordinated workers.\n- **Verification ownership:** keep one lane focused on tests, regression coverage, and evidence before shutdown.\n- **Escalation:** start a separate `omx ralph ...` \u002F `$ralph ...` only when a later manual follow-up still needs a persistent single-owner fix\u002Fverification loop.\n- **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.\n\n### Claude teammates (v0.6.0+)\n\nImportant: `N:agent-type` (for example `2:executor`) selects the **worker role prompt**, not the worker CLI (`codex` vs `claude`).\n\nTo launch Claude teammates, use the team worker CLI env vars:\n\n```bash\n# Force all teammates to Claude CLI\nOMX_TEAM_WORKER_CLI=claude omx team 2:executor \"update docs and report\"\n\n# Mixed team (worker 1 = Codex, worker 2 = Claude)\nOMX_TEAM_WORKER_CLI_MAP=codex,claude omx team 2:executor \"split doc\u002Fcode tasks\"\n\n# Auto mode: Claude is selected when worker launch args\u002Fmodel contains 'claude'\nOMX_TEAM_WORKER_CLI=auto OMX_TEAM_WORKER_LAUNCH_ARGS=\"--model claude-...\" omx team 2:executor \"run mixed validation\"\n```\n\n## Preconditions\n\nBefore running `$team`, confirm:\n\n1. `tmux` installed (`tmux -V`)\n2. Current leader session is inside tmux (`$TMUX` is set)\n3. `omx` command resolves to the intended install\u002Fbuild\n4. If running repo-local `node bin\u002Fomx.js ...`, run `npm run build` after `src` changes\n5. Check HUD pane count in the leader window and avoid duplicate `hud --watch` panes before split\n\nSuggested preflight:\n\n```bash\ntmux list-panes -F '#{pane_id}\\t#{pane_start_command}' | rg 'hud --watch' || true\n```\n\nIf duplicates exist, remove extras before `omx team` to prevent HUD ending up in worker stack.\n\n## Pre-context Intake Gate\n\nBefore launching `omx team`, require a grounded context snapshot:\n\n1. Derive a task slug from the request.\n2. Reuse the latest relevant snapshot in `.omx\u002Fcontext\u002F{slug}-*.md` when available.\n3. If none exists, create `.omx\u002Fcontext\u002F{slug}-{timestamp}.md` (UTC `YYYYMMDDTHHMMSSZ`) with:\n   - task statement\n   - desired outcome\n   - known facts\u002Fevidence\n   - constraints\n   - unknowns\u002Fopen questions\n   - likely codebase touchpoints\n4. If ambiguity remains high, run `explore` first for brownfield facts, then run `$deep-interview --quick \u003Ctask>` before team launch.\n\nDo not start worker panes until this gate is satisfied; if forced to proceed quickly, state explicit scope\u002Frisk limitations in the launch report.\n\nFor 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.\n\n## Follow-up Staffing Contract\n\nWhen `$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:\n\n- keep worker-role choices inside the known roster\n- state the recommended headcount and role counts\n- state the suggested reasoning level for each lane when available\n- explain why each lane exists (delivery, verification, specialist support)\n- include an explicit launch hint (`omx team N \"\u003Ctask>\"` \u002F `$team N \"\u003Ctask>\"`) for the coordinated team run; mention a later separate Ralph follow-up only when genuinely needed\n- if the ideal role is unavailable, choose the closest role from the roster and say so\n\n## Current Runtime Behavior (As Implemented)\n\n`omx team` currently performs:\n\n1. Parse args (`N`, `agent-type`, task)\n2. Sanitize team name from task text\n3. Initialize team state:\n   - `.omx\u002Fstate\u002Fteam\u002F\u003Cteam>\u002Fconfig.json`\n   - `.omx\u002Fstate\u002Fteam\u002F\u003Cteam>\u002Fmanifest.v2.json`\n   - `.omx\u002Fstate\u002Fteam\u002F\u003Cteam>\u002Ftasks\u002Ftask-\u003Cid>.json`\n4. Compose team-scoped worker instructions file at:\n   - `.omx\u002Fstate\u002Fteam\u002F\u003Cteam>\u002Fworker-agents.md`\n   - Uses project `AGENTS.md` content (if present) + worker overlay, without mutating project `AGENTS.md`\n5. Resolve canonical shared state root from leader cwd (`\u003Cleader-cwd>\u002F.omx\u002Fstate`)\n6. Split current tmux window into worker panes\n7. Launch workers with:\n   - `OMX_TEAM_WORKER=\u003Cteam>\u002Fworker-\u003Cn>`\n   - `OMX_TEAM_STATE_ROOT=\u003Cleader-cwd>\u002F.omx\u002Fstate`\n   - `OMX_TEAM_LEADER_CWD=\u003Cleader-cwd>`\n   - worker CLI selected by `OMX_TEAM_WORKER_CLI` \u002F `OMX_TEAM_WORKER_CLI_MAP` (`codex` or `claude`)\n   - optional worktree metadata envs when `--worktree` is used\n7. Wait for worker readiness (`capture-pane` polling)\n8. Write per-worker `inbox.md` and trigger via `tmux send-keys`\n9. Return control to leader; follow-up uses `status` \u002F `resume` \u002F `shutdown`\n\nImportant:\n\n- Leader remains in existing pane\n- Worker panes are independent full Codex\u002FClaude CLI sessions\n- Workers may run in separate git worktrees (`omx team --worktree[=\u003Cname>]`) while sharing one team state root\n- Worker ACKs go to `mailbox\u002Fleader-fixed.json`\n- Notify hook updates worker heartbeat and nudges leader during active team mode\n- Submit routing uses this CLI resolution order per worker trigger:\n  1) explicit worker CLI provided by runtime state (persisted on worker identity\u002Fconfig),\n  2) `OMX_TEAM_WORKER_CLI_MAP` entry for that worker index,\n  3) fallback `OMX_TEAM_WORKER_CLI` \u002F auto detection.\n- Mixed CLI-map teams are supported for both startup and trigger submit behavior.\n- Trigger submit differs by CLI:\n  - Codex may use queue-first `Tab` on busy panes (strategy-dependent).\n  - Claude always uses direct Enter-only (`C-m`) rounds (never queue-first `Tab`).\n\n### Team worker model + thinking resolution (current contract)\n\nTeam mode resolves worker **model flags** from one shared launch-arg set (not per-worker model selection).\n\nModel precedence (highest to lowest):\n1. Explicit worker model in `OMX_TEAM_WORKER_LAUNCH_ARGS`\n2. Inherited leader `--model` flag\n3. Low-complexity default from `OMX_DEFAULT_SPARK_MODEL` (legacy alias: `OMX_SPARK_MODEL`) when 1+2 are absent and team `agentType` is low-complexity\n\nDefault-model rule:\n- Do **not** assume a frontier or spark model from recency or model-family heuristics.\n- Use `OMX_DEFAULT_FRONTIER_MODEL` for frontier-default guidance.\n- Use `OMX_DEFAULT_SPARK_MODEL` for spark\u002Flow-complexity worker-default guidance.\n\nThinking-level rule (critical):\n- **No model-name heuristic mapping.**\n- Team runtime must **not** infer `model_reasoning_effort` from model-name substrings (e.g., `spark`, `high-capability`, `mini`).\n- When the leader assigns teammate roles\u002Ftasks, OMX allocates **per-worker reasoning effort dynamically** from the resolved worker role (`low`, `medium`, `high`).\n- 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.\n\nNormalization requirements:\n- Parse both `--model \u003Cvalue>` and `--model=\u003Cvalue>`\n- Remove duplicate\u002Fconflicting model flags\n- Emit exactly one final canonical flag: `--model \u003Cvalue>`\n- Preserve unrelated args in worker launch config\n- If explicit reasoning exists, preserve canonical `-c model_reasoning_effort=\"\u003Clevel>\"`; otherwise inject the worker role's default reasoning level\n\n## Required Lifecycle (Operator Contract)\n\nFollow this exact lifecycle when running `$team`:\n\n1. Start team and verify startup evidence (team line, tmux target, panes, ACK mailbox)\n2. Monitor task and worker progress with runtime\u002Fstate tools first (`omx team status \u003Cteam>`, `omx team resume \u003Cteam>`, mailbox\u002Fstate files)\n3. Wait for terminal task state before shutdown:\n   - `pending=0`\n   - `in_progress=0`\n   - `failed=0` (or explicitly acknowledged failure path)\n4. Only then run `omx team shutdown \u003Cteam>`\n5. Verify shutdown evidence and state cleanup\n\nDo not run `shutdown` while workers are actively writing updates unless user explicitly requested abort\u002Fcancel.\nDo not treat ad-hoc pane typing as primary control flow when runtime\u002Fstate evidence is available.\n\n### Active leader monitoring rule\n\nWhile a team is **ON\u002Frunning**, the leader must not go blind. Keep checking live team state until terminal completion.\n\nMinimum acceptable loop:\n\n```bash\nsleep 30 && omx team status \u003Cteam-name>\n```\n\nRepeat that check while the team stays active, or use `omx team await \u003Cteam-name> --timeout-ms 30000 --json` when event-driven waiting is a better fit.\n\nIf the leader gets a stale\u002Fteam-stalled nudge, immediately run `omx team status \u003Cteam-name>` before taking any manual intervention.\n\n## Message Dispatch Policy (CLI-first, state-first)\n\nTo avoid brittle behavior, **message\u002Ftask delivery must not be driven by ad-hoc tmux typing**.\n\nRequired default path:\n\n1. Use `omx team ...` runtime lifecycle commands for orchestration.\n2. Use `omx team api ... --json` for mailbox\u002Ftask mutations.\n3. Verify delivery via mailbox\u002Fstate evidence (`mailbox\u002F*.json`, task status, `omx team status`).\n\nStrict rules:\n\n- **MUST NOT** use direct `tmux send-keys` as the primary mechanism to deliver instructions\u002Fmessages.\n- **MUST NOT** spam Enter\u002Ftrigger keys without first checking runtime\u002Fstate evidence.\n- **MUST** prefer durable state writes + runtime dispatch (`dispatch\u002Frequests.json`, mailbox, inbox).\n- Direct tmux interaction is **fallback-only** and only after failure checks (for example `worker_notify_failed:\u003Cworker>`) or explicit user request (for example “press enter”).\n\n## Operational Commands\n\n```bash\nomx team status \u003Cteam-name>\nomx team resume \u003Cteam-name>\nomx team shutdown \u003Cteam-name>\n```\n\nSemantics:\n\n- `status`: reads team snapshot (task counts, dead\u002Fnon-reporting workers)\n- `resume`: reconnects to live team session if present\n- `shutdown`: graceful shutdown request, then cleanup (deletes `.omx\u002Fstate\u002Fteam\u002F\u003Cteam>`)\n\n## Data Plane and Control Plane\n\n### Control Plane\n\n- tmux panes\u002Fprocesses (`OMX_TEAM_WORKER` per worker)\n- leader notifications via `tmux display-message`\n\n### Data Plane\n\n- `.omx\u002Fstate\u002Fteam\u002F\u003Cteam>\u002F...` files\n- Team mailbox files:\n- `.omx\u002Fstate\u002Fteam\u002F\u003Cteam>\u002Fmailbox\u002Fleader-fixed.json`\n- `.omx\u002Fstate\u002Fteam\u002F\u003Cteam>\u002Fmailbox\u002Fworker-\u003Cn>.json`\n- `.omx\u002Fstate\u002Fteam\u002F\u003Cteam>\u002Fdispatch\u002Frequests.json` (durable dispatch queue; hook-preferred, fallback-aware)\n\n### Key Files\n\n- `.omx\u002Fstate\u002Fteam\u002F\u003Cteam>\u002Fconfig.json`\n- `.omx\u002Fstate\u002Fteam\u002F\u003Cteam>\u002Fmanifest.v2.json`\n- `.omx\u002Fstate\u002Fteam\u002F\u003Cteam>\u002Ftasks\u002Ftask-\u003Cid>.json`\n- `.omx\u002Fstate\u002Fteam\u002F\u003Cteam>\u002Fworkers\u002Fworker-\u003Cn>\u002Fidentity.json`\n- `.omx\u002Fstate\u002Fteam\u002F\u003Cteam>\u002Fworkers\u002Fworker-\u003Cn>\u002Finbox.md`\n- `.omx\u002Fstate\u002Fteam\u002F\u003Cteam>\u002Fworkers\u002Fworker-\u003Cn>\u002Fheartbeat.json`\n- `.omx\u002Fstate\u002Fteam\u002F\u003Cteam>\u002Fworkers\u002Fworker-\u003Cn>\u002Fstatus.json`\n- `.omx\u002Fstate\u002Fteam-leader-nudge.json`\n\n\n## Team Mutation Interop (CLI-first)\n\nUse `omx team api` for machine-readable mutation\u002Freads instead of legacy `team_*` MCP tools.\n\n```bash\nomx team api \u003Coperation> --input '{\"team_name\":\"my-team\",...}' --json\n```\n\nExamples:\n\n```bash\nomx team api send-message --input '{\"team_name\":\"my-team\",\"from_worker\":\"worker-1\",\"to_worker\":\"leader-fixed\",\"body\":\"ACK\"}' --json\nomx team api claim-task --input '{\"team_name\":\"my-team\",\"task_id\":\"1\",\"worker\":\"worker-1\"}' --json\nomx team api transition-task-status --input '{\"team_name\":\"my-team\",\"task_id\":\"1\",\"from\":\"in_progress\",\"to\":\"completed\",\"claim_token\":\"\u003Ctoken>\"}' --json\n```\n\n`--json` responses include stable metadata for automation:\n- `schema_version`\n- `timestamp`\n- `command`\n- `ok`\n- `operation`\n- `data` or `error`\n\n## Team + Worker Protocol Notes\n\nLeader-to-worker:\n\n- Write full assignment to worker `inbox.md`\n- Send short trigger (\u003C200 chars) with `tmux send-keys`\n\nWorker-to-leader:\n\n- Send ACK to `leader-fixed` mailbox via `omx team api send-message --json`\n- Claim\u002Ftransition\u002Frelease task lifecycle via `omx team api \u003Coperation> --json`\n\nWorker commit protocol (critical for incremental integration):\n\n- After completing task work and before reporting completion, workers MUST commit:\n  `git add -A && git commit -m \"task: \u003Ctask-subject>\"`\n- This ensures changes are available for incremental integration into the leader branch\n- If a worker forgets to commit, the runtime auto-commits as a fallback, but explicit commits are preferred\n\nTask ID rule (critical):\n\n- File path uses `task-\u003Cid>.json` (example `task-1.json`)\n- MCP API `task_id` uses bare id (example `\"1\"`, not `\"task-1\"`)\n- Never instruct workers to read `tasks\u002F{id}.json`\n\n## Environment Knobs\n\nUseful runtime env vars:\n\n- `OMX_TEAM_READY_TIMEOUT_MS`\n  - Worker readiness timeout (default 45000)\n- `OMX_TEAM_SKIP_READY_WAIT=1`\n  - Skip readiness wait (debug only)\n- `OMX_TEAM_AUTO_TRUST=0`\n  - Disable auto-advance for trust prompt (default behavior auto-advances)\n- `OMX_TEAM_AUTO_ACCEPT_BYPASS=0`\n  - Disable Claude bypass-permissions prompt auto-accept (default behavior auto-accepts `2` + Enter)\n- `OMX_TEAM_WORKER_LAUNCH_ARGS`\n  - Extra args passed to worker launch command\n- `OMX_TEAM_WORKER_CLI`\n  - Worker CLI selector: `auto|codex|claude` (default: `auto`)\n  - `auto` chooses `claude` when worker `--model` contains `claude`, otherwise `codex`\n  - In `claude` mode, workers launch with exactly one `--dangerously-skip-permissions`\n    and ignore explicit model\u002Fconfig\u002Feffort launch overrides (uses default `settings.json`)\n- `OMX_TEAM_WORKER_CLI_MAP`\n  - Per-worker CLI selector (comma-separated `auto|codex|claude`)\n  - Length must be `1` (broadcast) or exactly the team worker count\n  - Example: `OMX_TEAM_WORKER_CLI_MAP=codex,codex,claude,claude`\n  - When present, overrides `OMX_TEAM_WORKER_CLI`\n- `OMX_TEAM_AUTO_INTERRUPT_RETRY`\n  - Trigger submit fallback (default: enabled)\n  - `0` disables adaptive queue->resend escalation\n- `OMX_TEAM_LEADER_NUDGE_MS`\n  - Leader nudge interval in ms (default 120000)\n- `OMX_TEAM_STRICT_SUBMIT=1`\n  - Force strict send-keys submit failure behavior\n\n## Failure Modes and Diagnosis\n\nOperator note (important for Claude panes):\n- Manual Enter injection (`tmux send-keys ... C-m`) can appear to \"do nothing\" when a worker is actively processing; Enter may be queued by the pane\u002Ftask flow.\n- This is not necessarily a runtime bug. Confirm worker\u002Fteam state before diagnosing dispatch failure.\n- Avoid repeated blind Enter spam; it can create noisy duplicate submits once the pane becomes idle.\n\n### Safe Manual Intervention (last resort)\n\nUse only after checking `omx team status \u003Cteam>` and mailbox\u002Fstate evidence:\n\n1. Capture pane tail to confirm current worker state:\n   - `tmux capture-pane -t %\u003Cworker-pane> -p -S -120`\n   - If a larger-tail read or bounded summary would help, prefer explicit opt-in inspection via `omx sparkshell --tmux-pane %\u003Cworker-pane> --tail-lines 400` before improvising extra tmux commands.\n2. If the pane is stuck in an interactive state, safely return to idle prompt first:\n   - optional interrupt `C-c` or escape flow (CLI-specific) once, then re-check pane capture\n3. Send one concise trigger (single line) and wait for evidence:\n   - `tmux send-keys -t %\u003Cworker-pane> \"ack + continue current task; report status\" C-m`\n4. Re-check:\n   - pane output via `capture-pane`\n   - mailbox updates (`mailbox\u002Fleader-fixed.json` or worker mailbox)\n   - `omx team status \u003Cteam>`\n\n### `worker_notify_failed:\u003Cworker>`\n\nMeaning:\n- Leader wrote inbox but trigger submit path failed\n\nChecks:\n\n1. `tmux list-panes -F '#{pane_id}\\t#{pane_start_command}'`\n2. `tmux capture-pane -t %\u003Cworker-pane> -p -S -120`\n3. Verify worker process alive and not stuck on trust prompt\n4. Rebuild if running repo-local (`npm run build`)\n\n### Team starts but leader gets no ACK\n\nChecks:\n\n1. Worker pane capture shows inbox processing\n2. `.omx\u002Fstate\u002Fteam\u002F\u003Cteam>\u002Fmailbox\u002Fleader-fixed.json` exists\n3. Worker skill loaded and `omx team api send-message --json` called\n4. Task-id mismatch not blocking worker flow\n\n### Worker logs `omx team api ... ENOENT` (or legacy `team_send_message ENOENT` \u002F `team_update_task ENOENT`)\n\nMeaning:\n- Team state path no longer exists while worker is still running.\n- Typical cause: leader\u002Fmanual flow ran `omx team shutdown \u003Cteam>` (or removed `.omx\u002Fstate\u002Fteam\u002F\u003Cteam>`) before worker finished.\n\nChecks:\n\n1. `omx team status \u003Cteam>` and confirm whether tasks were still `in_progress` when shutdown occurred\n2. Verify whether `.omx\u002Fstate\u002Fteam\u002F\u003Cteam>\u002F` exists\n3. Inspect worker pane tail for post-shutdown writes\n4. Confirm no external cleanup (`rm -rf .omx\u002Fstate\u002Fteam\u002F\u003Cteam>`) happened during execution\n\nPrevention:\n\n1. Enforce completion gate (no in-progress tasks) before shutdown\n2. Use `shutdown` only for terminal completion or explicit abort\n3. If aborting, expect late worker writes to fail and treat ENOENT as expected teardown artifact\n\n### Shutdown reports success but stale worker panes remain\n\nCause:\n- stale pane outside config tracking or previous failed run\n\nFix:\n- manual pane cleanup (see clean-slate commands)\n\n## Clean-Slate Recovery\n\nRun from leader pane:\n\n```bash\n# 1) Inspect panes\ntmux list-panes -F '#{pane_id}\\t#{pane_current_command}\\t#{pane_start_command}'\n\n# 2) Kill stale worker panes only (examples)\ntmux kill-pane -t %450\ntmux kill-pane -t %451\n\n# 3) Remove stale team state (example)\nrm -rf .omx\u002Fstate\u002Fteam\u002F\u003Cteam-name>\n\n# 4) Retry\nomx team 1:executor \"fresh retry\"\n```\n\nGuidelines:\n\n- Do not kill leader pane\n- Do not kill HUD pane (`omx hud --watch`) unless intentionally restarting HUD\n\n## Required Reporting During Execution\n\nWhen operating this skill, provide concrete progress evidence:\n\n1. Team started line (`Team started: \u003Cname>`)\n2. tmux target and worker pane presence\n3. leader mailbox ACK path\u002Fcontent check\n4. status\u002Fshutdown outcomes\n\nDo not claim success without file\u002Fpane evidence.\nDo not claim clean completion if shutdown occurred with `in_progress>0`.\nUse `omx sparkshell --tmux-pane ...` as an explicit opt-in operator aid for pane inspection and summaries; keep raw `tmux capture-pane` evidence available for manual intervention and proof.\n\n## MCP Job Lifecycle Tools\n\nFor programmatic or agent-driven team spawning (as opposed to interactive CLI use), OMX exposes four MCP tools via the `team-server`:\n\n| Tool | Description |\n|------|-------------|\n| `omx_run_team_start` | Spawn tmux CLI workers in the background; returns a `jobId` immediately |\n| `omx_run_team_status` | Non-blocking status check for a running job |\n| `omx_run_team_wait` | Block until the job completes, with automatic idle-pane nudging |\n| `omx_run_team_cleanup` | Kill worker tmux panes for a job (early stop only) |\n\n### CLI vs MCP Tools\n\n- **`omx team ...` CLI** — Primary method for interactive team orchestration. Use this when you are operating inside a live tmux session and want direct pane visibility.\n- **`omx_run_team_*` MCP tools** — For programmatic or agent-driven team spawning (analogous to OMC's `omc_run_team_*` tools). Use these when an agent needs to launch workers, poll status, and collect results without manual intervention.\n\n### Naming Distinction\n\nTwo cleanup tools exist and must not be confused:\n\n- `team_cleanup` (**state-server**): Deletes team state **files** on disk (`.omx\u002Fstate\u002Fteam\u002F\u003Cteam>\u002F`). Use after a team run is fully complete.\n- `omx_run_team_cleanup` (**team-server**): Kills tmux worker **panes** for a job. Use only when stopping workers early; otherwise `omx_run_team_wait` handles natural termination.\n\n### Basic Usage Example\n\n```\n1. omx_run_team_start({\n     teamName: \"fix-bugs\",\n     agentTypes: [\"codex\"],\n     tasks: [{ subject: \"Fix bug\", description: \"...\" }],\n     cwd: \"\u002Fpath\u002Fto\u002Fproject\"\n   })\n   → Returns { jobId: \"omx-abc123\" }\n\n2. omx_run_team_wait({ job_id: \"omx-abc123\", timeout_ms: 300000 })\n   → Blocks until done, auto-nudges idle panes\n\n3. omx_run_team_cleanup({ job_id: \"omx-abc123\" })\n   → Only needed if stopping workers early\n```\n\n`omx_run_team_status` can be called between steps 1 and 2 for a non-blocking poll if you need to interleave other work while workers run.\n\n## Limitations\n\n- Worktree provisioning requires a git repository and can fail on branch\u002Fpath collisions\n- send-keys interactions can be timing-sensitive under load\n- stale panes from prior runs can interfere until manually cleaned\n\n## Scenario Examples\n\n**Good:** The user says `continue` after the workflow already has a clear next step. Continue the current branch of work instead of restarting or re-asking the same question.\n\n**Good:** The user changes only the output shape or downstream delivery step (for example `make a PR`). Preserve earlier non-conflicting workflow constraints and apply the update locally.\n\n**Bad:** The user says `continue`, and the workflow restarts discovery or stops before the missing verification\u002Fevidence is gathered.\n",{"name":5,"description":7},"main","7a38d8e7073e61c16eda85681cb32fb68a8657a5","skills-store\u002Fcodex\u002Fteam","https:\u002F\u002Fgithub.com\u002Fsapsapshen\u002Fai-memory-router","https:\u002F\u002Fgithub.com\u002Fsapsapshen","2026-04-14 21:12:12",{"source":8,"skillName":5,"commands":42,"prompt":52,"zipAvailable":53},[43,46,49],{"tool":44,"command":45},"npx","npx skills add sapsapshen\u002Fai-memory-router --skill team",{"tool":47,"command":48},"bunx","bunx skills add sapsapshen\u002Fai-memory-router --skill team",{"tool":50,"command":51},"pnpm","pnpm dlx skills add sapsapshen\u002Fai-memory-router --skill team","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fsapsapshen\u002Fai-memory-router\u002Fblob\u002Fmain\u002Fskills-store\u002Fcodex\u002Fteam\u002FSKILL.md",true,[],[56,66,73,81,87,95],{"skillNo":57,"name":58,"nameZh":6,"description":59,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":60,"licenseFileUrl":61,"sourceHtmlUrl":62,"categories":63,"keywords":64,"publishedAt":65},"01M72R8PZX1ABFHJGTYPA4CAF1","webapp-testing","To test local web applications, write native Python Playwright scripts.","Apache-2.0","https:\u002F\u002Fgithub.com\u002Fsapsapshen\u002Fai-memory-router\u002Fblob\u002Fmain\u002Fskills-store\u002Fglobal\u002Fwebapp-testing\u002FLICENSE.txt","https:\u002F\u002Fgithub.com\u002Fsapsapshen\u002Fai-memory-router\u002Fblob\u002Fmain\u002Fskills-store\u002Fglobal\u002Fwebapp-testing\u002FSKILL.md",[],[],"2026-11-10 22:39:42",{"skillNo":67,"name":68,"nameZh":6,"description":69,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":70,"categories":71,"keywords":72,"publishedAt":65},"01M72QG37MMZNDY7X7GXPAK5W6","python-packaging","Comprehensive guide to creating, structuring, and distributing Python packages using modern packaging tools, pyproject.toml, and publishing to PyPI.","https:\u002F\u002Fgithub.com\u002Fsapsapshen\u002Fai-memory-router\u002Fblob\u002Fmain\u002Fskills-store\u002Fglobal\u002Fpython-packaging\u002FSKILL.md",[],[],{"skillNo":74,"name":75,"nameZh":6,"description":76,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":60,"licenseFileUrl":77,"sourceHtmlUrl":78,"categories":79,"keywords":80,"publishedAt":65},"01M72NXR0QMP9G46TW6A2DH59C","canvas-design","These are instructions for creating design philosophies - aesthetic movements that are then EXPRESSED VISUALLY. Output only .md files, .pdf files, and .png files.","https:\u002F\u002Fgithub.com\u002Fsapsapshen\u002Fai-memory-router\u002Fblob\u002Fmain\u002Fskills-store\u002Fglobal\u002Fcanvas-design\u002FLICENSE.txt","https:\u002F\u002Fgithub.com\u002Fsapsapshen\u002Fai-memory-router\u002Fblob\u002Fmain\u002Fskills-store\u002Fglobal\u002Fcanvas-design\u002FSKILL.md",[],[],{"skillNo":82,"name":58,"nameZh":6,"description":59,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":60,"licenseFileUrl":83,"sourceHtmlUrl":84,"categories":85,"keywords":86,"publishedAt":65},"01M72N55TK3EEQ4QK4AWDC2KZS","https:\u002F\u002Fgithub.com\u002Fsapsapshen\u002Fai-memory-router\u002Fblob\u002Fmain\u002Fskills-store\u002Fcursor\u002Fwebapp-testing\u002FLICENSE.txt","https:\u002F\u002Fgithub.com\u002Fsapsapshen\u002Fai-memory-router\u002Fblob\u002Fmain\u002Fskills-store\u002Fcursor\u002Fwebapp-testing\u002FSKILL.md",[],[],{"skillNo":88,"name":89,"nameZh":6,"description":90,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":60,"licenseFileUrl":91,"sourceHtmlUrl":92,"categories":93,"keywords":94,"publishedAt":65},"01M72MTWC150CFAP4Y5GSNKF80","slack-gif-creator","A toolkit providing utilities and knowledge for creating animated GIFs optimized for Slack.","https:\u002F\u002Fgithub.com\u002Fsapsapshen\u002Fai-memory-router\u002Fblob\u002Fmain\u002Fskills-store\u002Fcursor\u002Fslack-gif-creator\u002FLICENSE.txt","https:\u002F\u002Fgithub.com\u002Fsapsapshen\u002Fai-memory-router\u002Fblob\u002Fmain\u002Fskills-store\u002Fcursor\u002Fslack-gif-creator\u002FSKILL.md",[],[],{"skillNo":96,"name":97,"nameZh":6,"description":98,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":60,"licenseFileUrl":99,"sourceHtmlUrl":100,"categories":101,"keywords":102,"publishedAt":65},"01M72KPT3VVNSP88MNAY466TZT","frontend-design","You are a frontend designer-engineer, not a layout generator.","https:\u002F\u002Fgithub.com\u002Fsapsapshen\u002Fai-memory-router\u002Fblob\u002Fmain\u002Fskills-store\u002Fcursor\u002Ffrontend-design\u002FLICENSE.txt","https:\u002F\u002Fgithub.com\u002Fsapsapshen\u002Fai-memory-router\u002Fblob\u002Fmain\u002Fskills-store\u002Fcursor\u002Ffrontend-design\u002FSKILL.md",[],[]]