Skip to content
Tabletop Tracker

ADR-0012: Work items — GitHub Issues plus in-repo specs

ADR-0012: Work items — GitHub Issues plus in-repo specs

  • Status: Accepted
  • Date: 2026-07-30
  • Supersedes: —
  • Superseded by: —

Context

The delivery loop needs work items that agents can query, claim and update, and that collaborators can see without a checkout. GitHub is already fixed as the source host (non-negotiable per docs/architecture.md §1).

Two media are available and they have opposite strengths. Issues give cheap, conflict-free state changes and a queryable API. Repo markdown gives version history, review-in-PR, and colocation with the code it describes.

Decision

Use both, split by role:

  • GitHub Issue — the ticket. Status via labels, dependencies via issue links, the loop’s running log via comments. Driven by the gh CLI.
  • docs/work/WI-###-slug.md — the spec. Problem, scope, out of scope, Definition of Done, verification commands. Versioned with the code and reviewable in the PR.

The issue links to the spec; the spec’s frontmatter carries the issue number.

Rationale

Status changes many times per work item and must never conflict between parallel agents — that is an Issues job. The spec changes rarely, must be reviewed, and must be readable at the commit that implemented it — that is a repo job.

Putting status in markdown makes parallel agents fight over the same files. Putting the spec only in an issue makes it unreviewable and invisible to the docs subsite.

Consequences

  • gh issue list --label status:ready is the agent’s work queue. Label hygiene is therefore load-bearing, not cosmetic.
  • Specs are picked up by the docs subsite (ADR-0013) automatically, so collaborators see the backlog at a URL.
  • Creating a work item means creating both artefacts. The issue template prompts for the spec path.
  • Label vocabulary is defined once in docs/standards/work-items.md and materialised in .github/labels.yml.

Alternatives considered

Pure markdown in the repo. Fully self-contained and auditable. Rejected: parallel agents conflict on status edits, and collaborators need a checkout to see the board.

GitHub Projects v2 board. Nicer human view with custom fields. Rejected for now: the GraphQL API is materially clunkier for agents than plain Issues. Can be layered on top later without changing this decision.

External tracker (Linear/Jira). Richer PM features. Rejected: a service outside the £0 constraint and a second auth surface for agents.