[RUNBOOK] Phase 2 — MVP rule set + token adapters

[aram-devdocs]

Summary

Ship the remaining 5 MVP rules (color/palette, radius/scale,
sibling/height, a11y/touch-target, edge/near-alignment), the full
config schema (color, radius, alignment, a11y), and adapters that
let teams reuse existing token sources — DTCG, Tailwind config,
CSS custom properties.

By the end of this phase, 8 rules operate end-to-end against real
design-system configs and plumb init can bootstrap from a
Tailwind project.

PRD references

• PRD §11.2
• PRD §11.3
• PRD §12.2
• PRD §12.3
• PRD §12.4
• PRD §13.2
• PRD §15.3
• PRD §15.4

Acceptance criteria

• 8 rules emit findings on a dogfood fixture with zero false positives.
• DTCG 2025.10 adapter round-trips a Tokens Studio export.
• Tailwind adapter round-trips a real tailwind.config.ts.
• plumb init detects Tailwind and scaffolds plumb.toml.
• All 13 child PRs merged.

Batches

Gates run sequentially (every PR in Gate N must merge before Gate N+1 starts). Within a gate, batches are parallel. For each batch, a recommended dispatch strategy is shown — you can always pick a different shape if it fits. See .agents/rules/dispatch-strategy.md for the heuristic.

Gate	Batches	Tickets	After
Gate 1	2A	#21 #22	(initial)
Gate 2	2B, 2C	#23 #24 #25 #26 #27 #28 #29 #30	Gate 1 merged
Gate 3	2D	#31 #32 #33	Gate 2 merged

---

Gate 1

Batch 2A — Config shape — remaining sections + span-annotated errors

#	Ticket	Crate	Effort	Extras
#21	[color], [radius], [alignment], [a11y] sections + schema	plumb-config	M	—
#22	span-annotated validation errors via miette	plumb-config	M	—

Dispatch (bundle): same crate, similar effort — bundling keeps related changes atomic.

/gh-issue 21 22 --worktree

Advance to Gate 2 when: every PR in Gate 1 is merged.

Gate 2 after Gate 1

2 parallel batches (2B, 2C) — every batch below can run concurrently. Each batch still has its own recommended shape.

Batch 2B — Remaining MVP rules (5 parallel implementations)

#	Ticket	Crate	Effort	Extras
#23	rule color/palette-conformance (Oklab ΔE00)	plumb-core	L	—
#24	rule radius/scale-conformance	plumb-core	S	—
#25	rule sibling/height-consistency	plumb-core	M	—
#26	rule a11y/touch-target	plumb-core	S	—
#27	rule edge/near-alignment	plumb-core	M	—

Dispatch (cluster): mix of small and large — bundle 4 small, split 1 large to keep review <400 LOC.

/gh-issue 24 25 26 27 --worktree   # 4 small: one bundled PR
/gh-issue 23 --worktree   # L: rule-color-palette-conformance

Batch 2C — Token adapters — DTCG + Tailwind + CSS custom properties

#	Ticket	Crate	Effort	Extras
#28	DTCG 2025.10 token adapter	plumb-config	L	security
#29	Tailwind config adapter	plumb-config	L	security
#30	CSS custom-properties scraper	plumb-config	S	—

Dispatch (cluster): mix of small and large — bundle 1 small, split 2 large to keep review <400 LOC.

/gh-issue 30 --worktree
/gh-issue 28 --worktree   # L: config-dtcg-adapter
/gh-issue 29 --worktree   # L: config-tailwind-adapter

Advance to Gate 3 when: every PR in Gate 2 is merged.

Gate 3 after Gate 2

Batch 2D — Developer experience — JSON output, selector scoping, init

#	Ticket	Crate	Effort	Extras
#31	--format json deterministic key ordering	plumb-format	S	—
#32	--selector flag scoping lint to subtree	plumb-cli	S	—
#33	plumb init with Tailwind detection	plumb-cli	M	—

Dispatch (split): touches 2 crates — split so each gets focused review.

/gh-issue 31 --worktree
/gh-issue 32 --worktree
/gh-issue 33 --worktree

Phase gate follows — see below.

Phase gate

just validate green AND 8 rules produce findings with zero false
positives on the dogfood fixture AND plumb init scaffolds a usable
plumb.toml from a Tailwind project AND cargo xtask pre-release
green AND just determinism-check holds on JSON output.

Unblocks: phase-3

How to execute

1. Create GitHub milestone v0.2-phase-2 if it doesn't already exist.
2. Run bash create-issues.sh from this directory to create all child issues.
3. Dispatch /gh-issue <child-number> for each batch in order; sessions within a batch run in parallel.
4. Close this parent issue when every child is merged and the phase gate holds.

Generated

• Generated at: 2026-04-24T13:16:33Z
• Source spec: docs/runbooks/phase-2-spec.yaml
• Repo: aram-devdocs/plumb