oh-my-codex 0.14.4 → 0.15.1

package/plugins/oh-my-codex/skills/ultrawork/SKILL.md

@@ -0,0 +1,175 @@
+---
+name: ultrawork
+description: Parallel execution engine for high-throughput task completion
+---
+
+<Purpose>
+Ultrawork is a parallel execution engine for high-throughput task completion. It is a component, not a standalone persistence mode: it provides parallelism, context discipline, and smart delegation guidance, but not Ralph's persistence loop, architect sign-off, or long-running completion guarantees.
+</Purpose>
+
+<Use_When>
+- Multiple independent tasks can run simultaneously
+- User says "ulw", "ultrawork", or explicitly wants parallel execution
+- Task benefits from concurrent execution plus lightweight evidence before wrap-up
+- You need a direct-tool lane plus optional background evidence lanes without entering Ralph
+</Use_When>
+
+<Do_Not_Use_When>
+- Task requires guaranteed completion with persistence, architect verification, or deslop/reverification -- use `ralph` instead (Ralph includes ultrawork)
+- Task requires a full autonomous pipeline -- use `autopilot` instead (autopilot includes Ralph which includes ultrawork)
+- There is only one sequential task with no parallelism opportunity -- execute directly or delegate to a single `executor`
+- The request is still in plan-consensus mode -- keep planning artifacts in `ralplan` until execution is explicitly authorized
+- User needs session persistence for resume -- use `ralph`, which adds persistence on top of ultrawork
+</Do_Not_Use_When>
+
+<Why_This_Exists>
+Sequential task execution wastes time when tasks are independent. Ultrawork keeps the execution branch fast while tightening the protocol: gather enough context first, define pass/fail acceptance criteria before editing, decide deliberately between local execution and delegation, and finish with evidence rather than vibes.
+</Why_This_Exists>
+
+<Execution_Policy>
+- Gather enough context before implementation. Start with the task intent, desired outcome, constraints, likely touchpoints, and any uncertainty that would change the execution path.
+- If uncertainty is still material after a quick repo read, do a focused evidence pass first instead of immediately editing.
+- Define pass/fail acceptance criteria before launching execution lanes. Include the command, artifact, or manual check that will prove success.
+- Prefer direct tool work when the task is small, coupled, or blocked on immediate local context. Delegate only when the work is independent enough to benefit from parallel execution.
+- When useful, run a direct-tool lane and one or more background evidence lanes at the same time. Evidence lanes can cover docs, tests, regression mapping, or bounded repo analysis.
+- Fire independent agent calls simultaneously -- never serialize independent work.
+- Always pass the `model` parameter explicitly when delegating.
+- Read `docs/shared/agent-tiers.md` before first delegation for agent selection guidance.
+- Auto-delegate `researcher` when official docs, version-aware framework guidance, best practices, or external dependency behavior materially affect task correctness; treat it as an evidence lane, not a replacement primary workflow.
+- Use `run_in_background: true` for operations over ~30 seconds (installs, builds, tests).
+- Run quick commands (git status, file reads, simple checks) in the foreground.
+- Apply the shared workflow guidance pattern: concise, evidence-dense progress and completion reporting (including speculative/blocked lanes), local overrides for the active workflow branch, and continuation of clear safe execution branches instead of restarting or re-asking.
+- If the user says `continue`, continue the active workflow branch rather than restarting discovery or re-asking settled questions.
+</Execution_Policy>
+
+<Steps>
+1. **Read agent reference**: Load `docs/shared/agent-tiers.md` for tier selection.
+2. **Context + certainty check**:
+   - State the task intent in one sentence.
+   - List the constraints and unknowns that could invalidate a quick fix.
+   - If confidence is low, explore first and narrow the task before editing.
+3. **Define acceptance criteria before execution**:
+   - What must be true at the end?
+   - Which command or artifact proves it?
+   - Which manual QA check is required, if any?
+4. **Classify the work by dependency shape**:
+   - Independent tasks -> parallel lanes.
+   - Shared-file or prerequisite-heavy tasks -> local execution or staged lanes.
+5. **Choose self vs delegate deliberately**:
+   - Work locally when the next step depends on immediate repo context, shared files, or tight iteration.
+   - Delegate when the task slice is bounded, independent, and materially improves throughput.
+6. **Run execution lanes**:
+   - Direct-tool lane for immediate implementation or verification work.
+   - Background evidence lanes for tests, docs, repo analysis, or regression checks.
+7. **Run dependent tasks sequentially**: Wait for prerequisites before launching dependent work.
+8. **Close with lightweight evidence**:
+   - Build/typecheck passes when relevant.
+   - Affected tests pass.
+   - Manual QA notes are recorded when the task needs a human-visible or behavior-level check.
+   - No new errors introduced.
+</Steps>
+
+<Tool_Usage>
+- Use LOW-tier delegation for simple lookups and bounded evidence gathering.
+- Use STANDARD-tier delegation for standard implementation and regression work.
+- Use THOROUGH-tier delegation for complex analysis, architectural review, or risky multi-file changes.
+- Prefer a direct-tool lane when the immediate next step is blocked on local context.
+- Prefer background evidence lanes when you can learn something useful in parallel with implementation.
+- Use `run_in_background: true` for package installs, builds, and test suites.
+- Use foreground execution for quick status checks and file operations.
+</Tool_Usage>
+
+## State Management
+
+Use `omx_state` MCP tools for ultrawork lifecycle state.
+
+- **On start**:
+  `state_write({mode: "ultrawork", active: true, reinforcement_count: 1, started_at: "<now>"})`
+- **On each reinforcement/loop step**:
+  `state_write({mode: "ultrawork", reinforcement_count: <current>})`
+- **On completion**:
+  `state_write({mode: "ultrawork", active: false})`
+- **On cancellation/cleanup**:
+  run `$cancel` (which should call `state_clear(mode="ultrawork")`)
+
+<Examples>
+<Good>
+Two-track execution with acceptance criteria up front:
+```
+Acceptance criteria:
+- `npm run build` passes
+- `node --test dist/scripts/__tests__/codex-native-hook.test.js` passes
+- Manual QA: verify `$ultrawork` activation message still points to the session state file
+
+Direct-tool lane:
+- update `skills/ultrawork/SKILL.md`
+
+Background evidence lane:
+- delegate(role="test-engineer", tier="STANDARD", task="Map which hook tests cover ultrawork activation messaging", model="...")
+```
+Why good: Context is grounded first, acceptance criteria are explicit, and the direct-tool lane runs alongside a bounded evidence lane.
+</Good>
+
+<Good>
+Correct use of self-vs-delegate judgment:
+```
+Shared-file edit in progress across `src/scripts/codex-native-hook.ts` and its test -> keep implementation local.
+Independent regression mapping for keyword-detector coverage -> delegate to a test-engineer lane.
+```
+Why good: Shared-file work stays local; independent evidence work fans out.
+</Good>
+
+<Bad>
+Parallelizing before the task is grounded:
+```
+delegate(role="executor", tier="STANDARD", task="Implement whatever seems necessary", model="...")
+delegate(role="test-engineer", tier="STANDARD", task="Figure out how to test it later", model="...")
+```
+Why bad: No context snapshot, no pass/fail target, and delegation starts before the work is shaped.
+</Bad>
+
+<Bad>
+Claiming success without evidence or manual QA:
+```
+Made the changes. Ultrawork should be updated now.
+```
+Why bad: No verification output, no acceptance evidence, and no manual QA note when the behavior is user-visible.
+</Bad>
+</Examples>
+
+<Escalation_And_Stop_Conditions>
+- When ultrawork is invoked directly (not via Ralph), apply lightweight verification only -- build/typecheck passes when relevant, affected tests pass, and manual QA notes are captured when needed.
+- Ralph owns persistence, architect verification, deslop, and the full verified-completion promise. Do not claim those guarantees from direct ultrawork alone.
+- If a task fails repeatedly across retries, report the issue rather than retrying indefinitely.
+- Escalate to the user when tasks have unclear dependencies, conflicting requirements, or a materially branching acceptance target.
+</Escalation_And_Stop_Conditions>
+
+<Final_Checklist>
+- [ ] Task intent and constraints were grounded before editing
+- [ ] Pass/fail acceptance criteria were stated before execution
+- [ ] Parallel lanes were used only for independent work
+- [ ] Build/typecheck passes when relevant
+- [ ] Affected tests pass
+- [ ] Manual QA notes recorded when behavior is user-visible
+- [ ] No new errors introduced
+- [ ] Completion claim stays inside ultrawork's lightweight-verification boundary
+</Final_Checklist>
+
+<Advanced>
+## Relationship to Other Modes
+
+```
+ralph (persistence + verified completion wrapper)
+ \-- includes: ultrawork (this skill)
+     \-- provides: high-throughput execution + lightweight evidence
+
+autopilot (autonomous execution)
+ \-- includes: ralph
+     \-- includes: ultrawork (this skill)
+
+ecomode (token efficiency)
+ \-- modifies: ultrawork's model selection
+```
+
+Ultrawork is the parallelism and execution-discipline layer. Ralph adds persistence, architect verification, deslop, and retry-until-done behavior. Autopilot adds the broader autonomous lifecycle pipeline. Ecomode adjusts ultrawork's model routing to favor cheaper models.
+</Advanced>

package/plugins/oh-my-codex/skills/visual-ralph/SKILL.md

@@ -0,0 +1,153 @@
+---
+name: visual-ralph
+description: "Visual Ralph orchestration for frontend UI from generated references, static references, or live URL targets, using $ralph with $visual-verdict and pixel-diff evidence until the implementation matches and leaves a reproducible design system."
+---
+
+# Visual Ralph Skill
+
+Use this skill when the user wants Codex to build or restyle frontend UI through a Visual Ralph loop: an approved generated reference, static reference, or live URL-derived baseline becomes the target, Ralph implements, and Visual Verdict drives measured iteration rather than subjective description alone.
+
+## Purpose
+
+Create a measured frontend delivery loop from either a generated reference, a static reference, or a live URL:
+
+`user description / live URL -> approved visual reference -> $ralph implementation -> $visual-verdict + pixel diff -> reproducible design system`.
+
+For live URL cloning requests, Visual Ralph owns the migrated `$web-clone` use case. Do not route new URL-driven website cloning work to `$web-clone`; preserve the URL, viewport, fidelity requirements, and interaction notes inside the Visual Ralph loop.
+
+This is an orchestration skill. It composes existing skills and must not add runtime commands, dependencies, or app-specific assumptions by itself.
+
+## Use when
+
+- The user describes a desired web/app UI and wants implementation, not just design advice.
+- The user provides a live URL and wants a visual implementation or clone through measured Visual Verdict iteration.
+- A generated raster mockup/reference image would make the target clearer.
+- The task needs pixel-level visual iteration with a pass/fail threshold.
+- The final result should leave reusable design tokens/components, not only a one-off screenshot match.
+
+## Do not use when
+
+- The user only wants design critique or general frontend advice; use `$frontend-ui-ux` or a designer lane.
+- The task is a non-visual backend/API implementation with no UI reference target.
+- The user already supplied a final static reference image and only needs comparison/fixes; hand directly to `$ralph` with `$visual-verdict` guidance.
+- The requested output is a deterministic SVG/vector/code-native asset rather than a raster reference.
+
+## Workflow
+
+### 1. Ground the target repo
+
+Before stack-specific choices, inspect local evidence:
+- package manager and scripts,
+- frontend framework and routing structure,
+- styling system and design-token conventions,
+- screenshot/test tooling,
+- existing components that should be reused.
+
+Do not hardcode React, Vue, Tailwind, Playwright, or any other stack unless the repository evidence supports it.
+
+### 2. Establish the visual reference
+
+For live URL requests, capture or document the URL-derived reference inside the Visual Ralph artifacts and carry forward viewport, content-state, and interaction constraints. Do not invoke `$web-clone`; that standalone skill is hard-deprecated.
+
+Live URL reference artifacts must include:
+- source URL and permission/scope note,
+- viewport(s), route/state, and any seed/login assumptions,
+- captured baseline screenshot path or documented capture command/tool,
+- interaction parity notes for visible controls,
+- known exclusions such as backend/API/auth, personalized data, multi-page crawling, and third-party widget parity.
+
+For generated UI concepts, use `$imagegen` to produce the reference from the user's UI description.
+
+Prompt requirements:
+- classify as `ui-mockup`, unless another imagegen taxonomy is clearly better,
+- include viewport/aspect ratio and intended surface,
+- specify layout, hierarchy, typography direction, color mood, and any exact text,
+- forbid logos/watermarks/unrequested brand marks,
+- ask imagegen to avoid impossible UI details or unreadable text.
+
+For project-bound implementation, copy the approved reference into the workspace, for example under `.omx/artifacts/visual-ralph/<slug>/reference.png`. Never leave the implementation reference only in `$CODEX_HOME/generated_images/...`.
+
+### 3. Require explicit user approval
+
+Stop after reference generation or URL-derived reference capture and ask the user to approve one reference image/state or request a targeted regeneration/capture adjustment.
+
+Before approval:
+- do not start frontend implementation,
+- do not invoke `$ralph`,
+- do not treat a rough image as final.
+
+After approval, the confirmed image or URL-derived baseline becomes the visual source of truth. Major design pivots, replacing the reference, or changing the design direction require an explicit user request.
+
+### 4. Hand off to `$ralph` for implementation
+
+Invoke `$ralph` with:
+- the approved reference image path or URL-derived baseline artifact,
+- source URL, viewport(s), content state, and interaction parity notes for live URL tasks,
+- the user description,
+- the detected repo/frontend context,
+- exact screenshot command/viewport requirements,
+- the completion checklist below.
+
+Ralph may iterate autonomously after approval. It should edit code, run the app, capture screenshots, and keep improving until the approved reference is matched or a real blocker exists.
+
+### 5. Use `$visual-verdict` before every next edit
+
+For each visual iteration:
+1. Capture the current generated screenshot with recorded viewport/state.
+2. Run `$visual-verdict` comparing the approved reference and generated screenshot.
+3. Treat the JSON verdict as authoritative.
+4. If `score < 90`, convert `differences[]` and `suggestions[]` into the next edit plan.
+5. Rerun before the next edit.
+
+Required verdict shape is inherited from `$visual-verdict`: `score`, `verdict`, `category_match`, `differences[]`, `suggestions[]`, and `reasoning`.
+
+### 6. Use pixel diff only as secondary debug evidence
+
+When mismatch diagnosis is hard, generate a pixel diff or pixelmatch overlay to locate hotspots. Pixel diff does not replace `$visual-verdict`; it only helps translate visual hotspots into concrete edits.
+
+Record final diff evidence with the reference/screenshot artifacts so the result can be audited.
+
+### 7. Build a reproducible design system
+
+The implementation is incomplete unless the visual match is encoded in repo-native reusable artifacts. Depending on the project, this may mean CSS variables, theme tokens, Tailwind config, component variants, Storybook stories, design docs, or existing equivalents.
+
+Capture at least the applicable:
+- colors,
+- spacing scale,
+- typography scale/weights,
+- radii,
+- shadows/elevation,
+- important component variants and states.
+
+Prefer existing token/component patterns. Do not introduce a new design-system layer if the repo already has one that can be extended.
+
+## Completion checklist
+
+Do not declare done until all are true:
+- Approved reference image or URL-derived reference artifact is saved in the workspace.
+- Screenshot reproduction command, viewport, route, seed/state, and output paths are documented.
+- `$visual-verdict` final score is `>= 90` against the approved reference.
+- Pixel diff or overlay evidence is recorded as secondary debug evidence.
+- Design-system tokens/components are repo-native and reusable.
+- Build/lint/test or the repo's equivalent verification passes.
+- No unapproved major design pivot occurred after reference approval.
+- Remaining visual differences, if any, are explicitly documented with rationale.
+
+## Handoff template
+
+```text
+$ralph "Implement the approved frontend reference.
+Reference: <workspace-reference-image-or-url-derived-artifact>
+Source URL (if URL-derived): <url and permission/scope note>
+Viewport/content state: <viewport, route/state, seed/login assumptions>
+Interaction parity notes: <visible controls and known exclusions>
+Route/surface: <route or component>
+Screenshot command: <command and viewport>
+Use $visual-verdict before every next edit; pass threshold score >= 90.
+Use pixel diff only as secondary debug evidence.
+Extract reusable design tokens/components for colors, spacing, typography, radii, shadows, and key variants.
+Run build/lint/test before completion.
+Do not make major design pivots unless explicitly requested."
+```
+
+Task: {{ARGUMENTS}}

package/plugins/oh-my-codex/skills/visual-verdict/SKILL.md

@@ -0,0 +1,76 @@
+---
+name: visual-verdict
+description: Structured visual QA verdict for screenshot-to-reference comparisons
+---
+
+<Purpose>
+Use this skill to compare generated UI screenshots against one or more reference images and return a strict JSON verdict that can drive the next edit iteration.
+</Purpose>
+
+<Use_When>
+- The task includes visual fidelity requirements (layout, spacing, typography, component styling)
+- You have a generated screenshot and at least one reference image
+- You need deterministic pass/fail guidance before continuing edits
+</Use_When>
+
+<Inputs>
+- `reference_images[]` (one or more image paths)
+- `generated_screenshot` (current output image)
+- Optional: `category_hint` (e.g., `hackernews`, `sns-feed`, `dashboard`)
+</Inputs>
+
+<Output_Contract>
+Return **JSON only** with this exact shape:
+
+```json
+{
+  "score": 0,
+  "verdict": "revise",
+  "category_match": false,
+  "differences": ["..."],
+  "suggestions": ["..."],
+  "reasoning": "short explanation"
+}
+```
+
+Rules:
+- `score`: integer 0-100
+- `verdict`: short status (`pass`, `revise`, or `fail`)
+- `category_match`: `true` when the generated screenshot matches the intended UI category/style
+- `differences[]`: concrete visual mismatches (layout, spacing, typography, colors, hierarchy)
+- `suggestions[]`: actionable next edits tied to the differences
+- `reasoning`: 1-2 sentence summary
+
+<Threshold_And_Loop>
+- Target pass threshold is **90+**.
+- If `score < 90`, continue editing and rerun `$visual-verdict` before any further code edits in the next iteration.
+- Persist the verdict in `.omx/state/{scope}/ralph-progress.json` with both:
+  - numeric signal (`score`, threshold pass/fail)
+  - qualitative signal (`reasoning`, `suggestions`, `next_actions`)
+</Threshold_And_Loop>
+
+<Debug_Visualization>
+When mismatch diagnosis is hard:
+1. Keep `$visual-verdict` as the authoritative decision.
+2. Use pixel-level diff tooling (pixel diff / pixelmatch overlay) as a **secondary debug aid** to localize hotspots.
+3. Convert pixel diff hotspots into concrete `differences[]` and `suggestions[]` updates.
+</Debug_Visualization>
+
+<Example>
+```json
+{
+  "score": 87,
+  "verdict": "revise",
+  "category_match": true,
+  "differences": [
+    "Top nav spacing is tighter than reference",
+    "Primary button uses smaller font weight"
+  ],
+  "suggestions": [
+    "Increase nav item horizontal padding by 4px",
+    "Set primary button font-weight to 600"
+  ],
+  "reasoning": "Core layout matches, but style details still diverge."
+}
+```
+</Example>

package/plugins/oh-my-codex/skills/wiki/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: wiki
+description: Persistent markdown project wiki stored under .omx/wiki with keyword search and lifecycle capture
+triggers: ["wiki add", "wiki lint", "wiki query", "wiki read", "wiki delete"]
+---
+
+# Wiki
+
+Persistent, self-maintained markdown knowledge base for project and session knowledge.
+
+## Operations
+
+### Ingest
+```text
+wiki_ingest({ title: "Auth Architecture", content: "...", tags: ["auth", "architecture"], category: "architecture" })
+```
+
+### Query
+```text
+wiki_query({ query: "authentication", tags: ["auth"], category: "architecture" })
+```
+
+### Lint
+```text
+wiki_lint()
+```
+
+### Quick Add
+```text
+wiki_add({ title: "Page Title", content: "...", tags: ["tag1"], category: "decision" })
+```
+
+### List / Read / Delete
+```text
+wiki_list()
+wiki_read({ page: "auth-architecture" })
+wiki_delete({ page: "outdated-page" })
+wiki_refresh()
+```
+
+## Categories
+`architecture`, `decision`, `pattern`, `debugging`, `environment`, `session-log`, `reference`, `convention`
+
+## Storage
+- Pages: `.omx/wiki/*.md`
+- Index: `.omx/wiki/index.md`
+- Log: `.omx/wiki/log.md`
+
+## Cross-References
+Use `[[page-name]]` wiki-link syntax to create cross-references between pages.
+
+## Auto-Capture
+At session end, discoveries can be captured as `session-log-*` pages. Configure via `wiki.autoCapture` in `.omx-config.json`.
+
+## Hard Constraints
+- No vector embeddings — query uses keyword + tag matching only
+- Wiki files remain local project state under `.omx/wiki/`

package/plugins/oh-my-codex/skills/worker/SKILL.md

@@ -0,0 +1,106 @@
+---
+name: worker
+description: Team worker protocol (ACK, mailbox, task lifecycle) for tmux-based OMX teams
+---
+
+# Worker Skill
+
+This skill is for a Codex session that was started as an OMX Team worker (a tmux pane spawned by `$team`).
+
+## Identity
+
+You MUST be running with `OMX_TEAM_WORKER` set. It looks like:
+
+`<team-name>/worker-<n>`
+
+Example: `alpha/worker-2`
+
+## Load Worker Skill Path (Claude/Codex)
+
+When a worker inbox tells you to load this skill, resolve the first existing path:
+
+1. `${CODEX_HOME:-~/.codex}/skills/worker/SKILL.md`
+2. `~/.codex/skills/worker/SKILL.md`
+3. `<leader_cwd>/.codex/skills/worker/SKILL.md`
+4. `<leader_cwd>/skills/worker/SKILL.md` (repo fallback)
+
+## Startup Protocol (ACK)
+
+1. Parse `OMX_TEAM_WORKER` into:
+   - `teamName` (before the `/`)
+   - `workerName` (after the `/`, usually `worker-<n>`)
+2. Send a startup ACK to the lead mailbox **before task work**:
+   - Recipient worker id: `leader-fixed`
+   - Body: one short deterministic line (recommended: `ACK: <workerName> initialized`).
+3. After ACK, proceed to your inbox instructions.
+
+The lead will see your message in:
+
+`<team_state_root>/team/<teamName>/mailbox/leader-fixed.json`
+
+Use CLI interop:
+- `omx team api send-message --input <json> --json` with `{team_name, from_worker, to_worker:"leader-fixed", body}`
+
+Copy/paste template:
+
+```bash
+omx team api send-message --input "{\"team_name\":\"<teamName>\",\"from_worker\":\"<workerName>\",\"to_worker\":\"leader-fixed\",\"body\":\"ACK: <workerName> initialized\"}" --json
+```
+
+## Inbox + Tasks
+
+1. Resolve canonical team state root in this order:
+   1) `OMX_TEAM_STATE_ROOT` env
+   2) worker identity `team_state_root`
+   3) team config/manifest `team_state_root`
+   4) local cwd fallback (`.omx/state`)
+2. Read your inbox:
+   `<team_state_root>/team/<teamName>/workers/<workerName>/inbox.md`
+3. Pick the first unblocked task assigned to you.
+4. Read the task file:
+   `<team_state_root>/team/<teamName>/tasks/task-<id>.json` (example: `task-1.json`)
+5. Task id format:
+   - The MCP/state API uses the numeric id (`"1"`), not `"task-1"`.
+   - Never use legacy `tasks/{id}.json` wording.
+6. Claim the task (do NOT start work without a claim) using claim-safe lifecycle CLI interop (`omx team api claim-task --json`).
+7. Do the work.
+8. Complete/fail the task via lifecycle transition CLI interop (`omx team api transition-task-status --json`) from `in_progress` to `completed` or `failed`.
+   - Do NOT directly write lifecycle fields (`status`, `owner`, `result`, `error`) in task files.
+9. Use `omx team api release-task-claim --json` only for rollback/requeue to `pending` (not for completion).
+10. Update your worker status:
+   `<team_state_root>/team/<teamName>/workers/<workerName>/status.json` with `{"state":"idle", ...}`
+
+## Mailbox
+
+Check your mailbox for messages:
+
+`<team_state_root>/team/<teamName>/mailbox/<workerName>.json`
+
+When notified, read messages and follow any instructions. Use short ACK replies when appropriate.
+
+Note: leader dispatch is state-first. The durable queue lives at:
+`<team_state_root>/team/<teamName>/dispatch/requests.json`
+Hooks/watchers may nudge you after mailbox/inbox state is already written.
+
+Use CLI interop:
+- `omx team api mailbox-list --json` to read
+- `omx team api mailbox-mark-delivered --json` to acknowledge delivery
+
+Copy/paste templates:
+
+```bash
+omx team api mailbox-list --input "{\"team_name\":\"<teamName>\",\"worker\":\"<workerName>\"}" --json
+omx team api mailbox-mark-delivered --input "{\"team_name\":\"<teamName>\",\"worker\":\"<workerName>\",\"message_id\":\"<MESSAGE_ID>\"}" --json
+```
+
+## Dispatch Discipline (state-first)
+
+Worker sessions should treat team state + CLI interop as the source of truth.
+
+- Prefer inbox/mailbox/task state and `omx team api ... --json` operations.
+- Do **not** rely on ad-hoc tmux keystrokes as a primary delivery channel.
+- If a manual trigger arrives (for example `tmux send-keys` nudge), treat it only as a prompt to re-check state and continue through the normal claim-safe lifecycle.
+
+## Shutdown
+
+If the lead sends a shutdown request, follow the shutdown inbox instructions exactly, write your shutdown ack file, then exit the Codex session.