Plan before you build.

5.1 Why agents need planning

With agents, the temptation to skip planning is strong. The agent is fast, it can “just get started”, and one big assignment seems to save time. In practice the opposite happens. The larger and more open an assignment, the more decisions the agent makes on its own — and the larger and harder to verify the result becomes.

The reasons are structural:

• Errors compound. An agent works in a loop of reading, acting and observing (Chapter 2). An early wrong assumption feeds into every later step. For a small task the chain is short; for a large one it is long.
• The context fills up. Long runs accumulate files, command output and intermediate states. As the history grows, so do costs and the risk that earlier instructions drop out of view.
• Reviews don't scale. A human reads an 80-line diff thoroughly. A 3,000-line diff gets skimmed. A review that doesn't actually happen is no review.
• Undoing gets expensive. If a small task was implemented wrongly, you discard a branch. If half of a large assignment is wrong, you have to separate good results from bad ones.

With agents, planning is therefore not bureaucratic overhead but the tool you use to control the size of every single decision. The rule of thumb: A task is cut correctly when you can fully judge its result in one review.

5.2 Decomposition: vertical rather than horizontal

There are two fundamental ways to decompose a piece of work.

• Horizontal (by layer): “First the database schema, then all repositories, then all services, then all controllers, then the UI.” Each task is technically homogeneous, but none delivers anything usable on its own. Errors in the interfaces between layers only surface at the very end.
• Vertical (by value): “First ‘create work order’ from database to UI, then ‘list work orders’, then ‘assign work order’.” Each task is a thin end-to-end slice that can be tested end to end.

For agents, vertical decomposition is almost always better. Each task can be backed by a real test, every merge leaves a working system, and architectural deviations show up in the first slice instead of the last. Horizontal tasks remain useful for genuine cross-cutting concerns: a build setup, a migration of the test infrastructure, a security header for all endpoints.

Open full-size graphicOpen full-size graphic

Good slice sizes

A usable task for one agent run typically has these properties:

• a clear goal that can be stated in one sentence,
• a manageable set of affected files or modules,
• two to six acceptance criteria — significantly more suggests the task is too large,
• a result that can be merged without the next task, without breaking anything.

Spikes for the unknown

Sometimes you simply don't know how something works: Which library fits? Does the integration with the legacy system work at all? Then the first task is not an implementation but an investigation (spike) with a clear outcome — such as a short decision note or a throwaway prototype. Only then do you plan the actual implementation. Agents are well suited for spikes, as long as the result is explicitly treated as insight and not as production code.

5.3 Describing a task well

A task is the assignment for exactly one run. It should be described so that an agent can implement it without asking back and a human can verify the result without guesswork. A small, fixed schema has proven itself:

Acceptance criteria per task

The most important element is the acceptance criteria. They turn an intention into something verifiable. Without them, the only question after the run is “Does this look good?” — with them, it is “Is every criterion backed by evidence?”. Good criteria describe observable behaviour, not implementation, and also cover the failure case:

• “When a dispatcher assigns an open order to an active technician, the system shall store the technician on the order and set the status to ‘assigned’.”
• “If the technician is deactivated, then the system shall reject the assignment with an understandable message.”

These are already phrased in the EARS pattern. How to write such criteria systematically, give them IDs and turn them into tests is the topic of Chapter 4. For planning it is enough that every task references the criteria it fulfils instead of rephrasing them slightly differently.

Definition of Done

Acceptance criteria are task-specific. In addition, there are conditions that apply to every task: build green, tests present and green, no new critical findings in the quality gate, documentation updated where necessary. That is the Definition of Done. It belongs in the project, written down once — not copied into every task.

5.4 Dependencies and order

Tasks are rarely completely independent. “List orders” requires “create order”; “close order” needs the assignment. Such relationships form a directed graph: each edge says “B can only start once A is done”. For an order to exist, this graph must contain no cycles — if A depends on B and B on A, neither can ever start. This is called a DAG (directed acyclic graph).

Open full-size graphicOpen full-size graphic

What a dependency graph gives you

• Order: The graph tells you which tasks can start now — all those whose predecessors are done.
• Parallelism: Tasks without mutual dependencies could run at the same time. When that is safe is covered in Chapter 7.
• Risk: Tasks that many others depend on deserve special care. An error there blocks everything behind it.

What “done” means

A seemingly small question with a big impact: Is a task done when the agent has written code? When the build is green? Or only when the result is on the main branch? For dependencies only the last one counts. If B builds on A and A is still on a branch, B works against a state that does not exist on the main branch. “Done” should therefore mean “merged”.

Minimising dependencies

Every dependency constrains the order and lengthens the critical path. Good planning tries to reduce them: with an early, small slice that creates a shared foundation (such as the data model of the core object), with clear interfaces between modules, or with contracts agreed in advance. The latter is the foundation of parallel work in Chapter 7.

5.5 Connecting plan and requirement

A plan describes what gets built next. A requirement describes what must hold. The two are related but not the same: a requirement can be implemented across several tasks, and one task can serve several requirements. If acceptance criteria exist only in the free text of the task, two problems arise:

• Two sources of truth: The task phrases the criterion slightly differently from the requirement. Which version applies?
• No traceability: If the requirement changes, nobody knows which planned tasks are affected.

The solution is to have tasks reference requirements by ID instead of copying them: “This task implements AC-012-03 and AC-012-04 from SPEC-012.” Then there is exactly one wording, and when something changes it is computable which tasks are affected. This is the core of traceability, covered in detail in Chapter 4.

5.6 Milestones and releases

Tasks are the smallest planning unit, milestones the next larger one. A milestone bundles several tasks into a state that means something to users — typically a version. Milestones answer questions that tasks alone cannot:

• What goes into the next version, and what doesn't?
• When is the version finished? (When all assigned tasks are done.)
• What changed compared with the last version? (The changelog.)

A clean release process turns a milestone into three things: a changelog entry summarising the completed tasks, an immutable marker in version control (a Git tag) and, where applicable, a release on the Git host's platform. Immutability is key: a released state is not rewritten after the fact; corrections go into the next version.

Time-based rhythms

Alongside content-driven planning there are time-based rhythms: a weekly planning session, a nightly run that updates dependencies, a regular inventory of technical debt. Such routines can be automated. The boundary is the same as everywhere in this course: automation does not replace the human approval points; it ensures that something verifiable is reliably ready at those points.

5.7 Common planning mistakes

5.8 Summary

• Small, scoped tasks make agent work reliable and verifiable. A task is cut correctly when its result can be fully judged in one review.
• Vertical decomposition delivers testable value with every task; spikes clarify the unknown before implementation.
• Every task has a title, rationale, scope, acceptance criteria and effort; the Definition of Done applies to all of them.
• Dependencies form a cycle-free graph; “done” means “merged”.
• In the factory, a plan run proposes tasks as plans/NNNN-*.md without keeping any code; the backlog manages status, dependencies and spec reference; activating starts a build run; milestones produce a changelog, a tag and optionally a GitHub release; routines and automatic follow-up suggestions close the loop.

Chapter questions

1. Name three structural reasons why agents work more reliably with small tasks than with large ones.

   Model answer

   Errors compound in the agent loop — with small tasks the chain is short. In long runs the context fills up with intermediate states, which increases costs and the risk of overlooking earlier instructions. Reviews don't scale: small diffs get checked thoroughly, large ones get skimmed. In addition, discarding a small, wrong task is cheap.

2. What is the difference between vertical and horizontal decomposition, and when does horizontal still make sense?

   Model answer

   Horizontal slices by technical layer (first all database tables, then all services …), vertical by value (one use case through all layers). Vertical tasks can be tested and merged individually and expose interface errors early. Horizontal makes sense for genuine cross-cutting concerns such as build setup, test infrastructure or a security header for all endpoints.

3. How do acceptance criteria differ from the Definition of Done?

   Model answer

   Acceptance criteria are task-specific and describe observable behaviour that this task must deliver. The Definition of Done is the same for every task and describes the hand-over state (build green, tests present, gate without critical findings, docs updated). In the factory, the Definition of Done lives in the project as DEFINITION_OF_DONE.md.

4. What happens in the factory at the end of a plan run if the agent, contrary to the directive, also changed a Java file?

   Model answer

   At the end of a plan run the factory commits only the files under plans/ and discards all other changes. The Java change therefore does not end up in the workspace state. No build gate runs for a plan run; the plans are indexed as backlog items and the run is completed.

5. Why should a task only count as done once it is merged, and how does the factory implement this?

   Model answer

   Dependent tasks build on the main branch. If the groundwork is only on a branch, the follow-up task works against a state that doesn't exist there. The factory automatically sets a backlog item to DONE only when its build run has been merged (in PR mode only with PR feedback enabled; otherwise opening the PR already counts); an item with an unfinished blocker cannot be activated.

6. You try to enter item A as a blocker of item B, although B is already (via C) a blocker of A. What happens, and why does that make sense?

   Model answer

   The factory rejects the dependency, pointing out that it would create a cycle; it also checks indirect cycles. This makes sense because in a cyclic dependency graph none of the tasks involved could ever be activated — there would be no valid order.

7. A project is in spec mode STRENG. A plan run produces a plan with Spec: SPEC-004 and AC: AC-004-07, but SPEC-004 only has a draft. What does the backlog show, and what happens on activation?

   Model answer

   The backlog shows a warning on the item that the spec has no approved version. In mode STRENG the factory refuses activation until a version of SPEC-004 that contains AC-004-07 is approved. In mode LEICHT it would only be a warning; the build run would then run without spec binding.

8. Why is it better for a plan to reference acceptance criteria by ID instead of repeating them in free text?

   Model answer

   There is then only one binding wording (in the spec) instead of two that can drift apart. In addition, it is computable which tasks are affected by a change to the requirement, and the chain can be traced into commits, tests and the why-trace.

9. Your team wants “the factory to simply keep working every night”. Which building blocks would you combine, and what precautions do you take?

   Model answer

   A routine (/projects/{id}/routines) with a cron expression, such as a nightly plan run, possibly complemented by automatic follow-up suggestions (run.auto-followup-plan) after successful build runs. Precautions: set budgets or token limits, keep approval points (before execution, before merge) active so that nothing gets merged unreviewed, and schedule fixed time for reviewing the backlog. Use BUILD routines only with a clearly scoped focus, because they produce code without plan approval.

10. What does the factory produce when a milestone is released, and what is different if no GitHub remote is set?

    Model answer

    It generates a changelog section from the milestone's completed items in the workspace's CHANGELOG.md, commits it and sets a Git tag v<target version>; the milestone moves to RELEASED. With a GitHub remote and token it pushes the tag and additionally creates a GitHub release. Without a remote it stays with a local tag and changelog.