contextos-agents 2.1.0 → 2.1.1

package/catalog/skills/security-audit/SKILL.md

@@ -0,0 +1,91 @@
+---
+name: security-audit
+description: Security guidance and vulnerability review for codebases, APIs, and services. Orchestrates adversarial hunting and independent verification with sandbox write isolation and evidence ledgers.
+---
+
+# Security Audit
+
+Find vulnerabilities that violate a real trust boundary, then give owners source evidence, safe reproduction, priority, and the smallest effective fix. This is a defensive, source-first workflow inspired by Cloudflare's security audit architecture.
+
+## Operating Modes
+
+This skill operates in two distinct modes:
+
+- **Guidance Mode**: For security questions, focused reviews, threat modeling, or triage of specific components, use only the relevant parts of this skill. Do not automatically create audit directories or write audit artifacts.
+- **Full Audit Mode**: Use the complete workflow when explicitly requested to audit, pen-test, or perform an end-to-end security review of a repository. Run all phases and generate structured artifacts.
+
+## Adversarial Multi-Agent Audit Protocol
+
+A core invariant of rigorous security auditing is adversarial verification:
+
+1. **Separation of Hunter and Verifier**:
+   - The agent that discovers a candidate vulnerability (**Hunter**) must never be the same agent that validates it.
+   - The verifying agent (**Verifier**) starts with a fresh context and explicitly attempts to disprove each finding.
+2. **Evidence-Based Standard**:
+   - A candidate vulnerability is confirmed only if it has a complete source trace from untrusted input to a sensitive sink, along with a bounded, observable defect.
+   - If an issue cannot be definitively reproduced or disproven locally, mark it as `needs_validation` rather than creating speculative findings.
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    SECURITY AUDIT PIPELINE                  │
+│                                                             │
+│  Phase 1: Reconnaissance (Map trust boundaries & inputs)    │
+│                     ↓                                       │
+│  Phase 2: Coverage Hunting (Hunter agents search surfaces)  │
+│                     ↓                                       │
+│  Phase 3: Candidate Validation (Verifier agents disprove)   │
+│                     ↓                                       │
+│  Phase 4: Structured Output (findings.json & ledger)        │
+│                     ↓                                       │
+│  Phase 5: Record Verification (Final attestation review)    │
+│                     ↓                                       │
+│  Phase 6: Target-Neutral Reporting (REPORT.md)              │
+└─────────────────────────────────────────────────────────────┘
+```
+
+## Universal Execution Safety & Sandbox Write Isolation
+
+Target repositories must be audited without risking supply-chain compromise or data exfiltration:
+
+- **Read-Only Target Code**: Source inspection is read-only. Target code must never be executed with write access to its own repository.
+- **Dedicated Scratch Root**: All target-controlled builds, tests, or reproduction scripts execute inside an isolated sandbox writing strictly to `scratch/`.
+- **Zero External Network**: Sandboxed processes must have no outbound internet access. Use isolated loopback namespaces if local client/server communication is needed.
+- **Sanitized Environment**: Clear credentials, SSH keys, cloud tokens, and parent process environments before spawning reproduction commands.
+- **Promotion to Artifacts**: Only trusted parent-side code may inspect and promote non-secret results from `scratch/` to retained `artifacts/`.
+
+## Audit Artifacts & Findings Schema
+
+Full audits produce machine-readable and human-readable artifacts:
+
+### findings.json
+```json
+{
+  "audit_version": "1.0.0",
+  "target_repository": "example-repo",
+  "commit_hash": "a1b2c3d",
+  "findings": [
+    {
+      "id": "SEC-001",
+      "title": "Path Traversal in File Download Handler",
+      "severity": "HIGH",
+      "cwe": "CWE-22",
+      "source_trace": {
+        "source_file": "src/controllers/download.ts",
+        "source_line": 42,
+        "entry_point": "req.query.filename",
+        "sink_file": "src/services/storage.ts",
+        "sink_line": 88,
+        "sink_function": "fs.promises.readFile"
+      },
+      "verification_status": "CONFIRMED",
+      "verifier_notes": "Reproduction script proved escape from base directory using %2e%2e%2f traversal.",
+      "remediation": "Apply path.normalize and verify path.resolve starts with the designated root directory."
+    }
+  ]
+}
+```
+
+### Required Reports
+- `REPORT.md`: Executive summary, risk score, vulnerability distribution, and remediation priorities.
+- `FINDINGS-DETAIL.md`: Detailed technical breakdown of each confirmed finding with step-by-step reproduction and surgical diff recommendations.
+- `NEEDS-VALIDATION.md`: Potential leads that could not be conclusively verified without live cloud infrastructure or out-of-scope permissions.

package/catalog/skills/security-audit/TROUBLESHOOTING.md

@@ -0,0 +1,46 @@
+# Security Audit - Troubleshooting & Common Edge Cases
+
+## Common Diagnostic Scenarios
+
+### 1. Hunter Agent Generates Speculative or Untraceable Findings
+
+- **Symptom**: Candidate vulnerability report contains vague descriptions like "Potential SQL injection in database layer" without line numbers, parameters, or affected sinks.
+- **Root Cause**: The Hunter agent skipped Step 1 (Reconnaissance) and performed heuristic keyword matching instead of taint tracking.
+- **Fix Protocol**:
+  1. Reject candidate immediately: mark status as `INVALID_SPECULATION`.
+  2. Mandate the 3-point trace requirement:
+     - Entry Point (HTTP param, header, body field, CLI flag).
+     - Intermediate Propagation (functions, transforms, assignments).
+     - Sensitive Sink (database query, filesystem access, shell execution, reflection).
+  3. If any of the three points is missing, the candidate cannot be submitted to the Verifier.
+
+---
+
+### 2. Sandbox File Promotion Failure (`scratch/` to `artifacts/`)
+
+- **Symptom**: Parent process fails to copy verified findings or test outputs from `scratch/` to `artifacts/`, throwing an access violation or promotion blocker.
+- **Root Cause**: Target-controlled code created symlinks, hardlinks, or unescaped nested paths attempting to escape the assigned scratch root.
+- **Fix Protocol**:
+  1. Never perform recursive copy or glob promotion across boundaries.
+  2. Walk paths with `no-follow` directory descriptors.
+  3. Verify that the leaf is a regular file with link count exactly 1 and size within the byte allowance.
+  4. Discard any entry violating promotion bounds and log `PROMOTION_SECURITY_REJECT`.
+
+---
+
+### 3. Loopback Port Collisions During Local Reproduction
+
+- **Symptom**: Standalone verification script fails with `EADDRINUSE: address already in use 127.0.0.1:3000`.
+- **Root Cause**: Fixed port numbers in reproduction tests collide with existing developer processes.
+- **Fix Protocol**:
+  - Always bind reproduction servers to port `0` (`server.listen(0)`), allowing the OS to allocate an ephemeral free port.
+  - Read `server.address().port` dynamically in test fixtures.
+
+---
+
+### 4. False Positives Due to Upstream Middleware Sanitization
+
+- **Symptom**: Hunter flags `req.query.path` passed to `res.sendFile`, but global Express middleware already calls `path.normalize` and rejects relative traversals.
+- **Root Cause**: Single-file inspection without analyzing the global middleware chain.
+- **Fix Protocol**:
+  - The Verifier agent must inspect the application entrypoint (`app.ts`, `server.ts`, router configuration) to verify active global filters before concluding the audit verdict.

package/catalog/skills/security-audit/VALIDATION.json

@@ -0,0 +1,11 @@
+{
+  "skill": "security-audit",
+  "version": "1.0.0",
+  "checks": [
+    "Hunter and verifier roles are strictly separated",
+    "Evidence-based verification requires complete source trace",
+    "Target code is executed in read-only sandbox writing only to scratch/",
+    "Findings are documented in structured findings.json format",
+    "Remediations adhere to surgical blast radius containment"
+  ]
+}

package/catalog/skills/security-audit/skill.yaml

@@ -0,0 +1,14 @@
+schemaVersion: 2
+name: security-audit
+description: Adversarial multi-agent security audit framework inspired by Cloudflare. Employs independent hunter and verifier roles, OS sandbox write isolation, and evidence-backed vulnerability verification.
+version: 1.0.0
+category: engineering
+type: instruction-only
+requires:
+  - engineering-workflow
+  - security
+resources:
+  - EXAMPLES.md
+  - SKILL.md
+  - TROUBLESHOOTING.md
+  - VALIDATION.json

package/catalog/skills/soft-design/EXAMPLES.md

@@ -0,0 +1,51 @@
+# Soft Design - Component & Layout Examples
+
+## Example 1: Glassmorphic Elevated Panel
+
+```tsx
+import React from 'react';
+
+interface SoftPanelProps {
+  title: string;
+  category: string;
+  children: React.ReactNode;
+}
+
+export function SoftElevatedPanel({ title, category, children }: SoftPanelProps) {
+  return (
+    <div className="relative overflow-hidden rounded-3xl border border-white/40 bg-white/60 p-8 shadow-[0_20px_50px_rgba(8,_112,_184,_0.07)] backdrop-blur-xl transition-all duration-300 hover:shadow-[0_30px_60px_rgba(8,_112,_184,_0.12)]">
+      {/* Subtle ambient light gradient */}
+      <div className="pointer-events-none absolute -right-20 -top-20 h-56 w-56 rounded-full bg-gradient-to-br from-indigo-200/50 to-pink-200/30 blur-2xl" />
+
+      <div className="relative z-10">
+        <span className="inline-block rounded-full bg-indigo-50/80 px-3 py-1 text-xs font-medium text-indigo-600 backdrop-blur-sm">
+          {category}
+        </span>
+        <h2 className="mt-4 text-2xl font-normal tracking-tight text-slate-800">
+          {title}
+        </h2>
+        <div className="mt-6 text-slate-600 leading-relaxed">
+          {children}
+        </div>
+      </div>
+    </div>
+  );
+}
+```
+
+---
+
+## Example 2: Soft Tactile Pill Button
+
+```tsx
+export function SoftPillButton({ label, onClick }: { label: string; onClick: () => void }) {
+  return (
+    <button
+      onClick={onClick}
+      className="rounded-full bg-gradient-to-b from-indigo-500 to-indigo-600 px-6 py-3 text-sm font-medium text-white shadow-[0_10px_20px_-5px_rgba(79,_70,_229,_0.3)] transition-all duration-200 hover:scale-[1.02] hover:shadow-[0_15px_25px_-5px_rgba(79,_70,_229,_0.4)] active:scale-[0.98]"
+    >
+      {label}
+    </button>
+  );
+}
+```

package/catalog/skills/soft-design/SKILL.md

@@ -0,0 +1,108 @@
+---
+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/catalog/skills/soft-design/VALIDATION.json

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

package/catalog/skills/soft-design/skill.yaml

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

package/catalog/skills/state-management/EXAMPLES.md

@@ -0,0 +1,56 @@
+# 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/catalog/skills/state-management/SKILL.md

@@ -0,0 +1,168 @@
+---
+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 asynchronous server state architecture in modern React and Next.js applications using Zustand and TanStack Query v5.
+
+## When to Use
+
+Activate when managing asynchronous server data fetching, HTTP caching, optimistic UI updates, or global synchronous client UI state (modals, active filters, multi-step wizards, theme overrides).
+
+## Rules & Patterns
+
+### The Rule of Two States
+
+1. **SERVER STATE (Async)**: Managed exclusively by TanStack Query (`useQuery`, `useMutation`). Handles HTTP caching, stale-while-revalidate, deduplication, background refetching, pagination, and query invalidation.
+2. **CLIENT STATE (Sync)**: Managed by Zustand. Handles transient UI state: modal visibility, sidebar collapsed state, active filter values, wizard steps, and offline draft buffers.
+
+### Negative Constraints (What NOT to Do)
+
+1. **NEVER store server-fetched entity data in Zustand or Redux**: Store ONLY client-local UI state in Zustand. All API responses, lists, and entity records belong 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)`) or `useShallow` 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`.
+6. **NEVER use ad-hoc array strings for query keys**: Always define and use a centralized Query Key Factory to guarantee consistent cache invalidation.
+
+---
+
+### Pattern 1: Zustand Slices Architecture
+
+Split large global stores into focused, typed slices that compose into a single unified hook:
+
+```typescript
+import { create, StateCreator } from 'zustand';
+import { devtools } from 'zustand/middleware';
+
+interface UiSlice {
+  isSidebarOpen: boolean;
+  activeModal: string | null;
+  toggleSidebar: () => void;
+  openModal: (modalId: string) => void;
+  closeModal: () => void;
+}
+
+const createUiSlice: StateCreator<UiSlice> = (set) => ({
+  isSidebarOpen: true,
+  activeModal: null,
+  toggleSidebar: () => set((state) => ({ isSidebarOpen: !state.isSidebarOpen })),
+  openModal: (modalId) => set({ activeModal: modalId }),
+  closeModal: () => set({ activeModal: null }),
+});
+
+export const useAppStore = create<UiSlice>()(
+  devtools((...args) => ({
+    ...createUiSlice(...args),
+  }))
+);
+```
+
+---
+
+### Pattern 2: Atomic Selectors & Re-render Prevention
+
+Always pass specific selector functions to extract only the state your component needs:
+
+```typescript
+// [BAD] Subscribes to the entire store; re-renders on ANY store change
+const { isSidebarOpen, activeModal } = useAppStore();
+
+// [GOOD] Subscribes only to isSidebarOpen; re-renders ONLY when it changes
+const isSidebarOpen = useAppStore((state) => state.isSidebarOpen);
+
+// [GOOD] Multiple values extracted without extra re-renders using useShallow
+import { useShallow } from 'zustand/react/shallow';
+
+const { isSidebarOpen, activeModal } = useAppStore(
+  useShallow((state) => ({
+    isSidebarOpen: state.isSidebarOpen,
+    activeModal: state.activeModal,
+  }))
+);
+```
+
+---
+
+### Pattern 3: TanStack Query Key Factory Standard
+
+Maintain a structured hierarchy of query keys for predictable invalidation:
+
+```typescript
+export const projectKeys = {
+  all: ['projects'] as const,
+  lists: () => [...projectKeys.all, 'list'] as const,
+  list: (filters: ProjectFilters) => [...projectKeys.lists(), filters] as const,
+  details: () => [...projectKeys.all, 'detail'] as const,
+  detail: (id: string) => [...projectKeys.details(), id] as const,
+};
+```
+
+---
+
+### Pattern 4: Optimistic Mutation with Rollback
+
+Safely update UI instantly and roll back on network or server error:
+
+```typescript
+import { useMutation, useQueryClient } from '@tanstack/react-query';
+import { projectKeys } from './query-keys';
+
+export function useUpdateProject() {
+  const queryClient = useQueryClient();
+
+  return useMutation({
+    mutationFn: (updated: { id: string; name: string }) => api.patch(`/projects/${updated.id}`, updated),
+    onMutate: async (newProject) => {
+      // 1. Cancel outgoing queries to avoid overwriting optimistic update
+      await queryClient.cancelQueries({ queryKey: projectKeys.detail(newProject.id) });
+
+      // 2. Snapshot the previous value
+      const previousProject = queryClient.getQueryData(projectKeys.detail(newProject.id));
+
+      // 3. Optimistically update the cache
+      queryClient.setQueryData(projectKeys.detail(newProject.id), (old: any) => ({
+        ...old,
+        ...newProject,
+      }));
+
+      // 4. Return context with snapshot for rollback
+      return { previousProject, projectId: newProject.id };
+    },
+    onError: (err, newProject, context) => {
+      // 5. Rollback to snapshot on failure
+      if (context?.previousProject) {
+        queryClient.setQueryData(projectKeys.detail(context.projectId), context.previousProject);
+      }
+    },
+    onSettled: (data, err, variables) => {
+      // 6. Always re-sync with server after error or success
+      queryClient.invalidateQueries({ queryKey: projectKeys.detail(variables.id) });
+    },
+  });
+}
+```
+
+---
+
+## Validation Checklist
+
+- [ ] Clear separation: Server state in TanStack Query, client UI state in Zustand.
+- [ ] Atomic selectors or `useShallow` used on all store consumers.
+- [ ] Centralized Query Key Factory used for all `queryKey` definitions.
+- [ ] Optimistic mutations implement `onMutate`, `onError` rollback, and `onSettled` invalidation.
+- [ ] Zero duplicated or redundant derived state stored in global stores.
+
+## Common Mistakes
+
+- **Storing API collections in Zustand**: Results in stale data and duplicate caching layers. Use TanStack Query.
+- **Missing query cancellation in onMutate**: Causes race conditions between ongoing fetches and optimistic updates.
+- **Forgetting atomic selectors**: Causes every component reading one store value to re-render when an unrelated value changes.
+
+## Integration Notes
+
+Interacts with `react`, `nextjs`, and `typescript`.

package/catalog/skills/state-management/TROUBLESHOOTING.md

@@ -0,0 +1,18 @@
+# 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/catalog/skills/state-management/VALIDATION.json

@@ -0,0 +1,11 @@
+{
+  "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/catalog/skills/state-management/skill.yaml

@@ -0,0 +1,14 @@
+schemaVersion: 2
+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
+resources:
+  - EXAMPLES.md
+  - SKILL.md
+  - TROUBLESHOOTING.md
+  - VALIDATION.json