Generate a system-level design document via `tx doc add design`. Covers cross-cutting architecture, service boundaries, data flows, scalability, and deployment topology. References plan via file path instead of embedding. Plan lives in ~/.codex/plans/<name>.md. Use for system-wide or multi-domain designs (vs /design-doc for feature-scoped).
Instalar com Codex ou Claude Copie este prompt, cole no Codex, Claude ou outro assistente e deixe que ele revise a página da skill e instale para você.
Um comando direto ignora o prompt de revisão. Verifique a origem antes de executá-lo.
Generate a system-level design document via `tx doc add design`. Covers cross-cutting architecture, service boundaries, data flows, scalability, and deployment topology. References plan via file path instead of embedding. Plan lives in ~/.codex/plans/<name>.md. Use for system-wide or multi-domain designs (vs /design-doc for feature-scoped).
argument-hint
<system-or-initiative-name>
Generate System Design Document
Create a system-level design document using the tx doc primitive. System design docs cover cross-cutting architecture spanning multiple domains. For single-feature designs, use /design-doc.
Workflow State Machine
START
│
▼
┌─────────────────────────────────────────────────────┐
│ Step 0: PLAN GATE │
│ │
│ Is there an active plan in this conversation? │
│ │
│ ├─ YES → Save plan to `~/.codex/plans/<name>.md` if not │
│ │ already saved. Set `plan: ~/.codex/plans/<name>.md` │
│ │ in frontmatter. │
│ │ → Continue to Step 1 │
│ │ │
│ └─ NO → Tell user to run /plan first. │
│ If enough detail, generate plan, save to │
│ `~/.codex/plans/<name>.md`. │
│ → Continue to Step 1 │
└─────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────┐
│ 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, DEPLOYMENT.md, │
│ ROLLBACK.md, RUNBOOKS.md, CLAUDE.md, │
│ schema.ts, workflows.ts, all infra packages, │
│ all existing specs (tx doc list) │
│ → Continue to Step 3 │
└─────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────┐
│ Step 3: FILL DOCUMENT │
│ │
│ Write `# Plan` first (reference to plan file from │
│ Step 0). │
│ Then fill all sections from plan + codebase. │
│ │
│ MINIMUM THRESHOLDS: │
│ - Invariants: ≥ 7 │
│ - Failure modes: ≥ 3 │
│ - Verification entries: ≥ 5 │
│ - Design decisions: ≥ 2 │
│ - Service boundaries: ≥ 3 │
│ - Data flow diagrams: ≥ 2 │
│ │
│ RULE: No section may be left as a template/stub. │
└─────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────┐
│ Step 4: SELF-AUDIT │
│ │
│ Every plan item captured? No stubs? Minimums met? │
│ All diagrams complete? Cross-cutting addressed? │
└─────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────┐
│ Step 5: VALIDATE │
│ │
│ tx spec lint │
│ ├─ PASS → Continue to Step 6 │
│ └─ WARN/FAIL → Fix, re-validate │
└─────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────┐
│ Step 6: DISCOVER + LINK + REPORT │
│ │
│ tx spec discover --doc <name> │
│ tx doc link <overview> <design> │
│ tx doc show <name> │
│ Print summary │
└─────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────┐
│ Step 6.5: SYNC PLAN FILE │
│ │
│ Read the plan file from frontmatter `plan:` path. │
│ UPDATE the plan file to incorporate everything │
│ the doc surfaced: service boundaries, data flows, │
│ design decisions, invariants, failure modes, │
│ deployment topology, scalability strategy. │
│ The plan file must reflect the FULL current state. │
│ This is a MANDATORY step, not optional. │
└─────────────────────────────────────────────────────┘
│
▼
DONE
Step 0 — Plan Gate
The plan is the primary input. Check for plan content in the conversation:
If the user ran /plan or was in plan mode, the plan is saved as a standalone file at ~/.codex/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 but detailed user request, generate a plan yourself (research the codebase, think through topology/services/constraints) and save it to ~/.codex/plans/<name>.md.
If no plan and vague request, ask user to run /plan first.
The doc's frontmatter gets plan: ~/.codex/plans/<name>.md and the # Plan section contains a reference link + brief summary, not the full verbatim content.
Body Structure — ALL sections MUST have real content
# Plan comes first (as a reference to the plan file). Every subsequent section draws from the plan file content. No section may be a stub.
# Plan> Full plan: [~/.codex/plans/<name>.md](../~/.codex/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 system-level design scope and key decisions.
# Architecture## Current State
What exists today. What works, what doesn't. Reference `docs/ARCHITECTURE.md`.
## Proposed Architecture
## Step 4 — Self-Audit
Re-read and verify:
1. Every plan item captured somewhere.
2. Minimums met: ≥7 invariants, ≥3 failure modes, ≥5 verifications, ≥2 decisions, ≥3 services, ≥2 data flows.
3. No stubs, no empty tables.
4. All diagrams complete.
5. Cross-cutting concerns addressed (security, monitoring, deployment, rollback).
6. Verify plan file exists at the path in frontmatter and its content is consistent with the doc.
## Step 5 — Validate
```bash
tx spec lint
Step 6 — Discover, Link & Report
tx spec discover --doc <name>
tx doc link <overview> <design>
tx doc show <name>
Step 6.5 — Sync Plan File (MANDATORY)
After filling and validating the doc, update the plan file at the plan: frontmatter path to reflect everything the doc surfaced. The plan file must be the living source of truth — not a stale initial draft.
What to add to the plan file:
Service boundaries and deployment topology
Data flow details and inter-service contracts
Design decisions and their rationale
Invariants, failure modes, scaling strategy
Security considerations and monitoring signals
Read the current plan file, merge in the new information, and write it back.
After Generation
Print output path (specs/design/<name>.md).
Summarize: invariant count, failure mode count, service count, decision count.
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.
