system-design-doc

name	system-design-doc
description	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 rather than feature-scoped subsystem docs.
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 and services. For feature-scoped or single-subsystem design work, use design-doc. For project-level product context and root scope, use overview-spec.

Before drafting from memory, fetch the canonical tx scaffold for the target system design doc and use that as the minimum valid schema. Run tx doc add design <name> --title "<title>" if the doc does not exist yet, then run tx doc show <name> --md. That output is the baseline shape to preserve. Add structure on top of it; do not invent frontmatter fields or remove tx-required top-level sections.

Naming Discipline

• tx assigns each doc an immutable doc_id. Human name slugs only need to be unique within their doc kind.
• Use distinct names for the overview, the system design, and lower-level subsystem docs.
• Prefer names that signal cross-cutting scope, such as <product>-system-design, <initiative>-architecture, or <platform>-runtime-design.

Migration Guidance

• When migrating a long handwritten system design, preserve the original wording first, then reorganize it into tx-managed sections.
• Do not collapse major cross-cutting sections such as tenancy, storage, workflows, billing, deployment, or observability into generic summaries. System designs should remain detailed.
• When the source document is large, split out subsystem details into companion docs only after the system-level document still carries the cross-cutting boundaries and integration rules.
• If you extract sections programmatically, use a fence-aware parser. Headings inside fenced code blocks are content, not section boundaries.

Example Reference

Read references/octospark-system-design-example.md before drafting when you need a concrete example of a serious system design source document.

That example is useful because it shows:

• cross-domain architectural decisions that cannot live inside a single subsystem doc
• detailed ownership rules, tenancy rules, and infrastructure choices
• how to preserve a very large source document while still decomposing work into subsystem docs later

Workflow State Machine

START
  |
  v
[Step 0: Plan Gate]
  - Save or create `~/.codex/plans/<name>.md`
  - If request is vague, ask for or create a plan first
  |
  v
[Step 1: Scaffold]
  - `tx doc add design <name> --title "<title>"`
  - `tx doc show <name> --md`
  |
  v
[Step 2: Deep Context Gathering]
  - Read architecture docs, deployment/runbooks, project instructions, schemas, workflows, and existing specs
  |
  v
[Step 3: Fill Document]
  - Preserve all cross-cutting architecture detail
  - Keep subsystem boundaries explicit
  - Add service boundaries, data flows, invariants, failure modes, and verification
  |
  v
[Step 4: Self-Audit]
  - Every plan item captured?
  - No stubs?
  - Cross-cutting constraints explicit?
  |
  v
[Step 5: Validate]
  - `tx spec lint`
  |
  v
[Step 6: Discover + Link + Report]
  - `tx spec discover --doc <name>`
  - `tx doc link <overview> <design>` when appropriate
  - `tx spec gaps --doc <name>`
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, write that plan to ~/.codex/plans/<name>.md.
• If a plan file already exists there, read it instead of overwriting.
• If no plan exists but the request is detailed, generate the plan yourself and save it.
• If the request is vague, ask the user to create or confirm the plan first.

The doc's frontmatter gets plan: ~/.codex/plans/<name>.md and the # Plan section contains a reference link plus a brief summary, not the full verbatim content.

Step 1 — Scaffold via tx

tx doc add design $ARGUMENTS --title "<Human-Readable Title>"
tx doc show $ARGUMENTS --md

Creates or opens specs/design/<name>.md. Treat the tx doc show --md output as the minimal schema for the document.

Step 2 — Gather Context

Read all relevant system-level material:

• docs/ARCHITECTURE.md
• docs/QUALITY.md
• docs/DEPLOYMENT.md
• docs/ROLLBACK.md
• docs/RUNBOOKS.md
• project instructions (for example AGENTS.md, if present)
• existing specs from tx doc list
• workflow code, infra packages, schemas, and service entrypoints

Step 3 — Fill the Document

Required Frontmatter (already generated by tx)

---
kind: spec
spec_type: design
name: <name>
title: "<title>"
status: draft
version: 1
owners:
  - <team-or-person>
summary: <one-line summary>
domain: platform
tags:
  - design
  - system
depends_on: []
supersedes: []
implements: null
last_reviewed_at: <YYYY-MM-DD>
plan: ~/.codex/plans/<name>.md
---

Minimum Expectations

• Invariants: at least 7
• Failure modes: at least 3
• Verification entries: at least 5
• Design decisions: at least 2
• Service boundaries: at least 3
• Data flow diagrams: at least 2

Content Rules

• # Plan comes first and references the saved plan file.
• Preserve cross-cutting architecture decisions in the system design even if subsystem docs also exist.
• Keep service boundaries, ownership rules, deployment topology, and major data flows explicit.
• No section may remain a stub.

Step 4 — Self-Audit

Before finishing, confirm:

• every plan item appears somewhere in the doc
• service boundaries and ownership boundaries are explicit
• major runtime flows have concrete diagrams or stepwise descriptions
• invariants, failure modes, and verification are specific rather than generic
• the system design still stands alone even if subsystem docs are added later

Step 5 — Validate

tx spec lint

Fix warnings or failures before reporting completion.

Step 6 — Discover + Link + Report

tx spec discover --doc <name>
tx spec gaps --doc <name>
tx doc link <overview> <design>

If subsystem docs exist, keep the linkage explicit:

• overview defines the root problem and scope
• system design defines cross-cutting HOW
• subsystem designs define local implementation detail