Generate a detailed design document via `tx doc add design`. Covers architecture, interfaces, data model, invariants, failure modes, verification, and testing strategy. References plan via file path instead of embedding. Plan lives in ~/.claude/plans/<name>.md. Reads companion PRD automatically to map EARS requirements to invariants. Output lands in specs/design/<name>.md.
Generate a detailed design document via `tx doc add design`. Covers architecture, interfaces, data model, invariants, failure modes, verification, and testing strategy. References plan via file path instead of embedding. Plan lives in ~/.claude/plans/<name>.md. Reads companion PRD automatically to map EARS requirements to invariants. Output lands in specs/design/<name>.md.
argument-hint
<feature-or-component-name>
Generate Design Document
Create a comprehensive technical design document using the tx doc primitive. Design docs specify HOW the system implements requirements, with traceable invariants and a concrete testing strategy.
Design Doc + PRD are companions. A PRD defines WHAT and WHY. A design doc defines HOW. If a PRD exists for this feature, the design doc reads it automatically and maps every must-priority EARS requirement to an invariant + verification entry.
Workflow State Machine
START
│
▼
┌─────────────────────────────────────────────────────┐
│ Step 0: PLAN GATE │
│ │
│ Is there an active plan in this conversation? │
│ │
│ ├─ YES → Save plan to `~/.claude/plans/<name>.md` if not │
│ │ already saved. Set `plan: ~/.claude/plans/<name>.md` │
│ │ in frontmatter. │
│ │ → Continue to Step 0.5 │
│ │ │
│ └─ NO → Tell the user to run /plan first. │
│ If enough detail provided, generate plan, │
│ save to `~/.claude/plans/<name>.md`. │
│ → Continue to Step 0.5 │
└─────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────┐
│ Step 0.5: CHECK FOR COMPANION PRD │
│ │
│ Run: tx doc list --kind prd │
│ │
│ ├─ PRD exists for this feature? │
│ │ → tx doc show <prd-name> --md │
│ │ → Extract ALL EARS requirements │
│ │ → Each `must` EARS req MUST get an invariant │
│ │ and a verification entry in this design doc │
│ │ → Set `implements: <prd-name>` in frontmatter │
│ │ → Continue to Step 1 │
│ │ │
│ └─ No companion PRD? │
│ → Continue to Step 1 (design doc stands alone) │
│ → Suggest creating PRD after: /prd <name> │
└─────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────┐
│ Step 1: SCAFFOLD via tx │
│ │
│ tx doc add design <name> --title "<title>" │
│ ├─ SUCCESS → Continue to Step 2 │
│ └─ FAIL (exists) → Edit existing doc │
└─────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────┐
│ Step 2: DEEP CONTEXT GATHERING │
│ │
│ Read: ARCHITECTURE.md, QUALITY.md, CLAUDE.md, │
│ domain code, schema.ts, effect-schemas, │
│ API routes, workflows, activities, │
│ existing designs (tx doc list --kind design) │
│ → Continue to Step 3 │
└─────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────┐
│ Step 3: FILL DOCUMENT │
│ │
│ Write `# Plan` first (reference to plan file from │
│ Step 0). │
│ Then fill all sections from plan + PRD + codebase. │
│ │
│ MINIMUM THRESHOLDS: │
│ - Invariants: ≥ 5 │
│ - Failure modes: ≥ 3 │
│ - Verification entries: ≥ 5 │
│ - Integration test files: ≥ 2 (HARD REQUIREMENT) │
│ - Unit test files: ≥ 1 (recommended, not hard) │
│ - Sequence diagrams: ≥ 2 (happy + error) │
│ - Design decisions: ≥ 1 │
│ │
│ Integration tests are the primary verification │
│ mechanism. Unit tests complement but do not replace │
│ integration tests. │
│ │
│ RULE: No section may be left as a template/stub. │
│ │
│ COMPREHENSIVENESS: The design doc must cover EVERY │
│ item from the plan. Every implementation step, │
│ constraint, risk, and decision in the plan must │
│ appear in the design doc with full technical detail. │
│ The design doc is the single source of truth for HOW │
│ the feature is built — it should be detailed enough │
│ that an engineer can implement from it alone. │
└─────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────┐
│ Step 4: SELF-AUDIT │
│ │
│ Check: │
│ ├─ Every plan item captured in a section? │
│ ├─ Every PRD `must` EARS req has an invariant? │
│ ├─ Every invariant has a verification entry? │
│ ├─ Minimums met? │
│ ├─ No stubs/placeholders? │
│ ├─ All diagrams complete? │
│ └─ Plan file exists at frontmatter path and is │
│ consistent with doc sections? │
└─────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────┐
│ Step 5: VALIDATE │
│ │
│ tx spec lint │
│ ├─ PASS → Continue to Step 6 │
│ └─ WARN/FAIL → Fix, re-validate │
└─────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────┐
│ Step 5.5: SYNC PLAN FILE │
│ │
│ Read the plan file from frontmatter `plan:` path. │
│ Compare with what the doc now contains. │
│ UPDATE the plan file to incorporate: │
│ - Architecture decisions, component inventory │
│ - Interface contracts, data model details │
│ - Invariants, failure modes, error handling │
│ - Implementation sequence, testing strategy │
│ The plan file must reflect the FULL current state │
│ of the feature — not just the initial draft. │
│ This is a MANDATORY step, not optional. │
└─────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────┐
│ Step 6: DISCOVER + LINK + REPORT │
│ │
│ tx spec discover --doc <name> │
│ tx doc link <prd> <design> (if PRD exists) │
│ tx doc show <name> │
│ tx spec gaps --doc <name> │
│ Print summary │
└─────────────────────────────────────────────────────┘
│
▼
DONE
Step 0 — Plan Gate
The plan is the primary input. Check for plan content in the conversation:
The plan is saved as a standalone file at ~/.claude/plans/<name>.md (relative to repo root).
If a plan already exists in the conversation, write it to that file.
If a plan file already exists at that path, read it instead.
If no plan and vague request, ask user to run /plan first.
The doc's frontmatter gets plan: ~/.claude/plans/<name>.md and the # Plan section contains a reference link + brief summary, not the full verbatim content.
Step 0.5 — Check for Companion PRD
tx doc list --kind prd
If a PRD exists for this feature:
Read it: tx doc show <prd-name> --md
Extract every EARS requirement
Every must-priority EARS requirement MUST become:
An invariant in invariants: YAML block
A verification entry in verification: YAML block
Set implements: <prd-name> in frontmatter
If no PRD exists, the design doc stands alone. Suggest creating one after.
Body Structure — ALL sections MUST have real content
# Plan comes first (as a reference to the plan file). Then all technical sections. No section may be a stub.
If a companion PRD exists, every must EARS requirement maps to an invariant + verification entry.
# Plan> Full plan: [~/.claude/plans/<name>.md](../~/.claude/plans/<name>.md)
<2-3 sentence summary of what the plan covers. The full plan lives in the file referenced above.>
# Summary
2-3 sentences on design approach and key technical decisions.
# Architecture## System Context
Where this feature sits in the existing system. Reference `docs/ARCHITECTURE.md`.
## Component Diagram
┌──────────────┐ ┌──────────────┐ ┌──────────────┐
│ organizations │────<│ teams │────<│ <entity> │
│ │ 1:N │ │ 1:N │ │
└──────────────┘ └──────────────┘ └──────────────┘
Invariants
MINIMUM: ≥ 5 invariants. If companion PRD exists, every must EARS req MUST map to an invariant.
invariants:-id:INV-<SCOPE>-001statement:<whatmustbetrue>
enforcement: <lint script | test | pgTAP>
traces_to: REQ-<SCOPE>-001 # link to PRD requirement if applicable
## Step 4 — Self-Audit
Re-read the plan file and verify:
1. **Comprehensiveness check**: Read the plan file. For EVERY item (implementation steps, constraints, risks, decisions), confirm it has full technical detail in the design doc. The design doc must be detailed enough to implement from alone.
2. If PRD exists: every `must` EARS req has an invariant. Every invariant has a verification entry.
3. HARD: ≥2 integration test files (blocking requirement). SOFT: ≥1 unit test file (recommended).
4. Minimums met: ≥5 invariants, ≥3 failure modes, ≥5 verifications, ≥2 sequence diagrams, ≥1 decision.
5. No stubs, no empty tables, no "..." placeholders.
6. All diagrams complete.
7. Implementation sequence lists real file paths.
8. Verify plan file exists at the path in frontmatter and its content is consistent with the doc sections.
## Step 5 — Validate
```bash
tx spec lint
Step 5.5 — Sync Plan File (MANDATORY)
After filling and validating the doc, update the plan file at the plan: frontmatter path to reflect everything the design doc surfaced. The plan file must be the living source of truth — not a stale initial draft.
What to add to the plan file:
Architecture decisions and their rationale
Component inventory and file paths
Interface contracts (API endpoints, port signatures, event payloads)
Data model details (tables, indexes, constraints)
Implementation sequence with specific file paths
Invariants, failure modes, and error handling strategies
Testing strategy and test file locations
Read the current plan file, merge in the new information, and write it back. Preserve the plan's structure but ensure it now covers the full technical design.
Step 6 — Discover, Link & Report
tx spec discover --doc <name>
tx doc link <prd> <design> # if PRD exists
tx doc show <name>
tx spec gaps --doc <name>
If PRD exists, show EARS→invariant mapping coverage.
List open questions.
Run tx spec lint.
If the plan file is modified later, update the # Plan summary and derived sections in this doc. If this doc's scope changes, update the plan file to stay consistent.
