contextos-agents 1.5.0

package/.agents/generated/claude/skills/state-management/SKILL.md

@@ -0,0 +1,120 @@
+# 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`.
+
+
+# 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} />;
+}
+```
+
+# 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/generated/claude/skills/subagent-orchestrator/SKILL.md

@@ -0,0 +1,93 @@
+# subagent-orchestrator
+
+## Overview
+
+Multi-agent coordination protocol inspired by [obra/superpowers](https://github.com/obra/superpowers). Enables a primary orchestrating agent to decompose complex workflows into isolated, parallel sub-tasks, delegate them with precise context boundaries, monitor execution, and synthesize outputs with zero merge conflicts.
+
+## When to Use
+
+Activate whenever:
+
+- A task can be parallelized across distinct modules, services, or test suites.
+- Long-running exploratory research or multi-file refactoring exceeds single-context budget.
+- Running autonomous subagent workers for specialized roles (e.g. specialized QA tester, Security auditor, Docs generator).
+
+## Rules & Patterns
+
+### 1. The Blast Radius Boundary Rule
+
+Before delegating any subagent task:
+
+- **Zero File Overlap**: Each subagent MUST have a mutually exclusive list of target files. Two subagents must never be instructed to edit the same file concurrently.
+- **Explicit Inputs & Outputs**: Provide only the minimal schema, contract, or mock that the subagent needs. Do not dump the entire workspace into subagent prompts.
+
+### 2. The 4-Step Delegation Lifecycle
+
+```
+[ Orchestrator ]
+       │
+       ├─▶ 1. DECOMPOSE: Break into orthogonal tasks with non-overlapping file sets
+       │
+       ├─▶ 2. DISPATCH: Launch subagent with precise goal, constraints, and finish criteria
+       │
+       ├─▶ 3. AWAIT & VERIFY: Validate subagent output against its individual quality gate
+       │
+       └─▶ 4. SYNTHESIZE: Merge subagent results into the main branch and run global regression suite
+```
+
+### 3. Context Hand-off Specification
+
+Every subagent dispatch prompt must contain:
+
+1. **Target Objective**: Single, verifiable deliverable.
+2. **Read-Only Context**: Files to consult as reference without modifying.
+3. **Write Scope**: Exact file paths the subagent is permitted to create or modify.
+4. **Completion Signal**: Explicit instruction to report `DONE` with test evidence or `BLOCKED` with reason.
+
+---
+
+## Code Examples
+
+### Orchestrator Task Dispatch Template
+
+```markdown
+**Subagent Task: Order Validation Service**
+
+- **Role**: `[ROLE: Senior Developer]`
+- **Goal**: Implement Zod validation schema and unit tests for order payloads.
+- **Write Scope**:
+  - `src/services/order/validation.ts`
+  - `tests/services/order/validation.test.ts`
+- **Read-Only Reference**:
+  - `src/types/order.ts`
+- **Quality Gate**:
+  - Run `npx vitest run tests/services/order/validation.test.ts`
+  - All tests must pass with 100% coverage of validation rules.
+- **Finish Criteria**:
+  - Report exact test output and finish with `DONE`.
+```
+
+---
+
+## Validation Checklist
+
+- [ ] All delegated tasks have disjoint, non-overlapping file sets.
+- [ ] Every subagent prompt has explicit read vs write boundaries.
+- [ ] Subagent results verified individually before merging.
+- [ ] Global regression suite executed across the entire repository after all subagents finish.
+
+---
+
+## Common Mistakes
+
+- **Concurrent file collisions**: Assigning two subagents to modify the same route handler or lockfile.
+- **Unbounded delegation**: Asking a subagent to "improve the codebase" without specific file limits.
+- **Trusting without verification**: Assuming subagent code works without executing the test gate in the parent context.
+
+---
+
+## Integration Notes
+
+- Integrates with `engineering-workflow` during the PLAN and BUILD phases.
+- Works directly with `gstack-roles` to assign specific specialist personas to each subagent.
+- Employs `ponytail-mindset` to keep subagent implementations minimal.