design-duo

name: design-duo description: "Two-agent design pipeline. design-researcher gathers competitive UI/UX patterns; design-principal synthesizes research into engineering-ready specs and self-contained HTML mockups. Both agents discover the host project's design system at runtime — no per-project editing required." source: original platforms: [hermes, codex, claude-code] install: "./install.sh (Hermes) | ./install-codex.sh (Codex) | ./install-claude.sh (Claude Code)"

Agent Design Duo

A two-agent design flow that grounds design direction in competitor research, then hands engineering-ready specs and a self-contained HTML mockup. Each agent discovers the host project's design system at runtime — no per-project editing required.

Source-of-truth lives here. To make changes, edit files in this directory and re-run the installer for your runtime. Runtime copies are generated; do not hand-edit them.

What it does

Pipeline:

Your question → design-researcher → research + gallery
             → design-principal  → design spec + mockup
             → engineering handoff

1. design-researcher — Gathers competitive UI/UX patterns, traces them to real product UI (Refero / Mobbin / web), saves a visual reference gallery.
2. design-principal — Reads the research, synthesizes design direction against the discovered design system, hands off an engineering-ready spec + interactive mockup.

Both agents discover DESIGN.md, the component library, and product context from your workspace automatically. They adapt to whatever host project you point them at.

▶ Watch the 71-second demo

When to use

• Before designing a new feature, flow, or page
• When you want competitor patterns grounded in real product UI, not generic training-data averages
• When design handoff must reference your components and tokens, not an invented design system
• When you want visual artifacts (research gallery + mockup) alongside written specs

Don't use for: copy-edits, one-off styling tweaks, or "what color should this be" questions. Those are craft questions, not pipeline questions.

Install

Hermes:

./install.sh

Codex:

./install-codex.sh

The Codex installer deploys the skill to ${CODEX_HOME:-~/.codex}/skills/design-duo/ and installs the design-researcher and design-principal custom-agent adapters in ${CODEX_HOME:-~/.codex}/agents/.

Claude Code:

./install-claude.sh

The Claude Code installer deploys the skill to ~/.claude/skills/design-duo/ and installs the design-researcher and design-principal subagents in ~/.claude/agents/. The canonical personas double as the agent definitions, so no adapters are needed.

Use

In Hermes:

/design-duo <your feature or pattern question>

In Codex, invoke the design-duo skill with your question. It dispatches the two installed custom agents sequentially.

In Claude Code, run /design-duo <your feature or pattern question> (same as Hermes). The orchestrator dispatches the two installed subagents sequentially. You can also invoke either subagent directly by asking for design-researcher or design-principal.

Examples:

• /design-duo account type selection patterns
• /design-duo how competitors handle portfolio overview on mobile
• /design-duo stepper vs accordion for multi-step forms

The orchestrator captures your topic (or asks for one), discovers your workspace, dispatches the researcher, and surfaces a one-liner before auto-continuing to the principal. Both artifacts go to .design-output/ in your repo.

Layout

design-duo/
├── SKILL.md                       # orchestrator
├── personas/
│   ├── design-researcher.md       # canonical (no de- prefix — design-duo is original)
│   └── design-principal.md
├── templates/
│   └── DESIGN-CONTEXT.md          # optional product context file
├── assets/
│   └── gallery-template.html      # visual reference gallery base
├── install.sh                     # deploys to Hermes runtime
├── install-codex.sh               # deploys the skill and Codex agent adapters
├── install-claude.sh              # deploys the skill and Claude Code subagents
├── platforms/codex/agents/        # Codex custom-agent TOML adapters
└── README.md                      # this file

Optional: provide upfront context

Drop a DESIGN-CONTEXT.md at your repo root (modeled on templates/DESIGN-CONTEXT.md here). The orchestrator reads it on every run; both agents use it. Industry, audience, competitors, differentiators — one file, low friction.

The agents also pick up:

• DESIGN.md (or docs/DESIGN.md, design/DESIGN.md, .cursor/DESIGN.md) for design tokens
• STRATEGY.md or README.md as fallbacks
• The component library in components/ui/ (or wherever your project keeps it)

If DESIGN-CONTEXT.md is missing, the orchestrator asks one clarifying question — industry and 2–3 competitors.

Outputs

Add .design-output/ to .gitignore for exploration that shouldn't ship.

Notes

• design-principal also works standalone (no research → confidence capped at Medium). Invoke /design-researcher or /design-principal directly when you only want one stage.
• External research can fail. If MCP and web search both fail, the orchestrator continues with design-system-only grounding and caps the principal's confidence at Medium.
• The mockup is a concept sketch, not production code. After the spec is approved, run de-plan or your planning tool to break it into engineering tickets.

Attribution

Original work by JulioGarcia. No external attributions.