Create Ticket

Creating a ticket

Tickets are how you logically track your own work that needs to be done. They are distinct from "agents" and "tasks" -- a "ticket" describes what needs to happen, while a "task" is the actual chunk of work assigned to an "agent" (often in order to accomplish a "ticket", though not always, and there will usually be multiple "tasks" for any given "ticket", eg, at least one for the working agent, and one for the verifying agent).

Tickets are managed using the tk command line tool, which stores them as markdown files with YAML frontmatter in .tickets/. You can run tk help to see all available commands.

When to create a ticket

• At capacity: You need to delegate work but have too many agents running (see delegate-task-to-agent skill). Create a ticket so the work is not forgotten, and it can be picked up later when capacity opens up.
• Follow-up work: A verifier recommends additional work, or a completed task surfaced something that needs attention later.
• Multi-step projects: Break a larger goal into multiple tickets, using dependencies to track ordering.
• User requests that can't start immediately: The user asks for something but you are busy with higher-priority work. Be sure to send them the ticket ID using your send-message-to-user skill, so they can refer to it later if needed.

How to create a ticket

tk create "<title>" \
  --description "<description of what needs to be done, including any relevant context>" \
  --acceptance "<what 'done' looks like -- the success criteria>" \
  --priority <priority> \
  --type <type>

Priority levels

Use these to determine which ticket to pick up first when capacity opens:

• 0 -- Critical. Must be done as soon as possible.
• 1 -- High. Important, should be done soon.
• 2 -- Normal (default). Standard work.
• 3 -- Low. Nice to have, do when convenient.
• 4 -- Minimal. Background/aspirational work.

Types

• task (default) -- a unit of work to be done
• bug -- something is broken and needs fixing
• feature -- a new capability to add
• epic -- a large effort that will be broken into sub-tickets
• chore -- maintenance, cleanup, or operational work

Tags

Use --tags to categorize tickets for easier filtering:

tk create "Refactor auth module" --description "..." --priority 2 --tags backend,refactor

Including enough context

The most important part of a ticket is that it contains everything a future agent will need to start working on it without asking you questions. Include:

• What needs to be done and why
• Success criteria (via --acceptance) so the verifier knows what to check
• Relevant context: conversation IDs, prior attempts, related agent IDs, links to code or docs
• The user's original request (if applicable), including the conversation ID and a summary

Think of it this way: when you later use list-tickets to find work to do, you will read this ticket and immediately create an agent from it using delegate-task-to-agent. The ticket must have enough detail for that to work smoothly.

Dependencies

If a ticket depends on another ticket being completed first:

tk dep <this-ticket-id> <depends-on-ticket-id>

Use tk ready to see which tickets have all dependencies resolved and are ready to work on.

After creating a ticket

Always post to the Work Log (see send-message-to-user skill) with a brief entry:

Created ticket <ticket-id>: <title> (priority <N>)

If the ticket was created because the user asked for something and you couldn't start immediately, also acknowledge this to the user in the relevant conversation via send-message-to-user -- let them know you've logged it and will get to it when capacity opens up (and be sure to include the ticket ID so they can refer to it later if needed).

Closing tickets

When a ticket's work is complete (the agent finished and verification passed), close it:

tk close <ticket-id>

You can also add notes to tickets as work progresses:

tk add-note <ticket-id> "Working agent <agent-id> has been created for this ticket"