Designing agentic development workflows: what a workflow is, and what it is made of

What the series is for Give a team an AI coding tool and you have not given them a way of working. Everyone gets the same agent and uses it differently: one engineer explores the codebase before planning, another goes straight to code, a third writes the tests afterwards if at all. The same engineer does it differently on a different day. The phases live in people's heads and get reconstructed from scratch every time, and nothing in the tool knows that your team reviews a plan before implementation, or what this repository's conventions are, or which mistake the last change of this shape made. The attention goes wrong in both directions, too. People sit and watch a model reason through a decision they were never going to argue with, then look away at the one point where their judgment was the only thing that mattered, and find out afterwards that it took a route nobody would have approved. Getting a model to write code is the easy part. The part that needs designing is getting it to do the same thing twice, to stop where you want it to stop, and to leave behind something you can actually review. This series is about how to design that: a family of agentic development workflows, what they are made of, why the pieces are shaped the way they are, what the shape buys, how you know any of it works, how you ship it to other people, and where it still hurts. It comes out of workflows we have designed, built and run on real work. Nothing here is about a particular product or codebase; the claims are about the pattern. How the series is organized | Part | Question it answers | | |---|---|---| | 1 | What a workflow is, and what it is made of | what the thing is, and what a single run looks like | | 2 | The principles | what keeps the shape honest: the machinery, and the doctrine | | 3 | The cost of control | how big an item, how many approvals, which model, and what the whole apparatus buys | | 4 | Is it working, and is it worth it | is the output correct · where does the process hurt · did it deliver | | 5 | Shipping it, porting it, letting it run | packaging, harness portability, and the road to unattended runs | | 6 | Where it hurts, and what to build first | the limitations, and the short list | What we mean by a workflow In software development, "workflow" is a heavily overloaded term. Throw "agentic" in front of it and get two opposite things, so it's worth defining exactly what we mean before building anything around the concept. The distinction that earns its keep is Anthropic's: a workflow is a system where models and tools are orchestrated through predefined code paths, while an agent is a system where the model dynamically directs its own process and tool use. Workflows buy predictability on work you can decompose in advance. Agents buy flexibility on work you cannot. This series is about workflows in that sense, applied to software development. The part worth noticing is that they are not the opposite of agents. They contain them. An agentic development workflow is a named, phased procedure that takes a unit of work from a request to a reviewable result, in which three parties each do what they are good at: - The procedure owns the path. Phases and their order are decided before the run, not chosen by a model halfway through it. - Agents own the judgment inside each phase. What to explore, what the plan should be, whether a review comment is correct. - A human owns specific decisions, named in advance, that the workflow cannot make for itself. None of the three is sufficient alone. A path with no judgment in it is a script, and judgment with no path is a prompt. Figure 1: A fixed order, a file out of every phase, and a person required at exactly two points. The interesting claim is not that a model can write code. It is that a procedure makes a model's work inspectable and interruptible at points you pick in advance, and that something other than the model's own discipline enforces those points. How you build such a procedure is a separate question with several answers, and the one used throughout this series is described below. That combination is what makes the following six properties reliable rather than aspirational. You can ask a bare prompt for most of them, and you will often get them: | Guarantee | Mechanism | |---|---| | A fixed execution path | phases in a declared order, not whatever the model improvises | | Scripts over inference | anything that can be decided deterministically is, and by a script | | Auditable state | every phase writes a file; the whole run is readable afterwards | | Absolute human authority | gates the workflow cannot approve for itself | | Isolation | the work happens somewhere that isn't your working copy | | Right-sized effort | each step runs at a deliberately chosen model and effort | Two of the six are different in kind, not just degree. Absolute human authority cannot come from an instruction, because the thing you would be instructing is the same thing that would have to enforce it. And right-sized effort is decided by how a step is dispatched, so a step cannot ask for it on its own behalf. The other four you can get out of a well-written prompt on a good day. What the workflow adds is getting them on every run, including the bad days. Those six run through everything below. Every later section is really an argument about how to keep one of them true under pressure. The phases come from your development process, not from the tool A development workflow maps a development process the team already follows. Something is requested; someone works out what it means; they decide an approach; somebody agrees to it; it gets built; it gets verified; it goes out for review; the review gets answered; it merges. The workflow does not invent that sequence, it encodes it. Three things follow, and they remove most of the guesswork from designing one: - You transcribe phases, you don't design them. If your process investigates before planning, so does the workflow. The order is not a modeling choice. - Gates go where the process already had a human checkpoint. A plan someone signs off, a review someone performs. Don't invent checkpoints your process doesn't have, and don't quietly drop the ones it does. - The artifacts are the ones the process already produces: a plan, a list of tests, a description of the change, a review. That is why people who never ran the workflow can still review its output. It looks like what they already read. Two more things are worth stating plainly. If your process is implicit, encoding it forces you to write it down. That is often the most valuable side effect of the whole exercise, and usually the hardest part, because the disagreements about how work should flow only surface when someone tries to make them executable. And don't invent a process for the agent. A workflow that follows a sequence nobody actually uses produces output nobody trusts, and its gates land where nobody wants to look. If a phase exists only because the workflow needed a phase there, delete it. This is also why a family of workflows shares a skeleton and diverges in specific places: the underlying process is shared, and the differences are real differences in how the work is done. One approach among several This post describes one way to build an agentic development workflow: an orchestrator skill that drives other skills, with the agent runtime as the execution engine and prose as the control flow. It is not the only shape, and the alternatives are not strawmen: | Approach | Strength | Cost | |---|---|---| | Orchestrator skill (this post) | legible to both the people who own it and the model running it; no build step; any step runnable by hand | prose is a weak way to express control flow | | Code-first orchestration: the flow is a program that calls the model | precise, strongly typed at the seams, testable with ordinary tooling | heavier to change; the logic is opaque to the model itself | | Graph / state-machine frameworks | excellent when the flow genuinely is a graph | overhead when it is a straight line with a few gates | | One instructions file, no phases | the cheapest thing that works, and it often does, for small changes | no gates, no artifacts, nothing to inspect afterwards | | Per-task commands or prompt templates | trivial to write and understand | fine until a task needs several steps to be trustworthy | | Event-driven bots | no human has to start anything | a trigger, not a procedure; it still needs one of the above to run | | Autonomous multi-agent crews | maximum flexibility | minimum auditability, and very hard to gate | The case for prose-orchestrated skills is maintainability: the people who own the process can edit them, not only the people who can modify a program. The price is that prose expresses control flow poorly, which is exactly why every part that has to be deterministic (the loop referee, the seam guards, the gate checks) is a script and not an instruction. Pick by what your team can actually maintain. A precise flow nobody edits is worse than a legible one they do. Local-development first These workflows are local-first by design. They run on a developer's machine, against their checkout (or an isolated working copy beside it), with the developer present at three or four decision points. That is the primary mode, not a stepping stone to tolerate until the infrastructure arrives. Four reasons to be deliberate about it: - The human is the highest-value component at a handful of specific moments: approving a plan, judging whether a review comment is correct, deciding what gets published. In between, almost worthless. Running locally makes those moments cheap to insert. - Failures are visible and cheap. When something goes wrong the developer is right there, the artifacts are on their disk, and they can open them in their normal editor. - Nothing needs to be built first. No queue, no runner, no service account. A workflow is useful on the day it is wri