Give an AI coding agent a reviewed IntentSpec in intent.md before it builds a consequential feature. The file should state the objective, observable outcomes, hard constraints, edge cases, scope where needed, and concrete verification. An agent can draft that content from the codebase and available evidence, but a human should authorize the product judgment it contains.
A builder gave Cursor a one-line ask: “let users filter the dashboard by date.” The agent shipped a clean date-range picker. The actual need, buried in support tickets, was a saved “last 7 days” default that survived reloads. The coding was competent. The product decision had not reached the repository.
Give the agent a decision, not a transcript dump
The coding agent does not need every artifact your team produced. It needs the reviewed decision that governs implementation. Put that decision in intent.md, where it can travel with the branch and be inspected in review.
At minimum, include:
- A meaningful title. Name the change precisely enough that another session can identify it.
- The objective. State the actor, problem or capability, and why the work matters.
- Observable outcomes. Describe what becomes true for users after success, not what code should be written.
- Hard constraints. Record security, business, compatibility, or architectural boundaries the implementation cannot violate.
- Edge cases. Pair likely failure modes and boundary conditions with expected behavior.
- Concrete verification. Name checks that can demonstrate success and catch regressions.
Add these when they carry real judgment:
- Scope for what the agent may and may not touch.
- Health metrics for behavior or performance that must not degrade.
- Evidence references for the signals that informed the decision.
- Decisions and rejected alternatives when later agents might reasonably reopen the choice.
The repo gets the decision, not every private input behind it.
Who writes it
An agent can do the first drafting pass. It can inspect the codebase, synthesize available evidence, label assumptions, and ask focused questions. That is authorship support, not product authority.
A human should review the objective and outcomes, resolve tradeoffs, confirm hard boundaries, and authorize the result. Pathmode confirmations are tied to the exact content: change the objective or outcome, and the old confirmation no longer silently applies.
Check it before implementation
Run Pathmode's deterministic preflight on intent.md. It grades six readiness gates without a model call and identifies the exact weak dimension. Repair the blocker, save the decision back to the same file, and then let the coding agent begin.
That is enough ceremony for the handoff: one portable file, one repeatable gate, and one clear line between what the agent may propose and what a human has authorized.
Frequently asked questions
- Isn't a well-written prompt enough?
- Yes for disposable, exploratory, or easily reversible work. For maintained product changes, intent.md keeps the decision with the branch and code so it survives new sessions, agents, and reviewers.
- What's the single most important thing to include?
- A specific objective connected to observable outcomes. The objective says what problem the work serves; the outcomes say what must become true. Together they keep implementation choices pointed at the authorized result rather than merely completing a task list.
- Should I put raw customer evidence in intent.md?
- Usually not. Repositories are durable and widely cloned. Put the decision and safe evidence references in the file; keep private tickets, transcripts, named guest feedback, and signed-in authorization in their source systems or the connected Pathmode team layer.
- Do I need every IntentSpec field every time?
- No. The preflight has six blocking gates: title, objective, outcomes, constraints, edge cases, and verification. Add scope, health metrics, evidence, and decision history when the risk and judgment of the change call for them.