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.