c-design

/c-design

You materialize a design folder from the 00-overview.md stub. You write one child doc at a time, pause for user review, and loop back to amend the overview if a child doc surfaces inconsistencies.

Entry contract

Requires: the design artifact for {yyyy-mm-dd-slug} exists — check via skills/_shared/storage-resolution.md (artifact_exists) — and its 00-overview, read via read_artifact, carries status: draft and a populated Doc index; do not assume a <paths.designs>/…/00-overview.md file path.

Refuses when: overview missing, status ≠ draft, empty doc index, or the stub carries an "Open questions" block (Invariant 1 violation — stub was written prematurely).

Folder layout (every design)

<paths.designs>/
  {yyyy-mm-dd-slug}/
    00-overview.md
    00a-plain-english.md
    01-<topic>.md, 02-…
    95-visual-contract.md            # opt-in
    mockups/01-<slug>.html, 02-…     # with 95; default location, see mockups.dir
    97-infrastructure-inventory.md   # opt-in
    98-architecture-diagrams.md      # opt-in
    99-out-of-scope.md

Reserved slots: 00-overview, 00a-plain-english, 95-visual-contract, 97-infrastructure-inventory, 98-architecture-diagrams, 99-out-of-scope. Refuse to scaffold conflicting names (a conflicting 95-* name included). Each slot is materialized per skills/_shared/storage-resolution.md (write_doc), which the layer maps to a <slot>.md file on the filesystem backend and to a titled sub-page on the notion backend; the folder layout above is the filesystem view only.

Frontmatter

See skills/_shared/frontmatter.md. Design overview carries lifecycle; child docs carry only title:.

Writing flow

1. Read the stub via skills/_shared/storage-resolution.md (read_artifact). List the proposed doc index. When the overview describes significant user-facing UI/UX work and the doc index lacks 95-visual-contract, offer the slot in the same confirmation (see Visual contract and mockups); when significance is genuinely unclear, ask; a mostly-backend design with an incidental UI touch gets no offer. Confirm with user: "Write 00a-plain-english.md next, then 01-<x>, 02-<y>. Sound right?" Then ask the generation-mode question (see Generation mode). Config values (authoring.*) come from running node "${CLAUDE_PLUGIN_ROOT}/scripts/resolve-config.js" (contract in skills/_shared/config-resolution.md; never read config files directly).
2. Write child docs per chosen mode. Each doc is written to its reserved slot per skills/_shared/storage-resolution.md (write_doc); do not open or path-compute a <paths.designs>/…/<slot>.md file.
   • All-at-once: dispatch one fresh generator agent per technical child doc in parallel (up to authoring.max_parallel). Every generator prompt names the resolved storage backend and the matching syntax reference: skills/_shared/obsidian-format.md always, plus skills/_shared/notion-translation.md when the backend is notion (so generators author callouts as native <callout> blocks, not obsidian syntax). After all complete, dispatch cadence-doc-consistency once over the set for a consistency sweep (see Generation mode). Then generate 00a-plain-english.md last.
   • One-by-one: write one child doc, then proceed to step 3.
   • Inline: the main session writes every technical child doc itself, sequentially, via write_doc — no generator sub-agents, no per-doc pause, no cadence-doc-consistency sweep (a single author holds the whole context; Invariant 2 still applies in full). Then generate 00a-plain-english.md last and continue at step 8.
3. Pause after each doc (one-by-one mode only). "<filename> written. Review and tell me to continue, revise, or stop." Never auto-write the next file in this mode. In all-at-once mode, the cadence-doc-consistency sweep is the single pause point after parallel generation.
4. Invariant 2 — consistency re-litigation. While drafting any child doc, if a question surfaces that contradicts or refines a decision in the overview or sibling, STOP writing. Surface the conflict. Ask the user to resolve. On resolution: amend overview's decisions log, amend affected siblings, update updated: on overview, then resume.
5. OOS additions during design. Any decision-not-to-do lands in 99-out-of-scope.md immediately with rationale + wikilink. Never deferred.
6. 00a-plain-english.md is written last. Sections (in order): What this feature does in one paragraph → The normal cycle → What the user sees → What can go wrong → How we'll know it's working → Lifecycle diagram → TL;DR. Length target: 400-700 lines for complex designs.
7. 97 / 98. Filled when the doc index includes them. 97 lists every piece of infra (existing + new), one line each, citing files/services. 98 holds dense mermaid diagrams; lighter narrative diagrams live in 00a per convention.
8. Resolve cross-references. After every doc in the artifact exists, call skills/_shared/storage-resolution.md (resolve_links) once over the artifact to turn [[…]] wikilinks into Notion page mentions. Backend-neutral: a no-op on the filesystem backend, the mention second pass on notion (see skills/_shared/notion-translation.md).
9. Self-review pass (see below). Read the written docs back via skills/_shared/storage-resolution.md (read_artifact) and run a final pass over the whole artifact.
10. Flip status to in-review per skills/_shared/storage-resolution.md (set_status), which also bumps updated:. Print: "Design ready for review. Walk through it and tell me when to mark it approved."
11. Status approved. User-driven only. User says "approved" → flip status per skills/_shared/storage-resolution.md (set_status); when the design has a 95-visual-contract slot, rewrite its freeze record from frozen: none to frozen: NN (the latest version) via write_doc in the same moment: an approved design with a 95 slot always names a frozen version, the invariant /c-plan relies on. Post-approval mockup changes are design drift under the existing drift rules, never a silent new version. Then print: "Run /c-plan to write the implementation plan."