product-design

Files (29)

• README.md
• SKILL.md
• evals.json · evals/
• README.md · evals/inputs/
• PRD.md · evals/inputs/briefbox/docs/
• UXD.md · evals/inputs/briefbox/docs/
• project.md · evals/inputs/briefbox/
• PRD.md · evals/inputs/lumen/docs/
• project.md · evals/inputs/lumen/
• DESIGN.md · evals/inputs/trimly-reentry/docs/
• DESIGN_open_issues.md · evals/inputs/trimly-reentry/docs/
• PRD.md · evals/inputs/trimly-reentry/docs/
• UXD.md · evals/inputs/trimly-reentry/docs/
• cycle-1.md · evals/inputs/trimly-reentry/docs/trail/uxd/
• project.md · evals/inputs/trimly-reentry/
• tokens.css · evals/inputs/trimly-reentry/src/styles/
• PRD.md · evals/inputs/trimly/docs/
• UXD.md · evals/inputs/trimly/docs/
• cycle-1.md · evals/inputs/trimly/docs/trail/uxd/
• project.md · evals/inputs/trimly/
• tokens.css · evals/inputs/trimly/src/styles/
• claude.md · intelligence/
• codex.md · intelligence/
• gemini.md · intelligence/
• hf.md · intelligence/
• ollama.md · intelligence/
• launcher.md
• rich.md · prompts/
• stack.json

SKILL.md (first lines)

# product-design

## Purpose

Author a project's **design language** (`DESIGN.md`): the visual source of truth — the tokens
that are normative and the prose that applies them — read cold by implementing agents to style
the product. It is written **off the UXD's design-system direction call**: that call names the
system and the constraints, and this document holds every value — a token value carried in both
is a defect of whichever document copied it. The sequence is
`<CORE>/doctrine/setup/setting_up_a_project.md`, which owns it and is not restated here.

The format is **external and machine-checked** — Google's DESIGN.md, linted by
`@google/design.md`. The schema's authority is the vendor, not this skill and not the template;
which invocation is pinned and what a clean result means are the prompt's.

This file is the **orchestrator**: posture, the file loop, path resolution, the machine-gate
step, staging, and the commit. **How to author** — the design-language completeness lens, the
evidence gate, the anti-default discipline, the provenance gate, the machine gate's bar, the
stability rule, and the tone — is the authoring prompt
**`prompts/rich.md`**, applied at Step 2; a rule referenced below by name
lives there. The design language's **section shape and token schema as stamped** are the template
**`<CORE>/templates/product-templates/design_template.md`**; the companion's shape is
**`design_open_issues_template.md`** beside it. None of them is restated here.

**Non-interactive.** The run never blocks on the owner: it derives the whole design language
best-effort, writes its load-bearing calls into a companion open-issues file the owner signs off on
their own time, and a re-run folds those answers in. That is what lets it run headless (as the
`cdo` subagent) as well as in an interactive `cdo:` session.

---

## Posture

**CDO role required.** If invoked outside CDO posture (neither a `cdo:` session nor the `cdo`
subagent), stop and say: *"product-design requires CDO posture. Switch? (Open a session with
the `cdo:` prefix, or run the `cdo` subagent.)"* Do not shed the role. Where the CDO ends and the
delivery-tier **Architect** begins is a posture fact the CDO loader stack already owns — the two
share the word "design" and nothing else, and the boundary comes from there, never from a
restatement here.

---

## The files and the loop

product-design produces the files below under the product's `docs/` — the skill resolves the
locations (next section); a caller names the **project**, never the paths.

| File | What it is | Lifecycle |
|---|---|---|
| `<Product path>/docs/DESIGN.md` | The design language — best-effort complete on every run. | Permanent; one document, revised and versioned in place (the bump-on-revision rule is the template's own header note), never forked. |
| `<Product path>/docs/DESIGN_open_issues.md` | The companion, holding the calls awaiting the owner's sign-off and the few things the run could not settle, in the buckets `design_open_issues_template.md` defines — kept distinct, never blurred. Which bucket an item lands in is the prompt's. | Transient — exists only while something is unresolved. **Its absence is the done signal.** |
| `<Product path>/docs/trail/design/cycle-<N>.md` | Each answered companion, retired whole. | Permanent. |

**Cycle numbering:** `N` is one higher than the **highest** `cycle-<N>.md` already in
`trail/design/` — list the directory and take the max, so a removed or renamed cycle can't make
you collide with an existing one. The first is `cycle-1.md`; create `trail/design/` if it isn't
there. Never overwrite an existing cycle.

**The loop, repeated until clean:**

1. The run derives/updates the design language and writes the companion with what it couldn't
   ground.
2. The **owner answers inline** — filling the companion's answer slots, whose names and shape are
   `design_open_issues_template.md`'s, stated there and not here — and re-runs the skill.
3. The run **copies the answered companion whole to the next trail cycle**, folds the answers
   into the design language, and rewrites the companion with only what is still unresolved — an
   answer the fold leaves unsettled still drops, its residue re-raised as a fresh unanswered
   item. This is the ordinary cycle — something survives the fold. A run where nothing would is
   step 4's, and step 4 alone says what it may touch.
4. When the answers resolve everything, the run is the close: one run that folds, copies the
   answered companion to the trail, and **removes** the companion instead of rewriting it —
   through the builder, Step 4's `--rm`, never a hand-`rm`. **No open-issues file = the design
   language is done.** The close has a precondition the ordinary cycle does not: the owner's
   answers must already be committed (Workflow Step 4 owns the rule and why). Re-entry is inline
   answers, so the first closing touch normally finds them uncommitted — and then it **changes
   nothing at all**: no fold, no trail copy, no rewrite, no commit; the companion survives
   intact, answers and all, for the owner to commit. It reports the state and asks for that
   commit; the re-run after it is the close, start to finish, in one run. That stop is a report
   with an ask, not a live interview.

Step 3 is why the trail exists. Folding rewrites the companion and the close removes it — so
without the trail the owner's answers are destroyed twice, and their reasoning for a decision
survives only in git history. The trail costs one `cp` on the same commit and makes every owner
answer permanently citable. It is the skill's job; the owner never manages it.

---

## Inputs and where the files land

- **The UXD** — your primary input; read it in full. Its location is `product-uxd`'s to name —
  that skill wrote it, and its own file table owns where the UXD lands under the product's
  `docs/`; resolve the path from `<CORE>/../skills/cdo/.claude/skills/product-uxd/SKILL.md`, never from a path
  remembered here. It must exist: if nothing is at the resolved path, halt and report — the
  design language is authored off the UXD's direction call, so there is nothing to derive one
  from. What the UXD's content means for the derivation — the direction call it seeds from, the
  accessibility requirements that bind the values — is the prompt's rule.
- **The product's own source** — locate and read whatever holds the product's existing visual
  decisions; what counts as that evidence is the prompt's § *Inputs you work from*. For an
  existing product this is the evidence base, and finding nothing is itself a finding the prompt
  says how to route — never a halt.
- **The PRD** — beside the UXD under the product's `docs/`; its location is `product-prd`'s to
  name, resolved from `<CORE>/../skills/cpo/.claude/skills/product-prd/SKILL.md`. Read it if it is there; what it
  feeds is the prompt's § *Inputs you work from*. **Its absence does not halt the run** — the
  state reaches the owner through the companion like any other input gap.
- **`system/projects/<name>/agari.md`** — the project's 上がり Agari, beside the card below. Read it
  in full; what the terminus bounds is the prompt's rule. **Absence does not halt the run**, nor
  does an unfilled placeholder — the state reaches the owner through the companion.
- **`system/projects/<name>/doctrine/`** — the project's own doctrine, if the folder holds anything.
  Read what is there; what it binds is the prompt's rule. Empty or absent is silence, not a halt.
- **The product's `docs/` folder** — read it by **listing the directory**, not by recalling a
  set of filenames. Beyond the files named here and the loop files above, whatever else the
  folder holds is input the run is entitled to: brand material, the product request, the UXD's
  and PRD's own trails of owner answers. What each carries, and which supersedes which, is the
  prompt's § *Inputs you work from*. Skip binary assets. Enumerating rather than naming is
  deliberate — a list of filenames kept here goes stale the day the product gains a document,
  and the run would never know what it had missed.
- **Context and constraints** — whatever the owner hands you, or the docs it points at. What
  counts as one is the prompt's § *Inputs you work from*; read the list there, it is not
  restated here.

From eyalgo/kensaiapp, MIT.

More from eyalgo/kensaiapp