awb-plan-then-code
Skill2 starsChanged 6 months agoMITView on GitHub
WHAT: a workflow for implementing a non-trivial change the disciplined way — plan, then code, then test, then review. USE WHEN: the user wants to add a feature or make a multi-file change, or says "implement", "build", "add", "let's do X" where X is more than a one-liner and the approach is already chosen (if it isn't, do awb-research first). DO NOT TRIGGER: a single-line fix (just do it); a bug with an unknown cause (use a debug skill); a pure code review (use awb-review); a question; a larger/higher-stakes build with checkpoints or multi-angle planning (use awb-cook); a spike to discover an unknown interface (build a throwaway slice first, then plan the real change).
In this repository21 other files it gives its agents.
- AGENTS.mdAGENTS.md
- CLAUDE.mdCLAUDE.md
- awb-config-guardSkill
- awb-cookSkill
- awb-dead-code-auditSkill
- awb-debugSkill
- awb-external-refSkill
- awb-handoverSkill
- awb-install-and-verifySkill
- awb-lessons-captureSkill
- awb-optimizeSkill
- awb-output-guardSkill
- awb-researchSkill
- awb-reviewSkill
- awb-session-closeSkill
- awb-stress-testSkill
- awb-tddSkill
- awb-uninstallSkill
- awb-using-skillsSkill
- awb-verify-docsSkill
- prompt-refinerSkill
The file
We split this skill into the rules it gives an agent
2 rules. About 0 are common, 1 is distinctive, and 1 is very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈1
Distinctive · estimate
This author's own choices. Worth a look.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 22
Right-size it: If you could describe the whole diff in one sentence (a typo, a log line, a rename), skip the plan and just do it.
- Very specific: line 61
NOT to do" scope), then hand it to awb-review — or review it adversarially yourself — before committing.
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Plan, then code
Announce on activation: "Using awb-plan-then-code — I'll plan before writing code."
This is a template — the shape of a reliable implementation workflow; adapt it to your stack.
Right-size it. If you could describe the whole diff in one sentence (a typo, a log line, a rename), skip the plan and just do it. Plan when the approach is uncertain, the change spans multiple files, or the code is unfamiliar — a legitimate skip, not the "it's obvious" rationalization the table fights.
Scope
- Does: carry one non-trivial change through scout, one-screen plan, agree, implement, test, hand to review — a single plan and one approval.
- Does NOT: prove the plan correct (the gate catches a wrong approach, not a wrong
detail); enforce anything (a bypassable exemplar, not a binding gate); compare approaches
(
awb-research, first); merge plans or dial checkpoints (awb-cook, the heavier sibling); drive code test-first (awb-tdd); review the finished diff (awb-review). It assumes the approach is already chosen.
Process
- Scout — read the code you'll touch and its neighbours; don't propose changes to code you
haven't read. Stop when you can name every file the change touches and why. If you can't yet
name the files or approach, this is a spike, not a plan-then-code change — build a throwaway
slice to learn the shape, then run this skill on the real change. If Scout reveals the change
is high-stakes — many modules, hard to reverse, or the right approach is genuinely uncertain
across angles — STOP and offer to escalate to
awb-cook(multi-angle planning + checkpoint control), naming it to the user; don't silently absorb a cook-shaped change into one plan. Offer at most once; if declined, proceed here. - Plan — what files change, what each does, and the runnable check that will prove it worked (a test, a build exit code, an output diff). Keep it to a screen.
- GATE: agree the plan before any code. With a user: get an explicit yes — a real gate (a person lifts the hold). Solo: there is no self-approval in Claude Code, so this is a sanity-check pause, not a gate — re-read the plan cold against the Goal and the "decided NOT to do" scope for a contradiction. It does not prove the plan correct.
- Implement — make the change; match the surrounding style; no placeholders or "TODO" stubs. If Implement shows the plan was wrong (an un-Scouted file, a misfit approach), STOP and return to step 3 — a plan that changed under you is an ungated plan.
- Test — add a runnable check that would have caught this change's absence (usually a test; for a config/data/content change, a command output or before/after observation). Run it and show the command and its output — don't assert success. If it fails, fix the code and re-run, or return to step 3 if the plan was wrong; never weaken a check to go green.
- Review — grade the diff against the plan (acceptance met, nothing outside the "decided
NOT to do" scope), then hand it to
awb-review— or review it adversarially yourself — before committing. For a risky plan, runawb-stress-testbefore approving at step 3.
Anti-rationalization
| You'll think | Reality |
| "It's obvious, I'll skip the plan" | If it's obvious, the plan takes 60 seconds and confirms it. If not, the plan just saved you. |
| "I'll add tests after it works" | "After it works" rarely arrives. Write the test that proves it works. |
| "The plan gate is bureaucracy" | The gate is the cheapest place to catch a wrong approach — before any code exists. |
| "The plan changed, I'll just keep going" | A changed plan is an ungated plan — stop and re-confirm before more code. |
Honesty / limits
The plan gate catches a wrong approach cheaply; it does not prove the plan correct or complete, and a green suite proves the checks ran, not that the plan was right. Solo, the gate is a sanity-check pause, not an enforceable approval — only a human lifts a hold. This skill enforces nothing on its own; for a real gate, some harnesses offer a read-only plan mode (in Claude Code, plan mode) that blocks edits until you approve — the skill is the workflow, plan mode is the enforcement, and it works with or without it.
References
references/plan-template.md— a fill-in-the-blanks plan
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

