reliquary/plugins/spire/skills/implementation/SKILL.md

name, description

name

description

implementation

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`.

Implementation

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.

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.

If one agent can do the whole change in one go, do it inline. The cycle below is for work that does not fit.

The cycle

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

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.

Attack the plan

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.

A plan written before earlier phases landed may be stale. The attack checks it against the code as it is now; it reads the previous phase's run log and review only when something is off.

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.

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.

A plan holds decisions, contracts, invariants and the scope fence. Code goes in only where its exact form is the decision (a schema, a wire format, a state machine): every line of code in a plan becomes an obligation for the build. Whatever tool wrote the plan, the attack is the same.

Building a phase

• 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 its owner writes a short handoff note (template: references/run-log.md): a gremlin writes notes/<block>.md and the Athanor appends it to the run log; a fresh agent writes into the run log directly. 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.

Context: fresh, trained, or keep

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.

The Athanor's option is a trained implementer and gremlins. One base per build, a headless session trained early: it reads the code the build touches and writes the trunk notes. One gremlin per complex block, spawned from the base with a delta brief, so each block starts from the base's reading. The base is rebased at phase boundaries or when the helper says so. Mechanical or distant blocks go to a fresh agent that reads the trunk notes. Mechanics and rules: spire:gremlins. It is Windows-tested; other platforms fail closed until tested, and there fresh agents build every block (a fresh agent then writes the trunk notes). Which harness behaviour is verified and which is assumed: references/spawning-claude-code.md.

Phase review, fix, stop

• 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.
• It lists what was built that the plan did not ask for. On record only, never an automatic revert: an unplanned addition may be a good one.
• 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. A Critical or Important that survives the re-check goes to the user or into a new plan, not into the next phase.
• 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.

Bugs

• 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.

Spawning and models

• 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.
• Gremlins run on the base's full model id; spawn takes no model override.
• Model traits are in references/models.md: dated observations, not law.

Writing things down

Use the workpad skill for placement.

• 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/.

Project settings

Read these from spire:project (its ## Build section; project.local.md wins over project.md). Unset means the default in this skill; none means deliberately absent. 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).

Composition

• workpad decides where documents go. research-tree comes first when how to build is itself an open question.
• Superpowers is not part of this cycle. When to use it anyway (e.g. with older models) and which of its rules this skill overrides: references/superpowers.md.
• This skill does not govern code style, test frameworks, CI or plan formats.