Next surface decision¶
Status: living decision record — original recommendation accepted and executed (v4.57–v4.61); re-evaluated 2026-07-06 (composed slice, executed v4.62–v4.64) and 2026-07-07 (MCP ↔ SDK parity, accepted). See the dated sections below for each decision's status. Date: 2026-07-03 (original) / 2026-07-07 (latest re-evaluation)
This record answers option 3 of the "Recommended next decision" in PRODUCT-READINESS.md: if the goal is "best design tool" as a broader product, which surface do we deepen next — CLI, VS Code extension, web UI, Figma plugin, or agent SDK?
Context and decision drivers¶
Who uses design-ai today¶
design-ai is a model-agnostic design knowledge corpus plus a deterministic, zero-dependency Node.js CLI. Its primary consumer is an AI coding agent (Claude Code, Codex, Cursor, Aider) that picks up the repo and behaves like a senior product designer for a session. The human is present but works through the agent — routing briefs, packing prompts, checking artifacts, running the Website Improvement handoff flow. Secondary consumers are maintainers who run the CLI directly and adopters who install via npm/Homebrew.
What is already shipped¶
Per external-status.md (checked 2026-07-02):
- CLI —
@design-ai/cli@4.56.0on npm, GitHub Releasev4.56.0, Homebrew tap. This is the mature surface: route/prompt/pack/check/search/show/examples, plussite(Website Console),learn, andworkspace. - MCP server — public
design-ai-mcpentrypoint, 10 tools, connected to Claude Code and Codex. This is the agent-facing distribution channel and it already works. - VS Code extension —
sungjin.design-ai-vscode@0.4.1on the Marketplace: sidebar trees + quick-pick commands over the corpus. - Web console — the zero-dependency static web console under
website-console/for the website-improvement workflow (workflow graph, browser-local handoff evidence tracking). - Docs — GitHub Pages (MkDocs).
The important framing: none of the five candidates is greenfield. Each is a deepening of something that already ships in thin form.
Maintenance constraints¶
- Single maintainer. Build cost and ongoing maintenance cost dominate. A surface that needs continuous platform-review babysitting (store submissions, plugin re-approvals) is expensive out of proportion to its code.
- Zero-dependency stance. The CLI and web console ship with no runtime dependencies. Any surface that forces a framework/toolchain (React build, Figma plugin bundler) breaks that stance and adds supply-chain surface.
- Deterministic architecture. The product is deterministic corpus routing, prompt packing, and quality checking — not model inference. Surfaces that imply "smart UI" set an expectation the architecture deliberately does not meet.
- Korean-market focus. Load-bearing value in the dogfood runs came from Korean i18n knowledge (see
DOGFOOD-FINDINGS.md,DOGFOOD-V4-FINDINGS.md). Any surface should keep that differentiator front and center, not dilute it into a generic tool.
Synergy driver¶
A sibling doc, AI-LEARNING-PHASE2.md, is being authored in parallel to open an AI-learning retrieval phase (retrieval memory over the corpus and local learning signals). Whichever surface we deepen should compound with that phase rather than fork effort away from it.
Evaluation criteria¶
Each surface is scored 1–5 on:
- Leverage — reuse of existing assets (corpus, CLI lib, MCP tools, web console).
- Reach — user value and how many of today's users it serves.
- Build cost — 1 = expensive, 5 = cheap (higher is better).
- Maintenance — ongoing burden for one maintainer; 1 = heavy, 5 = light.
- Distribution — discovery and install friction; 5 = frictionless.
- Risk — platform dependency and review-process exposure; 5 = low risk.
- Learning synergy — compounding with the AI-learning retrieval phase.
Scoring table¶
| Criterion | CLI deepening | VS Code deepening | Web UI | Figma plugin | Agent SDK |
|---|---|---|---|---|---|
| Leverage | 5 | 4 | 4 | 2 | 5 |
| Reach | 4 | 3 | 3 | 2 | 4 |
| Build cost | 5 | 3 | 3 | 2 | 4 |
| Maintenance | 5 | 3 | 4 | 1 | 4 |
| Distribution | 5 | 4 | 3 | 3 | 4 |
| Risk | 5 | 3 | 4 | 1 | 4 |
| Learning synergy | 5 | 3 | 3 | 2 | 5 |
| Total | 34 | 23 | 24 | 13 | 30 |
Per-surface analysis¶
1. CLI deepening¶
Scores. Leverage 5: every command already routes through the shared cli/lib surface and the MCP server wraps the same functions, so a CLI capability is instantly an MCP capability. Reach 4: serves the primary agent user and the maintainer directly. Build cost 5 and maintenance 5: no toolchain, no store, npm run audit (8/8) plus the packed-tarball and registry smokes already gate every change. Distribution 5: publish is a solved, provenance-signed path. Risk 5: no platform dependency. Learning synergy 5: retrieval memory is naturally exposed as new learn/route/pack flags and reused verbatim by MCP.
90-day slice. Land the AI-learning retrieval flow as CLI verbs (learn --recall, pack --with-recall), close the concrete corpus gaps the dogfoods named — money-aware patterns, mobile navigation, list/feed, React Native, Korean payments (from DOGFOOD-FINDINGS.md) — and add the async-control and Korean-density knowledge from DOGFOOD-V4-FINDINGS.md. Each ships behind existing gates and flows to MCP for free.
Evidence. The v4 dogfood explicitly credits the single npm run audit runner and the CLI corpus for a 3–5x speedup on Form/Dialog/List work; the friction it surfaced was missing corpus and flags, not a missing surface.
2. VS Code extension deepening¶
Scores. Leverage 4: reuses the corpus and search logic but the vscode API layer is its own code. Reach 3: serves humans who browse the corpus, not the agent that is the primary consumer. Build cost 3 and maintenance 3: TypeScript toolchain, and DOGFOOD-V4-VSCODE-FINDINGS.md shows the untested vscode API surface (quick-pick rendering, config propagation, tree refresh) still needs @vscode/test-electron plus a CI matrix. Distribution 4: Marketplace publish already works at 0.4.1. Risk 3: Marketplace review and API churn. Learning synergy 3: a webview could show recall results but that is net-new UI.
90-day slice. Add a webview that renders the Website Console workflow graph inside the editor and surfaces check results inline; add the deferred headless integration tests. Real value, but it targets the human-browsing path while the agent path (MCP) is where the product is consumed.
Evidence. The VS Code dogfood is honest that pure logic is 100% extracted and tested, but "actual UI rendering inside VS Code" and "config change handling under real load" are explicitly not validated — deepening here means first paying down that test debt.
3. Web UI (expand the website console)¶
Scores. Leverage 4: the static console already exists and is zero-dependency. Reach 3: good for the website-improvement workflow specifically, narrower for the rest of the corpus. Build cost 3 and maintenance 4: staying zero-dependency keeps it cheap, but broadening beyond the console's single workflow is real design work. Distribution 3: a static site needs hosting and discovery it doesn't have yet. Risk 4: low platform risk if it stays static. Learning synergy 3: could visualize recall, but as new UI.
90-day slice. Generalize website-console/ from one workflow into a small corpus browser + prompt-pack builder that runs fully client-side against exported JSON. Attractive, but it risks re-implementing the CLI's routing/packing in a second language and diverging from it.
Evidence. The console is the one shipped web asset and it is deliberately scoped to website-improvement; there is no dogfood evidence of demand for a broader web surface, whereas corpus and flag gaps are documented repeatedly.
4. Figma plugin¶
Scores. Leverage 2: the FIGMA-INTEGRATION.md bridge is token export/import, not a live plugin, so most plugin code is new. Reach 2: serves designers who are not today's primary agent user. Build cost 2, maintenance 1, risk 1: a Figma plugin means a bundler (breaking the zero-dependency stance), the Figma plugin-review process, and API churn maintained by one person. Distribution 3 and synergy 2 do not offset that.
90-day slice. A plugin that pushes generated tokens into Figma Variables and pulls selection context back. High desirability, but the worst fit for the constraints: new toolchain, external review gate, and a maintenance tail that competes directly with the learning phase.
Evidence. Nothing in the dogfood record points to Figma-plugin friction; the shipped Figma story is file-based token sync, which the CLI already serves.
5. Agent SDK (programmatic library surface)¶
Scores. Leverage 5: an SDK is a thin, documented wrapper over the exact cli/lib functions the MCP server already calls — near-zero new logic. Reach 4: lets other tools and agents embed design-ai's routing/packing/checking without shelling out to the CLI, extending the primary agent-consumer story. Build cost 4 and maintenance 4: mostly surface stabilization and typing over existing code, gated by the same smokes; the ongoing cost is API stability, not a platform. Distribution 4: ships in the same npm package. Risk 4: the only real risk is committing to a public API contract. Learning synergy 5: the retrieval phase is consumed programmatically day one.
90-day slice. Extract and document a stable @design-ai/cli programmatic entry (route(), pack(), check(), recall()) mirroring the MCP tool set, with typed inputs/outputs and smoke coverage. This is the second-best fit and a natural follow-on to CLI deepening — but committing to a public API contract before the retrieval phase settles risks freezing an interface we will want to change.
Evidence. The MCP server already proves these functions are cleanly separable from I/O; an SDK formalizes what MCP consumes internally.
Recommendation¶
Deepen the CLI (option 1), and treat the Agent SDK (option 5) as the fast follow once the AI-learning retrieval phase stabilizes.
Rationale: the CLI is the one surface where every constraint points the same direction — highest leverage (it is also the MCP surface, so one change serves both the human and the agent consumer), lowest build and maintenance cost, no platform-review risk, and the cleanest synergy with AI-LEARNING-PHASE2.md, whose retrieval verbs land as CLI flags and flow to MCP for free. The dogfood record is consistent that the friction today is missing corpus and missing flags, not a missing GUI. Deepening the CLI directly retires that friction while keeping the zero-dependency, deterministic, Korean-focused posture intact.
What we defer, and when to revisit¶
- Agent SDK — deferred only until the retrieval API stabilizes (target: after the first
AI-LEARNING-PHASE2.mdmilestone lands in the CLI). Revisit trigger: the CLI recall interface has been stable across two releases, or an external adopter asks to embed design-ai programmatically. - VS Code deepening — deferred pending demand and test-debt paydown. Revisit trigger: adopter reports of the extension being the primary entry point, or the headless
@vscode/test-electronsuite is in place. - Web UI — deferred beyond the current website-console scope. Revisit trigger: repeated requests for a no-install, browser-only corpus experience, or a non-agent audience becomes a real segment.
- Figma plugin — deferred longest. Revisit trigger: file-based token sync is demonstrably insufficient and a designer audience (not the agent) becomes a primary user, justifying the toolchain and review-process cost.
Cross-check any surface work against the release gate: npm run audit (8/8, link resolution included) and npm run release:metadata before touching README/DISTRIBUTION-class docs.
Decision record¶
- Status: accepted and executed — both recommended surfaces shipped
- Date: 2026-07-03 (proposed) / 2026-07-05 (executed)
- Deciders: maintainer
- Supersedes: none
- Related:
PRODUCT-READINESS.md,external-status.md,AI-LEARNING-PHASE2.md
Outcome (2026-07-05)¶
The recommendation was executed in order and both surfaces are live:
- CLI deepening shipped as v4.57.0 (local retrieval memory:
index,search --ranked,--with-recall,learn --recall, opt-in embedding rerank) and v4.58.0 (route --explainrelated knowledge, recall quality, corpus depth). The dogfood friction this document identified — missing corpus and missing flags — is retired; retrieval spans every CLI/MCP surface. - Agent SDK followed exactly on the stated revisit trigger (recall interface stable across two releases): design doc
AGENT-SDK.md, then v4.59.0 (Phase A — read-only@design-ai/cli/sdk, 8 verbs) and v4.60.0 (TypeScript declarations + the opt-inlearn.*local-write namespace).
The deferred surfaces (VS Code deepening, Web UI, Figma plugin) remain deferred with the same revisit triggers. The next-surface question is open again; re-evaluate against the criteria above when the next planning window opens, factoring in that the SDK now also serves programmatic adopters.
Re-evaluation (2026-07-06)¶
Scored with the same seven criteria, in the post-execution landscape: CLI deepening and the Agent SDK are shipped (v4.57–v4.61), the AI-learning Phase A follow-ups and Phase B are all closed, and the ranked-default question is decided for 4.x (see AI-LEARNING-PHASE2.md). The SDK's existence opens a new leverage axis — programmatic consumers — that did not exist at the original scoring.
| Candidate | Leverage | Reach | Build cost | Maintenance | Distribution | Risk | Synergy | Total |
|---|---|---|---|---|---|---|---|---|
| Dogfood verification pass | 5 | 4 | 4 | 5 | 3 | 5 | 5 | 31 |
| SDK adoption enablement | 4 | 4 | 5 | 4 | 4 | 5 | 4 | 30 |
| Web UI expansion | 4 | 3 | 3 | 4 | 3 | 4 | 3 | 24 |
| VS Code deepening | 4 | 3 | 3 | 3 | 4 | 3 | 3 | 23 |
| Component spec extractor v2 | 3 | 3 | 3 | 4 | 3 | 4 | 2 | 22 |
| Skill-proposal apply path | 3 | 3 | 3 | 3 | 4 | 2 | 4 | 22 |
- Dogfood verification pass — use design-ai itself to produce a real design artifact end-to-end and capture the gaps. This is how the async-control and Korean-density corpus gaps were found; it generates the next backlog organically and exercises every shipped surface.
- SDK adoption enablement — a real, runnable SDK consumer example plus an agent-integration recipe and docs. Converts the just-shipped SDK investment into adoption; zero new product code, zero platform risk.
- VS Code / Web UI / Figma: unchanged constraints, unchanged revisit triggers, no new demand signal — still deferred.
- Spec extractor: coverage is already 90.5%, so its value has shrunk from coverage-push to maintenance automation.
- Skill-proposal apply path: still gated on a separate approval + archive/review design per the standing constraint.
Recommendation (2026-07-06)¶
Run the two leaders as one composed slice: a real SDK consumer example that drives a design task end-to-end (route → pack → check → learn.captureFromCheck), documented as the SDK walkthrough. The example is simultaneously the SDK adoption artifact (D) and a dogfood pass (G): building it exercises the shipped surfaces against a genuine task, and any friction or corpus gaps it surfaces become the evidence-backed next backlog — the same loop that produced the v4.58 corpus additions.
- Status: accepted — maintainer signed off 2026-07-06; the composed slice is the next work item
Re-evaluation (2026-07-07)¶
The 2026-07-06 composed slice executed and compounded: two dogfood rounds plus a systematic 18-class route-coverage sweep shipped as v4.62.0–v4.64.0. Route coverage has converged (18/18 probed classes at medium+; 22 routes; example-qa 22/22), so further sweeps are diminishing returns. Scored against the same seven criteria in the new landscape:
| Candidate | Leverage | Reach | Build cost | Maintenance | Distribution | Risk | Synergy | Total |
|---|---|---|---|---|---|---|---|---|
| MCP ↔ SDK surface parity | 5 | 5 | 5 | 4 | 5 | 4 | 5 | 33 |
| Dogfood round 3 (browse/IA class) | 4 | 3 | 4 | 5 | 3 | 5 | 4 | 28 |
| Corpus automation (spec extractor v2) | 3 | 3 | 3 | 4 | 3 | 4 | 2 | 22 |
| VS Code deepening | 4 | 3 | 3 | 3 | 4 | 3 | 3 | 23 |
| Web UI expansion | 4 | 3 | 3 | 4 | 3 | 4 | 3 | 24 |
| Skill-proposal apply path | 3 | 3 | 3 | 3 | 4 | 2 | 4 | 22 |
- MCP ↔ SDK surface parity — fact-checked gap: the MCP server exposes 10 tools with no
design_ai_recalland no learning-write tools, while the SDK shipsrecallplus thelearn.*namespace (remember/feedback/captureFromCheck). MCP is the primary agent surface, yet an MCP-connected agent today cannot recall combined corpus+learning context as a standalone verb, nor record what it learned — the exact loop the SDK walkthrough demonstrates. The fix is the proven playbook: thin wrappers over the samecli/libfunctions, with the write tools opt-in and clearly marked (the server instructions already say "prefer read-only tools unless the user explicitly asks to record local learning"). Highest leverage (serves every MCP consumer), lowest cost (adapter-only), direct synergy with everything shipped this month. - Dogfood round 3 stays the standing loop — cheap to rerun, but its route-coverage yield has converged; next run should target curation quality (browse/IA) rather than routing.
- VS Code / Web UI / Figma: unchanged triggers, still no demand signal — deferred.
Recommendation (2026-07-07)¶
Close the MCP ↔ SDK parity gap: add design_ai_recall (read-only) and an opt-in learning-write tool set (design_ai_learn_remember, design_ai_learn_feedback, design_ai_learn_capture) mirroring the SDK's learn.* boundary — writes only the local learning profile, clearly marked in tool descriptions, never enabled implicitly. Same verification pattern as every surface addition: MCP protocol tests, smoke assertions, docs (MCP server guide + SDK/MCP parity note).
- Status: accepted — maintainer signed off 2026-07-07; MCP ↔ SDK parity is the next work item
Done (2026-07-07): added all four tools to cli/lib/mcp-server.mjs (14 tools total, up from 10). design_ai_recall maps to learn --recall <query> --json [--limit N] [--category kind]; design_ai_learn_remember maps to learn --remember <text> --json [--category kind]; design_ai_learn_feedback maps to learn --feedback <text> --json [--outcome keep|improve|avoid] [--category kind] (the CLI does expose --outcome, verified in cli/lib/learn-args.mjs's normalizeFeedbackOutcome/LEARNING_FEEDBACK_OUTCOMES, so the MCP schema mirrors it rather than omitting it); design_ai_learn_capture maps to check --stdin --learn --yes --json [--route id] (verified the full flag combination runs cleanly, matching the SDK's learn.captureFromCheck path). All three write tools carry the shared "Writes ONLY the local learning profile ... and only when explicitly called" marker in their descriptions, and the serverInfo instructions string now names the write set explicitly. Added category/outcome enum validation to the MCP schema layer (assertMcpInputValue gained an enum branch) so invalid values are rejected before CLI invocation, mirroring LEARNING_CATEGORIES/LEARNING_FEEDBACK_OUTCOMES. Added mapping tests for all four tools (all param combinations), a 14-tool tools/list assertion, a write-boundary-marker description test, and a tools/call happy-path test for design_ai_recall with an injected runner, in cli/lib/mcp-server.test.mjs. tools/audit/smoke_assertions.py's MCP assertion checks tool presence (design_ai_route, design_ai_search), not an exact count or full name list, so no smoke-assertion change was required; verified by grepping package-smoke.py/registry-smoke.py for the same presence-only pattern. Documented the new tools and the write-boundary note in docs/integrations/design-ai-mcp-server.md (no .ko variant exists) and added a one-line SDK/MCP parity cross-reference to docs/SDK.md. Full verification: npm test (593/593 pass), npm run audit (8/8), npm run release:metadata (pass), npm run package:smoke, npm run registry:smoke:self-test, and npm run ci:local all green. Live stdio E2E: initialize → tools/list (14 tools confirmed) → design_ai_recall with a real Korean query ("접근성 버튼") → design_ai_learn_remember against a temp DESIGN_AI_LEARNING_FILE (verified the file gained the entry) → design_ai_learn_capture against the same temp profile (verified entry count went from 1 to 9, one remembered plus eight captured from the failing check).