orchestration-protocol
The single source of truth for how TFW commands survey their runtime, choose an execution mode (teams / subagents / sequential), route models, and run the TOH LOOP — the autonomous plan-execute-verify protocol driven by .toh/plan.md + .toh/progress.md. Loaded by /toh, /toh-vibe, /toh-plan. Triggers: build a whole plan, resume a plan, "continue building", autonomous execution, multi-agent orchestration, parallel agents, work until done, MVP build, big multi-task jobs.
wasintoh · 已有 AI 审核记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add wasintoh/toh-framework --skill orchestration-protocol技能说明
name: orchestration-protocol description: > The single source of truth for how TFW commands survey their runtime, choose an execution mode (teams / subagents / sequential), route models, and run the TOH LOOP — the autonomous plan-execute-verify protocol driven by .toh/plan.md + .toh/progress.md. Loaded by /toh, /toh-vibe, /toh-plan. Triggers: build a whole plan, resume a plan, "continue building", autonomous execution, multi-agent orchestration, parallel agents, work until done, MVP build, big multi-task jobs. triggers:
- /toh (multi-task jobs)
- /toh-vibe (autonomous builds)
- /toh-plan (plan artifact + handoff)
- Any request to execute or resume .toh/plan.md
🔁 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:
| Context file that loaded you | Runtime |
|---|---|
CLAUDE.md | Claude Code |
.cursor/rules/*.mdc | Cursor |
AGENTS.md | Codex or ZCode — the **Runtime:** line inside the file names which |
.agents/rules/toh-framework.md | Antigravity (+ Antigravity CLI) |
GEMINI.md | Gemini CLI (legacy) |
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:
| Probe | Gate |
|---|---|
| Agent Teams | env CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS is set |
/goal | Claude Code >= 2.1.139 |
| Workflows | Claude Code >= 2.1.154 (can be plan-disabled) |
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.
- 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.
- NATIVE SUBAGENTS — the Agent tool (Task) exists. Delegate tasks to TFW agents; parallel only under the rules below. If unavailable, fall back one rung.
- 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
| Situation | Mode |
|---|---|
| <= 3 tasks total | SEQUENTIAL |
| Same-file or dependent edits | SEQUENTIAL |
| Debugging / fixing | SEQUENTIAL |
| Runtime without subagents (Codex / ZCode / Gemini) | SEQUENTIAL |
| >= 2 independent tasks on disjoint files, each substantial (~5+ min) | PARALLEL subagents |
| MVP-scale: >= 3 independent modules + a QC role, teams flag set | TEAMS |
Hard limits (load-bearing — never soften)
| Constant | Value |
|---|---|
| Concurrent subagents/teammates | max 4 |
| Delegation depth | <= 2 (you → worker; workers never spawn) |
| QC fix iterations per task | max 5 |
| Consecutive failures on same task → BLOCKED | 3 |
/goal bound | "or stop after 40 turns" |
.toh/plan.md size | <= 150 lines |
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.mdfirst — 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.
| Tier | Use for |
|---|---|
| haiku | Scaffolding, boilerplate, test writing |
| sonnet | Builders — ui-builder, dev-builder, implementation work |
| opus | Planning, QC/review, design review |
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.
# 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: