Every coding agent says done.Checked against what?
manifest-dev makes that check mark a finding instead of a claim. The agent investigates first, you agree in writing on what done means, and nothing is called finished until every criterion has evidence.
It starts building the moment you hit enter.
The request: half my background jobs silently stall. A plain agent doesn't ask what "stall" means. It takes the likeliest guess and starts writing: fast, confident, plausible.
An illustrative example, run two ways.
Then it reports ✓ Done.
Nobody wrote down what done means, so the agent drew its own finish line. That check mark is the agent's claim about its own work. Nobody has checked it.
You've been here. It says done, and the checking becomes your job.
Look closer. Three problems nobody checked for.
The root cause is untouched. The new retries hide the error that would have told you why. And what you needed, the outline on the right, was a different shape.
Built confidently, checked by no one, aimed at the wrong thing.
Next session, it starts from zero.
Nothing it figured out was written down, so the next session works it all out again.
Same request. Same codebase. Run it again.
This time with manifest-dev, in three steps: understand the problem, define what done means, then build and check. Watch how much happens before a single line of code gets written.
/figure-out reads first. It builds nothing yet.
Before writing a line, it reads your code and your logs. Everything you might mean is still out of focus.
That haze turns into questions, the big ones first.
It settles the question that decides the work first, and drops a branch only when the evidence rules it out. "Is the queue overloaded?" Checked. Queue depth stayed flat. Ruled out.
It ends with a Read, and asks you one thing.
The retry wrapper swallows timeouts: 48 of 50 stalled jobs had retried. Run 1 added another retry. Then the one call the code can't make: when a job stalls, retry quietly or fail and alert? That one's yours.
Now you both know what "right" means.
Write down what you'd accept, before anything gets built.
The work splits into Deliverables: pieces you can run and watch work on their own. Not "change the retry wrapper", but "timeouts fail loudly".
Each piece gets a gate it has to pass.
Acceptance Criteria check the outcome, like "a retried timeout still reports the original error". "Wrote some tests" doesn't count. Each one is a ring the work has to pass through.
Plus rules that hold everywhere.
Global Invariants hold across every piece, like "no job is marked done without a result."
Together, that's the Manifest: your definition of done, in a file. You read it and approve it before any code exists.
Now it builds, against the Manifest.
The agent decides how to do the work on its own. It doesn't get to decide on its own what counts as finished.
The same bug Run 1 shipped. This time it's caught.
AC-2.1 fails: the retried timeout still comes back "ok", the exact failure under Run 1's check mark. /do fixes it and checks again from scratch. The agent still makes mistakes. This time a gate was waiting for this one.
Then the rules that cover everything.
No job marked done without a result. The existing suite still green. Checked last, against all the finished work.
Done is a finding, not a claim.
You don't have to take its word for it.
/do can't say done until every gate passes with evidence attached: a command's output, or a separate review against the gate's own text. If it's stuck, it stops and shows you why.
Both runs say done. Only one can show you why.
| Plain agent | manifest-dev | |
|---|---|---|
| Starts by | writing code | reading, then asking the deciding question |
| "Done" means | whatever the agent decided | criteria you approved, written down first |
| A failure is caught by | you, later | a gate, before it reports |
| You're left with | a diff and a claim | a diff, plus evidence for every gate |
Put both under the x-ray.
On the left, the defects that were there all along. On the right, each one had a gate, checked before anyone said done. Gates only cover what you wrote down, which is why /figure-out comes first.
What one run learns, the next one reads.
It's written down where every session looks, so the next one starts from what was decided, not from zero:
- North Star: what the project is becoming.
- Tickets: what's worth doing next.
- Manifests: what done meant, run by run.
The trade, stated plainly.
It spends more tokens and more time up front than prompting directly. It's for developers who'd rather put the effort in before building than review afterwards. If shipping fastest is all that matters, a plain agent fits better.
The bet: time spent understanding and verifying leaves a project better off. It rests on daily use on our own projects, not a measured study.
Same check mark. This one comes with evidence.
Each ring is a gate you approved before any code existed, checked against the finished work. The agent still does the building. Done now means what you agreed it means, and you can see why.
Make your next ✓ mean something.
Type the bug you keep putting off. It reads your code, then asks the question that decides the work. Nothing gets built until you agree on what "right" means.
Want it without the approval stops? /auto <task> chains all three on its own.
github.com/doodledood/manifest-dev · just one skill: npx skills add doodledood/manifest-dev --skill figure-out