@adia-ai/adia-ui-forge 0.1.2

package/.claude-plugin/plugin.json

@@ -0,0 +1,23 @@
+{
+  "name": "adia-ui-forge",
+  "version": "0.1.2",
+  "description": "Author and maintain the adia-ui (@adia-ai) framework itself — primitives (web-components), composite shells (web-modules), the A2UI / gen-ui generation engine and its training corpus, the @adia-ai/llm client, quality sweeps, and release engineering across all @adia-ai packages. The maintainer counterpart to adia-ui-factory (the consumer/app-author plugin).",
+  "author": {
+    "name": "Kim",
+    "email": "kim@sublimeheroics.com"
+  },
+  "homepage": "https://github.com/adiahealth/gen-ui-kit",
+  "license": "MIT",
+  "keywords": [
+    "adia-ui",
+    "a2ui",
+    "gen-ui",
+    "web-components",
+    "web-modules",
+    "llm",
+    "framework-authoring",
+    "component-library",
+    "release-engineering",
+    "maintainer"
+  ]
+}

package/CHANGELOG.md

@@ -0,0 +1,26 @@
+# Changelog
+
+All notable changes to **adia-ui-forge** are documented here. Format follows [Keep a Changelog](https://keepachangelog.com/); versioning is [SemVer](https://semver.org/).
+
+## [0.1.2] — 2026-06-04
+
+- **Aspiration is now a precondition of making — a soft gate.** Before a maker skill converges, the **design principles** (the framework philosophy the change is reasoned toward — light-DOM composability, token-driven styling, contract-first authoring, no lifecycle leaks) must be at least lightly named; authoring reasoned toward _nothing_ drifts to the average primitive. `adia-ui-authoring` gains a **§DesignPrinciplesSoftGate** section before its cold-start menu; `adia-ui-a2ui` and `adia-ui-llm` get a brief domain-fitted equivalent at their cold-start (the generation philosophy; the client-contract philosophy); `/adia-forge-author` gains a one-line **"name the design principles before you converge"** gate. Because this plugin has no standalone design-principles document — only per-artifact guardrails — the gate also nudges the maintainer to **name the principles themselves, even provisionally** (they were previously implicit). It is a _soft_ blocker throughout — cleared by **naming** a provisional, revisable direction, never by stopping. Mirrors brand-forge v0.4.5 and the generalized rule in plugins-factory `operational-roles.md`.
+
+## [0.1.1] — 2026-06-04
+
+- **Quoted `argument-hint` frontmatter** across all commands — normalizes the value to a string (YAML was parsing the unquoted `[..]` as a flow list) and satisfies plugins-factory's new frontmatter flow-collection lint. No behavior change.
+
+## [0.1.0] — 2026-06-03
+
+Initial release — the maintainer-side counterpart to `adia-ui-factory`, carved and de-repo'd from the `@adia-ai` monorepo's `.agents/` system (scope A: the framework's own authoring toolkit, assuming `@adia-ai` monorepo conventions).
+
+### Added
+
+- **7 skills** — `adia-ui-forge` (orchestrator: classify subsystem → route) + `adia-ui-authoring` (web-components / web-modules), `adia-ui-a2ui` (the A2UI / gen-ui engine), `adia-ui-llm` (the `@adia-ai/llm` client), `adia-ui-gen-review` (generated-UI quality scoring), `adia-ui-dogfood` (QA sweep), `adia-ui-release` (release engineering + migration-guide authoring).
+- **7 commands** — `/adia-forge-orient·author·a2ui·llm·review·dogfood·release`.
+- **Advisory authoring-lint hook** — `bin/forge-lint` (11 component-authoring smells; `PostToolUse` on `Write|Edit`, never blocks).
+- **Co-located shared infra** — `references/shared/` (content-trust, plan-execute-verify, skill-conventions) + `bin/lib/` (audit-axes, teach-router, dry-run-irreversible, run-skill-evals). Self-contained, zero cross-plugin paths.
+
+### Reviewed
+
+- Red-teamed with the `plugins-factory` 9-critic council (CONDITIONAL → folded): reconciled the build-state docs, cut the always-on context tax (removed a redundant `trigger:` block, trimmed the longest skill descriptions), disclosed and guarded the release scripts' publish / network reach, synced the four description surfaces, and labeled the `forge-lint` ↔ `adia-lint` shared-core duplication. Full record under `reviews/`.

package/README.md

@@ -0,0 +1,54 @@
+# adia-ui-forge
+
+**Author and maintain the adia-ui (`@adia-ai`) framework itself.** This is the producer/maintainer counterpart to `adia-ui-factory` — where the factory builds _apps on_ the framework, the forge builds and ships _the framework_: its primitives, composite shells, the A2UI / gen-ui generation engine and training corpus, the LLM client, quality sweeps, and releases — across every `@adia-ai` package.
+
+> **Status: 0.1.2 — built and red-teamed.** All 7 skills, 7 commands, the advisory authoring-lint hook, and shared infra are in place and pass the harness gates (`validate_plugin.py --strict`, `reference-lint.py`, `forge-lint selftest`, markdownlint). The build record is in [ROADMAP.md](ROADMAP.md); the `plugins-factory` council critique is recorded under `reviews/`.
+
+## Who it's for
+
+Anyone working **on** the adia-ui framework — in the `@adia-ai` monorepo or a fork. It assumes the monorepo's package conventions (`packages/web-components`, `packages/web-modules`, `packages/a2ui`, `packages/llm`); it is not a generic "build any component library" toolkit. App authors who _consume_ the framework want `adia-ui-factory` instead.
+
+## Requirements & what it ships
+
+- **Two runtimes.** The hook + `forge-lint` are Python (3.8+); every skill script and `bin/lib/*` are Node ESM. Both must be on PATH — the skills' `§SelfAudit` and eval scripts need Node; the hook needs Python.
+- **The release skill bundles real capability.** `adia-ui-release` ships scripts that shell `git`, `npm publish`, `gh`, and `curl` (the deploy verify). They are operator-run (never hook-wired), go through a dry-run gate, and **fail loudly unless run inside an `@adia-ai`-style monorepo checkout** (a `packages/web-components` guard). The deploy host and npm scope are overridable (`--host`/`$ADIA_DEPLOY_HOST`, `--scope`/`$ADIA_NPM_SCOPE`).
+- **Skill versions are lineage, not the plugin version.** Per-skill `version` fields (e.g. `adia-ui-authoring` 1.9.2) are carried from the monorepo source skills; the plugin's own version is canonical for the bundle.
+- **Gates run via plugins-factory's harness.** `validate_plugin.py` / `reference-lint.py` live in `plugins-factory` (`/plugin install plugins-factory@plugins-forge` to run them; wire them into `adia-plugins` CI); `forge-lint selftest` is self-contained in the bundle.
+
+## The package surface it covers
+
+| Package / system | What the forge does with it |
+| --- | --- |
+| `@adia-ai/web-components` | author & evolve light-DOM primitives (props, `@scope` tokens, lifecycle, traits) |
+| `@adia-ai/web-modules` | author composite shells & clusters (admin / chat / editor / embed) |
+| `@adia-ai/a2ui` (6-pkg cluster: compose · corpus · retrieval · runtime · validator · mcp) | evolve the A2UI / gen-ui generation engine, chunk corpus, and MCP server |
+| gen-ui training data (`gen-ui-kit/data`) | author and curate the generation corpus / seed data |
+| `@adia-ai/llm` | maintain the provider-agnostic client (anthropic / openai / gemini adapters, SSE, models) |
+| all packages | gen-ui output quality review, cross-surface dogfood QA, and lockstep release engineering |
+
+## Skills (7)
+
+| Skill | Job |
+| --- | --- |
+| `adia-ui-forge` | cold-start orchestrator — classify the package/concern and route to the owning skill |
+| `adia-ui-authoring` | author primitives (`web-components`) + composite shells (`web-modules`), tokens, traits |
+| `adia-ui-a2ui` | the A2UI / gen-ui generation engine — compose strategies, chunk corpus, retrieval, validator, runtime, MCP server |
+| `adia-ui-llm` | the `@adia-ai/llm` client — provider adapters, SSE streaming, model registry, the bridge |
+| `adia-ui-gen-review` | closed-loop quality scoring of generated gen-ui output, driving corpus fixes |
+| `adia-ui-dogfood` | static + visual QA sweep across components, apps, playgrounds, and catalog |
+| `adia-ui-release` | release-engineering discipline (gates, changelog/notes authoring) + migration-guide authoring |
+
+## Relationship to adia-ui-factory
+
+Producer ↔ consumer, fully independent (zero cross-plugin dependencies):
+
+|  | `adia-ui-forge` (maintainer) | `adia-ui-factory` (consumer) |
+| --- | --- | --- |
+| **authoring** | builds the primitives & shells | composes screens from them |
+| **a2ui / gen-ui** | builds the engine + corpus | renders generated UI via the published MCP |
+| **llm** | builds the `@adia-ai/llm` package | wires it into an app |
+| **migration** | authors the MIGRATION GUIDE | applies it to consumer code |
+
+## Provenance
+
+Carved from the `@adia-ai` monorepo's `.agents/` maintainer system, then authored and red-teamed with [`plugins-factory`](https://github.com/kimgranlund/plugins-forge/tree/main/plugins-factory) against its 9-dimension architecture standard.

package/bin/forge-lint

@@ -0,0 +1,263 @@
+#!/usr/bin/env python3
+"""forge-lint — advisory authoring-smell checker for the adia-ui FRAMEWORK source (maintainer slice).
+
+This is the producer-side counterpart to the consumer plugin's app-lint: it checks the framework's
+OWN component source as a maintainer authors it (primitives in packages/web-components, composites in
+packages/web-modules) for the framework's structural invariants — light-DOM only (no attachShadow,
+no ::slotted), component CSS is `@scope`-wrapped and token-only (no raw colors, no raw px >= 3, no
+extent on :scope, no dead `--a-font`), property definitions are well-formed (no `default: true`, no
+`attr:` typo), composites use `*-ui` primitives (no native-primitive leak), and no retired shell
+shapes (ADR-0024 data-attribute forms). Foundation/token sheets (a styles/ or tokens/ dir, a
+tokens/theme/host/palette/… stem, or `/* forge-lint: foundation */`) are exempt from the CSS-literal
+and scope checks.
+
+It deliberately does NOT carry the consumer/app traps (SSR double-router, top-level kit import,
+hardcoded overlay open) — those are about CONSUMING the framework in an app and live in the
+consumer plugin. forge-lint judges only authoring structure, never whether a component is good,
+accessible, or on-spec — that lives in the skills (adia-ui-authoring / -a2ui / -gen-review / -dogfood).
+A clean forge-lint says "no structural tells," never "this is right."
+
+Shared core: the regex bank below (RAW-COLOR/PX, SCOPE-EXTENT, NATIVE-PRIMITIVE, LEGACY-SHELL,
+the _is_foundation_css exemption) is mirrored in the sibling CONSUMER plugin's
+adia-ui-factory/bin/adia-lint. They are deliberate VENDORED copies — the catalog forbids
+cross-plugin imports (each plugin installs copy-alone) — so any change to a shared rule must be
+reconciled in BOTH files. forge-lint drops the consumer/app traps (SSR double-router, top-level
+import, hardcoded overlay open) and adds MISSING-SCOPE; that divergence is the point.
+
+Usage:
+  forge-lint <file>...        # lint files; exit 1 if any smell found, else 0
+  forge-lint -                # lint stdin as a generic source file
+  forge-lint --hook           # PostToolUse hook mode: read event JSON on stdin, lint the written
+                              #   source file, print advisory findings, ALWAYS exit 0 (never blocks)
+  forge-lint selftest         # run built-in fixtures (seeded smells + clean files + the hook exit-0 invariant)
+Stdlib only (Python 3.8+).
+"""
+import json
+import os
+import re
+import sys
+
+CODE_EXT = (".js", ".mjs", ".cjs", ".ts", ".tsx", ".jsx")
+STYLE_EXT = (".css",)
+MARKUP_EXT = (".html", ".htm", ".vue", ".svelte", ".astro", ".tsx", ".jsx")
+LINT_EXT = tuple(sorted(set(CODE_EXT + STYLE_EXT + MARKUP_EXT)))
+
+HEXCOLOR = re.compile(r"#[0-9a-fA-F]{3,8}\b")
+FUNCCOLOR = re.compile(r"\b(?:rgba?|hsla?|oklch|oklab|lab|lch)\s*\(")
+DEAD_FONT = re.compile(r"var\(\s*--a-font\s*[,)]")
+SCOPE_EXTENT = re.compile(
+    r":scope(?:\[[^\]]*\])?\s*\{[^{}]*?\b(?:width|height|inline-size|block-size)\s*:", re.S)
+BOOL_TRUE = re.compile(r"\bdefault:\s*true\b")
+ATTR_TYPO = re.compile(r"\battr:\s*['\"]")
+NATIVE_PRIMITIVE = re.compile(r"<(?:button|input|select|textarea|dialog)(?![\w-])")  # raw native, not a *-ui
+LEGACY_SHELL = re.compile(
+    r"data-chat-(?:messages|input|empty|name)|data-editor-body|data-canvas\b|data-sidebar="
+    r"|data-pane-(?:side|grow)|<aside-ui\b|<dialog\s+data-command")  # retired shell shapes (ADR-0024)
+PX_GE = re.compile(r"(?<![\w.-])(\d+)px\b")   # integer px; fractional (1.5px) deliberately not matched
+SELECTOR_RULE = re.compile(r"(?m)^\s*[.#:\[&\w][^{}\n]*\{")  # a selector opening a rule block
+FOUNDATION_OPT_IN = re.compile(r"forge-lint:\s*foundation", re.I)
+# Genuine token/foundation SHEETS are exempt from the CSS-literal + scope checks — matched by exact
+# stem or a styles/tokens dir, NOT a path substring (so a `color-picker` component is still linted).
+FOUNDATION_STEMS = {"tokens", "token", "theme", "themes", "foundation", "foundations",
+                    "palette", "palettes", "host", "reset", "resets", "scheme", "schemes",
+                    "color", "colors"}
+
+
+def _ext(path):
+    return os.path.splitext(path or "")[1].lower()
+
+
+def _is_foundation_css(path, text):
+    """A genuine token/foundation sheet — exempt from the CSS-literal + scope checks."""
+    segs = (path or "").replace("\\", "/").split("/")
+    if "styles" in segs or "tokens" in segs:
+        return True
+    stem = os.path.splitext(segs[-1])[0].lower() if segs else ""
+    if stem in FOUNDATION_STEMS:
+        return True
+    return bool(FOUNDATION_OPT_IN.search(text[:1000]))
+
+
+def lint_text(text, path=""):
+    """Return a list of (NAME, line, snippet, why) advisory findings."""
+    ext = _ext(path)
+    findings = []
+    is_tokenish = _is_foundation_css(path, text)
+
+    for i, line in enumerate(text.splitlines(), 1):
+        s = line.strip()[:90]
+        if "attachShadow" in line:
+            findings.append(("SHADOW-DOM", i, s,
+                             "adia-ui is light-DOM — never attachShadow; it breaks the token cascade + @scope"))
+        if "::slotted(" in line:
+            findings.append(("SLOTTED", i, s,
+                             "light DOM has no ::slotted — style projected content via :scope > [slot=\"x\"]"))
+        if ext in STYLE_EXT:
+            if DEAD_FONT.search(line):
+                findings.append(("DEAD-FONT-TOKEN", i, s,
+                                 "--a-font is not a real token (resolves to UA serif) — use var(--a-font-family-ui)"))
+            if not is_tokenish:
+                for decl in line.split(";"):  # per-declaration: a literal on a line that also has a var() still counts
+                    d = decl.strip()
+                    if not d or d.startswith(("//", "/*", "*")) or "var(" in decl or "light-dark(" in decl:
+                        continue
+                    if HEXCOLOR.search(decl) or FUNCCOLOR.search(decl):
+                        findings.append(("RAW-COLOR", i, s,
+                                         "component CSS is token-only — replace the literal with var(--a-*) (foundation/token files excepted)"))
+                        break
+            if not is_tokenish and not line.lstrip().startswith("@"):  # skip @media/@container/@scope at-rules
+                for decl in line.split(";"):
+                    if "/*" in decl:                                   # author-annotated carve-out
+                        continue
+                    if any(int(v) >= 3 for v in PX_GE.findall(decl)):
+                        findings.append(("RAW-PX", i, s,
+                                         "no raw px >= 3 in component CSS — use var(--a-space-*); 1-2px hairlines exempt, annotate a deliberate exception with a comment"))
+                        break
+        if ext in CODE_EXT:
+            if BOOL_TRUE.search(line):
+                findings.append(("BOOL-DEFAULT-TRUE", i, s,
+                                 "a boolean prop defaulting true can't be turned off by absence — flip the name so absent = false"))
+            if ATTR_TYPO.search(line):
+                findings.append(("ATTR-TYPO", i, s,
+                                 "did you mean `attribute:`? `attr:` is silently ignored in a property definition"))
+        if (ext in MARKUP_EXT and "slot=" not in line and not s.startswith(("<!--", "//", "*", "/*"))
+                and NATIVE_PRIMITIVE.search(line)):
+            findings.append(("NATIVE-PRIMITIVE", i, s,
+                             "a composite must build from *-ui primitives (button-ui / input-ui / select-ui / textarea-ui / modal-ui) — raw natives skip focus rings, theming, and form association; a deliberate slotted trigger (with slot=) is the exception"))
+        if LEGACY_SHELL.search(line):
+            findings.append(("LEGACY-SHELL", i, s,
+                             "retired shell shape (ADR-0024, v0.4.0) — use the bespoke tag (chat-thread / chat-composer / chat-empty · admin-sidebar / admin-command · editor-canvas · pane-ui)"))
+
+    if ext in STYLE_EXT:
+        for m in SCOPE_EXTENT.finditer(text):
+            ln = text.count("\n", 0, m.start()) + 1
+            findings.append(("SCOPE-EXTENT", ln, ":scope { … width/height … }",
+                             "a primitive is size-agnostic — let the consumer own width/height; don't set extent on :scope"))
+        # MISSING-SCOPE (maintainer-authoring): a component sheet with rules but no @scope wrapper.
+        if not is_tokenish and "@scope" not in text and SELECTOR_RULE.search(text):
+            findings.append(("MISSING-SCOPE", 1, "(file has CSS rules but no @scope block)",
+                             "component CSS must be wrapped in `@scope (<tag>) { … }` so styles don't leak in light DOM (foundation/token sheets excepted; opt out with /* forge-lint: foundation */)"))
+
+    findings.sort(key=lambda f: (f[1], f[0]))
+    return findings
+
+
+def _render(path, findings):
+    out = [f"forge-lint: {len(findings)} structural smell(s) in {path or '<stdin>'}"]
+    for name, ln, snip, why in findings:
+        out.append(f"  [{name}] line {ln}: {snip}")
+        out.append(f"      → {why}")
+    return "\n".join(out)
+
+
+def _lint_path(path):
+    try:
+        with open(path, encoding="utf-8", errors="replace") as f:
+            return lint_text(f.read(), path)
+    except OSError as err:
+        msg = getattr(err, "strerror", None) or str(err)
+        return [("READ-ERROR", 1, path[:90], f"failed to read file: {msg}")]
+
+
+def _hook():
+    try:
+        event = json.load(sys.stdin)
+    except (json.JSONDecodeError, ValueError):
+        return 0
+    ti = event.get("tool_input", {}) or {}
+    path = ti.get("file_path", "") or ""
+    if _ext(path) not in LINT_EXT:
+        return 0  # only component source; stay quiet otherwise
+    text = ti.get("content")
+    if text is None:
+        if not os.path.isfile(path):
+            return 0
+        try:
+            with open(path, encoding="utf-8", errors="replace") as f:
+                text = f.read()
+        except OSError:
+            return 0
+    findings = lint_text(text, path)
+    if findings:
+        print(_render(path, findings))
+        print("  (advisory — adia-ui framework authoring smells; the skills own the judgment)")
+    return 0  # NEVER block
+
+
+def _selftest():
+    """Built-in fixtures: each seeded smell must fire, clean files must stay quiet, --hook must exit 0."""
+    import io
+    cases = [
+        ("packages/web-components/components/x/x.css",
+         "@scope (x) {\n"
+         "  :scope { color:#f00; width:100%; font-family:var(--a-font); padding:24px; }\n"
+         "  :scope > [slot=a]::slotted(p) { margin:0; }\n"
+         "}",
+         {"RAW-COLOR", "SCOPE-EXTENT", "DEAD-FONT-TOKEN", "SLOTTED", "RAW-PX"}),
+        ("packages/web-components/styles/theme.css", ":root { --a-bg: light-dark(#fff, #000); }", set()),
+        ("packages/web-components/components/y/y.css",
+         ".y-thing { margin: 0; }\n.y-thing__row { gap: 4px; }",
+         {"MISSING-SCOPE"}),
+        ("packages/web-components/components/z/z.js",
+         "class Z extends UIElement {\n  static props = { open: { default: true }, label: { attr: 'label' } };\n"
+         "  connected() { this.attachShadow({ mode: 'open' }); }\n}",
+         {"SHADOW-DOM", "BOOL-DEFAULT-TRUE", "ATTR-TYPO"}),
+        ("packages/web-components/components/clean/clean.js",
+         "import { UIElement } from '../../core/element.js';\n"
+         "class Clean extends UIElement { connected() { this.innerHTML = '<col-ui></col-ui>'; } }",
+         set()),
+        ("packages/web-modules/shell/markup.html",
+         "<admin-shell>\n  <button>Save</button>\n  <input type=\"text\">\n  <button-ui slot=\"trigger\">ok</button-ui>\n</admin-shell>",
+         {"NATIVE-PRIMITIVE"}),
+        ("packages/web-modules/chat/legacy.html",
+         "<chat-shell>\n  <section data-chat-messages></section>\n  <chat-input-ui data-chat-input></chat-input-ui>\n</chat-shell>",
+         {"LEGACY-SHELL"}),
+    ]
+    ok = True
+    for name, text, expected in cases:
+        got = {f[0] for f in lint_text(text, name)}
+        if expected - got:
+            ok = False
+            print(f"selftest: {name} MISSING {sorted(expected - got)} (got {sorted(got)})", file=sys.stderr)
+        if not expected and got:
+            ok = False
+            print(f"selftest: {name} expected clean, got {sorted(got)}", file=sys.stderr)
+    saved_in, saved_out = sys.stdin, sys.stdout    # never-block invariant: --hook exits 0 even on smelly input
+    try:
+        sys.stdin = io.StringIO(json.dumps({"tool_input": {"file_path": "c.css",
+                                "content": ".a { color:#f00; }"}}))
+        sys.stdout = io.StringIO()
+        rc = _hook()
+    finally:
+        sys.stdin, sys.stdout = saved_in, saved_out
+    if rc != 0:
+        ok = False
+        print("selftest: --hook did not exit 0 on smelly input", file=sys.stderr)
+    print("selftest: PASS" if ok else "selftest: FAIL")
+    return 0 if ok else 1
+
+
+def main(argv):
+    if argv and argv[0] == "selftest":
+        return _selftest()
+    if "--hook" in argv:
+        return _hook()
+    args = [a for a in argv if a == "-" or not a.startswith("-")]
+    if not args:
+        print(__doc__.strip().split("\n\n", 1)[0], file=sys.stderr)
+        return 2
+    total = 0
+    for path in args:
+        if path == "-":
+            findings = lint_text(sys.stdin.read(), "<stdin>")
+            path = "<stdin>"
+        else:
+            findings = _lint_path(path)
+        if findings:
+            total += len(findings)
+            print(_render(path, findings))
+    return 1 if total else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))