design authors design documents across the whole sizing ladder above /plan — from a one-pager for small work up to a cross-system HLD set. It picks the right amount of design for the work and holds the section conventions, the templates, and the finalization discipline. It is the design-authoring surface of how-we-engineer. It renames design-docs → design (bare noun) and declares [design, architecture].

The three rungs of one ladder:

Rung	Scope	Who reaches for it
abbreviated	a subset of the full doc for small work — the default rung, where most work lands	Engineer · Tech-Lead
full	single-system, the complete doc	Designer
architecture	cross-system / HLD — the four-pillar AG HLD set is the worked example	Architect

The primitives:

Primitive	Kind	Status	What it does
/design	command	delivered	The author → translate → sequence pipeline (impl owned by development-lifecycle; design-docs ships a thin wrapper).
/spec · /interview-me · /document-decision	command	delivered (re-homed)	PRD authoring · brief elicitation · decision capture.
design_doc.py · design_sequence.py · stage_plan.py	script	delivered (re-homed)	The Status:final gate + frontmatter parse · the Kahn topo-sort · the named-plan writer.
adr	skill	delivered	Decision-record authoring — scoped (agentm + crickets retired the ADR model; there it amends living designs instead).
design-doc template	template	delivered (re-homed)	The full-rung template + section conventions.
architecture-rung scaffolding	—	to build	Multi-system HLD + cross-system composition analysis + architecture-review.
abbreviated-design template	template	to build	The default-rung template.

One sizing ladder above /plan — abbreviated is the default rung most work lands on, full for a single system, architecture for cross-system HLDs (the four-pillar AG set is the worked example); each persona enters at its altitude.

A design fixes the architecture and the locked calls before any code — so a plan has something to decompose and the loop has something to hold to. Without one, /plan invents scope; a design that drifts from the code misleads as much as a stale doc. Design sits at the head of the loop: it makes plans possible (it generates them) and grounds the whole loop end-to-end (/plan, /review, and /release all bind back to it). The discipline is to spend the right amount of design for the work — over-designing small work fails as surely as under-designing a cross-system change.

What goes in is fixed by the rung. One ladder, three templates, each a deliberate shape:

Rung	The shape	The sections
abbreviated (default)	the canonical seven — most designs land here	Objective · Overview · Design · Dependencies · Risks & open questions · References · Amendment log (+ optional Alternatives · Migrations)
full	the locked ten — a substantial single system with ops / launch / quality obligations	Context · Design (Overview / Infrastructure / Detailed Design) · Alternatives · Dependencies · Migrations · Technical Debt & Risks · Quality Attributes (the 11-attribute walk) · Project management · Operations · Document History
architecture / HLD	the seven-section, vision-led whole — names the pillars and how they fit, documents none in depth	vision-led opening · What X is for · The pillars/capabilities (the heart — each links down to a sub-design) · How they fit together · Sub-designs · References · Amendment log

A design is above /plan (which produces a task list, not a design). Each persona enters at its altitude — Engineer / Tech-Lead at abbreviated, Designer at full, Architect at architecture.

The rungs nest by addition: an abbreviated design is a strict subset of the full template's sections, in the full template's order — so a design that grows graduates abbreviated → full by adding the heavier sections, never reshaping what it has. Within a rung, the sections flex to the work:

• the abbreviated rung includes Alternatives / Migrations only when they apply, and deliberately drops Infrastructure / Quality-Attributes / Project-management / Operations — adding one back only if a sub-design genuinely needs it (the anti-pattern it prevents: a how-the-generator-works sub-design carrying SLAs and work estimates);
• the full rung walks Quality Attributes (11) and Operations (4) consciously but omits the N/A ones — no N/A stubs;
• a real design freely shapes section content to the work while keeping the rung's required spine.

A finished design is several layers folded onto a rung template:

1. The template — the section spine; picking the rung is the how-we-engineer sizing call.
2. The design-authoring conventions — baked into the template: the section list + order, the [PENDING-IMPL] marker for a designed-but-not-yet-built clause, the finalization discipline (collapse the amendment log to one ≤2-paragraph "authored, reviewed, and finalized" entry), the every-design-carries-a-diagram rule, and — for a capability design — the mandatory ### Opinions it consumes clause.
3. The opinions — design consumes how-we-engineer (the sizing ladder, the templates, and the section conventions are how we engineer designs — how-we-engineer itself implements: crickets/development-lifecycle, not design) and consumes good (what a sound design reads like — the adversarial-read bar). One-way: design renders the standard into a document; it does not author the opinion.
4. The voice — the operator's prose voice (docs-prose-style, an agentm opinion: subjective and learned, not a convention) is folded in so the design reads in one voice. That voice is second-person and plain: no peacock or AI-tell adjectives, no prior-art name-drops, no "this-not-that" antithesis, labels de-performed, plain names over insider metaphors. Since 2026-07-16 the voice is also enforced at read-time: the prose-pass skill (Gemini simplifies via scripts/prose_pass.py with the voice pack inlined verbatim, Claude fact-checks and applies) runs over the full document at author Step 5 and review-pass entry — the operator's fixed design-doc-prose overlay is the default --overlay. Request-by-name through the opinion registry stays [PENDING-IMPL].
5. The published-doc structure — a published design lands in wiki/designs/ as the explanation mode of the documentation convention (Diátaxis), gated by wiki's check-wiki.py.

The line that organizes the layers: structure is a convention (objective, gate-backed); voice is an opinion (subjective, learned).

The conventions, templates, and voice that govern design authoring evolve from what works — they are living, amended artifacts (this very template grew its ### Opinions it consumes clause because the operator noticed it was missing mid-review). The mechanism that is built is the memory engine: the reflection loop mines each finished session for durable lessons — it is how docs-prose-style.md itself grew, most of its rules sourced from operator edits during these design reviews — and heat-curation keeps the always-load voice earning its cost. Designed-not-built is the design-authoring-specific sharpening: the Experience → Opinions loop that would tune how-we-engineer / good from session signal, crystallization (phase-close distillation), and template-self-evolution as a closed loop — today that evolution is hand-applied by the operator at review. [PENDING-IMPL].

The authoring chain is a strictly-ordered pipeline above /plan, split between interactive prompts and deterministic helpers (the crickets idiom: gates + sorts + writes in unit-tested stdlib Python; section walks + proposals + approvals in the prompt).

• Front matter (optional): /interview-me drives a brief to ~95% confidence one question at a time; /spec writes a six-section PRD (its Out-of-scope section is the highest-value one). Both feed a confirmed brief downstream.
• The core — /design author → translate → sequence: author walks the rung template's sections and is the only verb that moves Status draft → review → final (final needs a human "approve as final"); translate (gated on Status:final + a non-empty Detailed Design, both via design_doc.py) splits the final doc into parts/, one per Detailed-Design subsection, each sized for a single /work cycle; sequence (design_sequence.py — a Kahn topo-sort with an alphabetical tie-break, so re-runs never churn) orders the parts by their dependency DAG and writes them via stage_plan.py — the first activated to a named PLAN-<doc>-<part>.md, the rest queued inert, never touching the singleton PLAN.md.
• Decision capture: /document-decision (the WHEN/HOW trigger) + the adr skill (the shape). Both still teach the immutable-ADR workflow; in agentm + crickets the ADR model is retired (amend living designs), so the adr skill is scoped to other repos.
• The de-dup: development-lifecycle owns the real /design implementation + the helpers + the full template; design-docs ships only a thin delegating wrapper (requires: development-lifecycle) + the unique adr skill — one logic owner, one pointer.

Design makes plans possible, two ways:

1. Generation — sequence opens the queued tasks directly: one /plan-shaped body per part, each in a numbered task with a queued tracker, mapping the parent's scope → Brief, verification → Goal, locked calls → Constraints, sibling parts → Out-of-scope, with parent_design_doc traceability — then hands off to the normal /work → /review → /release loop.
2. Grounding — even a hand-authored plan is bound back to the governing design: /plan reads a bounded slice (frontmatter + ## Locked design calls, ~400-line cap, never the whole arc) and must cite parent_design_doc: or declare greenfield; a deterministic gate (check-plan-grounding.py) fails a plan that touches architecture without one; /review carries a design-conformance dimension and /release reconciles the diff against the locked calls. So design governs the loop end-to-end, not just plan creation.

A complete design often needs research first — research is a soft input (it enhances, never requires): the explorer read-only fan-out + bounded web lookups bring in what the work must know before it is designed or planned, feeding every rung's context. An architecture-rung HLD is the rung most likely to lean on it; the deep multi-source mode is forward-referenced to the operator's deep-research agent. Research feeds the context; it never gates the design. See research.

Delivered: the /design author → translate → sequence pipeline · /spec · /interview-me · /document-decision · design_doc.py · design_sequence.py · stage_plan.py · the full design-doc template · the adr skill · the grounding hooks · the headless cross-model prose pass (prose-pass skill + prose_pass.py — Gemini simplifies, Claude verifies; shipped 2026-07-16).

To build ([PENDING-IMPL]): the architecture-rung scaffolding (multi-system HLD + cross-system composition analysis + architecture-review — generalize from the AG HLD set); the abbreviated-design template packaged as a runnable /design template (an AG shape-spec today); the finalize tooling (auto-collapse the amendment log + the [PENDING-IMPL] stale-placeholder grep check — run by hand today, as in this set); request-by-name of the how-we-engineer / good / voice opinions (the Phase-3/4 registry); the design-authoring self-improvement loop; and the interactive external-review handoff (#5b — its headless sibling shipped as prose-pass; the transfer-context + resume session flow stays deferred).

design consumes how-we-engineer (layer 3 — the sizing ladder + the section conventions are how we engineer designs; how-we-engineer implements: crickets/development-lifecycle, so design is a cross-plugin consumer, not the implementer) and consumes good (the read-bar); the operator's voice is the third opinion it folds in (layer 4). The arrow is one-way — design renders the standards into a document, it does not author them. (Both bindings interpolated at build time from a committed snapshot via the markdown-prose consumer grammar — good since PLAN-opinion-consumer-grammar task 2, how-we-engineer since PLAN-wave-d-personas task 2; request-by-name is separately deferred to the Phase-3/4 registry work — the Opinions design.)

• requires development-lifecycle — design sits at the head of the loop, above /plan; sequence hands the loop its queued tasks, and the grounding hooks bind /plan · /review · /release back to the design.
• consumes how-we-engineer + good (agentm Opinions) — the sizing ladder is how-we-engineer; good is the read-bar. Both interpolated at build time from a committed snapshot (design does not implement either — how-we-engineer implements: crickets/development-lifecycle, good implements: crickets/code-review). It also folds in the operator's voice (an agentm opinion; always-load prose today, base⊕overlay request-by-name [PENDING-IMPL]).
• published output sits under the documentation convention (conventions via wiki) — a wiki/designs/ page in Diátaxis explanation mode, gated by check-wiki.py.
• enhanced by research — a soft input feeding a design's context (the explorer fan-out + bounded web); it enhances, never gates.
• composed by the Architect / Designer / Engineer-Tech-Lead personas (Personas) — each enters the ladder at its rung.
• Points up at the crickets HLD; the requires/enhances mechanics are in crickets-composition.

• The capability rename design-docs → design (bare noun), declaring [design, architecture] plus the retired design-docs name so existing references resolve (the composition rename mechanism — the group declares both names).
• The re-homing from developer-workflows — /spec, /interview-me, /document-decision, design_doc.py, design_sequence.py, the design-doc template move in; the requires target is the renamed development-lifecycle.
• De-dupe the two /design copies — both design-docs and the old developer-workflows shipped one; design owns the single copy.
• The ADR carve-out — the adr skill stays, but in agentm + crickets the ADR model is retired (amend living designs instead); the skill governs every other repo until it migrates.

• The architecture rung is to-build — the multi-system HLD scaffolding + cross-system composition analysis + architecture-review are greenfield; the four-pillar AG HLD set is the model to generalize from.
• The abbreviated-design template is to-build — the default rung needs its own template; today the abbreviated shape is applied by hand.
• Finalization is manual until built — the amendment-log collapse + the [PENDING-IMPL] stale-placeholder check run by hand (as in this design set).
• The prose pass depends on an external CLI (agy, serving Gemini). It asks for the strongest Gemini agy models serves, and PROSE_PASS_MODEL names another without editing the script (amendment 2026-10-16). When agy fails, the pass prints its degrade marker, and the caller relays it and runs the Claude-only pass. agy is never a hard dependency.
• Re-audit triggers: build the architecture-rung scaffolding (generalize from the AG HLD set); ship the abbreviated template + the finalize tooling; flip design-docs → design + re-point requires at v6.0; de-dupe the /design copies at the re-home.

• crickets src/design-docs/ (→ src/design/) + the re-homed developer-workflows design family — /design (impl: developer-workflows/commands/design.md) · /spec · /interview-me · /document-decision · adr skill (design-docs-native) · design_doc.py · design_sequence.py · stage_plan.py · templates/design-doc.md; declares [design, architecture]
• Templates: abbreviated-design-template · hld-template · the full template (developer-workflows/templates/design-doc.md)
• Voice: the ## Voice section of <vault>/standards/user-preferences.md (the always-on essence + tells; a vault from before the memory-root trims keeps it as voice-kernel.md in the retired _always-load/ pen) · docs-prose-style in <vault>/standards/voice/ (the on-demand design/wiki prose refinement, demoted from always-load 2026-07-05 per PLAN-r3-voice-mechanism — see wiki's 2026-07-05 amendment; the retired _global/wiki-style/ store is the fallback) · style_resolver.py (the base⊕overlay seam, built for wiki)
• Up / composed by: crickets HLD · composition · Personas (Architect / Designer / Engineer-Tech-Lead) · development-lifecycle · research (the soft context input) · conventions + wiki (the documentation convention for published output) · agentm Opinions (how-we-engineer / good / voice)

2026-10-16 — the prose pass asks for Gemini 4 Argon (High), and PROSE_PASS_MODEL overrides it (design 0.11.1). agy 1.4.0 stopped serving "Gemini 3.1 Pro (High)", the default since 2026-07-16. It now rejects that name in about 3 s with exit 1 and nothing on stdout, so every /design and documenter prose pass since then has printed PROSE-PASS-DEGRADED: agy call failed and run Claude-only. The fallback fired as designed, but the stderr line said only agy exited 1 with empty result. The default is now "Gemini 4 Argon (High)", the strongest of what agy models lists (Gemini 4 Argon and Gemini 3.8 Flash, each Low/Medium/High). This is the same pin code-review 0.4.1 gave cross-review.sh. PROSE_PASS_MODEL names another model, and --model beats it. A failed call's stderr line now names the model and quotes the first line of agy's own error. Exit codes, the retry and the marker are unchanged. Verified live: a one-paragraph doc came back simplified by Gemini, exit 0, in 25 s, with both fact-guards held; the retired name through PROSE_PASS_MODEL degraded with the marker and agy's "is not recognized as a known model" on stderr. Why not resolve the model from agy models at run time: that adds a network round trip to every pass, and nothing in the listing ranks models, so the ranking rule would go stale the same way a pin does. Why not put agy's reason in the marker: callers match the marker's reason strings, and the stderr line already sits beside it in the same Bash output. Re-audit trigger: agy models drops or renames Gemini 4 Argon, or a prose pass degrades with agy call failed within seconds.

2026-09-22 — /design sequence opens queued tasks (design 0.11.0; agentm-vault part 15, crickets task 100). sequence activated the first part as PLAN-<doc-slug>-<part-slug>.md and staged the rest in queued-plans/, a flat tier the projects migration dissolved. Every part is now a new numbered task, tasks/NNN-<doc-slug>-<part-slug>/, whose tracker opens at queued and names the design. design_sequence.py check-names refuses every name before anything is written: a name agentm places outside a task, one it names no tracker for, or one that already names a task. place then writes one part at a time, because agentm numbers a new task from the directories that exist. None is activated. Why not keep activating the first part: sequencing an arc is authoring. Starting work is the operator's word, and a task activates in place with /plan --activate or /work --name. Why task names stay <doc-slug>-<part-slug>: the migration named agentm-vault's parts that way, and the names are listed for the operator to confirm first. Re-audit if a project wants an arc's tasks started in order without a word per task.

2026-09-22 — confidential designs, parts and specs live in the project's own homes (design 0.11.0; agentm-vault part 15, crickets task 100). design_doc.resolve_harness_root took the parent of the resolved singleton PLAN.md as the place for confidential designs and parts. On a project that keeps its plans in tasks, the singleton call is exit 4, so /design author with a confidential design, and translate and sequence, could not run on agentm or crickets after the projects migration. design_doc.py now asks agentm for the project's designs/ through scripts/project_homes.py. Its verbs are designs-home, design-path <slug> (a confidential design, <designs>/<slug>.md) and parts-dir <slug> (<designs>/<slug>/parts/, for a published design too, since parts are working documents), and harness-root is gone. With no designs home it exits 3 and writes nothing. A published design still authors standalone. /spec writes <desk>/briefs/<slug>-spec.md, the skeleton's place for a brief with no task yet. The module also stops loading development-lifecycle's resolve_plan.py at import time. Why not keep parts beside the doc: a published doc sits in the repo's wiki/designs/, and parts are the project's working records, which agentm-vault's own parts already keep in the vault. Re-audit if a repo without agentm needs translate.

2026-09-13 — the voice inputs name the memory-root trims' homes. agentm-vault plan 05 (2026-09-11) folded voice-kernel.md into the ## Voice section of <vault>/standards/user-preferences.md and moved the cross-project voice rules from _global/wiki-style/ to <vault>/standards/voice/. References now names those homes first, and the retired paths second as the fallback prose_pass.py and vault_layout.py still probe. Why not drop the retired paths: a vault that never migrated still resolves through them. Re-audit trigger: the fallback rungs leave prose_pass.py and vault_layout.py.

2026-07-16 — the prose pass becomes the default for authoring, not just a standalone tool (operator escalation of the same-day session rule). /design author now runs the prose-pass skill (below) over the full document at Step 5 (author signals ready) and on review-pass entry, automatically — the operator no longer invokes it by hand. Claude generates the fact-guard list before calling prose_pass.py, using the default design-doc-prose overlay; the pass folds into that day's consolidated Amendment-log entry rather than adding a separate row. Degradation (exit 1/2) is graceful AND announced: the caller relays the PROSE-PASS-DEGRADED stdout marker, runs a Claude-only conformance pass instead, and continues — never blocks authoring. Same wiring lands in the wiki plugin's documenter agent (sibling-plugin resolution — design stays the sole owner of the primitive; wiki does not gain a hard requires:). Host note (forward reference, named not built): on Antigravity the host model is already Gemini, so the cross-model roles invert — the simplifier there would be Claude; deferred until the AG host has a Claude transport worth wiring. Re-audit trigger: agy retiring or its roster dropping the "Gemini 3.1 Pro (High)" pin; or building the AG role-inversion.

2026-07-16 — headless cross-model prose pass shipped (prose-pass, design plugin 0.7.0). The "external (cross-model) review" line item split in two, and the headless half shipped: scripts/prose_pass.py (Gemini simplifies via agy, mirroring cross-review.sh's prompt-first invocation and exit 0/1/2 degradation contract; a mandatory caller-supplied FACT-GUARD list plus the operator's voice pack inlined verbatim from the vault; frontmatter / headings / table structures / Document History validated byte-identical with one retry) + skills/prose-pass/SKILL.md (the Claude verification checklist, then deploy + one consolidated Document History row per day). Pattern proven by hand 2026-07-16 against agentm's capture design, where the un-guarded first pass inverted document truths and asserted a staging path the design's whole point is to bypass — hence the fact-guard block and the verify step being non-optional. Why not wait for #5b: the interactive handoff (transfer-context + resume session) is host-specific plumbing; the headless pass is host-agnostic and already proven — shipping it first captures the value without blocking on the session-handoff design. #5b stays deferred and will share the fact-guard + voice-pack discipline. Re-audit trigger: when #5b ships, fold both under one external-review umbrella; if agy's invocation contract changes (prompt-first, stdin-closed), re-audit prose_pass.py alongside cross-review.sh.

2026-07-07 — how-we-engineer wired as a cross-plugin interpolated binding; reconciled "implements" → "consumes" wording (PLAN-wave-d-personas task 2). Added how-we-engineer to design.md's opinions: frontmatter alongside good, and wrapped the rung-picking prose (the "Rungs" table's sizing call) in an <!-- opinion:how-we-engineer --> marker — generate.py build splices the committed snapshot's body into it, proven byte-identical across two consecutive builds and both hosts. This doc previously said design implements how-we-engineer; corrected throughout to consumes — per the opinion's own implements: crickets/development-lifecycle pointer, design is a genuine cross-plugin consumer (the same class as its already-wired good binding), not the implementer. Re-audit trigger: if a future change moves how-we-engineer's implements: target, re-check this doc's consumer/implementer framing against it.

2026-06-28 — lock-down sweep (operator review). Converted both mermaid diagrams to house-style hand-SVGs (the sizing ladder diagrams/crickets-design-ladder.svg + the author→translate→sequence pipeline diagrams/crickets-design-pipeline.svg). Confirmed the three-rung ladder above /plan and the organizing line — structure is a convention, voice is an opinion. No content change. Locked as a v5–v8 guidepost.

2026-06-24 — authored, reviewed, and finalized. (Authored + deepened 2026-06-23; approved 2026-06-24.) design authors design documents across the whole sizing ladder above /plan — three rungs of one ladder (abbreviated default · full · architecture/HLD), renamed design-docs → design, declaring [design, architecture]. The Design section is reasoning-first: why we design (fix architecture + locked calls before code; the head of the loop that makes plans possible), what goes into each rung template (the canonical-seven / locked-ten / vision-led-seven section structures), how a design adapts its template (rungs nest by addition; N/A-omit; the deliberately-dropped sections), the layering (template ⊕ design-authoring conventions ⊕ the how-we-engineer / good opinions ⊕ the operator's voice ⊕ the published documentation convention), self-reinforced learning (the built reflection loop that grew docs-prose-style.md from these reviews; the designed Experience→Opinions sharpening), the author → translate → sequence workflows + plug-in points (with a pipeline diagram), and how design feeds the dev loop (generation via sequence + grounding via the hooks; research a soft input). The organizing line: structure is a convention, voice is an opinion.

Built vs designed. Delivered: the /design author → translate → sequence pipeline (impl in development-lifecycle; design-docs a thin wrapper + the native adr skill), /spec · /interview-me · /document-decision, design_doc.py · design_sequence.py · stage_plan.py, the full template, the grounding hooks. [PENDING-IMPL]: the architecture-rung scaffolding (generalize from the AG HLD set), the abbreviated-design template packaged as a runnable /design template, the finalize tooling (amendment-log collapse + [PENDING-IMPL] stale-placeholder grep — run by hand today, as in this set), request-by-name of the opinions + voice (Phase-3/4 registry), the design-authoring self-improvement loop, external review. Re-audit: build the architecture rung + the abbreviated template + the finalize tooling; flip design-docs → design + re-point requires at v6.0; wire request-by-name when the registry ships.