Writing tickets for AI agents: the template that stops them inventing requirements
The most expensive thing an AI coding agent does is not write a bug. It is invent a requirement. Given "add invitations to the team page", an agent will decide who can invite, what happens to a pending invitation after seven days, and whether the email goes out before or after the record exists. All three are product decisions, and it will take them in the most reasonable way, which is not necessarily yours. The ticket template below exists to leave no room for the reasonable guess.
The rule under the template
No ticket, no work. No measurable acceptance criterion, the ticket goes back to the human before anything starts. The frontmatter is validated by a script in CI, so a ticket missing a field cannot be worked on. It sounds bureaucratic until the first time an agent builds the wrong half of a self contradicting ticket, which on my build took eighty lines of distance between the two contradictory sentences and cost a day.
The template
---
id: 143
title: Invite a teammate to a collection
status: todo
area: team
depends_on: [131]
decisions: [0088, 0091]
baseline: {design: 18, tokens: 7}
board: <url of the row on the board>
---
## Why
One sentence linking this to the thesis.
## What done looks like (measurable)
- A member with the owner role sends an invitation to an
email; the invitee receives it within 60 seconds in the
test mailbox.
- A pending invitation grants zero rows of any table,
proven by a test that runs as the pending user.
- Accepting makes the invitee a member with the role
chosen by the owner; the audit log records who invited
and who accepted, with timestamps.
- Browser test on mobile and desktop passes.
## Out of scope (explicit)
- Resending or expiring invitations (ticket 144).
- Inviting by link.
- Any change to the roles themselves (decision 0088 fixes them).
## Decisions already taken
- 0088: the four roles and what each may do.
- 0091: invitations are per collection, not per account.
## Open questions
- None. (If there were, the ticket would be blocked, not started.)
The three fields that do the work
What done looks like, measurably. Every line has a number, a role, or a test in it. "The invitation works" is not a criterion. "The invitee receives it within 60 seconds in the test mailbox" is one, and an agent can make it true and prove it. This is also what the reviewer checks against, so a vague criterion makes the review vague too.
Out of scope, explicitly. Agents build what you do not forbid. Listing the adjacent features, with the ticket where each one lives, turns "while I was there I also added resending" into a rule violation instead of initiative. On my build this list is the single most effective scope control, more than any conversation.
Decisions already taken, by id. A decision in a chat is gone next session. A decision with an id in a log is citable, and a ticket that cites it tells the agent "this is settled; do not reopen it". Half the escalations I received in the first two weeks were questions that had already been decided; the field removed them.
Frontmatter, because a script has to read it
The fields above the line exist so that scripts can check what humans forget: that the ticket has an id and a status, that its dependencies are merged before it starts, that it cites decisions that exist, that it has a row on the board (the board mirrors the tickets, never the other way), and which version of the design it was built against. A ticket that fails the schema is returned automatically. The validation took an hour to write and has caught something every week since.
What a ticket is not
It is not a specification of the implementation. The data model, the permissions and the design live in their own documents, and the ticket references them. A ticket that restates the domain model goes stale the day the model changes, and an agent will follow the stale copy. One source of truth per fact, and the ticket points at it.
This is step 3 of how to build an MVP with AI agents. The decisions log it cites is described in the project rules file; who takes the ticket from here is in the team structure.
Copy the template: Ticket template for agents, with a prompt to use it and its changelog.
Questions people ask
How detailed should a ticket for an AI agent be?
Detailed in the three places agents fail: what done looks like (measurable), what is out of scope (explicit), and which decisions are already taken (by id). Everything else can be short, because the agent reads the domain model and the rules file anyway.
Who writes the tickets, the human or the lead agent?
The human writes the ticket: intent, acceptance criterion, bounds. The lead agent decomposes it into work for the workers. An agent writing its own acceptance criterion is grading its own homework.
What happens when a ticket is wrong?
It goes back before any work starts. A ticket without a measurable criterion or with invalid frontmatter is returned, by rule. The cost of returning a ticket is minutes; the cost of building against a wrong one is the ticket plus everything that was built on top.
Working on something like this?
This is how I build products with AI agent teams, from scope to production. Discuss a product idea → Or email me.