🤖 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,51 @@
|
||||
# Model notes
|
||||
|
||||
Observations about models in Spire work. They are dated and sourced, and they are **not law**. Use them to pick a default and to know what to watch for; the problem at hand decides. When a note is contradicted, add the newer observation with its date rather than silently dropping the old one, unless it is plainly withdrawn.
|
||||
|
||||
Context figures are **guesstimates** from Claude Code experience. Agents cannot see their own token count, and orchestrators cannot yet look into a running subagent's usage.
|
||||
|
||||
Sources: dirigent `docs/workpad/reports/2026-10-01-lean-process-report.md` (+ 2026-10-05 addendum); spacecraft `docs/workpad/reports/2026-09-27-13-strategy-mvp-retrospective/report.md`, `docs/workpad/reports/2026-09-29-13-orchestration-overhead-attribution.md` and `docs/workpad/brainstorm/the_assistants_mindset.md`; reliquary journal `docs/workpad/journals/2026-10-05-21-athanor.md` (user direction).
|
||||
|
||||
## Defaults (2026-10-05)
|
||||
|
||||
Opus 5.5 for the Athanor, planning, attacking plans and phase review (user direction). Owner models for blocks come from the build plan; a common split is Opus 5.5 for hotspot blocks (state, concurrency, formats, read-path precedence) and Sonnet for mechanical ones (field sweeps, wiring, docs). Housekeeping (test runs, commits) on Haiku.
|
||||
|
||||
## Opus 5.5 — `claude-opus-5-5`
|
||||
|
||||
- Catches more, decides boldly. Can replace frequent small reviews, especially in Rust. (user, 2026-10-05)
|
||||
- Can take the user's word as holy, or reverse 100% when corrected. Relay user remarks with their weight: a passing thought is not a rule. (user, 2026-10-05)
|
||||
- Plans are thorough and long. A 5.5 plan traced a root cause in code that a 4.6 plan on the same scope missed (dirigent, 2026-10-01). 5.5 plans ran about 11× larger than earlier plans and drove scope (spacecraft, 2026-09-27). The attack step trims scope. Dirigent reports properly sized plans since (user, 2026-10-05).
|
||||
- An independent 5.5 review found 6 Important issues in about 20 min where an in-furnace review had passed; one 5.5 fix pass cleared them in 33 min (dirigent, 2026-10-01).
|
||||
- Context: comfortable to about 600k (guesstimate, user, 2026-10-05).
|
||||
|
||||
## Opus 4.6 — `claude-opus-4-6`
|
||||
|
||||
- Fast and capable. Sometimes better than 5.5 at interpreting what the user means; useful as an "understanding the human" interpreter. To be replaced eventually. (user, 2026-10-05)
|
||||
- A 4.6 plan misidentified a root cause and would have broken archive compatibility; one plan, one comparison (dirigent, 2026-10-01).
|
||||
- The dirigent Athanor end review that passed with zero findings ran on 4.6 (user's attribution, 2026-10-05; the report recorded "model unknown").
|
||||
- Withdrawn 2026-10-05: "prefer Opus 4.6 for implementation" and "Opus 5 tends to hallucinate" (former Igor model-tier notes, 2026-09). The 5.5 evidence above contradicts them.
|
||||
|
||||
## Fable
|
||||
|
||||
- Better still at interpreting intent (user, 2026-10-05). Used for two design reviews in spacecraft (Fable 5.1, 2026-09-27). Full id not recorded here.
|
||||
- Not dispatched as a subagent unless the user asks (Igor rule).
|
||||
|
||||
## Sonnet
|
||||
|
||||
Full id not recorded here; spacecraft notes mention "Sonnet 5".
|
||||
|
||||
- Dirigent Sonnet-first-draft experiment (2026-09-28 to 2026-10-01): the mechanical blocks were clean; all 6 Important findings sat in complex blocks. About 4 of the 6 were plan gaps that any implementer following the plan would have carried out. The user ended the experiment and moved complex work to 5.5. Read this as "the plan mattered as much as the model", not as "Sonnet cannot build".
|
||||
- Clean on run-and-record and checklist work. Wrote tests that could not fail; could not finish an open-ended performance task (spacecraft, 2026-09-29).
|
||||
- Reached 500k–750k tokens on long complex tasks (dirigent memory, 2026-10-01).
|
||||
|
||||
## Haiku
|
||||
|
||||
- Fine for runs, compiles, commits and mechanical appliers. Treat its self-reports as claims to check: it once reported "no deviations" alongside misplaced edits (spacecraft, 2026-09-29).
|
||||
|
||||
## Context and block size
|
||||
|
||||
- Both extremes failed. Many tiny fresh implementers relearn the code each time. One implementer carried across tasks reached about 960k tokens and drifted (spacecraft, 2026-09-29; model probably 5.5 through the alias).
|
||||
- Measured: dirigent blocks of 11–36 min of agent work used 186k–344k tokens each (Sonnet, 2026-10-01). None ran out.
|
||||
- Guesstimates (unmeasured): a trunk read at intake of about 100k–250k; leave room for fallout and the fix pass rather than running close to the comfortable limit.
|
||||
|
||||
**Future work:** orchestrator introspection of subagent token use, and signals into running work (dirigent is working on this). Until then, the Athanor records what usage it sees in completion results and judges by block count and size.
|
||||
@@ -0,0 +1,63 @@
|
||||
# Run log and handoff notes
|
||||
|
||||
The run log is the record of a build: one file per build plan, in the workpad's `reports/` folder (name it per the `workpad` skill, e.g. `<YYYY-MM-DD-hh>-<slug>-run.md`). Each phase appends to it. The phase reviewer reads it; a successor Athanor starts from it.
|
||||
|
||||
Rules:
|
||||
|
||||
- Take every time from `date` when you write it. Never estimate or count forward by feel.
|
||||
- Durations in summaries come from git commit times.
|
||||
- Stamp the exact model id from your system prompt. If you dispatched an agent and its id is unknown, write "unknown", not a guess.
|
||||
- Totals stay **provisional** until the phase review, fix pass and re-check have closed.
|
||||
|
||||
## Header
|
||||
|
||||
```markdown
|
||||
# Run log — <plan title>
|
||||
|
||||
- Plan: <path> · Build plan: <path>
|
||||
- Branch: <branch> · Start commit: <hash>
|
||||
- Trunk notes: <path or "none">
|
||||
- Athanor: <model id> · Session journal: <path>
|
||||
```
|
||||
|
||||
## Per phase
|
||||
|
||||
```markdown
|
||||
## Phase <N> — <title>
|
||||
|
||||
| Block | Owner (model id) | Start | End | Commit | Tokens (if known) |
|
||||
|---|---|---|---|---|---|
|
||||
```
|
||||
|
||||
## Handoff note (one per block, written by the block's owner)
|
||||
|
||||
```markdown
|
||||
### Block <N.M> — <title>
|
||||
|
||||
- Model: <exact id>
|
||||
- Start / end: <`date` output> / <`date` output>
|
||||
- Done: <what changed, in a few lines>
|
||||
- Deviations from plan: <what, and why> — or "none"
|
||||
- Flagged for review: <anything the reviewer should look at, e.g. a semantic you were unsure of>
|
||||
- Left for later: <work deferred to a later block or phase>
|
||||
- Expected broken: <areas that do not build or pass yet, and which block fixes them>
|
||||
- Commits: <hashes>
|
||||
```
|
||||
|
||||
## Phase close (written by the Athanor)
|
||||
|
||||
```markdown
|
||||
### Phase <N> close
|
||||
|
||||
- Gate: <command> — <result>
|
||||
- Tests: <command> — <result> (fallout fixed in block <N.M>)
|
||||
- Flags for the reviewer: every deviation and every "flagged for review" line above, one per bullet, with its block.
|
||||
- Not run / untested: <anything the tests do not cover>
|
||||
- Status: provisional until review, fix pass and re-check close.
|
||||
```
|
||||
|
||||
After the review, Igor (or the fixer) appends the review report path, the fix-pass commits, the re-check result, and the minors logged as follow-ups.
|
||||
|
||||
## Trunk notes (optional, written at intake)
|
||||
|
||||
Short, for the next agent that has not read the code: key files and seams, invariants the phase touches, every consumer of a changed semantic, the gate command, known traps. A page, not a design document.
|
||||
@@ -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