g4borg
e51520723c
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.
86 lines
7.6 KiB
Markdown
86 lines
7.6 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`; superpowers skills are optional tools.
|
|
---
|
|
|
|
# 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.
|
|
|
|
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.
|
|
|
|
Plan-writing tools are swappable (superpowers `writing-plans` today; others later). The attack is the same whichever wrote the plan.
|
|
|
|
## 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, fork, 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 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`.
|
|
|
|
## 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**.
|
|
- **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.
|
|
|
|
## 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`; 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 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.
|