design-agent

# Design-Agent — DSH Design Agent Workspace This is a **complete reproducible package** for a Design Agent based on [DeepSeek Harness (DSH)](https://github.com/deepseek-ai/deepseek-harness). It includes the `my-agent` preset, `design-references` routing skill (DSH-adapted), and `design-router` deterministic tool plugin. The project upgrades an existing HTML-based design agent by adopting the [design-references](https://github.com/haohaiHuang/my-pi-skills/tree/main/skills/design-references) methodology. > ⚠️ **This package reproduces mechanisms, not content.** Routing, discipline, and tools are fully self-contained (clone → `cp -RL` → run). However, *reference libraries* are personalized—several key resources point to `~/Desktop/Design/...` and `~/resources/design-references.md`, which are private assets not provided with the repository. On new machines, these will degrade to fallback chains (`web_search` + `dembrandt` + built-in hallmark disciplines). For a complete personal reference set, please copy these directories yourself; without them, this package still functions as a "hallmark discipline + web research" design agent. ## Contents | Component | Role | | --- | --- | | [`plugins/design-router/`](plugins/design-router/) | Deterministic tool Cordis plugin (6 read-only tools + 1 local log writer, zero external runtime dependencies) | | [`presets/my-agent/`](presets/my-agent/) | DSH Agent preset (`agent.cordis.yml` + `preset.yml`): Three-layer routing roles (stage → branch → stage) with per-stage confirmation gates | | [`skills/design-references/`](skills/design-references/) | Stage/branch routing skill (stage splitting → A Product / B Content / C General → five stages), DSH-adapted | | [`skills/hallmark/`](skills/hallmark/) | Anti-AI-slop execution skill (MIT upstream copy from [nutlope/hallmark](https://github.com/nutlope/hallmark); `site/` theme tokens and examples built into the skill, self-contained) | > **DSH Version Requirement: `0.1.5-rc.1` or higher.** The role plugin pattern changed in 0.1.5 (`text` → `prefix` + `suffix`); presets still using `text:` will fail to mount with `$.prefix missing required value`. This repository's presets are based on the 0.1.5 pattern and use the two lines introduced in 0.1.5: `present` (`dsh-tool-present`, delivery statement) and `command-goal` (`/goal` command). ## plugins/design-router — Deterministic Tools Ported from `extensions/design-router` in [my-pi-skills](https://github.com/haohaiHuang/my-pi-skills) (pi extension → DSH Cordis plugin). Mounted by the `my-agent` preset via **relative path lines** in `agent.cordis.yml` (the preset's `plugins/` is a relative symbolic link to the repository root `plugins/`, expanded during installation via `cp -RL`—no absolute paths needed): ```yaml - id: design-router name: './plugins/design-router/index.mjs' ``` ### Tools | Tool | Purpose | Stage | | --- | --- | --- | | `design_lookup <branch> <stage>` | Query design resource registry (R/C/E/V 3-D index + fallback chain + source; output tag-style buckets) | "What should I look up at this step?" | | `design_route <need>` | Map requirement keywords to recommended style bucket combinations (primary mandatory + secondary on-demand) + representative resources per bucket | Stage 1 Research (anti-homogenization routing) | | `design_diversity <c1> <c2> <c3>` | Machine check diversity of 3 candidates (hue family / font tone / source bucket), pass/fail | Before presenting candidates in Stage 1 (anti-homogenization check) | | `design_quality <report\|query>` | Record/query source quality signals (extraction success rate / rework rate / accessibility—objective, not taste-oriented); local log, not in git | Post-Stage 4 recording / Stage 1 descending consumption | | `design_audit <target>` | Machine slop gate (hallmark machine subset) + Interface CS-* 8 rules + Stage 4 scan + inheritance comparison | Stage 4 Verification | | `design_contrast <target>` | WCAG 2.1 + APCA approximate contrast | Stage 4 Verification | ### Intentional Differences from pi Version - **Removed** `design_research` (DSH uses ledger-grep + refero probes + `web_search` fallback chain) - **Removed** `hallmark_study_fetch` (DSH uses `dembrandt` / `defuddle` instead) - **Removed** `before_agent_start` injection and `/design-router` command (DSH's skill loading mechanism covers routing) - **Does not depend on `@deepseek-ai/dsh-tools`** (workspace modules cannot resolve dsh install directory); tool definitions use pure JSON Schema construction—zero external runtime dependencies ### Layout ``` plugins/design-router/ ├── index.mjs # Plugin entry: registers 6 tools (5 read-only + 1 local log writer) ├── checks/ # Ported checkers (TS→JS): typography/layout/accessibility/copy/contrast/slop/assets/types │ └── kill-slop.test.mjs # KS-* regression test (node checks/kill-slop.test.mjs) └── data/ └── registry.json # Data form of registry.md (91 resources × 9 branch routes) ``` ### Machine Gate Coverage `design_audit` runs seven checker modules and returns a todo list with gate numbers: | Family | Gates | Source | | --- | --- | --- | | Hallmark Slop | 1/2/10/14/19/24/26/27/30/33/34/37/38a/39/40/41/46/47/50/51 | hallmark `slop-test.md` (machine subset) | | Interface CS-* | CS-1…CS-8 | interfaces.dev cheat sheet | | Animation EM-* | EM-2/3/5 (EM-1/7/8 map to gates 10/14/27) | emilkowalski/skills | | kill-ai-slop KS-* | KS-03/04/05/08/14 | kill-ai-slop transcript | | Asset Layer DR-A* | DR-A1/DR-A2 | Anshu asset layer gates (brand logo/image existence) | | design-references Stage 4 | DR-4 (font weight/border-radius overspecification) | design-references workflow.md | ### Maintenance - `registry.md` is the **source of truth** (`~/.agents/skills/design-references/references/registry.md`); after editing, run `node plugins/design-router/scripts/build-registry.mjs` to regenerate `data/registry.json` (+ `data/manifest.json` version metadata). **Do not manually edit registry.json.** - Checker logic follows upstream `extensions/design-router/checks/` (TS→MJS port); after upstream updates, run `node plugins/design-router/scripts/check-checks-sync.mjs /path/to/my-pi-skills/extensions/design-router/checks` to verify gate coverage—**then manually compare checker constants**: gate number parity does not capture detail drift (e.g., extended default font lists). KS regression tests capture such drift. - After any checker changes: `node index.test.mjs` and `node checks/kill-slop.test.mjs`. ## One-Time Reproduction (New Machine) The repository reproduces **mechanisms**: plugins + presets + DSH-adapted skills are all within the repo (reference library *content* is personalized—see warning above). ```bash # ── Provided with repo (clone → run)── # 1. Skills (design-references is DSH-adapted; hallmark is MIT upstream copy) cp -R skills/design-references ~/.agents/skills/ cp -R skills/hallmark ~/.agents/skills/ # 2. Preset (cp -RL expands relative plugin symlinks in presets/my-agent/ into self-contained copies— # after installation, the preset no longer depends on repo paths and can be freely copied or migrated) mkdir -p ~/.dsh/.agent-presets cp -RL presets/my-agent ~/.dsh/.agent-presets/ # 3. Plugin source code (kept under plugins/ in repo root for git management) # The preset references via relative path './plugins/design-router/index.mjs': # presets/my-agent/plugins is a relative symlink to repo root plugins/, # cp -RL expands it into a real directory—no path editing needed on any machine. # 4. External dependencies (soft dependencies—graceful degradation if missing) npm install -g dembrandt # URL → design tokens (Stage 1 candidate validation) # defuddle: npm install -g defuddle # npm install -g @open-pencil/cli # Optional: read/convert/validate .fig/.pen design files (fallback to Figma family skills / manual review) # ── Bring Your Own (personal choice; degrades to fallback chain if missing)── # 5. Machine-local assets (ledger + kami/zine/logo-generator reference libraries) # Without them, this package still works—as a "hallmark discipline + web_search/dembrandt" # Design Agent—but the candidate pool loses your personal choices. ``` **Note**: The preset's plugin line uses **relative paths** (`./plugins/design-router/index.mjs`, `presets/my-agent/plugins` as relative symlink expanded by `cp -RL`), so new machines only need to copy the preset directory—**no path editing required**. If you want to avoid symlinks, you can copy `plugins/design-router/` to `presets/my-agent/plugins/` and use regular `cp -R` (same result, just an extra copy). ### Repository Structure ``` ├── plugins/design-router/ # Deterministic tool plugin (6 tools, zero runtime dependencies) ├── presets/my-agent/ # DSH preset (agent.cordis.yml + preset.yml) ├── skills/ │ ├── design-references/ # Routing skill (DSH-adapted) │ └── hallmark/ # Anti-AI-slop skill (MIT upstream copy, with site/ theme assets) ├── README.md # English (primary) └── README.zh.md # Chinese ``` ## Third-Party Content and License Attribution This repository bundles the following third-party content (retaining upstream licenses/attribution): | Content | Source | License | Location | | --- | --- | --- | --- | | hallmark skill + `site/` theme tokens and examples | [nutlope/hallmark](https://github.com/nutlope/hallmark) | MIT (full text in [`skills/hallmark/LICENSE`](skills/hallmark/LICENSE)) | `skills/hallmark/` | | External design resources referenced in registry (kami/zine/logo-generator etc.) | Their respective upstream repos | Link references only (not bundled; source URLs in [`registry.md`](skills/design-references/references/registry.md)) | — | All other content (`plugins/`, `presets/`, `skills/design-references/`) is original to this repository, licensed under [MIT License](LICENSE) (Copyright © 2026 haohaiHuang). ## Related Projects - [DeepSeek Harness](https://github.com/deepseek-ai/deepseek-harness) — Infrastructure running this package (`dsh`, everything is a plugin) - [my-pi-skills](https://github.com/haohaiHuang/my-pi-skills) — Upstream skill repository (design-references / skill-router / vision) - [awesome-dsh-plugin](https://github.com/awesome-dsh-plugin/awesome-dsh-plugin) — Curated list of DSH plugins