/rex-agent

name: rex-agent
description: "Manage AI agent fleets in a Rex terminal: tile root + workers in one tab, start/prompt/wait/read them, check what they do, steer fleet panes; `help` lists all. Don't use for Herdr, tmux, or one-off Rex tabs, splits or commands."
license: MIT
compatibility: "Requires the rex CLI on PATH and a running Rex server (`rex whoami`) for every operation except `help`, which runs no rex command. The server must offer the block program_status method and session.resize_pane; workers must report OSC 7501 program status (draft rev 0.4)."
effort: medium
metadata:
  version: 1.0.0
  author: "Luong NGUYEN <luongnv89@gmail.com>"

Rex Agent

Build and control an AI-agent fleet in the root agent's Rex window. Keep the **root block** as orchestrator; add each **worker** as a right-hand column running the main agent's own launch profile; equalize all columns; then prompt, wait, read, monitor, steer, or tear down through the `rex` CLI and this skill's scripts.

A **session** holds **windows** (tabs), and a window holds **blocks** (panes). Rex has no agent registry and no prompt-and-wait call, so the scripts add both: a worker's **name** is its block label, and its **status** is the OSC 7501 program status record its own CLI reports. For everyday Rex commands outside fleet work, `rex skill show` prints the guide that matches the installed CLI. Relay reply deltas rather than whole screens to protect the context and token budget.

Choose the Workflow

| Request | Follow | |---|---| | `help`, or what this does and how to drive it | Help in `references/help-request.md` — answer and stop | | Spawn workers beside root | Phases 1–2, then 4–6 if assigning work | | Message an existing agent | Phases 3–5 | | Give several workers different tasks | Phases 3 and 7 (`dispatch`) | | Read without sending | Phase 3, then Phase 5 read only | | Check what the fleet is doing | Phase 6 | | Broadcast to a fleet | Phases 3 and 7 | | Focus/steer a pane | Phase 3, then Phase 7 | | Close workers | Phase 7 teardown | | Main agent's own context is filling up | Phase 8 HANDOFF |

Read only the reference needed by that branch:

• See `references/rex-recipes.md` for the layout, spawn variants, equal-width semantics, multi-line prompts, focus, troubleshooting, and edge cases.
• See `references/launch-profile.md` for where a worker's kind, model, thinking level, and flags come from, the kind gate, and what never carries over.
• See `references/delivery-and-waiting.md` for the per-kind status table, the prompt contract and exit codes, reading replies, the file fallback, and fleet monitoring.
• See `references/context-succession.md` for the main agent's context gate, HANDOFF procedure, and handoff brief template.
• See `references/final-report.md` for the closing report's status words, required parts, and examples.

Answer a Help Request

Resolve this branch **before** Prerequisites: someone asking how this works may not have Rex installed yet. Take it on `help`, `--help`, `/rex-agent help`, or any plain question about what the skill does. Print the text in `references/help-request.md`, or for a narrower question (how to broadcast) answer from that one phase and name it. Run no `rex` command, change nothing, and emit no completion report.

**Done when:** the user has the summary or their specific answer, and no `rex` command ran.

Check Prerequisites

1. Set `here` to the `scripts/` directory beside this SKILL.md. When the harness does not show the skill's base directory, use the resolver in `references/rex-recipes.md`. 2. Run `python3 "$here/agent.py" check`. It calls `rex whoami` with `--autostart=false`, because the default starts a missing server and a new empty server is not the user's. It confirms that `REX_SESSION` and `REX_BLOCK` name this terminal, and probes capabilities rather than versions (`rex version` is not semver): the block `program_status` method and `session.resize_pane`. On any failure it prints the fix, and the run ends `BLOCKED`. Outside a Rex terminal, never act on whatever session the app shows. 3. Treat the installed CLI as authoritative. Check an uncertain command with `rex <command> --help` rather than inventing flags; options from tmux or Herdr do not apply.

Follow Non-Negotiable Rules

1. **Keep root as a role.** Never replace or close the root block during fleet work. The one exception is a Phase 8 HANDOFF, where the orchestrator role migrates to a ready successor block; even then the outgoing block is retired to read-only, never closed without Rule 8 confirmation. 2. **Run exactly one orchestrator.** Only the current main agent writes to fleet blocks. After a HANDOFF ack, the outgoing agent issues no further prompts, splits, or closes. 3. **Use full IDs.** Resolve a worker by exact label from `rex block ls --json`, then use its full `block:` ID for every later call. Never pass a bare name to `-b`: Rex falls back to ID suffixes, so a hex-only name such as `beef` can select another block. 4. **Use one equal-width row.** Split the rightmost column `right`, keep every worker in the root window, and equalize. Create separate windows only when the user explicitly requests isolation. If the window holds a pane stacked above or below another, stop and ask. 5. **Fail closed before writes.** Refuse a `working`, `blocked`, unverifiable (no fresh record), or agent-less target, and never write to your own block. A `done` record survives its agent exiting to the shell, so a record counts only while its owner is the block's foreground process. 6. **Wait before follow-ups.** Never prompt while an agent is working. Every follow-up is its own `agent.py prompt` cycle. 7. **Surface blockers.** A trust, auth, or permission prompt needs a human. Focus the block and tell the user; never answer the dialog for them, and never type into a block whose state you cannot verify. 8. **Confirm destruction.** Closing blocks, windows, or sessions can lose work. Obtain explicit approval and prese