Tickets that work with agents.
A simple, flexible ticket format and CLI designed for parallel, long-running agentic development—without requiring a hosted service or network access.
Apache-2.0 licensed • Built for humans and tools • Designed to be merge-friendly
Goals
Tickets.md is intentionally small: a proposed format plus a single repo-local interface for automation. The goal is to make collaboration between people and agents predictable, auditable, and easy to merge.
Simple, readable tickets
A Markdown-first definition that stays stable over time, with acceptance criteria and verification that agents can follow.
Merge-friendly parallelism
Per-run, append-only logs reduce conflicts and make concurrent work across branches practical.
Offline-first
Works in sandboxes and air‑gapped environments. The repo is the source of truth.
A consistent interface
A small CLI surface is the integration point for humans, IDE helpers, and agent tooling.
Agent-safe execution
Encourage explicit acceptance criteria, verification steps, and bounded iteration so work converges.
Open and collaborative
Designed to be shared, improved, and extended—without requiring a hosted service to get value.
Non-goals (by design)
Tickets.md is not trying to be a full project management suite, a required replacement for GitHub Issues, or a hosted service. The focus is a durable in-repo format and an interface agents can reliably use.
How it works
The system separates a human-readable ticket from a machine-friendly audit trail:
- Define work in a Markdown ticket with front matter and clear acceptance criteria.
- Log runs to append-only JSONL files (one file per run) so parallel work stays mergeable.
- Integrate tooling via a small CLI surface—agents, IDEs, and humans speak the same interface.
A collaborative default
This project is open source and welcomes contributions—from docs and examples to validators and integrations. If you build tooling that speaks the Tickets.md format, we want to learn from it.
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.