Plan: Docs harmonization — SOTA restructure

How-to — active implementation plan. Moves to ../archive/ when complete.

Status: in flight (2026-04-21)
Owner: solo (Claude Code session)
Spec: n/a — scoped directly in session dialogue; this plan IS the design artifact

Goal

Fold ~35 docs (~14k lines) spread across plans/, docs/, and root-level files into a single Diátaxis-structured docs/ tree. Adopt OSS SOTA patterns: ADR decision log, C4 Mermaid architecture, live status single source, glossary, docs-as-code discipline. Preserve all superpowers UX/UI brainstorm content.

Why

3 concurrent sources of truth for “what’s done” (ROADMAP, FEATURES, TaskList)
Plans never archived — flat plans/ mixes active/completed/tactical daily runs
No entry point — new reader couldn’t navigate
Tech-stack bullets buried in CLAUDE.md, decision rationale scattered across ROADMAP + memory + plans
.impeccable.md duplicated design tokens that live in code

Target structure

/README.md                         new — entry + nav
/CONTRIBUTING.md                   new — workflow + doc-maintenance triggers
/CHANGELOG.md                      keep
/CLAUDE.md                         keep (extended w/ Diátaxis matrix)
/.impeccable.md                    thin pointer → docs/design-system.md

/docs/
  README.md                        new — sitemap w/ quadrant index
  getting-started.md               new — tutorial
  architecture.md                  new — C4 Mermaid + tech stack
  design-system.md                 new — absorbs .impeccable.md + design-tokens
  infrastructure.md                new — absorbs docs/infra-comparison.md
  testing.md                       new — absorbs plans/e2e-test-plan.md
  roadmap.md                       new — absorbs ROADMAP + FEATURES
  status.md                        new — single live status table
  glossary.md                      new — domain terms

  decisions/                       new — 21 ADRs (MADR lite)
    README.md                      format + sub-topic index
    0001 … 0021

  specs/                           moved from plans/specs/
  plans/                           active impl plans only
  research/                        moved from plans/research/

  archive/2026-Q2/                 quarterly freeze
    autonomous-runs/               nightly runs
    plans/                         completed impls + superseded blueprints
    docs/                          legacy docs

Execution phases

Phase 1 — Move existing files (git mv)

Phase 2 — Write new skeleton docs (4 parallel agents)

docs/architecture.md — 349 lines, C4 L1+L2 + sequence diagrams
docs/design-system.md — 283 lines, absorbs .impeccable.md + design-tokens
docs/infrastructure.md — 236 lines, absorbs docs/infra-comparison.md
docs/testing.md — 224 lines, absorbs plans/e2e-test-plan.md
docs/roadmap.md — 232 lines, absorbs ROADMAP + FEATURES matrix
docs/status.md — 74 lines, live single-source tracker
docs/README.md, docs/glossary.md, docs/getting-started.md, docs/decisions/README.md — solo
README.md, CONTRIBUTING.md at repo root — solo

Phase 3 — Write ADRs (parallel agent + solo)

20 ADRs written by subagent (0001-0020)
ADR 0021 (central fonts registry) written solo (just-shipped decision)

Phase 4 — Delete legacy

ROADMAP.md → content absorbed, removed
FEATURES.md → content absorbed into roadmap + status, removed
agent-state.md → TaskList + memory own this, removed
.impeccable.md → replaced w/ thin pointer to docs/design-system.md
.gitignore — remove docs/ private-ignore; adds .superpowers/ if missing
Stale worktrees removed: agent-a680b77f, agent-ad665e05

Phase 5 — Wire AI agent discipline

Update CLAUDE.md — add Diátaxis matrix + doc-maintenance trigger table so every session knows when to update which doc.

Phase 6 — Commit & push

Single atomic commit: docs: harmonize to Diátaxis structure (ADR + C4 + single status)
Push to main (direct-push per MVP 0 convention)

Counts

Metric	Before	After
Top-level `*.md`	5	4 (README + CONTRIBUTING + CHANGELOG + CLAUDE) + .impeccable pointer
Active plan docs	28 flat	~10 organized (specs/plans/research split)
Archived docs	0	20+ in `archive/2026-Q2/`
Decision records	0 (scattered)	21 ADRs in `decisions/`
Live status sources	3 (ROADMAP checkboxes, FEATURES, TaskList)	1 (`status.md` + TaskList)
Tech-stack source	2 (CLAUDE.md + blueprint)	1 (`architecture.md`)
Design-system source	3 (.impeccable.md + design-tokens + tailwind)	1 (`design-system.md` — others reference)

SOTA patterns adopted

Diátaxis — every doc tagged tutorial / how-to / reference / explanation
ADRs (MADR v3 lite) — immutable, numbered, supersedable
C4 model diagrams — Mermaid, renders on GitHub, versioned w/ code
Single status source — docs/status.md replaces scattered checkboxes
Plan lifecycle — docs/plans/ active → docs/archive/YYYY-QN/ when complete
Specs lifecycle — docs/specs/ immutable after dated, absorbed into roadmap
Glossary — domain terms centralized, not restated per-doc
CLAUDE.md doc-maintenance matrix — agent sessions know which doc to touch per change type

Not adopted (YAGNI for now)

Auto-extracted tech-stack table from package.json — build complexity > value at this scale
Docs link-check CI — can add later if rot observed
Versioned spec footers (commit SHA of “locked”) — add when we supersede first spec
ADR auto-numbering hook — current manual numbering works at <100 ADRs

Open items after this lands

Run link-check locally once (markdown-link-check or similar) to verify no broken cross-refs
Consider adding docs/CODEMAPS/ if doc-updater agent flow is adopted (future)
Split ADR 0003 (NestJS+Fastify) into 2 if Fastify-specific decisions emerge