Design-Agent — DSH Design Agent workspace

A fully reproducible package for a design agent on DeepSeek Harness (DSH): the my-agent preset, the design-references routing skill (DSH-adapted), and the design-router deterministic-tool plugin. Built by upgrading an existing HTML-based design agent with the design-references methodology.

⚠️ What this package reproduces: the machinery, not the content. The routing, discipline, and tools are fully self-contained (clone → cp -RL → run). But the reference library is personal — several primary-level resources point at ~/Desktop/Design/... and ~/resources/design-references.md, private assets that do not ship with the repo. On a fresh machine those degrade to the fallback chain (web_search + dembrandt + the bundled hallmark discipline). If you want the full personal reference set, copy those directories yourself; without them the package still works, as a "hallmark discipline + web research" design agent. See One-shot reproduction for what ships vs. what you bring.

🇨🇳 中文版见 README.zh.md

What's inside

Component	Role
plugins/design-router/	Deterministic-tool Cordis plugin (6 read-only tools + 1 local-log writer, zero external runtime deps)
presets/my-agent/	DSH agent preset (agent.cordis.yml + preset.yml): three-layer routing persona (stage → branch → phase) with per-phase confirmation gates
skills/design-references/	Stage/branch routing skill (stage triage → A product / B content / C general → five phases), DSH-adapted
skills/hallmark/	Anti-AI-slop execution skill (MIT upstream copy from nutlope/hallmark; site/ theme tokens & examples bundled in-skill, self-contained)

DSH version requirement: 0.1.5-rc.1 or later. The persona plugin schema changed in 0.1.5 (text → prefix + suffix); a preset still using text: fails to mount with $.prefix missing required value. This repo's preset is on the 0.1.5 schema and also uses two rows introduced in 0.1.5: present (dsh-tool-present, deliverable declaration) and command-goal (/goal command).

plugins/design-router — deterministic tools

Ported from my-pi-skills extensions/design-router (pi extension → DSH Cordis plugin). Mounted by the my-agent preset via a relative-path row in agent.cordis.yml (the preset's plugins/ is a relative symlink to the repo-root plugins/, expanded by cp -RL on install — no absolute paths needed):

- id: design-router
  name: './plugins/design-router/index.mjs'

Tools

Tool	Purpose	Phase
design_lookup <branch> <stage>	Query the design-resource registry (R/C/E/V 3-D index + fallback chain + sources; output tags style buckets)	"What do I consult at this step?"
design_route <need>	Map need keywords to recommended style-bucket combos (primary must-check + secondary on-demand) + per-bucket representative resources	Phase 1 research (anti-homogeneity routing)
design_diversity <c1> <c2> <c3>	Machine check of 3 candidates' difference (hue family / font tone / source bucket), PASS/FAIL	Before presenting candidates in Phase 1 (anti-homogeneity check)
design_quality <report|query>	Record/query source-quality signals (extraction success / rework rate / reachability — objective, not taste-based); local log, not in git	Record after Phase 4 / consume for downranking in Phase 1
design_audit <target>	Machine slop gates (hallmark machine subset) + interfaces CS-* 8 rules + phase-4 scans + inherited-contrast	Phase 4 verification
design_contrast <target>	WCAG 2.1 + APCA-approx contrast	Phase 4 verification

Intentional differences from the pi version

• Removed design_research (DSH uses the ledger-grep + refero probe + web_search fallback chain)
• Removed hallmark_study_fetch (DSH uses dembrandt / defuddle instead)
• Removed before_agent_start injection and the /design-router command (DSH's skill-loading mechanism already covers routing)
• No dependency on @deepseek-ai/dsh-tools (a workspace module cannot resolve the dsh install directory); tool definitions are built with plain JSON Schema — zero external runtime deps

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/a11y/copy/contrast/cheat/kill-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 gate-numbered punch list:

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)
interfaces CS-*	CS-1…CS-8	interfaces.dev cheat-sheet
Motion 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 transcription
Asset layer DR-A*	DR-A1/DR-A2	Anshu asset-layer gates (brand logo/image presence)
design-references phase 4	DR-4 (font-weight / radius off-scale)	design-references workflow.md

Maintenance

• registry.md is the source of truth (~/.agents/skills/design-references/references/registry.md); after editing it, run node plugins/design-router/scripts/build-registry.mjs to regenerate data/registry.json (+ data/manifest.json version metadata). Never hand-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 diff the checker constants by hand: gate-number parity does not catch detail drift (e.g. an expanded default-font list). The KS regression test catches that class of drift.
• After any checker change: node index.test.mjs and node checks/kill-slop.test.mjs.

One-shot reproduction (fresh machine)

The repo reproduces the machinery: plugin + preset + DSH-adapted skills are all in-repo (reference-library content is personal — see the warning at the top).

# ── Ships with the repo (clone → run) ──
# 1. Skills (design-references is DSH-adapted; hallmark is an MIT upstream copy)
cp -R skills/design-references ~/.agents/skills/
cp -R skills/hallmark ~/.agents/skills/

# 2. Preset (cp -RL expands the relative plugins symlink in presets/my-agent/
#    into a self-contained copy — after install the preset no longer depends on
#    the repo path, so it can be copied around or migrated freely)
mkdir -p ~/.dsh/.agent-presets
cp -RL presets/my-agent ~/.dsh/.agent-presets/

# 3. Plugin source (keep it under the repo-root plugins/ for git management)
#    The preset references it via the RELATIVE path './plugins/design-router/index.mjs':
#    presets/my-agent/plugins is a relative symlink to the repo-root plugins/,
#    which cp -RL expands to a real directory — no path edits needed on any machine.

# 4. External deps (soft deps — missing ones degrade gracefully)
npm install -g dembrandt        # URL → design tokens (phase-1 candidate verification)
# defuddle: npm install -g defuddle
# npm install -g @open-pencil/cli   # Optional: read/convert/verify .fig/.pen design files (falls back to Figma-family skills / manual review)

# ── Bring your own (personal picks; absence degrades to the fallback chain) ──
# 5. Machine-local assets (ledger + kami/zine/logo-generator reference libs)
#    Without them the package still runs — as a "hallmark discipline + web_search/dembrandt"
#    design agent — but the candidate pool loses your personal picks.

Note: the preset's plugin row uses a relative path (./plugins/design-router/index.mjs, with presets/my-agent/plugins as a relative symlink expanded by cp -RL), so a fresh machine just copies the preset directory — no path edits required. If you'd rather avoid symlinks, copy plugins/design-router/ into presets/my-agent/plugins/ and use plain cp -R (same result, just a second copy).

Repository structure

├── plugins/design-router/     # Deterministic-tool plugin (6 tools, zero runtime deps)
├── 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, incl. site/ theme assets)
├── README.md                  # English (primary)
└── README.zh.md               # 中文

Third-party content & license attribution

This repo bundles the following third-party content (upstream licenses/attribution preserved):

Content	Source	License	Location
hallmark skill + site/ theme tokens & examples	nutlope/hallmark	MIT (full text in skills/hallmark/LICENSE)	skills/hallmark/
External design resources referenced by the registry (kami/zine/logo-generator, etc.)	respective upstream repos	link-only references (not vendored; source URLs in registry.md)	—

Everything else (plugins/, presets/, skills/design-references/) is original to this repo and licensed under the MIT License (Copyright © 2026 haohaiHuang).

Related

• DeepSeek Harness — the harness this runs on (dsh, everything is a plugin)
• my-pi-skills — upstream skills repo (design-references / skill-router / vision)
• awesome-dsh-plugin — curated DSH plugin list