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 (20 — 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 | | theme-audit | procedural | classify a consumer theme.css against the framework's own defaults/tokens/primitives — restated defaults, re-derived tokens, dead selectors, hand-built component work; audit + report only, no rewrites (gh#2257) |

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).

lab-posture-guard — PreToolUse (Write|Edit) blocking guard, active only in lab posture (see Posture, below); a no-op in bare-repo/absent posture, leaving adia-lint's existing advisory contract completely unchanged. A SessionStart hook warms its manifest cache once per session; selftest ships (npm run check:lab-posture-guard-selftest).

Posture

Two postures a consumer repo can declare (ADR-0108, LLD-0019 §C3): bare-repo (ADR-0040, the default — this plugin working standalone with no monorepo path assumptions) and lab (ADR-0108 — a repo that installs @adia-ai/web-components at root, pinned, and scaffolds prototypes that consume those root packages directly as app source). Posture is an EXPLICIT marker, never inferred from package.json or node_modules — that inventory-only question ("what's installed") is adia-info's separate probe, not a declared-intent signal.

A repo-root .adia JSON file declares posture:

{
  "posture": "lab",
  "kit": { "web-components": "9.9.9" }
}

• posture — "lab" or "bare-repo", required when the file exists. An explicit "bare-repo" value is accepted alongside the file's plain absence — both read as bare-repo behavior — so a repo can affirmatively opt OUT of lab posture in its own marker rather than relying on absence alone.
• kit — optional. When present, kit["web-components"] records the installed @adia-ai/web-components version the marker was written against — informational only; nothing in this plugin reads it yet.
• Missing file, unparseable JSON, or a missing/unrecognized posture value all resolve to bare-repo behavior — the permissive branch. A corrupt marker must never accidentally turn ON the stricter lab-posture enforcement below.

scripts/adia-posture.mjs (readPosture(repoRoot) → 'lab' | 'bare-repo' | 'absent') is the one reader both lab-posture-guard and a future scaffold_prototype (LLD-0019 §C6, not shipped yet) key on.

In lab posture, lab-posture-guard validates every Write/Edit against the installed manifest's tags, attributes, and declared enum values (UNKNOWN-TAG/UNKNOWN-ATTR/ENUM-VALUE/INTERNAL-TIER) and DENIES a violating write before it lands, naming the offending tag/attr/value and the manifest's allowed set in the deny reason so the agent can self-correct. In bare-repo or absent posture, this hook is a complete no-op — adia-lint's existing PostToolUse advisory contract is the only signal, unchanged.

Commands

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

Scripts

Consumer-runnable checks shipped as plain Node scripts under scripts/, no MCP server required: adia-probe.mjs (the browser-QA gate; see surface-qa), adia-preflight.mjs (every CI-step prerequisite, each failure named with its remedy), adia-contract-check.mjs (authored markup attributes vs. the shipped component contracts), and adia-theme-audit.mjs (the theme.css redundancy classifier; see theme-audit).

MCP

adia-gen-ui server pinned: @adia-ai/[email protected] (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.

theme-audit's adia-theme-audit bin runs identically on every harness — a plain Node script with no Claude-specific runtime dependency; the /theme-audit command degrades to invoking the skill directly on Codex and Hermes, and becomes a genuine prompts/theme-audit.md Pi command via build:harness-manifests.

Lab posture's write-time enforcement (ADR-0108 D5/D6) is a Claude Code-only guarantee — AGENTS.md's own "Non-Claude harnesses" section states plainly that none of Codex, Hermes, or Pi has a manifest key for hooks/, and none has a hook runtime a PreToolUse deny could wire into, so lab-posture-guard simply does not run on any of the three. They degrade to npm run lint in the monorepo (or the equivalent vendored adia-lint/lint-bank invocation in a consumer repo) picking up the same four manifest-derived rules (UNKNOWN-TAG/UNKNOWN-ATTR/ENUM-VALUE/INTERNAL-TIER, ADR-0108 D5) at warn severity — after the fact, at lint/check time, rather than before the write lands. get_manifest reachability without the hook is not uniform either: Codex reaches it through its plain .mcp.json passthrough; Hermes needs its hermes-mcp.yaml fragment hand-merged into ~/.hermes/config.yaml; Pi has no native MCP support at all, so a Pi session without the third-party pi-mcp-adapter gets neither the manifest nor the lint-time signal until a npm run check/npm run lint pass runs.

• 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, inside that same external Hermes Agent install (not a path in this repo), 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.

Release gate

release_gate.py's G15 (harness overlay freshness) FAILs for this plugin and is accepted, not fixed, per ticket 10035: release_gate.py has no config hook (no .claude/workflow.json field, no per-plugin file) that G15 itself reads, so there is no override mechanism to declare here as code, the acceptance is recorded here as doctrine instead.

Conductor ruling, gh#3764 issuecomment-5647637558 (2026-09-12, unattended run, authorized by issuecomment-5647495831), quoted verbatim as the ruling record:

Conductor ruling, 2026-09-12 (unattended run, authorization issuecomment-5647495831; posted here so it is citable, not only in PR #4403's body and the plugin READMEs).

release_gate.py G15 fails for both adia-ui-forge (8 findings, ticket 10026) and adia-ui-factory (13 findings, ticket 10035). Verified cause: G15 (harness 3.19.6, release_gate.py:917-932) is a bare subprocess of harness_emit.py --verify (:899-950) with no allow, skip, env or config hook, and its overlay convention differs from this repo's own manifest generators (scripts/build/codex-manifests.mjs, scripts/build/harness-manifests.mjs), which are gated fresh by check:codex-manifests-fresh and check:harness-manifests-fresh. Ruling: this repo keeps its generators as the source of truth; G15 is declared ACCEPTED (not fixed) for both plugins, recorded in each plugin README's release-gate section; the convention mismatch is routed upstream to the adia-harness conductor per the 2026-09-10 routing ruling. Tickets 10026 and 10035 stay OPEN until the upstream fix lands. Not a skip of any lockstep (class A) gate; those are the 36-gate roster in package-release.

Tickets: 10035 (this plugin), 10026 (adia-ui-forge, same class). Both stay OPEN pending the upstream harness-plugin item this ruling routes the fix to, filed by the adia-harness conductor on 2026-09-12 as adia-harness local ticket 137.

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.