# orchestrate-skill

The **main-actor** pattern for bot teammates. One bot owns the chat and never
blocks — it delegates real coding/build work to persistent `tmux` sub-agents,
polls a done-marker, and reports results back.

> One voice talks, hands stay clean.

## What's inside

```
skill/SKILL.md   the skill itself (the playbook, conventions, anti-patterns)
bin/mav-agent    spawn/observe named claude or codex sub-agents (one tmux window each)
bin/mav-tmux     run a one-off command in the shared persistent tmux session
install.sh       drop the skill + wrappers into your ~/.claude and ~/.local/bin
```

## Why

If you do heavy work inline in your own turn, the chat freezes and the work dies
when your session compacts or restarts. Instead: spawn the work in a tmux window
that **outlives your turn**, and use a real file marker for the handoff so you
always know when it's finished — no prompt-sniffing, no guessing.

## The clean handoff

Every `mav-agent run` writes, when the CLI exits:

- `/tmp/mav-agent/<name>.out`  — full stdout/stderr
- `/tmp/mav-agent/<name>.done` — exit code (present **only** when finished)

`mav-agent status` / `wait` poll the marker. Present ⇒ done. That's the whole trick.

## Install

```bash
git clone https://git.sevara.cloud/mav/orchestrate-skill.git
cd orchestrate-skill && ./install.sh
```

Requires `tmux`, plus `claude` and/or `codex` on PATH. Then the `/orchestrate`
skill shows up in your Claude Code session and the `mav-agent`/`mav-tmux` CLIs are
on your PATH.

## The loop

1. Acknowledge in chat fast — never a silent turn.
2. `mav-agent run <name> "<self-contained task with full context>"`
3. `mav-agent wait <name> 60` (short) or end turn + `mav-agent status <name>` next wake.
4. On done: `mav-agent result <name>`, summarize, reply. Check the exit code.
5. `mav-agent kill <name>` once you've read it.

See `skill/SKILL.md` for the full reference.