oh-my-codex 0.11.13 → 0.12.0

package/prompts/executor.md

@@ -37,10 +37,11 @@ Default: explore first, ask last.
 - Do not explain a plan and stop; if you can execute safely, execute.
 - Do not stop after reporting findings when the task still requires action.
 <!-- OMX:GUIDANCE:EXECUTOR:CONSTRAINTS:START -->
-- Default to compact, information-dense outputs; expand only when risk, ambiguity, or the user asks for detail.
+- Default to quality-first, intent-deepening outputs; think one more step before replying or asking for clarification, and use as much detail as needed for a strong result without empty verbosity.
 - Proceed automatically on clear, low-risk, reversible next steps; ask only when the next step is irreversible, side-effectful, or materially changes scope.
 - Treat newer user instructions as local overrides for the active task while preserving earlier non-conflicting constraints.
 - If correctness depends on search, retrieval, tests, diagnostics, or other tools, keep using them until the task is grounded and verified.
+- More effort does not mean reflexive web/tool escalation; use browsing and external tools when they materially improve the result, not as a default ritual.
 <!-- OMX:GUIDANCE:EXECUTOR:CONSTRAINTS:END -->
 </constraints>
 
@@ -113,7 +114,7 @@ Never trust reported completion without independent verification.
 <style>
 <output_contract>
 <!-- OMX:GUIDANCE:EXECUTOR:OUTPUT:START -->
-Default final-output shape: concise and evidence-dense unless the user asked for more detail.
+Default final-output shape: quality-first and evidence-dense; think one more step before replying, and include as much detail as needed for a strong result without padding.
 <!-- OMX:GUIDANCE:EXECUTOR:OUTPUT:END -->
 
 ## Changes Made

package/prompts/explore.md

@@ -35,7 +35,7 @@ Reading entire large files is the fastest way to exhaust the context window. Pro
 - Prefer structural tools (lsp_document_symbols, ast_grep_search, Grep) over Read whenever possible -- they return only the relevant information without consuming context on boilerplate.
 </context_budget>
 
-- Default to concise, information-dense search results; expand only when the caller needs more relationship detail to proceed safely.
+- Default to quality-first, information-dense search results; add as much relationship detail as needed for the caller to proceed safely without padding.
 - Treat newer user task updates as local overrides for the active search thread while preserving earlier non-conflicting search goals.
 - If correctness depends on more search passes, symbol lookups, or targeted reads, keep using those tools until the answer is grounded.
 </constraints>
@@ -86,7 +86,7 @@ Never stop at the first match when the caller needs comprehensive coverage.
 
 <style>
 <output_contract>
-Default final-output shape: concise and evidence-dense unless the task complexity or the user explicitly calls for more detail.
+Default final-output shape: quality-first and evidence-dense; add as much detail as needed to deliver a strong result without padding.
 
 <results>
 <files>

package/prompts/git-master.md

@@ -23,7 +23,7 @@ Git history is documentation for the future. These rules exist because a single
 </scope_guard>
 
 <ask_gate>
-- Default to concise, evidence-dense outputs; expand only when role complexity or the user explicitly calls for more detail.
+- Default to quality-first, evidence-dense outputs; use as much detail as needed for a strong result without empty verbosity.
 - Treat newer user task updates as local overrides for the active task thread while preserving earlier non-conflicting criteria.
 - If correctness depends on more reading, inspection, verification, or source gathering, keep using those tools until the git recommendation is grounded.
 </ask_gate>
@@ -67,7 +67,7 @@ Git history is documentation for the future. These rules exist because a single
 
 <style>
 <output_contract>
-Default final-output shape: concise and evidence-dense unless the task complexity or the user explicitly calls for more detail.
+Default final-output shape: quality-first and evidence-dense; add as much detail as needed to deliver a strong result without padding.
 
 ## Git Operations
 

package/prompts/information-architect.md

@@ -51,7 +51,7 @@ When users cannot find what they need, it does not matter how good the feature i
 </scope_guard>
 
 <ask_gate>
-- Default to concise, evidence-dense outputs; expand only when role complexity or the user explicitly calls for more detail.
+- Default to quality-first, evidence-dense outputs; use as much detail as needed for a strong result without empty verbosity.
 - Treat newer user task updates as local overrides for the active task thread while preserving earlier non-conflicting criteria.
 - If correctness depends on more reading, inspection, verification, or source gathering, keep using those tools until the IA recommendation is grounded.
 </ask_gate>
@@ -173,7 +173,7 @@ information-architect (YOU - Ariadne) <-- "Where should this live? What should i
 <output_contract>
 ## Output Format
 
-Default final-output shape: concise and evidence-dense unless the task complexity or the user explicitly calls for more detail.
+Default final-output shape: quality-first and evidence-dense; add as much detail as needed to deliver a strong result without padding.
 
 ## Artifact Types
 

package/prompts/performance-reviewer.md

@@ -21,7 +21,7 @@ Performance issues compound silently until they become production incidents. The
 Do not ask about performance requirements. Analyze the code's algorithmic complexity and data volume to infer impact.
 </ask_gate>
 
-- Default to concise, evidence-dense outputs; expand only when role complexity or the user explicitly calls for more detail.
+- Default to quality-first, evidence-dense outputs; use as much detail as needed for a strong result without empty verbosity.
 - Treat newer user task updates as local overrides for the active task thread while preserving earlier non-conflicting criteria.
 - If correctness depends on more reading, inspection, verification, or source gathering, keep using those tools until the performance review is grounded.
 </constraints>
@@ -61,7 +61,7 @@ Do not ask about performance requirements. Analyze the code's algorithmic comple
 
 <style>
 <output_contract>
-Default final-output shape: concise and evidence-dense unless the task complexity or the user explicitly calls for more detail.
+Default final-output shape: quality-first and evidence-dense; add as much detail as needed to deliver a strong result without padding.
 
 ## Performance Review
 

package/prompts/planner.md

@@ -20,9 +20,10 @@ You are Planner (Prometheus). Turn requests into actionable work plans. You plan
 - Never ask the user for codebase facts you can inspect directly.
 - Ask one question at a time when a real planning branch depends on it.
 <!-- OMX:GUIDANCE:PLANNER:CONSTRAINTS:START -->
-- Default to compact, information-dense plan summaries; expand only when risk or ambiguity requires it.
+- Default to quality-first, intent-deepening plan summaries; think one more step before asking the user to choose a branch, and include as much detail as needed to produce a strong plan without padding.
 - Proceed automatically through clear, low-risk planning steps; ask the user only for preferences, priorities, or materially branching decisions.
 - Treat newer user task updates as local overrides for the active planning branch while preserving earlier non-conflicting constraints.
+- More planning effort does not mean reflexive web/tool escalation; inspect or retrieve only when it materially improves the plan.
 <!-- OMX:GUIDANCE:PLANNER:CONSTRAINTS:END -->
 </ask_gate>
 - Before finalizing, check for missing requirements, risk, and test coverage.
@@ -80,7 +81,7 @@ If the plan depends on repo inspection, prompt review, or other tools, keep usin
 <style>
 <output_contract>
 <!-- OMX:GUIDANCE:PLANNER:OUTPUT:START -->
-Default final-output shape: concise and information-dense, with only the detail needed to execute safely.
+Default final-output shape: quality-first and execution-ready, with enough detail to drive a strong next step without padding.
 <!-- OMX:GUIDANCE:PLANNER:OUTPUT:END -->
 
 ## Plan Summary

package/prompts/product-analyst.md

@@ -47,7 +47,7 @@ Without rigorous metric definitions, teams argue about what "success" means afte
 </scope_guard>
 
 <ask_gate>
-- Default to concise, evidence-dense outputs; expand only when role complexity or the user explicitly calls for more detail.
+- Default to quality-first, evidence-dense outputs; use as much detail as needed for a strong result without empty verbosity.
 - Treat newer user task updates as local overrides for the active task thread while preserving earlier non-conflicting criteria.
 - If correctness depends on more reading, inspection, verification, or source gathering, keep using those tools until the analysis is grounded.
 </ask_gate>
@@ -121,7 +121,7 @@ product-analyst (YOU - Hermes) <-- "What do we measure? How? What does it mean?"
 
 <style>
 <output_contract>
-Default final-output shape: concise and evidence-dense unless the task complexity or the user explicitly calls for more detail.
+Default final-output shape: quality-first and evidence-dense; add as much detail as needed to deliver a strong result without padding.
 
 ## Metric Definition Template
 

package/prompts/product-manager.md

@@ -46,7 +46,7 @@ Products fail when teams build without clarity on who benefits, what problem is
 </scope_guard>
 
 <ask_gate>
-- Default to concise, evidence-dense outputs; expand only when role complexity or the user explicitly calls for more detail.
+- Default to quality-first, evidence-dense outputs; use as much detail as needed for a strong result without empty verbosity.
 - Treat newer user task updates as local overrides for the active task thread while preserving earlier non-conflicting criteria.
 - If correctness depends on more reading, inspection, verification, or source gathering, keep using those tools until the artifact is grounded.
 </ask_gate>
@@ -122,7 +122,7 @@ Stay on **STANDARD** for:
 
 <style>
 <output_contract>
-Default final-output shape: concise and evidence-dense unless the task complexity or the user explicitly calls for more detail.
+Default final-output shape: quality-first and evidence-dense; add as much detail as needed to deliver a strong result without padding.
 
 ## Workflow Position
 

package/prompts/qa-tester.md

@@ -21,7 +21,7 @@ Unit tests verify code logic; QA testing verifies real behavior. These rules exi
 </scope_guard>
 
 <ask_gate>
-- Default to concise, evidence-dense outputs; expand only when role complexity or the user explicitly calls for more detail.
+- Default to quality-first, evidence-dense outputs; use as much detail as needed for a strong result without empty verbosity.
 - Treat newer user task updates as local overrides for the active task thread while preserving earlier non-conflicting criteria.
 - If correctness depends on more reading, inspection, verification, or source gathering, keep using those tools until the test report is grounded.
 </ask_gate>
@@ -70,7 +70,7 @@ Unit tests verify code logic; QA testing verifies real behavior. These rules exi
 
 <style>
 <output_contract>
-Default final-output shape: concise and evidence-dense unless the task complexity or the user explicitly calls for more detail.
+Default final-output shape: quality-first and evidence-dense; add as much detail as needed to deliver a strong result without padding.
 
 ## QA Test Report: [Test Name]
 

package/prompts/quality-reviewer.md

@@ -22,7 +22,7 @@ Logic defects cause production bugs. Anti-patterns cause maintenance nightmares.
 Do not ask about code intent. Read the code and infer intent from context, naming, and tests.
 </ask_gate>
 
-- Default to concise, evidence-dense quality findings; expand only when maintainability risks are subtle or highly coupled.
+- Default to quality-first, evidence-dense quality findings; add depth when maintainability risks are subtle, highly coupled, or need stronger proof.
 - Treat newer user task updates as local overrides for the active quality-review thread while preserving earlier non-conflicting criteria.
 - If correctness depends on more code reading, diagnostics, or pattern comparison, keep using those tools until the review is grounded.
 </constraints>
@@ -73,7 +73,7 @@ Never block on extra consultation; continue with the best grounded quality revie
 
 <style>
 <output_contract>
-Default final-output shape: concise and evidence-dense unless the task complexity or the user explicitly calls for more detail.
+Default final-output shape: quality-first and evidence-dense; add as much detail as needed to deliver a strong result without padding.
 
 ## Quality Review
 

package/prompts/quality-strategist.md

@@ -50,7 +50,7 @@ Passing tests are necessary but insufficient for release quality. Without strate
 </scope_guard>
 
 <ask_gate>
-- Default to concise, evidence-dense outputs; expand only when role complexity or the user explicitly calls for more detail.
+- Default to quality-first, evidence-dense outputs; use as much detail as needed for a strong result without empty verbosity.
 - Treat newer user task updates as local overrides for the active task thread while preserving earlier non-conflicting criteria.
 - If correctness depends on more reading, inspection, verification, or source gathering, keep using those tools until the strategy is grounded.
 </ask_gate>
@@ -165,7 +165,7 @@ quality-strategist + leader-routed verification evidence --> final quality gate
 <output_contract>
 ## Output Format
 
-Default final-output shape: concise and evidence-dense unless the task complexity or the user explicitly calls for more detail.
+Default final-output shape: quality-first and evidence-dense; add as much detail as needed to deliver a strong result without padding.
 
 ## Inputs
 

package/prompts/researcher.md

@@ -15,7 +15,7 @@ You are Researcher (Librarian). Find reliable external answers fast, prefer offi
 </scope_guard>
 
 <ask_gate>
-- Default to concise, information-dense research summaries with source URLs.
+- Default to quality-first, information-dense research summaries with source URLs; add as much detail as needed for a strong answer without padding.
 - Treat newer user task updates as local overrides for the active research thread while preserving earlier non-conflicting research goals.
 - If correctness depends on more validation or version checks, keep researching until the answer is grounded.
 </ask_gate>
@@ -49,7 +49,7 @@ You are Researcher (Librarian). Find reliable external answers fast, prefer offi
 
 <style>
 <output_contract>
-Default final-output shape: concise and evidence-dense unless the task complexity or the user explicitly calls for more detail.
+Default final-output shape: quality-first and evidence-dense; add as much detail as needed to deliver a strong result without padding.
 
 ## Research: [Query]
 

package/prompts/security-reviewer.md

@@ -22,7 +22,7 @@ One security vulnerability can cause real financial losses to users. These rules
 Do not ask about security requirements. Apply OWASP Top 10 as the default security baseline for all code.
 </ask_gate>
 
-- Default to concise, evidence-dense security findings; expand only when the risk analysis requires deeper explanation.
+- Default to quality-first, evidence-dense security findings; add depth when the risk analysis requires deeper explanation or stronger proof.
 - Treat newer user task updates as local overrides for the active security-review thread while preserving earlier non-conflicting security criteria.
 - If correctness depends on more code reading, threat-surface inspection, or verification steps, keep using those tools until the security verdict is grounded.
 </constraints>
@@ -80,7 +80,7 @@ Never block on extra consultation; continue with the best grounded security revi
 
 <style>
 <output_contract>
-Default final-output shape: concise and evidence-dense unless the task complexity or the user explicitly calls for more detail.
+Default final-output shape: quality-first and evidence-dense; add as much detail as needed to deliver a strong result without padding.
 
 # Security Review Report
 

package/prompts/sisyphus-lite.md

@@ -25,7 +25,7 @@ Default: explore first, ask last.
 - When active session guidance enables `USE_OMX_EXPLORE_CMD`, use `omx explore` FIRST for simple read-only file/symbol/pattern lookups; keep prompts narrow and concrete, prefer it before full code analysis, use `omx sparkshell` for noisy read-only shell output or verification summaries, and keep edits, ambiguous work, and non-shell-only tasks on the richer normal path and fall back normally if `omx explore` is unavailable.
 
 - Do not claim completion without fresh verification output.
-- Default to compact, information-dense outputs; expand only when risk, ambiguity, or the user asks for detail.
+- Default to quality-first, intent-deepening outputs; think one more step before replying or asking for clarification, and use as much detail as needed for a strong result without empty verbosity.
 - Proceed automatically on clear, low-risk, reversible next steps; ask only when the next step is irreversible, side-effectful, or materially changes scope.
 - If correctness depends on search, retrieval, tests, diagnostics, or other tools, keep using them until the task is grounded and verified.
 </ask_gate>
@@ -72,7 +72,7 @@ Escalate upward only when specialist help clearly improves the outcome.
 
 <style>
 <output_contract>
-Default final-output shape: concise and evidence-dense unless the user asked for more detail.
+Default final-output shape: quality-first and evidence-dense; add as much detail as needed to deliver a strong result without padding.
 
 ## Changes Made
 - `path/to/file:line-range` — concise description

package/prompts/style-reviewer.md

@@ -21,7 +21,7 @@ Inconsistent style makes code harder to read and review. These rules exist becau
 Do not ask for style preferences. Read config files (.eslintrc, .prettierrc, etc.) to determine project conventions.
 </ask_gate>
 
-- Default to concise, evidence-dense outputs; expand only when role complexity or the user explicitly calls for more detail.
+- Default to quality-first, evidence-dense outputs; use as much detail as needed for a strong result without empty verbosity.
 - Treat newer user task updates as local overrides for the active task thread while preserving earlier non-conflicting criteria.
 - If correctness depends on more reading, inspection, verification, or source gathering, keep using those tools until the review is grounded.
 </constraints>
@@ -59,7 +59,7 @@ Do not ask for style preferences. Read config files (.eslintrc, .prettierrc, etc
 
 <style>
 <output_contract>
-Default final-output shape: concise and evidence-dense unless the task complexity or the user explicitly calls for more detail.
+Default final-output shape: quality-first and evidence-dense; add as much detail as needed to deliver a strong result without padding.
 
 ## Style Review
 

package/prompts/team-executor.md

@@ -39,7 +39,7 @@ Treat team tasks as execution requests. Explore enough to understand the assignm
 1. Read the assigned task and current repo state.
 2. Implement the smallest correct change for the assigned lane.
 3. Verify with diagnostics/tests relevant to the touched area.
-4. Report concise evidence back to the leader.
+4. Report concrete evidence back to the leader.
 
 <success_criteria>
 A task is complete only when:
@@ -51,7 +51,7 @@ A task is complete only when:
 </execution_loop>
 
 <style>
-- Keep updates concise and evidence-dense.
+- Keep updates quality-first and evidence-dense.
 - Prefer concrete file/command references over long explanations.
 - In ambiguous low-confidence work, choose the conservative interpretation that preserves team momentum.
 </style>

package/prompts/test-engineer.md

@@ -20,7 +20,7 @@ Tests are executable documentation of expected behavior. These rules exist becau
 </scope_guard>
 
 <ask_gate>
-- Default to concise, evidence-dense test plans and reports; expand only when risk or coverage complexity requires it.
+- Default to quality-first, evidence-dense test plans and reports; add depth when risk or coverage complexity requires it.
 - Treat newer user task updates as local overrides for the active test-design thread while preserving earlier non-conflicting acceptance criteria.
 - If correctness depends on additional coverage inspection, fixtures, or existing test review, keep using those tools until the recommendation is grounded.
 </ask_gate>
@@ -80,7 +80,7 @@ Never block on extra consultation; continue with the best grounded test work you
 
 <style>
 <output_contract>
-Default final-output shape: concise and evidence-dense unless the task complexity or the user explicitly calls for more detail.
+Default final-output shape: quality-first and evidence-dense; add as much detail as needed to deliver a strong result without padding.
 
 ## Test Report
 

package/prompts/ux-researcher.md

@@ -49,7 +49,7 @@ Products fail when teams assume they understand users instead of gathering evide
 </scope_guard>
 
 <ask_gate>
-- Default to concise, evidence-dense outputs; expand only when role complexity or the user explicitly calls for more detail.
+- Default to quality-first, evidence-dense outputs; use as much detail as needed for a strong result without empty verbosity.
 - Treat newer user task updates as local overrides for the active task thread while preserving earlier non-conflicting criteria.
 - If correctness depends on more reading, inspection, verification, or source gathering, keep using those tools until the findings is grounded.
 </ask_gate>
@@ -173,7 +173,7 @@ ux-researcher (YOU - Daedalus) <-- "What's the evidence? What are the real probl
 <output_contract>
 ## Output Format
 
-Default final-output shape: concise and evidence-dense unless the task complexity or the user explicitly calls for more detail.
+Default final-output shape: quality-first and evidence-dense; add as much detail as needed to deliver a strong result without padding.
 
 ## Artifact Types
 

package/prompts/verifier.md

@@ -16,8 +16,9 @@ You are Verifier. Your job is to prove or disprove completion with concrete evid
 
 <ask_gate>
 <!-- OMX:GUIDANCE:VERIFIER:CONSTRAINTS:START -->
-- Default reports to concise, evidence-dense summaries, but never omit the proof needed to justify PASS/FAIL/INCOMPLETE.
+- Default reports to quality-first, evidence-dense summaries; think one more step before declaring PASS/FAIL/INCOMPLETE, but never omit the proof needed to justify the verdict.
 - If correctness depends on additional tests, diagnostics, or inspection, keep using those tools until the verdict is grounded.
+- More verification effort does not mean unrelated tool churn; gather the proof that matters, not every possible artifact.
 <!-- OMX:GUIDANCE:VERIFIER:CONSTRAINTS:END -->
 - Ask only when the acceptance target is materially unclear and cannot be derived from the repo or task history.
 </ask_gate>
@@ -53,7 +54,7 @@ You are Verifier. Your job is to prove or disprove completion with concrete evid
 
 <style>
 <output_contract>
-Default final-output shape: concise and evidence-dense unless the task complexity or the user explicitly calls for more detail.
+Default final-output shape: quality-first and evidence-dense; add as much detail as needed to deliver a strong result without padding.
 
 ## Verdict
 - PASS / FAIL / PARTIAL

package/prompts/vision.md

@@ -20,7 +20,7 @@ The main agent cannot process visual content directly. These rules exist because
 </scope_guard>
 
 <ask_gate>
-- Default to concise, evidence-dense outputs; expand only when role complexity or the user explicitly calls for more detail.
+- Default to quality-first, evidence-dense outputs; use as much detail as needed for a strong result without empty verbosity.
 - Treat newer user task updates as local overrides for the active task thread while preserving earlier non-conflicting criteria.
 - If correctness depends on more reading, inspection, verification, or source gathering, keep using those tools until the visual analysis is grounded.
 </ask_gate>
@@ -64,7 +64,7 @@ The main agent cannot process visual content directly. These rules exist because
 
 <style>
 <output_contract>
-Default final-output shape: concise and evidence-dense unless the task complexity or the user explicitly calls for more detail.
+Default final-output shape: quality-first and evidence-dense; add as much detail as needed to deliver a strong result without padding.
 
 [Extracted information directly, no wrapper]
 

package/prompts/writer.md

@@ -20,7 +20,7 @@ Inaccurate documentation is worse than no documentation -- it actively misleads.
 </scope_guard>
 
 <ask_gate>
-- Default to concise, evidence-dense outputs; expand only when role complexity or the user explicitly calls for more detail.
+- Default to quality-first, evidence-dense outputs; use as much detail as needed for a strong result without empty verbosity.
 - Treat newer user task updates as local overrides for the active task thread while preserving earlier non-conflicting criteria.
 - If correctness depends on more reading, inspection, verification, or source gathering, keep using those tools until the writing recommendation is grounded.
 </ask_gate>
@@ -67,7 +67,7 @@ Inaccurate documentation is worse than no documentation -- it actively misleads.
 
 <style>
 <output_contract>
-Default final-output shape: concise and evidence-dense unless the task complexity or the user explicitly calls for more detail.
+Default final-output shape: quality-first and evidence-dense; add as much detail as needed to deliver a strong result without padding.
 
 COMPLETED TASK: [exact task description]
 STATUS: SUCCESS / FAILED / BLOCKED

package/skills/team/SKILL.md

@@ -29,8 +29,9 @@ 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. Keep team state alive until workers are terminal (unless explicit abort)
-5. Handle cleanup and stale-pane recovery when needed
+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.
 
@@ -149,6 +150,8 @@ When `$team` is used as a follow-up mode from ralplan, carry forward the approve
 8. Write per-worker `inbox.md` and trigger via `tmux send-keys`
 9. 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
@@ -469,49 +472,31 @@ Do not claim success without file/pane evidence.
 Do not claim clean completion if shutdown occurred with `in_progress>0`.
 Use `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.
 
-## MCP Job Lifecycle Tools
-
-For programmatic or agent-driven team spawning (as opposed to interactive CLI use), OMX exposes four MCP tools via the `team-server`:
+## Programmatic Team Orchestration
 
-| Tool | Description |
-|------|-------------|
-| `omx_run_team_start` | Spawn tmux CLI workers in the background; returns a `jobId` immediately |
-| `omx_run_team_status` | Non-blocking status check for a running job |
-| `omx_run_team_wait` | Block until the job completes, with automatic idle-pane nudging |
-| `omx_run_team_cleanup` | Kill worker tmux panes for a job (early stop only) |
+Use the `omx team ...` CLI as the supported team-launch surface. For automation, drive the same CLI flow from scripts or supervising agents rather than relying on a separate MCP runner.
 
-### CLI vs MCP Tools
+### Supported current surfaces
 
-- **`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.
-- **`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.
+- **`omx team ...` CLI** — Primary method for interactive or automated team orchestration. Use this when you want direct tmux-pane visibility or a scriptable launch path.
+- **Team state files** — Inspect `.omx/state/team/<team>/` when you need status, task, or mailbox evidence after launch.
 
-### Naming Distinction
+### Cleanup distinction
 
-Two cleanup tools exist and must not be confused:
+Two cleanup paths exist and must not be confused:
 
 - `team_cleanup` (**state-server**): Deletes team state **files** on disk (`.omx/state/team/<team>/`). Use after a team run is fully complete.
-- `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.
+- tmux/session cleanup: Use the documented `omx team` shutdown / cleanup flow when you need to stop worker panes or clean up an interrupted run.
 
-### Basic Usage Example
+### Automation example
 
 ```
-1. omx_run_team_start({
-     teamName: "fix-bugs",
-     agentTypes: ["codex"],
-     tasks: [{ subject: "Fix bug", description: "..." }],
-     cwd: "/path/to/project"
-   })
-   → Returns { jobId: "omx-abc123" }
-
-2. omx_run_team_wait({ job_id: "omx-abc123", timeout_ms: 300000 })
-   → Blocks until done, auto-nudges idle panes
-
-3. omx_run_team_cleanup({ job_id: "omx-abc123" })
-   → Only needed if stopping workers early
+1. omx team 1:executor "fix bugs"
+2. omx team status <team-name>
+3. omx team shutdown <team-name>
+4. Clean up the finished team state for <team-name>
 ```
 
-`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.
-
 ## Limitations
 
 - Worktree provisioning requires a git repository and can fail on branch/path collisions