Skip to content

ADR-0013: GitHub issues are the task specifications

Status: Accepted · Date: 2026-10-19

Context

Tasks are implemented by humans and by AI agents (Claude Code, Grok, Codex …) and reviewed by humans. An agent needs a spec it can parse and cannot misread. A reviewer needs the same spec, to check the PR against it.

Decision

  • Each task is one GitHub issue, labelled task, in a GitHub milestone (M1, M2, M3).
  • The issue body follows .github/ISSUE_TEMPLATE/task.md:
  • a fenced yaml manifest: task, milestone, depends_on, blocks, requirements, adrs, touches, migration, contract_change, closes_todos, verify;
  • human sections: Context, Decisions already made, Scope, Out of scope, Acceptance criteria (AC-n, Given/When/Then, each mapped to a named test), Definition of done.
  • Dependencies are recorded both in the manifest (task ids) and as GitHub "blocked by" relationships. A task is ready when every blocker is closed.
  • Precedence: AGENTS.md invariants > the ADRs > the issue > the docs prose. If an agent finds a contradiction or a gap, it stops and comments on the issue with a proposed resolution. It does not guess.
  • docs/roadmap.md keeps milestones, exit criteria and the dependency graph, and links each task to its issue. The issue is the source of truth for task scope and status.
  • A PR closes exactly one task issue (Closes #n). Its title starts with the task id.

Consequences

  • + Reviewable, parseable, parallelisable (the graph shows which tasks can run at once).
  • − Scope changes must be edited in the issue, not only in the docs.