contextos-agents 1.7.0 → 2.0.0-beta.3

package/.agents/generated/gemini/skills/soft-design/SKILL.md

@@ -1,109 +0,0 @@
----
-name: soft-design
-description: >
-  High-end agency-grade UI architecture, haptic micro-aesthetics, and fluid spring motion choreography.
----
-# 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/generated/gemini/skills/state-management/SKILL.md

@@ -1,129 +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`.
-
-
-<!-- Source: EXAMPLES.md -->
-
-# 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} />;
-}
-```
-
-<!-- Source: TROUBLESHOOTING.md -->
-
-# 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/gemini/skills/subagent-orchestrator/SKILL.md

@@ -1,116 +0,0 @@
----
-name: subagent-orchestrator
-description: >
-  Subagent delegation and parallel coordination skill. Implements task decomposition, context hand-offs, blast-radius boundary isolation, and conflict-free merge synthesis.
----
-# 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 must be backed by an immutable `TaskBrief`:
-
-```ts
-type TaskBrief = Readonly<{
-  taskId: string;
-  baseSha: string;
-  objective: string;
-  writeScope: readonly string[];
-  testCommand: string;
-  expectedResult: string;
-  maxAttempts: number;
-}>;
-```
-
-Create the brief once before dispatch. Agents and retry loops must reuse it without
-changing the base commit, scope, verification command, or acceptance result.
-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 worker received an immutable `TaskBrief` tied to the original `baseSha`.
-- [ ] 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.
-