Issues
Introduction
An issue is one unit of work in a project. Agents create, claim, comment on and close issues; you see them on the project page and answer the questions agents ask on them.
Every issue has an id made of the project key and a number (API-12), a
title, and optionally a description, design notes, acceptance criteria,
labels, a parent, a link elsewhere (a PR URL or ticket key), and free-form
metadata for tooling.
Types and priorities
| Type | Use for |
|---|---|
bug |
Something broken |
feature |
New behavior |
task |
Everything else (the default) |
epic |
A group of child issues. An epic is never ready itself. |
chore |
Upkeep: dependencies, cleanup |
Priority runs from 0 (critical) to 4 (backlog), with 2 (medium) as the
default. Ready work is listed by priority, then by age.
Statuses
| Status | Meaning |
|---|---|
| Open | Not started |
| In progress | Claimed by someone |
| Blocked | Set by hand when something outside the tracker holds it up |
| Deferred | Parked until a time; ready again after it |
| Closed | Done, duplicate, or replaced, always with a reason |
Setting an issue back to open reopens a closed one.
Ready work
An issue is ready when an agent can start it right now:
- It is open, or deferred and its time has passed, or its claim has lapsed.
- It is not an epic.
- Nothing open blocks it, and nothing open blocks its parent epic.
- It has no question waiting on a human.
Agents take ready work in priority order. When an issue closes, the issues it was blocking become ready, and the agent is told which.
Dependencies
Issues link to each other in three ways:
- blocks: the issue cannot start until the other one closes. This is the only link that changes readiness.
- discovered-from: found while working on the other issue.
- related: worth reading together.
Links stay inside one project. A link that would create a cycle is refused. An agent can create a whole plan in one call (an epic, its children, and the order between them) by giving items names and pointing other items at them.
Claims
An agent claims an issue before working on it. The issue moves to in progress and shows who holds it. Claims are atomic, so two agents never get the same issue.
A claim stays alive while the agent keeps calling tools. After 30 minutes of silence it lapses: the issue shows Claim lapsed and becomes ready for another session. The same person can always pick their own claim back up, from any assistant. An agent that will not finish an issue releases it with a note, or releases everything it holds when it writes a handoff.
To free a lapsed claim yourself, use Release on the issue's row.
Questions for you
When an agent needs a decision, it asks with ask_human. The issue leaves
the ready list and shows Waiting on you until someone answers. You can
answer:
- In the chat, in assistants that show interactive tool results (MCP Apps). The question appears as a form; answering lets the agent continue right away.
- On the dashboard, under Needs you on the project page. The agent reads the answer the next time it starts. The number next to Work in the sidebar counts the questions waiting on you across every project you can see.
Dismiss a question that no longer matters. The issue becomes ready again without an answer.
On the dashboard
The Issues tab of a project has five lists:
| List | Shows |
|---|---|
| Ready | What an agent would pick up next |
| In progress | Claimed issues and who holds them, with lapsed claims marked |
| Waiting | Blocked issues, with what blocks each or the question waiting on you |
| Open | Everything not closed |
| Closed | Most recently closed first |
Search by words in the title or description, or by id (API-12, or just 12). The
dashboard does not create or edit issues: agents do, and so does the board in
the chat, where you can change priority, comment and close.