agent-tickets

Cards are the database. Git history is the audit trail. The state machine is the guardrail.

The itch was simple: AI agents are useful once the work unit is clear, bounded, and recoverable. A chat message is too soft. A full project-management app is too much furniture.

agent-tickets keeps the work unit in the boring place that already survives: markdown files in the repo, with YAML frontmatter for the parts machines need to trust. Humans and agents look at the same object. No hidden database truth, no separate dashboard reality.

The current shape is a Go CLI with markdown ticket cards, initiative folders, finite lifecycle states, hard dependencies, soft awaits, retry limits, and optional agent-mux dispatch/reconciliation. No server. No database. No hidden queue service. It can run fully offline as a local work ledger, or it can hand eligible cards to async workers when agent-mux is available.

The important concept is the split between initiative and ticket. An initiative is the small operating manual for a repeated kind of work: objective, conventions, routing, quality bar, and default worker shape. A ticket is the immediate scope: what needs to happen now, what done means, and where the result goes.

This matters because cold-start agents need contracts, not vibes. The card gives them context and scope, and it can be pasted directly into an agent as the prompt. The lifecycle gives the coordinator a recoverable state machine. The git diff gives the human a review surface. Gaal can later tell which session touched what. agent-mux can dispatch the worker. Pratchett-OS gets a durable execution trail instead of a fading chat memory.

It evolved through a few less-clean versions: plan-coupled markdown cards, a flat backlog, a SQLite state machine, and then the current initiative-scoped file system. The final version is deliberately less clever than the prototypes. At this scale, files are enough, diffs are useful, and a single Go binary is easier to trust than a small stack of services.

Status as of May 2026: public repo, daily-use tool inside Pratchett-OS, and the missing middle between "I should do this later" and "spawn an autonomous worker now." Not a grand OS. Just a proper little work ledger for agents that need to finish jobs instead of merely discussing them.

Repo: buildoak/agent-tickets. Related organs: agent-mux, Gaal, and Pratchett-OS.