vndangkhoa/open-design
1
0
Fork 0
mirror of https://github.com/nexu-io/open-design.git synced 2026-06-01 03:14:35 +07:00
Code Issues Projects Releases Packages Wiki Activity Actions 1
open-design/docs/atoms.md
Cursor Agent e0840697ed
docs(plugins): add docs/atoms.md (first-party atom catalog reference) 
Plan G5 / spec §10 / §21 / §23.

A user / plugin author / reviewer asking 'what atoms can I reference?'
now has one canonical document with:

  - the full id list (implemented + planned, with task kinds),
  - how the daemon resolves an atom at run time
    (pipeline.ts → pipeline-runner.ts → system prompt fragment),
  - the v1 until-signal vocabulary (critique.score / iterations /
    user.confirmed / preview.ok) and how to encode a build-test
    pass/fail signal until Phase 7 promotes named signals,
  - the spec §22.5 'community plugin → first-party atom' promotion
    path so future PRs that flip a planned id to implemented have a
    documented landing route.

Source of truth remains apps/daemon/src/plugins/atoms.ts; this doc
points at it. `GET /api/atoms` already returns the same list and
the future `od atoms list` CLI verb (Phase 4 follow-up) will be a
thin wrapper around it.

Co-authored-by: Tom Huang <1043269994@qq.com>
2026-05-09 12:30:22 +00:00

5.2 KiB
Raw Blame History

First-party atom catalog

The atomic capabilities Open Design exposes to plugins. Spec: docs/plugins-spec.md §10. Source of truth: apps/daemon/src/plugins/atoms.ts. Live discovery: GET /api/atoms (also reachable via od atoms list --json in a future PR).

A plugin assembles atoms into ordered stages (od.pipeline.stages[].atoms[]). The Open Design daemon is responsible for resolving each atom into a system-prompt fragment, tool gating, and (when applicable) GenUI surface declarations. Plugins never own the atom implementations; they only reference them by id.

Reading this document

  • id — what you write inside od.pipeline.stages[*].atoms[] and od.context.atoms[]. Stable across daemon versions.
  • status — implemented (live in v1) or planned (id reserved; the daemon will accept it but emit a doctor warning until the matching atom is wired in).
  • task kinds — which of the four product scenarios (new-generation, code-migration, figma-migration, tune-collab) the atom is intended for. Plugins may reference an atom outside its declared task kinds, but doctor flags this as suspicious.

Implemented atoms (v1)

id label task kinds
discovery-question-form Discovery question form — turn-1 question form for ambiguous briefs. new-generation, tune-collab
direction-picker Direction picker — 3–5 direction picker before the final commit. new-generation, tune-collab
todo-write Todo write — TodoWrite-driven plan. all
file-read / file-write / file-edit File ops on the project cwd. all
research-search Research search — Tavily-backed shallow research. new-generation
media-image / media-video / media-audio Media generation through configured providers. new-generation, tune-collab
live-artifact Create / refresh live artifacts. new-generation, tune-collab
connector Composio connector tool calls. new-generation, tune-collab
critique-theater 5-dimension panel critique; emits the critique.score signal that drives devloop convergence. all

Planned atoms (reserved ids)

These ids are reserved so plugins authored against the v1 spec do not have to churn names when the daemon adds the matching capability. Until promotion, the daemon treats references as "doctor warning" rather than "unknown atom error".

id label task kinds
code-import Clone / read existing repo. code-migration
design-extract Extract design tokens from source code / Figma / screenshots. code-migration, figma-migration
figma-extract Extract Figma node tree + tokens + assets. figma-migration
token-map Map extracted tokens onto the active design system. code-migration, figma-migration
rewrite-plan Long-running multi-file rewrite plan. code-migration, tune-collab
patch-edit Small-step file patches. code-migration, tune-collab
diff-review Render rewrite as a reviewable diff. code-migration, tune-collab
handoff Push artifact to downstream surfaces (cli / cloud / desktop). tune-collab

How the daemon resolves an atom

  1. The plugin manifest's od.pipeline.stages[*].atoms[] is parsed into a PipelineStage[] by apps/daemon/src/plugins/pipeline.ts.
  2. At run time, apps/daemon/src/plugins/pipeline-runner.ts walks the stages. For each stage entry it:
    • emits a pipeline_stage_started SSE event,
    • asks the caller-supplied stage runner to execute the atom (today this is a stub; Phase 4's atom migration into plugins/_official/<atom>/SKILL.md makes this fully data-driven),
    • persists one row into run_devloop_iterations for audit,
    • emits a pipeline_stage_completed event with the resulting signals.
  3. The atom's prompt fragment / tool gating is currently inline in apps/daemon/src/prompts/system.ts. Phase 4 patch 2 (spec §23.3.2) lifts each fragment out into plugins/_official/atoms/<atom>/SKILL.md so the prompt becomes fully data-driven.

Atom signals + the until vocabulary

Spec §10.1 locks the v1 until vocabulary to:

  • critique.score — emitted by critique-theater.
  • iterations — built-in per-stage counter.
  • user.confirmed — emitted when a confirmation GenUI surface resolves.
  • preview.ok — emitted by the live-artifact preview pipeline.

Atoms outside that list contribute signals through critique.score (which is how today's build-test-shaped community plugins encode pass/fail). Phase 7 (spec §21.4) extends the vocabulary so atoms can declare named signals through od.atom.untilSignals[]; until then, the closed vocabulary is the contract.

Adding a new atom

  1. Author the atom out-of-tree as a plugin (per spec §22.5 promotion path).
  2. Once the SKILL.md / MCP tool / pipeline shape stabilises, append the matching row to FIRST_PARTY_ATOMS in apps/daemon/src/plugins/atoms.ts.
  3. Update this document and the spec §10 / §21 / §23 tables in the same PR.
  4. The atom is now reachable via:
    • od.pipeline.stages[*].atoms[] references in any plugin,
    • GET /api/atoms discovery,
    • od plugin doctor validation.