git:20260910.20bff72 to git:20260910.7a6362e

---

name: orchestration

description: "Multi-agent orchestration: lane contracts, worker-model doctrine, fault tolerance. Triggers: orchestrate, coordinate, agents, parallel, spawn, contract, tier 2, tier 3."

allowed-tools: Task, Bash, Read

kernel:

kind: methodology

version: 1

side_effects: none

confirmation: none

---

<skill id="orchestration">

<purpose>

Orchestration is coordination, not implementation. You define contracts, agents

execute, AgentDB is the bus. Never assume completion without reading the file.

Reference on demand: skills/orchestration/reference/orchestration-research.md.

</purpose>

<lane_contract>

Every spawned lane gets ALL of these fields; a missing field is where the lane fails:

1. **Deliverable**: the observable artifact, named exactly (file path, PR, report).

2. **Read-first list**: the files/docs the lane must read before acting.

3. **Files table**: exhaustive list of files it may touch (`constraints.files`).

No two concurrent lanes may overlap. Contract JSON:

`{"goal":"X","constraints":{"files":["a.sh","b.md"]},"tier":2}`

4. **Known traps, restated**: gotchas relevant to this lane, inlined, not linked.

5. **Verification loop with exact commands**: the literal commands the lane runs to

prove its own work (test invocation, grep, curl), plus expected output.

6. **Forbidden list**: what the lane must NOT do (push, touch _meta/, add deps, ...).

7. **Raw-data return format**: counts, file lists, command output. Never narrative

alone; a lane that returns only prose has returned nothing checkable.

</lane_contract>

<output_integrity>

Structured long-report lanes degrade silently to placeholders under load. Validate

every lane return mechanically before using it: minimum-length check on required

sections, placeholder detection ("TBD", "...", repeated boilerplate), counts match

the claimed work. Reject-and-retry a degraded return; never synthesize over it.

Pass large input pools to lanes by FILE PATH, never as an inline slice (silent

truncation reads as full coverage). Each lane keeps a per-lane journal/checkpoint

so a degraded final message is not the only record of what it did.

</output_integrity>

<single_coordinator>

One coordinator per repo at a time. Before coordinating, check for a live second

session on the same working directory (stale sessions can survive as background

daemons and produce split-brain: two coordinators mutating one repo in parallel).

When killing a stuck session, kill its whole process pool, not just the visible pid.

</single_coordinator>

<worker_model_doctrine>

Select model and effort from the lane's task shape and measured evidence, never from

role prestige. Mechanical total-spec execution with deterministic checks can use the

lowest setting proven adequate. Ambiguous judgment or a measured miss justifies more

effort; protected work requires a fresh independent verifier. The lane contract records

the requested model and effort, whether inheritance is intentional, and the escalation

condition. A prompt that says "use your judgment" is evidence of ambiguity, not a license

to choose a prestige model by role. Receipts keep `requested_model` and `requested_effort`

separate from `observed_model` and `observed_effort`. Unsupported or unexposed values are

`unavailable`, never inferred. Protected receipts require distinct `builder_identity` and

`verifier_identity`; the builder never grades its own protected work. The coordinator

reproduces acceptance evidence.

</worker_model_doctrine>

<fault_tolerance>

1. RETRY transient failures with backoff, max 3. 2. CLASSIFY the failure before choosing

recovery. 3. Never silently substitute model, effort, or provider. Use an alternative only

when the contract names a pre-authorized fallback; record the original request, the failure,

and the observed fallback identity separately. Otherwise stop and re-contract. 4. CHECKPOINT

state to AgentDB at every boundary so a respawn resumes instead of restarting.

</fault_tolerance>

<worktree_safety>

Parallel lanes (tier 2+) run in isolated git worktrees (`isolation: "worktree"`),

never the main worktree; failed work is discarded by deleting the worktree. Pre-spawn:

working tree clean or stashed; each lane's `constraints.files` disjoint from all

active lanes. Post-agent validation: read the lane's checkpoint, then

`git diff --name-only {base}..{lane_branch}`; every changed file MUST appear in

`constraints.files`, and an out-of-scope file means reject, do not merge, re-contract.

Tier 1 skips worktrees (unnecessary overhead).

</worktree_safety>

<knowledge_injection>

Inject context BEFORE spawn, never let lanes discover it at runtime: build the slice

with `agentdb inject-context <agent_type>` and inline it in the prompt (surgeon gets

gotchas + patterns + contract; adversary/reviewer get past failures + recent errors;

researcher gets domain learnings). The orchestrator owns injection. Every agent

boundary is lossy compression: structured briefing in, structured checkpoint out;

never rely on conversation history across agents.

</knowledge_injection>

<anti_patterns>

Holding context in memory instead of AgentDB · assuming a lane finished without

reading the deliverable file (receipts describe intent; files describe reality) ·

parallel lanes touching shared files (N-way merge conflicts) · serial execution when

parallel is genuinely safe · retrying without new information from the failure ·

autonomous loops without a budget cap (`max_budget_usd` on the contract) ·

accepting a lane return without the output-integrity check (placeholder degradation

</anti_patterns>

</skill>