ADR-0016: GitHub issues and the Projects board are the central trellis work system

Status: accepted (2026-07-09)

Context

Work organization on this box grew several overlapping, half-built mechanisms that each captured a piece of one job - get work out of a session’s head, track it, dispatch it - but none was the whole thing:

• the user-level spinoff queue (~/work-queue.md, cross-repo, flock-serialized, ~/.claude/skills/spinoff);
• the trellis-board skill’s “basket” candidate convention (bare gh issues, a candidate label, an idea: prefix);
• a 2026-07-07 issue-driven-workflow draft spec.

The cost was a split: trellis work lived partly in spinoff entries and partly in ad-hoc issues, so what was visible depended on where it happened to be filed. The spinoff queue had accumulated trellis-desktop work (the four-modes-* entries; one of them, four-modes-awaiting-truth, was ALSO already issue #36) alongside genuinely-ward-os items.

The 2026-07-09 issue-dispatch-loop spec (docs/specs/2026-07-09-issue-dispatch-loop-design.md) unified these into one design: issues as the single work currency, the Projects v2 board (issue #23) Status field as the lifecycle spine, dispatched fresh sessions carrying planning->build momentum with a per-task model/effort hand-off, all gated by Sam’s manual test gate. Two prerequisites are now met: the board exists (user project #3 “trellis board”, the six Status columns, linked to the repo, populated), and the agent classic PAT (ADR-0015) has gained the project scope.

Decision

GitHub issues on sam-henry-dev/trellis, organized by the Projects v2 board (#3) Status field, are THE central work system for trellis. The 2026-07-09 issue-dispatch-loop spec is adopted as its design; it is built in the spec’s four phases, each a reviewed PR.

• trellis capture / digest / dispatch run as trellis-agent. This extends ADR-0015: trellis-agent is a write collaborator on the repository AND on the project board. The project scope lives on the trellis-agent PAT, superseding #23’s plaintext-hosts.yml wording.
• spinoff (~/work-queue.md) is RETIRED FOR TRELLIS WORK: trellis tasks are board issues, not queue entries. spinoff remains only for genuinely non-trellis / cross-repo dispatch, if any survives. The live four-modes-* entries migrate onto the board (see docs/plans/2026-07-09-spinoff-to-board-migration.md); the ward-os queue entries are retired as obsolete pending Sam’s confirmation (ward-os is HISTORICAL; the NVMe migration already happened at the 2026-07-07 install).
• The trellis-board skill’s “basket” convention is superseded by “candidates” (per #23) and delegates capture to trellis capture.
• The 2026-07-07 issue-driven-workflow draft is removed (provenance in git history); the 2026-07-09 spec is canonical.

Alternatives considered

• Keep spinoff as the trellis dispatcher: it is user-level and cross-repo, has no per-issue lifecycle or test gate, offers no GitHub surface for phone / hand-off, and duplicates the board. Rejected for trellis; kept for non-trellis.
• Labels instead of a board Status field (the draft’s ready label): #23 already rejected this - built-in workflows cannot sync labels to Status, so it means two hand-maintained copies of one fact.
• Leave the machinery parallel (do nothing): the split IS the problem; work is invisible depending on where it was filed.

Consequences

• One surface for trellis work: the board is the single source of truth; digest and dispatch read it, capture writes it. The phone Claude app and the GitHub app become first-class hand-off surfaces (the issue trail carries the context).
• This ADR records the direction; the phased plans carry the build (docs/plans/2026-07-09-dispatch-loop-phase1-capture-board.md is Phase 1). The board-writing verbs stay blocked until trellis-agent has Write access on project #3 - a Sam grant, mirroring the ADR-0015 repo-collaborator grant.
• The four-modes epic’s remaining work moves onto the board.
• spinoff’s SessionStart heads hook and skill scope note are updated so trellis work no longer routes through it.