[codex] Add DESIGN.md skill support (#21)

* Add DESIGN.md skill support

* fix(design-md): narrow triggers, add precondition, align activation, register decision

Follow-up to PR #21 (the original adds the design-md skill). Cross-model
review (Claude + Codex) flagged 9 issues; addressing all of them in one
commit so the PR can land.

P1 — Triggers were too broad. Original list included "UI", "frontend",
"components", "styling" — substring-matched against every UI task in any
project, even ones with no DESIGN.md. Existing skills (git-proxy,
deploy-checklist) use 4–7 specific phrases. Trimmed to 7 narrow triggers
focused on DESIGN.md / Google Stitch / design tokens / design system /
visual design.

P2 — Missing precondition. Skill is only useful when DESIGN.md exists at
the project root. git-proxy uses ["..git exists"]; design-md now uses
["DESIGN.md exists at project root"] following the same pattern. Skill
loader short-circuits when the file isn't there.

P2 — Activation rules drifted between AGENTS.md and the manifest. AGENTS.md
said to load the skill "during UI, frontend, component, styling, or
prototype work" while the manifest used a different (overly broad) trigger
set. Same task, different harness, different behavior. AGENTS.md now
mirrors the manifest's narrower trigger list and notes the
preconditions-gated load.

P2 — Skill body had no "don't modify DESIGN.md by default" guard. For a
contract file, read-only-by-default is the right posture. Added an explicit
"Default: read-only" section + a constraint that says "do not modify
DESIGN.md unless the user explicitly asks". Implementation work consumes
the contract; it doesn't edit it.

P3 — Skill was not logged in .agent/memory/semantic/DECISIONS.md.
docs/writing-skills.md:50 says new skills must be logged there. Added a
2026-04-26 entry covering the decision, rationale, and rejected alternatives.

P3 — Self-rewrite hook didn't follow the repo's own format. Replaced the
vague "if UI work repeatedly drifts" prose with the standard "after every
5 uses OR on any failure" template from docs/writing-skills.md:36-44 with
concrete steps and a commit message format.

P3 — Stale "five seed skills" copy. README.md:124 said "five" and
docs/demo/src/scenes/Outro.tsx:6 hardcoded `value: "5"` for seed skills,
but the same PR adds a sixth. Both bumped to 6.

P3 — Validation guidance overstated the manual fallback. The CLI checks
contrast ratios and orphaned tokens; the manual checklist doesn't. Note
that the manual fallback is best-effort and re-run the CLI when network
is available.

Codex confirmed `@google/design.md` exists on npm and the CLI commands
in the skill body are correct (https://github.com/google-labs-code/design.md).

---------

Co-authored-by: codejunkie99 <email@email.com>

Author: danielfoch

.agent/AGENTS.md

@@ -41,6 +41,19 @@ are the exact failure mode this layer prevents.
 - Load a full `SKILL.md` only when its triggers match the current task
 - Every skill has a self-rewrite hook; invoke it after failures
 
+## Design Systems
+- If the project root contains `DESIGN.md`, treat it as the source of truth
+  for visual design decisions and load `skills/design-md/SKILL.md` when a
+  task mentions `DESIGN.md`, Google Stitch, design tokens, design system,
+  or visual design. (The skill's `preconditions` field gates loading on
+  `DESIGN.md` actually existing — keep this rule in lockstep with
+  `skills/_manifest.jsonl` to avoid same-task / different-harness drift.)
+- Prefer exact tokens, component rules, and design rationale from
+  `DESIGN.md` over invented colors, typography, spacing, shadows, or motion.
+- Do not modify `DESIGN.md` unless the user explicitly asks for a design
+  system change; implementation work consumes the contract, it doesn't
+  edit it.
+
 ## Protocols
 - `protocols/permissions.md` — read before any tool call
 - `protocols/tool_schemas/` — typed interfaces for external tools

.agent/memory/semantic/DECISIONS.md

@@ -14,3 +14,9 @@
 **Rationale:** Each layer has different retention and retrieval needs. Flat memory breaks at ~6 weeks.
 **Alternatives considered:** Flat directory (fails at scale), vector store (over-engineered for single user).
 **Status:** active
+
+## 2026-04-26: Add `design-md` seed skill (DESIGN.md / Google Stitch)
+**Decision:** Ship a sixth seed skill, `design-md`, that points coding agents at a root `DESIGN.md` (Google Stitch format) as the visual-system source of truth. Loads only when `DESIGN.md` exists at the project root, default behavior is read-only on the contract file, and validation prefers `npx @google/design.md lint DESIGN.md` over hand-checks.
+**Rationale:** `DESIGN.md` is becoming a de facto contract for AI-driven UI work; without an explicit skill, agents invent ad-hoc tokens that drift from the user's design system. Gating on `DESIGN.md`-existence keeps the skill silent on projects that don't use the format.
+**Alternatives considered:** Bundle the rules into `git-proxy` or `skillforge` (wrong scope, wrong triggers); leave it to per-project `.agent/skills/` overrides (loses the cross-harness benefit); broader triggers like "UI"/"frontend"/"components"/"styling" (too generic, loads on every UI task even without DESIGN.md).
+**Status:** active

.agent/skills/_index.md

@@ -26,3 +26,15 @@ Pre-deployment verification against a structured checklist.
 Triggers: "deploy", "ship", "release", "go live"
 Constraints: all tests passing, no unresolved TODOs in diff,
 requires human approval for production.
+
+## design-md
+Uses a root `DESIGN.md` as the portable visual system contract for
+Google Stitch workflows. Loads only when `DESIGN.md` exists at the
+project root.
+Triggers: "DESIGN.md", "design.md", "Google Stitch", "design tokens",
+"design system", "visual design"
+Preconditions: DESIGN.md exists at project root.
+Constraints: prefer DESIGN.md tokens over invented values, do not modify
+DESIGN.md unless the user explicitly asks, preserve unknown sections when
+an edit IS authorised, validate with `npx @google/design.md lint DESIGN.md`
+when available.

.agent/skills/_manifest.jsonl

@@ -3,3 +3,4 @@
 {"name":"git-proxy","version":"2026-01-01","triggers":["commit","push","branch","merge","rebase","pull request","PR"],"tools":["bash"],"preconditions":[".git exists"],"constraints":["never force push to main","never force push to protected branches","run tests before push"],"category":"operations"}
 {"name":"debug-investigator","version":"2026-01-01","triggers":["debug","why is this failing","investigate","stack trace","bug"],"tools":["bash","memory_reflect"],"preconditions":[],"constraints":["reproduce before fixing","fix root cause, not symptoms"],"category":"engineering"}
 {"name":"deploy-checklist","version":"2026-01-01","triggers":["deploy","ship","release","go live"],"tools":["bash"],"preconditions":[],"constraints":["all tests passing","no unresolved TODOs in diff","requires human approval for production"],"category":"operations"}
+{"name":"design-md","version":"2026-04-26","triggers":["DESIGN.md","design.md","Google Stitch","Stitch","design tokens","design system","visual design"],"tools":["bash","memory_reflect"],"preconditions":["DESIGN.md exists at project root"],"constraints":["prefer DESIGN.md tokens over invented values","do not modify DESIGN.md unless the user explicitly asks","preserve unknown sections when an edit IS authorised","validate when tooling is available"],"category":"design"}

.agent/skills/design-md/SKILL.md

@@ -0,0 +1,92 @@
+---
+name: design-md
+version: 2026-04-26
+triggers: ["DESIGN.md", "design.md", "Google Stitch", "Stitch", "design tokens", "design system", "visual design"]
+tools: [bash, memory_reflect]
+preconditions: ["DESIGN.md exists at project root"]
+constraints: ["prefer DESIGN.md tokens over invented values", "do not modify DESIGN.md unless the user explicitly asks", "preserve unknown sections when an edit IS authorised", "validate when tooling is available"]
+---
+
+# DESIGN.md — portable visual system contract
+
+Use this skill when a task touches Google Stitch's `DESIGN.md` format or
+the project explicitly references its design system / design tokens. The
+skill loads only when `DESIGN.md` exists at the project root (see
+`preconditions` above), so general UI / frontend / component work that
+isn't tied to a `DESIGN.md` won't trip it.
+
+## Source of truth
+- `DESIGN.md` is a contract file. Read it before changing visual UI.
+- Treat YAML front matter tokens as normative values: colors, typography,
+  spacing, radius, and component tokens are exact inputs to code.
+- Treat the Markdown body as design rationale: it explains mood, hierarchy,
+  interaction intent, and where tokens should or should not be used.
+- If no `DESIGN.md` exists this skill is inactive; for new UI, offer to
+  create one or ask for a brand/reference, but don't generate one
+  unprompted.
+
+## Default: read-only
+**Do not modify `DESIGN.md` unless the user explicitly asks for a design
+system change.** Implementation work consumes the contract; it does not
+edit it. Token additions, renames, or section restructures land in their
+own commit with a clear message and (ideally) a Stitch round-trip.
+
+## Implementation rules
+1. Map tokens into the local styling system already in use: CSS variables,
+   Tailwind theme values, design-token JSON, component props, or native
+   styles.
+2. Use token references and component patterns from `DESIGN.md` instead of
+   hard-coded one-off values.
+3. Keep accessibility constraints intact. Do not weaken contrast, focus,
+   reduced-motion, or touch-target guidance unless the user explicitly
+   asks.
+
+## When an edit IS authorised
+1. Preserve unknown headings and extra prose; other agents or Stitch may
+   own them.
+2. Express component variants as related entries
+   (`button-primary`, `button-primary-hover`, etc.).
+3. Land token / structure changes in their own commit, separate from the
+   feature consuming them.
+
+## Validation
+- If Node/npm tooling is available, lint with:
+
+  ```bash
+  npx @google/design.md lint DESIGN.md
+  ```
+
+- For design system changes, diff before/after:
+
+  ```bash
+  npx @google/design.md diff DESIGN.before.md DESIGN.md
+  ```
+
+- If the CLI is unavailable or network/dependency policy blocks it, the
+  manual fallback is best-effort only — check for broken `{path.to.token}`
+  references, missing primary color / typography tokens, duplicate section
+  headings, and section order. The CLI ALSO checks contrast ratios and
+  orphaned tokens; the manual fallback does not, so re-run the CLI when
+  you regain network access.
+
+## Expected sections
+The Google draft spec uses YAML front matter plus Markdown sections.
+Common sections:
+
+- `## Overview`
+- `## Colors`
+- `## Typography`
+- `## Layout`
+- `## Elevation & Depth`
+- `## Shapes`
+- `## Components`
+- `## Do's and Don'ts`
+
+## Self-rewrite hook
+After every 5 uses OR on any failure:
+1. Read the last N skill-specific episodic entries.
+2. If a new failure mode has appeared (e.g. tokens drifting away from
+   DESIGN.md, accessibility rules being weakened, unauthorised edits to
+   the contract file), append it to this skill's `KNOWLEDGE.md`.
+3. If a constraint was violated, escalate to `semantic/LESSONS.md`.
+4. Commit: `skill-update: design-md, <one-line reason>`.

README.md

@@ -188,7 +188,7 @@ See [`docs/architecture.md`](docs/architecture.md) for the full lifecycle.
 
 Every guide shows the folder structure. This repo gives you the folder
 structure **plus the files that actually go inside**: a working portable
-brain with five seed skills, four memory layers, enforced permissions, a
+brain with six seed skills, four memory layers, enforced permissions, a
 nightly staging cycle, host-agent review tools, and adapters for multiple
 harnesses.
 
@@ -201,7 +201,9 @@ harnesses.
   a required rationale. No unattended reasoning, no provider coupling.
 - **Skills** — progressive disclosure. A lightweight manifest always
   loads; full `SKILL.md` files only load when triggers match the task.
-  Every skill ships with a self-rewrite hook.
+  Every skill ships with a self-rewrite hook. The bundled `design-md`
+  skill teaches agents to use a root `DESIGN.md` as the visual source of
+  truth for UI and Google Stitch workflows.
 - **Protocols** — typed tool schemas, a `permissions.md` that the
   pre-tool-call hook enforces, and a delegation contract for sub-agents.
 
@@ -315,6 +317,8 @@ verify_codex_fixes.py           # v0.8.0 regression checks (33 checks)
 - **git-proxy** — all git ops, with safety constraints
 - **debug-investigator** — reproduce → isolate → hypothesize → verify
 - **deploy-checklist** — the fence between staging and production
+- **design-md** — uses Google Stitch-style `DESIGN.md` files as portable
+  design-system context for UI, frontend, and component work
 
 ## How it compounds
 

docs/demo/src/scenes/Outro.tsx

@@ -3,7 +3,7 @@ import { COLORS, FONT } from "../tokens";
 
 const STATS = [
   { value: "7", label: "harnesses" },
-  { value: "5", label: "seed skills" },
+  { value: "6", label: "seed skills" },
   { value: "4", label: "memory layers" },
 ];
 

docs/getting-started.md

@@ -42,6 +42,19 @@ Open your harness and ask it anything. The first few days it will feel
 stateless. After ~2 weeks you'll notice it checking past lessons, logging
 failures with reflection, and (if you let it) proposing skill rewrites.
 
+## Optional: add a visual system with `DESIGN.md`
+
+If your project has UI, drop a Google Stitch-style `DESIGN.md` file in the
+project root. The bundled `design-md` skill tells compatible agents to use
+that file as the source of truth for colors, typography, spacing, component
+rules, and design rationale instead of inventing visual choices.
+
+When Node tooling is available, agents can validate the file with:
+
+```bash
+npx @google/design.md lint DESIGN.md
+```
+
 ## Verify the wiring
 ```bash
 python3 .agent/tools/budget_tracker.py "commit and push"