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

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.