# adia-ui-kit-forge

Maintainer plugin for the adia-ui (`@adia-ai`) framework, author primitives
and shells, run the A2UI pipeline, review gen-UI quality, sweep QA, release,
deploy. Consumer counterpart: **adia-ui-kit-factory**.

Re-engineered 2026-07 for the Fable 5 harness (design:
`.claude/docs/specs/plugin-estate-v2.md`): one skill per job, explicit
invocation dials, references for depth, mechanical rules in hooks, thin agents.

## Skills (12)

| Skill | Species | Job |
|---|---|---|
| `primitive-authoring` | procedural | author/modify framework source, primitives, shells, traits, yaml SoTs, demos |
| `component-md-authoring` | procedural | author a component's `component.md` screen-reader/behavioral spec, keep it PR-fresh |
| `a2ui-maintenance` | procedural | the A2UI pipeline, strategies, corpus, retrieval calibration, MCP server |
| `gen-ui-review` | procedural | closed-loop gen-UI output quality review |
| `demo-audit` | procedural | multi-mode QA sweep (visual/static/anatomy/leak/composition) |
| `llm-client-maintenance` | procedural | maintain the `@adia-ai/llm` client (providers, streaming, registry) |
| `package-release` | procedural | cut/tag/publish/deploy releases; author migration guides |
| `site-deployment` | procedural | exe.dev service ops, site deploys, VM diagnosis, secret rotation |
| `site-docs-authoring` | procedural | author/review `site/pages/` docs pages against the shared skeleton |
| `ssr-compatibility` | knowledge | answers SSR failure-shape questions (linkedom/Astro consumers) |
| `cross-harness-authoring-standards` | procedural | author consumer-facing multi-harness install instructions |
| `cross-harness-compatibility-standards` | procedural | engineering standard for building a capability that genuinely works across Claude/Codex/Pi/Hermes (ADR-0091) |

## Agents (8, thin shells)

`primitive-authoring-agent` (sonnet, builds) · `a2ui-maintenance-agent` (pipeline) ·
`demo-audit-agent` (**no Write/Edit**, the critic wall; dogfood sweeps) ·
`gen-ui-review-agent` (**no Write/Edit**, the critic wall; A2UI-engine gallery
scoring, split from the retired `framework-reviewer`, gh#1733) · `package-release-agent`
(the serial ship seat) · `framework-planner-agent` (fable, decomposes a framework change
into PRD/SPEC/LLD/ADR before a builder seat touches it) · `a2ui-planner-agent` (fable,
same decomposition scoped to A2UI catalog/tier cohesion, never touches corpus or evals) ·
`framework-checker` (fable, **no Write/Edit**, read-only corpus-wide cohesion
audit: color tokens, typography, state naming, attrs-as-api, implementation patterns).

## Hooks (5, `adapters/claude/hooks.json` is the roster; `check:plugin-count-claims` guards this header count)

`sidecar-prewrite-guard` (PreToolUse deny on hand-edits to generated
artifacts) · `release-pretag-docs-gate` (PreToolUse: release-tagging Bash
calls need their docs gate) · `forge-lint` (PostToolUse advisory
authoring-smell repair loop) · `demo-postwrite-pattern-gate` (PostToolUse:
composite demos must cite a `Pattern source:`) · `site-postwrite-derivation-gate`
(PostToolUse: `site/sitemap.json` edits must regenerate `site/llms.txt` +
the patterns/templates index). All ship `selftest` modes.

## Commands

`/package-release` · `/site-deployment` · `/demo-audit` · `/gen-ui-review`

## Non-Claude harnesses

External install beyond Claude Code (AGENTS.md's own "Non-Claude harnesses"
section carries the shared degradation table this summarizes):

- **Codex** (gh#1888): `.codex-plugin/plugin.json` + per-skill
  `agents/openai.yaml`, derived. No manifest key for hooks/commands/agents, a command degrades to invoking its skill directly.
- **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-forge` directory. No hooks/agents surface.
  This plugin ships no `.mcp.json`, so there's no MCP story to wire either
  way.
- **Pi** (gh#1954): discovered via the `pi-package` keyword and the `"pi"`
  field in `package.json`; `prompts/*.md` gives every `/command`, including
  the two consent-gated ones, `/package-release` and `/site-deployment`, a
  genuine Pi prompt template (Pi's prompt layer is human-keystroke-only, the
  same trust boundary those two already sit behind in Claude Code). No
  hooks/agents surface.

## Contracts

`references/contracts/`, the producer side of the MIGRATION GUIDE format and
the a2ui MCP tool-surface stability rule (vendored twins live in
adia-ui-kit-factory; reconcile both on change).

## Release gate

`release_gate.py`'s G15 (harness overlay freshness) FAILs for this plugin and
is accepted, not fixed, per ticket 10026: `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: 10026 (this plugin), 10035 (adia-ui-factory, 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 (hooks) + Node 22 (scripts). Runs against an `@adia-ai`-style
monorepo checkout.

## Feedback / bugs

`npm view @adia-ai/adia-ui-forge bugs`, a monitored address reachable with
no adiahealth repo access; triage owner: **kimba**.

---

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 (see `package-release`
`references/cut-procedure.md` §Plugin cache).