/ao-rules

name: ao-rules
description: >-
  Shared rules and the connection helper for every ao-* skill (run
  Orchestrator from chat). Read before running any ao-* skill.

AO rules

Every ao-* skill follows these rules. Other skills link here instead of repeating them.

AO hosts

An **AO host** is one computer that runs the AO daemon. Each host has its own projects, sessions and orchestrators, and AO never links them: a repo cloned on two hosts is two separate projects. AO names a project after its folder, so both can still get the same id, and then the same session id (for example `agent-orchestrator-1-12`) can exist on both. Always name a session as `<host>/<session id>`, and act only on the host that owns it.

Memory keeps one note named **AO hosts**, with one line per host:

| Field | Example | Meaning | |---|---|---| | `name` | `Pro` | A short name: the user's pick, else the model word of the ListMachines label (`Pro`, `Air`, `mini`). Never the network hostname such as `MacBookAir.lan` | | `reach` | `local` or `remote` | How you get to its AO | | `via` | `laptop` | The ListMachines label of the computer whose shell you use | | `base` | `http://192.168.1.20:7444` | Remote only. The host's LAN address from AO's remote access settings | | `header` | `~/.ao-grok/studio.header` | Remote only. File on `via` that holds the host's password |

• **local**: the Grok Bot desktop app runs on the AO host. `via` is the host itself.
• **remote**: the Grok Bot desktop app runs on another computer. You call the host's AO API over the network from `via`. The `ao` CLI on `via` talks only to `via`'s own AO, so never use it for a remote host.

One computer can be `via` for itself (local) and for other hosts (remote) at the same time.

Every run: call ListMachines, then use every host whose `via` computer is connected, in parallel, labelled by host name. Say once which hosts you could not reach. Never hard-code machine ids or home paths.

Calling AO

Start every shell command that calls AO with this helper. It works in zsh and bash:

aoapi(){ # aoapi METHOD PATH [JSON]
  local base hdr=() data=() f="${AO_RUN_FILE:-$HOME/.ao/running.json}"
  if [ -n "$AO_REMOTE_BASE" ]; then base="$AO_REMOTE_BASE"; hdr=(-H @"$AO_REMOTE_HEADER")
  else [ -f "$f" ] || { echo "AO_NOT_RUNNING" >&2; return 3; }
    base="http://127.0.0.1:$(grep -o '"port": *[0-9]*' "$f" | grep -o '[0-9]*$')"; fi
  [ -n "$3" ] && data=(--data "$3")
  curl -sS --fail-with-body --max-time 30 -X "$1" "${hdr[@]}" -H 'Content-Type: application/json' "${data[@]}" "$base/api/v1/$2"
}

• Local host: use `aoapi` as is.
• Remote host: on the `via` computer, first set `AO_REMOTE_BASE='<base>' AO_REMOTE_HEADER="$HOME/.ao-grok/<name>.header"`.
• Build JSON bodies with `python3 -c 'import json,sys; print(json.dumps(...))' "$ARG"`, never by pasting text into quotes.
• Anything longer than one line goes in a file first: `~/.ao-grok/out/<date>-<short name>.md` on `via`. The user can see what was sent.
• Use the `ao` CLI only where a skill says "local only".

Errors

| You see | Meaning and next step | |---|---| | `AO_NOT_RUNNING`, or connection refused on a local host | AO is not running there. Ask the user to open AO | | Connection refused or timeout on a remote host | The host is asleep, off this network, or remote access is off. Ask the user to check AO's remote access settings on the host | | HTTP 401 or 403 on a remote host | The host's password changed. Run ao-setup "Remote host" again | | HTTP 404 on a session path | No such session on that host. Check the host name | | Any other error | AO returns JSON with `message`. Relay it in plain words |

Who does what: orchestrator first

Each project on a host has at most one live **orchestrator**: an agent that plans the project's work, starts and steers workers, and gets their reports. It has more context than you do. You are the user's phone line to it.

• **Send to the orchestrator** (ao-orchestrator): starting or changing work, "catch me up", "why", "what next", plans, and anything that needs judgement about the code.
• **Do directly**: status lists (ao-status), answering a pending request with the user's own pick (ao-answer), stop and interrupt, merges after the user's yes, files and screenshots (ao-actions).
• Never start a worker yourself in a project that has a live orchestrator. Ask the orchestrator instead. With no orchestrator, ask the user whether to start one or to start the worker directly.
• After you act directly on a worker (answer, stop, merge), the orchestrator sees it through AO. Don't send it a separate note.

Decisions

A worker asks for two kinds of decision. A **question** (`user_input`) asks what to build. An **approval** asks permission to run a command or change files. Who decides depends on the mode, saved in memory:

1. **Default mode**: show each question or approval to the user as a card with the exact options. Answer only with their pick for that request. Never reuse a pick for a new request. 2. **Away mode** starts when the user says something like "I'm away", "decide for me" or "keep it moving". Save the scope and the end time in memory. Then:

• Answer routine questions yourself, and tell the user afterwards what you picked and why.
• Accept `low` and `normal` approvals with the one-time option (`kind` `allow_once`). Never pick an `allow_always` option: it changes the agent's permissions for good. Never accept a `high` approval without the user's yes for that request.
• Leave product direction, money, publishing and anything the user kept for themselves to the user.
• Away mode ends at the end time or when the user is back. Say when it ended.

3. **Standing approvals**: the user may list kinds of approvals to always accept. Follow the list exactly.

AO gives no risk level, so you judge it. Treat these as a floor. If a command looks riskier, call it high.

| Risk | Examples | |---|---| | high | Deletes outside the session's worktree, `rm -rf`, `git