/design is the upstream authoring step of the phase loop — it starts earlier than /plan. Use it when the problem is not yet tasks-shaped; use /plan once the design is settled. The three sub-verbs run in order: author → translate → sequence. The gate between them is a single hard Status: final check (run by the tested helper design_doc.py), so you cannot skip ahead — only the human approval inside author sets final.

1. Author the design doc (/design author). Run /design author <slug> [--visibility confidential|published] (bare /design <slug-or-brief> defaults to author). On a new slug the command bootstraps from the bundled template (${CLAUDE_PLUGIN_ROOT}/templates/design-doc.md), prefills frontmatter (status: draft, visibility from your flag, author read from .git/config's [user] name, dates set to today), and starts the section walk.

   Walk the 10 sections in template order — Context → Design → Alternatives Considered → Dependencies → Migrations → Technical Debt & Risks → Quality Attributes → Project management → Operations → Document History. The Quality Attributes section drills all 11 sub-attrs (Security → Reliability → Data Integrity → Privacy → Scalability → Latency → Abuse → Accessibility → Testability → Internationalization & Localization → Compliance); answer each with a concern, or N/A: <one-sentence reason> — a bare N/A is pushed back. The command saves after every section, so an interrupted session resumes where you left off. When the draft is complete, pick "Ready for review (Status → review)" — the command first runs the prose-pass skill over the full document (Gemini simplifies it in your voice pack; Claude fact-checks the result and applies it; frontmatter, headings, tables, and Document History come through byte-identical, and the pass is recorded in that day's Document History row). The pass runs again when you re-run /design author <slug> to enter the inline review pass (Approve / Revise / Skip per section); answer "Approve as final?" to transition review → final. Only author moves Status, and it refuses to re-open a final doc. If the agy CLI is missing or misbehaves, the command tells you so (a PROSE-PASS-DEGRADED line), applies the Claude-only style conformance pass instead, and keeps going — the pass never blocks authoring.

2. Translate the final doc into parts (/design translate). Run /design translate <slug>. The command runs two hard gates through the helper — design_doc.py gate <path> (must be Status: final) and design_doc.py detailed-design <path> (the ### Detailed Design section must be non-empty). Both must pass or it halts with the helper's verbatim refusal. It then proposes a part split (one part per Detailed-Design subsection by default, soft-capped at ~6 with --allow-large-design to override) and presents it as a table for Approve / Reshape / Cancel. On Approve it writes one <designs>/<slug>/parts/<part-slug>.md per part, in the project's designs/ as agentm names it (design_doc.py parts-dir <slug>), (each carrying parent_design, part_slug, dependencies, estimated_scope frontmatter), then appends one Document-History row to the parent — the parent's Status stays final.

3. Review and fill the part files. translate lifts each part's Scope, Dependencies, and Verification criteria from the parent's Detailed-Design subsections, so the part files arrive populated. Read each part file, confirm its Scope and dependency rationale match your intent, and flesh out any Verification-criteria bullets that need more than the parent supplied — these become the sequenced plan's Goal and Verification strategy in the next step.

4. Sequence the parts into queued tasks (/design sequence). Run /design sequence <slug>. The command re-checks the Status: final gate and that the parts are non-empty and valid, then topo-sorts them via design_sequence.py order <parts-dir> (deterministic; alphabetical tie-break; halts on a dependency cycle or a missing dependency, surfacing the helper's message verbatim). It maps each part to a /plan-shaped plan body (with parent_design_doc + parent_part_slug traceability frontmatter), lists the task names — <doc-slug>-<part-slug> — for you to confirm, and checks them all with design_sequence.py check-names before writing anything. Then it places each part, one at a time, with design_sequence.py place: agentm puts it in a new numbered task, tasks/NNN-<doc-slug>-<part-slug>/plan.md, and its tracker opens at queued, naming the design. No part is started, and nothing is written to a flat staging directory — a project that keeps no tasks is refused up front.

5. Run the sequenced tasks. Start the first with /work --name <doc-slug>-<first-part-slug> (or /plan --activate it first; see Run a named plan). Each task's plan is a draft decomposition — run /plan --name <doc-slug>-<part-slug> against it to refine the steps before /work. Later parts wait at queued until you start them.

A design worth committing alongside the wiki. Author it published, so it routes to wiki/designs/:

/design author export-pipeline --visibility published

You walk the 10 sections and the 11 Quality-Attributes sub-attrs, mark it Ready for review, then re-run /design author export-pipeline and Approve as final. The doc now lives at wiki/designs/export-pipeline.md with status: final. Translate and sequence it:

/design translate export-pipeline      # Approve the proposed split
/design sequence export-pipeline

Resulting tree (the part split is illustrative — three Detailed-Design subsections → three parts, command-surface depending on data-model; the task numbers are the next free ones in the project):

wiki/designs/
  export-pipeline.md                 # Status: final
<vault>/projects/<slug>/
  designs/
    export-pipeline/parts/
      data-model.md                  # dependencies: []
      command-surface.md             # dependencies: [data-model]
      rollout.md                     # dependencies: [data-model, command-surface]
  tasks/
    043-export-pipeline-data-model/        # plan.md + tracker.md (queued)
    044-export-pipeline-command-surface/   # plan.md + tracker.md (queued)
    045-export-pipeline-rollout/           # plan.md + tracker.md (queued)

A design you don't want committed (sensitive, or just not wiki-worthy). Drop --visibility (or pass confidential explicitly) and it routes to the project's own designs/ in the vault, never the repo:

/design author export-pipeline      # confidential is the default

The command asks agentm where the project's designs/ is, through python3 "${CLAUDE_PLUGIN_ROOT}/scripts/design_doc.py" design-path export-pipeline — it never composes a project path. The doc lands at <designs>/export-pipeline.md. With no agentm, or no vault for the project, the command writes nothing and offers --visibility published. Translate and sequence are identical to Scenario A; only the doc's own location differs:

<vault>/projects/<slug>/
  designs/
    export-pipeline.md                     # confidential, Status: final
    export-pipeline/parts/                 # as in Scenario A
  tasks/
    043-export-pipeline-data-model/        # queued
    044-export-pipeline-command-surface/   # queued
    045-export-pipeline-rollout/           # queued

The default one-part-per-subsection split rarely matches the real shape. During /design translate, after the proposed table, choose Reshape instead of Approve. Say translate proposed four parts but data-model and access-layer are one deployable unit, and rollout is large enough to split:

Reshape
merge data-model access-layer        # → one "foundations" part; confirm merged scope
split rollout                        # → "rollout-flag" + "rollout-telemetry"; confirm split lines
rename foundations data-foundations  # optional tidy-up
Approve

Each op re-presents the table; the loop continues until you Approve. Only then does translate write the part files — Cancel at any point leaves the parent untouched and writes nothing. /design sequence then topo-orders the reshaped parts exactly as in Scenario A.

After each verb, confirm the on-disk state (substitute your slug for export-pipeline and your doc dir for wiki/designs):

# After author — the doc is Status: final
grep -m1 '^status:' wiki/designs/export-pipeline.md      # → status: final

# After translate — one part file per proposed part
ls "$(python3 "${CLAUDE_PLUGIN_ROOT}/scripts/design_doc.py" parts-dir export-pipeline)"
                                                          # → data-model.md  command-surface.md  rollout.md

# After sequence — one queued task per part, none started
grep -l '^status: queued' <tasks>/*-export-pipeline-*/tracker.md   # → all three

(<tasks> is the project's tasks/: python3 "${CLAUDE_PLUGIN_ROOT}/scripts/project_homes.py" home tasks. For a confidential design, the doc itself is at design_doc.py design-path export-pipeline instead of wiki/designs/.)

• /design translate or /design sequence refuses with a Status: message. The doc is not Status: final — translate and sequence both hard-gate on it via design_doc.py gate, which exits 2 with a state-specific reason (draft / review / launched / malformed) and never auto-repairs. Finish the author review pass: run /design author <slug>, walk the inline review (Approve / Revise / Skip), and answer "Approve as final?" with yes. The Status field is then final and the gate passes.
• /design translate refuses with "Detailed Design has no content". This is the second gate (design_doc.py detailed-design): the ### Detailed Design section is scaffold-only, so there is nothing to split. Re-run /design author <slug>, Revise the Design section, and author at least one Detailed-Design subsection (the split heuristic keys off these), then re-run /design translate.
• /design author refuses to re-open a final doc. By design — only author transitions Status, and it will not re-invoke after final (that would silently re-open an approved design). The escape hatch is manual: edit the doc's status: frontmatter field from final back to review yourself and append a Document-History row noting why, then re-run /design author <slug> to enter the review pass. author never moves Status backwards on its own.
• /design sequence halts with a cycle or missing-dependency message. The topo-sort (design_sequence.py order) found a dependency cycle detected: a → b → a or a part 'x' depends on 'y' which does not exist in parts/. Edit the offending part file's dependencies: frontmatter to break the cycle or fix the dangling slug, then re-run /design sequence — the order is deterministic, so a fixed parts/ always re-sequences the same way.

• Named plans — the reference for the phase-loop command surface /design joins, including the /design row.
• Run a named plan — drive the queued tasks /design sequence opens.
• Run a coordinator-directed worker team — hand the sequenced tasks to workers; tech-lead forward-references the /design → /plan authoring arc.
• Coordinator roles — the tech-lead role whose authoring floor /design raises.
• Development lifecycle design — package /design as a command — why /design ships as a command (tested Python helper + thin prompt), not a skill.