docs(adr): ADR-0033 — AI-assisted metadata authoring

[xuyushun441-sys]

Summary

Proposes the authoring loop for an AI-authored platform — how an AI generates/modifies any metadata type and how a human safely confirms it before it goes live. Status: Proposed (for discussion).

Decisions:

1. One brain, many surfaces — AI authoring lives in the agent + global chat; designers contribute context + an in-context "Ask AI", never bespoke per-type generators.
2. AI never publishes — every agent write lands in the ADR-0027 draft; the change is confirmed in the designer's review/diff; the human's Publish is the only path to live. The draft is the gate (retires the unenforced requiresConfirmation).
3. Type-agnostic apply — one update_metadata(type,name,patch,mode:'draft') (+ create/describe) validated against the per-type Zod schema (ADR-0005), instead of N per-type write tools.
4. Plan-first for vague intent — for "build me a project-management system," the agent emits a structured blueprint the human confirms before batch-drafting. No mass-generating unreviewed artifacts.
5. Type-agnostic review in the shared host — generic draft↔published structural diff for all types; rich per-type diffs as enhancements; flow (graph) last.
6. Open-core boundary — agent framework + generic tools + BYO-model (incl. local/offline) ship OSS; managed AI + governance (approval gate, env promotion, audit, publish RBAC) are EE.

Builds on ADR-0010 (NL→flow) / ADR-0011 (actions-as-tools) / ADR-0027 (authoring lifecycle) / ADR-0032 (validate-by-default) / ADR-0005 / ADR-0019.

Why now

The pieces exist but aren't a safe loop: the metadata tools publish immediately (no draft, requiresConfirmation unenforced); write tools cover only objects/fields; and nothing handles low-specificity "design me a system" input. This ADR specifies the target end-state (pre-launch, no deprecation path).

Note

Doc-only. The objectui side already shipped the client foundations referenced here (per-designer designers, review/diff, designer→chat context + "Ask AI"). The framework-side changes (draft-routed tools, generic update_metadata, blueprint) are the Phase A/C work this ADR motivates.

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
spec	Ready	Preview, Comment	Jun 2, 2026 7:56am