Manifest-driven development: press the problem until it is understood, write down what you would accept as a Manifest of deliverables with verifiable criteria, then let the agent build and check every criterion against evidence. Above the task, a North Star and a Ticket store hold the project's direction and queue.
See the same request run by a plain agent and by Manifest Dev in the interactive explainer.
The loop, in one picture
The idea: stop asking how to make the agent implement correctly. Ask what would make you accept the result, write that down, and check it.
Three skills, run in order, though each is useful on its own. The picture shows the workflow as it runs: the third skill cannot report done until every criterion holds evidence, and the escalate exit exists because some blockers need a person.
- /figure-outUnderstandemits a Read
A named conclusion with its confidence, the evidence it rests on, and what would overturn it.
- /defineWrite down doneemits a Manifest
Deliverables, each with acceptance criteria, plus the invariants that hold across all of them.
- /doBuild and proveemits evidence per gate
Implements, then checks every criterion against evidence before it may report done.
- all passdone, with evidence
- any failfix, then re-verify
- blockedescalate to a person
/figure-out produces understanding. /define turns it into a Manifest, the written acceptance contract for one run. /do builds against the Manifest and evaluates every criterion before it may say anything is finished. If you take one thing from this post, take the order. Understanding is the part the other two depend on.
Understanding first, with /figure-out
The failures that cost me the most over the past year were not bad code. They were correct code for the wrong problem. The agent takes a request shaped like a solution, builds exactly that, verifies it, and reports done, and the thing it built was never what the situation needed. No amount of verification catches that, because every check passes. The defect was upstream, in a question nobody asked.
/figure-out is that question, asked relentlessly. Four things it does that set it apart from a planning prompt:
- It reads your code before it says anything.
- When a topic arrives already shaped as a solution, it finds the problem the solution is supposed to serve and puts the stated solution back in the pool as one candidate among others, including doing nothing.
- It classifies a constraint before letting it prune options: is this hard, or is it a habit wearing a rule's clothes? And it says of every claim whether it verified it, inferred it, or is carrying it unchecked.
- It holds a position under pushback and drops it on evidence, never on insistence. That is the behavior I want from a colleague and rarely get from a model by default.
The Read it hands over
What it hands over is a Read: a named conclusion, a confidence, the evidence it rests on, and what would overturn it. /define starts from that Read. One more thing it does that I did not expect to matter this much: when the read implies making something, it states exactly what the thing will be and offers to render a disposable draft, because two people agreeing on a sentence are usually picturing two different artifacts.
Verification cannot catch the wrong problem. Understanding comes first.
The 2026-07-05 decision record in the manifest-dev repository fronts /figure-out as the entry point on every discovery surface, with the define-and-do loop as what it opens into.
The Manifest and the shape of a gate
A Manifest is the acceptance contract for one run: the thing you would accept as "I'd ship the outcome of executing this." It has six sections:
- Intent states the problem as a specific story of what breaks today, the appetite (how big a change the problem is worth, as a bound on complexity and surface, not time), and what is out of bounds.
- Initial Approach, written only for complex work, is a starting direction the executor may depart from.
- Global Invariants are rules that hold across the whole run.
- Process Guidance is advice on how to work; the executor weighs it and may depart from it.
- Known Assumptions record what was decided by default and what it costs if wrong.
- Deliverables are the slices of work, each with its Acceptance Criteria.
Two words in that list carry the weight. A Deliverable is a slice you can finish on its own and exercise end to end, put in front of its real use, so its criteria can judge whether it works. "The data model" is not a Deliverable; "a login round trip from the browser to a protected page" is. An Acceptance Criterion is a gate: one text, read by you and by the evaluator alike.
A gate is one text
A gate is a title, a body, an optional why, and a declared kind, deterministic or judgment, and the body has to say what done means, what evidence settles it, and where the line between PASS and FAIL falls, precisely enough that two evaluations read the same thing. Here are two from the Manifest this post was written under.
INV-G4No hype, no capture, no topic beat, no em dashes
Read the rewritten post, the new components' copy, the project card text, and the card images. FAIL if any of them contains a hype register (superlatives such as "revolutionary", "game-changing", "10x", "the only tool you'll need", or any promise of what an agent cannot reliably do), a newsletter, subscribe, or follow gate, a stated list of subject areas or a topic beat for the site, or an em dash or en dash character (U+2014, U+2013) anywhere in the post body, component copy, or image copy. Code blocks quoting manifest-dev's own text verbatim are exempt from the dash rule only where the quoted source contains it.
Why: the site's Nevers and the human-voice register the post is graded in both forbid these, and the dash rule is the cheapest AI tell to lose.
Deterministic gate.
AC-1.2The post reads as human-voiced writing
Done when the manifest-dev:review-writing skill, activated with register=voice over content/blog/manifest-driven-development.mdx (prose and component string props; ignore import lines and JSX syntax), reports no MEDIUM-or-higher finding.
Judgment gate.
The kind matters because it decides how the gate re-verifies. A deterministic gate takes its verdict from a command that returns the same result for the same artifact, so it re-runs in full whenever it is eligible. A judgment gate is a model's judgment over an open space of findings, so a fresh look can turn up things the last one did not. /do reads the full change once for such a gate and afterwards judges only whether the prior findings were repaired and whether the delta introduced anything new. Without that ratchet, every round of repairs re-opens every judgment gate, and the run never converges.
The scope limit
Every Manifest includes a scope limit: the change stops at what it authorized. This prevents the verification loop from expanding into work the user did not request.
Execution and verification with /do
/do works through the Deliverables and checks every criterion and invariant against evidence. Each gate declares its kind. A deterministic gate reruns its check in full; a judgment gate reads the whole change once, then checks repairs and new changes in later rounds.
The executor now judges the gates itself. This is cheaper and simpler than launching a separate evaluator for each gate, but it gives up independent verification. For consequential changes, I still need a separate review if that independence matters.
The run repairs failed gates and verifies again. When outside intervention is required and no useful independent work remains, it invokes /escalate. It may report done only when every gate has current evidence; a summary claim is not evidence.
The Manifest is read-only to the run
The Manifest itself is read-only to the executor. A gate's text changes through /define, not by editing it during /do; a changed gate returns unverified. Feedback you give mid-run amends the Manifest first, so the contract still describes what the code is being held to after you steer.
My own rule: resist jumping in mid-run. It will not get everything right on the first pass. The verify loop is there precisely for that, and every time I have interrupted it, I have paid for the context I broke.
Three surfaces at three lifetimes
Until August 2026 the unit manifest-dev served was the task. One Manifest, one run, one diff. Then I counted a month of my own decision records and found that half of them sat above any single task: what the project was trying to become, what was worth doing next, what a stranger would need to pick up a piece of work. Those questions were living in whoever happened to be at the keyboard, and every session re-derived them from scratch. The agent's speed was multiplying work nobody could tell was worth doing.
So the unit moved from the task to the project. A Manifest is now one of three surfaces, each at its own lifetime, each making the one below it decidable.
- What is this project becoming?A North Star, in the repostands until the owner changes it/init-context
- What is worth doing next?A Ticket, in the tracker or in filesas long as that piece of work/ticket-up
- What does done mean here?A Manifest, written per runresets every run/define
The North Star
The North Star is the standing direction: what the project is for, who it serves, what winning means, what it will never do. It informs every session and binds nothing on its own; the one binding route is /define turning an unsafe "never" into a Global Invariant. Each position in it carries a state (evidence, hypothesis, ruled, or empty) and a date, and positions move only on the owner's ruling, recorded as a decision record. /init-context installs one, along with a glossary and decision-record conventions, seeding them from the project's own history where there is any.
The Ticket
A Ticket is a self-sufficient prose work packet: everything a stranger, person or agent, needs to pick a piece of work up, do it, and judge it done. /ticket-up writes them, from a finished Manifest, a direct request, or an open question. /next-ticket reads the store and claims the one worth doing now. /run-ticket takes one exact Ticket end to end, and a scheduled /sweep-tickets picks up or resumes a single unattended one. A Ticket may carry an Auto grant, an opt-in saying unattended automation may take it all the way; absent the grant, automation leaves it alone entirely.
The bar I hold the whole thing to now is the one written into the project's own North Star:
“I can give the agent a complex task and trust the output enough to ship it with minimal review, and come back to the project weeks later and find it still knows what it's becoming, what's next, and what done means.”
Source: manifest-dev NORTH_STAR.md, the Promise, as of 2026-09-02; one dash rendered as a comma
Spec-driven development with Claude Code, and what a Manifest adds
If you have tried spec-driven development with Claude Code, through Spec Kit, OpenSpec, Kiro, or a /spec command of your own, the family resemblance to this is real. The tools I have looked at, as of September 2026, run the same four beats: requirements, design, tasks, execute, with the spec kept beside the code as a source of truth. That gets you a written agreement before any code exists, a real improvement over prompting and hoping. It stops at two places I could not live with.
Verification against an explicit acceptance contract
The first is verification. A spec says what the system should do; a Manifest states what evidence would make you accept this run. /do checks every criterion against that evidence before reporting done. The current executor judges its own work, so the contract and evidence are explicit, but the judgment is not independent.
What gets kept after the run
The second is what gets kept. Spec-driven development, at least in its spec-anchored and spec-as-source forms, keeps the spec alive as a second description of the system. Two documents that describe the same system will disagree, and I would rather not maintain the one that cannot be executed. A Manifest is disposable by design: it drives one run, and then the code is the source of truth. What manifest-driven development keeps instead sits above the task, in the North Star and the Ticket store, and those hold direction and a queue. Neither describes the system.
The step before the spec
And one step comes before either. A spec written from a misunderstood problem is a very precise description of the wrong thing. That is why /figure-out sits at the front of the loop as a required step. The spec is the middle of the loop. The two ends are where the wins are.
What it costs, and what is not proven
As of September 2026, this costs more tokens and more up-front work than prompting directly. Manifest Dev now ships one skill per beat: /figure-out, /define, and /do, with /auto to chain them. Their shorter prompts reduce the cost of carrying the workflow, while /do's own gate judgments reduce the cost of verification and its independence. If you optimize only for cost or speed, this is still more process than a direct prompt.
What is not proven
What you get back, in my experience: a first pass that lands closer to done, and a result you can check. I say "in my experience" deliberately. The core claim, that spending more up front on understanding, on what is worth doing next, and on what done means leaves a project better off than moving faster without it, is recorded in the tool's own North Star as a hypothesis with strong lived support across my projects and no measurement beyond them. Nobody but me has yet run all three surfaces on a project of theirs. That is the open question the project carries, and this post carries it in the open.
Things that still go wrong, so you know what to watch for:
- a gate written to pin a mechanism instead of an outcome; it costs an amendment cycle the moment the run legitimately pivots;
- a threshold set higher than it returns, where each round's findings are real, smaller than the last, and cheaper to leave than to re-verify.
The executor can amend a mechanism-pinned gate through /define within its authority. An unresolved blocker goes to a person when independent work is exhausted.
Who this is forand who it is not
Developers who already drive an agentic coding CLI, who work solo or in a small team, and who will spend tokens and up-front effort for output they can trust. Not for cost optimizers, speed-first shippers, people who want to tweak every knob, or anyone not using a coding agent at all. That is the tool's own stated audience, and it matches me; no user beyond the maintainer has confirmed the segment.
Where it runs
Claude Code is the primary target. The same skills ship as generated distributions for Codex CLI, Pi, and OpenCode, and any single skill installs into many other agents on its own. The install commands below are copied from the repository's READMEs on the date shown; if they have moved, the repository is right and this page is stale.
- Claude Codeprimary target; the core plugin
/plugin marketplace add doodledood/manifest-dev/plugin install manifest-dev@manifest-dev
- Codex CLIplugin-native install
codex plugin marketplace add doodledood/manifest-devcodex plugin add manifest-dev@manifest-dev
- Piinstalls from git
pi install git:github.com/doodledood/manifest-dev@main - OpenCodeclone, then add the plugin path to your config
git clone https://github.com/doodledood/manifest-dev - Any agent, one skillthe understanding step on its own
npx skills add doodledood/manifest-dev --skill figure-out
Start with /figure-out on something you are about to ask an agent to build. It is the plain entry to the method: nothing gets built until you both know what right means here. Then write down what you would accept, and let the loop run.
Frequently Asked Questions
What is manifest-driven development?
Manifest-driven development is a way of working with coding agents where the agent first reaches shared understanding of the problem, then encodes what you would accept as a Manifest of deliverables with verifiable acceptance criteria and global invariants, then builds against that Manifest and checks every criterion against evidence before it may report done. The Manifest is disposable: it drives one run, and the code is the source of truth afterwards. Above the task, a North Star and a Ticket store carry the project's direction and its queue of work.
How is manifest-driven development different from spec-driven development?
Spec-driven development with Claude Code, through Spec Kit, OpenSpec, Kiro, or a custom command, writes requirements, design, and tasks before code and keeps the spec beside the code as a source of truth. Manifest-driven development starts by understanding the problem and ends by checking every acceptance criterion against evidence. A Manifest is a per-run acceptance contract that is thrown away when the run completes, so there is no second document to drift from the code; what is kept instead is a North Star and a Ticket store, which hold direction and a queue and never describe the system.
Why does /figure-out come before /define?
Verification cannot catch the wrong problem: correct code for a misunderstood request passes every check. /figure-out reads the code, finds the problem behind a solution-shaped request, keeps doing nothing in the option set, and produces a Read with a conclusion, a confidence, its evidence, and what would overturn it. /define then encodes that understanding rather than re-investigating it.
What does /do check before it says done?
Every Acceptance Criterion and Global Invariant in the Manifest. A deterministic gate reruns its check in full; a judgment gate reads the change once, then checks repairs and new changes. The executor judges its own gates, so independent review is a separate step when needed. Every gate needs current evidence before /do reports done; unresolved blockers go to /escalate when no useful independent work remains.
Which tools does manifest-dev run on?
Claude Code is the primary target, installed through its plugin marketplace. Generated distributions ship for Codex CLI, Pi, and OpenCode, and any single skill installs into many other agents with npx skills add doodledood/manifest-dev --skill <name>. Commands are as of September 2026; the repository README is the current source.