DeepWorkPlan — Design-System Addon

Give a repo with a user-facing interface surface a DESIGN.md — living
under docs/ alongside the repo's other specs and indexed from
AGENTS.md — so any human or AI agent generates interface output that matches
the repo's own conventions, instead of the unstyled, statistically-common
defaults an agent falls back to with no guidance. "Interface surface" is plural
(SPEC.md §3): a rendered visual UI, styled CLI output, or a
conversational surface (the product talks on chat/email) each count, as
independent profiles that stack into the same single DESIGN.md. This is an
opt-in addon — it is never required for a repo to be AI-first, and it is
only for repos with at least one real interface surface.

The rule that overrides everything: REASON about the repo's source, then write

A DESIGN.md is only useful if it reflects this repo. The first job is to
read the repo's real design source — its stylesheet, CSS custom properties,
Tailwind config, token files, and component styles; or its CLI display/theme
module and print helpers; or its message-composition layer and documented voice
rules (see SPEC.md §3–§5 and templates/presets.md) — then document those
values. Never paste a third-party brand's DESIGN.md (a Stripe/Linear/etc.
catalog entry) and never import another CLI's or bot's conventions wholesale:
reference catalogs are inspiration for structure, never content.

Read these first (all relative inside the skill)

• `SPEC.md` — the normative (RFC-2119) contract: interface-surface
  gate + the three profiles, canonical sections per profile, reason-don't-copy,
  reconcile-don't-clobber, accessibility & output integrity,
  pragmatic-reference posture, validation step.
• `templates/DESIGN.md.md` — the annotated DESIGN.md
  skeleton (each canonical section per profile + how to fill it from the repo).
  The shape is fixed; the content is reasoned per repo.
• `templates/presets.md` — per-stack reasoning presets
  (Tailwind, CSS-variables/vanilla, component-library/design-tokens, CLI
  rendering layers, conversational platforms) — where to find the design source
  in each stack. A starting checklist, not an answer key — detected reality
  wins.
• `templates/agent_prompt_guide.md` — the
  "Agent Prompt Guide" block to embed so downstream agents know how to follow
  DESIGN.md.
• `templates/design-system-command.md` — the
  optional /design-system delegator this addon MAY install into the target
  repo's .agents/commands/ (only when accepted and wanted).
• ../README.md — the addon mechanism (opt-in, reconcile-don't-clobber, contract).

When this runs

• From onboard Phase 7b — after the core AI-first scaffolding. Detection
  makes the offer mandatory (SPEC.md §3.5): when any interface surface is
  detected — even an ambiguous one — onboarding evaluates it, records the
  detection rationale, and presents the addon with a clear recommendation;
  the evaluation and offer are not skippable in either mode. Every profile
  still requires explicit acceptance, including visual UI in trust mode; no
  profile is auto-applied. When no interface surface is detected the
  addon is not offered. Either way the developer may decline and the repo
  stays baseline-conformant.
• Directly — /deepworkplan-addon-design-system on an already-onboarded repo
  to create or refresh DESIGN.md (or add a newly relevant profile to it), or
  via the installed /design-system delegator if one was added.

Trust boundary (write scope)

allowed-tools includes write-capable Edit, Write, and Bash.

Writes: DESIGN.md (created once at the repo-root or docs/ location
Step 3 reasons about, then reconciled on refresh; existing sections the
developer wrote are preserved unless explicitly re-approved), the short
AGENTS.md index/pointer entry Step 3 adds so humans and agents can find the
file (merged — never over an existing section), and — optionally and only on
acceptance — the /design-system delegator command under
.agents/commands/. Everything the addon needs to "see" (existing components,
styles, docs) is read-only analysis.

It MUST NOT: modify source components, styles, or any application file
(DESIGN.md is a specification humans and agents read, not a code generator),
invent tokens no real component uses, or apply a profile the developer declined.

The flow

Step 0 — Consent + interface-surface gate

1. Confirm the developer wants a DESIGN.md (skip silently if declined — the repo
   stays baseline-conformant).
2. Detect the repo's interface surfaces, profile by profile (SPEC.md §3):
   • visual-ui — stylesheets / CSS custom properties, a Tailwind config or
     @theme block, UI components (.tsx/.vue/.svelte/.astro), or a
     token/brand source.
   • cli-output — a CLI/TUI rendering library (rich, chalk, ink, lipgloss,
     ratatui, …) plus a deliberate rendering layer (a display.*/ui.*
     helper, semantic print helpers, documented output patterns). Skip the
     profile for a bare argument parser with raw unstyled prints.
   • conversational — a chat-platform SDK (Slack, Discord, Teams, …), a
     message-composition layer, or documented outbound-message voice rules.
3. If no profile is detected, stop and tell the developer this addon
   does not apply. Otherwise, the offer is mandatory (§3.5): evaluate the
   detected signal, record the detection rationale, and offer each detected
   profile per its strength — strongly recommend visual-ui, recommend
   cli-output and conversational; an ambiguous signal still gets the
   offer, with the ambiguity named. Apply only profiles explicitly accepted
   by the developer. Existing acceptance need not be asked again; an explicit
   decline is respected for that run. Trust alone accepts none.

Step 1 — Locate the design source (the part you MUST reason about)

Find where each accepted profile's design values actually live, using
templates/presets.md:

• Tailwind → tailwind.config.* or a Tailwind v4 @theme {} block in CSS:
  theme colors, font families, spacing, radius, screens.
• CSS variables / vanilla → :root { --… } custom properties in the global
  stylesheet; spacing/size scales; media-query breakpoints.
• Component library / design tokens → a tokens.* / theme.* export, a
  design-tokens JSON, or a Storybook/theme file.
• CLI rendering layer → the display.*/output.*/ui.* helper module, its
  semantic styles and print helpers, spinner/panel/prompt wrappers, and any
  output best-practices doc.
• Message composition layer → the helpers/templates that build outbound
  messages, their envelope kinds (DM/channel/thread/edit), and any documented
  voice/brand-naming rules (often in AGENTS.md or a skill doc).
• Brand/style guide → any BRAND*.md / STYLE*.md doc, plus accessibility
  rules documented in AGENTS.md/CLAUDE.md.

A repo MAY combine sources (a Tailwind config + a brand doc + a CLI display
module). Read all that exist; the real files win over any preset assumption.

Step 2 — Reason out each canonical section, per accepted profile

Using templates/DESIGN.md.md, fill each accepted profile's sections from its
design source (SPEC.md §4):

• visual-ui — Overview/atmosphere · Color palette & roles (light + dark) ·
  Typography · Layout & spacing · Elevation & depth · Shapes/radius · Components
  (in terms of the tokens) · Responsive behavior · Do's & don'ts (incl. the
  repo's accessibility rules).
• cli-output — Output voice & intent · Semantic colors & styles (success/
  error/warning/info/highlight/dim mapped to the real theme) · Output components
  (panels, tables, spinners, progress, prompts — named after the real helpers) ·
  Layout conventions · Degradation & environment (TTY vs pipe, NO_COLOR,
  stdout/stderr, exit codes) · Do's & don'ts.
• conversational — Voice & register (tone, brevity, brand naming) ·
  Message anatomy (envelope kinds + structure) · Platform rendering (only the
  platforms the repo actually targets) · Do's & don'ts.

One Overview and one Agent prompt guide serve the whole file (§4.1). Express
values as named tokens with usage notes; add a machine-readable token block
only if the repo already maintains structured tokens. Flag any value you had to
infer so a human can confirm it.

Step 3 — Write or reconcile DESIGN.md, then index it in AGENTS.md

• Choose the location (SPEC.md §2): if the repo has a docs/ tree (DWP-native),
  write docs/DESIGN.md alongside the other specs; if it has no docs/ tree,
  write ./DESIGN.md at the root. Never create sibling per-surface files
  (CLI_DESIGN.md, CONVERSATION_DESIGN.md) — one repo, one DESIGN.md.
• If no DESIGN.md exists → write it at the chosen location. A single accepted
  profile keeps its sections at the top level; multiple accepted profiles get
  one top-level heading per profile (§4.1).
• If one already exists → reconcile additively (SPEC.md §6): keep working
  values, add missing canonical sections — and when adding a new profile to
  an existing file, append its sections (grouping per §4.1) without rewriting
  the existing content. Ask before any destructive change.
• Index it in AGENTS.md (and therefore CLAUDE.md): add a reference to
  DESIGN.md in the documentation index so agents discover it like the other
  docs/ specs. This pointer — not the physical location — is what guarantees
  discovery (SPEC.md §2).

Step 4 — Validate (the gate)

Run the validation step (SPEC.md §11):

• DESIGN.md exists at the chosen location (docs/DESIGN.md or root) with all
  canonical sections for each accepted profile, and AGENTS.md references
  it; no sibling per-surface files were created.
• Every documented value traces to the real design source (spot-check a few
  against the stylesheet/config/display module/message helpers); inferred
  values flagged.
• Per-profile integrity (SPEC.md §7): text-color pairings meet WCAG AA
  (visual-ui); color is not the sole carrier of meaning and degradation rules
  are documented (cli-output); rich renderings note plain-text fallbacks
  (conversational); token references resolve (no orphans/broken refs).
• New profiles were asked about before applying — never auto-applied.
• File is Markdown-first and compact (~2–5K tokens single-profile, ≤ ~8K
  multi-profile); no build dependency added.

Step 5 — (Optional) install the /design-system delegator

If the developer wants a one-command refresh later, install a /design-system
delegator into the repo's .agents/commands/ (template:
templates/design-system-command.md) that re-runs this addon. Skip if not wanted —
a declined command leaves a baseline-conformant repo.

Failure-mode guardrails

• Never required, never blocking. If the developer declines, stop cleanly.
• Interface surfaces only. Skip for repos with no interface surface of any
  kind (pure library, headless service, infra-only) — applying it there is a defect.
• Offer mandatorily, accept explicitly. A detected interface surface makes
  the evaluation and offer mandatory in both modes; installation still needs
  explicit acceptance — no profile is auto-applied, even in trust mode. (The
  required local AI Diff Reviewer installs as baseline; the near-default
  dependency-upgrade delegator installs inert under the onboarding consent
  unless declined — neither applies a design profile.)
• Reason about the source. Document the repo's real values; never paste a
  brand file or another product's conventions.
• One file. Profiles stack inside DESIGN.md; never create per-surface siblings.
• Reconcile, don't clobber. Preserve a working DESIGN.md; ask before destructive edits.
• Protect integrity. Capture the repo's contrast rules (visual), degradation
  rules (CLI), and plain-text fallbacks (conversational); don't document failing patterns.
• Reference, don't hard-bind. Follow the convention's shape, not its Alpha format details.