Skip to content
Tabletop Tracker

WI-005: Author the ADR catalogue and standards

WI-005: Author the ADR catalogue and standards

Problem

Agents need the rules before they need the scaffold. docs/architecture.md held ADR-1..7 inline as prose; decisions from the delivery-system planning conversation were unrecorded; and no standards existed, so nothing defined what “done” meant.

This is a bootstrapping item: it was authored ahead of WI-002, because the standards are what every later work item is held to.

In scope

  • Extract ADR-1..7 from docs/architecture.md §3 into numbered MADR files, unchanged in substance.
  • Author ADR-0008..0015 from the planning conversation, and ADR-0016..0017 for the catalogue seeder.
  • docs/decisions/README.md as the hand-maintained index.
  • The ten standards in docs/standards/.
  • docs/work/README.md — the backlog and dependency graph.
  • M0 specs WI-001..006.

Out of scope

  • Changing any decision’s substance during extraction. ADR-0001..0007 must say what §3 said.
  • Reworking docs/architecture.md itself — that is WI-050-adjacent cleanup, tracked separately.
  • Specs for M1–M4 items, which are written at step 1 of the loop when each is picked up.

Definition of done

  • docs/decisions/ contains ADR-0001 through ADR-0017, each with Status / Date / Supersedes / Superseded by.
  • ADR-0001..0007 are faithful to docs/architecture.md §3 — verified by reading both side by side.
  • Every ADR has a populated Consequences section including downsides, and Alternatives considered with a specific reason each lost.
  • docs/decisions/README.md lists all 17 with working links.
  • All ten standards exist, each stating rules rather than describing the codebase.
  • docs/standards/the-loop.md is self-contained enough that a fresh agent with no conversational context can execute a work item from it alone.
  • docs/work/README.md has a dependency graph consistent with every spec’s depends_on.
  • Every file has title and description frontmatter for Starlight.
  • Every internal link resolves.

Verification

Author-time review is the verification for a docs-only item — there is no test to run. Concretely:

  1. Read docs/decisions/README.md and follow every link; none 404.
  2. Diff ADR-0001..0007 against docs/architecture.md §3 for substantive drift.
  3. Hand docs/standards/the-loop.md plus one M1 spec to an agent with no other context and confirm it can state what it would do, in order, and when it would stop.
  4. Once WI-004 lands, pnpm --filter docs build reports no broken links.

Notes

Authored before the scaffold existed, which is why its depends_on is empty despite being numbered in M0. The ordering in docs/architecture.md §6 is about build sequence; this item is about having rules to build under.

The the-loop.md cold-start check is the real acceptance criterion. If a fresh agent can’t run the loop from that document alone, the document is wrong regardless of how complete it looks.