The plan is where the work lives

Knowledge-driven development is an experiment of mine, and it isn't battle-tested yet. Part 1 says where it started.

Here is the entire prompt I give a planning agent when I want a feature built:

Plan how to implement this feature, and write it up using knowledge-driven development.

It goes to a top-tier model at high effort, with whatever description of the feature I've got. That's usually a paragraph. Sometimes it's a sentence. I've written longer commit messages.

What comes back is the documentation of the system as it will be once the feature exists, written in the present tense, with almost every new sentence marked ⚠️. That's the plan.

It's also the best way I've found to keep a fleet of agents pointed in the same direction.

---

1. What the planning agent writes

The agent doesn't produce a list of steps. It edits the documents that already describe the system, or creates the ones that should exist, and describes the feature in them.

• The feature document gets a section describing the new capability from the point of view of whoever will use it, statement by statement, each one ⚠️.
• The user journeys that pass through the feature get new steps, each one ⚠️.
• The subsystem documents get the new ways things can fail: what goes wrong, what it looks like from the outside, and what an operator does about it. All ⚠️.
• The API contract gets the new operations, with their request and response shapes, each one marked ⚠️.

If something can't be built from where we are (it needs a decision from someone outside, a piece of hardware that isn't on my desk, a third party that hasn't shipped), the agent writes it as ⚠️⛔ and says what would unblock it. That's how blockers reach me: as a sentence in the document that owns them.

The quality bar for those ⚠️ paragraphs is that an agent can build from them without asking much. They don't need to be perfect. The agent is fast, and I can review what it built fairly quickly afterwards and correct its direction.

2. What the work orders used to be

I didn't always do it this way. Until recently I had agents write plans as work orders for the fleet: a list of self-contained steps, each with its own definition of done, with the parallel steps marked and the riskiest step first.

They worked. They were also a second map.

A work order describes a sequence of changes. Once the changes are made, it describes nothing. It becomes a historical document about a plan, sitting next to a system that has since moved on. The next agent to touch the feature doesn't read it, because nothing points to it, and if it did read it, the work order would tell it what someone intended three weeks ago, not what's true now.

A knowledge-driven plan doesn't expire, because it's the description of the system, and implementing it means making its sentences true. When the last ⚠️ in a feature turns into ✅, nothing gets archived. The plan is the documentation now, which is what it was all along.

The work orders are gone. I don't miss them.

3. What the implementing agents do

Every agent that comes after the planner treats the design documents as its primary guidance, ahead of my original paragraph, the chat history or any ticket.

That works because of how the documents reach the agents. The implementing agents are handed the documents the planner wrote, and the repository's agent instructions tell every agent to read the documents about whatever it's changing. Nobody has to remember to point the agent at them.

An implementing agent works like a Mars rover. When NASA's Spirit and Opportunity had no attitude estimate worth trusting, they worked one out from scratch: the accelerometers told them which way was down, and a camera searched the sky for the sun to tell them which way they were facing. Perseverance drives the same way. It keeps imaging the terrain around it, maps it, and chooses its own path to the destination, around whatever rocks it finds.

None of them needs the story so far. They look around, work out where they are, and go. My agents start from the same nothing. They don't need the chat history, the plan so far or my original paragraph. They read the documents, find the ⚠️ marks, and start building. It works brilliantly.

The one rule they must follow is that the mark moves in the same commit as the code: shipping a capability turns its ⚠️ into ✅ in the same pull request.

Defects don't come out of the commits. They turn up in user testing, or arrive in a chat message, an email, an Asana task or a phone call. More and more often I find them myself, because my systems have good observability: I ask an agent what went wrong since yesterday, and then I tell it to fix it. Wherever a defect comes from, the usual answer is the same. Claude diagnoses it and fixes it, and the defect is gone before anyone thinks of writing it down. Defects are short-lived in an AI-driven world, tokens allowing.

When a fix has to wait, I ask Claude to update the knowledge documents instead. That's what a ❌ is for: a known defect that's still there.

This also means the implementing agents can be cheaper than the planner. The planner did the judgment: what the feature is, where it belongs, how it fails. The implementers are translating well-specified sentences into code and tests, and that's work a smaller model at lower effort does well.

4. The backlog and the sprint board

I don't have a separate backlog. My project manager does have a sprint board, and I keep it up to date. Well, Claude does. But it's a second map, and however well it's kept, it's never going to be a holistic picture of what's actually going on in the code base.

My own sprint board is a grep that Claude runs for me. The backlog is every ⚠️ in the repository. The sprint is the ⚠️ marks in the documents the planning agent just wrote. Progress is the count of those marks going down. Something blocked is ⚠️⛔ and says what it's waiting on. A defect that's waiting for a fix is a ❌, in the place the defect lives.

grep -rn '⚠️' documentation/Features/my-new-feature.md

It updates itself in the same commits as the code, which is more than anyone can say for the other one.

5. How I review

A feature pull request built by agents can easily be two thousand lines of code and tests. I can't review two thousand lines of anything with any real attention, and nobody else can either, whatever they put in their performance review.

So I don't start there. I start with two short things: the delta to the knowledge files, and the change logs.

That diff is usually short. Twenty lines, maybe forty. It tells me, in plain sentences, what the agent claims to have done: these ⚠️ became ✅, this ❌ is a defect left for later, this one is now ⚠️⛔ and says what it's waiting on. Every mark that moved is a claim, and every claim names the behavior it's about.

The change logs come from a rule my agents follow: every prompt that changes the code base gets a change log file. It says what I asked for and how the agent interpreted it, and, where it matters, what the change needs: how to test it, data to migrate, compatibility issues. I read those carefully, because they tell me whether the agent misunderstood me.

In a forest of agent-made changes, those two are the most concise way I know to see what a pull request thinks it's changing. Sometimes that's enough to show that the agent got me wrong. One decided to write a data migration for something I could have done by opening a web page and toggling a feature flag.

Then the claims get checked, because a ✅ means someone read the code and saw the tests pass, and agents report success the way a teenager reports that their room is clean.

I don't check them myself. That would be too much work. I ask another agent to do it.

Sending one teenager to inspect another teenager's room sounds like a terrible idea. It works because this one has never met the first one.

Every pull request that ships a capability carries a documentation hunk. That's a feature: it's the only part of the diff written for the reviewer. A pull request that changes behavior and moves no mark is either not visible to anyone, or has left the documentation lying. Either way, it's the first question the review asks.

Reading the knowledge delta and the change logs first turns review from reading two thousand lines of code and guessing what they were for, into reading a few dozen lines of claims and intent, and handing the checking to an agent. That's a job I can actually do.

---

The plan isn't a document that gets written and forgotten. It's where the work lives.