How to write a plan an AI agent can deliver without guessing

Where the guessing comes from

A coding agent reads code, runs commands and edits files. But it doesn’t know what the team agreed in a meeting, what the client doesn’t want, or which of two reasonable paths you prefer. When an agent builds something other than what you expect, it is usually missing exactly that kind of information. An agent may also read a request conservatively and build the smallest version that satisfies it, because it doesn’t know how much you are hoping for.

The second gap is at the end of the work. An agent usually stops when the result looks finished. If there is nothing to run to check that it really is finished, a mistake stays in the code until you notice it.

Take the task “Add CSV export for invoices”. It sounds clear until the agent gets to work:

• All invoices, or just those from a selected month?
• With credit notes or without them?
• Which field separator, and how are amounts written?
• Should it fix the existing PDF export while it’s at it?

The agent will settle each of these questions its own way, or ask you about it while it works. A good plan settles them before the work begins.

Four parts of a plan

A plan for an agent doesn’t have to be long. It has to answer four questions: why, what exactly, how to recognize a good result, and when the work is finished. When the sequence matters, add the steps as well.

Spec-driven development means working from a specification: the document comes before the agent’s work, and at the end the result is checked against that same document. A plan with the four parts described below is just such a specification. You’ll find more about this approach in the glossary entry spec-driven development.

Goal

Why the work is needed, in one or two sentences. When the agent runs into a decision the plan didn’t foresee, the goal tells it which option to pick. The sentence “Every month, the accounting team retypes the invoices into their own software by hand” tells the agent more than “CSV export”.

Scope

What is part of the work and what is explicitly left out. What is left out matters as much as what is in. The sentence “The PDF export stays unchanged” guards against changes made along the way, and “Credit notes go into the file too” against a version that does too little.

Acceptance criteria

Verifiable statements that must hold when the work is finished. You judge each one with a single word: yes or no. They are what you compare the result with at acceptance, so write them like a checklist.

Definition of done

How whoever does the work will know it is finished and nothing is left to complete. Acceptance criteria apply to this one piece of work, while a definition of done is usually shared by many pieces of work, for example: the tests pass, the new behavior has its own test, the documentation is up to date.

Put a command here that the agent can run itself and that ends in success or failure: the tests, the project build or a linter, for example npm test. The agent can then make the change, run the check, and when something breaks, fix it and check again.

Example: a plan for the invoice export

The same export, described so that the agent can deliver it without having to ask:

# Export invoices to CSV

## Goal
Every month, the accounting team retypes the invoices into
their own software by hand. A CSV file should replace this.

## Scope
- An export button on the invoice list, for a selected month.
- Out of scope: PDF export and sending the file by email.

## Acceptance criteria
- The file starts with a row of column names.
- The file includes every invoice of the month, credit
  notes included.
- Fields are separated by semicolons, and amounts use
  a decimal comma.
- When the month has no invoices, the user sees a message
  instead of an empty file.

## Definition of done
- npm test passes, and the export has its own tests.
- Nothing in scope has been put off for later.

How to write criteria you can check

Criteria are the part of a plan that is easiest to write too vaguely. Four rules help:

• One statement, one check. “The export works correctly” doesn’t say what to check. “The file includes credit notes” does.
• Behavior you can see. Describe what the user will see or what the program will return, not what the code should look like.
• A number instead of an adjective. Everyone reads “fast” differently. “Exporting a month with a thousand invoices takes less than five seconds” can be measured.
• The edge cases you care about. An empty month, bad data, missing permissions. The agent may skip a case you don’t write down, or handle it differently from what you expect.

Open decisions and the size of a plan

Not everything is clear before the start, and that is fine as long as the plan says so. When a choice remains, name it and give a recommendation, for example: “File encoding: UTF-8, unless the accounting software needs a different one.” The agent then won’t settle it quietly, and you know what to look at during acceptance. The same goes for two good solutions: if you prefer one of them, say so in the plan.

When you are missing most of the answers, reverse the order: ask the agent to keep asking you questions until the answers are enough to write a specification. Then start work on the code in a new session, from the finished document.

The last thing is size. A plan should describe work that one agent session delivers whole. Split a large task into several plans and write down which waits on which. Each then gets its own criteria and its own acceptance.

Why fewer questions and less rework

The agent’s questions come up where the plan is silent. Every decision written down before the start is a question that won’t interrupt the work. Rework comes from expectations nobody wrote down: the result does what was asked but misses what you need.

Acceptance criteria turn acceptance into a comparison. You go through the list point by point, and if something doesn’t match, you point to the exact criterion when you reject the work. The agent then knows what to fix and doesn’t have to guess a second time.

How it works in featureloom

In featureloom, a task for an agent is a plan: a markdown document on a kanban board that the console receives whole. You write a plan yourself with the New plan button. Such a plan starts from an empty document, so you type the goal, scope, acceptance criteria and definition of done under your own headings, as in the example above.

A plan generated from material or written by an agent in a console follows the project’s plan template. The built-in template asks, among other things, for the goal, scope, steps, acceptance criteria and definition of done. The Planner prompt tells the agent to write plans in the template’s sections and, when the material leaves a choice, to name it in the plan with a recommendation. You save your own template on the Project settings screen, in the Plan template tab.

You hand a finished plan to the agent by pasting the command from the plan into the console, for example featureloom realizer INV-14. In one call, the agent gets the prompt, the whole plan document and the documents of the delivered plans this plan directly depends on. The Realizer prompt tells it to do what the plan says and nothing more and, when the plan leaves something open, to ask a question instead of guessing. The question and your answer stay in the plan document, and the agent reads the answer when it fetches the plan again.

At the end, the Realizer prompt tells the agent to report the plan delivered with a note: what was done, what was done differently from the plan and why, and what was not done. You compare the result with the acceptance criteria and, in the Acceptance section, choose Accept or Do not accept. The verdict is always given by a person, in the app. After a rejection, the agent reads the verdict with your reasons and goes back to rework.