@adia-ai/adia-ui-factory 0.2.2 → 0.2.4

package/skills/adia-ui-kit/assets/team-scaffold/tickets-README.md

@@ -0,0 +1,208 @@
+# Ticket Lifecycle Specification
+
+> **Authoring discipline:** `adia-ui-kit` skill §FeedbackDiscipline +
+> `../../references/feedback-authoring.md` (vendored from color-app's
+> `.agents/team/skills/feedback-authoring.md` — battle-tested across 60+
+> real tickets to `@adia-ai/*` packages).
+> **Response discipline:** same skill + `../../references/response-authoring.md`.
+> **Schema:** YAML front-matter + CommonMark body per state below.
+
+---
+
+## Stages & Naming
+
+```
+drafts/        Agent rough drafts, blocker notes
+  - filename:  FEEDBACK-NN--<recipient>--YYYY-MM-DD.md  (or RESPONSE-NN for self-review drafts)
+  - status:    draft
+  - P3 stays here; P0/P1/P2 promoted to outbox after polish
+
+outbox/        Polished, submitted to upstream
+  - filename:  FEEDBACK-NN--<recipient>--YYYY-MM-DD.md
+  - status:    submitted → responded → resolved (or retracted)
+  - Once submitted, do not edit body; corrections via --followup.md sibling
+
+inbox/         Responses received from upstream
+  - filename:  RESPONSE-NN--<sender>--YYYY-MM-DD.md
+  - status:    received → triaged → resolved
+  - Triaging may produce new outbox tickets (--followup files for clarifications)
+
+archive/       Superseded registries, historical legacy docs only
+  - Immutable after write
+  - Use when migrating storage layouts or pruning stale arcs
+```
+
+**Serial numbering:** `NN` is monotonic across the entire repo, allocated
+at draft-creation time. `REGISTRY.md` shows the highest in-use number.
+Use `ticket-tool next-id`
+to get the next available NN.
+
+**Recipient slug:** kebab-case identifier of the upstream maintainer or
+package family. Examples: `adia-ui`, `adia-packages`, `pi-skills`.
+
+**Followups:** when the original ticket needs an addendum after a
+RESPONSE, name the addendum `FEEDBACK-NN--<recipient>--YYYY-MM-DD--followup.md`.
+Followups land directly in `outbox/` (they're already polished — the
+context is the existing ticket).
+
+---
+
+## Draft Frontmatter Contract
+
+```yaml
+---
+id: "NN"                                              # serial — see ticket-tool next-id
+type: feedback                                        # feedback | request | response
+recipient: adia-ui
+date: "YYYY-MM-DD"
+author: "<agent-name> (<session-context>)"            # don't claim a human author
+project: "<consumer-project-name>"
+status: draft                                         # draft → submitted → responded → resolved (or retracted)
+references:                                           # every prior touchpoint
+  - "FEEDBACK-NN--adia-ui--YYYY-MM-DD"
+  - "RESPONSE-NN--adia-ui--YYYY-MM-DD"
+  - "FEEDBACK-NN--OMISSIONS-DEFENSE"                  # if a companion was authored
+version: "@adia-ai/web-components@X.Y.Z"              # version verified against
+priority: p0                                          # highest priority in the doc (p0|p1|p2|p3)
+---
+```
+
+`status: draft` is the right starting point. `ticket-tool finalize` flips
+it to `status: submitted` and moves the file to `outbox/`. Retraction
+flips it to `status: retracted` and moves the file BACK to `drafts/`.
+
+---
+
+## Body Shape — 4-block per finding
+
+Multi-item tickets are normative. Each numbered finding (`## N. <Title> (P<x>)`)
+contains:
+
+1. **What happened** — concrete observed behavior. Stack trace if a
+   crash. Screenshot path if visual. Cite `file:line` for both consumer
+   code AND framework code.
+2. **Root cause (verified end-to-end)** — walk the recipient through
+   HOW you established the cause. Probe output. Source file + line.
+3. **Reproduction** — minimal code block the recipient can paste into
+   their test harness and observe the symptom.
+4. **Request** — specific ask. Code patch sketch, concrete API shape,
+   doc paragraph, or a multi-option proposal (Option A/B/C with trade-offs).
+5. **Why this matters** — one paragraph. Who else hits this? Workaround
+   cost? Cost of NOT fixing?
+
+Plus, ticket-level:
+- **Executive Summary** at top — one paragraph stating the headline
+  problem and net effect.
+- **Cost-estimate table** under the summary — `| Pri | Item | Estimated cost |`
+  with honest estimates (`unknown — defer to maintainer judgement` is
+  acceptable; guesses are not).
+- **Items deliberately NOT included** at bottom — the exclusion defense.
+  Every exclusion cites a verification anchor.
+- **Related observations (non-asks)** at very bottom — context the
+  recipient may find useful but isn't a code ask.
+
+If the exclusion list has 15+ items or spans 4+ rationale categories,
+promote it to a companion `FEEDBACK-NN--OMISSIONS-DEFENSE.md` file (see
+`../../references/feedback-authoring.md` §6b).
+
+---
+
+## RESPONSE Format
+
+When upstream replies, file in `inbox/` as `RESPONSE-NN--<sender>--YYYY-MM-DD.md`.
+Schema:
+
+```yaml
+---
+id: "NN"
+type: response
+recipient: <consumer-project>
+date: "YYYY-MM-DD"
+author: "<upstream-maintainer-name>"
+project: "<upstream-project-name>"
+references:
+  - "FEEDBACK-NN--<recipient>--YYYY-MM-DD"
+version: "@adia-ai/web-components@X.Y.Z"
+status: submitted
+---
+```
+
+Body: claim-by-claim verdicts using the verdict taxonomy from
+`../../references/response-authoring.md`:
+
+| Marker | Verdict |
+| ------ | ---------------------- |
+| ✅     | Confirmed (shipped / accepting) |
+| ⚠️     | Confirmed — partial    |
+| ⏳     | Deferred               |
+| ❌     | Dismissed (not-reproducible / by-design / incorrect-claim) |
+| 🔍    | Needs clarification    |
+| 🔀    | Out of scope — redirected |
+
+Every claim from the original FEEDBACK gets exactly one marker.
+
+---
+
+## Workflow Summary
+
+### Filing FEEDBACK
+
+1. Agent observes issue → drafts to `drafts/FEEDBACK-NN--<recipient>--YYYY-MM-DD.md`
+   (allocate NN via `ticket-tool next-id`).
+2. Agent polishes using `feedback-authoring.md` discipline (4-block body,
+   verified exclusions, cost estimates, references).
+3. Human (or human-driven agent) runs `ticket-tool finalize <NN>` —
+   gates verify completeness, file moves to `outbox/`, status flips to
+   `submitted`, `REGISTRY.md` gets a row.
+4. Commit. Submit upstream (open as GH issue / email / Slack — out of
+   scope for this tooling).
+
+### Receiving RESPONSE
+
+1. Upstream replies → manually create `inbox/RESPONSE-NN--<sender>--YYYY-MM-DD.md`
+   with their verdict-per-claim body.
+2. Run `ticket-tool register-response <NN>` — adds a row to `REGISTRY.md`
+   under the RESPONSE table, updates the matching FEEDBACK row's status
+   to `responded`.
+3. Triage: if any verdicts are partial / deferred / needs-clarification,
+   draft a `--followup.md` sibling in `outbox/`.
+
+### Retracting
+
+When a FEEDBACK turns out to be wrong (RESPONSE dismisses it correctly,
+or self-review post-submission reveals a flaw):
+
+1. Run `ticket-tool retract <NN> --reason "<one-sentence reason>"` —
+   moves file from `outbox/` back to `drafts/`, flips status to
+   `retracted`, populates `retracted-reason` front-matter field.
+2. `REGISTRY.md` row stays — status column flips to `retracted`. The
+   ticket is part of the audit trail forever; retraction is a status
+   change, not a deletion.
+
+### Archiving
+
+When migrating storage layouts or pruning superseded arcs, move the
+artifact to `archive/` and add a one-line note to `REGISTRY.md` pointing
+at the new location. `archive/` is immutable after write.
+
+---
+
+## Deduplication Rules
+
+Before promoting draft → outbox, the author MUST check:
+
+1. `rg '<component>' outbox/FEEDBACK-*` — same component filed recently?
+2. `rg '<symptom>' inbox/RESPONSE-*` — already addressed in a response?
+3. `ls drafts/` — same blocker from another agent?
+4. `cat REGISTRY.md` — grep for keywords matching the new ask.
+
+If duplicate found: merge into existing ticket OR add as "Related
+observations" in the existing ticket, rather than filing a new top-level
+finding.
+
+---
+
+*Aligned with: RFC 2119 (key words), RFC 5322 (email envelope), ADR-0000
+(decision record format), Keep a Changelog (date/scope/summary),
+GitHub Issues Markdown (task lists). Layout vendored from color-app's
+battle-tested 2026-05-17 spec.*

package/skills/adia-ui-kit/assets/team-scaffold/tickets-REGISTRY.md

@@ -0,0 +1,81 @@
+# `.agents/team/tickets/` — Outbound + Inbound Correspondence Registry
+
+> **Live since:** 2026-05-20
+> **Schema:** see the `README.md` in this directory
+
+---
+
+## Directory Layout
+
+```
+.agents/team/tickets/
+├── REGISTRY.md          ← This file: master registry of ALL tickets
+├── README.md            ← Ticket lifecycle specification
+├── drafts/              ← Agent rough drafts → coordinator drafts
+├── outbox/              ← Polished FEEDBACK tickets sent upstream
+├── inbox/               ← RESPONSE tickets received from upstream
+└── archive/             ← Superseded registries, historical legacy docs
+```
+
+---
+
+## Quick Navigation
+
+| Want to...                       | Go to                              |
+| -------------------------------- | ---------------------------------- |
+| File new upstream feedback       | Draft to `drafts/`, then `ticket-tool finalize` |
+| Read upstream response           | `inbox/`                           |
+| Read a draft before publication  | `drafts/`                          |
+| See all FEEDBACK ever filed      | This file ↓ (FEEDBACK table)       |
+| See all RESPONSE ever received   | This file ↓ (RESPONSE table)       |
+| Get the next available ticket ID | `ticket-tool next-id`              |
+
+---
+
+## FEEDBACK Filed (0 total)
+
+| # | File | Recipient | Date | Status | Priority | Summary |
+|---|------|-----------|------|--------|----------|---------|
+
+*(No tickets filed yet. New rows are appended at draft-finalize time by
+`ticket-tool finalize`.)*
+
+### FEEDBACK with OMISSIONS-DEFENSE companions
+
+| FEEDBACK | Companion | Items | Categories |
+|----------|-----------|-------|------------|
+
+---
+
+## RESPONSE Received (0 total)
+
+| # | File | Recipient | Date | Status | Verdicts |
+|---|------|-----------|------|--------|----------|
+
+*(No responses received yet. New rows are appended by
+`ticket-tool register-response`.)*
+
+---
+
+## Adding New Tickets
+
+### Filing FEEDBACK
+
+1. Get next ID: `ticket-tool next-id`
+2. Draft: `ticket-tool new <type> <recipient> --slug <short-slug>`
+3. Polish using `../../references/feedback-authoring.md` (vendored from color-app).
+4. Finalize: `ticket-tool finalize <NN>`
+   - Runs gates, moves `drafts/` → `outbox/`, flips status to `submitted`, appends a row here.
+5. Commit. Open upstream issue / send via the appropriate channel.
+
+### Receiving RESPONSE
+
+1. File in: `.agents/team/tickets/inbox/RESPONSE-NN--<sender>--YYYY-MM-DD.md`
+2. Run: `ticket-tool register-response <NN>`
+3. Triage in your session — if any verdicts need clarification, draft a
+   `--followup.md` sibling in `outbox/`.
+
+---
+
+*Live registry. Append-only via tooling; manual edits limited to status
+column transitions (e.g. flipping `submitted` → `responded` → `resolved`).*

package/skills/adia-ui-kit/assets/templates/AGENTS.template.md

@@ -0,0 +1,128 @@
+# {{PROJECT_NAME}} — Agent Guidelines
+
+Auto-loaded by agentic IDE / harness at session start.
+Read this first; defer to the AdiaUI skill for procedural detail.
+
+## Project
+
+{{PROJECT_DESCRIPTION_ONE_LINER}}
+
+Stack: {{STACK}} (e.g. "Vite + TypeScript + `@adia-ai/web-components` + `@adia-ai/web-modules`").
+
+## Skill (procedural source-of-truth)
+
+Use the AdiaUI Kit skill for all build / wiring / pattern / ticket
+procedural work:
+
+`{{SKILL_PATH}}`
+
+(Typical path: `/Users/<you>/Projects/gen-ui-kit/.agents/skills/adia-ui-kit/SKILL.md`.)
+
+When the user invokes `use adia-ui-kit` / `load the AdiaUI skill`, render
+the capability surface from the skill, not from this file. This file
+holds **project-specific** decisions; the skill holds **AdiaUI-general**
+procedure.
+
+To verify the skill version your install resolves to:
+
+```bash
+grep '^version:' {{SKILL_PATH}}
+```
+
+Pin a specific version in your project notes if reproducibility matters.
+
+## Ticket pipeline (upstream feedback to `@adia-ai/*`)
+
+Findings about `@adia-ai/*` packages or the `adia-ui-kit` skill itself
+file directly into the **central inbound store** at `chat-ui` (ADR-0031).
+One numbering namespace across all consumer projects; no per-repo
+drift. Set `ADIA_TICKETS_DIR` so the canonical ticket-tool routes to
+the central store:
+
+```bash
+export ADIA_TICKETS_DIR=/Users/<you>/Projects/gen-ui-kit/.agents/team/tickets
+
+# Allocate a global NN (consults chat-ui's REGISTRY, not yours)
+ticket-tool next-id
+
+# Scaffold polished FEEDBACK directly into chat-ui/.../inbound/
+ticket-tool \
+  new feedback adia-ui --inbound --sender {{PROJECT_NAME_KEBAB}} \
+  --slug <kebab-topic>
+
+# Polish per references/feedback-authoring.md in the skill bundle.
+# Then commit the file inside chat-ui (it lives there now).
+```
+
+For drafts that need polishing pressure before relay, you can still
+use a local `.agents/team/tickets/drafts/` in this project — drop
+`ADIA_TICKETS_DIR` from the env when running `new`/`finalize`. Polished
+tickets relay manually by `cp` into chat-ui inbound + `ticket-tool
+registry-rebuild` in chat-ui.
+
+See `.agents/skills/adia-ui-kit/SKILL.md` §FeedbackDiscipline + §Team
+Tickets + §InboundTickets for the full workflow. See
+`{{SKILL_PATH_DIR}}/../../team/tickets/inbound/README.md` for the
+consumer-agent vs maintainer-agent role split.
+
+Recipients:
+- `adia-ui` — package-side bugs / gaps (`@adia-ai/web-components`,
+  `@adia-ai/web-modules`, `@adia-ai/a2ui-*`, `@adia-ai/llm`)
+- `adia-ui-skill` — skill-side doc bugs / gaps
+
+## Install verification
+
+Before any non-trivial work, verify your `@adia-ai/*` install is sane:
+
+```bash
+{{SKILL_PATH_DIR}}/scripts/check-adia-versions.py --root .
+```
+
+Should exit 0 with all 9 packages on a single version, matching npm
+latest. Drift means stale install — see SKILL.md §VersionCheck.
+
+## Key conventions (AdiaUI-specific)
+
+- **Never `git add -A`** — multi-agent repos demand explicit file
+  allowlists; see SKILL.md §FeedbackDiscipline + `multi-agent-git-
+  staging-discipline` skill if you have it
+- **Always import shell CSS explicitly** when using a shell tag.
+  `admin-shell.js` / `chat-shell.js` / etc. do NOT self-import their
+  layout CSS — see SKILL.md §CSSPolicy. Add to your entry file:
+  ```js
+  import '@adia-ai/web-modules/shell/admin-shell.css';
+  // or chat-shell.css, editor-shell.css, simple-shell.css
+  ```
+- **Use Vite 8-compatible glob form** for icon loaders:
+  ```js
+  import.meta.glob('../node_modules/@phosphor-icons/core/assets/regular/*.svg', { … });
+  // NOT '@phosphor-icons/core/...' — rolldown rejects @-scoped
+  ```
+- **Do NOT import the full `@adia-ai/web-modules` barrel** —
+  use per-cluster subpaths (`@adia-ai/web-modules/shell`,
+  `@adia-ai/web-modules/generative`, etc.). The full barrel is broken
+  on `<v0.6.8` and noisy on `>=v0.6.8`.
+
+## Project-specific decisions
+
+{{PROJECT_SPECIFIC_DECISIONS}}
+
+Examples:
+- "All routes pre-rendered statically; SPA mode only for admin
+  dashboards under `/admin/*`."
+- "Theme: light-only default; dark scheme opt-in per user setting."
+- "Data layer: REST-only — no GraphQL, no SSE."
+
+## Skill version pinning (optional)
+
+If you want to lock the skill version this project depends on, record
+the version + commit SHA here:
+
+- Skill version: `{{SKILL_VERSION}}` ({{SKILL_COMMIT}})
+- AdiaUI packages: `@adia-ai/*@{{ADIA_AI_VERSION}}`
+
+Re-verify and bump when intentionally adopting newer skill capabilities.
+
+---
+
+**Last reviewed:** {{DATE}}

package/skills/adia-ui-kit/assets/templates/CLAUDE.template.md

@@ -0,0 +1 @@
+@AGENTS.md

package/skills/adia-ui-kit/assets/templates/FEEDBACK-OMISSIONS-DEFENSE.template.md

@@ -0,0 +1,150 @@
+# FEEDBACK-{{ID}} Omissions Defense
+
+**Date:** {{DATE}}
+**Author:** {{AGENT}} ({{SESSION_CONTEXT}})
+**Context:** Prepared for leadership + principal engineer review. Every
+item below was considered for inclusion in `FEEDBACK-{{ID}}--{{RECIPIENT}}--{{DATE}}.md`
+and deliberately excluded.
+
+> **Use this companion when:** the inline `§Items deliberately NOT included`
+> block in the main ticket would exceed ~15 items or span ~4+ rationale
+> categories. Large inline blocks get skimmed; a standalone file forces
+> reviewers to treat exclusions as first-class artifacts.
+
+---
+
+## Principle Applied
+
+<2–4 sentences naming the scoping rule the ticket used, e.g.
+"current-session, concrete, reproducible friction that blocked or
+significantly slowed <feature> delivery.">
+
+Items were excluded if they were:
+
+1. <Category 1, e.g. "Already filed by the peer agent in FEEDBACK-NN-1">
+2. <Category 2, e.g. "Resolved in prior releases">
+3. <Category 3, e.g. "Standard CSS customization, not framework defects">
+4. <Category 4, e.g. "Speculative / not yet encountered in practice">
+5. <Category 5, e.g. "Internal to our adapter architecture">
+
+I will flag items where my confidence is low.
+
+---
+
+## <Category 1> — Correctly Omitted
+
+### Omission 1: <one-line title> (P<x>)
+
+**<EVIDENCE TAG>** — uppercase, scannable. Examples:
+`PEER FINDING` / `VERIFIED IN SOURCE` / `RESOLVED IN v0.5.2` /
+`OUR INTERNAL API` / `THIRD-PARTY TOOL` / `STANDARD CUSTOMIZATION` /
+`SPECULATIVE`
+
+<1–2 sentences citing the verification anchor — file:line, version,
+prior ticket ID, or skill/docs reference.>
+
+**Defense:** <Why this exclusion is correct. 1–3 sentences.>
+
+**Confidence:** High | Medium | Low.
+*(Medium or Low ratings are honesty, not weakness. If you flag low
+confidence, the reviewer can prioritize verification.)*
+
+### Omission 2: <next title> (P<x>)
+
+**<EVIDENCE TAG>**
+<anchor citation>
+
+**Defense:** <reasoning>
+
+**Confidence:** High | Medium | Low.
+
+<Repeat for all omissions in this category.>
+
+---
+
+## <Category 2> — Correctly Omitted
+
+### Omission N: ...
+
+<Same shape as above.>
+
+---
+
+## <Category 3> — Correctly Omitted
+
+### Omission N: ...
+
+---
+
+## <Category 4> — Correctly Omitted
+
+### Omission N: ...
+
+---
+
+## <Category 5> — Correctly Omitted
+
+### Omission N: ...
+
+---
+
+## Mistakes I May Have Made
+
+Flag items where, on reflection, exclusion might have been an error.
+This section is the inverse of the rest of the file — it's where the
+author voluntarily surfaces their own weakest exclusions for review.
+
+### Potential Mistake A: <title>
+
+**WHY IT MATTERS:** <one paragraph on why this exclusion might have
+been wrong.>
+
+**ACTION:** Willing to add as P<x> to FEEDBACK-{{ID}} §<N> if requested.
+
+### Potential Mistake B: <title>
+
+<same shape>
+
+---
+
+## If I Had Two More Hours
+
+With additional time, I would:
+
+1. <Specific verification I'd run, e.g. "Bisect Omission 6 to confirm
+   which release fixed it and whether a regression test exists.">
+2. <Audit I'd perform.>
+3. <Component(s) I'd test that haven't been exercised yet.>
+4. <Docs / source I'd cross-check.>
+
+This section gives the reviewer a roadmap for what additional verification
+would tighten the ticket.
+
+---
+
+## Bottom Line
+
+`FEEDBACK-{{ID}}` contains <N> items, all of which are <core scope claim,
+e.g. "current-session, concrete, and blocking-or-slowing">. The <M>
+omissions above are either <category-1>, <category-2>, <category-3>,
+<category-4>, or <category-5>. I'm prepared to escalate any of them if
+the reviewer disagrees with the classification.
+
+---
+
+## Cross-link in the main ticket
+
+The main `FEEDBACK-{{ID}}--{{RECIPIENT}}--{{DATE}}.md` MUST include this
+companion in front-matter:
+
+```yaml
+references:
+  - "FEEDBACK-{{ID}}--OMISSIONS-DEFENSE"
+```
+
+…and in its §Items deliberately NOT included section, replace the bullet
+list with a one-line pointer:
+
+> Items considered and deliberately excluded are tracked in
+> `FEEDBACK-{{ID}}--OMISSIONS-DEFENSE.md` — <M> omissions across <N> rationale
+> categories, each with verification anchor and confidence rating.