For agents that write and change code from a brief: a command, a site, a page or a migration.
What is in it
7 in the kit
Open leverWhen the work isn't trivial, build the tool that does it. A script does the work- Do the first unit by hand to learn the recipe. Then write the tool, rerun it o- Make it safe to rerun (idempotent).- Codemod for edits, generator for repeated files, a query (sqlite, jq, awk) for- One deterministic pass beats handing units out. If neighbours share the work, - Smallest tool that does the job, never a framework. Scratch levers live in the- If you cite this skill and there is no script, codemod or generator in the res
When the work isn't trivial, it has your agent write the script that does it, rerun it on the first unit and diff the result against the hand version.
Open prove-itUnverified work has unknown correctness. Check the real thing directly.- Run the real program from outside and read what it prints (a demonstration, de- Check liveness directly (the process, the listener), not state derived from it- When a check fails, suspect the way you looked before you suspect the system.- Script the check when you can, so a reviewer reruns it instead of trusting you- A script that proves a fix is a demonstration, not a new test. Add a test only- Visual results go to the user, shown inline. Their eyes are the check.
Before your agent says it is done, it runs the real program from outside and reads what it prints, instead of trusting a compile, a cached screenshot or its own word.
Open first-principlesDon't bolt a change onto the current design. Redesign as if the new requirement 1. Read every affected file, type and rule. Know the current design before you c2. Ask: "Writing this from scratch with this requirement, what would we build?" 3. Propagate the change everywhere it reaches: types, states, events, errors cat4. Design the whole redesign, then deliver it in small verifiable steps.Signs you bolted it on: a new optional field or flag beside an old one, a specia
When a rule changes, it redesigns the type model or module from the start instead of adding another special case.
Open error-messagesWhen something fails, the person wants three things, in order: what went wrong, > The test: read the message as if you just hit the error and know nothing aboutNever ship a generic failure string: no "too weak", "invalid input", "save faile## The formula[what failed] - [the specific reason] - [the concrete next step]- What: the thing, in the person's words ("password", "this CSV file", "checkout- Why: the specific rule or cause that fired, not the whole rulebook. "needs an - Next step: something they can actually do: a format to use, a field to change,- Blame-free: describe the input, not the person. "needs an uppercase letter", nNot every message needs all three as separate phrases, but it must answer all th## Examples### Validation: name the rule that failed, not all of themts// ❌ same message no matter which rule failed
Rewrites a vague error or validation message so it names exactly what went wrong, which rule failed and what to do next, without blaming the person.
Open eval-design## Words- Environment: the briefs, skills, rules, harness, strategy, model and effort. W- Experiment: one change to the environment, then runs of real tasks.- Eval: a question and the figure that it produces. Ask the question of many ite- Judge: the one who answers an eval's question: a program, the owner, or a mode- Rung: one model at one effort. Opus medium is the top rung.- Owner: the person whose judgement the work serves.- Lights out: the work runs without a review by the owner. Lights out is the goa## Kinds of eval- Capability eval: a figure that we try to move. Read it as a trend. Do not put - Regression eval: a figure that holds on this rung. It is a gate for each exper- When a capability eval holds reliably, move it to regression.- A gate without capability evals cannot improve. Do not use it until it has the## Write an eval
It turns 'is the agent better now?' into a question asked of many items of real work, with a named judge and a figure you can track.
Open encode-lessonsThe second time a lesson comes up, the text failed. Hold it with structure inste- Pick the cheapest guard that holds it: a type, then a lint rule, then a hook o- If the fix is structural, ship only the structural fix. Delete the instruction- If the lesson needs judgement and no guard can hold it, make the line more pro- Record the lesson's origin (the user's words, with the time) on the ticket, noExample: "never auto-compact" was a habit to remember. It became DISABLE_AUTO_CO
When the same correction comes up a second time, it picks the cheapest guard that holds it (a type, a lint rule, a hook or a script) instead of adding another line of text.
Open state-machinesDesign each module as a state machine. Design each program as a state machine ofPut the states of a module in one union type. Put its events in a different unioA surface is a CLI command, an HTTP route or a page. A surface sends events in aDo not use classes. Do not use inheritance. Do not use methods that hide state.Types do not reach across modules. When two modules need the same type, do one o1. Lift it out to a place both import from, if it is a fact about the domain (Em2. Merge the modules, if it is a state or event variant. The split was wrong, an
lever: When the work isn't trivial, it has your agent write the script that does it, rerun it on the first unit and diff the result against the hand version. prove-it: Before your agent says it is done, it runs the real program from outside and reads what it prints, instead of trusting a compile, a cached screenshot or its own word. first-principles: When a rule changes, it redesigns the type model or module from the start instead of adding another special case. error-messages: Rewrites a vague error or validation message so it names exactly what went wrong, which rule failed and what to do next, without blaming the person. eval-design: It turns 'is the agent better now?' into a question asked of many items of real work, with a named judge and a figure you can track. encode-lessons: When the same correction comes up a second time, it picks the cheapest guard that holds it (a type, a lint rule, a hook or a script) instead of adding another line of text. state-machines: Design each module as a state machine.