ao-operator-discipline

AO Operator Discipline

Overview

AO parameters are commitments. If the user asks for Codex workers, PR-specific workers, a certain runtime, or a specific project, you must pass those parameters explicitly and then verify that AO actually honored them.

The failure pattern this skill prevents is simple: a worker exists, but it is the wrong worker.

When to Use

Use this skill when:

• the user asks to use AO or ao
• you plan to run ao spawn, ao send, ao session claim-pr, or ao status
• the user specifies a worker type such as Codex, Claude, Gemini, or a runtime
• you are claiming PRs or creating a PR-focused worker fleet

Do not use this skill for tiny read-only checks like a one-off ao status.

Agent Name Resolution — Read Config First

Before evaluating any --agent value, read the active AO config:

head -20 ~/.hermes/agent-orchestrator.yaml   # check defaults.agent and installed plugins

--agent values are resolved against the config, not against AO package plugin directories. If <X> in --agent <X> is not a well-known CLI name (codex, claude, claude-code, gemini), look it up in the config before concluding it's unsupported.

Known shorthands on this machine:

• agy / antigravity → ~/.local/bin/agy (Google Antigravity / Gemini CLI) — this is the default agent
• minimax → claude CLI + MiniMax API redirect
• wafer → claude CLI + Wafer API redirect

Never scan packages/agent-*/ as a substitute for reading the config.

Required Rules

1. Treat user-specified AO parameters as hard requirements:

   • --agent
   • --runtime
   • --project
   • --claim-pr
   • target PR / branch / evidence standard

2. Never rely on AO defaults when the user asked for something specific.

3. After every ao spawn, verify the spawned session before trusting it.

4. If the verified session does not match the request, kill or replace it. Do not proceed with the wrong worker.

Spawn Pattern

For Codex workers, use an explicit agent override:

unset GITHUB_TOKEN
ao spawn --project <project> --agent codex --claim-pr <pr> "<task>"

If the user specified another runtime too, pass it explicitly:

unset GITHUB_TOKEN
ao spawn --project <project> --agent codex --runtime tmux --claim-pr <pr> "<task>"

Verification Checklist

Immediately after spawn, inspect the session file under ~/.agent-orchestrator/.../sessions/<session> and confirm:

• agent=codex when Codex was requested
• pr=<expected PR URL> when a PR was specified
• runtimeHandle.data.launchCommand contains the expected CLI and model

Example verification:

python3 - <<'PY'
from pathlib import Path
p = Path("~/.agent-orchestrator/<hash>-<project>/sessions/<session>").expanduser()
print(p.read_text())
PY

For Codex requests, expected launch shape:

agent=codex
launchCommand=...'codex' ... --model 'gpt-5.4' ...

If you see gemini, claude, MiniMax, or another unexpected launcher, the spawn is wrong.

Tmux Monitoring

After verification, check the tmux pane with at least 20 lines:

tmux capture-pane -pt <tmux-session>:0.0 -S -40

Look for:

• real PR-specific work
• tool use
• red/green testing
• review or CI inspection

Do not accept a welcome screen, generic prompt, or stale queued message as evidence the worker is on task.

Recovery

If a worker was launched with the wrong agent or runtime:

ao session kill <session>
ao spawn --project <project> --agent codex --claim-pr <pr> "<task>"

Then re-run the verification checklist.

Common Mistakes

• Spawning without --agent codex because “the config probably defaults correctly”
• Inspecting ao status only, instead of session metadata
• Treating “session exists” as proof that the worker matches the user’s request
• Monitoring only the last 5 lines of tmux output

Minimum Completion Bar

Do not report success on AO setup until you have all of:

• explicit spawn command with required parameters
• verified session metadata
• verified launch command
• tmux evidence showing the worker is actually doing the assigned PR/task