@adia-ai/adia-ui-forge 0.1.3 → 0.8.0

package/skills/adia-ui-authoring/references/teach-protocol.md

@@ -1,428 +0,0 @@
-# Reference: Teach Protocol — Absorbing new knowledge into the adia-ui-authoring skill
-
-**Ecosystem context:** This reference is one instantiation of a generalizable **extensibility** pattern shared across the forge skill family (the consumer-side composition skill in the adia-ui-factory plugin and the sibling **adia-ui-release** skill carry parallel `teach-protocol.md` files). The pattern separates universal components (the trigger cluster, the 7 anti-patterns, the 5-step landing procedure, the citation-vs-knowledge principle, the negative case) from skill-specific components (the decision tree's branches, the worked examples). When editing this file, preserve the universal sections verbatim where possible — they're shared infrastructure. The ecosystem-level rationale lives in `${CLAUDE_PLUGIN_ROOT}/references/shared/pev-rationale.md` and `${CLAUDE_PLUGIN_ROOT}/references/shared/skill-conventions.md`.
-
-**Why this exists:** As the authoring skill absorbs new authoring-side patterns (new primitive-audit checklist items, new CSS / token / lifecycle rules, new shell-cluster decompositions, new module-promotion observations, new LLM-bridge defaults, new anti-patterns), each absorption was previously a one-off improvisation. This protocol gives every future "make sure `adia-ui-authoring` knows about [pattern]" request a deterministic landing path.
-
-**Used by:** the `adia-ui-authoring` skill, when an agent receives one of the trigger phrases below. SKILL.md §Teach is the seed; this file is the binding procedure.
-
-- "make sure `adia-ui-authoring` knows about [the new primitive contract / token rule / shell pattern]"
-- "train `adia-ui-authoring` on [the new lifecycle rule / module-promotion observation]"
-- "the skill should know about [the new CSS pattern from ADR-NNNN]"
-- "absorb this authoring-pattern into adia-ui-authoring"
-- "teach the skill about [the new LLM-bridge default / the new anti-pattern]"
-- "[a FEEDBACK item resolved with this fix] — make sure the skill reflects it"
-
-**Companion:** the `§SelfAudit` section + `scripts/audit-authoring-roster.mjs` (run after any §Teach landing to verify the mechanized axes hold — manifest / reference graph / capability-menu drift / authoring-roster currency), and [authoring-cycle.md](authoring-cycle.md) (the 5-step canonical procedure — §Teach landings near it should preserve its structure).
-
-**Anti-companion:** the repo's dated journal (`docs/journal/YYYY/MM/<date>.md`) — one-off authoring debug stories, "how I caught the lifecycle leak today" arc stories belong there, NOT in the skill (see Branch H below).
-
----
-
-## When to Use
-
-Trigger phrases (mirrored from the SKILL.md §Teach section):
-
-- "make sure `adia-ui-authoring` knows about X"
-- "train the skill on X"
-- "teach the skill about Y"
-- "the skill should be aware of Z"
-- "absorb [pattern / lesson / FEEDBACK resolution] into adia-ui-authoring"
-- "update the skill to reflect [the new ADR / the resolved contract bug / the new shell pattern]"
-
-This protocol applies when **another agent in the codebase** (substrate author, kanban worker, peer skill author) hands the authoring skill new knowledge to integrate. It does NOT apply when:
-
-- You're authoring a NEW primitive right now (use mode 1 / [primitive-audit.md](primitive-audit.md) + [authoring-cycle.md](authoring-cycle.md))
-- You're modifying an existing primitive (use mode 2 / [authoring-cycle.md](authoring-cycle.md) step 2 onward)
-- You're running cleanup / archive sweeps (use §SelfAudit's hygiene-cut shape)
-
-The procedure below is the binding for skill-teach requests against `adia-ui-authoring`. Follow it in order. Each step has a stop-condition; do not skip ahead.
-
----
-
-## Core Principles
-
-1. **The skill is a citation layer, not a knowledge layer.** Per-component contracts live in `packages/web-components/components/*.yaml` (props, slots, decision rules, keywords, synonyms). ADR rationale lives in the repo's ADR set. The skill cites yaml tags + ADR numbers + contract-spec sections — it does NOT duplicate yaml prose or ADR rationale. When a §Teach landing's first instinct is "rewrite what `docs/specs/component-token-contract.md` says," stop: the substrate is the source of truth.
-2. **Reference files are the cold-start budget's safety valve.** New content > ~50 LOC of procedural detail belongs in `references/<topic>.md` and is cited from SKILL.md, not inlined. This keeps the cold-start surface small (the ColdStartTriage menu) and lets modes load only their declared bundles.
-3. **Triggers without binding sections are waste.** Adding keywords to `trigger:` without a corresponding section in SKILL.md (or referenced file) consumes activation budget for no payoff. Always pair the two.
-4. **Capability menu items must reach an actual mode.** The cold-start `§ColdStartTriage` table is the agent's mental model on bare activation. Lies in that table cost more than gaps.
-5. **Version bumps are PATCH for citations, MINOR for new sections, MAJOR for renames/removals.** Most §Teach landings here are PATCH (a new anti-pattern in [anti-patterns.md](anti-patterns.md), a new rule in [api-contract.md](api-contract.md)) or MINOR (a new mode, a new reference file). Never bundle MINOR with PATCH polish in one cut.
-6. **§SelfAudit is the receipt.** A §Teach landing isn't done until `node scripts/audit-authoring-roster.mjs --strict` runs clean. If the audit regresses, fix in the same cut.
-
----
-
-## The Decision Tree — where does new authoring knowledge land?
-
-Run this **before** any patch. The wrong landing target wastes effort and creates drift.
-
-```text
-Is the new fact a PER-COMPONENT contract (slot, prop, decision rule,
-keyword, synonym, a2ui.rule, default value)?
-  → YES: belongs in YAML SoT, not in the skill.
-         Open the component's `.yaml` file at
-         `packages/web-components/components/<name>/<name>.yaml`
-         (or `packages/web-modules/.../<name>.yaml`).
-         Add to the appropriate field; run `npm run build:components`
-         to regenerate sidecars + catalog. Skill cites by tag — it
-         doesn't need to change.
-         STOP HERE. Do not edit the skill.
-         (See Worked Example A below.)
-  → NO: continue.
-
-Is it a NEW AUTHORING RULE that belongs to the four-axis contract
-(props/attributes, CSS @scope/tokens, lifecycle, form-association)?
-  → YES: route to the appropriate mode-1/2 reference:
-           - prop naming / reflection / static properties → references/api-contract.md
-           - @scope / variants / modes / L3 tokens → references/css-patterns.md
-           - connected/disconnected / observers / listeners → references/lifecycle-patterns.md
-           - raw colors / chrome palette / data palette → references/token-contract.md
-           - general convention not fitting the above → references/code-style.md
-         Add cross-link from authoring-cycle.md Step 3 if the new
-         rule extends the non-negotiable list.
-         (See Worked Example B below.)
-
-Is it a NEW SHELL PATTERN — a new bespoke child concern, a 5th cluster
-candidate, a new state-as-attribute convention, or an ADR-0023 extension?
-  → YES: lands in references/shell-patterns.md (mode 3). Add to
-         the 4-concern decomposition heuristic if the concern is new;
-         add to the pitfall list if it's a failure mode; add to the
-         4-canonical-cluster table if it's a 5th instance.
-         (See Worked Example C below.)
-
-Is it a NEW MODULE-PROMOTION pattern — a new OD-NNN rule, a new
-cluster-placement consideration, a new phase or sweep technique?
-  → YES: lands in references/module-promotion.md (mode 4). The
-         5-phase arc is the spine; new ODs extend the "Two rules from
-         observed bugs" section. Add a worked-example reference if
-         the pattern is grounded in a real arc.
-         (See Worked Example D below.)
-
-Is it a NEW LLM-BRIDGE DEFAULT or extension procedure step?
-  → YES: lands in references/llm-bridge.md (mode 6). The 5 hard
-         rules are the spine; new rules extend that list. The
-         "add a 4th provider" 8-step procedure extends if a new
-         provider class (passthrough proxy, smart proxy, hybrid)
-         needs documenting.
-         (See Worked Example E below.)
-
-Is it a NEW ANTI-PATTERN or WORKED EXAMPLE?
-  → YES: lands in references/anti-patterns.md (failure-mode
-         catalogue) OR references/worked-example.md (positive
-         example). Anti-patterns get the AP-N## label form
-         (AP-N## for new-component AP, AP-T## for token AP, etc.).
-         Worked examples mirror the badge-ui / counter-ui shape.
-         (See Worked Example F below.)
-
-Is it a METHODOLOGY / POSTURE shift — a new cold-start mode, a new
-§SelfAudit axis, a new architectural principle (§FirstPrinciples
-extension)?
-  → YES: lands INLINE in SKILL.md (the procedural spine). These
-         shape every mode: §Mission, §ColdStartTriage, §Posture,
-         §LoadingProtocol, §FirstPrinciples, §Plan-Execute-Verify,
-         §SelfAudit, §FileMap. They're allowed to grow because they
-         shape every other section. Run §SelfAudit immediately to
-         confirm the cold-start budget held.
-         (See Worked Example G below.)
-
-Is it a one-off AUTHORING ARC STORY, debug session, or LESSON LEARNED
-for a specific component (one-off fix, journal-worthy)?
-  → NO landing in the skill. It belongs in docs/journal/YYYY/MM/<date>.md
-    where future archeology will find it (per the repo's journal
-    discipline). The GENERALIZED rule extracted from the arc may
-    graduate to the skill via one of the branches above, but the
-    cycle-specific story stays in the journal.
-    Skipping the skill is a FEATURE, not a gap.
-    (See Worked Example H — the negative case.)
-```
-
----
-
-## The Five-Step Landing Procedure
-
-After the decision tree picks a target, follow these steps in order:
-
-### Step 1 — Audit before patching
-
-Before writing anything:
-
-1. **Read the target file in full.** Don't skim. The authoring-skill reference files have established voice + section ordering; patches must match.
-2. **`git status` + `git log -5`** on the working tree. Confirm no peer activity in the skill directory (peer agents may be authoring sibling skills like **adia-ui-release** or the consumer-side composition skill). If a peer is dirty here, halt + coordinate.
-3. **Grep for existing coverage.** Run `grep -rn "<keyword>" skills/adia-ui-authoring/` to confirm the new knowledge isn't already partly covered. If it IS, the landing is a _patch + augment_, not a _new section_.
-4. **Confirm the landing-target choice.** Re-read the Decision Tree above against your specific case. Two minutes of "is this really a CSS pattern, or is it actually a lifecycle rule?" prevents two hours of misplaced content.
-
-### Step 2 — Author the patch
-
-Two shapes depending on Step 1's grep:
-
-#### Shape A — NEW section / file (no existing coverage)
-
-If the target is a new reference file: create `references/<topic>.md` with the canonical header (provenance, why-authored, used-by, companion, anti-companion), then "## When to Use", "## Core Principles", then content. Reference from SKILL.md §FileMap + §ColdStartTriage if it opens a new mode.
-
-If the target is a new H2 inside an existing reference (most common for authoring-skill §Teach): find the semantically correct insertion point. E.g., a new lifecycle rule goes in `lifecycle-patterns.md` near related rules, not at the file's end. A new anti-pattern goes in `anti-patterns.md` under its axis (AP-N## / AP-T## / AP-S## / AP-L##).
-
-#### Shape B — AUGMENT existing section (grep found partial coverage)
-
-Read the entire existing section first, including any cross-references to other files. Author the augment as a sub-section or inline paragraph at the _semantically correct place_, not the end. If the augment changes the meaning of nearby paragraphs, edit those too — don't leave stale claims standing.
-
-### Step 3 — Wire the activation surface
-
-For any §Teach landing that should be discoverable:
-
-1. **Add trigger keywords to `description:` in the frontmatter** if the new knowledge introduces a vocabulary the existing trigger phrases don't cover. Pick 1-3 phrases an operator would naturally say (e.g. "validate primitive contract", "audit token consumption").
-2. **Add a capability menu entry** in §ColdStartTriage ONLY if the new content opens a new mode. Most §Teach landings extend existing modes 1-6; they don't create new ones.
-3. **Add a binding-procedure line** in §LoadingProtocol or §Plan-Execute-Verify only if the new section must run in a specific phase. Most don't (default LLM behavior is "scan cold-start menu → match → jump").
-
-If the landing is a new reference file, the SKILL.md edits are minimal — just the §FileMap row + a §ColdStartTriage row if it warrants one.
-
-### Step 4 — Version + CHANGELOG
-
-Cut the new content as a release:
-
-- **PATCH (vN.M.x+1)** — citation strengthening, typo fixes, augmenting an existing section with one paragraph, new anti-pattern entry, new rule in api-contract / css-patterns / lifecycle-patterns.
-- **MINOR (vN.M+1.0)** — new reference file, new H2 section in SKILL.md, new cold-start mode with binding, new §SelfAudit axis.
-- **MAJOR (vN+1.0.0)** — renames, removals, restructuring (don't bundle with adds).
-
-Update `skill.json` version + `CHANGELOG.md` entry. The entry must name:
-
-- What was added (one-line summary)
-- Where it lives (file path + section anchor)
-- What triggers it (1-3 phrases from the trigger keywords)
-- What it replaces / supersedes (if anything)
-
-### Step 5 — Verify with §SelfAudit
-
-Run the audit:
-
-```bash
-node scripts/audit-authoring-roster.mjs --strict
-```
-
-Mechanized axes are checked: manifest enforcement (skill.json vs on-disk), reference graph (all intra-skill links resolve), capability-menu drift (every mode points to an existing reference), authoring-roster currency (every absorbed-skill has a redirect or correct absence). The manual-review axes (token economy, content currency, cold-start path weight, fence-leak, CLI helper currency) need eyeballing — see `${CLAUDE_PLUGIN_ROOT}/references/shared/skill-conventions.md`.
-
-If the audit regresses, **fix in the same cut**. Don't defer hygiene-debt; it compounds.
-
----
-
-## Worked Examples
-
-### Example A — Per-component yaml fact (NOT a skill landing)
-
-**Request:** "make sure adia-ui-authoring knows that `<rating-ui>` defaults to `count=5` and supports half-star precision via `step=0.5`."
-
-**Decision tree:** Per-component contract (default value + prop semantics). → **YAML SoT, not skill.**
-
-**Action:**
-
-```bash
-# Open the yaml
-$EDITOR packages/web-components/components/rating/rating.yaml
-
-# Update props section with default + step values + a2ui.rule
-# Run regen
-npm run build:components
-npm run verify:components   # "clean — N files up-to-date"
-```
-
-**No skill edits required.** The skill cites `<rating-ui>` by tag in `code-style.md`'s primitive examples; the yaml propagates through the catalog automatically.
-
-**Pitfall to avoid:** "While I'm in the skill, let me add a paragraph about rating-ui in `code-style.md`." NO. That paragraph would duplicate the yaml SoT and drift on the next yaml change. Skill cites the tag; doesn't describe its contract.
-
-### Example B — New authoring rule (four-axis contract extension)
-
-**Request:** "train adia-ui-authoring on the new rule: state-bearing Booleans MUST also reflect to attribute via `reflect: true` so CSS `:scope[disabled]` selectors fire."
-
-**Decision tree:** New authoring rule, axis = API contract (reflection). → **references/api-contract.md**.
-
-**Action:**
-
-1. Open `api-contract.md`. Find the section on `static properties` declarations.
-2. Add a new rule entry: rule body + rationale + example showing right vs wrong.
-3. If the rule replaces a previous looser claim, edit that claim too — don't leave stale guidance standing.
-4. Cross-link from `authoring-cycle.md` Step 3 (the non-negotiable rules list) if it's a hard rule.
-5. PATCH bump (`vN.M.x+1`) — augmenting existing reference.
-
-### Example C — New shell pattern
-
-**Request:** "absorb the new `<docs-shell>` decomposition pattern (5th cluster after admin/chat/editor/simple)."
-
-**Decision tree:** New shell pattern. → **references/shell-patterns.md** (mode 3).
-
-**Action:**
-
-1. Open `shell-patterns.md`. Find the "Examples — 4 canonical clusters" section.
-2. Add a 5th example block: `<docs-shell>` family (JS-bearing + CSS-only children), CSS bridge file, tests, replication notes.
-3. Update the compounding-insight table with a 5th row (build time, notes).
-4. If the new cluster surfaces a 16th pitfall, append to the pitfall list (numbered, not bullets).
-5. PATCH bump (augmenting existing reference).
-
-### Example D — New module-promotion observation
-
-**Request:** "OD-004 — when the promoted module owns a popover, the consumer's existing popover-trigger button must move INTO the module's [data-trigger] slot, not stay outside; otherwise the popover-trigger binding silently breaks."
-
-**Decision tree:** New module-promotion observation. → **references/module-promotion.md** (mode 4), "Two rules from observed bugs" → "Three rules" (now 4).
-
-**Action:**
-
-1. Open `module-promotion.md`. Find the OD-002 + OD-003 section.
-2. Add OD-004 as a new H3 with: pattern (the failure mode), recipe (the fix), example (the real arc that surfaced it).
-3. Update the section heading from "Two rules" → "Four rules" (or generalize to "rules from observed bugs").
-4. PATCH bump.
-
-**Pitfall to avoid:** Authoring OD-004 in `worked-example.md` instead. The OD-NNN labels belong in `module-promotion.md` where the matrix of observation rules lives.
-
-### Example E — New LLM-bridge rule
-
-**Request:** "make sure adia-ui-authoring knows about Rule 6 — providers with native function-calling must not be wrapped with the json-mode fallback; the bridge auto-detects via `MODELS.<provider>.supportsTools`."
-
-**Decision tree:** New LLM-bridge default. → **references/llm-bridge.md** (mode 6), "Hard rules — defaults that bit us" extends.
-
-**Action:**
-
-1. Open `llm-bridge.md`. Find the "Rule 1 / 2 / 3 / 4 / 5" section.
-2. Add Rule 6 in the same H3 form: rule body + rationale + example (provider list affected).
-3. If the rule affects the 8-step "How to add a 4th provider" procedure, update step 1 (adapter file) and step 4 (models.js) to reference the new constraint.
-4. PATCH bump.
-
-### Example F — New anti-pattern
-
-**Request:** "AP-T07 — using `color: var(--a-fg)` inside a `:scope[variant="accent"]` body bypasses the L3 cascade (should be `--a-accent-fg-hover` etc); we saw this in `tag-ui`."
-
-**Decision tree:** New anti-pattern, axis T (token contract). → **references/anti-patterns.md**.
-
-**Action:**
-
-1. Open `anti-patterns.md`. Find the AP-T section (token contract).
-2. Add AP-T07 as a new entry: failure mode + symptom + fix + file:line where the bug was found.
-3. Cross-link from `token-contract.md` if the rule maps to a documented audit step.
-4. Cross-link from `code-style.md` § "Tokens, never raw colors" if it extends that section.
-5. PATCH bump.
-
-**Pitfall to avoid:** Authoring AP-T07 only in `token-contract.md`. The canonical home for anti-patterns is `anti-patterns.md` — that's where the catalogue lives. Other references cite the AP-NN label.
-
-### Example G — Methodology / posture (inline)
-
-**Request:** "we should add a §FirstPrinciples #6: 'Light-DOM positioning is by CSS rule, never by slot' — slot= attributes are decorative metadata per ADR-0033. The retraction lesson generalizes."
-
-**Decision tree:** New first-principle. → **INLINE in SKILL.md §FirstPrinciples**.
-
-**Action:**
-
-1. Open `skills/adia-ui-authoring/SKILL.md` §FirstPrinciples.
-2. Add the new principle as #6 with: principle body + rationale + ADR cross-reference + cite-by-tag of the retraction.
-3. MINOR bump (new first-principle = new procedural commitment).
-4. Run §SelfAudit immediately — confirm the cold-start budget held (the new principle adds maybe 50 lines).
-
-**Why inline, not reference file:** §FirstPrinciples is the procedural spine. Reference-extracting it would mean agents miss it on cold-start. It's allowed to grow.
-
-### Example H — One-off arc story (the NEGATIVE case)
-
-**Request:** "the skill should remember the author-from-scratch bug — a peer landed source under [Unreleased] but no release commit; I had to do a mode-2 cycle 'from scratch'. Make sure adia-ui-authoring knows about it."
-
-**Decision tree:** This is a RELEASE-cycle arc, not an AUTHORING-cycle arc. → **wrong skill entirely — should be the adia-ui-release skill's recovery-paths reference, NOT adia-ui-authoring.**
-
-**Action:**
-
-1. Route to the **adia-ui-release** skill's recovery-paths reference instead.
-2. **Do nothing in adia-ui-authoring.** This is anti-pattern 7 (one-way thinking) avoided.
-
-**Counter-example** (a genuine NEGATIVE case for authoring):
-
-**Request:** "the skill should remember how I caught the `<rating-ui>` `reflect: true` missing bug today — grep'd for `reflect: true` in `static properties` arrays, found 3 components missing it, fixed all 3 in one PR."
-
-**Decision tree:** One-off authoring arc story / specific debug session. → **`docs/journal/YYYY/MM/<date>.md`, NOT the skill.**
-
-**Action:**
-
-1. Write the journal entry under §N — the arc.
-2. The GENERALIZED rule extracted ("state-bearing Booleans need `reflect: true`") may already be in `api-contract.md` (Example B above). If so, no skill change needed. If not, that's a Branch B landing — separate arc.
-3. **Do nothing else in the skill.** The skill teaches the agent what to do; the journal records what happened.
-
-**Pitfall to avoid:** "But the skill should know about every important arc!" NO. Conflating procedural ("what to do") with historical ("what happened") bloats the skill and rots the journal.
-
----
-
-## Anti-patterns (the §Teach landing failure modes)
-
-These are universal across extensible skills. Each one was observed during sibling-skill §Teach rollouts.
-
-### Anti-pattern 1 — "Append-only" landing
-
-Adding new content to the end of an existing reference without integrating it. Symptom: `anti-patterns.md` grows monotonically; new APs pile under no axis header; cross-references go stale.
-
-**Fix:** When augmenting a reference, find the _semantically correct insertion point_. APs go under their axis section. Lifecycle rules go near related rules in `lifecycle-patterns.md`. Don't pile at file ends.
-
-### Anti-pattern 2 — Duplicating substrate facts
-
-Adding what `packages/web-components/components/<name>/<name>.yaml` already says as prose in the skill. Symptom: the skill paragraph and the yaml `description` say the same thing in different words; the next yaml edit drifts the skill.
-
-**Fix:** When you catch yourself writing "the `<X-ui>` component does Y", check — is this really in the yaml? If yes, cite by tag. Skill cites; doesn't describe.
-
-### Anti-pattern 3 — Trigger keywords without binding
-
-Adding phrases to `description:` for content that doesn't exist yet, or that exists but has no procedural binding. Symptom: agent activates the skill on the keyword, then has no procedure to follow.
-
-**Fix:** Pair the keyword add with the section authoring in the SAME cut. Never bump the version with orphan triggers.
-
-### Anti-pattern 4 — Capability menu lies
-
-Adding a §ColdStartTriage row pointing to a section that doesn't exist or to a stub. Symptom: agent reads the menu, picks the row, jumps to the reference, finds nothing actionable.
-
-**Fix:** §ColdStartTriage entries are the cold-start surface — load-bearing. Treat each new row as a contract that the underlying reference MUST deliver. If you're not ready to write the section, don't add the row yet.
-
-### Anti-pattern 5 — Bundling MINOR + PATCH in one cut
-
-Shipping a new §SelfAudit axis (MINOR) alongside three citation-strengthening edits to `anti-patterns.md` (PATCH) in a single `vN.M+1.0` cut. Symptom: the CHANGELOG entry is unclear; consumers can't tell what the new behavior is.
-
-**Fix:** Cut the MINOR first (with just the new axis). Cut the PATCH after (with the polish). Each cut has a clean intent.
-
-### Anti-pattern 6 — Hygiene-debt deferral
-
-Landing a new section, observing that `audit-authoring-roster.mjs --strict` shows axis regression, and deferring the fix. Symptom: the next cut has a different focus; the hygiene-debt is forgotten; six cuts later the skill has 30+ unresolved references in the manifest.
-
-**Fix:** Fix axis regressions IN THE SAME CUT as the §Teach landing. Hygiene-debt compounds.
-
-### Anti-pattern 7 — Treating §Teach as one-way
-
-Receiving a §Teach request and landing the content without asking "should this be in `adia-ui-authoring`, or in the consumer-side composition skill (composition recipes) / **adia-ui-release** (release-cycle patterns) / **adia-ui-a2ui** (generator internals) / an incident-postmortem skill (incident write-ups)?" Symptom: the authoring skill absorbs content that semantically belongs in a sibling, blowing past the cold-start budget while leaving the sibling thin.
-
-**Fix:** Before landing here, ask: is there a sibling skill for this domain? The consumer-side composition skill (in the adia-ui-factory plugin) owns 3rd-party composition; **adia-ui-release** owns the release cycle; **adia-ui-a2ui** owns generator + corpus internals; an incident-postmortem skill owns incident write-ups; a deployment-ops skill owns long-running VM ops. The authoring skill owns the four-axis contract for code inside the monorepo, not adjacent concerns. Example H above demonstrates the routing decision.
-
----
-
-## Cross-references
-
-- **§Mission** (`SKILL.md`) — defines the authoring-engineer posture. §Teach is a narrower lane.
-- **§SelfAudit** (`SKILL.md`) + **`scripts/audit-authoring-roster.mjs`** — the audit gate that catches §Teach landing regressions. Always run after.
-- **§LoadingProtocol** (`SKILL.md`) — defines the reference-file extraction discipline. §Teach respects it by routing content > ~50 LOC to `references/`.
-- **§ColdStartTriage** (`SKILL.md`) — the mode cold-start menu. §Teach lands in mode 7.
-- `${CLAUDE_PLUGIN_ROOT}/references/shared/skill-conventions.md` + `${CLAUDE_PLUGIN_ROOT}/references/shared/pev-rationale.md` — the shared infrastructure motivating §Teach and PEV across the forge family.
-- the **adia-ui-release** skill's `teach-protocol.md` — a sibling instantiation. Universal sections vendored here.
-- the repo's AGENTS.md — defines journal + audit-history disciplines that §Teach defers to for arc stories.
-
----
-
-## Worked Decision Examples — Quick-Reference Card
-
-When in doubt, the table below routes by request shape.
-
-| Request shape | Landing target | Version bump | Audit gate |
-| --- | --- | --- | --- |
-| "new primitive contract / yaml fact" | yaml SoT only (no skill change) | yaml change only | `npm run verify:components` |
-| "new prop reflection / attribute mapping rule" | references/api-contract.md | PATCH | `audit-authoring-roster.mjs` |
-| "new @scope / variant-vs-mode / L3 token rule" | references/css-patterns.md or token-contract.md | PATCH | `audit-authoring-roster.mjs` |
-| "new lifecycle rule (observer / listener / cleanup)" | references/lifecycle-patterns.md | PATCH | `audit-authoring-roster.mjs` |
-| "new shell pattern / 5th cluster / state-as-attr" | references/shell-patterns.md | PATCH | `audit-authoring-roster.mjs` |
-| "new OD-NNN module-promotion rule" | references/module-promotion.md | PATCH | `audit-authoring-roster.mjs` |
-| "new LLM-bridge default / Rule N+1" | references/llm-bridge.md | PATCH | `audit-authoring-roster.mjs` |
-| "new anti-pattern (AP-N## / AP-T## / AP-S## / AP-L##)" | references/anti-patterns.md | PATCH | `audit-authoring-roster.mjs` |
-| "new worked example (badge-ui / counter-ui shape)" | references/worked-example.md | PATCH | `audit-authoring-roster.mjs` |
-| "new general convention / code style" | references/code-style.md | PATCH | `audit-authoring-roster.mjs` |
-| "new first-principle / cold-start mode / §SelfAudit axis" | inline in SKILL.md | MINOR | `audit-authoring-roster.mjs` after |
-| "one-off authoring arc / debug session" | `docs/journal/YYYY/MM/<date>.md` (NOT skill) | n/a | journal-date hook |
-| "release-cycle pattern" | route to adia-ui-release (NOT this skill) | varies | peer review |
-| "3rd-party composition recipe" | route to the adia-ui-factory plugin (NOT this skill) | varies | peer review |
-| "A2UI corpus / generator internals" | route to adia-ui-a2ui (NOT this skill) | varies | peer review |
-
----
-
-When new landing-target patterns emerge that don't fit the 8 branches above, augment this file's decision tree + worked examples in the same arc as the landing.

package/skills/adia-ui-authoring/scripts/audit-authoring-roster.mjs

@@ -1,148 +0,0 @@
-#!/usr/bin/env node
-// audit-authoring-roster.mjs — §SelfAudit enforcement for adia-ui-authoring.
-// Universal axes via the shared audit-axes lib; plus a skill-specific
-// absorbed-skill roster-currency axis.
-//
-// Usage (from anywhere):
-//   node scripts/audit-authoring-roster.mjs
-//   node scripts/audit-authoring-roster.mjs --json
-//   node scripts/audit-authoring-roster.mjs --strict
-//
-// Resolves the shared lib via ${CLAUDE_PLUGIN_ROOT}/bin/lib/audit-axes.mjs,
-// with a fallback relative to this script (skills/<name>/scripts → bin/lib).
-
-import fs from 'node:fs';
-import path from 'node:path';
-import process from 'node:process';
-import { fileURLToPath, pathToFileURL } from 'node:url';
-
-const __dirname = path.dirname(fileURLToPath(import.meta.url));
-const SKILL_DIR = path.resolve(__dirname, '..');            // skills/adia-ui-authoring
-const SKILLS_ROOT = path.resolve(SKILL_DIR, '..');          // skills/
-const PLUGIN_ROOT = process.env.CLAUDE_PLUGIN_ROOT
-  ? path.resolve(process.env.CLAUDE_PLUGIN_ROOT)
-  : path.resolve(SKILL_DIR, '..', '..');                    // plugin root
-
-const SKILL_MD = path.join(SKILL_DIR, 'SKILL.md');
-const SKILL_JSON = path.join(SKILL_DIR, 'skill.json');
-
-// Resolve the shared audit-axes library from the plugin root, falling back
-// to the script-relative location if the env var isn't set.
-const auditAxesPath = (() => {
-  const fromEnv = path.join(PLUGIN_ROOT, 'bin', 'lib', 'audit-axes.mjs');
-  if (fs.existsSync(fromEnv)) return fromEnv;
-  return path.resolve(__dirname, '..', '..', '..', 'bin', 'lib', 'audit-axes.mjs');
-})();
-
-const { runUniversalAxes, formatResults } = await import(pathToFileURL(auditAxesPath).href);
-
-// [name, expected-redirect-path or null if already-gone]. The legacy
-// skills these absorbed were never carried into this plugin, so every
-// entry is expected to be absorbed-clean (no directory present).
-const ABSORBED = [
-  ['primitive-audit',            null],
-  ['component-token-audit',      null],
-  ['llm-bridge-extension',       null],
-  ['adia-ui-code-bestpractices', null],
-  ['bespoke-shell-children',     null],
-  ['promote-inline-to-module',   null],
-];
-
-const CLEAN_STATUSES = ['absorbed-clean', 'absorbed-clean-deleted', 'redirect-ok'];
-
-function parseArgs(argv) {
-  if (argv.includes('--help') || argv.includes('-h')) {
-    console.log(`audit-authoring-roster.mjs — adia-ui-authoring §SelfAudit.
-
-USAGE
-  node scripts/audit-authoring-roster.mjs [--json] [--strict]
-
-FLAGS
-  --json     Emit findings as JSON instead of human text
-  --strict   Exit 1 on any drifting axis
-  --help     Show this help
-
-AXES (universal axes from \${CLAUDE_PLUGIN_ROOT}/bin/lib/audit-axes.mjs)
-  1  Manifest enforcement     — skill.json files[] matches disk (recursive)
-  2  Reference graph          — every markdown link inside SKILL.md resolves
-  3  Capability-menu drift    — every §ColdStartTriage row's entry reference exists
-  4  Version-literal parity   — SKILL.md frontmatter version matches skill.json
-  5  Phase-label absence      — no stale Phase N annotations in skill prose
-  6  Fence-leak detection     — no orphan fence markers
-  7  Content currency         — references cited by skill.json exist on disk
-  8  CLI helper currency      — npm scripts cited by SKILL.md (skips substrate-only)
-
-  9  Authoring-roster currency (skill-specific) — every absorbed skill has a
-     redirect SKILL.md at the expected path or is absorbed-clean (no directory).
-
-EXIT CODES
-  0   All axes clean
-  1   At least one axis drifting (with --strict)
-`);
-    process.exit(0);
-  }
-  return { json: argv.includes('--json'), strict: argv.includes('--strict') };
-}
-
-function axis9_authoringRosterCurrency() {
-  const findings = [];
-  for (const [name, redirectPath] of ABSORBED) {
-    if (redirectPath === null) {
-      const dir = path.join(SKILLS_ROOT, name);
-      if (fs.existsSync(dir)) {
-        findings.push({ type: 'unexpected-directory', message: `${name}/ exists but was claimed absorbed-and-gone`, name });
-      } else {
-        findings.push({ type: 'absorbed-clean', message: `${name}: no directory — correct`, name });
-      }
-    } else {
-      const full = path.join(PLUGIN_ROOT, redirectPath);
-      if (!fs.existsSync(full)) {
-        const dir = path.dirname(full);
-        findings.push({
-          type: fs.existsSync(dir) ? 'redirect-missing' : 'absorbed-clean-deleted',
-          message: fs.existsSync(dir)
-            ? `${name}: expected redirect at ${redirectPath} — not found`
-            : `${name}: fully deleted post-soak`,
-          name,
-        });
-      } else {
-        const txt = fs.readFileSync(full, 'utf8');
-        findings.push(
-          /status:\s*redirect/m.test(txt)
-            ? { type: 'redirect-ok', message: `${name}: redirect ok`, name }
-            : { type: 'redirect-not-tagged', message: `${name}: ${redirectPath} lacks 'status: redirect'`, name }
-        );
-      }
-    }
-  }
-  const driftCount = findings.filter(f => !CLEAN_STATUSES.includes(f.type)).length;
-  return {
-    axis: 'authoringRosterCurrency',
-    axis_num: 9,
-    status: driftCount > 0 ? 'drift' : 'ok',
-    findings,
-    summary: driftCount > 0 ? `${driftCount} absorbed-skill issue(s)` : 'all absorbed-skill entries clean',
-  };
-}
-
-function main() {
-  const args = parseArgs(process.argv.slice(2));
-  const ctx = { skillDir: SKILL_DIR, skillMd: SKILL_MD, skillJson: SKILL_JSON, repoRoot: PLUGIN_ROOT };
-  const { results: universal } = runUniversalAxes(ctx);
-  const axis9 = axis9_authoringRosterCurrency();
-  const allResults = [...universal, axis9];
-  const driftCount = allResults.filter(r => r.status === 'drift').length;
-
-  if (args.json) {
-    console.log(JSON.stringify({ results: allResults, driftCount }, null, 2));
-    if (args.strict && driftCount > 0) process.exit(1);
-    return;
-  }
-
-  console.log(`[audit-authoring-roster] adia-ui-authoring §SelfAudit — ${driftCount} drifting axis/axes`);
-  console.log(formatResults(allResults));
-  if (driftCount === 0) console.log('\n✓ All clean.');
-  if (args.strict && driftCount > 0) process.exit(1);
-}
-
-main();

package/skills/adia-ui-authoring/skill.json

@@ -1,45 +0,0 @@
-{
-  "name": "adia-ui-authoring",
-  "version": "1.9.2",
-  "description": "Author or modify code INSIDE the adia-ui (@adia-ai) monorepo — primitives in packages/web-components/, composite shells in packages/web-modules/, inline page content promoted to reusable modules, composite/module demos (.examples.html, .contents.html), the @adia-ai/llm bridge, the trait catalog, .a2ui.json sidecars, yaml SoTs — clearing the four-axis contract before review and VERIFYING against the built/rendered artifact (build:components --verify, the primitive's demo page, the rendered-DOM probe), never 'looks done'. Use whenever the user wants to ADD A NEW PRIMITIVE / MODIFY A COMPONENT / FIX A YAML / PROMOTE INLINE TO MODULE / UPDATE A SHELL / AUTHOR A DEMO FOR A COMPOSITE OR MODULE / COMPOSE EXAMPLES.HTML / EXTEND THE LLM BRIDGE — the work happens on packages/* source, not on consumer code. Triggers on 'add a primitive', 'modify table-ui yaml', 'author a new web-module shell', 'trait catalog regenerated wrong', 'promote inline CSS to a module', 'audit the four-axis contract', '.a2ui.json sidecar is stale', 'set up LLM-bridge surface', 'author a demo for X', 'compose examples.html for Y', any edit under packages/web-modules/**/*.examples.html or **/*.contents.html. Does NOT trigger for: composing screens FROM existing primitives in consumer/app code (the adia-ui-factory plugin), cutting a release (adia-ui-release), generation-pipeline internals (adia-ui-a2ui), scoring generated UI quality (adia-ui-gen-review), broad cross-surface QA (adia-ui-dogfood). Absorbs primitive-audit + component-token-audit + code-bestpractices + bespoke-shell-children + promote-inline-to-module + llm-bridge-extension.",
-  "status": "stable",
-  "authors": ["kim.granlund"],
-  "codeowners": [],
-  "tags": ["adia-ui", "web-components", "web-modules", "design-system", "component-authoring", "tokens", "light-dom", "scope-css", "lifecycle", "form-associated", "shell-patterns", "inline-to-module", "llm-bridge", "composite-demo"],
-  "depends_on": [],
-  "peer_skills": ["adia-ui-release", "adia-ui-a2ui", "adia-ui-llm", "adia-ui-gen-review", "adia-ui-dogfood", "ui-audit-coherence", "analyze-css", "ui-build-components"],
-  "environment": {
-    "portable": false,
-    "requires": ["the adia-ui (@adia-ai) framework monorepo with packages/web-components/, packages/web-modules/, packages/llm/, packages/a2ui/, and the component-token-contract spec"],
-    "rationale": "Every mode operates on monorepo-specific source layout, build scripts, and the four-axis contract; it does not apply to consumer repos."
-  },
-  "files": [
-    "SKILL.md",
-    "CHANGELOG.md",
-    "skill.json",
-    "references/primitive-audit.md",
-    "references/authoring-cycle.md",
-    "references/code-style.md",
-    "references/api-contract.md",
-    "references/yaml-contract.md",
-    "references/css-patterns.md",
-    "references/lifecycle-patterns.md",
-    "references/shell-patterns.md",
-    "references/module-promotion.md",
-    "references/token-contract.md",
-    "references/llm-bridge.md",
-    "references/teach-protocol.md",
-    "references/composite-demo-protocol.md",
-    "references/canonical-pattern-index.md",
-    "references/common-gotchas.md",
-    "references/anti-patterns.md",
-    "references/worked-example.md",
-    "scripts/audit-authoring-roster.mjs",
-    "scripts/build-canonical-pattern-index.mjs",
-    "evals/routing-corpus.json",
-    "evals/adversarial-design-plan-gates.json",
-    "assets/case-studies/maxtokens-32768-discovery.md",
-    "assets/case-studies/admin-shell-decomposition.md",
-    "assets/case-studies/theme-panel-promotion.md"
-  ]
-}

package/skills/adia-ui-dogfood/CHANGELOG.md

@@ -1,17 +0,0 @@
-# Changelog — adia-ui-dogfood
-
-## [0.1.0] stable — 2026-06-03
-
-**MINOR** — first cut as a plugin skill. Ported from the framework monorepo's maintainer skill `dogfood-sweep`, renamed and de-repo'd: absolute paths stripped, shared-infra references rewritten to `${CLAUDE_PLUGIN_ROOT}/...`, the component visual probe bundled at `scripts/analyze.mjs` (repo-root resolved from `$ADIA_REPO_ROOT` / cwd, not a path relative to the install), instance data dropped. No procedural changes to the 6 modes.
-
-SKILL.md carries all 6 modes inline (component visual probe / app-shell QA / HTML typo sweep / native-primitive leak / admin-shell composition / component anatomy + card header), with a cold-start triage menu, §Plan-Execute-Verify, §SelfAudit, §Teach, and §FileMap added to match the rollup-family conventions. Modes 2 / 4 / 5 drive **repo-local** audit scripts that ship in the monorepo (`scripts/dev/audit-app-shells.mjs`, `audit-native-primitive-leak.mjs`, `audit-shell-composition.mjs`); modes 3 / 6 use inline shell snippets.
-
-### Reconstructed history (pre-port)
-
-- Added probe #6 (missing component CSS detection) to mode 1 after the swap-to-primitive-but-forget-the-link class slipped past a real PR. The bug class: an agent uses `<button-ui>` markup but forgets the `<link rel="stylesheet">` for the button component CSS; the element registers, the markup looks right, and the control renders unstyled.
-
-- Native-primitive-leak audit (mode 4) intent-marker detection window widened from 80 → 200 chars after a peer agent found that realistic preceding-line comments (indent + comment prefix + reason text + closing `-->` + newline) sat at exactly the 80-char boundary and were not detected.
-
-- Mode 6 (Component Anatomy + Card Header Sweep) added: card-ui `<header><div>` wrapper anti-pattern + missing anatomy sections per the anatomy-sweep gate's expectations.
-
-- Mode 1 (component visual probe via Chromium) was the initial skill. Modes 2–5 were absorbed from the substrate-side `scripts/dev/audit-*.mjs` work over multiple cycles. The skill grew its 6-mode catalog organically.