contextos-agents 1.7.0 → 2.0.0-beta.3

package/.agents/core/skills/react-best-practices/SKILL.md

@@ -1,155 +0,0 @@
----
-name: vercel-react-best-practices
-description: React and Next.js performance optimization guidelines from Vercel Engineering. This skill should be used when writing, reviewing, or refactoring React/Next.js code to ensure optimal performance patterns. Triggers on tasks involving React components, Next.js pages, data fetching, bundle optimization, or performance improvements.
-license: MIT
-metadata:
-  author: vercel
-  version: "1.0.0"
----
-
-# Vercel React Best Practices
-
-## Overview
-
-Comprehensive performance optimization guide for React and Next.js applications, maintained by Vercel. Contains 70 rules across 8 categories, prioritized by impact to guide automated refactoring, code generation, and production review.
-
-## When to Use
-
-- When authoring new React functional components or Next.js App Router pages.
-- When implementing data fetching (client or server-side Server Actions, RSC).
-- When reviewing pull requests for rendering bottlenecks or memory leaks.
-- When optimizing bundle size, eliminating network waterfalls, or improving Core Web Vitals (LCP, INP, CLS).
-
-## Rules & Patterns
-
-### Rule Categories by Priority
-
-| Priority | Category | Impact | Prefix |
-|----------|----------|--------|--------|
-| 1 | Eliminating Waterfalls | CRITICAL | `async-` |
-| 2 | Bundle Size Optimization | CRITICAL | `bundle-` |
-| 3 | Server-Side Performance | HIGH | `server-` |
-| 4 | Client-Side Data Fetching | MEDIUM-HIGH | `client-` |
-| 5 | Re-render Optimization | MEDIUM | `rerender-` |
-| 6 | Rendering Performance | MEDIUM | `rendering-` |
-| 7 | JavaScript Performance | LOW-MEDIUM | `js-` |
-| 8 | Advanced Patterns | LOW | `advanced-` |
-
-### 1. Eliminating Waterfalls (CRITICAL)
-
-- `async-cheap-condition-before-await` - Check cheap sync conditions before awaiting flags or remote values.
-- `async-defer-await` - Move await into branches where actually used.
-- `async-parallel` - Use `Promise.all()` for independent asynchronous operations.
-- `async-dependencies` - Use better-all for partial dependencies.
-- `async-api-routes` - Start promises early, await late in API routes.
-- `async-suspense-boundaries` - Use Suspense to stream content progressively.
-
-### 2. Bundle Size Optimization (CRITICAL)
-
-- `bundle-barrel-imports` - Import directly from specific modules, avoid broad barrel files (`index.ts`).
-- `bundle-analyzable-paths` - Prefer statically analyzable import paths to avoid bloated traces.
-- `bundle-dynamic-imports` - Use `next/dynamic` or `React.lazy()` for heavy interactive components.
-- `bundle-defer-third-party` - Load analytics and logging scripts after hydration.
-- `bundle-conditional` - Load modules only when feature flags or user actions require them.
-- `bundle-preload` - Preload assets on hover or focus for perceived instant navigation.
-
-### 3. Server-Side Performance (HIGH)
-
-- `server-auth-actions` - Always authenticate server actions like API routes.
-- `server-cache-react` - Use `React.cache()` for per-request deduplication.
-- `server-cache-lru` - Use LRU cache for cross-request caching.
-- `server-dedup-props` - Avoid duplicate serialization in RSC props.
-- `server-hoist-static-io` - Hoist static I/O to module level.
-- `server-no-shared-module-state` - Avoid module-level mutable request state in RSC/SSR.
-- `server-serialization` - Minimize data passed across the server-client boundary.
-- `server-parallel-fetching` - Restructure components to parallelize fetches.
-- `server-after-nonblocking` - Use `after()` for non-blocking operations like analytics logging.
-
-### 4. Client-Side Data Fetching (MEDIUM-HIGH)
-
-- `client-swr-dedup` - Use SWR or TanStack Query for automatic request deduplication.
-- `client-event-listeners` - Deduplicate global event listeners.
-- `client-passive-event-listeners` - Use passive listeners for scroll and touch.
-- `client-localstorage-schema` - Version and minimize data stored in localStorage.
-
-### 5. Re-render Optimization (MEDIUM)
-
-- `rerender-defer-reads` - Don't subscribe to state only used in callbacks.
-- `rerender-memo` - Extract expensive work into memoized components.
-- `rerender-memo-with-default-value` - Hoist default non-primitive props.
-- `rerender-dependencies` - Use primitive dependencies in effects and callbacks.
-- `rerender-derived-state` - Subscribe to derived booleans, not raw high-frequency values.
-- `rerender-derived-state-no-effect` - Derive state during render, never in `useEffect`.
-- `rerender-functional-setstate` - Use functional `setState` for stable callback references.
-- `rerender-lazy-state-init` - Pass initializer functions to `useState` for expensive computations.
-- `rerender-transitions` - Use `startTransition` for non-urgent state updates.
-- `rerender-use-deferred-value` - Defer expensive renders to keep input responsive.
-- `rerender-no-inline-components` - Never define subcomponents inside component render bodies.
-
-### 6. Rendering Performance (MEDIUM)
-
-- `rendering-content-visibility` - Use `content-visibility: auto` for long offscreen lists.
-- `rendering-hoist-jsx` - Extract static JSX elements outside components.
-- `rendering-conditional-render` - Use ternary (`condition ? <Comp /> : null`), not `&&` to avoid 0 rendering.
-- `rendering-usetransition-loading` - Prefer `useTransition` for loading state indicators.
-
-### 7. JavaScript Performance (LOW-MEDIUM)
-
-- `js-index-maps` - Build `Map` for repeated lookups instead of repeated array searches.
-- `js-cache-property-access` - Cache object properties in tight loops.
-- `js-early-exit` - Return early from functions to avoid nested complexity.
-- `js-hoist-regexp` - Hoist RegExp creation outside loops and functions.
-- `js-set-map-lookups` - Use `Set` / `Map` for O(1) lookups.
-
-### 8. Advanced Patterns (LOW)
-
-- `advanced-effect-event-deps` - Don't put `useEffectEvent` results in effect deps.
-- `advanced-event-handler-refs` - Store event handlers in refs for stable listener attachments.
-- `advanced-init-once` - Initialize app singletons once per lifecycle.
-
-## Code Examples
-
-```tsx
-// [GOOD] Parallel server fetching without waterfall
-import { cache } from 'react';
-
-export const getUser = cache(async (id: string) => {
-  return db.user.findUnique({ where: { id } });
-});
-
-export default async function UserPage({ params }: { params: { id: string } }) {
-  // Parallel dispatch
-  const userPromise = getUser(params.id);
-  const postsPromise = getPosts(params.id);
-
-  const [user, posts] = await Promise.all([userPromise, postsPromise]);
-
-  return (
-    <main>
-      <h1>{user.name}</h1>
-      <PostList posts={posts} />
-    </main>
-  );
-}
-```
-
-## Validation Checklist
-
-- [ ] All independent async fetches use `Promise.all()` instead of sequential `await`.
-- [ ] Direct imports used instead of barrel file imports for large libraries.
-- [ ] No `useEffect` used for deriving computed state from props or state.
-- [ ] Heavy interactive modals/drawers loaded dynamically via `next/dynamic`.
-- [ ] Server actions perform authentication checks before data mutations.
-- [ ] Zero subcomponents defined inside the body of parent components.
-
-## Common Mistakes
-
-- Writing sequential `await fetchA(); await fetchB();` creating avoidable network waterfalls.
-- Importing from package root barrel files triggering full bundle inclusion.
-- Setting state inside `useEffect` in response to prop changes.
-- Serializing full database models with sensitive or unused fields to Client Components.
-
-## Integration Notes
-
-- Pairs with `react` and `nextjs` skills for idiomatic App Router patterns.
-- Complements `performance` for Lighthouse and Core Web Vitals verification.

package/.agents/core/skills/react-best-practices/VALIDATION.json

@@ -1,12 +0,0 @@
-{
-  "$schema": "http://json-schema.org/draft-07/schema#",
-  "type": "object",
-  "properties": {
-    "rules_followed": {
-      "type": "boolean"
-    }
-  },
-  "required": [
-    "rules_followed"
-  ]
-}

package/.agents/core/skills/react-best-practices/skill.yaml

@@ -1,14 +0,0 @@
-name: react-best-practices
-type: instruction-only
-description: React and Next.js performance optimization guidelines from Vercel Engineering.
-tags:
-  - react
-  - nextjs
-  - performance
-  - vercel
-version: 1.0.0
-requires:
-  - react
-resources:
-  - SKILL.md
-  - VALIDATION.json

package/.agents/core/skills/redesign-audit/SKILL.md

@@ -1,117 +0,0 @@
----
-name: redesign-existing-projects
-description: Upgrades existing websites and apps to premium quality. Audits current design, identifies generic AI patterns, and applies high-end design standards without breaking functionality. Works with any CSS framework or vanilla CSS.
----
-
-# Redesign Skill & UI Audit
-
-## Overview
-
-A systematic redesign and auditing protocol designed to elevate existing websites, dashboards, and web applications to world-class agency quality. It diagnoses and eradicates generic AI design fingerprints, sloppy typography, inconsistent palettes, and absent interaction states without breaking business logic or underlying component contracts.
-
-## When to Use
-
-- When auditing an existing UI codebase for design quality, responsiveness, or accessibility.
-- When modernizing a legacy application or uplifting generic templates.
-- When tasked to "redesign", "clean up the layout", "audit UI", or "make it look expensive and modern".
-
-## Rules & Patterns
-
-### 1. Workflow: Scan → Diagnose → Fix
-
-1. **Scan:** Read the codebase. Identify the framework, styling method (Tailwind v3/v4, vanilla CSS, CSS Modules), and established design tokens.
-2. **Diagnose:** Run through the design audit categories. Catalog generic patterns, missing states, and optical alignment flaws.
-3. **Fix:** Apply surgical, targeted upgrades working within the existing stack. Do not rewrite from scratch.
-
-### 2. Design Audit Categories
-
-#### Typography
-
-- **Replace Browser Defaults:** Swap generic `Inter`, `Roboto`, or system fonts with expressive typefaces (`Geist`, `Outfit`, `Cabinet Grotesk`, `Satoshi`).
-- **Presence & Scale:** Increase display text size, tighten letter-spacing (`-0.02em` to `-0.04em`), reduce line-height on headlines.
-- **Reading Comfort:** Limit body text to 65 characters per line (`max-w-prose`), increase line-height to 1.6.
-- **Figures:** Enable tabular figures (`font-variant-numeric: tabular-nums`) for numbers in tables and data readouts.
-- **Orphan Prevention:** Apply `text-wrap: balance` on headlines and `text-wrap: pretty` on paragraphs.
-
-#### Color and Surfaces
-
-- **No Pure Black Backgrounds:** Replace `#000000` with tinted dark charcoal (`#0A0A0A`, `#121212`).
-- **Desaturate Accents:** Keep accent saturation below 80% so it blends harmoniously with neutrals.
-- **Single Accent Color:** Commit to one dominant accent hue; remove conflicting secondary tints.
-- **Tinted Shadows:** Tint shadows to match the background hue rather than harsh black opacity.
-- **Background Depth:** Prevent sterile flat sections by layering subtle noise overlays, ambient gradients, or masked imagery.
-
-#### Layout and Space
-
-- **Asymmetry & Bento Grids:** Break repetitive 3-column Bootstrap grids with asymmetrical spans or offset cards.
-- **Mobile Viewport Bug Fix:** Never use `height: 100vh`; always use `min-height: 100dvh`.
-- **Vertical Alignment:** Pin action buttons to the bottom of card groups (`mt-auto` or grid alignment) to maintain horizontal baseline harmony across differing text heights.
-- **Optical Centering:** Adjust icons, badges, and play buttons optically by 1-2px rather than relying solely on pure mathematical centering.
-
-#### Interactivity and States
-
-- **Interactive Feedback:** Add 200-300ms transitions, distinct hover shifts, and physical active presses (`scale(0.98)`).
-- **Visible Focus Rings:** Mandatory `:focus-visible` styling for keyboard navigation.
-- **States Completeness:** Always provide designed skeleton loaders, empty states, and inline error messages.
-
-#### Content & Code Quality
-
-- **Eradicate AI Clichés:** Remove buzzwords ("Elevate", "Seamless", "Unleash", "Next-Gen") and placeholder latin text.
-- **Semantic HTML:** Replace nested div containers with `<nav>`, `<main>`, `<article>`, `<section>`, `<aside>`.
-- **Relative Units:** Use `rem`, `%`, and CSS Grid rather than hardcoded pixel widths.
-
-### 3. Fix Priority
-
-1. **Font Swap:** Biggest instant aesthetic elevation with lowest regression risk.
-2. **Palette Cleanup:** Eliminate clashing or oversaturated colors.
-3. **States & Feedback:** Add hover, active, focus, loading, and empty states.
-4. **Layout & Alignment:** Fix container widths, baseline alignment, and mobile viewport heights.
-5. **Component Polish:** Replace generic cards and accordion boxes with modern minimal equivalents.
-
-## Code Examples
-
-```tsx
-// [BEFORE] Generic, misaligned card with generic shadow
-<div className="bg-white border rounded shadow p-4">
-  <h2>{title}</h2>
-  <p>{desc}</p>
-  <button className="bg-blue-500 text-white p-2">Click</button>
-</div>
-
-// [AFTER] Polished card with optical baseline alignment, tinted surface, and micro-interaction
-<div className="flex flex-col bg-[#FFFFFF] dark:bg-[#121212] border border-black/5 dark:border-white/10 rounded-2xl p-6 hover:shadow-[0_4px_20px_rgba(0,0,0,0.04)] transition-all duration-200">
-  <h3 className="font-semibold text-lg tracking-tight text-neutral-900 dark:text-neutral-100 text-balance mb-2">
-    {title}
-  </h3>
-  <p className="text-sm text-neutral-600 dark:text-neutral-400 leading-relaxed text-pretty mb-6">
-    {desc}
-  </p>
-  <button 
-    type="button" 
-    className="mt-auto inline-flex items-center justify-center font-medium text-sm px-4 py-2.5 rounded-xl bg-neutral-900 dark:bg-neutral-100 text-white dark:text-black hover:bg-neutral-800 active:scale-[0.98] transition-transform duration-150 focus-visible:ring-2 focus-visible:ring-neutral-400"
-  >
-    Continue
-  </button>
-</div>
-```
-
-## Validation Checklist
-
-- [ ] All headings have `text-wrap: balance` and appropriate negative letter tracking.
-- [ ] No pure black `#000000` backgrounds or oversaturated accent colors (>80% saturation).
-- [ ] All interactive elements include `:hover`, `:active`, and `:focus-visible` styles.
-- [ ] Cards in side-by-side grids align primary CTA buttons along the same bottom baseline.
-- [ ] Viewport containers use `100dvh` instead of `100vh`.
-- [ ] All lists, tables, and feeds have a designed empty state.
-
-## Common Mistakes
-
-- Rewriting components from scratch and breaking existing prop contracts or unit tests.
-- Forcing full-width sections without `max-w` constraints on ultra-wide screens.
-- Leaving action buttons at random heights inside differing text content cards.
-- Introducing external UI libraries without checking existing `package.json` dependencies.
-
-## Integration Notes
-
-- Complements `impeccable-design` for hard 50-rule QA verification.
-- Works alongside `ui-ux-pro` for token generation and color theory.

package/.agents/core/skills/redesign-audit/VALIDATION.json

@@ -1,12 +0,0 @@
-{
-  "$schema": "http://json-schema.org/draft-07/schema#",
-  "type": "object",
-  "properties": {
-    "rules_followed": {
-      "type": "boolean"
-    }
-  },
-  "required": [
-    "rules_followed"
-  ]
-}

package/.agents/core/skills/redesign-audit/skill.yaml

@@ -1,12 +0,0 @@
-name: redesign-audit
-type: instruction-only
-description: Audits and upgrades existing web codebases with high-end typography, color, layout, and interaction polish.
-tags:
-  - ui
-  - design
-  - audit
-  - refactor
-version: 1.0.0
-resources:
-  - SKILL.md
-  - VALIDATION.json

package/.agents/core/skills/soft-design/SKILL.md

@@ -1,108 +0,0 @@
----
-name: high-end-visual-design
-description: Teaches the AI to design like a high-end agency. Defines the exact fonts, spacing, shadows, card structures, and animations that make a website feel expensive. Blocks all the common defaults that make AI designs look cheap or generic.
----
-
-# Agent Skill: Principal UI/UX Architect & Motion Choreographer (Awwwards-Tier)
-
-## Overview
-
-Engineers high-end, agency-level digital experiences characterized by tactile haptic depth, cinematic spatial rhythm, obsessive micro-interactions, and fluid spring physics. Rejects generic commodity SaaS templates in favor of bespoke layout archetypes, nested double-bezel enclosures, and purposeful motion dynamics.
-
-## When to Use
-
-- When tasked with creating luxury, premium, Awwwards-tier landing pages, portfolio showpieces, or editorial SaaS interfaces.
-- When explicitly prompted for "soft UI", "expensive design", "Apple-level polish", or "calm aesthetics".
-- When standard component libraries feel too clinical or generic.
-
-## Rules & Patterns
-
-### 1. Absolute Zero Directive (Strict Anti-Patterns)
-
-- **Banned Fonts:** Inter, Roboto, Arial, Open Sans, Helvetica. (Use `Geist`, `Clash Display`, `PP Editorial New`, or `Plus Jakarta Sans`).
-- **Banned Icons:** Thick-stroked Lucide, FontAwesome, or Material Icons. Use ultra-light, precise line icons (Phosphor Light, Remix Line).
-- **Banned Borders & Shadows:** Generic 1px solid gray borders. Harsh dark drop shadows (`rgba(0,0,0,0.3)`).
-- **Banned Layouts:** Edge-to-edge sticky navbars glued to the top. Symmetrical 3-column Bootstrap-style grids without massive whitespace.
-- **Banned Motion:** Standard `linear` or `ease-in-out` transitions. Instant state changes without interpolation.
-
-### 2. The Creative Variance Engine
-
-Before writing code, consciously pick ONE combination:
-
-#### Vibe & Texture Archetypes
-
-1. **Ethereal Glass (SaaS / AI / Tech):** Deep OLED black (`#050505`), subtle radial mesh gradients, vantablack cards with `backdrop-blur-2xl` and white/10 hairlines.
-2. **Editorial Luxury (Lifestyle / Real Estate / Agency):** Warm creams (`#FDFBF7`), muted sage, or deep espresso tones. Variable serif headings with subtle CSS noise overlay (`opacity-[0.03]`).
-3. **Soft Structuralism (Consumer / Health / Portfolio):** Silver-grey or pure white backgrounds, bold grotesk typography, airy floating components with ultra-diffuse ambient shadows.
-
-#### Layout Archetypes
-
-1. **The Asymmetrical Bento:** Masonry CSS Grid of varying card spans. (Collapses to single-column `grid-cols-1 gap-6` on mobile).
-2. **The Z-Axis Cascade:** Stacked cards with varying depth of field and subtle `-2deg` or `3deg` rotations. (Rotations removed on mobile).
-3. **The Editorial Split:** Massive typography on the left half (`w-1/2`), with horizontal interactive card ribbons on the right.
-
-### 3. Haptic Micro-Aesthetics
-
-- **The Double-Bezel (Doppelrand):**
-  - **Outer Shell:** Wrapper `div` with subtle background (`bg-black/5` or `bg-white/5`), hairline border (`border border-white/10`), padding (`p-2`), and large outer radius (`rounded-[2rem]`).
-  - **Inner Core:** Nested card inside shell with distinct background, inner highlight (`shadow-[inset_0_1px_1px_rgba(255,255,255,0.15)]`), and mathematically concentric smaller radius (`rounded-[calc(2rem-0.5rem)]`).
-- **Button-in-Button Trailing Icon:** Pill-shaped primary buttons (`rounded-full px-6 py-3`) with trailing arrows nested inside their own dedicated circular badge (`w-8 h-8 rounded-full bg-black/5 flex items-center justify-center`).
-- **Macro-Whitespace:** Minimum `py-24` to `py-40` for section padding.
-
-### 4. Motion Choreography & Performance Guardrails
-
-- **Custom Physics:** All transitions use custom cubic-beziers: `transition-all duration-700 ease-[cubic-bezier(0.32,0.72,0,1)]`.
-- **GPU-Safe Animation:** Animate exclusively via `transform` and `opacity`. Never animate `top`, `left`, `width`, or `height`.
-- **Blur Discipline:** Restrict `backdrop-blur` to fixed or sticky elements (navbars, modals). Never apply to scrolling containers.
-
-## Code Examples
-
-```tsx
-export function DoubleBezelCard({ title, subtitle, tag }: { title: string; subtitle: string; tag: string }) {
-  return (
-    // Outer Shell
-    <div className="p-2 rounded-[2rem] bg-black/5 dark:bg-white/5 border border-black/10 dark:border-white/10 transition-all duration-700 ease-[cubic-bezier(0.32,0.72,0,1)] hover:shadow-2xl">
-      // Inner Core
-      <div className="p-8 rounded-[calc(2rem-0.5rem)] bg-[#FFFFFF] dark:bg-[#0E0E0E] shadow-[inset_0_1px_1px_rgba(255,255,255,0.15)] flex flex-col justify-between min-h-[320px]">
-        <div>
-          <span className="inline-block px-3 py-1 rounded-full text-[10px] uppercase tracking-[0.2em] font-medium bg-black/5 dark:bg-white/10 text-neutral-600 dark:text-neutral-400 mb-4">
-            {tag}
-          </span>
-          <h3 className="text-2xl font-bold tracking-tight text-neutral-900 dark:text-white mb-2">{title}</h3>
-          <p className="text-sm text-neutral-500 dark:text-neutral-400 leading-relaxed">{subtitle}</p>
-        </div>
-        <button 
-          type="button" 
-          className="group mt-6 inline-flex items-center justify-between pl-6 pr-2 py-2 rounded-full bg-neutral-900 dark:bg-white text-white dark:text-neutral-950 font-medium text-sm active:scale-[0.98] transition-all duration-300"
-        >
-          <span>Explore Experience</span>
-          <span className="w-8 h-8 rounded-full bg-white/10 dark:bg-black/10 flex items-center justify-center transition-transform duration-300 group-hover:translate-x-0.5 group-hover:-translate-y-0.5">
-            ↗
-          </span>
-        </button>
-      </div>
-    </div>
-  );
-}
-```
-
-## Validation Checklist
-
-- [ ] All major cards and interactive modules use the Double-Bezel concentric architecture.
-- [ ] Primary buttons feature the nested button-in-button trailing icon pattern.
-- [ ] Section vertical padding is at minimum `py-24`.
-- [ ] Transitions use spring or custom cubic-bezier curves (no default linear transitions).
-- [ ] Layout collapses gracefully to single-column on mobile viewports (<768px).
-- [ ] Animations use only `transform` and `opacity`.
-
-## Common Mistakes
-
-- Using standard `shadow-md` or harsh dark drop shadows instead of soft ambient shadows.
-- Failing to recalculate concentric inner border-radii (`calc(outer - padding)`).
-- Applying `backdrop-blur` on large scrolling sections, triggering GPU repaints.
-- Sticking to generic 3-column Bootstrap grids.
-
-## Integration Notes
-
-- Complements `impeccable-design` for QA and anti-pattern enforcement.
-- Pairs with `ui-ux-pro` for color palette harmony and accessibility compliance.

package/.agents/core/skills/soft-design/VALIDATION.json

@@ -1,12 +0,0 @@
-{
-  "$schema": "http://json-schema.org/draft-07/schema#",
-  "type": "object",
-  "properties": {
-    "rules_followed": {
-      "type": "boolean"
-    }
-  },
-  "required": [
-    "rules_followed"
-  ]
-}

package/.agents/core/skills/soft-design/skill.yaml

@@ -1,12 +0,0 @@
-name: soft-design
-type: instruction-only
-description: High-end agency-grade UI architecture, haptic micro-aesthetics, and fluid spring motion choreography.
-tags:
-  - ui
-  - design
-  - premium
-  - motion
-version: 1.0.0
-resources:
-  - SKILL.md
-  - VALIDATION.json

package/.agents/core/skills/state-management/EXAMPLES.md

@@ -1,56 +0,0 @@
-# State Management Examples — Anti-patterns vs ContextOS Standard
-
-## Example 1: Selecting State from Zustand
-
-### Anti-pattern: Anti-pattern (Subscribing to full store causes unnecessary renders)
-
-```typescript
-// BAD: component re-renders whenever ANY property in the store changes!
-function CartBadge() {
-  const store = useCartStore(); // subscribes to entire object!
-  return <span>{store.items.length}</span>;
-}
-```
-
-### Best practice: ContextOS Standard (Atomic granular selector)
-
-```typescript
-// GOOD: component ONLY re-renders when itemCount changes
-function CartBadge() {
-  const itemCount = useCartStore((state) => state.items.length);
-  return <span>{itemCount}</span>;
-}
-```
-
----
-
-## Example 2: Server State Invalidation
-
-### Anti-pattern: Anti-pattern (Manually syncing server data into global state with useEffect)
-
-```typescript
-// BAD: manual sync, race conditions, stale cache bugs
-function UserProfile({ userId }) {
-  const { setUser } = useUserStore();
-  useEffect(() => {
-    fetch(`/api/users/${userId}`).then(res => res.json()).then(setUser);
-  }, [userId]);
-}
-```
-
-### Best practice: ContextOS Standard (Declarative TanStack Query caching)
-
-```typescript
-// GOOD: automatic caching, deduplication, background revalidation
-function UserProfile({ userId }: { userId: string }) {
-  const { data: user, isLoading, error } = useQuery({
-    queryKey: ['users', userId],
-    queryFn: () => fetchUserById(userId),
-    staleTime: 1000 * 60 * 5, // 5 minutes fresh
-  });
-
-  if (isLoading) return <SkeletonLoader />;
-  if (error) return <ErrorMessage error={error} />;
-  return <UserDetails user={user} />;
-}
-```

package/.agents/core/skills/state-management/SKILL.md

@@ -1,48 +0,0 @@
----
-name: state-management
-description: Client and server state management standards using Zustand and TanStack Query. Enforces minimal global state, optimistic updates, and clean query invalidation.
----
-
-# State Management
-
-## Overview
-
-Global client state and server state management in modern React and Next.js applications using Zustand and TanStack Query.
-
-## When to Use
-
-Activate when managing asynchronous server data fetching/caching, optimistic UI updates, or global UI client state (modals, filters, wizards).
-
-## Rules & Patterns
-
-### The Rule of Two States
-
-- **SERVER STATE (Async)**: Managed exclusively by TanStack Query (`useQuery`, `useMutation`). Caching, background refetching, pagination, and invalidation.
-- **CLIENT STATE (Sync)**: Managed by Zustand. Modal visibility, active filters, wizard step, theme.
-
-### Negative Constraints (What NOT to Do)
-
-1. **NEVER store server-fetched data in Zustand or Redux stores**: Store ONLY client-local UI state in Zustand. All API data belongs in TanStack Query.
-2. **NEVER duplicate derived state**: Compute values inline or via `useMemo` from existing state instead of storing redundant state variables.
-3. **NEVER subscribe to entire store objects in components**: Always use atomic selector functions (e.g. `useStore(state => state.isOpen)`) to prevent unnecessary component re-renders.
-4. **NEVER mutate state directly**: Always return new immutable state objects in Zustand setters.
-5. **NEVER ignore optimistic rollback on mutation failure**: When implementing optimistic UI, always capture `previousData` in `onMutate` and restore it in `onError`.
-
-## Code Examples
-
-See `EXAMPLES.md` for Zustand store patterns and optimistic TanStack mutations.
-
-## Validation Checklist
-
-- [ ] Clear separation between Server (TanStack Query) and Client (Zustand) state
-- [ ] Atomic selectors used on all Zustand hook calls
-- [ ] Optimistic updates implement rollback on error
-- [ ] Zero duplicated derived state
-
-## Common Mistakes
-
-- Subscribing to full store objects causing cascading re-renders. See `TROUBLESHOOTING.md`.
-
-## Integration Notes
-
-Interacts with `react`, `nextjs`, and `typescript`.

package/.agents/core/skills/state-management/TROUBLESHOOTING.md

@@ -1,18 +0,0 @@
-# State Management Troubleshooting Guide
-
-## Common Issues & Fixes
-
-### 1. Infinite re-renders when calling `useStore` with an inline object selector
-
-- **Cause**: Returning a new object reference from a selector without a custom equality check.
-- **Fix**: Use `useShallow` from `zustand/react/shallow` or select scalar values directly.
-
-### 2. Stale data shown after mutation
-
-- **Cause**: Missing `queryClient.invalidateQueries` in `onSettled` or `onSuccess`.
-- **Fix**: Always invalidate the relevant query keys on mutation completion to trigger background refetch.
-
-### 3. Server-Side Rendering (SSR) Hydration Mismatch in Next.js
-
-- **Cause**: Reading localStorage-persisted Zustand store directly during initial SSR render.
-- **Fix**: Use a custom `useHydratedStore` hook or render persisted components only after client mount.

package/.agents/core/skills/state-management/VALIDATION.json

@@ -1,11 +0,0 @@
-{
-  "skill": "state-management",
-  "version": "1.0.0",
-  "checks": [
-    "Strict separation between Server and Client state",
-    "No server API responses cached in Zustand",
-    "Granular atomic selectors used for component subscriptions",
-    "Optimistic mutations include rollback handler",
-    "Zero duplicated derived state"
-  ]
-}

package/.agents/core/skills/state-management/skill.yaml

@@ -1,28 +0,0 @@
-name: state-management
-description: Client and server state management standards using Zustand and TanStack Query. Enforces minimal global state, optimistic updates, and clean query invalidation.
-version: 1.0.0
-category: frontend
-type: instruction-only
-requires:
-  - react
-  - typescript
-triggers:
-  files:
-    - "*store*"
-    - "*state*"
-    - "use*Query.ts"
-    - "use*Mutation.ts"
-  keywords:
-    - "zustand"
-    - "tanstack"
-    - "react-query"
-    - "state"
-    - "store"
-    - "optimistic"
-    - "mutation"
-    - "cache"
-resources:
-  - EXAMPLES.md
-  - SKILL.md
-  - TROUBLESHOOTING.md
-  - VALIDATION.json