# Track is the mainline

Shipping one change touches many records: a ticket, a todo in an iteration, a
branch and a pull request, pipelines, a test run, a delivery and its tag. In a
usual setup they live in four or five tools, and someone keeps the tracker in
step with the code by hand. Acahti keeps all of them in one instance, so it can
join them into one line per piece of work: **Track**.

## Flows and stages

A **flow** is one piece of work followed through. Tickets, todos, iterations,
deliveries and failing Argos cases each have one. Every flow runs along the same
eight stages, in this order:

<ol class="rail" aria-label="Track stages and their evidence">
<li><b>Reported</b><span>Ticket</span></li>
<li><b>Planned</b><span>Todo, iteration, documents</span></li>
<li><b>In progress</b><span>Todo status</span></li>
<li><b>Review</b><span>Pull request</span></li>
<li><b>Build</b><span>Pipeline</span></li>
<li><b>Argos</b><span>Argos run</span></li>
<li><b>Delivered</b><span>Delivery, tag pipeline</span></li>
<li><b>Released</b><span>Release, verified ticket</span></li>
</ol>

A flow shows the stages its type expects (a bug, a feature, a todo, ops work, an
Argos case, an iteration) and any other stage it has evidence for. Work managers
adjust a type's template, or one flow where reality differs. The stages and
templates are listed in [Track](track.md#stages).

## Evidence moves the flow

A stage is reached when a record for it appears. Each stage is done, current,
upcoming, failed or skipped, and an unfinished flow reports how long it has been
stuck. Nobody keeps a status field in step with the code:

- **Name the work and it links itself.** A pull request whose title, body or
  branch names `todo#123`, `ticket#45`, `todo/123` or `T-123`, and a pipeline
  whose commit, branch or pull request does, join that flow under Review and
  Build. A delivery's tag pipelines show under Delivered.
- **Agents link as they work.** The skill has agents name the todo in the branch
  and commit; `planning_todo_links` attaches a pull request, pipeline or Argos
  run by hand.
- **Tests report back.** A pipeline step running `argos run … --dash` streams
  its run to the instance, and a failing case opens its own flow, from the first
  failure to green again.

## Everything hangs off the line

Because Track reads the same records the rest of the app writes, every tab is a
view of some part of it:

| Tab | Its part of the line |
|---|---|
| [Tickets](work.md) | Where flows are reported, and verified at the end |
| [Projects](projects.md) and [iterations](iterations.md) | Where work is planned, delivered and released |
| [Repos](repos.md) | Branches and pull requests: Review |
| [Pipelines](pipelines.md) | Build, deploy and tag runs |
| [Argos](testing.md) | Test runs, and failing cases as flows of their own |
| [Knowledge](knowledge.md) | Documents linked to a flow, shown under Planned |
| [Board](board.md) | What needs you now across all of them |

## Read it three ways

- **One item.** Every todo and ticket page has a Track card: the stage rail, and
  a timeline of when each stage was reached, by whom, and the records behind it.
- **Every open flow.** **Track** in the header lists open work by project, with
  each flow's stages, its current stage and how long it has been stuck.
- **One person.** The People view shows what a person (or an agent) moved over
  the last 7, 14 or 30 days: work, commits, pull requests, reviews and pipelines.

![Track in a synthetic example workspace](/images/track.png "Track lists every open flow by project, with its stages, current stage and time stuck.")

Agents read the same thing: `track_get` returns one flow, `track_list` the open
ones and `track_activity` one person's. See [Track](track.md) for every view, filter and operation.