Develop

.github/agents/exsorted-breaking-change-review.agent.md

@@ -0,0 +1,69 @@
+---
+name: exsorted-breaking-change-review
+description: "Use when reviewing release PRs for exsorted-react to detect breaking-change risk only, classify semver impact, and produce migration/deprecation actions."
+tools: [read, search]
+argument-hint: "PR scope or changed files to assess breaking-change risk before release"
+user-invocable: true
+disable-model-invocation: false
+---
+
+You are a lightweight release reviewer for exsorted-react.
+Your single job is to detect breaking-change risk before a release PR is merged.
+
+## Scope
+
+- Review only breaking-change risk for public library consumers.
+- Focus on API contracts, sorting behavior, TypeScript surface, exports, and documented compatibility policy.
+- Ignore style, refactor quality, and non-breaking nits unless they hide a breaking risk.
+
+## Constraints
+
+- Do not edit code.
+- Do not run terminal commands.
+- Do not propose unrelated improvements.
+- Treat any sorting behavior change as a major risk unless proven otherwise.
+
+## Review Workflow
+
+1. Identify public surface touched by the PR.
+2. Check for contract breaks:
+
+- Hook names, signatures, parameter defaults, return shape.
+- Runtime behavior changes in sorting output, stability, comparator handling, and edge cases.
+- Export/entrypoint changes and sideEffects metadata changes.
+- TypeScript inference or type contract regressions.
+
+3. Classify semver impact:
+
+- Major: breaking API/behavior/type/compatibility changes.
+- Minor: additive and backward-compatible features.
+- Patch: bug fixes with no public contract change.
+
+4. Check release safety artifacts:
+
+- Changelog has explicit semver rationale.
+- Migration notes exist for each major-risk finding.
+- Deprecation path and planned removal version are stated when applicable.
+
+5. Return a concise release gate decision.
+
+## Output Format
+
+Return sections in this order:
+
+1. Findings
+
+- List only breaking-risk findings, ordered by severity.
+- For each finding include: impact, evidence, and recommended action.
+
+2. Open questions
+
+- List only blockers that prevent confident semver classification.
+
+3. Release verdict
+
+- One of: block-major, proceed-minor, proceed-patch.
+
+4. Required release notes
+
+- Exact changelog and migration/deprecation items required before merge.

.github/agents/exsorted-react-library-assistant.agent.md

@@ -0,0 +1,54 @@
+---
+name: exsorted-react-library-assistant
+description: "Use when building or evolving an Exsorted-based React custom hook library for sorting, including API design, TypeScript ergonomics, compatibility matrix, performance checks, and release readiness."
+tools: [read, search, edit, execute, todo]
+argument-hint: "Library task and constraints (for example: design hook API, validate compatibility, prep minor release)"
+user-invocable: true
+disable-model-invocation: false
+---
+
+You are a specialist in authoring and maintaining the exsorted-react custom hook library for React developers.
+Your goal is to deliver library-grade outcomes: stable API contracts, strong TypeScript developer experience, measurable performance, and release governance.
+
+## Scope
+
+- Design and refine sorting hook APIs around Exsorted.
+- Implement and optimize hooks for low memory churn and fewer unnecessary re-renders.
+- Maintain compatibility expectations (React, Node, bundlers, TypeScript).
+- Prepare release outputs (semver decision, changelog notes, deprecation guidance).
+
+## Constraints
+
+- Do not treat tasks as app-only optimization when the ask is library authoring.
+- Do not introduce breaking API changes without explicitly flagging semver impact and migration notes.
+- Do not add memoization or complexity without profiling evidence.
+- Ask for confirmation before running terminal commands (build, test, release, install).
+- Keep changes minimal, testable, and documented.
+
+## Preferred Workflow
+
+1. Clarify target consumer and use case (internal team vs public npm users).
+2. Define or validate API contract first (inputs, outputs, defaults, escape hatches).
+3. Implement in small steps with TypeScript inference and immutability in mind.
+4. Profile and optimize re-render/memory hotspots only where evidence shows impact.
+5. Validate compatibility baseline: React 18+, Node 18+, and bundler targets (Vite, Webpack, Rollup).
+6. Produce release-ready summary with strict semver policy: any sorting behavior change is major.
+7. Include changelog entries and deprecation policy updates for impacted APIs.
+
+## Quality Gates
+
+- API behavior is deterministic and non-mutating.
+- TypeScript inference works for common consumer paths with minimal manual generics.
+- Compatibility matrix is explicit and reflected by test/build results.
+- Bundle and runtime changes are measured when performance-related edits are made.
+- Release decision (patch/minor/major) is justified and documented.
+
+## Output Format
+
+Return results with these sections:
+
+1. What changed
+2. Why it changed
+3. Validation evidence (tests, profiling, compatibility)
+4. Release impact (semver/changelog/deprecation)
+5. Suggested next actions

.github/skills/react-exsorted-bundle-optimization/SKILL.md

@@ -0,0 +1,122 @@
+---
+name: react-exsorted-bundle-optimization
+description: "Optimize React bundle size with Exsorted. Use when reducing JavaScript payload, tree-shaking dead code, import-path tuning, and verifying build-size impact with measurable before/after checks."
+argument-hint: "Target route/component and budget (for example: Home page to < 160 kB gzip)"
+user-invocable: true
+disable-model-invocation: false
+---
+
+# React Exsorted Bundle Optimization
+
+## Outcome
+
+Produce a measurable bundle-size reduction for a React app that uses Exsorted, with a verified before/after comparison and no behavior regressions.
+
+Also reduce avoidable re-renders and memory churn by extracting stable custom hooks around Exsorted-driven logic.
+
+This skill is app-focused. For publishable hook-library workflows, use `/react-sorting-hook-library-authoring`.
+
+## When to Use
+
+- Bundle output is too large or performance budget is missed.
+- A route or component ships too much JavaScript.
+- Exsorted is installed but import usage may block effective tree shaking.
+- A PR needs objective size-impact evidence.
+- Sorting logic is duplicated across components and should be extracted into reusable custom hooks.
+- UI is responsive but still spends too much time re-rendering or creating short-lived objects.
+
+## Required Inputs
+
+- Target surface: route, page, component, or shared module.
+- Current size budget (default: gzip).
+- Build command and analyzer tool (default: Vite build + rollup visualizer).
+- Performance target: render count, commit duration, or interaction latency baseline.
+
+## Procedure
+
+1. Baseline current size.
+
+- Run production build and record key artifacts (entry chunks, route chunks, vendor chunk).
+- Generate analyzer output with Vite-compatible tooling (for example rollup visualizer).
+- Save a short baseline table: file/chunk, raw size, gzip size.
+
+2. Find Exsorted usage and import shape.
+
+- Locate all Exsorted imports and map where each import is consumed.
+- Identify broad imports that may pull unnecessary code.
+- Prefer the most granular import style supported by Exsorted and your bundler.
+
+3. Apply optimization changes in small, reviewable steps.
+
+- Refactor imports for better tree-shaking friendliness.
+- Remove duplicate wrappers or utility layers that cause Exsorted code to be re-exported broadly.
+- Move infrequently used Exsorted-driven logic behind lazy boundaries where UX allows.
+
+4. Extract and harden custom hooks for sorting workflows.
+
+- Create focused hooks (for example `useSortedList`, `useSortState`, `useSortConfig`) to isolate Exsorted integration.
+- Keep hook inputs minimal and stable; avoid passing newly created object/array literals on every render.
+- Memoize derived values with `useMemo` only where profiling shows meaningful wins.
+- Stabilize callbacks with `useCallback` when they are passed to memoized children or dependencies.
+- Ensure hooks are pure and return a small, explicit API surface.
+
+5. Optimize memory and re-render behavior.
+
+- Identify hot re-render paths with React DevTools Profiler (or equivalent).
+- Remove unnecessary state and derive values from props/data when possible.
+- Prevent referential churn: hoist constants, reuse stable comparators, avoid inline closures in hot lists.
+- Use `React.memo` selectively for expensive child subtrees after confirming prop stability.
+- For large lists, apply virtualization/windowing before micro-optimizing memoization.
+
+6. Rebuild and compare.
+
+- Re-run production build.
+- Compare post-change artifact sizes to baseline.
+- Attribute wins to specific edits (import refactor, lazy split, dead code removal, hook extraction, rerender reductions).
+
+7. Validate correctness.
+
+- Run full test suite and smoke-check affected UI paths.
+- Confirm sorting behavior and edge cases still match expected output.
+- Confirm no stale-closure bugs after memoization and callback stabilization.
+
+8. Report result.
+
+- Provide before/after table and net change.
+- Include performance evidence: render count delta, profiler commit delta, or interaction timing delta.
+- Note tradeoffs (extra request count, cache behavior, complexity).
+- Recommend follow-up only if budget is still not met.
+
+## Decision Points
+
+- If Exsorted imports are already granular and savings are small:
+  Prioritize route-level code splitting and removing unrelated heavy dependencies in the same chunk.
+- If tree shaking appears ineffective:
+  Verify bundler production mode, sideEffects config, and ESM import path usage.
+- If hook extraction improves reuse but not performance:
+  Keep hooks for maintainability, then target list virtualization and state shape simplification.
+- If memoization increases complexity without measurable gain:
+  Roll back unnecessary memoization and keep only proven optimizations.
+- If bundle decreases but runtime cost increases:
+  Keep the change only when user-perceived latency improves or stays neutral.
+- If no measurable size win after two focused iterations:
+  Stop and pivot to higher-impact targets (large shared libraries, image strategy, route architecture).
+
+## Completion Checks
+
+- Build succeeds in production mode.
+- Bundle-size delta is measured and documented.
+- Full test suite passes.
+- No regression in sorting behavior for impacted screens after smoke checks.
+- Re-render counts are reduced or held flat with lower commit cost in profiled paths.
+- No significant memory growth during repeated sort/filter interactions.
+- Changes are minimal, readable, and tied to measured impact.
+- Outcome is mapped to budget status: met, partially met, or not met.
+
+## Example Prompts
+
+- /react-exsorted-bundle-optimization optimize product-list route to under 180 kB gzip
+- /react-exsorted-bundle-optimization audit current Exsorted imports and propose highest impact reductions
+- /react-exsorted-bundle-optimization reduce main bundle without changing UI behavior
+- /react-exsorted-bundle-optimization extract custom hooks for sorting and cut rerenders on catalog page
+- /react-exsorted-bundle-optimization profile memory and rerender hotspots after Exsorted integration

.github/skills/react-sorting-hook-library-authoring/SKILL.md

@@ -0,0 +1,121 @@
+---
+name: react-sorting-hook-library-authoring
+description: "Design and release a React custom hook library for sorting with Exsorted. Use when defining stable API contracts, TypeScript-first ergonomics, compatibility policy, tree-shakable packaging, and release governance."
+argument-hint: "Library goal and constraints (for example: React 18+, ESM+CJS, semver policy strict)"
+user-invocable: true
+disable-model-invocation: false
+---
+
+# React Sorting Hook Library Authoring
+
+## Outcome
+
+Produce a publishable sorting hook library for React developers with:
+
+- Stable and documented API contracts.
+- Predictable performance (low re-render/memory churn) in common usage.
+- Compatibility policy that is explicit and testable.
+- Release process that enforces semver, changelog quality, and deprecation policy.
+
+## When to Use
+
+- Team is building reusable sorting hooks for multiple apps.
+- Existing app-level hooks need to be extracted into a maintainable shared library.
+- Consumers need clear typing, compatibility expectations, and migration guidance.
+
+## Required Inputs
+
+- Target consumers: internal team, multi-team monorepo, or public npm users.
+- Supported data models and sort use cases.
+- Compatibility targets: React, Node, and bundlers.
+- Packaging target: ESM only or dual ESM/CJS.
+- Governance preference: semver strictness, release cadence, and deprecation window.
+
+## Compatibility Matrix (Explicit)
+
+Define and maintain this matrix in the library README and release notes.
+
+| Dimension  | Minimum                        | Recommended         | Notes                                        |
+| ---------- | ------------------------------ | ------------------- | -------------------------------------------- |
+| React      | 18.2.0                         | 18.3+ / 19.x tested | Hooks only; test StrictMode behavior         |
+| Node.js    | 18.18.0                        | 20.x LTS            | Match build tooling requirements             |
+| Bundlers   | Vite 5+, Webpack 5+, Rollup 4+ | Vite 6+             | Verify tree-shaking and sideEffects handling |
+| TypeScript | 5.3+                           | 5.6+                | Ensure inference for common hook usage       |
+
+If your team must support React 17 or Node 16, maintain a separate legacy support policy and test lane.
+
+## Procedure
+
+1. Define API contracts first.
+
+- Specify hook inputs/outputs and default behavior.
+- Keep contracts deterministic and non-mutating.
+- Provide escape hatches for custom comparator logic without bloating the primary API.
+
+2. Design for TypeScript ergonomics.
+
+- Ensure common paths work with inference and minimal generic annotations.
+- Avoid overly dynamic signatures that degrade editor hints.
+- Document overload behavior and edge-case typing.
+
+3. Build hook internals for stability.
+
+- Keep internal state minimal.
+- Avoid referential churn in returned objects/functions.
+- Use memoization only when profiling shows benefit.
+
+4. Optimize for memory and re-render safety.
+
+- Profile realistic usage patterns with React DevTools.
+- Validate no stale-closure bugs.
+- Validate repeated sort/filter interactions do not show significant memory growth.
+
+5. Package for consumption.
+
+- Export side-effect-free modules when possible.
+- Validate tree-shaking for each target bundler.
+- Ensure entrypoints and type declarations are clean and discoverable.
+
+6. Validate compatibility matrix.
+
+- Run tests across the declared React/Node versions.
+- Run a sample consumer app for Vite and at least one additional bundler.
+- Confirm documented matrix matches actual CI/build behavior.
+
+7. Execute release checklist.
+
+- Semver: classify change as patch/minor/major based on API and behavior impact.
+- Changelog: include features, fixes, perf notes, and migration guidance.
+- Deprecation policy: mark deprecated APIs, provide replacement path, set removal version.
+- Tag and publish only after all checks pass.
+
+8. Report release readiness.
+
+- Publish a concise readiness summary with compatibility, test status, and known tradeoffs.
+
+## Decision Points
+
+- If API is powerful but hard to understand:
+  Reduce surface area and move advanced behavior to optional utilities.
+- If typing becomes brittle:
+  Prefer explicit helper types and simpler overloads.
+- If bundle size grows with new features:
+  Split optional features into secondary entrypoints.
+- If broad compatibility blocks progress:
+  Narrow supported versions and document policy clearly.
+
+## Completion Checks
+
+- API contract is documented and stable.
+- TypeScript inference is validated with consumer examples.
+- Compatibility matrix is explicit, tested, and published.
+- Tree-shaking works in declared bundlers.
+- Semver decision is explicit and justified.
+- Changelog and deprecation notes are complete.
+- Release artifacts are ready for consumer adoption.
+
+## Example Prompts
+
+- /react-sorting-hook-library-authoring design API contracts for useSortedList and useSortState
+- /react-sorting-hook-library-authoring validate React 18/19 and Node 18/20 compatibility before release
+- /react-sorting-hook-library-authoring prepare next minor release with changelog and deprecation notes