TICKETS.md
Agent-native in-repo ticketing

Tickets that work with agents.

A repo-native ticket format and CLI ideal for sandboxed environments. Structured for parallel, long-running agentic development, with generic planning primitives, append-only logs, and agent ticket claims.

View on GitHubGetting Started
Apache-2.0 license • Built for humans and machines

Ticketing for Agent Teams

Agentic coding tools are great at writing code, but they still have problems with staying coordinated over time. As additional agents are added to work on more complex tasks, having effective task tracking, context availability, and a clear understanding of work done becomes key.

TICKETS.md aims to address common issues with agentic development by providing a clear agent contract, an open and merge friendly in-repo ticket+context format, with skill support and simple tooling for the agent to work with tickets, planning views, and claims.

The TICKETS.md file is a human readable shared contract that tells the agent how to work with tickets, what the ticket format is, and what tooling is available to work with tickets.
An agent friendly, in-repo ticket format provides a common mechanism for agents to keep track of scope, detail changes made, carry across context, and establish relationships between tickets. These act as history for agents, in a stable and merge-friendly way.
A set of simple CLI tools provides a consistent way for agents and humans to easily work with tickets.

We’re not aiming to replace AGENTS.md, but to provide a contract with agents about how to define work, track changes, and carry over context. This separation keeps the ticket system stable, discoverable, and easy to integrate across different agentic environments.

Getting Started

It's simple to add TICKETS.md to your repo with helpful tooling and templates. Make it your own and see how you can integrate to your agentic workflows.

Install the package
Add the package in the repo where you want to run Agent-First In-Repo Ticketing.
npm install @picoai/tickets
Initialize in your repo
Bootstrap the ticket system assets from the package templates.
npx @picoai/tickets init
Create a ticket
Create your first ticket; the CLI prints the UUIDv7 and creates its folder.
npx @picoai/tickets new --title "Feature Alpha" --node-type group --lane build --horizon current
Anatomy of TICKETS.md
Initializing a repo with `@picoai/tickets` writes the key files needed to manage ticket tracking, overrides, and repo-local skill loading.
.
├── TICKETS.md
└── .tickets/
    ├── config.yml
    ├── skills/tickets/SKILL.md
    └── <ticket-id>/
        ├── ticket.md
        └── logs/<run>.jsonl
Each ticket gets its own folder, a human readable Markdown definition, a repo-local config for semantic overrides, and append-only JSONL structured logs.
Updates, claims, and carried context live in merge friendly logs, not a single mutable state file.
This layout shows the files the package adds to a repo that uses it. It is not the layout of this package's source repo.

Get involved

Use it in a repo
Start with the canonical docs in TICKETS.md and the project overview in README.md.
Improve the spec
Propose fields, validation rules, and interoperability patterns that help agents collaborate across tools and branches.
Build integrations
IDE helpers, lightweight dashboards, CI checks, or agent harness adapters— all through the same repo-local interface.
TICKETS.md is a community project.
GitHubApache-2.0