Trails and tickets

A trail is a map of decision tickets with blocking edges; agents work the ready ones and you make the calls that need you.

#The trail map

Every trail has a destination (what done looks like) and these sections, stored in the trail's map.md:

Section	What it holds
Destination	One or two sentences: what done looks like.
Notes	Context worth keeping.
Assumptions	What the plan relies on and could turn out wrong. See Assumptions and reroutes.
Decisions so far	One line per decision, added as tickets close.
Not yet specified	Known unknowns. A line can be promoted to a ticket later.
Out of scope	What the trail won't do, with the reason.

A trail runs in one of two modes: plan+execute (default) or plan-only, which disables execute tickets.

#Ticket types

Type	Used for	Needs you?
`research`	Things an agent can find out alone.	No
`junction`	Decisions only you can make. The agent asks, you answer.	Yes
`prototype`	Something to try before deciding. You judge the result.	Yes
`task`	Checks and chores. `hitl: true` when you must do or approve it.	When `hitl`
`execute`	Implementation, once its decisions are made.	When `hitl`
`review`	An independent review of another ticket's work, created by verification.	No

blockedBy wires tickets together: a ticket is ready only when everything it's blocked by is closed.

#Ticket phases

Phase	Meaning
`backlog`	Waiting on blockers, or parked on a `plan-only` trail.
`ready`	Nothing blocks it; any agent can claim it.
`working`	Claimed by an agent.
`verifying`	Completed and being checked. See Verification and criteria.
`rework`	Checks failed; back to an agent with the output.
`blocked`	Waiting on you (failed too often, can't verify, or needs your approval).
`done`	Closed with a resolution and a decision record.
`cancelled`	Ruled out of scope, or cancelled by an approved reroute.

Every phase change goes through one transition table in code and is appended to the trail's journal.

#Claims are leases

A claim lasts 15 minutes, and every tool call from the claiming agent renews it, including waits on ask_human. If the agent goes silent, the lease expires and the ticket goes back to the queue with a Returned to queue comment holding the agent's progress notes and decisions. The next agent gets it as a resume. Change the length with --lease-minutes or $TEAMTRAIL_LEASE_MINUTES. In the Lookout, tickets close to expiry show as Stalled, and you can release them by hand.

#Decisions

Closing a ticket records a decision record: the question, the decision, a summary, the alternatives, the rationale, who decided and, for HITL tickets, the transcript. Agents can also keep other decisions with record_decision. Every decision shows in the Decisions view and in the briefing, marked as made by you or by an agent, and a later decision can supersede an earlier one. See File formats.

#Where it's stored

As markdown in .teamtrail/<trail>/, or as issues in GitHub or Linear, with the same body format.