sherpa
Guides for building and shipping real software with a coding agent.
##harness
Most people struggling with a coding agent are not struggling with the model. They are struggling because nothing in the loop can tell the difference between done and claimed done.
harness closes that gap. The agent has to prove its own checks actually
work before it trusts them, and it cannot ship to production without asking you first. It
came out of shipping several products with an agent, and every rule in it was learned by
something going wrong first.
Things you have probably said out loud
If you cannot read the diff yourself, you are relying entirely on the agent being straight with you about what it did. These are the moments where that breaks.
What it adds
Five skills, and they load when the work matches rather than all at once.
The idea in one line
Four separate checks in the source project shipped green while checking nothing. One
compiled zero files, one walked only an entrypoint's imports, one silently stopped comparing
because it never stripped ANSI codes, and one matched a renamed export and passed with an
empty list. Each of them was believed for weeks. So the first thing the gate
skill tells you to do is plant the exact error the gate exists to catch and watch it fail.
The same goes for a fix. Do not call it done because you applied it. Re-run the check, and when it comes back empty then it is done.
##The working skeleton
The rules are only half of it. HARNESS.md also carries a project skeleton that runs, and one command writes the whole thing. It is generated from a tree that passed both gates and every gate-proof, so it is the code that actually worked rather than a description of it.
backend
the gates
frontend & shared
The marked files are the ones that cannot be retrofitted later. Tenancy and provenance touch every table written after them, and the agent loop decides what a skill is even allowed to do.
The phase order it expects
Phase 1 is the one people skip and the only one that cannot be added later. Phase 6 is the one people cut, and then nobody can say whether the thing works.
##Gates that prove themselves
The skeleton ships with a script that plants the exact error each gate exists to catch and confirms every one goes red. Run it when you write a gate, and again after you touch one.
If one of them passes, the script says ✗ PASSED — the gate is decoration and tells you to fix it before you trust a green build.
HARNESS.md
The plugin ships with HARNESS.md, which is the full source document the skills are derived from. It is long and that is deliberate, because the skills are the rules and HARNESS.md is why, with the failure behind each one.
On the stack
HARNESS.md commits to a specific stack and that is deliberate, because every trap in it is mapped for that exact combination, which is what makes a runbook worth anything.
The protocol does not depend on it. The seven artefacts, the phase order, proving gates, the ship discipline and the symptom table all work anywhere. Read the stack sections as a worked example of what a mature rule set looks like once somebody has paid for it, and not as a requirement.
Make it yours
The rules here are ones somebody else earned. You will respect the ones you earn yourself far more, so the most important habit in the whole document is also the smallest one.
Anything that cost more than ten minutes goes into your standing rules in the same session.
Every trap in HARNESS.md was learned twice, because it was not written down the first time.
##Contributing
The most useful thing you can send is something that looked like it worked and didn't.
Every rule here was learned by something going wrong first, and a rule with no failure behind it is just a preference, which is what people delete when they are in a hurry. So symptom → cause entries are the contributions that make this better.
There is an issue template with three fields, which are the symptom, the cause, and how you found it. The third one matters most, because how you found it is reusable even when the specific bug is not.
##License
Apache-2.0. Permissive, so use it, fork it, and adapt it commercially. Keep the attribution, and if you modify and redistribute it then say what you changed.