🤖 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:
2026-10-05 22:12:31 +02:00
parent 08e22a731d
commit e51520723c
5 changed files with 283 additions and 72 deletions
+52 -48
View File
@@ -1,81 +1,85 @@
---
name: implementation
description: Orchestrate non-trivial implementation work across one or more agents — deciding what to do inline, what to delegate, in what order, and how to verify. Use this skill whenever the user asks you to "implement", "build", "ship", "fix this bug", "make this work", or hands you a plan / spec / ticket to execute. Trigger especially for multi-step changes, anything involving compilation or test failures, hard-to-reproduce bugs, or work that spans multiple files or subsystems. Composes with the `workpad` skill (for any plans / journals / reports produced) and runs alongside `superpowers` and similar orchestration helpers.
description: Drive implementation lean — test the plan against the code before building, build in large blocks with a cheap gate between them, run tests and one review per phase, fix once, stop. Use whenever the user asks to "implement", "build", "ship", "fix this bug", or hands you a plan / spec / ticket to execute, especially for multi-step or multi-file changes and hard bugs. Harness mechanics and model notes live in references/. Composes with `workpad`; superpowers skills are optional tools.
---
# Implementation Orchestration
# Implementation
This skill is about **how to drive implementation work**, not about how to write code. It covers: when to delegate to subagents vs. work inline, how to sequence agents, how to handle test/compile failures, and how to approach bugs without thrashing.
How to drive building, not how to write code. The default is lean: few, strong checks placed where the risk is. Every check re-reads the same code, so one check sized to the risk beats several small ones. More ceremony is allowed when you can say why.
**Cycle context:** This skill governs what happens inside Stage 5 (Implement) of the development cycle. The Athanor receives a plan, not a conversation — no mid-run questions. Its output (diff + plan reference) goes to a fresh reviewer for Stage 6 (Review).
The plan is the main lever. Most defects trace back to the plan, not to the model that drafted the code. So quality control moves upstream: attack the plan before building, then build in large chunks and review once per phase.
## Default to sequence, not parallel
If one agent can do the whole change in one go, do it inline. The cycle below is for work that does not fit.
Implementation work is almost always **sequential** by nature — later changes depend on earlier ones, even when they look independent on paper. Two agents editing the same file in parallel is a merge conflict; two agents touching adjacent abstractions in parallel is a subtle integration bug.
## The cycle
Run subagents in parallel only when the work is **genuinely** parallelizable:
- Touching disjoint files / modules with no behavioral coupling.
- Independent investigations or read-only exploration.
- Test runs across separate test suites.
```
plan ─► attack the plan ─► user sees the reshaped plan and open decisions
phase: block ─► gate ─► block ─► gate ─► … ─► tests once ─► run log
phase review (fresh) ─► one fix pass ─► re-check only Critical/Important ─► stop ─► next phase
```
If you have to think hard about whether two tasks are independent, they probably aren't. Default to sequencing.
Separate the roles: the planner, the attacker, the builder and the reviewer are different agents. Under Igor, Igor dispatches the plan, the attack and every phase review; the Athanor builds one phase per turn.
## Delegate compile / test fixes — but verify
## Attack the plan
A common, useful pattern: when the build is broken or tests are failing after a change, dispatch a subagent to fix it. They're tight, well-scoped tasks with a clear pass/fail signal, and they free up the main thread for higher-level decisions.
After the plan is written, a fresh agent that did not write it **tests it adversarially against the code**: blockers, design errors, wrong root causes, and consumers of changed semantics the plan missed (other readers, stats, migrations, callers in other crates). In the same pass it **reshapes** the plan: phases that each end in a testable state, blocks that one owner can finish, scope cut back to the goal, decisions the user must make listed. It writes a new build plan; the original stays as written.
But: **always verify the fix yourself before trusting it.** Subagents fixing tests have a strong incentive to make the test pass, and the easiest way to make a test pass is sometimes the wrong way (deleting the assertion, weakening the expected value, mocking out the thing being tested, catching-and-ignoring the failing path). When the agent reports green:
This step is what pays for dropping per-task review. A plan checked against the code catches in minutes what many small reviews would find one by one, or not at all. Without it, lean is just less review.
1. Read the diff they produced — not just the report.
2. Confirm the fix matches the intent of the original test, not just its letter.
3. Re-run the relevant tests yourself if there's any doubt.
The build plan sets defaults: block size, owner model per block, the gate per block, what may stay broken between blocks. It may place an extra review at a hotspot if it says why. Its risk list shapes the build. It is not the phase reviewer's scope: a reviewer handed a checklist tends to confirm the checklist.
If you can't tell from the diff whether the fix is real, push back. "Tests pass" from a subagent is a hypothesis, not a conclusion.
Plan-writing tools are swappable (superpowers `writing-plans` today; others later). The attack is the same whichever wrote the plan.
## Bugs: prove before fixing, explore before focusing
## Building a phase
Two patterns that prevent the worst kinds of bug-fix thrash.
- **Sequence by default.** Later changes depend on earlier ones, even when they look independent. Run in parallel only for truly disjoint work: separate files with no behavioural coupling, read-only exploration, separate test suites. If you have to think hard about independence, sequence.
- **One owner per coherent change.** Do not split one logical change across agents; they fight over the boundary.
- **Hand over as commits, not descriptions.** Each block commits and adds a short handoff note to the run log (template: `references/run-log.md`). The note is how flags reach the reviewer.
- **Between blocks, a cheap gate, not a review.** Compile or typecheck what the block owns. Run the test suite once, at phase end, and fix the fallout in that last block.
- **Decisions belong before the run.** Inside it, take the conservative default, flag it in the handoff note and continue. Do not wait on the user.
- **Deviate with a reason.** Splitting a block, changing an owner model, adding a check: allowed, logged with why.
**Hard bugs should be proven by a test first.** Before changing production code to fix a bug, write the test that reproduces the bug and watch it fail. This does three things at once: it confirms you actually understand the bug, it gives you an unambiguous signal when the fix works, and it leaves a regression guard behind. If you cannot write a failing test, you do not yet understand the bug well enough to fix it — keep investigating.
## Context: fresh, fork, or keep
For trivial / obvious bugs (typo, off-by-one in an unambiguous spot, missing null check), skip this. The test-first rule is for anything you'd describe as "I think the issue is…" rather than "the issue is…".
Both extremes have failed. Many tiny fresh implementers relearn the code each time and fragment the plan. One implementer kept across many tasks bloats and drifts. Choose per block: how much shared understanding does it need, and how much room is left? Context figures in `references/models.md` are guesstimates, not limits.
**Bugfixing starts with exploration, not focus.** When handed a bug, the temptation is to dive into the suspected file and start poking. Resist for a few minutes:
One option is **trunk and forks**. At intake the builder reads the build plan and the code it touches (the trunk) and writes short trunk notes. Complex blocks in the trunk's area go to a fork of the builder, which inherits its context and model. Mechanical or distant blocks go to a fresh agent that reads the trunk notes. Which harness behaviour is verified and which is assumed: `references/spawning-claude-code.md`.
- Look at the surrounding code paths, not just the suspected one. Bugs often live one or two layers up from where the symptom manifests.
- Skim recent commits to that area — was something changed recently that might explain it?
- Check whether the same pattern appears elsewhere — if it does, the fix may need to be applied in multiple places, or the abstraction itself is the problem.
- Reproduce the bug yourself end-to-end before changing anything.
## Phase review, fix, stop
A short exploration phase pays for itself many times over against fixing-then-discovering-it-was-the-wrong-place.
- A **fresh** reviewer that did not build the phase, dispatched outside the build, stamps its model id in its report header. A review without a stamped id does not count.
- It is adversarial: it runs the gates, traces concrete scenarios, and **answers every deviation and flag in the handoff notes**, one by one. It looks specifically for **weakened checks** (loosened assertions, downgraded errors) and **tests that cannot fail**.
- **One fix pass** over all findings. Minors are fixed in that pass or logged as follow-ups.
- **Re-check only Critical and Important**, by a fresh reviewer scoped to those findings. Then stop.
- Extra reviews (for example a mid-phase review of a hotspot block whose note flags a deviation) are a choice with a stated reason, not a default.
## Sequencing implementation agents
## Bugs
When a task needs multiple implementation agents, plan the sequence before launching:
- **Prove it with a failing test first** when you would say "I think the issue is…". It confirms you understand the bug, signals when the fix works, and stays as a guard. If you cannot write the failing test, keep investigating. Skip this for obvious bugs.
- **Explore before you focus.** Look one or two layers up from the symptom, skim recent commits in the area, check where the same pattern recurs, reproduce end to end before changing anything.
1. **One agent owns each coherent change.** Don't split a single logical change across two agents — they'll fight over the boundary.
2. **Each agent receives the changes from the previous one as committed code, not as a description.** Either commit between agents or hand the diff over explicitly.
3. **Run tests between agents, not just at the end.** Catching a regression at agent N+1 is much cheaper than catching it at agent N+5.
4. **The orchestrator (you) is responsible for keeping the high-level plan coherent.** Subagents see only their slice.
## Spawning and models
For changes small enough that a single agent could do the whole thing, just do it inline. The orchestration overhead is only worth paying when the work genuinely doesn't fit.
- Read `references/spawning-claude-code.md` before dispatching. In short: sequential work runs in the foreground; resume agents only from the session root; leaf briefs say "do this yourself; do not dispatch further agents".
- Every plan, handoff note and review stamps the exact model id the agent ran on.
- Model traits are in `references/models.md`: dated observations, not law.
## When to write things down
## Writing things down
Use the `workpad` skill for placement. The implementation-specific cases:
Use the `workpad` skill for placement.
- **Plan first** for anything more than a few files or a few hours of work. Write it to `plans/` and confirm with the user before touching code. A wrong plan caught at planning time costs minutes; caught at code-review time costs days.
- **Journal a hard bug** — long bug hunts with multiple dead ends should be captured in `journals/` as you go (append-only). The journey is the value; the final fix alone won't tell future-you why obvious-looking alternatives didn't work.
- **Spec frozen contracts.** If implementation reveals an invariant that other code will need to rely on (an event shape, an error code, a state-machine transition), promote it to `specs/` so it doesn't quietly drift.
- The plan and the build plan go to `plans/`, the run log and review reports to `reports/`.
- The run log and the session journals are the record of a run. Take times from `date` and durations from git, never from feel. Journals are also raw material for later mining (future work).
- Journal a hard bug as you go, dead ends included.
- Promote invariants that other code will rely on (event shapes, error codes, state transitions) to `specs/`.
## Composition with other skills
## Project settings
- **`workpad`** governs where any markdown artifacts go. Defer to it.
- **`research-tree`** is the right tool when the question "how should I implement this" is itself unsettled and decomposes into multiple investigations. Run that first; come back to this skill once you have a plan to execute.
- **`superpowers`** and project-specific skills (e.g. ticket workflows, review skills) layer on top of this — they handle domain specifics; this skill handles the orchestration shape.
Read these from `spire:project`; a brief overrides both the config and this skill: worktrees or one checkout, branch ownership, staging (explicit paths), gate and test commands, owner-model defaults per block kind, standing brief constraints for sensitive areas, host rules (temp dirs, memory caps).
## What this skill does *not* govern
## Composition
- Code style, language conventions, or framework choices — that's the project's call.
- Specific test frameworks, CI configuration, or branch strategy.
- The internal structure of a plan / journal / spec — see `workpad`.
- **`workpad`** decides where documents go. **`research-tree`** comes first when how to build is itself an open question.
- **Superpowers** is a toolbox: `writing-plans`, `test-driven-development`, `systematic-debugging`, `verification-before-completion`, `dispatching-parallel-agents` and others are fine to use. Where one prescribes a per-task review loop or other ceremony, the lean rules here take precedence. `subagent-driven-development` is not the default loop; use it only when a plan asks for per-task review.
- This skill does not govern code style, test frameworks, CI or plan formats.
@@ -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) |