From 9e332e296c33650604707bcd6648978ca4ee65ad Mon Sep 17 00:00:00 2001 From: Drew Stone Date: Mon, 3 Aug 2026 15:01:58 -0600 Subject: [PATCH] =?UTF-8?q?docs(skills):=20orchestration=20layering=20doct?= =?UTF-8?q?rine=20=E2=80=94=20harness-native=20orchestration=20is=20layer?= =?UTF-8?q?=20one?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Foundation harnesses ship TRAINED orchestration and prose is its native API. The graph layer composes ACROSS harnesses (conserved budget, ledger evidence, resume, heterogeneous models); it must not re-choreograph WITHIN one. Outer coarse, inner maximal. Consequence recorded as the sixth gen4 requirement: the unmeasured-harness case expectation (nodes=3) and v3's held N-roles-N-nodes lesson are both suspect — the layer-aware answer to 'three probes on claude-code' may be ONE node instructed to run three native subagents. gen4 needs a case that encodes this, with the qualifying-harness list owned by the supervisor-lab harness KB. --- skills/agent-graphs/IMPROVE.md | 8 ++++++++ skills/agent-graphs/generations/gen3.json | 3 ++- 2 files changed, 10 insertions(+), 1 deletion(-) diff --git a/skills/agent-graphs/IMPROVE.md b/skills/agent-graphs/IMPROVE.md index 92269073..29a08090 100644 --- a/skills/agent-graphs/IMPROVE.md +++ b/skills/agent-graphs/IMPROVE.md @@ -35,6 +35,14 @@ Holdout discipline: at least 3 of the 8 held out, never trained on; `runImprovem - No new optimizer, campaign runner, judge plumbing, or ledger — all named above. - No live-backend scoring in the loop. Live runs are pursuit work, not skill-improvement work; the loop stays offline and free. +## Orchestration layering (doctrine, gates gen4) + +Two layers, different jobs. +Foundation harnesses ship trained orchestration — Claude Code subagents, codex goal-mode, pi extensions — and prose is that layer's native API: instructing a claude-code node to "fan out subagents over these files" invokes an in-distribution capability, not vibes. +The graph/script layer exists for what no single harness provides: cross-harness composition, one conserved budget across the whole tree, durable ledger evidence, resume, and heterogeneous model placement. +Rule: outer layer coarse, inner layer maximal — one harness-sized node told to use its native fan-out beats N externally-choreographed thin nodes that each pay the harness floor while suppressing the orchestration the model was trained for. +Which harnesses qualify for native fan-out is a supervisor-lab harness-KB row, not a guess. + ## Version history The live tree carries only the current `SKILL.md`; every prior surface text is recoverable from git history via the pinned sha256s below, and each generation's full measurement record lives in `generations/`. diff --git a/skills/agent-graphs/generations/gen3.json b/skills/agent-graphs/generations/gen3.json index 47329ddb..5d9b6d51 100644 --- a/skills/agent-graphs/generations/gen3.json +++ b/skills/agent-graphs/generations/gen3.json @@ -695,7 +695,8 @@ "author JSON contract aligned with the skill text (remove perWorker.maxIterations or lower it correctly)", "holdout refresh: cases authored blind by an agent given only the case schema, never failure history; contaminated comparison retired", "persist revision-prompt inputs alongside the sha", - "fix in-loop gate wiring so the upstream record is authoritative" + "fix in-loop gate wiring so the upstream record is authoritative", + "layering doctrine: foundation harnesses ship TRAINED orchestration (Claude Code subagents, codex goal-mode, pi extensions) and prose is its native API \u2014 the graph layer composes ACROSS harnesses (conserved budget, ledger evidence, resume, heterogeneous models), it does not re-choreograph WITHIN one. Outer layer coarse, inner layer maximal: prefer one harness-sized node instructed to use its native fan-out over N externally-choreographed thin nodes. The unmeasured-harness case expectation (nodes=3) and v3's held N-roles-N-nodes lesson are both suspect under this rule; gen4 needs a case whose correct answer is one node + native-fanout instruction, and the harness KB row decides which harnesses qualify" ] } }