61 lines
4.1 KiB
Markdown
61 lines
4.1 KiB
Markdown
## Session orchestration
|
||
|
||
- The role split is absolute, not situational: the main loop is the session's
|
||
executive. It interprets the user, plans, delegates, verifies, and reports —
|
||
it does not do grunt work. Main-loop tokens are the most expensive in the
|
||
session, and every byte read here is re-billed on every later turn: budget
|
||
spent on grunt work is stolen from the session's total capacity for
|
||
high-level turns. Do NOT decide per task whether the coming chain is "short
|
||
enough" to do directly — chain length and follow-up probability are
|
||
unknowable at decision time, and one short chain reliably leads to another.
|
||
Delegation is the default for everything outside the exemption list below.
|
||
- Exempt from delegation (enumerated and mechanical — never "quick" or
|
||
"simple"): (a) reading a file or path the user explicitly named this turn;
|
||
(b) reviewing diffs, test output, and verification results before sign-off —
|
||
verification IS executive work, and a confident report reads the same whether
|
||
the work is right or subtly wrong: read the diff, not the report of the
|
||
diff; (c) a single state-inspection command needed to answer the user
|
||
accurately (a status, a version, a path check); (d) acts only the main loop
|
||
can perform — user interaction, spawning/steering agents, final commits it
|
||
must stand behind. Everything else — searching, investigating, editing,
|
||
testing, running evals — is delegated work, even when strictly sequential.
|
||
- Persistent manager, not spawn-per-errand: at the first delegable work of the
|
||
session, spawn ONE sonnet manager agent; route subsequent grunt episodes to
|
||
that same agent via SendMessage — it already holds the files, layout, and
|
||
diagnosis, while a fresh spawn re-pays the per-agent system-prompt tax and
|
||
re-covers ground. Spawn additional agents only for genuinely parallel,
|
||
independent work (then batch: group ~5–8 similar items into one prompt with
|
||
an explicit return format, planned before the first spawn).
|
||
- Tier routing — set `model:` explicitly on every `Agent` call (an omitted
|
||
`model` silently bills at the main-loop rate):
|
||
- `haiku`: near-mechanical, fully specified steps — apply a listed edit set,
|
||
run-and-report a command matrix, format/parser conversions, ticket and
|
||
bookkeeping API sequences, bulk moves from an explicit map. The sonnet
|
||
manager may hand these down itself.
|
||
- `sonnet` (default manager tier): investigation and diagnosis, implementing
|
||
from a settled design/spec/defect list, red-green TDD over a specified fix
|
||
list, wide grep-and-synthesize, log review, eval extraction runs.
|
||
- `opus`: entered on observed failure, not forecast — when the sonnet
|
||
manager is wrong or stuck twice on the same problem, re-delegate that
|
||
problem to opus (or pull it up to the main loop). Also first choice for
|
||
work that is judgment-dense end-to-end: architectural review, subtle
|
||
concurrency/correctness diagnosis, adversarial test design.
|
||
- When a spawn requests `sonnet` or `opus` → append to its prompt: "State the
|
||
exact model ID you are running as in the first line of your report." (The
|
||
launch result does not show the resolved model.) A report showing a lower
|
||
tier than requested → say so and adapt (re-spawn or flag the downgrade);
|
||
never treat downgraded output as judgment-tier work silently.
|
||
- Delegate async and keep working: launch independent agents in the background
|
||
and continue the executive thread; intervene only when a result shows an
|
||
agent off track. Never sleep-poll a background job from the main loop —
|
||
rely on completion notification (or Monitor); a `sleep` loop is main-loop
|
||
idle time billed at the top rate.
|
||
- Don't re-cover your own ground: a file already read under an exemption goes
|
||
into the agent prompt as a stated fact or summary, not an instruction to
|
||
re-read it. If the target of an investigation is uncertain, that uncertainty
|
||
is itself the delegable task — send orientation to an Explore agent rather
|
||
than orienting by hand.
|
||
- Where a call exposes an effort dial (Workflow `agent()` opts), set it per
|
||
stage: mechanical stages `effort: low`; hard verify/judge stages
|
||
`high`/`xhigh`.
|