contextos-agents 1.5.0

package/.agents/core/skills/security/skill.yaml

@@ -0,0 +1,10 @@
+id: security
+name: Application Security
+category: backend
+tags: [backend, security, auth, owasp, jwt, encryption]
+requires: []
+optional: [node, fastapi, nestjs]
+conflicts: []
+weight: 9
+documents:
+  - security.md

package/.agents/core/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/.agents/core/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/.agents/core/skills/soft-design/skill.yaml

@@ -0,0 +1,8 @@
+name: soft-design
+description: High-end agency-grade UI architecture, haptic micro-aesthetics, and fluid spring motion choreography.
+tags:
+  - ui
+  - design
+  - premium
+  - motion
+version: 1.0.0

package/.agents/core/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/.agents/core/skills/state-management/SKILL.md

@@ -0,0 +1,48 @@
+---
+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

@@ -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/.agents/core/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/.agents/core/skills/state-management/skill.yaml

@@ -0,0 +1,22 @@
+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
+requires:
+  - react
+  - typescript
+triggers:
+  files:
+    - "*store*"
+    - "*state*"
+    - "use*Query.ts"
+    - "use*Mutation.ts"
+  keywords:
+    - "zustand"
+    - "tanstack"
+    - "react-query"
+    - "state"
+    - "store"
+    - "optimistic"
+    - "mutation"
+    - "cache"

package/.agents/core/skills/subagent-orchestrator/SKILL.md

@@ -0,0 +1,100 @@
+---
+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 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.

package/.agents/core/skills/subagent-orchestrator/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/.agents/core/skills/subagent-orchestrator/skill.yaml

@@ -0,0 +1,8 @@
+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.
+tags:
+  - subagents
+  - orchestration
+  - multi-agent
+  - workflow
+version: 1.0.0

package/.agents/core/skills/system-design/EXAMPLES.md

@@ -0,0 +1,75 @@
+# system-design Examples — Anti-patterns vs ContextOS Standard
+
+## Example 1: Database Caching Strategy
+
+### Anti-pattern: Cache-Aside with Unbounded Thundering Herd
+
+```typescript
+// BAD: When cache expires, 10,000 concurrent requests hit PostgreSQL simultaneously
+async function getUserProfile(id: string) {
+  const cached = await redis.get(`user:${id}`);
+  if (cached) return JSON.parse(cached);
+  const user = await db.user.findUnique({ where: { id } });
+  await redis.set(`user:${id}`, JSON.stringify(user), 'EX', 300);
+  return user;
+}
+```
+
+### Best practice: ContextOS Standard (Mutex Lock / Single-Flight Pattern)
+
+```typescript
+// GOOD: Only one worker fetches from DB on cache miss; others wait
+import { singleflight } from './singleflight';
+
+async function getUserProfile(id: string) {
+  const cached = await redis.get(`user:${id}`);
+  if (cached) return JSON.parse(cached);
+
+  return singleflight.do(`user:${id}`, async () => {
+    const fresh = await redis.get(`user:${id}`);
+    if (fresh) return JSON.parse(fresh);
+
+    const user = await db.user.findUnique({ where: { id } });
+    if (user) {
+      await redis.set(`user:${id}`, JSON.stringify(user), 'EX', 300);
+    }
+    return user;
+  });
+}
+```
+
+---
+
+## Example 2: Outbox Pattern for Distributed Consistency
+
+### Anti-pattern: Dual-Write Anti-pattern (Direct DB write + Kafka publish)
+
+```typescript
+// BAD: If Kafka publish fails, DB change is committed but event is lost forever
+async function createOrder(data: OrderInput) {
+  const order = await db.order.create({ data });
+  await kafkaProducer.send({ topic: 'orders', messages: [{ value: JSON.stringify(order) }] });
+  return order;
+}
+```
+
+### Best practice: ContextOS Standard (Transactional Outbox)
+
+```typescript
+// GOOD: Order and Outbox record committed in a single atomic DB transaction
+async function createOrder(data: OrderInput) {
+  return await db.$transaction(async (tx) => {
+    const order = await tx.order.create({ data });
+    await tx.outbox.create({
+      data: {
+        aggregateType: 'Order',
+        aggregateId: order.id,
+        eventType: 'OrderCreated',
+        payload: JSON.stringify(order),
+        status: 'PENDING',
+      },
+    });
+    return order;
+  });
+}
+```