DevSpark Roadmaps: Planning Before the Agent Builds

An Agent Can Build the Wrong Thing Very Quickly

An agent will implement a poorly chosen feature with exactly the same enthusiasm it brings to a good one. It doesn't stop to ask whether the ticket describes the right outcome, whether the thing it depends on actually exists yet, or whether the result will be useful on its own or only after three follow-up projects nobody has started. Faster code generation makes that problem cheaper per line and more expensive in total.

Back in August I wrote that planning was the stage agentic development hadn't shifted left yet. Testing moved earlier, security moved earlier, and code got cheap, but the decision about what code deserves to exist was still happening in someone's head or not at all. Writing that was the easy part. Building it into DevSpark without turning it into a new bureaucracy was harder, and version 9.5.0 is my first real attempt.

This is what I built, where I drew the lines, and what broke when I went looking.

Shift the Reasoning, Not the Paperwork

The thing I was most worried about was rebuilding the process I had just torn down. DevSpark 9.4 simplified the delivery flow on purpose, and I didn't want to rebuild a mandatory specification pipeline around it. I had already written about the spec scope-creep spiral and did not want a roadmap to become the next gate everyone learns to route around.

So the roadmap is optional. I can start work, fix a defect, run an experiment, or cut a release with no roadmap at all. If the planning directory doesn't exist, the checker reports that it isn't present and everything is fine, and it creates nothing. A roadmap is an aid to choosing and shaping work. It is not a permission slip for doing it.

What /devspark-roadmap adds is a bounded role for the agent before implementation. It can help me establish direction and a factual baseline for the application, propose future outcomes and judge whether they are sized sensibly, look at dependencies and compatibility, suggest which items are dependency-unblocked, and compare what the plan claims against what the repository actually shows.

The records are plain Markdown. By default they live under .devspark.work/roadmap/, and a repository can point roadmap.root somewhere else, including a shared planning folder outside the application repo. The command will not go wandering into neighboring repositories and assume it's allowed to write there.

Dividing Outcomes Instead of Tasks

The center of the design is something I called a Prospective Spec, or PS. The name is deliberate. It is prospective because it describes something that might get built, and it leaves out the implementation detail of a real spec: no file-by-file plan, no task list, no test inventory. Those belong to delivery, when the agent can work against what the code looks like that day rather than what it looked like when the plan was written.

The line in the template that I keep coming back to is this one:

Tasks divide implementation work. Prospective Specs divide deliverable outcomes.

The sizing test I wrote into the command is the most useful thing in the feature, and it's simple enough to use without the tool. Imagine finishing this increment and then canceling every later item on the roadmap. Is the application still healthy, complete and releasable?

That question catches the two mistakes I have watched plans make for most of my career. An increment can be too small: an endpoint, a migration, or a fragment of UI that can't deliver anything until unfinished follow-up work lands. Or it can be too large, bundling several outcomes that could each have shipped and been useful on their own. I didn't want a rule about task counts, repository counts or days of effort. The goal is the smallest coherent delivery boundary. Depending on something already delivered is fine. Depending on a future item to finish or repair this one is not.

A complete capability can still ship switched off. Independence doesn't require activation, but it does require that the capability is finished rather than a promise.

A Worked Example

Picture a catalog application that needs export. A task-shaped roadmap would list four things: add an export endpoint, add an export button, connect the two, handle failures. Those are reasonable tasks. They are not four independently valuable outcomes, and if the roadmap gets reprioritized after the first two, what's left in production is an endpoint nobody can reach.

Here is roughly what the same work looks like as a single hypothetical PS, using the template's sections:

## Outcome
A user can export the currently filtered catalog view as CSV.

## Current reality
Filtering exists and respects per-user access rules. No export exists.

## Scope and independence
Includes a usable action, correct content matching the filter, existing
access rules preserved, and understandable failure behavior.
If every later item is canceled, CSV export is still complete.

## Future health
Should not foreclose additional formats later. No new coupling between
the filter UI and the data layer.

## Dependencies and decisions
None open. Scheduled exports, other formats, and export history are
separate future outcomes.

## Completion expectations
Merged, with observable evidence that a filtered export downloads
correct rows for a restricted user.

Notice what isn't there. No controller name, no class layout, no list of tests. The PS describes what "done" has to mean and leaves the delivery agent room to find the simplest way to get there in the code as it actually exists. The argument about whether an endpoint alone counts as shipping happens here, while it's still a sentence in a planning file, instead of during a pull request review.

Who Gets to Decide

Moving an agent upstream raises an obvious worry: does it quietly become the product owner? I spent more time on this boundary than on anything else in the release.

The roadmap command may read source, tests, configuration, current Knowledge and Git history. It may only write roadmap files inside the resolved planning root. It must not edit application code, run the application's build or tests, or slip in a convenient fix it noticed along the way. It recommends changes to priorities, scope, architecture, sizing and status, and I approve them before anything is recorded. And it never starts delivery.

That last rule is the one I care about most. When I want to build a PS, I run /devspark-specify and name it explicitly. Specify then reads the PS as context, checks its current-reality claims against the repository, and carries on through the normal workflow. Specify doesn't go looking for a roadmap when I haven't named one, and an unresolved roadmap dependency is reported to me as something to decide, not turned into a new gate.

I should be honest about what kind of boundary that is. These are prompt rules. The structural checker is not a sandbox, and the contract tests verify that the instruction text says the right things, not that every agent on every day obeys it. This is the same lesson I wrote about in autonomy guardrails: a rule that the tooling states clearly is better than no rule, and it's still not enforcement.

Keeping Intent Separate From Truth

There's a quieter design decision underneath all this. A roadmap describes intent. Code, tests and .knowledge/ describe what the software actually does. If a confidently written plan starts leaking into the documentation of current behavior, an agent will eventually treat an aspiration as a fact.

So current code and Git evidence outrank stale planning claims, and PS identifiers are allowed in work notes, commit messages and PR descriptions but not in shipped code, tests or Knowledge. Traceability runs one direction: the plan points at the software that realized it, and the software never needs an old plan to explain itself. It's the same principle behind the spec never being the record, applied one level further up.

The command also separates two kinds of drift. Tracking drift is when a status label disagrees with the evidence, such as an item still marked active after its work merged. Product drift is when delivered work, or current priorities, wander away from the direction the roadmap set out. The first is a bookkeeping fix; the second needs a conversation. In both cases the agent's job is to show the evidence and recommend a correction, not rewrite priorities on its own.

Merged, deployed and activated stay three different facts. Roadmap completion requires delivery evidence, with merge as the minimum, and that says nothing about whether anyone can use the capability yet.

What My Own Review Found

Before writing this I ran a technical review of the 9.5.2 code rather than relying on the release notes. Sixty-two focused tests passed, covering the checker, both shell wrappers, release archival, the consumer skill and the install index. Then three small synthetic probes, written to poke at shared-roadmap edge cases, each reproduced a real defect.

None of these are dramatic, and all three sit in the shared-roadmap path, which is exactly where I most want the automation to be trustworthy. The second one bothers me most, because it fails successfully: the response looks correct and hands the wrong outcome to delivery. Each has a recommended correction and a regression case to add, and I would rather publish them here than let someone find them in their own planning repo.

It's also worth saying what the review did not establish. It didn't run the full framework suite or full package builds, didn't test a fresh install, didn't measure whether live agents follow the planning boundary, and didn't measure anything about delivery speed. I don't have a productivity number, and I'm not going to invent one.

What I'll Be Watching

The claim I'm comfortable making is narrow. Agents can help clarify what is worth building, what a complete increment means, and what evidence would show success, before anyone asks them to build it. Whether that actually pays off is something to observe over time. Are scope and dependency corrections happening before implementation instead of during review? Do finished increments stay useful when later items get canceled? Is less work being redone because the outcome was misunderstood? Does total delivery time improve without planning overhead quietly eating the gain?

Those are questions to watch, not telemetry the feature collects. If the honest answer after a few months is that the roadmap mostly produces nicer documents, that will be worth knowing too. What I'm hoping to see is the cancel-everything-after-this question showing up in planning conversations on its own, whether or not anyone opens the roadmap file.

Explore More

• Shift Left Into Planning — the argument this feature tries to put into practice
• DevSpark Dogfooding: Escaping the Scope-Creep Spiral — why I was wary of adding another mandatory stage
• Autonomy Guardrails: Bounding Agent Action Safely — the difference between a stated rule and an enforced one
• DevSpark v4: The Spec Was Never the Record — keeping planning artifacts out of the source of truth