Before the plan

Do you need a PRD before a coding agent starts?

The question usually arrives after an agent built something you did not ask for, in a shape you did not want. The reflex answer is "write a spec first". That is right about half the time, and the half it is wrong about is the half where the spec would have been a paragraph anyway.

Disclosure: I build Ordewell, so this is how one tool handles the question rather than a survey of the field. It is free and Apache 2.0. The distinction below is worth having whether or not you install anything.

The plan is not the spec, and the spec is not the plan

Two documents get conflated. A plan is a set of tasks with dependencies, each one small enough for a single agent session. A PRD is the feature described in prose: what it is for, who it is for, what the stories are, what is out of scope.

A plan answers "what do I run next". A PRD answers "why is this correct". A plan is written for the scheduler. A PRD is written for the argument you are going to have with yourself in three days when a task looks wrong and you cannot remember what the point of it was.

When the PRD pays for itself

When the work will be revised. This is the strongest case. A plan gets re-read, and it should be re-read against the whole feature and not against one task's slice of it. If the spec exists as a file, the revision pass opens the spec. If it only exists in the original prompt, the revision pass has to reconstruct it from a conversation that has since grown.

When tasks need to trace back to intent. A task that says which user story it delivers can be argued about. A task that says "refactor the provider layer" cannot. If the PRD is there, each task can carry the exact story text it covers, copied rather than paraphrased, so the mapping is auditable instead of implied.

When more than one person has to agree. A spec is a review artifact. It is cheaper to disagree with prose than with a diff.

When it is busywork

When the goal is already fully specified. "Add a retry with backoff to the fetch helper, three attempts, jitter, log each attempt" is a complete spec. Writing a PRD for it produces a document whose only reader is the plan.

And when the unknowns are in the code, not in your head. If the reason you cannot specify the work is that you do not know how the current thing works, a PRD will not fix that. Reading the repository will. Writing a spec on top of a repository you have not read is how you get a beautiful document specifying the wrong system.

The middle path: questions before the plan

The alternative to writing a spec is being asked what you meant. A planner that has read the repository can ask two or three questions that only someone who has read the repository would ask, and the answers are usually more useful than the document you would have written blind.

In Ordewell that is what happens before planning. The planner explores a read-only envelope, then asks concise questions pinned to real files. It is told to ask when the goal is vague or when the answer would materially change the outcome, a storage engine, a library choice, the shape of an API. It is also told that a fully specified goal needs no questions, because interrogating a user who already said what they want is its own failure mode.

So the order is: read, ask, plan. The PRD sits third in that list, next to the plan, and only when it earns its place.

How it looks when the PRD is written

When there is a PRD, it does not live in the conversation. The planner emits it as a markdown block between two HTML comment markers, and the markers exist for one reason: so the block can be lifted out and saved to disk at .scratch/<slug>/PRD.md. The markers are not a state machine. Nothing gates on them.

What they buy is a file with a stable path. The revision pass reads the original goal plus that file, so a plan can be checked against the whole feature rather than against whatever the last few messages happened to mention.

# start from a goal, not a spec
ordewell plan "teams can share a saved query"

# the planner reads the repo, then asks
  How are saved queries stored today, per user or per
  workspace? And should sharing be a link, a copy, or
  a live reference?

# it proposes the plan; the spec, if you want one,
# is saved where the plan can re-read it
  .scratch/saved-query-sharing/PRD.md

A cheap model may write the PRD block and the plan in the same turn, which is fine, and the block is still captured. The document is a by-product of planning, not a phase you have to complete before planning may start.

Honest limits

• The PRD is optional, and nothing enforces it. There is no check that a plan covers every user story. The story field is a place to put the link, and it is only as honest as the writing in it.
• A PRD does not make a plan correct. It makes the intent legible. A legible wrong plan is still wrong, just easier to catch before you run it.
• One-shot runs have nobody to ask. Where there is no user in the loop to answer questions, the planner is told to make the most reasonable assumption grounded in its research and record that assumption in the task description. A recorded assumption is weaker than an answer, and it is worse than a PRD you wrote yourself.
• Spec drift is real. The PRD is a file on disk. If you change the goal and don't update the file, the plan will be revised against a stale spec and it will look perfectly self-consistent while being wrong.
• It is not a process. No approvals, no sign-off states, no ticket sync. It is a markdown file and a saved path, and if you need more ceremony than that, use your existing tooling for it.

Source and design notes

The interesting part is that the markers are purely for saving, not for gating, and that the revision pass re-reads the spec rather than the conversation. The code behind that: the PRD store, the planner conversation, the planner prompts, and github.com/ordewell/ordewell.