| name | overview-spec |
| description | Generate a system overview spec via `tx doc add overview`. Produces an architectural overview covering problem, scope, components, data flows, and non-goals. References plan via file path instead of embedding. Plan lives in ~/.codex/plans/<name>.md. Output lands in specs/<name>.md with tx-managed frontmatter. |
| argument-hint | <system-name> |
Generate Overview Spec
Create a system-level overview specification using the tx doc primitive. One overview per project — it is the root of the spec graph.
Workflow State Machine
START
│
▼
┌─────────────────────────────────────────────────────┐
│ Step 0: PLAN GATE │
│ │
│ Is there an active plan in this conversation? │
│ (i.e. the user used /plan or plan mode before │
│ invoking this skill) │
│ │
│ ├─ 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 the user: │
│ "No plan found in conversation. Run /plan │
│ first to create one, then re-run │
│ /overview-spec. Or describe what you want │
│ and I'll draft the plan inline." │
│ │
│ If the user provides enough detail in their │
│ message to proceed, generate a plan │
│ yourself (act as if you are in plan mode — │
│ research the codebase, think through scope, │
│ components, constraints). Save it to │
│ `~/.codex/plans/<name>.md`. │
│ → Continue to Step 1 │
└─────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────┐
│ Step 1: SCAFFOLD via tx │
│ │
│ tx doc add overview <name> --title "<title>" │
│ ├─ SUCCESS → Continue to Step 2 │
│ └─ FAIL (name exists) → tx doc show <name> │
│ → Edit existing doc instead │
└─────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────┐
│ Step 2: GATHER CONTEXT │
│ │
│ Read: ARCHITECTURE.md, QUALITY.md, CLAUDE.md, │
│ domain code, existing specs (tx doc list) │
│ → Continue to Step 3 │
└─────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────┐
│ Step 3: FILL DOCUMENT │
│ │
│ Write `# Plan` section first (verbatim from Step 0). │
│ Then write all remaining sections, drawing from the │
│ plan content + codebase context. │
│ │
│ For EVERY section header: │
│ ├─ Plan has relevant content? │
│ │ → Use it + expand with codebase detail │
│ ├─ Codebase provides signal? │
│ │ → Generate from analysis │
│ └─ Neither? │
│ → Generate best analysis, mark [NEEDS REVIEW] │
│ │
│ RULE: No section may be left as a template/stub. │
│ Every section MUST have real content. │
└─────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────┐
│ Step 4: SELF-AUDIT │
│ │
│ Re-read the plan. Every plan item must appear │
│ somewhere in the document. Re-read every section — │
│ no stubs, no empty tables. │
└─────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────┐
│ Step 5: VALIDATE │
│ │
│ tx spec lint │
│ ├─ PASS → Continue to Step 6 │
│ └─ WARN/FAIL → Fix issues, re-validate │
└─────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────┐
│ Step 5.5: SYNC PLAN FILE │
│ │
│ Read the plan file from frontmatter `plan:` path. │
│ UPDATE the plan file to incorporate everything │
│ the doc surfaced: refined scope, components, │
│ data flows, risks, dependencies, stakeholders. │
│ The plan file must reflect the FULL current state. │
│ This is a MANDATORY step, not optional. │
└─────────────────────────────────────────────────────┘
│
▼
┌─────────────────────────────────────────────────────┐
│ Step 6: LINK & REPORT │
│ │
│ tx doc link <overview> <related-docs> │
│ tx doc show <name> │
│ Print summary │
└─────────────────────────────────────────────────────┘
│
▼
DONE
