Orchestration Protocol

🔁 Orchestration Protocol

Purpose: One protocol for surveying the runtime, picking the right execution mode, and building until done — without asking the user between tasks. Version: 1.0.0 For: Toh Framework v2.0.0+ Used by: /toh, /toh-vibe, /toh-plan — MANDATORY for multi-task work

Core idea: the plan is a file, never chat state. .toh/plan.md holds the backlog, .toh/progress.md holds the ledger, and the loop runs until every "Done When" criterion is verified. The model only remembers what is saved to disk.

🔍 A. 2-Step Survey (run before any multi-task job)

Step 1 — Identity (declared, never guessed)

Your runtime identity is declared by the platform context file that loaded you:

Confirm capabilities from .toh/capabilities.json (written by the installer). If it is missing, infer conservatively: Claude Code has subagents, teams, hooks, /goal, /loop; Cursor (2.4+) and Antigravity have native/file-based subagents but no teams; Codex and ZCode are single-session sequential.

Step 2 — Runtime probe (ONLY for what install time cannot know)

Probe exactly these, nothing else:

Do NOT invent other detection heuristics. Identity comes from Step 1; the probe only checks feature gates.

🪜 B. Execution Ladder

Three rungs, best first. Each rung: if unavailable, fall back one rung. Sequential is the floor and is always available.

1. AGENT TEAMS — Claude Code with the teams env flag set, AND the plan has >= 3 independent modules plus a QC role. Recipe in Section F. If unavailable, fall back one rung.
2. NATIVE SUBAGENTS — the Agent tool (Task) exists. Delegate tasks to TFW agents; parallel only under the rules below. If unavailable, fall back one rung.
3. SEQUENTIAL SELF — execute every task yourself, in order, in this session. This is the default mode and the correct choice more often than not.

When to use which

Hard limits (load-bearing — never soften)

Parallelism must be earned by independence — a wrong parallel split costs more than sequential ever would.

Delegation brief (subagents and teammates)

Every spawn prompt MUST carry:

• The plan task line verbatim (T-ID, agent, description, exact file path) — the worker touches ONLY those files.
• The phase Checkpoint command, with instructions to run it and report the actual output.
• For UI tasks: "read root DESIGN.md first — all tokens/typography/nav come from it."
• The reminder that its report will be re-verified by the orchestrator (Section E step 4).

🎚️ C. Model Routing

Mirrors TFW agent frontmatter; teams and subagents both honor per-agent model fields.

On runtimes without model routing, ignore this table and proceed.

📄 D. Plan Artifact — .toh/plan.md

The contract between /toh-plan (writes it) and /toh-vibe (executes it). Compact state file, <= 150 lines, re-read once per phase.

markdownCopy code
# Plan: <project name>
Status: draft | approved | building | done
Created: <date> by /toh-plan

## Goal
<one paragraph: what, for whom, why>

## Stack
- <framework, styling, data — bullets>

## Pages
| Page | Route | Purpose |
|------|-------|---------|

## Done When
- [ ] `npm run build` exits 0
- [ ] Every route in Pages renders without console errors
- [ ] <observable feature criterion, e.g. "adding an item updates the cart badge">

## Phase 1 — <name>
- [ ] T000 design-reviewer — generate root DESIGN.md (design identity)
- [ ] T001 [P] ui-builder — dashboard shell in app/dashboard/page.tsx
- [ ] T002 dev-builder — cart state hook in lib/use-cart.ts
**Checkpoint:** `npm run build` exits 0 AND /dashboard renders

## Phase 2 — <name>
- [ ] T003 ...
**Checkpoint:** <runnable command + expected result>

Schema rules

• Task grammar: - [ ] T001 [P] agent-name — description in app/exact/path.tsx. Exact file path mandatory. [P] = parallel-safe (disjoint files only). Each task sized to fit one context window.
• T000 rule: any project/feature with UI gets T000 design-reviewer — generate root DESIGN.md as the FIRST task, before any UI task. UI tasks depend on it.
• Checkpoint per phase: a runnable command + expected result. Phases end at checkpoints, not at vibes.
• Done When: runnable/observable acceptance criteria for the whole plan — completion is verified against these, never self-assessed.
• Blocked marker: flip - [ ] to - [!] and append BLOCKED: <one-line diagnosis>.
• NO Progress Log in plan.md — state history lives in .toh/progress.md. Keep plan.md a compact snapshot: checkboxes ARE the state.
• Status lifecycle: draft (written, awaiting one approval) → approved (user said Go, or /toh-vibe auto-approves its own mini-plan) → building (loop running) → done (all Done When verified).
• Terminal statuses — auto-resume exemption: a plan whose Status is done, draft, blocked, or paused (any case) is TERMINAL for auto-resume: report the status, do not resume its checkboxes. blocked/paused are manual header overrides for parking a plan; flip Status back to approved/building (or say "continue the plan") to make it resumable again.
• Archive: when a new plan is needed and Status is done (or the user says "fresh start"), move the old file to .toh/memory/archive/plan-<date>.md first. One active plan at a time.
• Memory pointer: .toh/memory/active.md holds only a POINTER — plan status + next unchecked task — never a plan dump.

Ledger — .toh/progress.md

Append-only, one line per state change, plus learnings:

Copy code
2026-07-16 14:02 T001 queued
2026-07-16 14:03 T001 running (ui-builder)
2026-07-16 14:11 T001 done — CHECK_OK: npm run build exit 0
2026-07-16 14:30 T004 blocked — BLOCKED: STRIPE_SECRET_KEY missing, checkout untestable
LEARNING: Tailwind 4 needs @import "tailwindcss" not @tailwind directives

Learnings are gotchas worth remembering across sessions — append them when discovered; promote durable ones to .toh/memory/decisions.md.

🔁 E. The TOH Loop

The universal execution protocol. Runs identically on every runtime; Claude Code merely enforces it harder (Section G).

0. SURVEY — Section A, then choose a rung from Section B.
1. LOAD — read .toh/plan.md + .toh/progress.md. If plan.md is absent, write a mini-plan first (4–8 tasks, Done When, Checkpoint per phase, Status: approved), then continue.
2. PICK — the first unchecked, unblocked task. Append T00x running to progress.md.
3. IMPLEMENT — only that task. Delegate per Sections B/C, or do it yourself on the sequential rung. One task per iteration.
4. QC GATE — run the phase Checkpoint YOURSELF and QUOTE the actual output lines into the conversation. A builder/teammate report is evidence to verify, never proof. Only a quoted passing run counts as done.
5. IF RED — state the root cause from the quoted text, apply a minimal fix, re-run. Budget: max 5 fix iterations per task; 3 consecutive failures on the same task → mark it [!] BLOCKED: <one-line diagnosis> in plan.md, log it in progress.md, and return to step 2 for independent work.
6. IF GREEN — flip - [ ] to - [x], append T00x done — CHECK_OK: <command + result> and any learnings to progress.md, update the pointer in .toh/memory/active.md, and go to step 2 WITHOUT asking the user. Emit exactly ONE status line per task (e.g. CHECK_OK T003 — cart hook, build green), nothing more.
7. REPEAT — until no unchecked, unblocked tasks remain.
8. FINISH — run EVERY Done When criterion and quote its output.
   • All green and nothing blocked → set Status: done, output <promise>COMPLETE</promise>, then close per engineer-harness Section C (the announce/next-actions contract lives there — follow it, do not improvise).
   • Blocked tasks exist → escalate: per-task one-line diagnosis, then close per engineer-harness Section C with unblocking as the recommended action.

Loop rules

• Never ask "continue?" between tasks or phases. Interrupt only for genuine blockers: missing credentials, destructive/irreversible choices, or a contradiction in the plan itself.
• Foundation deadlock: if a blocked task makes everything downstream dependent (nothing independent remains), stop and deliver one clear blocker report — do not thrash on dependent tasks.
• Checkbox-resume: any fresh session (any IDE, any day) reads plan.md and continues at the first unchecked task — unless the plan header carries a terminal status (Status: done/draft/blocked/paused): then report the status and stop, do not resume. This is the crash/context-loss recovery mechanism — keep the file states accurate at all times.
• Completion is a contract: <promise>COMPLETE</promise> may only follow quoted, passing Done When runs. Never emit it on feel.

👥 F. Teams Recipe (Claude Code, env-gated)

Preconditions: CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS set AND plan has >= 3 independent modules. Otherwise fall back one rung (Section B).

1. Spawn teammates from TFW agent definitions by name (their tools + model frontmatter is honored): one builder per independent module (sonnet), one QC teammate (opus). Respect the cap of 4 concurrent.
2. Plan approval, autonomous: require plan approval for builders. YOU (the lead) approve or reject — no human in the loop — against exactly these criteria: the plan names its verify command AND touches only files disjoint from every other teammate. Reject with the reason otherwise.
3. Delegate mode: the lead coordinates only — never edits files itself.
4. Task list: create tasks from plan.md task lines with their dependencies; each teammate owns disjoint files.
5. Dispatch → wait → synthesize: one dispatch per wave, then wait for completion reports (SendMessage mailbox). No polling — do not repeatedly check on teammates.
6. Trust boundary: teammate reports are evidence to verify, never proof. The lead re-runs each phase Checkpoint itself (Section E step 4) before flipping any checkbox.
7. Hooks as backstop: optional hardening you can add to .claude/settings.json (not shipped by the installer): a TaskCompleted hook (exit 2 if the verify command fails → the task cannot be marked complete) and a TeammateIdle hook (exit 2 with remaining work → idle teammate keeps going).

⚙️ G. Claude Code Enforcement Notes

Section E is the floor on every runtime. On Claude Code the installer ships machinery that enforces it:

Antigravity runs the same loop and also gets a deterministic Stop hook (.agents/hooks.json) that blocks ending a session while .toh/plan.md has unchecked tasks (both hooks exempt a terminal-status plan). Every other runtime (Cursor / Codex / ZCode / Gemini) runs the SAME loop as prose in one session — no hooks, no /goal. The recovery mechanism there is checkbox-resume: a fresh session picks up at the first unchecked task — unless the plan header carries a terminal status (done/draft/blocked/paused), which is reported instead of resumed. If context runs low mid-plan, flush state (plan checkboxes + progress.md + active.md pointer), then tell the user to re-run the command — it resumes exactly where it stopped.

🔗 Integration

Commands load this skill for any multi-task job and pair it with the closing contract:

yamlCopy code
skills:
  - orchestration-protocol   # survey + ladder + plan artifact + TOH Loop
  - engineer-harness         # Section C: announce block + next actions (canonical)

Division of labor: this skill owns HOW work gets executed and verified; engineer-harness Section C owns how every stage ENDS (status, evidence, exactly the right next actions). Reference both; duplicate neither.

Orchestration Protocol v1.0.0 — survey, ladder, plan artifact, and the TOH Loop in one place. Commands reference this skill; they never duplicate it.