88 lines
8.0 KiB
Markdown
88 lines
8.0 KiB
Markdown
---
|
|
name: implementation
|
|
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`.
|
|
---
|
|
|
|
# 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 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.
|
|
|
|
## Context: fresh, gremlin, 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.
|
|
|
|
One option is **trunk and gremlins**. At intake the builder reads the build plan and the code it touches (the trunk) and writes short trunk notes. A headless base is trained on that trunk, and each complex block in its area goes to a gremlin forked from the base (`spire:gremlins`; the Athanor's procedure has the call sequence). Mechanical or distant blocks go to a fresh Agent-tool agent that reads 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.
|
|
- 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.
|
|
- This skill does not govern code style, test frameworks, CI or plan formats.
|