ticket.app

Ticket Protocol

The open standard for machine-readable work stored in Git. CC0 licensed.

A format, not a product.

The protocol defines repository layout, ticket file format, workflow states, and the index schema. Any implementation can read and write tickets that conform.

Includes

  • ✓.tickets/ repository structure
  • ✓Ticket file format (YAML frontmatter + Markdown body)
  • ✓Five-state workflow and transitions
  • ✓index.json schema for efficient querying
  • ✓Forward compatibility rules (x_ticket namespace)

Does not include

  • ×CLI commands
  • ×Dashboard UI
  • ×Pricing or business model
  • ×GitHub-specific features

Core and Indexed

Core profile

  • Only requires .tickets/tickets/*.md
  • Ideal for minimal tooling or manual workflows

Indexed profile

  • Adds .tickets/config.yml and .tickets/index.json
  • Enables fast dashboards and large-scale querying

ticket.app requires Indexed profile.

Canonical examples

Ticket file
---
id: 01ARZ3NDEKTSV4RRFFQ69G5FAV
title: Example ticket
state: ready
priority: p1
labels: []
---

Markdown body…
index.json
{
  "format_version": 1,
  "generated_at": "2026-02-16T18:22:11Z",
  "workflow": "simple-v1",
  "tickets": [
    {
      "id": "01ARZ3NDEKTSV4RRFFQ69G5FAV",
      "short_id": "01ARZ3ND",
      "display_id": "TK-01ARZ3ND",
      "title": "Example ticket",
      "state": "ready",
      "priority": "p1",
      "labels": [],
      "path": ".tickets/tickets/01ARZ3NDEKTSV4RRFFQ69G5FAV.md"
    }
  ]
}

Git is authoritative.

Any caches, databases, or indexes are derived and disposable. If there is a conflict, ticket files win.

View PROTOCOL.mdInstall CLI