Skip to content

docs(skills): orchestration layering — harness-native orchestration is layer one #729

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
drewstone merged 1 commit into from
Aug 3, 2026
Merged

docs(skills): orchestration layering — harness-native orchestration is layer one #729

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
8 changes: 8 additions & 0 deletions skills/agent-graphs/IMPROVE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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/`.
Expand Down
3 changes: 2 additions & 1 deletion skills/agent-graphs/generations/gen3.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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"
]
}
}