Pathmode does not require replacing a well-written PRD. Keep the PRD when you need narrative, stakeholder alignment, or broader strategy. Add an IntentSpec in intent.md when the repository needs a compact product decision an AI coding agent can repeatedly read: objective, observable outcomes, constraints, scope, edge cases, and verification.
A builder writes a careful PRD: problem, customer context, outcomes, alternatives, and edge cases. The team agrees, work starts, and the coding agent receives one line in a ticket. The failure is not that the PRD was written by hand or that nobody read it. The failure is the lossy handoff between the product record and the repository.
PRDs and IntentSpecs have different jobs
A PRD is flexible narrative. That makes it useful for persuasion, strategy, discovery, alternatives, rollout thinking, and stakeholder review. Its structure varies because the conversation around a product decision varies.
An IntentSpec is deliberately narrower. It carries the authorized decision an implementation agent must honor:
- the objective and why it matters;
- observable outcomes with stable identities;
- hard constraints and explicit scope;
- edge cases with expected behavior;
- decisions, rejected alternatives, and reopen triggers when relevant;
- concrete verification checks and regression guards.
The conventional artifact is intent.md, committed beside the code. It can be reviewed in the same pull request, read by any agent, and updated when the product decision changes.
The PRD can explain the decision.
intent.mdgoverns the build.
PRD vs repo-bound IntentSpec
| PRD | IntentSpec in intent.md | |
|---|---|---|
| Primary reader | People aligning on the product | Agents and people implementing or reviewing the change |
| Shape | Flexible narrative | Open, structured product-intent format |
| Location | Product or document system | Repository and branch it governs |
| Evidence | May quote, summarize, embed, or link it | Carries references; private raw evidence can stay outside git |
| Change review | Document history and stakeholder process | Git diff plus explicit human authorization |
| Definition of done | Often narrative success criteria | Canonical verification checks tied to outcomes |
Three sensible ways to use them
- Use only
intent.md. Good for a small team that wants one concise artifact and does not need a separate alignment narrative. - Keep the PRD and derive
intent.md. Good when the PRD already holds valuable context but the implementation agent needs a tighter, repo-native handoff. - Draft both from the same evidence and decisions. Good when connected Pathmode teams want private provenance and review behind a public or widely cloned repository artifact.
The point is not to declare every PRD stale. It is to make sure the current, authorized product decision reaches the agent in the place where implementation actually happens.
Frequently asked questions
- Isn't a PRD still useful?
- Yes. A good PRD can align people, explain context, compare alternatives, and record strategy. The problem is not that PRDs are hand-written; it is that coding agents often receive a much thinner ticket or prompt instead of the decision the PRD contains.
- How is an IntentSpec different from a well-written PRD?
- IntentSpec has a narrower execution job. Its conventional file, intent.md, lives beside the code and expresses the fields an agent and reviewer need to build and verify a change. It can reference the PRD and private evidence without copying their full narrative into git.
- Do I have to throw away my existing PRDs?
- No. Extract or draft the load-bearing decision into intent.md, review it, and link back to the existing record. The PRD can remain the human narrative while the IntentSpec becomes the repo-bound authority for implementation.