# References

**Parent:** [`spec.md`](spec.md)

Every external project this spec leans on. Three questions per entry: what is it, what do we borrow, and what do we deliberately not take.

---

## Primary references

### [Claude Design](https://claude.ai/design) (Anthropic)

- **Role:** Historical UX reference for natural-language editing of visual artifacts, inline editing, and adjustment controls.

### [Open CoDesign][ocod] (OpenCoworkAI)
- **Repo:** [github.com/OpenCoworkAI/open-codesign][ocod]
- **Site:** [opencoworkai.github.io/open-codesign](https://opencoworkai.github.io/open-codesign/)
- **What it is:** An open-source design workspace. MIT-licensed. Electron desktop app. React 19 + Vite + Tailwind v4. [`@mariozechner/pi-ai`][piai] for multi-provider. SQLite for version history. 12 built-in design skill modules. HTML/JSX sandboxed iframe preview. Exports HTML/PDF/PPTX/ZIP/MD. 15 templates. Comment mode + slider controls + multi-frame preview.

[ocod]: https://github.com/OpenCoworkAI/open-codesign
[piai]: https://github.com/badlogic/pi-mono/tree/main/packages/ai
- **Why it matters:** Reference for interactive artifact review and export workflows.
- **What we borrow:**
  - UI concepts: **comment mode** (click-to-pin element edits), **tweak sliders** (agent-emitted parameters), **multi-frame preview** (desktop/tablet/phone).
  - Sandboxed iframe preview (`<iframe sandbox="allow-scripts">` with vendored React 18 + Babel standalone for JSX).
  - Export pipeline shape (HTML/PDF/PPTX/ZIP/MD).
- **What we don't:**
  - **Electron as the product runtime** — our product UI remains the shared Next.js web app; `apps/desktop` and `apps/packaged` provide a thin Electron host around the same daemon/web sidecars.
  - **Bundled agent on `pi-ai`** — we delegate to the user's existing CLI.
  - **Proprietary skill format** (TypeScript modules compiled into the app) — we use Claude Code's `SKILL.md` so third-party skills drop in.
  - **SQLite blobs for artifact bytes** — generated files remain on disk while daemon SQLite owns project and metadata state.
  - **Sole focus on UI panels** — we add a first-class Design System product surface and `DESIGN.md` contract.

### [multica][multica] (multica-ai)
- **Repo:** [github.com/multica-ai/multica][multica]
- **Docs:** [multica.ai/docs/skills](https://multica.ai/docs/skills)

[multica]: https://github.com/multica-ai/multica
- **What it is:** Open-source "managed agents platform." Frontend: Next.js 16. Backend: Go + Chi + WebSocket. DB: PostgreSQL + pgvector. **Local daemon auto-detects CLIs on PATH: Claude Code, Codex, OpenClaw, OpenCode, Hermes, Gemini, Pi, Cursor Agent.** Assigns work via a web board view; agents execute; WebSocket streams progress.
- **Why it matters:** They already solved the "detect and wrap local code agents" problem.
- **What we borrow:**
  - **PATH-scan + config-dir probe detection** strategy.
  - **Local daemon + WebSocket** topology (daemon on user's machine, thin web client).
  - Agent catalog (our P0–P2 list maps closely to theirs).
  - Workspace/local skill import and agent-scoped skill attachment model.
- **What we don't:**
  - Go backend + PostgreSQL — overkill for our scope; Node daemon + filesystem is enough.
  - Team / board / issue-assignment model — not our domain.
  - pgvector — we don't embed anything in MVP.

### [OpenHuman][openhuman] (tinyhumansai)
- **Repo:** [github.com/tinyhumansai/openhuman][openhuman]

[openhuman]: https://github.com/tinyhumansai/openhuman
- **What it is:** Open-source personal AI assistant with many integrations, auto-fetch into a memory tree, local editable knowledge, and a TokenJuice-style compression layer before LLM use.
- **Why it matters:** It is the clearest reference for "connect sources once, then the agent wakes up with compressed context already available."
- **What we borrow:**
  - Connector-driven ingestion as a first-class loop, not a prompt the user rewrites each time.
  - Editable local memory tree rather than opaque vector-only recall.
  - Token compression as an optional stage before agent context injection.
- **What we don't:**
  - General personal-assistant scope, messaging/voice/meeting participation, and bundled subscription/model routing.

### [Hermes Agent][hermes] (Nous Research)
- **Repo:** [github.com/nousresearch/hermes-agent][hermes]
- **Docs:** [hermes-agent.nousresearch.com/docs/skills](https://hermes-agent.nousresearch.com/docs/skills)

[hermes]: https://github.com/nousresearch/hermes-agent
- **What it is:** Self-improving agent with persistent memory, skills created from experience, skill improvement during use, scheduled automations, and a large skill hub.
- **Why it matters:** It turns "agent learns from work" into a product loop instead of a side effect.
- **What we borrow:**
  - Closed learning loop: experience -> memory or skill proposal -> future run.
  - Scheduled automations that can deliver across surfaces.
  - Explicit compression and usage inspection controls.
- **What we don't:**
  - Owning the user's entire agent runtime, messaging gateway, or model/provider layer.

### [GenericAgent][genericagent] (lsdefine)
- **Repo:** [github.com/lsdefine/GenericAgent][genericagent]

[genericagent]: https://github.com/lsdefine/GenericAgent
- **What it is:** Minimal self-evolving autonomous agent framework that crystallizes solved tasks into a personal skill tree for direct reuse.
- **Why it matters:** It names the core loop OD needs for design work: solve once, verify, save the execution path, and recall it with less context next time.
- **What we borrow:**
  - Skill crystallization from successful tasks.
  - Layered memory and direct recall to reduce prompt size.
  - A bias toward small composable primitives instead of a heavy agent framework.
- **What we don't:**
  - Broad uncontrolled desktop authority. OD keeps daemon, connector, filesystem, and review gates explicit.

### [cc-switch][ccsw] (farion1231)
- **Repo:** [github.com/farion1231/cc-switch][ccsw]

[ccsw]: https://github.com/farion1231/cc-switch
- **What it is:** Tauri desktop app for managing five CLI tools (Claude Code, Codex, Gemini CLI, OpenCode, OpenClaw). Provider management, MCP server config, skills install, session browsing. SQLite at `~/.cc-switch/cc-switch.db`. **Skills dir at `~/.cc-switch/skills/` with symlinks into each agent's config dir.** 50+ provider presets.
- **Why it matters:** Shows exactly how to live beside multiple code-agent CLIs without stepping on their config.
- **What we borrow:**
  - The idea of one discoverable library serving several agent runtimes. Open
    Design implements that boundary through its own registries and makes a
    real CWD-local copy of active skill resources for each run; it does not
    symlink bundles into every agent's global skills directory.
  - Knowledge of per-agent config dir locations (`~/.claude/`, `~/.codex/`, …).
  - "Provider presets" idea — a curated list we can ship so users don't have to hand-enter endpoint URLs for OpenAI-compatible relays.
- **What we don't:**
  - Tauri / desktop app — not our shape.
  - Provider-switching as core feature — we defer that to the underlying agent. If a user wants to switch providers inside Claude Code, they use Claude Code's config, not ours.
  - Tray icon / system integration — out of scope.

### [awesome-claude-design][acd] (VoltAgent)
- **Repo:** [github.com/VoltAgent/awesome-claude-design][acd]

[acd]: https://github.com/VoltAgent/awesome-claude-design
- **Historical ecosystem:** the project exposed 68 `DESIGN.md` files and a
  nine-heading baseline when this reference was first recorded.
- **Related URLs:** claude.ai/design, getdesign.md, Discord community
- **Why it matters:** Defines the de-facto portable design-system format for AI agents.
- **What we borrow:**
  - Portable `DESIGN.md` prose remains a compatibility floor: a legacy folder
    containing only that file can still be discovered and used.
  - The original nine headings remain a useful historical sample, not a fixed
    authoring schema. Current repository packages use `manifest.json`,
    `DESIGN.md`, `tokens.css`, and optional rich component/source/preview
    resources; migrated packages need substantive coverage without prescribed
    heading names or order.
- **What we don't:**
  - Treating one upstream list as the current catalogue boundary. The bundled
    catalogue now contains 151 packages drawn from multiple attributed sources
    and OpenDesign-authored systems.
  - Their Discord / community layer — not our product.

### [guizang-ppt-skill][guizang] (op7418)
- **Repo:** [github.com/op7418/guizang-ppt-skill][guizang]

[guizang]: https://github.com/op7418/guizang-ppt-skill
- **What it is:** A Claude Code skill producing magazine-style, horizontal-swipe web decks. Structure: `SKILL.md` + `assets/template.html` + `references/{components,layouts,themes,checklist}.md`. 6-step workflow. Single-file HTML output with embedded CSS/WebGL. Keyboard/scroll/touch navigation.
- **Why it matters:** Reference implementation of a high-quality Claude skill and the source of our bundled guizang deck template.
- **What we borrow:**
  - The workflow and assets are bundled under [`design-templates/guizang-ppt/`](../design-templates/guizang-ppt/) with the upstream license preserved and OpenDesign metadata/file-handoff integration applied.
  - Skill directory convention (`assets/` + `references/` + `SKILL.md`) as the pattern we document for skill authors.
  - The "6-step workflow + quality-checklist rubric" pattern for authoring new skills.
- **What we don't:** We do not require the retired `od skill add` flow; the rendering template ships in the catalogue and can still be consumed as a portable `SKILL.md` bundle.

---

## Secondary references (format / protocol / UI ideas)

| Project | Relevance |
|---|---|
| [Claude Code skills docs](https://docs.anthropic.com/) | Source of the `SKILL.md` format we adopt |
| [Cursor rules](https://docs.cursor.com/) | Historical format inspiration only; the current Cursor Agent adapter receives OpenDesign's composed prompt over stdin and uses the same CWD-local resource staging as other runtimes |
| [Reveal.js](https://revealjs.com/) / [Marp](https://marp.app/) | Reference for deck HTML navigation patterns |
| [Shadcn/ui](https://ui.shadcn.com/) | Component and registry reference; the product shell now uses repository-owned primitives from `@open-design/components` |
| [Vercel AI SDK](https://sdk.vercel.ai/) | Historical API-fallback exploration; current BYOK providers run through the OpenCode adapter rather than a direct SDK adapter |
| [Puppeteer](https://pptr.dev/) | Reference for template/skill-owned browser rendering; core desktop PDF export uses Electron `printToPDF` or the screenshot/PDF pipeline |
| [pptxgenjs](https://gitbrent.github.io/PptxGenJS/) | PPTX export engine |
| [chokidar](https://github.com/paulmillr/chokidar) | Ref-counted project-file watching; skill/template registries rescan on listing requests instead |

---

## What we explicitly don't borrow (and why)

- **Electron as a separate product architecture.** OpenDesign now ships thin
  desktop and packaged Electron hosts, including signing/update work, but the
  product UI remains the same Next.js web app and daemon rather than a second
  desktop-only implementation.
- **SQLite for artifacts** (from [Open CoDesign][ocod] and [cc-switch][ccsw]). Plain files + JSONL history are reviewable in git, trivially portable, and match the "skills are files" ethos.
- **Bundled model router** ([`pi-ai`][piai] from [Open CoDesign][ocod]). The user's code agent already routes. Two routers is worse than one.
- **PostgreSQL + pgvector** (from [multica][multica]). We don't embed anything in MVP. When we do, SQLite + `sqlite-vec` is enough for single-user scale.
- **Board / issue model** (from [multica][multica]). Off-brand for a design tool.

These boundaries keep external integrations from replacing the shared web,
daemon, filesystem, and agent-runtime contracts.

---

## Living references

This file is maintained. When we add an adapter or borrow a pattern from a new upstream, add it here with the same three-question format. When upstream licensing or direction changes materially, flag it here and cross-link from [`spec.md`](spec.md).