open-design/docs/roadmap.md

# Roadmap

**Parent:** [`spec.md`](spec.md) · **Siblings:** [`architecture.md`](architecture.md) · [`skills-protocol.md`](skills-protocol.md) · [`agent-adapters.md`](agent-adapters.md) · [`modes.md`](modes.md)

Phased plan from "spec-only today" to "usable MVP" to "published v1." All estimates assume one focused developer; multiply by 0.6 for two and 0.4 for three.

---

## Phase 0 — Spec finalization (current, ~3–5 days)

**Goal:** get the interfaces right before writing implementation code. All decisions that are cheap to change on paper and expensive to change in code live here.

**Deliverables:**
- [x] `README.md` + `docs/spec.md` + architecture / protocol / adapter / modes / references docs (this repo, as of now)
- [ ] `docs/schemas/skill-manifest.json` — JSON Schema for the `od:` front-matter block
- [ ] `docs/schemas/design-system.md` — formal spec of the 9-section `DESIGN.md`
- [ ] `docs/schemas/protocol.md` — HTTP/SSE API schemas
- [ ] `docs/schemas/adapter.md` — adapter interface in TypeScript, printed out
- [ ] `docs/examples/DESIGN.sample.md` — a working example design system
- [ ] `docs/examples/saas-landing-skill/` — a working example skill (the one sketched in `skills-protocol.md` §8)
- [ ] Resolve the four "open questions" at the end of each spec doc

**Exit criteria:** every interface we'll implement has a signed-off schema in this repo. No code yet.

---

## Phase 1 — MVP (~6–8 weeks)

**Goal:** a single developer can clone, install, start the daemon, point at Claude Code, and produce a prototype and a deck from scratch. The tool is usable for real work even if not polished.

### Scope

**Included:**
- Web app (Next.js 16, App Router)
  - chat pane · artifact tree · sandboxed iframe preview · export menu
  - skill picker · mode picker · design-system picker
  - **no** comment mode yet · **no** sliders yet · **no** template gallery UI yet
- Local daemon (Node)
  - HTTP/SSE API on `:7456`
  - agent detection + cached results
  - skill registry (scan three dirs, hot-reload)
  - artifact store (plain files + `history.jsonl`)
  - design-system resolver
  - export pipeline (HTML + ZIP only; PDF/PPTX in Phase 2)
- Agent adapters
  - **`claude-code`** — native skill loading, streaming, surgical edit
  - **`api-fallback`** — direct Anthropic Messages API, minimal tool loop (Read/Write/Edit only)
- Skills shipped in repo
  - `saas-landing` (Prototype)
  - `magazine-web-ppt` (Deck, fork of guizang-ppt-skill)
- Modes available
  - **Prototype** (fully working)
  - **Deck** (fully working)
  - **Design System** (basic: from text brief only; no screenshot input yet)
  - **Template** (deferred to Phase 2)
- Topologies
  - **A — fully local** (primary)
  - **C — Vercel + direct API** (partial; no daemon features)

**Explicitly out of MVP:**
- Codex / Cursor / Gemini adapters
- Comment mode + sliders
- Template gallery + template skill
- Design System from screenshot (vision) / PDF / URL
- PDF / PPTX export
- Topology B (Vercel + tunneled local daemon)
- Docker compose file
- Skill tests (`od skill test`)
- Auth / multi-user

### Week-by-week breakdown

| Week | Theme | Concrete deliverables |
|---|---|---|
| 1 | Scaffolding | pnpm workspaces (`apps/web`, `apps/daemon`, `e2e`); Next.js 16 base; daemon CLI skeleton; CI green |
| 2 | Daemon core | HTTP/SSE API; project/conversation store; skill registry scanning; artifact store; design-system resolver loading `DESIGN.md` |
| 3 | Claude Code adapter | detection (PATH + `~/.claude/` probe); spawn with `--output-format stream-json`; parser from JSON-lines → `AgentEvent`; streaming to daemon's session; cancel via SIGTERM |
| 4 | API-fallback adapter | Anthropic Messages streaming; minimal tool loop (Read/Write/Edit rooted to artifact cwd); integration with skill prompt injection |
| 5 | Web UI — chat + file workspace | React state + daemon-backed project store; SSE client; chat pane; file workspace reflects project files; skill picker |
| 6 | Web UI — preview + export | sandboxed iframe with hot reload; JSX → vendored React/Babel runtime; export ZIP; export self-contained HTML (inline CSS) |
| 7 | Default skills | port `guizang-ppt-skill` (no modifications; add `od:` extension block); write `saas-landing` skill; write 1–2 DESIGN.md examples; docs for skill authors |
| 8 | Polish + dogfood | end-to-end dogfooding; performance pass (daemon <500ms cold start, first generation overhead <50ms); bug-fixing; first publishable alpha |

### MVP exit criteria

1. `corepack enable && pnpm install && pnpm tools-dev run web` works on clean macOS and Linux with Node 24.
2. With Claude Code installed: prototype + deck generation works end-to-end.
3. Without Claude Code installed: API-fallback produces prototypes (not decks — guizang-ppt-skill needs native skill loading).
4. A user can drop a DESIGN.md into the project root and subsequent generations respect it.
5. A third party can publish a skill repo; `od skill add <url>` installs it and it works.
6. Artifacts are plain files; `git add ./.od/artifacts/` and `git log` tell a sensible story.
7. No Electron, no Tauri, no desktop packaging anywhere in the repo.

---

## Phase 2 — v1 (~8 weeks after MVP)

**Goal:** feature parity with the "UI-polish-heavy" parts of Open CoDesign + multi-agent support + the full four modes.

### Scope

**Agent adapters:**
- `codex` (P1)
- `cursor-agent` (P1)
- capability-driven UI gating (disable features per adapter)
- agent fallback chain

**UI:**
- **Comment mode** (click element → surgical edit; only when `capabilities.surgicalEdit`)
- **Slider parameters** (live-tweak `od.parameters`)
- **Multi-frame preview** (desktop / tablet / phone)
- **Template gallery** UI with thumbnails
- **Design System editor** (split view: markdown ↔ sample-components preview)

**Skills:**
- Template skills: `stripe-ish-landing`, `linear-ish-docs`, `notion-ish-workspace`, `vercel-ish-pricing`
- More Prototype skills: `dashboard`, `login-flow`, `empty-state-pack`, `pricing-page`
- More Deck skills: `pitch-deck`, `product-demo-deck`
- Design System skills: `design-system-from-screenshot`, `design-system-refine`

**Modes:**
- **Template mode** fully shipped
- **Design System mode** extended: screenshot input, URL input

**Export:**
- PDF (Puppeteer)
- PPTX (pptxgenjs, driven by `slides.json`)

**Deployment:**
- Docker compose file
- Topology B: Vercel web + tunneled local daemon
  - Ship a helper subcommand: `od daemon --expose` using `cloudflared` (opt-in, documented)

**Dev experience:**
- `od skill test` with cheap-model runs
- Skill author starter template: `od skill scaffold`

### v1 exit criteria

1. All four modes fully functional.
2. Three adapters working (Claude Code, Codex, Cursor Agent); fallback chain shipping.
3. PDF + PPTX export working for at least the `magazine-web-ppt` + `pitch-deck` skills.
4. Deployed example at `demo.open-design.dev` (Topology C).
5. Skill author docs published; at least one third-party skill submitted.
6. Documentation site rebuilt from these spec docs.

---

## Phase 3 — v2 (~12 weeks after v1)

**Goal:** ecosystem + robustness.

**Scope sketch (non-binding):**
- Skill marketplace UI — searchable, categorized, install with one click
- Skill signing / checksums
- Gemini CLI + OpenCode + OpenClaw adapters (P2 tier)
- Windows support
- Collaborative mode (multi-user session on a single daemon)
- "Freeze prototype as design system" action
- Figma export (behind the Open CoDesign post-1.0 line; borrow their approach when they ship it)
- Telemetry (opt-in, self-hosted, never phoning home to a central service)
- Hosted SaaS offering (optional; full-local stays primary)

v2 isn't promised. It's the direction if v1 lands.

---

## Risk register

| Risk | Impact | Mitigation |
|---|---|---|
| Claude Code JSON stream format changes between versions | adapter breaks | pin version range; write a compatibility test; keep a parser for each major release |
| Third-party agent CLIs don't expose enough to stream tool calls | UX degrades silently | capability flags + feature gates; document per-adapter limitations in-product |
| `@mariozechner/pi-ai` or similar abstractions get popular and contributors ask us to support them | scope creep | defer; if demand is real, add as yet-another-adapter next to `api-fallback` |
| Vercel deploy (Topology B) flaky because of tunnel setup | users can't try the cloud path | ship Topology C (direct API) as the always-works path; document Topology B as advanced |
| `guizang-ppt-skill` or similar upstream skill changes format | default deck skill breaks | pin git SHA in our default install; monitor upstream |
| DESIGN.md format evolves in awesome-claude-design | incompatibility | track upstream; adopt changes; our resolver is tolerant of missing sections |
| Anthropic ships an open-source Claude Design | differentiation collapses | our moat is the "uses user's existing agent" angle; Anthropic is unlikely to ship that |
| Skill security (malicious skill via `od skill add`) | user machine compromise | install-time warning; rely on agent's own permission model; document best practices |

---

## Decision log (lightweight)

Record one line per material decision as we go. Example entries:

- 2026-04-24 — Use plain files + `history.jsonl` over SQLite for artifacts. *Why:* git-reviewable, no driver dependency, matches "skills are files" ethos.
- 2026-04-24 — Adopt `DESIGN.md` (awesome-claude-design) verbatim rather than inventing a new format. *Why:* 68 existing files are immediately compatible.
- 2026-04-24 — Do not ship an Electron / Tauri wrapper. *Why:* every minute on code-signing is a minute not on skills; `cc-switch` already solves the tray-icon use case.
- 2026-04-24 — Delegate the entire agent loop to the user's CLI. *Why:* reimplementing is worse than integrating; ecosystem compatibility beats control.

Decisions supersede each other; keep the log append-only and date every entry.

---

## What to do right after reading this

If you're the implementer:

1. Read [`spec.md`](spec.md) top to bottom.
2. Skim [`architecture.md`](architecture.md), [`skills-protocol.md`](skills-protocol.md), [`agent-adapters.md`](agent-adapters.md).
3. Argue with anything in the four "open questions" sections; file one-line decisions.
4. Fill in the missing Phase 0 deliverables (the `docs/schemas/` and `docs/examples/` files).
5. Scaffold the monorepo and start Week 1.

If you're evaluating the concept:

1. Read [`README.md`](../README.md) + [`spec.md`](spec.md) §1–3.
2. Check the comparison matrix in [`references.md`](references.md).
3. Look at the worked example in [`skills-protocol.md`](skills-protocol.md) §7 — that's the end-to-end feel.