agent-bios 0.14.0 → 0.16.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/DEPENDENCIES.md +35 -12
- package/README.md +346 -31
- package/claude/CLAUDE.md +2 -2
- package/claude/agents/frontier.md +1 -1
- package/claude/agents/sweep.md +3 -3
- package/claude/agents/workhorse.md +2 -2
- package/claude/guides/claude-prompting.md +119 -34
- package/claude/guides/cli-multi-model-workflow.md +33 -15
- package/claude/guides/gpt-prompting.md +148 -28
- package/claude/guides/review-request.md +27 -0
- package/claude/guides/session-distill-workflow.md +54 -2
- package/claude/guides/slide-writing/RUNBOOK.md +137 -0
- package/claude/guides/slide-writing/scripts/pair.py +979 -0
- package/claude/guides/slide-writing/scripts/render.mjs +82 -0
- package/claude/guides/slide-writing.md +195 -0
- package/claude/guides/svg-visualization-guide.md +9 -0
- package/claude/guides/verification-discipline.md +5 -1
- package/claude/hooks/tooling-gotchas-hook.py +7 -5
- package/codex/AGENTS.md +2 -2
- package/codex/agents/frontier.toml +2 -1
- package/codex/agents/reviewer.toml +1 -1
- package/codex/agents/sweep.toml +3 -3
- package/codex/agents/workhorse.toml +1 -1
- package/codex/config-additions.toml +1 -1
- package/codex/guides/claude-prompting.md +119 -34
- package/codex/guides/cli-multi-model-workflow.md +33 -15
- package/codex/guides/gpt-prompting.md +148 -28
- package/codex/guides/review-request.md +27 -0
- package/codex/guides/session-distill-workflow.md +54 -2
- package/codex/guides/slide-writing/RUNBOOK.md +137 -0
- package/codex/guides/slide-writing/scripts/pair.py +979 -0
- package/codex/guides/slide-writing/scripts/render.mjs +82 -0
- package/codex/guides/slide-writing.md +195 -0
- package/codex/guides/svg-visualization-guide.md +9 -0
- package/codex/guides/verification-discipline.md +5 -1
- package/compose/assemble.py +290 -14
- package/compose/bootstrap/SKILL.md +119 -0
- package/compose/check-domains.py +102 -9
- package/compose/corpus-state.py +1174 -0
- package/compose/corpus.py +387 -0
- package/compose/corpus_catalog.py +882 -0
- package/compose/corpus_install.py +1617 -0
- package/compose/corpus_session.py +726 -0
- package/compose/corpus_store.py +1414 -0
- package/compose/corpus_transaction.py +236 -0
- package/compose/corpus_ui.py +644 -0
- package/compose/domains.json +101 -100
- package/compose/write-update-cache.py +53 -0
- package/install.sh +174 -24
- package/launch/agent-launch.py +1327 -184
- package/launch/agent-launch.toml +12 -16
- package/launch/i18n/en.toml +113 -7
- package/launch/i18n/ja.toml +113 -7
- package/launch/i18n/ko.toml +113 -7
- package/learn/collect-learning.py +46 -19
- package/learn/migrate-learnings.py +10 -1
- package/package.json +13 -3
- package/provenance.json +1 -1
- package/session-cost.py +22 -2
- package/wrappers/codex-helm.sh +3 -3
package/claude/CLAUDE.md
CHANGED
|
@@ -84,8 +84,8 @@
|
|
|
84
84
|
|
|
85
85
|
## Multi-Model Workflow
|
|
86
86
|
|
|
87
|
-
- Standing spawn policy: check the spawn gates at every work-unit boundary — judgment latitude applies inside a gate, never to whether the gates are checked. Independence:
|
|
88
|
-
- Down-spawns carry a machine-checkable done-when on decision-complete work with staged output (no external irreversible actions) and
|
|
87
|
+
- Standing spawn policy: check the spawn gates at every work-unit boundary — judgment latitude applies inside a gate, never to whether the gates are checked. Independence: before presenting a load-bearing conclusion or taking an irreversible step, propose the cross-check unprompted; the user should never have to ask for it. Independence comes from the seat you dispatch to, so name it. Parallelism: two or more independent items spawn in parallel — SWEEP when each item applies one explicit rule and returns ambiguity as an exception, else WORKHORSE. Residual context: work whose log dwarfs the conclusion the main needs spawns with a bounded report contract. Escalation: an irreversible or authority-changing action ahead, two failed attempts, or two persisting design alternatives spawns a bounded FRONTIER judgment with a blind packet (evidence, constraints, rubric, neutral alternatives — never your draft conclusion) and a pre-noted change condition. Specifiability/de-minimis: work needing your live context, or whose verification would repeat the reasoning, or whose packet outweighs the work, stays inline.
|
|
88
|
+
- Down-spawns carry a machine-checkable done-when on decision-complete work with staged output (no external irreversible actions) and a tier pinned before dispatch. Record one line per gate decision — `SpawnGate: <gate> <tier> spawn|inline — <why>` — and for FRONTIER record the disposition afterward (what changed, or why nothing did). A launch contract's `Delegation=off` lifts the spawn obligation, not the records; explicit user no-fan-out always wins.
|
|
89
89
|
- For work spanning multiple models or CLI agents, context resets and handoffs, unattended LLM batches (including orchestrated subagent fleets), or parallel worktree branches, read and use `${CLAUDE_CONFIG_DIR:-$HOME/.claude}/guides/cli-multi-model-workflow.md` as a scoped extension of this section.
|
|
90
90
|
- For composing a prompt, packet, or tool description aimed at a specific model family — including cross-family review dispatch, porting a prompt written for an older model, or choosing a reasoning-effort level for a model family — read and use `${CLAUDE_CONFIG_DIR:-$HOME/.claude}/guides/gpt-prompting.md` for gpt-family targets and `${CLAUDE_CONFIG_DIR:-$HOME/.claude}/guides/claude-prompting.md` for claude-family targets as scoped extensions of this section.
|
|
91
91
|
- Allocate models by difficulty × blast radius, not phase name; when implementation ran on a cheaper tier, compensate by raising reviewer effort or adding a reviewer kind — never economize on implementation and verification at once.
|
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: frontier
|
|
3
3
|
description: FRONTIER tier — bounded hardest decisions, first-of-kind design, triage gates, and final verdicts. Spawn when the Escalation gate fires — an irreversible or authority-changing action ahead, two failed attempts, or two persisting design alternatives — with a blind packet (evidence, constraints, rubric, neutral alternatives; no draft conclusion) and a pre-noted change condition.
|
|
4
|
-
model: claude-fable-5
|
|
4
|
+
model: claude-fable-5-1
|
|
5
5
|
effort: max
|
|
6
6
|
disallowedTools: [Edit, Write, NotebookEdit]
|
|
7
7
|
---
|
package/claude/agents/sweep.md
CHANGED
|
@@ -1,9 +1,9 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: sweep
|
|
3
|
-
description: SWEEP tier —
|
|
3
|
+
description: SWEEP tier — read-only checks applying one explicit rule to each item. Ambiguity returns as an exception, never resolved.
|
|
4
4
|
model: claude-haiku-4-5
|
|
5
|
-
|
|
5
|
+
tools: [Read, Glob, Grep]
|
|
6
6
|
disallowedTools: [Edit, Write, NotebookEdit]
|
|
7
7
|
---
|
|
8
8
|
|
|
9
|
-
|
|
9
|
+
Apply one explicit rule to each item in the supplied inputs and stop at the declared boundary. Read-only: do not edit, broaden scope, choose architecture, or seek authority. Parallelize independent reads. Surface ambiguity as an exception instead of inferring intent. Report: status, the non-empty items_checked, findings with proving evidence or command, risks_or_escalations.
|
|
@@ -1,8 +1,8 @@
|
|
|
1
1
|
---
|
|
2
2
|
name: workhorse
|
|
3
3
|
description: WORKHORSE tier — bounded implementation, fixes, tests, and per-item judgment. Spawn decision-complete work with frozen scope/interfaces and a machine-checkable done-when; two or more independent items spawn in parallel.
|
|
4
|
-
model: claude-
|
|
5
|
-
effort:
|
|
4
|
+
model: claude-sonnet-5
|
|
5
|
+
effort: xhigh
|
|
6
6
|
---
|
|
7
7
|
|
|
8
8
|
Complete one bounded implementation, fix, or per-item judgment from a packet naming objective, frozen scope and inputs, allowed actions, output, done-when, and verification. Preserve out-of-scope behavior; batch independent reads; escalate missing decisions or authority instead of resolving them. Stage output for the main's acceptance — no external irreversible actions (push, install, credential, or remote mutation). Run the narrowest reliable changed-path check. Report: status, files_or_items_touched, evidence, verification or gap, risks_or_escalations.
|
|
@@ -9,13 +9,26 @@ use_when:
|
|
|
9
9
|
- porting a prompt written for an older claude model
|
|
10
10
|
- deciding a reasoning-effort level for claude work
|
|
11
11
|
core_rules:
|
|
12
|
+
- choose guidance by the actual target model — Fable 5.1 and Opus 5 need different progress, delegation, and verification tuning
|
|
12
13
|
- state the goal, the constraints, and the reason behind the request; let the model choose the route
|
|
13
|
-
-
|
|
14
|
+
- compare inherited process scaffolding on the target model before keeping or removing it
|
|
14
15
|
- put the full task specification in the first turn for long-horizon work rather than revealing it across turns
|
|
15
16
|
- make tool descriptions prescriptive about when to call, not only what the tool does
|
|
16
17
|
- require progress claims to be audited against a tool result from the same session
|
|
17
18
|
- name the boundary explicitly — what to do without asking, and what to stop and ask about
|
|
19
|
+
derived_at: 2026-09-07
|
|
20
|
+
source_pins:
|
|
21
|
+
- doc: prompting-claude-opus-5
|
|
22
|
+
sha256: 65be3e0b437cbe23cc41bb4f9b7a5031c5a71cd49ab91ec4d19c62738762b086
|
|
23
|
+
pinned_at: 2026-09-07
|
|
24
|
+
- doc: claude-prompting-best-practices
|
|
25
|
+
sha256: f98aa130a7974b2edf98f8c3babe806ab140d5cdd3933a506f5211335b431c5f
|
|
26
|
+
pinned_at: 2026-09-07
|
|
27
|
+
- doc: prompting-claude-fable-5-1
|
|
28
|
+
sha256: 4aa645dd26fe9efebdaaff7462563bfac1f27782ce2d71dd5afffeaf02a80c62
|
|
29
|
+
pinned_at: 2026-09-07
|
|
18
30
|
targets:
|
|
31
|
+
- claude-fable-5-1
|
|
19
32
|
- claude-fable-5
|
|
20
33
|
- claude-opus-5
|
|
21
34
|
- claude-sonnet-5
|
|
@@ -24,6 +37,7 @@ verification_focus:
|
|
|
24
37
|
- prompt changes are A/B'd against the prior scaffolding rather than assumed
|
|
25
38
|
- effort changes are swept across levels on a real eval set, not chosen by reputation
|
|
26
39
|
- per-model constraints are confirmed against the live surface before use
|
|
40
|
+
- model-specific advice stays within its named section, including after assembly
|
|
27
41
|
---
|
|
28
42
|
|
|
29
43
|
# Claude Prompting Guide
|
|
@@ -33,26 +47,56 @@ composing a prompt for a claude-tier model — a review packet dispatched
|
|
|
33
47
|
cross-family, a subagent brief, or the main's own instructions when the main is
|
|
34
48
|
Claude.
|
|
35
49
|
|
|
36
|
-
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
|
|
40
|
-
|
|
50
|
+
Use the shared recipe and checklist together with the section for the model being
|
|
51
|
+
prompted, even when a subagent uses a different model from the main. Model-specific
|
|
52
|
+
tuning preserves the corpus's permission boundaries and required verification.
|
|
53
|
+
|
|
54
|
+
| Target | Apply |
|
|
55
|
+
| --- | --- |
|
|
56
|
+
| `claude-fable-5-1` | Shared recipe and Claude Fable 5.1 |
|
|
57
|
+
| `claude-opus-5` | Shared recipe and Claude Opus 5 |
|
|
58
|
+
| `claude-fable-5`, `claude-sonnet-5`, `claude-haiku-4-5` | Shared recipe; consult the target's own guidance before borrowing another model's tuning |
|
|
41
59
|
|
|
42
60
|
## Default prompt recipe
|
|
43
61
|
|
|
44
|
-
- `Goal` and the **reason behind it** —
|
|
45
|
-
context
|
|
46
|
-
"I'm doing X for Y, who needs Z; with that in mind: …" outperforms the bare
|
|
47
|
-
request, most of all for long-running agents holding several workstreams.
|
|
62
|
+
- `Goal` and the **reason behind it** — provide the audience, purpose, and relevant
|
|
63
|
+
context so the model does not have to infer the intent.
|
|
48
64
|
- `Success criteria` — what done means and how it is checked.
|
|
49
|
-
- `Constraints and boundaries` —
|
|
50
|
-
unrequested-but-adjacent actions; naming the boundary is the fix.
|
|
65
|
+
- `Constraints and boundaries` — state the permitted scope and approval conditions.
|
|
51
66
|
- `Tools` — each description states **when to call it**, not only what it does.
|
|
52
|
-
|
|
67
|
+
Name prerequisite retrieval and validation when correctness depends on them.
|
|
53
68
|
- `Output` — the artifact shape and the register.
|
|
54
69
|
|
|
55
|
-
##
|
|
70
|
+
## Claude Fable 5.1
|
|
71
|
+
|
|
72
|
+
- Begin effort experiments at `high`; compare supported levels afresh. Identical
|
|
73
|
+
effort names need not have identical costs across models.
|
|
74
|
+
- Request brief start, progress, and final updates; first verify the client renders
|
|
75
|
+
updates and remove conflicting silence instructions.
|
|
76
|
+
- Batch independent tool calls. Let the lead do independent work while subagents run.
|
|
77
|
+
- Complete authorized requests, including promised next steps. State genuine approval
|
|
78
|
+
boundaries and whether a person is available; avoid unnecessary pauses.
|
|
79
|
+
- Ask for literal prose and useful formatting. Demonstrate how retrieved quotations
|
|
80
|
+
should be marked and attributed.
|
|
81
|
+
- Keep edits targeted and tests proportional to the requested behavior; report
|
|
82
|
+
unrelated issues separately.
|
|
83
|
+
- At `low`, explicitly trigger retrieval for current facts instead of trusting name
|
|
84
|
+
recognition. Compare higher effort when retrieval still fails.
|
|
85
|
+
- Preserve decisions, constraints, open work, and exact details in compaction summaries.
|
|
86
|
+
- Append API history unchanged; use supported compaction instead of replaying thinking
|
|
87
|
+
against an edited prefix.
|
|
88
|
+
- At `xhigh`/`max`, budget tokens for thinking and the deliverable; compare `high` for
|
|
89
|
+
long outputs.
|
|
90
|
+
- Give dense-image work crop and zoom tools.
|
|
91
|
+
|
|
92
|
+
These are prompt and harness tuning choices, not changes to the configured seat's
|
|
93
|
+
effort or permissions. The Opus-specific advice below does not apply to this model.
|
|
94
|
+
|
|
95
|
+
## Claude Opus 5
|
|
96
|
+
|
|
97
|
+
The following behavior claims and tuning recommendations apply to `claude-opus-5`.
|
|
98
|
+
|
|
99
|
+
### When to add blocks
|
|
56
100
|
|
|
57
101
|
- Long-horizon or autonomous work: give the full spec up front in one
|
|
58
102
|
well-specified turn and run at a high effort. Do **not** add a self-check
|
|
@@ -68,7 +112,12 @@ pick the path.
|
|
|
68
112
|
- Delegation: say when *not* to delegate, and cap the spawn count. The helm
|
|
69
113
|
binding reaches for subagents readily — the reverse of the binding it replaced
|
|
70
114
|
— and every spawn rebuilds context, reports back, and is then re-read, so
|
|
71
|
-
unbounded delegation multiplies cost and latency.
|
|
115
|
+
unbounded delegation multiplies cost and latency. Where the harness offers
|
|
116
|
+
deterministic caps, prefer them to prose: under Claude Code and the Agent SDK
|
|
117
|
+
these are `CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH`,
|
|
118
|
+
`CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS`, and the SDK's `max_budget_usd` — a
|
|
119
|
+
limit the model cannot talk itself past. Confirm the harness version supports
|
|
120
|
+
them before relying on it. File-based memory and custom
|
|
72
121
|
tools are the opposite case: they still need an explicit when-to-use trigger.
|
|
73
122
|
- Autonomous runs with no human watching: say so. Otherwise it asks permission
|
|
74
123
|
it does not need and blocks. Grant autonomy on minor choices (naming,
|
|
@@ -77,21 +126,18 @@ pick the path.
|
|
|
77
126
|
- Progress reporting: require each claim to be traceable to a tool result from
|
|
78
127
|
the session, and unverified work to be labeled as such.
|
|
79
128
|
|
|
80
|
-
|
|
129
|
+
### How to choose prompt shape
|
|
81
130
|
|
|
82
131
|
- One bounded question with a self-contained packet → a single run. Default for
|
|
83
132
|
review.
|
|
84
133
|
- Independent workstreams → delegate, and prefer asynchronous subagents over
|
|
85
134
|
spawn-and-block: long-lived agents keep their context instead of rebuilding it
|
|
86
135
|
per subtask, and the orchestrator is not pinned to the slowest one.
|
|
87
|
-
-
|
|
88
|
-
and
|
|
89
|
-
|
|
90
|
-
|
|
91
|
-
|
|
92
|
-
often *reduces* turn count and total cost on agentic work, and some tasks land
|
|
93
|
-
equally well a level down. Effort does not control response length — see
|
|
94
|
-
Working rules.
|
|
136
|
+
- Start effort experiments at `high`; compare lower settings on representative
|
|
137
|
+
tasks and step up to `xhigh` for demanding coding or agentic work when quality
|
|
138
|
+
improves. Re-test inherited defaults. The configured seat's effort remains an
|
|
139
|
+
explicit workload choice. Effort does not control response length — see Working
|
|
140
|
+
rules.
|
|
95
141
|
- Per-model constraints differ across the `targets` bindings — thinking
|
|
96
142
|
configuration, sampling parameters, and effort support are not uniform, and
|
|
97
143
|
the sweep binding is the most restricted. On the helm binding, for instance,
|
|
@@ -100,14 +146,16 @@ pick the path.
|
|
|
100
146
|
live surface before relying on it in a dispatch; do not assume the frontier
|
|
101
147
|
binding's rules apply to the sweep one.
|
|
102
148
|
|
|
103
|
-
|
|
149
|
+
### Working rules
|
|
104
150
|
|
|
105
151
|
- Expect long turns. A single request on a hard task at high effort can run for
|
|
106
152
|
minutes; plan timeouts, streaming, and progress UX around that rather than
|
|
107
153
|
treating a quiet call as a hang.
|
|
108
154
|
- Do not add "summarize every N tool calls" scaffolding — this tier narrates on
|
|
109
155
|
its own. If it narrates too much for a coding agent, set a silence default
|
|
110
|
-
instead: text only on a finding, a direction change, or a blocker.
|
|
156
|
+
instead: text only on a finding, a direction change, or a blocker. Describe the
|
|
157
|
+
cadence you want by example; a positive description of the style outperforms a
|
|
158
|
+
list of what not to do.
|
|
111
159
|
- Length is a prompting lever, not an effort lever. This tier writes longer
|
|
112
160
|
answers and longer files than its predecessors, and lowering `effort` does not
|
|
113
161
|
reliably shorten visible output — only an explicit instruction does. Calibrate
|
|
@@ -121,6 +169,36 @@ pick the path.
|
|
|
121
169
|
work they did not watch. Lead with the outcome; drop the working shorthand.
|
|
122
170
|
- Do not show a remaining-context countdown. This tier can start conserving and
|
|
123
171
|
suggest a fresh session instead of finishing.
|
|
172
|
+
- Re-validate prompt-side vision workarounds carried from older bindings; this
|
|
173
|
+
tier is strong on charts, documents, diagrams, and UI replication, and the
|
|
174
|
+
workaround may now be the thing costing quality. Tools that let it crop and
|
|
175
|
+
visually verify beat thinking alone here.
|
|
176
|
+
- Instruction following stays consistent across the full context window, so a
|
|
177
|
+
rule does not need restating near the end to survive a long session.
|
|
178
|
+
|
|
179
|
+
### Running with thinking disabled
|
|
180
|
+
|
|
181
|
+
Disabling thinking is accepted only at `high` effort or below, and it is usually
|
|
182
|
+
the wrong lever: thinking on at `low` effort generally beats thinking off at
|
|
183
|
+
comparable cost. Reach for lower effort before reaching for the switch.
|
|
184
|
+
|
|
185
|
+
Two artifacts appear when it is off, and both are prompt-fixable:
|
|
186
|
+
|
|
187
|
+
- A tool call written as **user-facing text** instead of a structured call. The
|
|
188
|
+
turn completes, the call never runs, and in an agentic loop the leaked text
|
|
189
|
+
stays in history and contaminates later turns. Most common on tool-heavy work.
|
|
190
|
+
- Internal XML tags leaking into the visible response.
|
|
191
|
+
|
|
192
|
+
One instruction mitigates both — permission to speak before a call, an out when
|
|
193
|
+
no tool fits, and a general ban on internal tags:
|
|
194
|
+
|
|
195
|
+
> When you use a tool, you may say a brief sentence first. If no tool can express
|
|
196
|
+
> what the user asked for, say so instead of guessing. Do not include internal or
|
|
197
|
+
> system XML tags in your response.
|
|
198
|
+
|
|
199
|
+
Two traps. Naming the tags specifically is **less** effective than the general
|
|
200
|
+
form. And if a prompt anywhere tells this tier not to think or not to reason,
|
|
201
|
+
delete it: that instruction increases tag leakage rather than suppressing it.
|
|
124
202
|
|
|
125
203
|
## Prompt assembly checklist
|
|
126
204
|
|
|
@@ -128,14 +206,21 @@ pick the path.
|
|
|
128
206
|
2. Name the boundaries — what to do freely, what to stop and ask about.
|
|
129
207
|
3. Give each tool a when-to-call description.
|
|
130
208
|
4. Say how progress claims must be grounded, and how the deliverable should read.
|
|
131
|
-
5.
|
|
132
|
-
|
|
133
|
-
|
|
209
|
+
5. Apply the target model's section and check for contradictions. Compare changes
|
|
210
|
+
on the same tasks; remove inherited scaffolding only when the target benefits,
|
|
211
|
+
keeping required repository checks and permission boundaries intact.
|
|
134
212
|
|
|
135
213
|
## Sources
|
|
136
214
|
|
|
137
|
-
|
|
138
|
-
|
|
139
|
-
|
|
140
|
-
|
|
141
|
-
|
|
215
|
+
The shared recipe is derived from `claude-prompting-best-practices`; the Fable 5.1
|
|
216
|
+
section from `prompting-claude-fable-5-1`; and the Opus 5 section from
|
|
217
|
+
`prompting-claude-opus-5`. `source_pins` records the exact bytes used for this
|
|
218
|
+
derivation. Fable 5.1 has its own prompting document; model names in `targets` do
|
|
219
|
+
not extend the Opus-specific behavior claims to other models.
|
|
220
|
+
|
|
221
|
+
When a `targets` model changes, re-derive its advice from its own current document
|
|
222
|
+
and check the shared recipe for conflicts.
|
|
223
|
+
`launch/check-prompting-targets.sh` fails when the launch config binds a model
|
|
224
|
+
this guide does not list; that check is about **naming**, and a model added to
|
|
225
|
+
`targets:` satisfies it forever. Whether the guidance was actually re-derived is
|
|
226
|
+
not decidable and is gated nowhere.
|
|
@@ -23,7 +23,7 @@ Scoped extension of the global Multi-Model Workflow rules. Rules use portable ro
|
|
|
23
23
|
|
|
24
24
|
- FRONTIER: hardest bounded design, authority-changing decisions, triage, final verdicts.
|
|
25
25
|
- HELM: standing main/judgment seat; orchestration and bounded escalation.
|
|
26
|
-
- WORKHORSE: implementation volume and per-item judgments. SWEEP:
|
|
26
|
+
- WORKHORSE: implementation volume and per-item judgments. SWEEP: read-only work applying one explicit rule to each item, returning ambiguity as an exception.
|
|
27
27
|
- VERIFIER-A/B: different review kinds, preferably cross-family. INDEPENDENT-PR-REVIEWER: final review from a different family than the author.
|
|
28
28
|
|
|
29
29
|
- Bind concrete models in Environment Binding and allocate by **difficulty × blast radius**. The main defaults to HELM; first-of-kind/authority-changing mains use FRONTIER at a session boundary; trivial work stays direct.
|
|
@@ -35,7 +35,8 @@ Scoped extension of the global Multi-Model Workflow rules. Rules use portable ro
|
|
|
35
35
|
|
|
36
36
|
Main-context pollution is usually costlier than spawn overhead. Apply these gates in order; the first that fires decides:
|
|
37
37
|
|
|
38
|
-
1. **Independence:** verification
|
|
38
|
+
1. **Independence:** verification and review go outside your own reasoning, not merely outside your conversation. A child carries the standing corpus on both hosts, except Claude's built-in `Explore` and `Plan`, which omit the CLAUDE.md hierarchy. Otherwise a Claude child starts fresh, while Codex `spawn_agent` forks by default — `fork_turns` defaults to `all`, so the child also holds the parent's turn input unless the call passes `none` or a turn count. What a spawn buys is graded by the seat — see Review Independence — never by the fact that it happened.
|
|
39
|
+
Verify a spawn from the artifact: Claude writes the child to its own `agent-<id>.jsonl` beside the session transcript; Codex writes a rollout whose header carries `parent_thread_id`, `agent_nickname`, `agent_path`, `agent_role`. Codex's `--json` stream cannot see a spawn at all — its `collab_tool_call` object is identical whether or not one occurred.
|
|
39
40
|
2. **Parallelism:** independent items spawn in parallel with per-item tracking.
|
|
40
41
|
3. **Residual context:** spawn work whose working log is much larger than the conclusion the main needs, such as broad reads, searches, tests, or implementation bursts.
|
|
41
42
|
4. **Specifiability:** keep work local when it needs the main's live context or unresolved round-trips, especially deep debugging. Grind alone is not a FRONTIER reason.
|
|
@@ -46,6 +47,14 @@ Main-context pollution is usually costlier than spawn overhead. Apply these gate
|
|
|
46
47
|
- Explicit no-fan-out overrides standing authorization.
|
|
47
48
|
- Record one line per gate decision — `SpawnGate: <gate> <tier> spawn|inline — <why>` — plus the FRONTIER disposition. A launch contract's `Delegation=off` lifts the spawn obligation, not the records.
|
|
48
49
|
|
|
50
|
+
### Cost-Driven Down-Spawn (bounded implementation work)
|
|
51
|
+
|
|
52
|
+
For a unit already classified as bounded implementation work, this rule takes the place of gates 4 and 5 above; gates 1–3 and Escalation still come first, and an explicit no-fan-out instruction still wins. It is the measured text — apply it verbatim, do not paraphrase it:
|
|
53
|
+
|
|
54
|
+
> This rule applies at a work-unit boundary of bounded implementation work; an explicit instruction not to fan out always wins. Spawn a WORKHORSE for the unit when it has 5 or more items and is decision-complete, has a machine-checkable done-when, and is self-contained; otherwise do it inline. An unstated count is below 5.
|
|
55
|
+
|
|
56
|
+
Measured 2026-09-08 on the dependent L2 edit family with a claude-opus-5 (xhigh) parent and a claude-sonnet-5 WORKHORSE child: delegating a five-item unit saved about $0.05 per unit and a ten-item unit $0.14–0.18, net of the rule's own cost; a one-item unit cost $0.05 more delegated, and a three-item unit was unresolved at the registered sample. Untested sizes between and above the tested ones rest on the assumption that a saving present at 5 and 10 holds at 6–9 and beyond; the ordering with the gates above, the cost of reading this guide, and the rule's firing rate were not measured. Shipped by guide placement rather than into the global (decision D-20260908-2186cd).
|
|
57
|
+
|
|
49
58
|
## Delegation Mechanics And Teammate Persistence
|
|
50
59
|
|
|
51
60
|
Delegate execution, not decisions. A unit is delegable only when it is decision-complete, self-containedly specifiable, machine-checkable at done-when, and bounded in blast radius. Delegated output is staged until the main accepts it — workers take no external irreversible actions — and handling (brief, verify, correct, integrate) must be clearly subordinate to the work itself. A SWEEP-bound unit applies one explicit rule per item and returns ambiguity as an exception, never resolved.
|
|
@@ -54,11 +63,14 @@ Delegate execution, not decisions. A unit is delegable only when it is decision-
|
|
|
54
63
|
- Bundle related sub-floor tasks up to the decision-complete ceiling. A scout is read-only and reports file:line evidence for named pending decisions, probing the highest kill-risk unknown first.
|
|
55
64
|
- Prompt constants, thresholds, signatures, and judgment criteria are decisions even when stored in code. Discard decision-tainted worker output when review would cost more than a clean re-dispatch.
|
|
56
65
|
- Worker cost grows with request count × transcript prefix. Batch independent reads, minimize edit rounds, and dispatch independent workers/messages together.
|
|
66
|
+
- **Pin the tier before dispatch.** Unpinned, the tier is chosen once the work is in view and tracks task size rather than task difficulty. Claim a cost advantage only from evidence on this task.
|
|
57
67
|
- Use a resident teammate only for dependent slices in one burst. Verify that the CLI preserves its model and context; resume-after-completion may silently change both. Retire after the burst or cache TTL, and persist durable knowledge in files.
|
|
58
68
|
- After a discard or direction change, respawn once a routine round costs about as much as a fresh slice. Recover unique in-flight state to files first.
|
|
59
69
|
- Redirects to busy workers may queue rather than preempt. Check artifacts before destructive redirects, phrase them conditionally, and stop an actively harmful worker by scoped PID/worktree authority.
|
|
60
70
|
- Idle/progress notifications are hypotheses; verify repo artifacts before re-dispatch. An idle signal is liveness decoupled from the report: a subagent can go idle without ever delivering its result, so idle-without-report is not done — request the report explicitly rather than waiting. Cross-reset state belongs in files, not task boards or transcripts. When polling concurrent async jobs, pin the exact id/handle received at dispatch — a "latest" convenience selector can silently point at a sibling job and return plausible-but-wrong results.
|
|
61
71
|
- Give reviewers/subagents a read-only diff, snapshot, or isolated worktree — not the live tree the main is editing — and forbid destructive git ops (checkout --, reset --hard, stash, clean) on any tree with uncommitted work; re-verify tree integrity before trusting results produced mid-edit.
|
|
72
|
+
- Codex `spawn_agent` decides how much of the parent crosses: `fork_turns` defaults to `all`, and takes `none` or a turn count. A `SubagentStart` hook there receives `agent_type` and may return `continue: false`, so a tier rule can be enforced rather than stated.
|
|
73
|
+
- No per-spawn corpus suppression exists on either host: the subagent definition carries model and effort, not scope. Excluding the standing instructions is a process-level act — `claude --setting-sources ''`, or `CODEX_HOME` pointed at a directory holding only `auth.json` — and it removes the tier definitions with them, so a corpus-free reader and a pinned tier cannot come from one process. An emptied `CODEX_HOME` without `auth.json` fails 401; skills still load.
|
|
62
74
|
- Review cost scales with the diff, so layered review preserves delegation savings. Lower reviewer tier before dropping a review kind.
|
|
63
75
|
|
|
64
76
|
## Driving Codex CLI Directly
|
|
@@ -99,6 +111,7 @@ Instruction/config reach is per invocation. A rule in AGENTS.md cannot bind a he
|
|
|
99
111
|
- Prompt caches are per model; each mid-session switch reprocesses the loaded transcript once. Batch work by model and switch at reset boundaries.
|
|
100
112
|
- Prefer a spawned FRONTIER decision. Switch the main only when context fidelity outweighs handoff cost and the judgment cannot be delegated.
|
|
101
113
|
- Avoid unplanned alternation. Planned escalate/return and explicit A/B comparisons are valid when each cache miss is budgeted.
|
|
114
|
+
- Forking preserves conversation content on both hosts and the prompt cache on only one: a Claude `--fork-session` at the same model reuses nearly all of it and loses it across models, while a Codex `exec fork` re-sends at any model. So "fork without changing the model" is a Claude rule; on Codex a fork is priced like a fresh dispatch.
|
|
102
115
|
|
|
103
116
|
## Cross-Verification Economy
|
|
104
117
|
|
|
@@ -120,7 +133,7 @@ How much independence a review actually bought, as an ordinal grade per reviewer
|
|
|
120
133
|
| `perspective_floor` | otherwise — still a real review |
|
|
121
134
|
|
|
122
135
|
- Only upward counts. A different-but-**lower** effort earns nothing and lands on the floor: cheaper is not another perspective.
|
|
123
|
-
- **Isolation is a gate, not a rung.** A reviewer that cannot be shown to run in a fresh context is excluded entirely (`NOT_REVIEW`), never graded low — an in-context "review" is the failure this ladder exists to make visible, so it must not appear as a weak pass. Isolation is realised per mechanism: a fresh read-only subprocess, a hermetic profile, a stdio tool call in a fresh session, a headless host workflow, or a stateless API call. If none of these can deliver the required seat, the review did not happen.
|
|
136
|
+
- **Isolation is a gate, not a rung.** A reviewer that cannot be shown to run in a fresh context is excluded entirely (`NOT_REVIEW`), never graded low — an in-context "review" is the failure this ladder exists to make visible, so it must not appear as a weak pass. Isolation is realised per mechanism: a fresh read-only subprocess, a hermetic profile, a stdio tool call in a fresh session, a headless host workflow, or a stateless API call. If none of these can deliver the required seat, the review did not happen. An in-process subagent clears the conversation and keeps the standing instructions, so it satisfies isolation and still grades only by its seat — spawning is not itself a rung.
|
|
124
137
|
- The floor still requires **at least two distinct perspectives**; one pass on the main's own seat is self-review with extra steps.
|
|
125
138
|
- Multiple ready methods are **coverage, not diversity**. Distinct labels do not prove the perspectives differed.
|
|
126
139
|
- **Achieved is not available.** What can be projected before a review runs is `projected`; a clean verdict without a receipt evidencing a fresh dispatch, the declared packet, a non-empty result and the exact seat is `PROPOSED`, never ACHIEVED. A model echo is not a receipt.
|
|
@@ -222,14 +235,14 @@ Write for the next agent and re-verification, not narrative. Required content:
|
|
|
222
235
|
|
|
223
236
|
This is the human-readable projection of concrete models/tools; `launch/agent-launch.toml` is the machine launch authority and parity checks keep them aligned. Re-probe when the binding is older than ~8 weeks or a newer observable model/tool changes the surface. `agent-bios install` overwrites deployed bindings, so edit the repo copy.
|
|
224
237
|
|
|
225
|
-
Binding (2026-08
|
|
238
|
+
Binding (2026-09-08):
|
|
226
239
|
|
|
227
240
|
| Slot | Binding | Notes |
|
|
228
241
|
|---|---|---|
|
|
229
|
-
| FRONTIER | Claude Fable 5 · GPT-
|
|
242
|
+
| FRONTIER | Claude Fable 5.1 · GPT-6 Astra (read-only; max default; launcher may explicitly select Ultra) | bounded hardest decisions and verdicts |
|
|
230
243
|
| HELM | Claude Opus 5 (xhigh) · GPT-5.6 Sol (xhigh main; main Ultra requires explicit selection; bounded FRONTIER Ultra allowed) | standing main; Codex defaults bypass, explicit sandbox narrows |
|
|
231
|
-
| WORKHORSE | Claude
|
|
232
|
-
| SWEEP | Claude Haiku 4.5 · GPT-5.6 Luna (
|
|
244
|
+
| WORKHORSE | Claude Sonnet 5 (xhigh) · GPT-5.6 Terra (xhigh) | implementation and per-item judgment |
|
|
245
|
+
| SWEEP | Claude Haiku 4.5 (effort omitted) · GPT-5.6 Luna (max) | read-only; one explicit rule per item; not a rebind candidate |
|
|
233
246
|
| VERIFIER-A | plain `codex exec` deep pass — GPT-5.6 Sol at ultra effort, packet on stdin (`-c service_tier="fast"` as explicit fast opt-in) | strongest single reader; cross-family from a Claude main |
|
|
234
247
|
| VERIFIER-B | Claude Code ultracode workflow (keyword-opened, many-agent) | code/execution kind; fan-out counterpart |
|
|
235
248
|
| INDEPENDENT-PR-REVIEWER | Codex CLI | adversarial `gh pr diff` review |
|
|
@@ -241,8 +254,8 @@ Binding (2026-08-10):
|
|
|
241
254
|
Codex direct-drive (verified 0.144.1, 2026-07-12):
|
|
242
255
|
|
|
243
256
|
- `codex-helm` defaults the HELM main to `--dangerously-bypass-approvals-and-sandbox`; explicit `--sandbox` wins in any flag order. Non-Ultra defaults native multi-agent off; explicit main Ultra defaults it on.
|
|
244
|
-
- HELM is instructed to dispatch tiers through internal `codex-run`, which pins model/effort/sandbox. FRONTIER uses a separate `gpt-
|
|
245
|
-
- This is an instruction-backed, live-E2E-verified default, not a security boundary: main bypass and arbitrary expert `-c` remain available by design. `frontier.toml`
|
|
257
|
+
- HELM is instructed to dispatch tiers through internal `codex-run`, which pins model/effort/sandbox. FRONTIER uses a separate `gpt-6-astra`, read-only root: max by default, Ultra for divisible work, lower effort when cost/latency dominates. Nested multi-agent is enabled only for Ultra. Native `codex exec` spawn cannot pin role/effort.
|
|
258
|
+
- This is an instruction-backed, live-E2E-verified default, not a security boundary: main bypass and arbitrary expert `-c` remain available by design. `frontier.toml` pins the direct native FRONTIER default to max; launcher projections overwrite it from the selected tier.
|
|
246
259
|
- `codex-run` owns reach, stdin, schema, profiles, expert `-c`, channel preservation, and exit status. Keep it internal.
|
|
247
260
|
- `claude-run` is its Claude-side twin and the command a composable review contract names for a panel dispatch on that host. Same shape: prompt on stdin, final message on stdout, exit status mirrored, `--model`/`--effort` pinning the seat, everything it does not recognise forwarded to `claude`. It denies the mutating tools by default, which is not the OS-level sandbox `codex-run` gets — do not read the two defaults as equivalent guarantees. Dispatch whatever command the contract names rather than the bare CLI: only the adapter can report what the dispatch actually did, and a review with no receipt stays PROPOSED.
|
|
248
261
|
|
|
@@ -250,21 +263,23 @@ Dispatch packets:
|
|
|
250
263
|
|
|
251
264
|
| Target | Required packet / default |
|
|
252
265
|
|---|---|
|
|
253
|
-
| GPT-
|
|
254
|
-
| GPT-5.6 Terra WORKHORSE | outcome, frozen scope/inputs, authority, done-when, evidence/report, escalation;
|
|
255
|
-
| GPT-5.6 Luna SWEEP | exact search space,
|
|
266
|
+
| GPT-6 Astra FRONTIER | outcome, evidence, decision boundary, stop/verification; max default; read-only |
|
|
267
|
+
| GPT-5.6 Terra WORKHORSE | outcome, frozen scope/inputs, authority, done-when, evidence/report, escalation; xhigh |
|
|
268
|
+
| GPT-5.6 Luna SWEEP | exact search space, one rule per item, ambiguity behavior, stop, output; max; read-only; no architecture/debugging |
|
|
256
269
|
| Claude Opus 5 HELM | xhigh for agentic work; high minimum for sensitive judgment; lower only when bounded/cost-led |
|
|
257
|
-
| Claude
|
|
258
|
-
| Claude Haiku 4.5 SWEEP |
|
|
270
|
+
| Claude Sonnet 5 WORKHORSE | exact scope, apply-to-all rules, tools, verification, report; xhigh default |
|
|
271
|
+
| Claude Haiku 4.5 SWEEP | one explicit rule per item, read-only; effort parameter omitted; ambiguity returned as an exception |
|
|
259
272
|
|
|
260
273
|
Use only task-relevant tools; parallelize independent calls. Worker report: `status`, `files_or_items_touched`, `evidence`, `verification`, `risks_or_escalations`. Official basis: OpenAI [model](https://developers.openai.com/api/docs/guides/latest-model?model=gpt-5.6), [migration](https://developers.openai.com/api/docs/guides/upgrading-to-gpt-5p6-sol), [prompting](https://developers.openai.com/api/docs/guides/prompt-guidance-gpt-5p6), [Codex models](https://learn.chatgpt.com/docs/models); Anthropic [subagents](https://code.claude.com/docs/en/sub-agents), [model effort](https://code.claude.com/docs/en/model-config).
|
|
261
274
|
|
|
262
275
|
## Evidence Base
|
|
263
276
|
|
|
264
|
-
Single owner of numeric defaults
|
|
277
|
+
Single owner of numeric defaults. Dates and workload scopes belong to each observation; recalibration updates this table and dependent inline thresholds.
|
|
265
278
|
|
|
266
279
|
| Evidence | Result / rule supported |
|
|
267
280
|
|---|---|
|
|
281
|
+
| Claude M=40 confirmation (2026-09-06), adopted by owner correction (2026-09-08) | Sonnet 5/xhigh child under Opus 5/xhigh: KEEP confirmed on five fresh paired blocks; modelled cost-to-parity saving 45.5%, lower bound 40.4%. This is scoped cost evidence, not a general quality or billing guarantee. |
|
|
282
|
+
| Owner tier correction (2026-09-08), Codex discovery cells incomplete | Terra/xhigh is the measured experimental effort adopted by owner instruction, not a confirmed Codex KEEP verdict. The two HELM parent seats stay unchanged; SWEEP is not a rebind candidate and remains one-rule-per-item read-only work. |
|
|
268
283
|
| 15 sessions, 3,758 requests, 10 switches | switches consumed 13.9% of uncached input; avoid unplanned switching |
|
|
269
284
|
| 285-call limit incident | 208 post-limit dispatches and 34/35 lost items; breaker default 3 |
|
|
270
285
|
| 99 staged reviews | 15.2% halted after most compute; resume-first |
|
|
@@ -274,3 +289,6 @@ Single owner of numeric defaults; one production environment, 2026-07. Recalibra
|
|
|
274
289
|
| Codex native-spawn probe + HELM E2E | requested max/Ultra native children recorded xhigh/role null; separate read-only roots recorded max and Ultra successfully |
|
|
275
290
|
| 1,075 sessions of 50+ requests, both hosts (2026-08-16; the earlier 62-session top-by-size sample gave ~1,800-2,000) | context grows ~2,400 tok/request (IQR 1,850-2,950), hosts within 7%, ~1,800 in 400+-request sessions; auto-compaction fires at 84-95% of window, never earlier |
|
|
276
291
|
| 2 sessions decomposed by cost component (2026-08) | input 92-94% of cost, output 6-8%, cache hit 95-97%, uncached input 0.0%; an 867K→200K budget cuts cost per request ~4x |
|
|
292
|
+
| 4 dispatches over 3 situations built to trigger the Independence gate, plus a positive control (2026-09-01) | 0 spawns in the 3, 1 in the control; de-minimis absorbed all three and each inline answer was correct — a spawn mandate stated as always-fire did not fire |
|
|
293
|
+
| 60/150-file mechanical scan, N=5 on load-bearing cells (2026-09-02) | inline $0.627→$0.919; tier-pinned delegation $0.665→$0.921; unpinned +57-73%; an N=2 first reading of the same cells reported 19% and 36% savings that N=5 erased |
|
|
294
|
+
| fork cache reuse, both hosts (2026-09-02) | Claude same-model 98.9%, cross-model 0-26%; Codex 14-18% at any model (N=1 per Codex cell) — fork guidance is host-qualified |
|