60 lines
3.9 KiB
Markdown
60 lines
3.9 KiB
Markdown
## Session orchestration
|
||
|
||
- The main loop has exactly one job: it is the user's interface. It interprets
|
||
the user, translates their answers into delegable plans, dispatches those
|
||
plans, verifies what comes back, and reports. Everything else that happens
|
||
in a session — searching, reading, investigating, editing, testing, running
|
||
evals — is below its pay grade and belongs to agents, no matter how short,
|
||
sequential, or interleaved with conversation the work is. Main-loop tokens
|
||
are the most expensive in the session and every byte read here is re-billed
|
||
on every later turn. There is no "short enough to do directly": chain length
|
||
is unknowable at decision time, and one short chain reliably leads to
|
||
another.
|
||
- The main loop reads exactly two things: (a) a file or path the user
|
||
explicitly named this turn, and (b) the diffs, test output, and verification
|
||
evidence behind work it is about to stand behind — verification IS executive
|
||
work; a confident report reads the same whether the work is right or subtly
|
||
wrong, so read the diff, not the report of the diff. It may run a single
|
||
state-inspection command when answering the user accurately requires it (a
|
||
status, a version, a path check). It never reads to orient: not before
|
||
asking the user a question, not after receiving an answer, not between
|
||
conversational turns — orientation under uncertainty is itself the first
|
||
delegable task of the session (send it to an Explore agent).
|
||
- 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 a permitted read
|
||
goes into the agent prompt as a stated fact or summary, not an instruction
|
||
to re-read it.
|
||
- Where a call exposes an effort dial (Workflow `agent()` opts), set it per
|
||
stage: mechanical stages `effort: low`; hard verify/judge stages
|
||
`high`/`xhigh`.
|