trio-claude
Skill2 starsChanged 26 days agoMITView on GitHub
Run a Claude trio loop (Claude-native Trio, native trio, trio loop with Claude) - start, continue, resume, check status of, or land a Trio loop on a mailbox by driving the installed release launcher native/launch.sh (host engine, frozen acceptance per profile, root-free, lands at SHIP). This is the default for a plain run/start/continue the trio loop request (also status, land or resume of such a loop) when the user names no other harness. If the user names Omnigent or Cursor use trio-omnigent instead; for OpenCode, Codex, Kimi or another harness use that harness's own Trio entrypoint. Never invoke the trio-native Workflow directly.
The file
We split this skill into the rules it gives an agent
12 rules. About 0 are common, 2 are distinctive, and 10 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈2
Distinctive · estimate
This author's own choices. Worth a look.
10
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 10
Never run the Lead, the Evaluator, builders, scouts or the commit gate in this session.
- Very specific: line 11
Never call the Workflow tool (the saved trio-native workflow) directly.
- Very specific: line 12
Never pass --dangerously-skip-permissions, and never edit settings or permissions files.
- Distinctive: line 14
Never edit mailbox files, except where a step below says so.
- Very specific: line 48
continue / resume: read <mailbox>/.native-launch.json (recorded args, engine) and <mailbox>/.native-result.json (if any), then pick one:
- Very specific: line 58
abandon: only on the user's explicit request: bash "$L" abandon --mailbox <abs>/loop.
- Very specific: line 68
If status later reports driver_dead before a result was written, that is a kill mid-run: offer the resume_command it prints (run it only if …
- Distinctive: line 78
Every re-arm after that carries the last event you have seen, so nothing is missed and nothing is reported twice:
- Very specific: line 97
If the repository's own instructions (its CLAUDE.md / AGENTS.md) authorise this session to resolve verify: human checks itself, a …
- Very specific: line 115
When status shows the loop finished, read <mailbox>/.native-result.json via status.
- Very specific: line 133
If a needs_human reason carries an acceptance adopt refusal (it prints a command with --acceptance-adopt <12-hex pin>), show that exact …
- Very specific: line 137
Always say the mode (lockstep or open-loop, from the result), the engine (from .native-launch.json engine) and whether acceptance was on.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
You run a Claude-native Trio loop by driving the installed release launcher. You are the orchestrator only: you start the launcher, wait, and report. The launcher owns the Lead, the builders, the Evaluator, the commit gate, frozen acceptance and the landing at SHIP.
Hard rules
- Never run the Lead, the Evaluator, builders, scouts or the commit gate in this session. Never spawn
trio-*role agents yourself. The launcher does all of it. - Never call the Workflow tool (the saved
trio-nativeworkflow) directly. It is the launcher's internal engine: calling it skips the host engine and leaves frozen acceptance off. - Never pass
--dangerously-skip-permissions, and never edit settings or permissions files. - Never poll in a sleep loop. Start with
--detach(below), then arm the stop waiter AND the ScheduleWakeup/CronCreate second channel (§5): the waiter runs in the background and blocks with negligible CPU until the loop stops, so it is not a poll loop. Never pollbash "$L" statusin a loop. Never watch a loop with apgrep/ps … | grep/sleeploop either: such loops match themselves and never end. Watch a loop only with thewaitcommand (§5). - Never edit mailbox files, except where a step below says so. HUMAN.md is written only by the trio-dash Answer box or by the user, never by you.
- One mailbox per loop. Never start a second launcher on a mailbox while one runs (
statusis safe at any time).
1. Find the launcher
L="${XDG_DATA_HOME:-$HOME/.local/share}/trio-agent-loop/current/native/launch.sh"
[ -f "$L" ] && [ -x "$L" ] && echo okThat is ~/.local/share/trio-agent-loop/current/native/launch.sh, the installed Trio release. If it is not an executable regular file, tell the user the Trio release with the native launcher is not installed (install the Trio release bundle; ./install.sh --global installs the skill only, not the launcher) and stop. Always run it as bash "$L" ....
2. Find the mailbox
The mailbox is the directory the user names, else <git toplevel of the current directory>/loop. Resolve it to an absolute path. It must contain GOAL.md and STATE.md. If it does not, offer /trio-init <goal> (or /trio-init dir=<name> <goal>) and stop. If the repository has several loop* mailboxes and the user named none, ask which one.
On EVERY user turn that touches a loop, and on every session (re)start (fresh, resumed or compacted), first catch up on stops you missed (inbox is quick, run it in the FOREGROUND before anything else, including on "continue" and on "status"):
bash "$L" inbox --repo <repo root>It lists the loop's unacknowledged stop events (kind, loop, iteration, summary, the event id). Relay each one with the rules in §5, then bash "$L" ack --event <id> it. Then make sure a waiter is armed for every loop still running, together with the ScheduleWakeup/CronCreate second channel (§5): a waiter killed by Claude Code under memory pressure, or lost with an ended session, is re-armed on the next turn, and inbox is the catch-up for what it missed. A session that ended lost its waiter, but the event is still durably in the host index and this inbox; read a loop's own record only after inbox says nothing is pending.
3. Map the request to an action
start / run (also a plain "run the trio loop"):
bash "$L" start --mailbox <abs>/loop --detach [options]Pass options only when the user asks for them: --no-acceptance / --acceptance, --engine workflow (or host), --root-bound, --max-iterations N, --target BRANCH, --slice-eval-concurrency N, --max-repair-rounds N, --worktree-root /abs/dir, --max-hours H (engine time limit, default 6), --commit-attribution, --allow-overlapping-writes, --refuse-overlapping-writes, and --acceptance-adopt PIN12 (only a pin the user approved). With no options the launcher uses the host engine, frozen acceptance per the Trio profile, a root-free Lead worktree and --max-iterations 4.
continue / resume: read <mailbox>/.native-launch.json (recorded args, engine) and <mailbox>/.native-result.json (if any), then pick one:
- The last run stopped
needs_land: runland(below). - The last run was killed mid-run (the session crashed, or
statusreportsdriver_deadwith no.native-result.jsonfor the recordedsession_id):bash "$L" resume --mailbox <abs>/loop --run-id wf_... --detach. Take the run id from.native-result.jsonrun_id, else the newestwf_*under${CLAUDE_CONFIG_DIR:-~/.claude}/projects/*/<session_id>/subagents/workflows/. If no run id can be found, do a freshstartwith the recorded flags. - Any finished stop (
needs_humanafter the human answered,held,error,budget,max_iterations, orblockedafter a redirect): a freshbash "$L" start --mailbox <abs>/loop --detachre-using the recorded options. A root-free loop re-attaches to the same Lead worktree; a journalresumeof an ended run would only replay the same stop. Raise--max-iterationsonly if the user asks.
status: bash "$L" status --mailbox <abs>/loop in the foreground (it is quick). Summarize the JSON: mode, iteration, STATE, Lead worktree, target, and driver_alive. If driver_dead is set, say the driver died and offer the printed resume_command (run it only if the user agrees). The status output is the source of truth for progress: when root_copy_stale is set the root mailbox copy is stale while a root-free run is live (it holds a LIVE-MAILBOX pointer), so never read the root copy's STATE.md for progress.
land: bash "$L" land --mailbox <abs>/loop --detach, detached like a start. It retries the landing with the recorded args.
abandon: only on the user's explicit request: bash "$L" abandon --mailbox <abs>/loop.
4. Run it detached
start, resume and land take hours. Run bash "$L" start --mailbox <abs>/loop --detach (the same for resume and land) in the FOREGROUND. It returns at once with one JSON line {"detached": true, "pid", "log", "status_command"}. Do not use the Bash tool's run_in_background for these commands and do not give them a long timeout. Tell the user the loop is running: the mailbox, the pid and the log path (plus the engine and acceptance setting if the launcher printed them). The loop no longer depends on this session staying alive.
Then arm the stop waiter and the ScheduleWakeup/CronCreate second channel (§5) and end the turn; the waiter's task notification or the scheduled wakeup re-invokes this session.
--detach waits for host admission (other live loops, memory) instead of failing; --no-wait-admission makes a full host refuse with exit 9 instead.
If status later reports driver_dead before a result was written, that is a kill mid-run: offer the resume_command it prints (run it only if the user agrees).
5. Stop notifications — never miss a stop
After EVERY start, resume, land, and every answer-and-restart, arm the waiter immediately, as a background task with the Bash tool (run_in_background: true), and arm the second channel (below) in the same turn. A session that ends its turn with only a background Bash waiter has effectively nothing armed.
bash "$L" wait --mailbox <abs>/loopEvery re-arm after that carries the last event you have seen, so nothing is missed and nothing is reported twice:
bash "$L" wait --mailbox <abs>/loop --since <last seen event id>The id is the waiter's last JSON line's event.id, or the newest event id inbox showed for that loop.
Run it with run_in_background: true and with NO timeout parameter on the Bash call (the --detach start/resume/land itself stays a FOREGROUND call, §4): a Bash timeout kills the background waiter at that limit, and the waiter has its own --timeout-hours (below). A Monitor on the same wait command is an acceptable alternative to the background Bash call, but a Monitor expires after its timeout_ms (30 min at most), so it must be re-armed far more often. Either way the waiter is only half of the arming: also arm the second channel (below). It blocks with negligible CPU until the loop's next stop — it is not a poll loop — and prints a human block — kind, loop, iteration, the verbatim question for needs_human, the land/merge result, branch, log path, the exact next command — and a last JSON line {"kind", "exit", "event", "rearm"}. It returns at once if the loop already stopped; every start/resume/land records a started event, so arming right after a start never re-reports the previous stop. Default timeout 24 h (--timeout-hours H). Never hand-roll pgrep / ps … | grep / sleep / log-regex waiters (they match themselves, never end, or fire on unrelated log lines such as kill_check: error); wait is the only supported waiter — use only the wait command. bash "$L" wait --help prints this recipe (with L set as in §1; it is launch.sh wait --help).
One waiter per loop. Do not arm a second waiter for the same mailbox while one is still running in this session; when you arm a new one, stop the old one first. Then keep working or end the turn — the waiter's task notification re-invokes this session.
Second channel — arm it on every turn that leaves a loop running. The waiter can die unseen: a run_in_background Bash call made with a timeout is killed at that timeout, Claude Code kills background tasks under host memory pressure, and a Monitor expires. So every turn that leaves a loop running must ALSO arm a durable channel that does not depend on the waiter surviving: ScheduleWakeup or CronCreate, every 20–30 min, whose prompt runs bash "$L" inbox --repo <repo root> (and re-arms the waiter with --since <last seen event id> if it is gone). A session that ends its turn with only a background Bash waiter has effectively nothing armed. Re-arm the second channel too whenever it fires and a loop is still running; stop it once no loop is running.
On ANY wake — a waiter exit, a scheduled wakeup, a cron firing, a user message or a session start — run inbox first, before reading any loop file (bash "$L" inbox --repo <repo root>, FOREGROUND), relay and ack what it lists, then re-arm.
When the notification arrives, read the waiter's output and relay it:
needs_human(exit 5): the verbatim question from the waiter output (andVERDICT.md's## Human checksteps). Tell the user what they can answer: the trio-dash Answer box (start it withtrio-dashfrom the repository root if it is not running), then say "continue". Never write HUMAN.md yourself.- If the repository's own instructions (its CLAUDE.md / AGENTS.md) authorise this session to resolve
verify: humanchecks itself, aneeds_humanwake means: do the check, answer, relaunch, re-arm (waiter + second channel). Otherwise relay the question to the user VERBATIM. Never assume the authorisation.
- If the repository's own instructions (its CLAUDE.md / AGENTS.md) authorise this session to resolve
landed(exit 0): what landed where — the landed commits (commit_shas) and the target branch.blocked(2),needs_land(8),land_blocked(12),error(3),max_iterations(4),held(7),driver_dead(10),supervisor_gave_up(11),needs_retirement(6): the cause plus the offered next step (resume, land retry, raise iterations, abandon) from the outcome table in §6 — run it only if the user agrees, as always.interrupted(13): the driver went away and nothing will resume it; offer theresume_commandas in §6.
Then bash "$L" ack --event <event id> (the id is the last JSON line's event.id; acknowledge the same events the dashboard shows). Answering a needs_human in the trio-dash Answer box does not acknowledge the stop event: ack it with bash "$L" ack --event <id> once you have relayed it. A launch whose engine never began reaches this waiter as error (exit 3) with details.reason and the retry details.next_command: relay the reason and offer that command. After the user answers and the loop is restarted, arm a new waiter immediately.
After ANY waiter exit, re-arm with --since <last seen event id>:
- A relayed stop: after relaying and acking it, re-arm with
--since <that stop's id>so it is never re-reported (only if the loop is still running or was restarted; one waiter per loop still holds — stop the old one before arming a new one). - Exit
124(timeout): the loop simply has not stopped yet — re-arm silently: run the samewaitagain in the background (with--since <last seen event id>) and say nothing to the user. - A Monitor expiry, or any task completion/kill notification, counts as a waiter exit: re-arm with
--since <last seen event id>. - Killed by the harness (for example Claude Code killing background tasks under memory pressure, or the task reported as killed/failed without a stop block) or any other unexpected exit code: re-arm with
--since <last seen event id>and tell the user once. Any other unexpected exit: re-arm once and tell the user what happened.
A waiter killed under memory pressure, or lost with an ended session, is re-armed on the next turn; a session that ends loses its waiter, but nothing is lost: the stop is still a durable event in the host index, visible in the dashboard and returned by bash "$L" inbox --repo <repo root> when this or another session next (re)starts work, and on every user turn that touches a loop (§2).
6. Report the outcome
When status shows the loop finished, read <mailbox>/.native-result.json via status. A run that never started writes <mailbox>/.native-runs/<session>.result.json instead. Report plainly, by status and exit code:
| exit | status | what you do | ||
| 0 | shipped | SHIP, landed (landed: true). Name the landed commits (commit_shas) and the target branch. Next command: none. | ||
| 2 | blocked | Surface VERDICT.md's "what the human must decide". The user answers through the trio-dash Answer box; after that the next command is a fresh bash "$L" start --mailbox <abs>/loop. | ||
| 2 | start refused: cross-loop writes overlap | By default the overlap check only warns; a start is REFUSED only when the refusal was opted into (--refuse-overlapping-writes or TRIO_REFUSE_OVERLAPPING_LOOPS=1). No result; stderr says the PLAN's writes: overlap a live loop of the same repository. Show stderr. Run bash "$L" status --mailbox <abs>/loop, wait for the other loop, or, only if the user confirms the overlap is safe, run bash "$L" start --mailbox <abs>/loop --allow-overlapping-writes. Any other exit 2 with no result is a usage or record refusal: show stderr. | ||
| 3 | interrupted | The driver died or hit its time limit. Show reason, run bash "$L" status --mailbox <abs>/loop, and run the resume_command (from status / the result) only if the user agrees. | ||
| 3 | error (or no result parsed) | Show reason, the raw output path under <mailbox>/.native-runs/, and run bash "$L" status --mailbox <abs>/loop. A fresh bash "$L" start --mailbox <abs>/loop now resumes an error-stopped loop from its last durable phase. Operators can force a phase with `bash "$L" start --mailbox <abs>/loop --restart-from <lead-running | lead-done | repair-running>`; offer it only when the user asks. |
| 4 | max_iterations / budget | Say so. Continuing needs the user to raise --max-iterations (or the budget): bash "$L" start --mailbox <abs>/loop --max-iterations N. | ||
| 5 | needs_human | Show human_check (the Evaluator's ## Human check from <mailbox>/VERDICT.md) with its exact steps. The user answers through the trio-dash Answer box (if the dashboard is not running, the user starts it with trio-dash from the repository root), which writes the verified HUMAN.md entry. A hand-written HUMAN.md entry is ignored by the driver. After that the user says "continue" and you run a fresh bash "$L" start --mailbox <abs>/loop. | ||
| 5 | needs_human with reason starting live-check <name>: | A live check declared in GOAL.md ## Live checks could not run. Show the reason and its exact fix (for example op signin, or creating the missing env file the reason names), tell the user to do it, then run a fresh bash "$L" start --mailbox <abs>/loop. Never read env or credential files yourself. | ||
| 5 | error with lock: foreign (locked mailbox) | A live driver holds the mailbox lock. Run bash "$L" status --mailbox <abs>/loop and wait for that driver to finish. Run bash "$L" abandon --mailbox <abs>/loop only on the user's explicit request. Never start a second launcher. | ||
| 6 | needs_retirement | Show reason. The SHIP's retirement commits are missing: recover with /trio-ship, then a fresh bash "$L" start --mailbox <abs>/loop. | ||
| 7 | held | Show reason. "Continue" is a fresh bash "$L" start --mailbox <abs>/loop. | ||
| 8 | needs_land | Shipped, but the landing is blocked. Run bash "$L" land --mailbox <abs>/loop once. If it is a conflict, explain it (lead_worktree, conflicts): the user resolves and commits in that Lead worktree, then you run bash "$L" land --mailbox <abs>/loop again. | ||
| 9 | admission refused (no result) | Too many live loops on the host, or memory below the floor (--no-wait-admission was given). Wait, or re-run bash "$L" start --mailbox <abs>/loop --detach, which waits for admission. |
If a needs_human reason carries an acceptance adopt refusal (it prints a command with --acceptance-adopt <12-hex pin>), show that exact command and ask the user to approve it before running it. Never adopt a pin on your own.
Never shorten an adopt, resume or restart command you show the user: quote it whole, from the first word to the last flag (the launcher's detail text is cut at 900 characters, so take the command from .native-result.json or the raw output, not from a truncated excerpt).
Always say the mode (lockstep or open-loop, from the result), the engine (from .native-launch.json engine) and whether acceptance was on.
Not this skill
- The user names Omnigent or Cursor: use
trio-omnigent. - The user names another harness (OpenCode, Codex, Kimi, ...): use that harness's own Trio entrypoint.
- A deliberate single supervised iteration:
/trio, which only the user invokes. - An orphaned SHIP verdict whose retirement commits are missing:
/trio-ship.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

