chore: agentic upgrade

.agents/skills/composition-patterns/SKILL.md

@@ -0,0 +1,62 @@
+---
+name: composition-patterns
+description: Use when writing, reviewing, or refactoring React component APIs that risk boolean prop proliferation, renderHeader/renderFooter-style slots, prop drilling, trapped local state, context-provider architecture, compound components, explicit variants, or React 19 ref/context composition patterns.
+---
+
+# Composition Patterns
+
+## Overview
+
+Apply scalable React composition patterns from Vercel's `composition-patterns`
+skill, adapted for this Next.js/FSD repository. Prefer explicit composed APIs
+over configuration-heavy components, and keep reusable UI parts decoupled from
+state implementations.
+
+## Workflow
+
+1. Identify whether the component is becoming a mode switcher.
+   Look for multiple boolean props, conditional branches that choose whole UI
+   regions, `renderHeader`/`renderFooter` props, or impossible prop
+   combinations.
+2. Split behavior into explicit variants when the rendered structure differs.
+   Prefer names such as `ThreadComposer`, `EditComposer`, or
+   `ForwardComposer` over one `Composer` with `isThread`, `isEditing`, and
+   `isForwarding`.
+3. Extract shared pieces into compound components when consumers need to
+   arrange the parts themselves. Use `Root`/`Provider`, `Frame`, `Header`,
+   `Body`, `Footer`, `Trigger`, `Content`, `Action`, or domain-specific names
+   that fit the existing component.
+4. Lift shared state into a provider boundary when siblings or custom outer UI
+   need the same state/actions. Keep visual nesting separate from state access:
+   components only need to be inside the provider, not inside the same DOM box.
+5. Define a context contract with `state`, `actions`, and `meta` when multiple
+   providers can drive the same UI. UI subcomponents consume the contract, while
+   providers decide whether state comes from local hooks, server-synced data,
+   forms, or feature-specific stores.
+6. In this React 19 repo, pass `ref` as a normal prop and use `use(Context)` for
+   context reads where the surrounding codebase allows it. Preserve existing
+   conventions if a nearby component has not migrated yet.
+
+## Decision Rules
+
+- Do not add a boolean prop to control a large behavior branch until checking
+  whether an explicit variant or child composition would make the state space
+  clearer.
+- Use children for static structure composition. Keep render props for cases
+  where the parent must pass item data, measurements, or callback-local state
+  back into the child.
+- Keep providers as the only layer that knows a concrete state implementation.
+  Subcomponents should not import feature stores or synchronization hooks unless
+  they are provider components.
+- Avoid prop drilling through compound components. Put shared state/actions in a
+  typed context and expose narrow subcomponents.
+- Keep FSD boundaries intact: shared compound UI belongs under `src/shared/ui`;
+  feature-specific variants and providers belong in the appropriate feature,
+  entity, widget, or page layer.
+
+## Reference
+
+Read `references/rules.md` when you need examples, a review checklist, or the
+upstream rule inventory. It summarizes all files from:
+`https://github.com/vercel-labs/agent-skills/tree/main/skills/composition-patterns`
+at commit `ce3e64e468f8fa09a2d075d102771838061fdac0`.