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

96 lines
5.2 KiB
Markdown
Raw Permalink Blame History

This file contains ambiguous Unicode characters

This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.

# First-party atom catalog
> The atomic capabilities Open Design exposes to plugins.
> Spec: [`docs/plugins-spec.md`](plugins-spec.md) §10.
> Source of truth: [`apps/daemon/src/plugins/atoms.ts`](../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.
Reference in a new issue View git blame Copy permalink