codex-ops

name: codex-ops description: Use when the user asks for Codex-native OPS orchestration, Codex worker coordination, Codex task intake, Codex mailbox processing, Codex review/verification lanes, provider routing between Codex and Claude, or anything that should be handled as Codex OPS rather than Claude OPS.

Codex OPS

Codex OPS is the Codex-owned control plane for intake, routing, task tracking, worker coordination, review, verification, and closeout. It may interoperate with Claude when explicitly configured, but the orchestrator and default workers are Codex.

Core Posture

• Top-level Codex is the orchestrator, not the default long-running executor.
• Keep inline work only for tiny control-plane tasks or when the user explicitly asks for inline handling.
• For non-trivial implementation, debugging, research, docs, or review tasks, route to a focused Codex worker/subagent when available.
• Keep the coordinator free for intake, task-doc lifecycle, aggregation, verification, and final reporting.
• There is no autonomous chat listener; automatic wake-up requires a separate local daemon/watcher.
• Keep Codex OPS files under Codex-owned paths such as ~/.codex/skills or ~/.codex/ops, not under ~/.claude/ops.

Phase Pipeline

1. Intake

   • Parse the request.
   • Classify task type.
   • Define success criteria and verification signal.
   • Decide inline vs worker routing.

2. Task Doc / Plan

   • Create a concise task doc for non-trivial or async work.
   • Record objective, owner role, provider, write scope, and expected evidence.
   • Do not create broad process artifacts when a short checklist is enough.

3. Routing

   • Codex role -> Codex worker/subagent when available.
   • Claude role -> Redis/mailbox handoff only when explicitly requested or configured.
   • Inline -> only tiny control-plane work or user-requested inline handling.

4. Execution

   • Worker performs bounded work inside its assigned scope.
   • Worker reports changed files, checks run, blockers, and exact evidence.

5. Review

   • Reviewer checks diff/findings against the task objective.
   • Prefer actionable findings over broad commentary.
   • Use adversarial review for risky implementation or security/privacy-sensitive changes.

6. Verification

   • Run the verification signal identified during intake.
   • Inspect outputs and exit codes before claiming success.
   • Capture rendered/browser evidence for UI work when relevant.

7. Aggregation

   • Orchestrator reads worker/reviewer/verifier outputs.
   • Resolve conflicts and decide whether another loop is needed.
   • Do not blindly trust worker success reports.

8. Closeout

   • Mark task done, failed, or blocked.
   • Close the same mailbox task id that was claimed.
   • Run scratch cleanup for non-trivial tasks when available.
   • Final report includes scope, files/artifacts touched, verification, and remaining risk.

Intake Classification

Use one of these categories:

• tiny control-plane
• research/codebase exploration
• docs/wiki sync
• implementation/refactor
• verification/debugging
• mailbox/provider coordination
• architecture/decision support

For every non-trivial task, record:

• success criteria
• verification signal
• write scope, if any
• provider/role routing decision
• whether Redis/mailbox, browser/devtools, GitHub, or local shell access is needed

If the request is ambiguous or the fastest path risks correctness, surface the tradeoff before acting.

Provider Routing

A Codex OPS lane can use different providers by role:

agents:
  implementer:
    provider: codex
  reviewer:
    provider: claude
  verifier:
    provider: codex
  docs:
    provider: claude

Rules:

• provider: codex means route to a Codex worker/subagent when available.
• provider: claude means create a task document and hand off through the mailbox/Redis protocol.
• Keep Codex as orchestrator unless the user explicitly changes ownership.
• Do not mix providers inside one worker's write scope unless the task doc says how conflicts are resolved.

Worker Selection

Use workers when context isolation or parallelism helps.

Good worker tasks:

• focused file exploration or repo mapping
• product code implementation with clear write scope
• targeted debugging with reproduction steps
• scoped diff review
• verification/report generation
• docs/wiki updates with clear source material

Avoid worker routing when:

• the task is one or two control-plane commands
• the coordinator needs the result immediately and no parallel work exists
• the task requires user clarification before useful work can begin
• the worker would duplicate the coordinator's current critical path

Task Doc Shape

For async or multi-step OPS work, use a compact task document:

id: <task-id>
owner: codex
role: implementer|reviewer|verifier|docs|researcher|orchestrator
provider: codex|claude
status: queued|claimed|running|blocked|done|failed
objective: <one sentence>
success_criteria:
  - <observable result>
verification:
  - <command/check/evidence>
write_scope:
  - <paths or none>
notes:
  - <short evidence trail>

Mailbox / Redis Interop

Use mailbox interop only when Redis/provider routing is explicitly in scope.

Default keys:

• Codex inbox: ccb:inbox:codex
• Codex role inbox pattern: ccb:inbox:codex:<role>
• Claude inbox: ccb:inbox:claude
• Task docs: ccb:task:{id}

Protocol:

1. Write ccb:task:{id} first.
2. Push the task id to the selected provider inbox.
3. When claiming queued work, claim/remove the queued id before execution if the available tool supports it.
4. Finish the same task id with done/failed/blocked semantics.
5. Do not create a reply task unless delegating brand-new work.

If Redis is blocked, report the exact connection/sandbox blocker instead of debugging unrelated workflow logic.

Verification Gate

Before reporting success:

1. Run the verification signal identified during intake.
2. Inspect output and exit code.
3. Confirm changed files/artifacts match scope.
4. Note unverified risk explicitly.
5. For non-trivial tasks, run scratch cleanup when available:

rtk __YAO_HOME__/.local/bin/tmp-prune.sh --quiet

If verification is blocked, report the exact blocker and do not claim completion.

Final Report

Keep final reports concise and evidence-backed:

• routing/execution summary
• files or artifacts touched
• verification run and result
• remaining risk or next step