adia-ui-kit-factory

Consumer plugin for building apps ON the adia-ui (@adia-ai) framework — orient, scaffold, compose, wire, verify, migrate, across SPA/SSR/hybrid hosts. Maintainer counterpart: adia-ui-kit-forge.

Re-engineered 2026-07 for the Fable 5 harness (design: .claude/docs/specs/plugin-estate-v2.md).

Install

Via Git (Claude Code plugin marketplace — requires access to this repo, which is private):

/plugin marketplace add adiahealth/gen-ui-kit
/plugin install adia-ui-kit-factory@adia-ui-kit

(adia-ui-kit-factory@adia-ui-kit, not @gen-ui-kit — the marketplace registers under its own manifest name, adia-ui-kit (.claude-plugin/marketplace.json), not the repo name.)

Sources the in-repo manifest at .claude-plugin/marketplace.json (repo root — claude plugin marketplace add always expects the manifest there, with or without --sparse; it does not resolve a subdirectory manifest). The LIVE public install path (ADR-0045's npm-sourced manifest, @adia-ai/adia-plugins, live since v0.1.0 — gh#1160; see packages/plugins/adia-plugins/README.md for its own current version, which cuts on its own Class-B schedule independent of the framework lockstep):

/plugin marketplace add https://unpkg.com/@adia-ai/adia-plugins/marketplace.json
/plugin install adia-ui-kit-factory@adia-plugins

The manifest's entries are unpinned npm sources, so installs track each plugin's published latest — no manifest republish per plugin cut.

Via npm (package content only):

npm install @adia-ai/adia-ui-factory

Published in lockstep with the framework packages — pulls this plugin's skills/agents/commands/references/hooks into node_modules/@adia-ai/adia-ui-factory for vendoring or inspection. This does not by itself register the plugin with Claude Code's /plugin system — no marketplace manifest currently sources it from npm. The bare-repo posture (ADR-0040) is about this plugin working standalone in any consumer repo once installed some other way (no monorepo path assumptions in its own scripts) — it does not add an npm-sourced marketplace entry.

Skills (19 — skills/ on disk is the roster; check:plugin-count-claims guards this header count)

Skill	Species	Job
app-planning	procedural	classify a GREENFIELD app (mode/shape/shell/state) → Orientation Record
domain-planning	procedural	reasoning ladder (intent/domain/roles/tasks/decisions → scored wireframe) → Domain Plan block; preloaded by app-planning-agent
app-audit	procedural	diagnose an EXISTING/brownfield consumer repo — recon, gap classes, root-cause triage → ranked report
project-scaffolding	procedural	project shapes + scaffolding decisions
pattern-catalog	knowledge	index of pre-assembled patterns/template screens — check BEFORE composing from primitives
screen-composition	procedural	compose screens from the catalog; consumes the Domain Plan for PRD/spec input (§SpecToUi walked planning-side, gh#1207)
shell-selection	procedural	shell-family selection + per-shell contracts
wave-coordination	procedural	team-wave mechanics — parallel-branch integration, PR/conflict rules, shared-file ownership, wave sizing; preloaded by ui-architect
ui-architect	procedural	portable (runtime-neutral) whole-deliverable coordination workflow — gear selection, wave decomposition, generator-≠-reviewer separation, the four-lap cap, failure routing, the closing VerifyProof; the Claude-only dispatch mechanics live in agents/ui-architect.md + wave-coordination instead
data-wiring	knowledge	data/state patterns (signals, controllers, DataClient, hybrid)
chart-selection	knowledge	which component renders a chart/graph/sparkline/gauge/heatmap, and data/legend/theming wiring
table-composition	knowledge	table-ui usage — chrome, striping, sort/resize, inline-edit-grid, tree rows
host-wiring	procedural	wire the host — SPA / SSR / hybrid; icons + module barrels + CDN
gen-ui-wiring	procedural	generative-UI experiences on the a2ui runtime + MCP; agentic-UX patterns
llm-wiring	knowledge	consuming @adia-ai/llm (client, streaming, proxy security)
token-selection	knowledge	which color token/role — the --a-* / --md-sys-color-* layer choice
app-migration	procedural	version upgrades + port-to-adia sweeps (breaking changes)
find-unused	procedural	what a non-breaking upgrade left unused — inert opt-in layers, stale workarounds
surface-qa	procedural	browser + a11y + composition exit gate

Agents (4)

ui-architect (whole-deliverable coordinator — GEAR 1 novice one-shot through GEAR 2 PRD-driven decompose/plan/iterate; dispatches the other three, never duplicates their charters, holds no Write/Edit) · app-planning-agent (read-only planner → Orientation Record) · screen-composition-agent (builder; holds the validate-before-serialize trust gate on generated A2UI) · surface-qa-agent (read-only QA/composition-quality seat; VerifyProof + the COMPOSE/REALIZE rubric).

Plugin-root references (composed against by multiple skills)

agentic-ux-patterns.md (the six agent-surface UX patterns → gen-ui-wiring) · composed-surface-rubric.md (the two-axis COMPOSE/REALIZE quality rubric → surface-qa-agent) · component-model.md · the references/contracts/ twins.

Hooks

adia-lint — PostToolUse advisory consumer-smell repair loop (selftest ships).

Commands

/project-scaffolding · /app-planning · /surface-qa · /app-migration · /find-unused · /gen-ui-wiring · /app-audit

MCP

adia-gen-ui server pinned: @adia-ai/mcp@0.8.55 (tool SoT: packages/gen-ui/mcp/TOOLS.md — the gen-ui section; stability rule in references/contracts/; pin lives in .mcp.json — check:plugin-count-claims guards this README copy against it). The server is adia-mcp gen-ui, published as @adia-ai/mcp (gh#1240 folded the ADR-0048 P2 rename target @adia-ai/gen-ui-mcp and P4's @adia-ai/a2ui-protocol-mcp into one package before either ever published; the pin name and the mcpServers key flipped in the P7 release commit per the 2026-08-14 config-key ruling — new entries for the other subcommands use adia-protocol / adia-factory).

Non-Claude harnesses

External install beyond Claude Code (AGENTS.md's own "Non-Claude harnesses" section carries the shared degradation table this summarizes). The MCP story is the one place neither non-Claude harness matches Claude Code's plug-and-play install — read this section before promising Pi/Hermes support for this plugin specifically, since its whole value proposition is wiring the adia-gen-ui MCP server.

• Codex (gh#1888): .codex-plugin/plugin.json + per-skill agents/openai.yaml, derived; mcpServers points at the same .mcp.json Claude Code uses. No manifest key for hooks/commands/agents — a command degrades to invoking its skill directly, and ui-architect's whole-deliverable coordination — gear selection, wave decomposition, generator-≠-reviewer separation, the four-lap cap, failure routing, the closing VerifyProof — ships as its own portable ui-architect skill instead of a Claude subagent (ADR-0091): invoke it by name ("use the ui-architect skill…"); it runs planning/composition/QA as isolated dispatches where the installed Codex runtime supports that, or serially in one context otherwise. Install via npm (see the adia-plugins package README) or straight from Git, for anyone with repo access:

  codex plugin marketplace add adiahealth/gen-ui-kit --ref main
  codex plugin add adia-ui-kit-factory@adia-ui-kit
  codex plugin add adia-ui-kit-forge@adia-ui-kit
  

  Sourced from the repo-root .agents/plugins/marketplace.json — the Codex-side sibling of this repo's own in-repo Claude channel (.claude-plugin/marketplace.json), hand-authored the same way, never generated (ADR-0091 D2/D3). Both plugins register under the manifest's own name, adia-ui-kit — not the repo name, and a distinct marketplace name from the npm-sourced channel above it (adia-plugins), mirroring the existing Claude-side split exactly, kept deliberately parallel rather than merged.
• Hermes (gh#1954): plugin.yaml + __init__.py at this package's root — point Hermes's plugin loading at the installed node_modules/@adia-ai/adia-ui-factory directory. MCP is user-level config in Hermes, not a plugin field — merge the generated hermes-mcp.yaml into your own ~/.hermes/config.yaml by hand; there is no automatic wiring. __init__.py registers the portable ui-architect skill (ADR-0091) alongside every other skill, and a generated /ui-architect command — verified against the installed Hermes Agent's real PluginContext.register_command + dispatch_tool and tools/delegate_tool.py's delegate_task(goal, context, role, …) (not assumed from documentation): each of planning, composition, and QA runs as its own isolated delegate_task child (role="leaf"), gated by the same OrientationRecord/BuildResult/VerifyProof linters every other runtime calls, capped at four plan→build→QA laps per wave (LLD §C6, SPEC REQ-012/013). Generated by scripts/build/harness-manifests.mjs — never hand-edit __init__.py. Verified live via hermes plugins doctor --ci (clean registration against the real PluginContext) plus a Python-level selftest (check:harness-manifests-selftest) driving the actual generated orchestration logic against a scripted delegate_task double and the real linters; a live interactive /ui-architect dispatch was not completed (sandboxed dev environment blocks mutating Hermes's global plugin-enable state) — the mechanism itself is real and independently verified, not simulated. No hooks/agents surface otherwise.
• Pi (gh#1954): discovered via the pi-package keyword and the "pi" field in package.json; prompts/*.md gives every /command a genuine Pi prompt template. Pi core has no native MCP support at all — the adia-gen-ui server only reaches Pi through the third-party pi-mcp-adapter package, which reads this plugin's .mcp.json unmodified (same shape, no substitution needed). Install that adapter first; without it, this plugin's headline feature — the a2ui MCP wiring — silently does nothing on a stock Pi install. The portable ui-architect skill (ADR-0091) is discoverable via the "pi": {"skills": [...]} glob like every other skill, and pi/ui-architect.extension.ts ("pi": {"extensions": [...]}) registers a real /ui-architect command: verified against the installed @earendil-works/pi-coding-agent v0.84.3 — its own shipped (if not core-builtin) examples/extensions/subagent/ proves the pattern this extension reuses — dispatching planning, composition, and QA as isolated nested pi --mode json -p --no-session child processes, each tool-walled to mirror this plugin's Claude seats (read,grep,find,ls,bash for planning/QA; add edit,write only for composition) and gated by the same three portable-contract linters (LLD §C5, SPEC REQ-011). Live-verified end to end in this change's own development — a real pi -e ./pi/ui-architect.extension.ts session ran /ui-architect against a live model, dispatched all three isolated passes, wrote a real file, took a real screenshot, and returned a clean VerifyProof — not simulated against an unverified API. No hooks/agents surface otherwise.

Requirements

Python 3 (hook) + Node 22. Installs standalone in consumer repos (no monorepo path assumptions — ADR-0040 bare-repo posture).

Feedback / bugs

npm view @adia-ai/adia-ui-factory bugs — a monitored address reachable with no adiahealth repo access; triage owner: kimba. Filed an issue in-session via the report_issue MCP tool? It writes a local qa/findings/issues/<id>.md + .json and transmits nothing — attach the generated markdown to that address yourself.

---

Versioned with the @adia-ai lockstep (npm run check:lockstep) — see CHANGELOG.md for the current version; content merged between cuts is invisible to the installed plugin cache until the next lockstep bump or a manual sync.