/architect

name: architect
description: >-
  Writes the design docs before code (SOURCE_OF_TRUTH.md,
  ARCHITECTURE_ROADMAP.md, TODO_WORKFLOW.md, CLAUDE.md) and audits existing
  docs against the code.
when_to_use: >-
  Use unasked when a new app, feature, or workstream starts with no design
  docs, or to wire one missing fact into existing docs. Run "architect
  audit" when docs may have drifted from code. Also on "architect", "design
  doc", "spec this out", "roadmap", "audit the docs". Not for a small fix
  current docs already cover or for implementing an already-designed phase:
  just code.
argument-hint: "[what you're building]   ·   add 'audit' to check existing docs for drift"
effort: high

!`ls -1 SOURCE_OF_TRUTH.md ARCHITECTURE_ROADMAP.md TODO_WORKFLOW.md CLAUDE.md docs/architecture 2>/dev/null || true`

The line above lists which design docs already exist in this repo, so create-vs-audit mode is known before the first tool call.

Architect

Design and document the system before building it — in the house doc format, kept in sync at all times. Output is **documents, not code.**

Principles

Enforced *in the docs*: **model first** (data + invariants before framework) · **enforce every invariant at the core**, ideally at *two* boundaries (app-layer validation **and** a DB constraint) — never "the frontend handles it" · **design failure paths** as deliberately as happy paths · **small, reversible, independently shippable steps** · **one source of truth** — everything else derives from it and links back.

Proactive use

If a new app, feature, or workstream is starting and no current design docs exist, invoke this without being asked: announce in one line — "Running architect: <why>" — and proceed. Never ask permission to run the skill; the 1–3 blocking questions below are still allowed.

The four artifacts (+ the modular set)

Authority flows top-down. A fact lives in exactly one place and is linked from everywhere else.

1. **`SOURCE_OF_TRUTH.md`** (apex) — the canonical, slow-changing truth: scope & non-goals · the domain model · the **invariants** and *where each is enforced* · the load-bearing decisions as mini-ADRs (*decision · why · alternative rejected*). If anything conflicts with this file, this file wins. Keep it tight — it is the contract, not the manual. 2. **`ARCHITECTURE_ROADMAP.md`** — architecture + phased plan derived from the SoT. Header block (`Version · Status · Owner`), then §-numbered: `0` Executive context · `1` Tech stack (Layer · Tech · Role table) · `2` Data schema (low-level: columns, types, constraints, indexes, JSONB shapes, decision call-outs) · `3` Backend (structure · services · API-contract table · failure paths: per component, what fails and what happens next) · `4` Frontend · `5` Execution phases · `6` Non-functional requirements. 3. **`docs/architecture/00-index.md` + `01-…NN`** (larger projects only) — agent-friendly modular extracts of the roadmap sections. The index carries a **File Map** table (# · file · covers · roadmap §), a **Dependency Graph** (ASCII), and a **Quick Reference** ("I need to work on X → read these files"). 4. **`TODO_WORKFLOW.md`** — the task tracker. Status legend (`[ ]` · `[IN PROGRESS]` · `[FINISHED - PENDING MERGE]` · `[MERGED/DONE]` · `[BLOCKED]`); tasks grouped by phase; each row: `# · Task · Architecture Ref (linked to the §/file) · Status · Branch`. A task closed mid-phase leaves a `Left for <id>: ...` note for whoever picks it up next. 5. **`CLAUDE.md`** (project root) — the rules file Claude Code auto-loads: operating rules + the sync protocol (template below). One markdown file — no `.clauderules`, no `.cursorrules`, no import shim.

Sync protocol — the docs are never allowed to drift

This is the whole point. Bake it into `CLAUDE.md` and obey it yourself:

• **Top-down, docs-before-code.** A change to any architectural fact updates

`SOURCE_OF_TRUTH.md` first (if it touches a truth/invariant/decision), then `ARCHITECTURE_ROADMAP.md`, then the affected `docs/architecture/NN-*.md`, **then** the code. Never ship a change the docs don't yet describe.

• **One fact, one home, many links.** A detail is defined once and referenced by

link elsewhere. Every doc header links to the others.

• **TODO tracks reality.** Every task cites the arch §/file it implements; a task

that changes architecture names the doc it updated; statuses are current.

• **Definition of "synced":** no architectural claim in code that isn't in the

docs · no dead cross-links · `00-index` File Map matches files on disk · TODO statuses match git reality.

`audit` mode

Given `architect audit`, do **not** author — verify sync and report drift: code facts missing from the docs, dead links, index/file mismatches, stale TODO statuses. Output a prioritized fix list and offer to apply it.

Every drift item cites **both sides**: the `file:line` in code that states the fact, and the doc (+ § or line) that should describe it and doesn't. No item without both is a finding — it's a hunch, and hunches don't go in the list.

`CLAUDE.md` template (generalize to the project)

# <Project> — Rules

Stack: <one-line stack summary>.

## Commands

| Scope | Install | Test | Lint | Format |
|---|---|---|---|---|
| root | `<cmd>` | `<cmd>` | `<cmd>` | `<cmd>` |
| <package> | `<cmd>` | `<cmd>` | `<cmd>` | `<cmd>` |

Note any package-manager quirk here (workspaces, monorepo tool, pinned version).

## Git (mandatory, no exceptions)
- Open `feature/<topic>` branch BEFORE first edit. Never commit to `main`.
- Micro-commit per logical step. Conventional Commits (feat/fix/refactor/chore/docs/test).
- Commits are authored by the repo owner alone — never add an AI co-author or `Co-Authored-By` trailer, never mention AI in commit messages or PRs.
- Never delete branches. Never force-push. Never skip hooks. PRs only.

## Workflow
1. Locate the task in `TODO_WORKFLOW.md`; mark `[IN PROGRESS]`;