🤖 Rewrite implementation skill and Athanor for lean building
The implementation skill now states the lean loop: attack the plan against the code before building, build phases in blocks with a cheap gate between them, test and review once per phase, one fix pass, stop. Harness mechanics, model observations and the run-log template move to references with dated, sourced claims. The Athanor becomes a build furnace pinned to claude-opus-5-5: one phase per turn, no planning, no plan attack, no self-review. It no longer preloads superpowers; those skills stay available as tools.
This commit is contained in:
@@ -0,0 +1,68 @@
|
||||
# Spawning agents in Claude Code
|
||||
|
||||
Harness mechanics for dispatching, resuming and forking agents in Claude Code. Other harnesses get their own `spawning-<harness>.md` when needed.
|
||||
|
||||
Each claim carries a status and a date:
|
||||
|
||||
- **verified**: read from the tool schema or checked directly, on that date.
|
||||
- **observed**: seen in real runs; the mechanism may be assumed. Source given.
|
||||
- **assumed**: inferred, not checked. Treat as a hypothesis.
|
||||
- **unknown**: open; check before relying on it.
|
||||
|
||||
The harness changes. When a claim fails, fix it here with a new date.
|
||||
|
||||
## Rules of thumb
|
||||
|
||||
- **Foreground for sequential work.** Pass `run_in_background: false` when the next step depends on the result. Background only for independent leaves whose result can go to the session root.
|
||||
- **Resume only from the session root.** Igor may `SendMessage` a finished agent (the Athanor between phases, an adept). A subagent should not resume its own children; it dispatches fresh foreground agents instead.
|
||||
- **Pinned agents: omit `model`.** The per-call alias overrides the agent's frontmatter pin. Pass `model` to a pinned agent only when you mean to override it, and say so in the journal or run log.
|
||||
- **Unpinned agents: pass `model`.** Otherwise they inherit the caller's model, which may be Fable.
|
||||
- **Stamp the model id.** Every agent reads its exact id from its system prompt and writes it into its output.
|
||||
- **Leaf briefs say "do this yourself; do not dispatch further agents."** Only orchestrators (the Athanor) are meant to fan out.
|
||||
- **Notifications report a turn ending, not a job finishing.** Read the result text before concluding anything. Check `ListAgents` before resuming.
|
||||
|
||||
## Dispatch and notification
|
||||
|
||||
| Claim | Status |
|
||||
|---|---|
|
||||
| `Agent` calls run in the background by default; `run_in_background: false` runs them in the foreground and returns the result to the caller. | verified 2026-10-05 (Agent tool schema) |
|
||||
| Background children of a subagent notify the **session root**, not their parent. The parent sees nothing and stalls until the root feeds it the result. | observed 2026-09-24 and 2026-09-28 (spacecraft journals, "athanor stalled twice … nudged with results"); dirigent memory, settled 2026-09-29. Mechanism assumed. |
|
||||
| An agent that hands work to a background child and then yields notifies `completed` at once, before any deliverable exists. Expect one more notification per background grandchild, each with its own `task-id`. | observed 2026-09-22 (Spire harness notes) |
|
||||
| The same `task-id` may notify more than once (one per turn). Track the deliverable, not the count. | observed 2026-09-22 |
|
||||
| Background grandchildren show up in `ListAgents` as flat, top-level agents of the session. If one is still writing your output path, do not resume its parent: that starts a second writer. `TaskStop` the child first if you mean to abandon it. | observed 2026-09-22 |
|
||||
| `TaskList` is the todo list, unrelated to agents. `TaskOutput` on an agent dumps its whole transcript into your context; do not use it for agents. | observed 2026-09-22 |
|
||||
| A `general-purpose` agent has the Agent tool and will delegate if its brief reads like an orchestration brief. | observed 2026-09-22 |
|
||||
|
||||
## Resume
|
||||
|
||||
| Claim | Status |
|
||||
|---|---|
|
||||
| `SendMessage` to a finished agent's name or id resumes it with its context intact. A new `Agent` call starts fresh. | verified 2026-10-05 (Agent tool schema) |
|
||||
| A resume issued from inside a subagent runs in the background; its completion goes to the root and the subagent stalls. From the root (Igor) it is safe, because the root is where the notification lands. | observed once 2026-10-05 (spacecraft journal: orchestrator resumed its implementer via SendMessage, went background, yielded). Mechanism assumed from the routing above. |
|
||||
|
||||
## Models
|
||||
|
||||
| Claim | Status |
|
||||
|---|---|
|
||||
| The per-call `model` parameter accepts aliases only (`opus`, `sonnet`, `haiku`, `fable`) and takes precedence over the agent definition's `model` frontmatter. | verified 2026-10-05 (Agent tool schema) |
|
||||
| With `model` omitted, a pinned agent runs on its pin; an unpinned agent inherits the caller's model unless a default subagent model is configured. | verified 2026-10-05 (Agent tool schema) |
|
||||
| A full model id (e.g. `claude-opus-5-5`) can only be set in the agent definition's frontmatter, so pinning by full id means a pinned agent dispatched without `model`. | verified 2026-10-05 (follows from the alias-only parameter) |
|
||||
| The `opus` alias overrode 4.6 pins in 184 of 184 spawns (they ran on 5.5). | observed 2026-09-27 (spacecraft MVP retrospective) |
|
||||
| Passing `model: "opus"` gave the Athanor the model Igor was running on: a 4.6 Igor produced a 4.6 Athanor (the dirigent end review that passed with zero findings). | observed 2026-10-05 (user's attribution; the dirigent report recorded the model as unknown). How the alias resolves is assumed, not checked: it may follow the caller's model or a session default. Either way the alias, not the pin, decided. |
|
||||
| Every agent sees its exact model id in its system prompt. | verified 2026-10-05 (this agent's prompt shows `claude-opus-5-5`) |
|
||||
|
||||
## Fork
|
||||
|
||||
| Claim | Status |
|
||||
|---|---|
|
||||
| `subagent_type: "fork"` exists. A fork always inherits the caller's model; the `model` parameter is ignored. | verified 2026-10-05 (Agent tool schema) |
|
||||
| A fork copies the **caller**, not an arbitrary agent. Only the agent holding a context (e.g. the Athanor as trunk) can fork it. | assumed (no parameter names a fork source; Igor's skill calls it "forking yourself") |
|
||||
| A fork starts with the caller's full transcript, so it starts at the caller's token count. | assumed, not measured |
|
||||
| Can a fork fork again? Does a foreground fork return its result to the caller? Does it see the caller's preloaded skills? | unknown; check in a throwaway preflight before relying on trunk and forks |
|
||||
|
||||
## Agent types
|
||||
|
||||
| Claim | Status |
|
||||
|---|---|
|
||||
| Plugin agent types (`athanor`, `adept`, `researcher`, …) can be missing in remote sessions, where `/reload-plugins` is not available. Fallback: `general-purpose` with an explicit `model`, and the agent file's body pasted into the brief. | observed 2026-10-05 (reliquary Igor journal, 21:00) |
|
||||
| `Explore` and `Plan` are read-only (no Edit/Write). Do not use them for tasks that must write a file. | observed 2026-09-22 (Spire model tiers) |
|
||||
Reference in New Issue
Block a user