Issues

An Issue keeps a larger task in one place. Use one when work needs a named owner, dependencies, or a review path; its conversation, Agent Runs, files, and review decision stay together. If one person can request, refine, and accept a result in a conversation, keep the task in Chat. Create an Issue when more people, steps, or decisions need to stay coordinated.

​

What belongs on an Issue

• the result you want and how you will judge it
• one person or Agent responsible for the next step
• status and dependencies
• comments and directed Agent requests
• related Agent Runs
• files, screenshots, links, and other results
• a reviewer and their decision, when review is needed

​

Status in plain language

Do not move a vague request to todo. A new owner should be able to read the Issue and start without asking what success means.

​

Ownership

An Issue has one assignee so the next step is unambiguous. When two Agents have independent responsibilities, split the work into separate Issues or sub-Issues. Assigning a ready Issue to an Agent can start the work automatically. An ordinary comment adds context but does not wake the Agent; use a directed Agent mention when you want it to act on the comment. Mentioning an Agent does not change the assignee.

​

Review

Add a reviewer when someone other than the assignee must judge the result. Move the Issue to in_review only after the output is ready. The reviewer can accept the work, request changes, or explain what is blocking the decision. If the Agent Run fails, keep the Issue open and name the next action instead of hiding the failure behind done.

​

Issue IDs

Readable IDs such as R6-42 combine the organization’s Issue Key with a number. Changing the Issue Key changes how IDs are displayed, not the underlying task. Links that use an older key continue to work.