ticket-states
Skill1 starsChanged 5 days agoMITView on GitHub
A small shared vocabulary of ticket states that say who acts next: needs design, ready for an agent, needs a human, needs review; and how to record a change to a ticket's brief. Use when filing, triaging, or labelling tickets, when a skill sets or clears a ticket's state or changes its brief, or when the user asks what needs design, review, or their attention, or what's ready for an agent.
In this repository22 other files it gives its agents.
- AGENTS.mdAGENTS.md
- .cursor/rules/beads.mdcCursor rule
- beadsSkill
- arenaSkill
- build-ticketSkill
- deep-reviewSkill
- design-it-twiceSkill
- designSkill
- domain-modelingSkill
- grillingSkill
- land-to-mainSkill
- lets-buildSkill
- lets-designSkill
- markdown-for-humansSkill
- model-tiersSkill
- orca-subagentsSkill
- prepare-commitSkill
- ready-ticketSkill
- reflectSkill
- review-diffSkill
- to-ticketsSkill
- verify-ticketSkill
The file
We split this skill into the rules it gives an agent
10 rules. About 0 are common, 3 are distinctive, and 7 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈3
Distinctive · estimate
This author's own choices. Worth a look.
7
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 37
Only a human's approval sets ready-for-agent: /to-tickets after the user approves the tickets, or the user answering a needs-human ticket.
- Distinctive: line 47
Never lose a ticket's original text.
- Distinctive: line 49
When a decision contradicts a ready ticket, keep its brief and append a note saying what changed and why.
- Distinctive: line 50
When rewriting a rough ticket into a ready one, the new brief replaces it.
- Very specific: line 61
Use the state names as labels or tags.
- Very specific: line 64
Use the override wherever this skill names that state, commands included.
- Very specific: line 70
Never answer one with bd human respond or bd human dismiss: both close the ticket.
- Very specific: line 76
Don't use --set-labels: it also removes labels that aren't states.
- Very specific: line 77
Add a note with bd update <id> --append-notes "<text>".
- Very specific: line 78
Add a comment with bd comments add <id> "<text>".
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Ticket states
A ticket's state says who acts next. The tracker owns lifecycle: claims, blocking edges, deferral, and closing. These states record only what the tracker can't: whether a ticket is designed, approved, or waiting on a human.
States
| State | Meaning | Set by | Cleared by |
| (none) | Untriaged: nobody has looked at it | whoever triages it | |
needs-design | Real work; design is the next step | whoever triages it; /build-ticket stopping for redesign | /to-tickets |
ready-for-agent | Designed and approved by a human; an agent may pick it up | /to-tickets; a human answering | /build-ticket |
needs-human | An agent needs a decision or an answer; a comment on the ticket says what | /build-ticket stopping on a question, or on a failed verification it can't fix | whoever answers it |
needs-review | Built with evidence, still claimed, not yet landed | /build-ticket hand-off | closing the ticket |
Rules
- A ticket has at most one state: setting one removes any other. Closing a ticket removes its state.
- The table names the usual setters, not the only allowed transitions.
Set whichever state says who acts next, except as the
ready-for-agentrule below says. - Parent tickets carry no state; their children do. A parent not yet designed may be
needs-design. - Tickets are often filed with no state. An agent may triage them for the user,
setting any state except
ready-for-agent, e.g.needs-designfor work still to be designed. - Only a human's approval sets
ready-for-agent:/to-ticketsafter the user approves the tickets, or the user answering aneeds-humanticket. It records that a human approved the design. - An agent choosing its own work picks only open, unblocked
ready-for-agenttickets. A ticket the user names directly needs no state. - To answer a
needs-humanticket, comment with the answer, then set the state that says who acts next: for exampleready-for-agentif the design stands,needs-designif it must be redesigned or split, orneeds-reviewif the built change stands.
Changing a brief
Never lose a ticket's original text.
- When a decision contradicts a ready ticket, keep its brief and append a note saying what changed and why.
- When rewriting a rough ticket into a ready one, the new brief replaces it; keep the original text in a note.
Comments
Record work on a ticket as comments on it: decisions made while building, why work stopped, questions and answers, verification verdicts, hand-off results. They're the ticket's discussion; the brief and notes stay what to build. In a tracker without comments, append to the ticket's notes instead.
Names
Use the state names as labels or tags.
A project overrides a name with one line in its AGENTS.md,
e.g. "Use label agent-ready for tickets ready for implementation."
Use the override wherever this skill names that state, commands included.
In a tracker with neither labels nor tags, write a State: line in the ticket.
Beads
needs-human is beads' own human label, so bd human list shows it.
Never answer one with bd human respond or bd human dismiss: both close the ticket.
The state labels are needs-design, ready-for-agent, human, and needs-review.
Set a state by adding its label and removing the other three,
e.g. needs-human: bd update <id> --add-label human --remove-label needs-design,ready-for-agent,needs-review.
Clear it: bd update <id> --remove-label needs-design,ready-for-agent,human,needs-review.
Don't use --set-labels: it also removes labels that aren't states.
Add a note with bd update <id> --append-notes "<text>"; --notes replaces the existing notes.
Add a comment with bd comments add <id> "<text>"; list them with bd comments <id>.
A child created with --parent inherits its parent's labels, state included, and labels given at create add to them.
Set the child's state with bd update after creating it.
The untriaged query also lists parents: a parent with children (bd children <id>) is already triaged.
| Question | Command |
| What's ready for an agent? | bd ready -l ready-for-agent |
| What needs design? | bd list -l needs-design |
| What needs me? | bd human list, and bd list -l needs-review |
| What's untriaged? | bd list --status=open --exclude-label needs-design,ready-for-agent,human,needs-review |
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

