contextos-agents 1.5.0

package/.agents/generated/gemini/skills/performance/SKILL.md

@@ -0,0 +1,185 @@
+---
+name: Web Performance
+description: >
+  ContextOS skill for Web Performance
+---
+# Web Performance & Core Web Vitals
+
+## Overview
+
+Enforces high-efficiency frontend and full-stack performance standards to achieve exceptional Core Web Vitals: Largest Contentful Paint (LCP < 2.5s), Interaction to Next Paint (INP < 200ms), and Cumulative Layout Shift (CLS < 0.1).
+
+## When to Use
+
+Activate whenever analyzing, profiling, writing, or optimizing page loading speeds, network waterfalls, script bundling, animation frame rates, or data caching.
+
+## Negative Constraints (What NOT to Do)
+
+1. **NEVER introduce async waterfalls**: Do not chain sequential `await` calls when requests can be executed concurrently via `Promise.all()`.
+2. **NEVER import large full libraries when only a utility is needed**: Never `import _ from 'lodash'`; use `import debounce from 'lodash/debounce'` or native alternatives.
+3. **NEVER render images or videos without explicit aspect ratios**: Always provide `width` and `height` or `aspect-ratio` to avoid Cumulative Layout Shift (CLS).
+4. **NEVER trigger synchronous layout thrashing**: Do not alternate between reading layout properties (`offsetHeight`, `getBoundingClientRect`) and writing styles in loops.
+5. **NEVER animate non-composited properties**: Animate only GPU-composited CSS properties (`transform`, `opacity`). Never animate `width`, `height`, `top`, `left`, or `margin`.
+
+## Rules & Patterns
+
+### 1. Vercel Optimization Hierarchy by Impact
+
+| Priority | Category | Key Optimization Target | Expected Impact |
+|:---|:---|:---|:---|
+| **1. CRITICAL** | **Eliminating Waterfalls** | Parallel data fetching (`Promise.all`), Suspense streaming | **30–60% faster LCP** |
+| **2. CRITICAL** | **Bundle Size Optimization** | Direct submodule imports, `next/dynamic`, deferring 3rd party scripts | **40–70% smaller initial JS** |
+| **3. HIGH** | **Server-Side & RSC Caching** | `React.cache()` request deduplication, edge SSR caching | **Lower TTFB & DB load** |
+| **4. MEDIUM-HIGH** | **Client Query Optimization** | SWR / TanStack Query stale-while-revalidate, deduplication | **Zero redundant network calls** |
+| **5. MEDIUM** | **Render & DOM Optimization** | Virtualization for large lists, state colocation, `:focus-visible` | **Smooth 60 FPS / INP < 100ms** |
+
+### 2. Eliminating Network Waterfalls
+
+```ts
+// [GOOD] Parallel execution
+const [user, notifications] = await Promise.all([
+  fetchUser(),
+  fetchNotifications(),
+]);
+const posts = await fetchPosts(user.id);
+```
+
+### 3. Layout Shift & Visual Stability (CLS < 0.1)
+
+- **Images & Video**: Always supply `width`, `height`, and `sizes` or CSS `aspect-ratio: 16 / 9`.
+- **Dynamic Content**: Reserve layout space for dynamically loaded widgets with min-height placeholders or skeletons.
+- **Tabular Numbers**: Use `font-feature-settings: "tnum"` / `font-variant-numeric: tabular-nums` for counters, clocks, and tables to prevent number width jitter.
+
+## Code Examples
+
+See `EXAMPLES.md` for detailed performance patterns and benchmark snippets.
+
+## Validation Checklist
+
+- [ ] LCP target is < 2.5s with preloaded critical fonts and LCP image `priority`.
+- [ ] No sequential `await` waterfalls in API routes or Server Components.
+- [ ] All animated elements use only `transform` and `opacity`.
+- [ ] `prefers-reduced-motion` media queries are respected.
+- [ ] Large tables / lists (> 100 items) utilize virtualization.
+
+## Common Mistakes
+
+- Chaining independent async requests instead of using `Promise.all`.
+- Animating layout-triggering properties (`height`, `width`, `top`) causing jank.
+- Missing image dimensions causing layout shift when images finish loading.
+
+## Integration Notes
+
+- Pairs with `nextjs` and `react` for App Router caching and component lifecycle tuning.
+- Pairs with `ui-ux-pro` for smooth animations and responsive design tokens.
+
+
+<!-- Source: performance.md -->
+
+# Web Performance — Best Practices
+
+## Core Web Vitals
+
+| Metric | Target | What it measures |
+| --- | --- | --- |
+| LCP (Largest Contentful Paint) | < 2.5s | Loading performance |
+| INP (Interaction to Next Paint) | < 200ms | Responsiveness |
+| CLS (Cumulative Layout Shift) | < 0.1 | Visual stability |
+
+## Loading Performance
+
+- **Code splitting** — split by route, lazy load non-critical components
+- **Tree shaking** — use ES modules, avoid side-effect imports
+- **Image optimization** — WebP/AVIF, responsive srcset, lazy loading
+- **Font loading** — `font-display: swap`, preload critical fonts
+- **Critical CSS** — inline above-the-fold styles
+- **Preconnect** — `<link rel="preconnect">` for third-party origins
+
+## Runtime Performance
+
+- **Avoid layout thrashing** — batch DOM reads and writes
+- **Debounce/throttle** — expensive event handlers (scroll, resize, input)
+- **Web Workers** — offload heavy computation
+- **Virtualize long lists** — render only visible items
+- **Avoid synchronous operations** — use async/await, requestIdleCallback
+
+## Bundle Optimization
+
+- **Analyze bundle** — use webpack-bundle-analyzer or similar
+- **Dynamic imports** — `import()` for heavy libraries
+- **Avoid barrel exports** — they prevent tree shaking
+- **Vendor splitting** — separate vendor chunks for caching
+- **Compression** — Brotli > gzip
+
+## Caching Strategy
+
+| Asset | Cache | Strategy |
+| --- | --- | --- |
+| HTML | Short (5min) | Revalidate |
+| JS/CSS (hashed) | Long (1 year) | Immutable |
+| Images | Long (1 year) | Immutable |
+| API responses | Depends | stale-while-revalidate |
+| Fonts | Long (1 year) | Immutable |
+
+## Anti-Patterns
+
+- [FAIL] Importing entire libraries (`import _ from 'lodash'`)
+- [FAIL] Unoptimized images (PNG > 500KB)
+- [FAIL] Blocking scripts in `<head>` without `defer`
+- [FAIL] Layout shifts from dynamic content (no dimensions on images)
+- [FAIL] Premature optimization — measure first, optimize second
+
+<!-- Source: EXAMPLES.md -->
+
+# performance Examples — Anti-patterns vs ContextOS Standard
+
+## Example 1: Dynamic Imports for Heavy Libraries
+
+### Anti-pattern: Static Import of Heavy Visualizers in Initial Bundle
+
+```typescript
+// BAD: Adds 800KB (Monaco editor or Three.js) to the critical first-paint bundle!
+import { CodeEditor } from '@/components/CodeEditor';
+
+export default function Page() {
+  return <div><CodeEditor /></div>;
+}
+```
+
+### Best practice: ContextOS Standard (Lazy Load on Demand)
+
+```typescript
+// GOOD: Dynamic import splits chunk, only downloads when component renders
+import dynamic from 'next/dynamic';
+
+const CodeEditor = dynamic(
+  () => import('@/components/CodeEditor'),
+  { loading: () => <EditorSkeleton />, ssr: false }
+);
+
+export default function Page() {
+  return <div><CodeEditor /></div>;
+}
+```
+
+<!-- Source: TROUBLESHOOTING.md -->
+
+# performance Troubleshooting & Common Mistakes
+
+## 1. Cumulative Layout Shift (CLS) from Images & Fonts
+
+- **Symptom**: Page content jumps around as images and custom fonts load.
+- **Root Cause**: Missing width and height attributes on image tags and FOUT (Flash of Unstyled Text).
+- **Fix**: Always specify aspect-ratio or width/height on images, and use next/font to preload web fonts with fallback sizing.
+
+## 2. High Interaction to Next Paint (INP)
+
+- **Symptom**: User clicks a button and the UI freezes for 200ms+ before responding.
+- **Root Cause**: Long task blocking the main thread during event dispatch.
+- **Fix**: Defer non-critical state updates using startTransition() or split heavy computation with Web Workers.
+
+## 3. Unoptimized SVG / Icon Overload
+
+- **Symptom**: Huge DOM node count and slow initial render times.
+- **Root Cause**: Rendering 500 inline SVG icons with complex paths.
+- **Fix**: Use SVG sprite sheets, dynamic icon loaders, or lightweight canvas rendering for dense data visualizations.

package/.agents/generated/gemini/skills/ponytail-mindset/SKILL.md

@@ -0,0 +1,261 @@
+---
+name: ponytail-mindset
+description: >
+  Minimalist coding mindset based on DietrichGebert/ponytail. Teaches the AI to write only what is strictly necessary. Uses a 7-rung ladder: YAGNI → reuse → stdlib → platform → deps → one-liner → minimum. Minimizes unnecessary boilerplate and over-engineering while keeping all safety, validation and security guards.
+---
+# ponytail-mindset
+
+## Overview
+
+Minimalist engineering discipline that eliminates over-engineering and premature abstraction while maintaining 100% of required validation, type safety, error boundaries, and security invariants.
+
+## When to Use
+
+Activate on all BUILD phases to prevent bloated implementations and enforce concise, focused solutions.
+
+## Rules & Patterns
+
+Based on [DietrichGebert/ponytail](https://github.com/DietrichGebert/ponytail).
+
+> _He says nothing. He writes one line. It works._
+
+**Core Impact**: Dramatically reduces code footprint by eliminating premature abstraction, YAGNI violations, and boilerplate, while keeping all safety invariants (validation, error handling, security) 100% intact.
+
+---
+
+### Core Principle
+
+> **The best code is code you don't write.**  
+> Write only what the task strictly needs. Lazy about the solution, never about reading and understanding.
+
+---
+
+### The 7-Rung Decision Ladder
+
+**Before writing ANY code**, stop and check each rung in order. Stop at the first rung that holds:
+
+```text
+1. Does this need to exist?
+   → No: YAGNI — skip it entirely. Don't build for "future use."
+
+2. Already in this codebase or component library?
+   → Yes: Reuse it. Don't rewrite. Call the existing function/component/module.
+   → For UI: Check shadcn/ui FIRST. Before building a complex UI element from scratch, check if it exists in the component library. If yes, generate the install command: npx shadcn@latest add dialog — never manually rewrite what shadcn already provides.
+
+3. Standard library does it?
+   → Yes: Use it. Don't write formatDate() — use Intl.DateTimeFormat or dayjs.
+
+4. Native platform feature?
+   → Yes: Use it. Don't install flatpickr when <input type="date"> exists.
+   → Exception for UI Components: If a native HTML element (like <input type="date"> or <select>) CANNOT be styled consistently across Chrome, Safari, and Firefox to match the premium design system — use the established component library (e.g., shadcn/ui <DatePicker>, <Select>) instead. Cross-browser inconsistency is a legitimate reason to NOT use native.
+
+5. Already-installed dependency?
+   → Yes: Use it. Don't install a new library to do what an existing one can.
+
+6. Can it be done in one line?
+   → Yes: One line. No abstraction layer needed.
+
+7. Only then: write the MINIMUM that works.
+   → No classes when a function works. No module when an inline does.
+```
+
+---
+
+### The Rule of Three (Do Not Abstract Early)
+
+- **First occurrence**: Write it inline directly where it is needed.
+- **Second occurrence**: Duplicate it cleanly. Duplication is cheaper than the wrong abstraction.
+- **Third occurrence**: Only now extract a shared helper or utility.
+
+---
+
+### 10 Concrete Over-Engineering Red Flags
+
+1. Creating a `GenericRepository<T>` when you only have 2 database tables.
+2. Creating a custom state machine or complex reducer for 2 boolean flags.
+3. Adding a configuration file or environment variables for values that never change.
+4. Writing custom retry/circuit-breaker logic when native `fetch` or SDK already handles it.
+5. Building a generic `BaseService` with 15 hook methods implemented by only one class.
+6. Wrapping every standard library call in a custom helper class (`StringUtils`, `DateUtils`, `ObjectUtils`).
+7. Creating a multi-level folder structure (`domains/auth/adapters/driving/rest/controllers/dto/`) for a 30-line microservice.
+8. Writing custom mock frameworks when Vitest/Jest/Node test runner provide standard mocks.
+9. Installing a 50KB npm package for a 3-line utility (e.g. `left-pad`, `is-number`, `deep-clone`).
+10. Pre-optimizing caching and indexing for endpoints serving 10 requests a day.
+
+---
+
+### The Sacred Exceptions (NEVER Cut These)
+
+The ladder applies to features and abstractions. These 4 areas are **non-negotiable** and **never simplified away**:
+
+#### 1. Input Validation
+
+```javascript
+// [GOOD] Always validate — even if "internal" API
+function createUser(data) {
+  if (!data.email || !isValidEmail(data.email)) {
+    throw new ValidationError('Invalid email');
+  }
+  return db.insert('users', data);
+}
+
+// [BAD] Never skip validation for "speed"
+function createUser(data) {
+  return db.insert('users', data); // NEVER
+}
+```
+
+#### 2. Error Handling
+
+```javascript
+// [GOOD] Always handle errors explicitly
+async function fetchUser(id) {
+  try {
+    const user = await db.findById(id);
+    if (!user) throw new NotFoundError(`User ${id} not found`);
+    return user;
+  } catch (err) {
+    logger.error('fetchUser failed', { id, err });
+    throw err;
+  }
+}
+```
+
+#### 3. Security Checks
+
+- Authorization check BEFORE every query or mutation.
+- Parameterized queries everywhere — zero string concatenation in SQL.
+- Strict sanitization of all rendered HTML and markdown.
+
+#### 4. Type Safety & Behavioral Tests
+
+- Strict TypeScript types — no `any` evasion.
+- Tests covering happy path, 4xx, and 5xx edge cases.
+
+---
+
+## Code Examples
+
+### Native Platform vs Over-Built Package
+
+**Over-build**:
+
+```bash
+npm install flatpickr
+# Creates DatePickerWrapper.jsx (45 lines) + useDatePicker.js (30 lines) + styles (60 lines)
+```
+
+**Ponytail approach (rung 4)**:
+
+```html
+<input type="date" name="date" aria-label="Appointment date" />
+```
+
+### Next.js App Router Server Action vs REST Endpoint
+
+```typescript
+// Instead of /api/users/[id]/route.ts + custom fetch wrapper:
+"use server";
+
+export async function updateUser(id: string, data: UpdateUserInput) {
+  const session = await getSession(); // auth check — never skip
+  if (session?.userId !== id) throw new Error("Forbidden");
+  return db.users.update(id, data);
+}
+```
+
+---
+
+## Validation Checklist
+
+- [ ] Every new dependency has been verified: cannot be solved with native platform or existing dependencies.
+- [ ] No single-use abstractions, wrappers, or interfaces created.
+- [ ] Sacred exceptions preserved: 100% input validation, explicit error handling, security checks intact.
+- [ ] All code written passes all existing unit and integration tests.
+
+---
+
+## Common Mistakes
+
+- **Cutting validation to write less code**: The goal is less architecture/boilerplate, never less safety.
+- **Creating utilities "for future use"**: Only write utilities when used 3+ times.
+- **Rewriting component libraries**: Building custom modals, tabs, or tooltips from scratch when shadcn/ui or Radix is already in the project.
+
+---
+
+## Integration Notes
+
+- Runs at the start of every `[PHASE: Build]` and `[PHASE: Review]`.
+- Enforces minimalism alongside `system-design` (think at scale, implement minimally).
+- Pairs with `impeccable-design` for UI tasks.
+
+
+<!-- Source: EXAMPLES.md -->
+
+# ponytail-mindset Examples — Anti-patterns vs ContextOS Standard
+
+## Example 1: Data Formatting and Manipulation
+
+### Anti-pattern: Over-engineered Custom Utility Class
+
+```typescript
+// BAD: 40 lines of boilerplate for relative date formatting
+export class DateFormatterService {
+  private static instance: DateFormatterService;
+  public static getInstance() { /* singleton boilerplate */ }
+  public formatRelative(date: Date): string {
+    const diff = Date.now() - date.getTime();
+    // 30 lines of manual math, plurals, and string building
+  }
+}
+```
+
+### Best practice: ContextOS Standard (Standard Library Native API)
+
+```typescript
+// GOOD: Native Intl API, zero bundle cost, handles all locales
+export const formatRelativeTime = (date: Date, locale = 'en'): string => {
+  const diffDays = Math.round((date.getTime() - Date.now()) / (1000 * 60 * 60 * 24));
+  return new Intl.RelativeTimeFormat(locale, { numeric: 'auto' }).format(diffDays, 'day');
+};
+```
+
+---
+
+## Example 2: Component Library Reuse
+
+### Anti-pattern: Hand-rolled Modal from Scratch
+
+```text
+BAD: Writing custom overlay DOM, manual scroll locking, manual focus trapping,
+and custom keydown listeners. Burns 300+ lines of fragile code.
+```
+
+### Best practice: ContextOS Standard (Leverage Established Primitives)
+
+```bash
+# GOOD: Install battle-tested primitive that handles ARIA, portals, and keyboard navigation
+npx shadcn@latest add dialog
+```
+
+<!-- Source: TROUBLESHOOTING.md -->
+
+# ponytail-mindset Troubleshooting & Common Mistakes
+
+## 1. Conflating Minimalism with Cutting Safety Guards
+
+- **Symptom**: Agent removes input validation, error handling, or security checks in the name of "less code".
+- **Root Cause**: Misunderstanding the Ponytail principle. Ponytail cuts unnecessary abstractions, never safety invariants.
+- **Fix**: Invariant: Always retain 100% of input sanitization, error boundaries, and type safety checks.
+
+## 2. "Just In Case" Speculative Coding (YAGNI Violation)
+
+- **Symptom**: Adding config options, generics, and plugin interfaces for features not requested.
+- **Root Cause**: Premature future-proofing.
+- **Fix**: Apply Rung 1 of the ladder: If it doesn't solve the immediate requirement, do not write it.
+
+## 3. Reinventing Installed Dependencies
+
+- **Symptom**: Writing a deep-clone helper when Lodash or native structuredClone is available.
+- **Root Cause**: Skipping inspection of package.json and runtime environment.
+- **Fix**: Inspect installed dependencies before writing utility functions.