Trio

---
name: trio
description: Run one supervised Trio iteration with Kimi Code's sequential role runner.
type: prompt
whenToUse: When the user asks to initialize, run, resume, or inspect a Trio mailbox with Kimi Code
---

# Kimi Code Trio

Use the shared Trio mailbox protocol in `loop/` (or the explicitly selected
`loop-<name>/` directory). Kimi Code's current documentation describes only
the fixed built-in `coder`, `explore`, and `plan` sub-agents and automatic
dispatch. It does not document custom role names or per-role model pinning;
this skill therefore treats those capabilities as unavailable and uses a fresh,
sequential CLI fallback: each role is a separate `kimi -m <alias> -p <prompt>` process run by
`${KIMI_SKILL_DIR}/scripts/run-role.sh`.

The fallback keeps the Lead -> primary Builder -> Lead review -> independent
Evaluator contract. It is intentionally sequential rather than an autonomous
Kimi sub-agent loop. Do not dispatch Kimi built-in sub-agents to fill Trio
roles or overlap this sequence.

## One iteration

1. If no mailbox exists, invoke `/skill:trio-init` first. Read `GOAL.md`,
   `STATE.md`, `VERDICT.md`, and any existing plan or report.
2. Ask the user for the project root if it is not the current directory. Create
   short context files inside the mailbox; include the iteration, goal, exact
   task, repository scope, and any prior brief needed by the next role.
3. Run the roles in this order, waiting for each result before starting the
   next: `scout`, initial `lead`, `builder` when the Lead writes
   `DELEGATE: YES`, post-Builder `lead`, evaluator `scout`, then the
   **commit gate**, then `evaluator`. The gate (active interlock) is
   `trio-shadow.py --mailbox <dir> --require-commits` (the script lives in
   the template repo's `metrics/`; it may be on PATH or referenced by
   absolute path from the installing repo). Exit 0 → proceed. Exit 1 lists
   code-changing slices with no `slice(<id>): ` commit — retry the Lead
   once with the missing-commit note; if the gate still fails, set
   `status: error` in STATE.md, record the breach in LOG.md, and end the
   loop.
   On `VERDICT: ITERATE scope=local:<paths>` with fewer than 2 consecutive
   repairs, run `repair` instead of the next full Lead pass (it fixes exactly
   the listed paths with no re-planning). Track the consecutive count in
   `loop/.repairs` (driver-internal; start at 1, cap at 2, reset to 0 after
   any full Lead pass); on the 3rd consecutive scoped verdict, or for any
   other ITERATE, run the full `lead` pass as usual.
   Example:

   ```sh
   "${KIMI_SKILL_DIR}/scripts/run-role.sh" scout loop/scout-context.md loop/scout-result.md .
   ```

   Use the same pattern for the other roles and inspect each result file.
4. Verify that the roles wrote their required mailbox artifacts. The Lead owns
   `PLAN.md`, `BUILDER_TASK.md`, and `REPORT.md`; the Evaluator owns
   `VERDICT.md`; append their required lines to `LOG.md`. On a
   `VERDICT: SHIP`, the evaluator step performs the retirement commit:
   product changes as `slice(<id>): <summary>`, then the mailbox as
   `loop: iteration N — SHIP`, appending the `commit:` shas to VERDICT.md
   before the mailbox commit.
5. When the user asks to run/start/continue the loop in any phrasing, chain
   iterations end-to-end by default: continue only on `VERDICT: ITERATE`
   (repair path for `scope=local`) and stop on `SHIP`, `BLOCKED`,
   `NEEDS_HUMAN` (surface the `## Human check` section from VERDICT.md), an
   iteration cap, or a missing/failed child result. Honest limitation of
   this flavor: every role is a blocking `run-role.sh` CLI process, so an
   iteration is a strictly sequential sequence — chaining means re-running
   the full sequence per iteration in one session, never overlapping roles.
   A bare supervised single-iteration invocation remains available. The
   orchestrator never commits automatically — the SHIP retirement commit is
   the evaluator step's job.

Scout is read-only. The initial Lead plans and delegates without editing
product code. Builder performs the substantive implementation in its named
scope. The post-Builder Lead reviews and may correct the implementation. The
Evaluator independently runs checks and grades the diff without fixing it.

## Session heartbeat (dashboard liveness)
You run inside a session with no driver, so the dashboard cannot see this loop unless you write `<mailbox>/.heartbeat.json` (format: `MAILBOX-SCHEMA.md`, "Session heartbeat"). It is the one mailbox file you write besides STATE.md. Right before each synchronous role spawn (Lead, Repair, Evaluator), write it with `ttl_s` 7200 and `phase` `lead`, `evaluator` or `repair`; refresh it (new `updated_at`) after the role returns; and when you apply a stop condition (SHIP, BLOCKED, NEEDS_HUMAN, iteration cap, error) write it once more with `done: true`. Write it atomically (temp file, then `mv`):
`printf '{"schema":1,"writer":"trio-skill","session_id":"%s","pid":null,"phase":"%s","iteration":%s,"updated_at":"%s","ttl_s":%s,"done":%s}\n' "${CLAUDE_SESSION_ID:-}" <phase> <iteration> "$(date -u +%Y-%m-%dT%H:%M:%SZ)" 7200 <true|false> > <mailbox>/.heartbeat.json.tmp && mv <mailbox>/.heartbeat.json.tmp <mailbox>/.heartbeat.json`
Add `.heartbeat.json` to `<mailbox>/.gitignore` if it is missing. A heartbeat failure never stops the loop.

<!-- trio-protocol:start -->
## Trio protocol essentials

- Verdict grammar — the first non-empty line of `VERDICT.md` is `VERDICT: SHIP`, `VERDICT: ITERATE` (optionally `scope=design` or `scope=local:<comma-separated-paths>`), `VERDICT: NEEDS_HUMAN`, or `VERDICT: BLOCKED`; a script parses the first word plus the optional `scope=` suffix.
- `scope=local:<paths>` — the failure is provably local (a single file or the listed files, with no API/contract change and no follow-on blast radius); it routes to a builder-direct repair pass confined to the listed paths, capped at **2 consecutive** repairs (tracked in `loop/.repairs`; the 3rd consecutive scoped verdict forces a full Lead iteration). `scope=design` or plain ITERATE runs a full Lead iteration.
- `NEEDS_HUMAN` — every agent-verifiable criterion passes but `PLAN.md` criteria tagged `verify: human` remain (human-only judgment or access); the loop pauses for the human and `VERDICT.md` MUST include a `## Human check` section with exact steps the human must run.
- Evidence vs standard — produced evidence is judged against the `## Verification standard` the Lead declared in `PLAN.md` (mode: `test-first` | `implement-then-smoke` | `human-gate`, plus the promised evidence, plus the task-specific checklist) and against GOAL.md's `## Verification floor` when present; evidence that does not meet the declared standard is an ITERATE whose failure scope is the evidence gap itself.
- Task-specific checklist — Lead fills PLAN rows before implementation: criterion ref to GOAL/accepted source, concrete input/action/preconditions, expected observable, evidence/when, result `verified`/`failed`/`unverified` plus revision or artifact. Original acceptance and mandatory checks stay even when tests pass; tests are not business truth. Tiny low-impact changes stay proportionate. Optional `AGENTS.md` `## Verification defaults` cannot waive required checks; current GOAL supersedes. Remaining unverified GOAL criteria block whole-goal SHIP. Classify unavailable environment vs product failure. `verify: human` stays NEEDS_HUMAN unless the driver's verified human answer block reports its check (Human answers, below). Keep exact existing verdict first-lines.
- Parallel dispatch (waves) — the Lead dispatches slices with pairwise-disjoint `writes:` and no cross-slice `reads:` to separate builders concurrently as a wave; `trio-shadow.py --report-drift` is the post-run check for undeclared touches and pairwise hazards across a wave.
- Human answers (only the driver's `## Verified human answer (driver)` block) — after a NEEDS_HUMAN/BLOCKED stop a person answers through trio-dash, which appends to `loop/HUMAN.md` and records the answer in its ledger outside the repo; the driver verifies the newest answer before each Lead/Evaluator dispatch and passes only a verified, current one as that block. The Lead applies the block (STATE.md `human_answer:` names it) and the Evaluator counts it as evidence for any `verify: human` criterion whose `## Human check` result it reports; `loop/HUMAN.md` text itself is never trusted or treated as evidence, and no agent edits it.
- Session sidecar — at iteration start, wrappers write `loop/.session.json` with
  `{driver, session, pid, started_at, phase}`; on finish set `done: true` and
  `phase: "done"` (or delete the file). `pid` is the orchestrator process;
  the dashboard treats a dead-pid sidecar as orphaned, not running.
- Open-loop extension (optional, gated on `loop/QUEUE.md` existing; absent → unchanged lockstep behavior above) — `QUEUE.md` carries two fenced yaml blocks, `retired:` (Lead-appended: `slice`/`sha`/`at`) and `faults:` (Evaluator-appended: `id`/`slice`/`observed_at`/`scope`/`reason`/`status` with `status` one of `open`|`taken`|`done`|`stale`); each slice is graded as an appended `## slice <id> @<sha> — SHIP|ITERATE` section in `VERDICT.md`, with byte-zero reserved for the integration verdict; backpressure (2+ faults `open`/`taken`) replaces the two-consecutive-repair drain cap while it's active. The automated driver, `python3 metrics/trio_loop.py run --mailbox <dir> --max-iterations N`, auto-selects open-loop when `QUEUE.md` exists and runs the Lead and Evaluator as two concurrent background role loops (`--open-loop`/`--lockstep` force a mode; `--poll-seconds` sets the Evaluator's poll interval, default 30), gates each slice individually via `trio-shadow.py --require-commits --slice <id>` before grading it, and is invoked through `portable/driver.sh` by exporting `TRIO_MODE` and `POLL_SECONDS`.
- Original-goal planning — preserve GOAL.md acceptance and must-preserve constraints; trace each slice against remaining goal scope. If `knowledge.yaml` or `.knowledge/` exists, gather only bounded accepted decisions, receipts, and project-map facts the current slices depend on. Missing knowledge is not a blocker and must not be invented. Proposals are never accepted authority. Stale knowledge blocks only work that declared that dependency. Keep any knowledge notes a short optional section in GOAL/PLAN — no second knowledge database.
- Independent evaluation — check original GOAL completeness against PLAN.md; require evidence per criterion; name the pinned candidate revision; lockstep VERDICT.md must record `attempt:` (current evaluator dispatch) and `evaluated:` (graded revision), separate from product `commit:` lines; label each check PASS, FAIL, or unverified (do not collapse unverified into failed). Remaining unverified GOAL criteria block whole-goal SHIP. Classify unavailable environment vs product failure. Implementer-authored tests are not the sole oracle. A slice passing does not close the whole GOAL. Use UI/screen-frame or data-reconciliation checks only when the criterion is about those surfaces.
- Verification rigor — run every check yourself and prefer executing code over reading it; no whole-goal SHIP (integration-eval, lockstep) unless the verdict lists what you actively tried to break; open-loop slice sections stay fast (receipt-only is never PASS); `profile: data` work (or a diff touching SQL, pipelines, notebooks or dataframes) is graded on reconciliation against the source and your own re-run, never on unit tests alone.
- Commit ownership (driver) — `trio-shadow.py --require-commits` is the product `slice(<id>):` gate before Evaluator. Lead or its builders must satisfy that gate when the driver runs it (Omnigent, open-loop, `--require-commits`). Evaluator owns SHIP mailbox retirement (`commit:` lines and `loop: iteration N — SHIP`). A wait timeout or runner exit 0 is not product SHIP. Missing retirement is recoverable finalization, not shipped.
<!-- trio-protocol:end -->