@amsterdamdatalabs/enact-extensions 0.1.37 → 0.1.47

package/extensions/enact-repo/skills/grill-me/SKILL.md

@@ -0,0 +1,20 @@
+---
+name: grill-me
+description: A relentless interview to sharpen a plan or design.
+disable-model-invocation: true
+---
+
+# Grill Me
+
+## Use When
+
+- The user wants a plan or design interrogated and sharpened through a relentless interview.
+
+## Do Not Use When
+
+- The user also wants ADRs and glossary entries captured as decisions crystallize — use `grill-with-docs` instead.
+- The user wants execution, not interrogation — use `implement`.
+
+## Process
+
+Run a `/grilling` session.

package/extensions/enact-repo/skills/grill-with-docs/SKILL.md

@@ -0,0 +1,20 @@
+---
+name: grill-with-docs
+description: A relentless interview to sharpen a plan or design, which also creates docs (ADR's and glossary) as we go.
+disable-model-invocation: true
+---
+
+# Grill With Docs
+
+## Use When
+
+- The user wants a plan or design interrogated and sharpened, with ADRs and glossary entries captured as decisions crystallize.
+
+## Do Not Use When
+
+- The user wants the interview without any documentation side effects — use `grill-me` instead.
+- Nothing is being decided yet and the user just wants information gathered — use `research`.
+
+## Process
+
+Run a `/grilling` session, using the `domain-modeling` skill.

package/extensions/enact-repo/skills/handoff/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: handoff
+description: Compact the current conversation into a handoff document for another agent to pick up.
+disable-model-invocation: true
+---
+
+# Handoff
+
+## Use When
+
+- The user wants the current conversation compacted into a handoff document for another agent to continue the work.
+
+## Do Not Use When
+
+- The conversation is still active and the same agent will keep working on it — there is nothing to hand off yet.
+- The user wants a permanent project artifact (spec, ADR, glossary entry) rather than a session-transfer document — write directly to that artifact instead.
+
+## Process
+
+Write a handoff document summarising the current conversation so a fresh agent can continue the work. Save to the temporary directory of the user's OS - not the current workspace.
+
+Include a "suggested skills" section in the document, which suggests skills that the agent should invoke.
+
+Do not duplicate content already captured in other artifacts (specs, plans, ADRs, issues, commits, diffs). Reference them by path or URL instead.
+
+Redact any sensitive information, such as API keys, passwords, or personally identifiable information.
+
+If the user passed arguments, treat them as a description of what the next session will focus on and tailor the doc accordingly.

package/extensions/enact-repo/skills/http-contract-migration/SKILL.md

@@ -0,0 +1,74 @@
+---
+name: http-contract-migration
+description: Migrate one Enact HTTP operation through Rust wire fidelity, utoipa annotations, enact-app OpenApiRouter composition, generated OpenAPI TypeScript/Zod, and desktop or mobile runtime validation. Use for route adoption or replacing handwritten frontend wire contracts; use atlas-contract-generation for full regeneration.
+disable-model-invocation: false
+---
+
+# HTTP contract migration
+
+Migrate one vertical operation at a time: producer serialization, runtime
+route, OpenAPI operation, generated artifacts, transport validation, consumer
+projection, and focused evidence land together.
+
+Coverage, blockers, pass counts, and migration order belong in the active
+rollout plan. This skill contains only the repeatable method.
+
+## Use When
+
+Adopting or replacing one HTTP route's wire contract end to end — Rust
+serialization, utoipa annotation, enact-app router composition, generated
+OpenAPI/TypeScript/Zod, and desktop or mobile consumer validation for that
+single operation.
+
+## Do Not Use When
+
+Regenerating the full OpenAPI surface rather than migrating one operation —
+use `atlas-contract-generation`. Deciding rollout order, tracking coverage, or
+resolving a blocker across many operations — that belongs in the active
+rollout plan, not this skill.
+
+## Reverify before changing code
+
+1. Run git status and preserve concurrent work.
+2. Run crg status; use graph results only when branch and commit match.
+3. Read the production router, handler, request and response types,
+   enact-app/src/openapi.rs, generated OpenAPI, affected transport, and every
+   desktop/mobile consumer.
+4. Read the active plan for ownership and current coverage.
+5. Classify each claim as source-verified, command-verified, or unproven.
+
+Do not infer gate phase placement, route coverage, or compatibility policy from
+screenshots, comments, generated counts, or this skill.
+
+## Method
+
+Work through each phase in order; each links to its full reference.
+
+1. [Hexagonal boundary](references/hexagonal-boundary.md) — who owns DTOs,
+   handlers, composition, and utoipa-axum.
+2. [Wire fidelity and DTO direction](references/wire-fidelity-and-dto.md) —
+   prove serde behavior before generating; keep DTOs minimal and reviewed.
+3. [Publication and frontend adoption](references/publication-and-adoption.md)
+   — expose the route, regenerate artifacts, and bind the frontend to the
+   generated operation.
+4. [Compatibility and gate responsibilities](references/compatibility-and-gates.md)
+   — the deployment/version policy migration tests must enforce, and which
+   proof belongs to which gate.
+
+## Verification
+
+Run from the repository root, substituting the affected domain:
+
+    just schema::http-api-check
+    just schema::contracts-check
+    bash workflows/scripts/gates/db/contracts-stale.sh
+    just backend::_cargo check --locked -p enact-app -p enact-<domain>
+    just backend test-batch -p enact-<domain>
+    just frontend fmt-check
+    just frontend lint
+    just frontend typecheck
+    just frontend mobile-typecheck
+
+Also run the exact composition, serialization, transport parsing, and consumer
+tests for the migrated operation. Report focused and full-estate validation
+separately.

package/extensions/enact-repo/skills/http-contract-migration/references/compatibility-and-gates.md

@@ -0,0 +1,26 @@
+# Compatibility and gate responsibilities
+
+## Compatibility
+
+Read the generator's unknown-field policy and active compatibility decision
+before migration. Strict response parsing must be paired with an explicit
+deployment policy, breaking-OpenAPI comparison, and supported client/server
+version tests. This skill does not decide whether additive fields are
+compatible; the active architecture/plan does, and migration tests must enforce
+that decision.
+
+Desktop and mobile release skew exists even when both live in one repository.
+
+## Gate responsibilities
+
+Keep these proofs separate:
+
+- contract freshness reproduces generated artifacts;
+- exposure control rejects unapproved public schemas and operations;
+- composition tests couple runtime method/path topology to OpenAPI;
+- adoption checks reject handwritten mirrors and unvalidated migrated calls;
+- compatibility checks compare supported API versions;
+- live smoke tests prove a deployed producer and real consumer interoperate.
+
+Before claiming a gate is live, verify its executable engine, profile trigger
+coverage, positive and clean fixtures, and a genuine failing test.

package/extensions/enact-repo/skills/http-contract-migration/references/hexagonal-boundary.md

@@ -0,0 +1,16 @@
+# Hexagonal boundary
+
+- enact-api-types owns serialized wire DTOs. It may use utoipa, never Axum or
+  utoipa-axum.
+- A domain inbound adapter owns Axum handlers and co-located utoipa path
+  annotations. A domain may use utoipa, never utoipa-axum.
+- enact-app is the composition owner and the only utoipa-axum user.
+- Each per-domain OpenApiRouter<State> fragment feeds both production routing
+  and OpenAPI export through split_for_parts().
+- Group handlers in one routes! invocation only when they share the exact path
+  and use distinct methods.
+
+Deployment-conditional operations require an explicit publication policy. A
+common generated client may contain only operations served by every target
+deployment; variant-only operations need a separate documented surface or must
+remain unavailable to that client.

package/extensions/enact-repo/skills/http-contract-migration/references/publication-and-adoption.md

@@ -0,0 +1,31 @@
+# Publication and frontend adoption
+
+## Publication and composition
+
+1. Add or correct ToSchema and the handler annotation.
+2. Add intentional public roots to
+   schema/contracts/http-dto-exposure.yaml.
+3. Add the handler to the composition-owned router fragment and use that
+   fragment for both runtime and export.
+4. Validate final route-reachable schemas against the exposure manifest.
+5. Regenerate OpenAPI, TypeScript, Zod, and package exports.
+6. Prove path and method coverage, not path-string presence alone.
+
+A generated component does not prove its route is public, served, or consumed.
+
+## Frontend adoption
+
+Bind the generated operation, not independent pieces:
+
+- method, path, path/query parameters, request body, success responses, error
+  responses, and status/content-type handling derive from one generated
+  operation contract;
+- untrusted JSON enters as unknown and is parsed immediately at the shared
+  transport boundary;
+- validate outgoing request bodies where the operation defines a schema;
+- import through @enact/schema, never a generated implementation file;
+- project parsed wire DTOs into UI models only after validation;
+- remove handwritten mirrors only after all consumers and focused tests move.
+
+Keep schema-aware and legacy transport helpers visibly distinct. A migrated
+operation must not use an unvalidated generic response cast.

package/extensions/enact-repo/skills/http-contract-migration/references/wire-fidelity-and-dto.md

@@ -0,0 +1,31 @@
+# Wire fidelity and DTO direction
+
+## Wire fidelity
+
+Before generating:
+
+- prove serde field names, flattening, tagging, defaults, omission, and null
+  behavior match ToSchema;
+- treat property presence separately from nullable values;
+- use typed enums instead of String when the wire has a closed value set;
+- document the actual success envelope, error envelope, status codes, content
+  types, auth, path/query parameters, and request body;
+- add serialization tests for ambiguous shapes and negative tests for missing,
+  extra, invalid, and legacy values.
+
+Do not manually copy a Rust fixture into TypeScript and call that parity.
+Either generate the fixture from Rust as test input or compare independently
+produced artifacts through a checked boundary.
+
+## DTO direction
+
+Use a dedicated operation DTO containing the minimum reviewed wire fields.
+
+- Persistence rows, secret-bearing runtime configuration, external provider
+  configuration, manifests, and UI view state are not endpoint DTOs.
+- Keep view models only for UI semantics such as normalized nulls, derived
+  labels, transient errors, or presentation state.
+- If consumers need classification absent from the wire DTO, add one narrowly
+  named reviewed field rather than casting to a broader manifest.
+- Normalize a legacy payload only for an explicitly supported compatibility
+  case, then parse it with the current generated schema.

package/extensions/enact-repo/skills/implement/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: implement
+description: "Implement a piece of work based on a spec or set of tickets."
+disable-model-invocation: true
+---
+
+# Implement
+
+## Use When
+
+- The user has a spec or set of tickets ready and wants the described work implemented.
+
+## Do Not Use When
+
+- There is no spec or ticket yet and the shape of the change is still an open question — use `research` or `prototype` first to settle it.
+- The request is to review already-implemented work rather than build new work — use `code-review`.
+
+## Process
+
+Implement the work described by the user in the spec or tickets.
+
+Use /tdd where possible, at pre-agreed seams.
+
+Run typechecking regularly, single test files regularly, and the full test suite once at the end.
+
+Once done, use /code-review to review the work.
+
+Commit your work to the current branch.

package/extensions/enact-repo/skills/improve-codebase-architecture/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: improve-codebase-architecture
+description: Scan a codebase for deepening opportunities, present them as a visual HTML report, then grill through whichever one you pick.
+disable-model-invocation: true
+---
+
+# Improve Codebase Architecture
+
+Surface architectural friction and propose **deepening opportunities** — refactors that turn shallow modules into deep ones. The aim is testability and AI-navigability.
+
+## Use When
+
+- The user wants the codebase scanned for architectural deepening opportunities, presented as a visual HTML report to choose from.
+
+## Do Not Use When
+
+- The user already knows which module to change and just wants it built — use `implement`.
+- The user wants to pin down domain terminology directly rather than scan for architecture — use `domain-modeling`.
+
+This command is _informed_ by the project's domain model and built on a shared design vocabulary:
+
+- Run the `/codebase-design` skill for the architecture vocabulary (**module**, **interface**, **depth**, **seam**, **adapter**, **reach**, **locality**) and its principles (the deletion test, "the interface is the test surface", "one adapter = hypothetical seam, two = real"). Use these terms exactly in every suggestion — don't drift into "component," "service," "API," or "boundary."
+- The domain language in `CONTEXT.md` gives names to good seams; ADRs in `docs/adr/` record decisions this command should not re-litigate.
+
+## Process
+
+### 1. Explore
+
+**Scope before you scan — YAGNI.** Deepening a module pays off by making future changes to it easier, so put extra weight on the parts of the codebase that have recently changed. Decide *where* to look before you look:
+
+- If the user named a direction — a module, a subsystem, a pain point — take it, and skip the inference below.
+- Otherwise, walk back a good stretch of the commit history (`git log --oneline`) to find the codebase's hot spots — the files and areas that keep coming up — and let those paths pull your attention first. If the changes are scattered with no clear hot spot, widen the net.
+
+Read the project's domain glossary (`CONTEXT.md`) and any ADRs in the area you're touching first.
+
+Then use the Agent tool with `subagent_type=Explore` to walk the codebase. Don't follow rigid heuristics — explore organically and note where you experience friction:
+
+- Where does understanding one concept require bouncing between many small modules?
+- Where are modules **shallow** — interface nearly as complex as the implementation?
+- Where have pure functions been extracted just for testability, but the real bugs hide in how they're called (no **locality**)?
+- Where do tightly-coupled modules leak across their seams?
+- Which parts of the codebase are untested, or hard to test through their current interface?
+
+Apply the **deletion test** to anything you suspect is shallow: would deleting it concentrate complexity, or just move it? A "yes, concentrates" is the signal you want.
+
+### 2. Present candidates as an HTML report
+
+Write a self-contained HTML file to the OS temp directory so nothing lands in the repo. Resolve the temp dir from `$TMPDIR`, falling back to `/tmp` (or `%TEMP%` on Windows), and write to `<tmpdir>/architecture-review-<timestamp>.html` so each run gets a fresh file. Open it for the user — `xdg-open <path>` on Linux, `open <path>` on macOS, `start <path>` on Windows — and tell them the absolute path.
+
+The report uses **Tailwind via CDN** for layout and styling, and **Mermaid via CDN** for diagrams where a graph/flow/sequence reliably communicates the structure. Mix Mermaid with hand-crafted CSS/SVG visuals — use Mermaid when relationships are graph-shaped (call graphs, dependencies, sequences), and hand-built divs/SVG when you want something more editorial (mass diagrams, cross-sections, collapse animations). Each candidate gets a **before/after visualisation**. Be visual.
+
+For each candidate, render a card with:
+
+- **Files** — which files/modules are involved
+- **Problem** — why the current architecture is causing friction
+- **Solution** — plain English description of what would change
+- **Benefits** — explained in terms of locality and reach, and how tests would improve
+- **Before / After diagram** — side-by-side, custom-drawn, illustrating the shallowness and the deepening
+- **Recommendation strength** — one of `Strong`, `Worth exploring`, `Speculative`, rendered as a badge
+
+End the report with a **Top recommendation** section: which candidate you'd tackle first and why.
+
+**Use CONTEXT.md vocabulary for the domain, and the `/codebase-design` vocabulary for the architecture.** If `CONTEXT.md` defines "Order," talk about "the Order intake module" — not "the FooBarHandler," and not "the Order service."
+
+**ADR conflicts**: if a candidate contradicts an existing ADR, only surface it when the friction is real enough to warrant revisiting the ADR. Mark it in the card (e.g. a warning callout: _"contradicts ADR-0007 — but worth reopening because…"_). Don't list every theoretical refactor an ADR forbids.
+
+See [references/HTML-REPORT.md](references/HTML-REPORT.md) for the full HTML scaffold, diagram patterns, and styling guidance.
+
+Do NOT propose interfaces yet. After the file is written, ask the user: "Which of these would you like to explore?"
+
+### 3. Grilling loop
+
+Once the user picks a candidate, run the `/grilling` skill to walk the decision tree with them — constraints, dependencies, the shape of the deepened module, what sits behind the seam, what tests survive.
+
+Side effects happen inline as decisions crystallize — run the `/domain-modeling` skill to keep the domain model current as you go:
+
+- **Naming a deepened module after a concept not in `CONTEXT.md`?** Add the term to `CONTEXT.md`. Create the file lazily if it doesn't exist.
+- **Sharpening a fuzzy term during the conversation?** Update `CONTEXT.md` right there.
+- **User rejects the candidate with a load-bearing reason?** Offer an ADR, framed as: _"Want me to record this as an ADR so future architecture reviews don't re-suggest it?"_ Only offer when the reason would actually be needed by a future explorer to avoid re-suggesting the same thing — skip ephemeral reasons ("not worth it right now") and self-evident ones.
+- **Want to explore alternative interfaces for the deepened module?** Run the `/codebase-design` skill and use its design-it-twice parallel sub-agent pattern.

package/extensions/enact-repo/skills/improve-codebase-architecture/references/HTML-REPORT.md

@@ -0,0 +1,123 @@
+# HTML Report Format
+
+The architectural review is rendered as a single self-contained HTML file in the OS temp directory. Tailwind and Mermaid both come from CDNs. Mermaid handles graph-shaped diagrams reliably; hand-built divs and inline SVG handle the more editorial visuals (mass diagrams, cross-sections). Mix the two — don't lean on Mermaid for everything, it'll start to look generic.
+
+## Scaffold
+
+```html
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <title>Architecture review — {{repo name}}</title>
+    <script src="https://cdn.tailwindcss.com"></script>
+    <script type="module">
+      import mermaid from "https://cdn.jsdelivr.net/npm/mermaid@11/dist/mermaid.esm.min.mjs";
+      mermaid.initialize({ startOnLoad: true, theme: "neutral", securityLevel: "loose" });
+    </script>
+    <style>
+      /* small custom layer for things Tailwind doesn't cover cleanly:
+         dashed seam lines, hand-drawn-feeling arrow heads, etc. */
+      .seam { stroke-dasharray: 4 4; }
+      .leak { stroke: #dc2626; }
+      .deep { background: linear-gradient(135deg, #0f172a, #1e293b); }
+    </style>
+  </head>
+  <body class="bg-stone-50 text-slate-900 font-sans">
+    <main class="max-w-5xl mx-auto px-6 py-12 space-y-12">
+      <header>...</header>
+      <section id="candidates" class="space-y-10">...</section>
+      <section id="top-recommendation">...</section>
+    </main>
+  </body>
+</html>
+```
+
+## Header
+
+Repo name, date, and a compact legend: solid box = module, dashed line = seam, red arrow = leakage, thick dark box = deep module. No introduction paragraph — straight into the candidates.
+
+## Candidate card
+
+The diagrams carry the weight. Prose is sparse, plain, and uses the glossary terms (from the `/codebase-design` skill) without ceremony.
+
+Each candidate is one `<article>`:
+
+- **Title** — short, names the deepening (e.g. "Collapse the Order intake pipeline").
+- **Badge row** — recommendation strength (`Strong` = emerald, `Worth exploring` = amber, `Speculative` = slate), plus a tag for the dependency category (`in-process`, `local-substitutable`, `ports & adapters`, `mock`).
+- **Files** — monospaced list, `font-mono text-sm`.
+- **Before / After diagram** — the centrepiece. Two columns, side by side. See patterns below.
+- **Problem** — one sentence. What hurts.
+- **Solution** — one sentence. What changes.
+- **Wins** — bullets, ≤6 words each. e.g. "Tests hit one interface", "Pricing logic stops leaking", "Delete 4 shallow wrappers".
+- **ADR callout** (if applicable) — one line in an amber-tinted box.
+
+No paragraphs of explanation. If the diagram needs a paragraph to be understood, redraw the diagram.
+
+## Diagram patterns
+
+Pick the pattern that fits the candidate. Mix them. Don't make every diagram look the same — variety is part of the point.
+
+### Mermaid graph (the workhorse for dependencies / call flow)
+
+Use a Mermaid `flowchart` or `graph` when the point is "X calls Y calls Z, and look at the mess." Wrap it in a Tailwind-styled card so it doesn't feel parachuted in. Style with classDef to colour leakage edges red and the deep module dark. Sequence diagrams work well for "before: 6 round-trips; after: 1."
+
+```html
+<div class="rounded-lg border border-slate-200 bg-white p-4">
+  <pre class="mermaid">
+    flowchart LR
+      A[OrderHandler] --> B[OrderValidator]
+      B --> C[OrderRepo]
+      C -.leak.-> D[PricingClient]
+      classDef leak stroke:#dc2626,stroke-width:2px;
+      class C,D leak
+  </pre>
+</div>
+```
+
+### Hand-built boxes-and-arrows (when Mermaid's layout fights you)
+
+Modules as `<div>`s with borders and labels. Arrows as inline SVG `<line>` or `<path>` elements positioned absolutely over a relative container. Reach for this when you want the "after" diagram to feel like one thick-bordered deep module with greyed-out internals — Mermaid won't render that with the right weight.
+
+### Cross-section (good for layered shallowness)
+
+Stack horizontal bands (`h-12 border-l-4`) to show layers a call passes through. Before: 6 thin layers each doing nothing. After: 1 thick band labelled with the consolidated responsibility.
+
+### Mass diagram (good for "interface as wide as implementation")
+
+Two rectangles per module — one for interface surface area, one for implementation. Before: interface rectangle is nearly as tall as the implementation rectangle (shallow). After: interface rectangle is short, implementation rectangle is tall (deep).
+
+### Call-graph collapse
+
+Before: a tree of function calls rendered as nested boxes. After: the same tree collapsed into one box, with the now-internal calls shown faded inside it.
+
+## Style guidance
+
+- Lean editorial, not corporate-dashboard. Generous whitespace. Serif optional for headings (`font-serif` works well with stone/slate).
+- Colour sparingly: one accent (emerald or indigo) plus red for leakage and amber for warnings.
+- Keep diagrams ~320px tall so before/after sits comfortably side by side without scrolling.
+- Use `text-xs uppercase tracking-wider` for module labels inside diagrams — they should read as schematic, not as UI.
+- The only scripts are the Tailwind CDN and the Mermaid ESM import. The report is otherwise static — no app code, no interactivity beyond Mermaid's own rendering.
+
+## Top recommendation section
+
+One larger card. Candidate name, one sentence on why, anchor link to its card. That's it.
+
+## Tone
+
+Plain English, concise — but the architectural nouns and verbs come straight from the `/codebase-design` skill. Concision is not an excuse to drift.
+
+**Use exactly:** module, interface, implementation, depth, deep, shallow, seam, adapter, reach, locality.
+
+**Never substitute:** component, service, unit (for module) · API, signature (for interface) · boundary (for seam) · layer, wrapper (for module, when you mean module).
+
+**Phrasings that fit the style:**
+
+- "Order intake module is shallow — interface nearly matches the implementation."
+- "Pricing leaks across the seam."
+- "Deepen: one interface, one place to test."
+- "Two adapters justify the seam: HTTP in prod, in-memory in tests."
+
+**Wins bullets** name the gain in glossary terms: *"locality: bugs concentrate in one module"*, *"reach: one interface, N call sites"*, *"interface shrinks; implementation absorbs the wrappers"*. Don't write *"easier to maintain"* or *"cleaner code"* — those terms aren't in the glossary and don't earn their place.
+
+No hedging, no throat-clearing, no "…". If a sentence could be a bullet, make it a bullet. If a bullet could be cut, cut it. If a term isn't in the `/codebase-design` glossary, reach for one that is before inventing a new one.

package/extensions/enact-repo/skills/interaction-design/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: interaction-design
+description: Design and implement microinteractions, motion design, transitions, and user feedback patterns. Use when adding polish to UI interactions, implementing loading states, or creating delightful user experiences.
+disable-model-invocation: false
+---
+
+# Interaction Design
+
+Add motion, feedback, and state-transition polish to a UI: microinteractions, transitions, loading states, and gesture handling, implemented with accessibility-aware timing.
+
+## Use When
+
+- Adding microinteractions to enhance user feedback (button presses, toggles, ripples).
+- Implementing smooth page and component transitions, or loading states and skeleton screens.
+- Creating gesture-based interactions (swipe, drag, pull-to-refresh).
+- Building notification and toast systems, or drag-and-drop interfaces.
+- Adding scroll-triggered animations, or designing hover and focus states.
+
+## Do Not Use When
+
+- The task is static visual design — layout, color, typography — with no motion or state-transition component; use `frontend-design`.
+- You need a searchable rule database for design-system decisions (palettes, stacks, accessibility checklist) rather than motion implementation; use `ui-ux-pro-max`.
+- The work is backend logic or has no user-facing interaction surface.
+
+See [references/Workflow.md](references/Workflow.md) for the full interaction patterns, timing guidelines, CSS animation patterns, and accessibility considerations. That file's "Further Reading" section indexes the rest:
+
+- [references/interaction-patterns.md](references/interaction-patterns.md)
+- [references/microinteraction-patterns.md](references/microinteraction-patterns.md), [references/microinteraction-patterns-advanced.md](references/microinteraction-patterns-advanced.md)
+- [references/animation-libraries.md](references/animation-libraries.md), [references/animation-libraries-gsap.md](references/animation-libraries-gsap.md), [references/animation-libraries-native.md](references/animation-libraries-native.md)
+- [references/scroll-animations.md](references/scroll-animations.md), [references/scroll-animations-reveals.md](references/scroll-animations-reveals.md)

package/extensions/enact-repo/skills/interaction-design/references/Workflow.md

@@ -0,0 +1,146 @@
+# Interaction Design
+
+Create engaging, intuitive interactions through motion, feedback, and thoughtful state transitions that enhance usability and delight users.
+
+## Core Principles
+
+### 1. Purposeful Motion
+
+Motion should communicate, not decorate:
+
+- **Feedback**: Confirm user actions occurred
+- **Orientation**: Show where elements come from/go to
+- **Focus**: Direct attention to important changes
+- **Continuity**: Maintain context during transitions
+
+### 2. Timing Guidelines
+
+| Duration  | Use Case                                  |
+| --------- | ------------------------------------------ |
+| 100-150ms | Micro-feedback (hovers, clicks)           |
+| 200-300ms | Small transitions (toggles, dropdowns)    |
+| 300-500ms | Medium transitions (modals, page changes) |
+| 500ms+    | Complex choreographed animations          |
+
+### 3. Easing Functions
+
+```css
+/* Common easings */
+--ease-out: cubic-bezier(0.16, 1, 0.3, 1); /* Decelerate - entering */
+--ease-in: cubic-bezier(0.55, 0, 1, 0.45); /* Accelerate - exiting */
+--ease-in-out: cubic-bezier(0.65, 0, 0.35, 1); /* Both - moving between */
+--spring: cubic-bezier(0.34, 1.56, 0.64, 1); /* Overshoot - playful */
+```
+
+## CSS Animation Patterns
+
+### Keyframe Animations
+
+```css
+@keyframes fadeIn {
+  from {
+    opacity: 0;
+    transform: translateY(10px);
+  }
+  to {
+    opacity: 1;
+    transform: translateY(0);
+  }
+}
+
+@keyframes pulse {
+  0%,
+  100% {
+    opacity: 1;
+  }
+  50% {
+    opacity: 0.5;
+  }
+}
+
+@keyframes spin {
+  to {
+    transform: rotate(360deg);
+  }
+}
+
+.animate-fadeIn {
+  animation: fadeIn 0.3s ease-out;
+}
+.animate-pulse {
+  animation: pulse 2s ease-in-out infinite;
+}
+.animate-spin {
+  animation: spin 1s linear infinite;
+}
+```
+
+### CSS Transitions
+
+```css
+.card {
+  transition:
+    transform 0.2s ease-out,
+    box-shadow 0.2s ease-out;
+}
+
+.card:hover {
+  transform: translateY(-4px);
+  box-shadow: 0 12px 24px rgba(0, 0, 0, 0.1);
+}
+```
+
+## Accessibility Considerations
+
+```css
+/* Respect user motion preferences */
+@media (prefers-reduced-motion: reduce) {
+  *,
+  *::before,
+  *::after {
+    animation-duration: 0.01ms !important;
+    animation-iteration-count: 1 !important;
+    transition-duration: 0.01ms !important;
+  }
+}
+```
+
+```tsx
+function AnimatedComponent() {
+  const prefersReducedMotion = window.matchMedia(
+    "(prefers-reduced-motion: reduce)",
+  ).matches;
+
+  return (
+    <motion.div
+      animate={{ opacity: 1 }}
+      transition={{ duration: prefersReducedMotion ? 0 : 0.3 }}
+    />
+  );
+}
+```
+
+## Guidelines
+
+1. **Performance First**: Use `transform` and `opacity` for smooth 60fps
+2. **Reduce Motion Support**: Always respect `prefers-reduced-motion`
+3. **Consistent Timing**: Use a timing scale across the app
+4. **Natural Physics**: Prefer spring animations over linear
+5. **Interruptible**: Allow users to cancel long animations
+6. **Progressive Enhancement**: Work without JS animations
+7. **Test on Devices**: Performance varies significantly
+
+## Common Issues
+
+- **Janky Animations**: Avoid animating `width`, `height`, `top`, `left`
+- **Over-animation**: Too much motion causes fatigue
+- **Blocking Interactions**: Never prevent user input during animations
+- **Memory Leaks**: Clean up animation listeners on unmount
+- **Flash of Content**: Use `will-change` sparingly for optimization
+
+## Further Reading
+
+- [interaction-patterns.md](interaction-patterns.md) — worked examples: button microinteraction, loading states, state transitions, page transitions, ripple feedback, swipe-to-dismiss.
+- [microinteraction-patterns.md](microinteraction-patterns.md) and [microinteraction-patterns-advanced.md](microinteraction-patterns-advanced.md) — button, form, feedback, navigation, and data-interaction component patterns.
+- [animation-libraries.md](animation-libraries.md), [animation-libraries-gsap.md](animation-libraries-gsap.md), and [animation-libraries-native.md](animation-libraries-native.md) — Framer Motion, GSAP, CSS spring physics, and native browser animation APIs.
+- [scroll-animations.md](scroll-animations.md) and [scroll-animations-reveals.md](scroll-animations-reveals.md) — intersection-observer, parallax, and scroll-triggered reveal patterns.