contextos-agents 1.5.0

package/.agents/core/skills/ponytail-mindset/SKILL.md

@@ -0,0 +1,193 @@
+---
+name: ponytail-mindset
+description: >
+  Minimalist coding mindset. Write only what is strictly necessary for the task.
+  7-rung decision ladder before writing any code. Eliminates premature abstraction
+  while keeping all safety, validation, error handling, and security guards intact.
+---
+
+# 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.

package/.agents/core/skills/ponytail-mindset/TROUBLESHOOTING.md

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

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

@@ -0,0 +1,14 @@
+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.
+tags:
+  - minimalism
+  - efficiency
+  - quality
+  - yagni
+  - refactoring
+version: 1.0.0
+source: https://github.com/DietrichGebert/ponytail

package/.agents/core/skills/react/EXAMPLES.md

@@ -0,0 +1,79 @@
+# React Examples — Anti-patterns vs ContextOS Standard
+
+## Example 1: Derived State vs. useEffect
+
+### Anti-pattern: Anti-pattern (Redundant state + extra render with useEffect)
+
+```tsx
+// BAD: causes an unnecessary extra render cycle and potential state desync
+function OrderSummary({ items }: { items: CartItem[] }) {
+  const [total, setTotal] = useState(0);
+
+  useEffect(() => {
+    const calculated = items.reduce((sum, item) => sum + item.price * item.quantity, 0);
+    setTotal(calculated);
+  }, [items]);
+
+  return <div>Total: ${total}</div>;
+}
+```
+
+### Best practice: ContextOS Standard (Inline derived calculation / useMemo)
+
+```tsx
+// GOOD: calculated instantly during render with zero extra render pass
+function OrderSummary({ items }: { items: CartItem[] }) {
+  const total = useMemo(
+    () => items.reduce((sum, item) => sum + item.price * item.quantity, 0),
+    [items]
+  );
+
+  return <div>Total: ${total.toFixed(2)}</div>;
+}
+```
+
+---
+
+## Example 2: Custom Hook Encapsulation
+
+### Anti-pattern: Anti-pattern (Scattered listener logic inside component)
+
+```tsx
+// BAD: window listener logic cluttering UI component
+function NavHeader() {
+  const [isScrolled, setIsScrolled] = useState(false);
+  useEffect(() => {
+    const handleScroll = () => setIsScrolled(window.scrollY > 50);
+    window.addEventListener('scroll', handleScroll);
+    return () => window.removeEventListener('scroll', handleScroll);
+  }, []);
+  return <header className={isScrolled ? 'scrolled' : ''}>Header</header>;
+}
+```
+
+### Best practice: ContextOS Standard (Reusable Custom Hook)
+
+```tsx
+// GOOD: extracted into a reusable, testable custom hook
+export function useScrollThreshold(threshold = 50): boolean {
+  const [isPassed, setIsPassed] = useState(() => typeof window !== 'undefined' && window.scrollY > threshold);
+
+  useEffect(() => {
+    let ticking = false;
+    const handleScroll = () => {
+      if (!ticking) {
+        window.requestAnimationFrame(() => {
+          setIsPassed(window.scrollY > threshold);
+          ticking = false;
+        });
+        ticking = true;
+      }
+    };
+
+    window.addEventListener('scroll', handleScroll, { passive: true });
+    return () => window.removeEventListener('scroll', handleScroll);
+  }, [threshold]);
+
+  return isPassed;
+}
+```

package/.agents/core/skills/react/SKILL.md

@@ -0,0 +1,132 @@
+---
+name: React
+description: >
+  ContextOS skill for modern React (v18/v19), component architecture, state colocation, render optimization, and Vercel performance rules.
+---
+
+# React Engineering & Performance Best Practices
+
+## Overview
+
+Enforces declarative, component-driven UI architecture with optimal re-render cycles, state colocation, responsive optimistic updates, and robust accessibility standards.
+
+## When to Use
+
+Activate whenever creating, refactoring, or optimizing React functional components, custom hooks, context providers, or UI interaction states.
+
+## Negative Constraints (What NOT to Do)
+
+1. **NEVER use `useEffect` to synchronize or compute derived state**: Calculate derived state inline during render. Use `useMemo` only for computationally intensive derivations.
+2. **NEVER use array indices as `key` props on dynamic or reorderable lists**: Always use stable, unique entity identifiers (`item.id`).
+3. **NEVER mutate React state directly**: Always return new immutable references (`[...prev, newItem]` or `{ ...prev, key: value }`).
+4. **NEVER declare subcomponents inside the render body of parent components**: Declare components at module scope or in dedicated files to prevent DOM node remounting and lost focus state.
+5. **NEVER create memory leaks in `useEffect`**: Always provide clean-up functions for event listeners, `AbortController`, timers, and websocket subscriptions.
+6. **NEVER lift state higher than necessary**: Colocate state to the nearest common ancestor or leaf component to prevent wasteful re-renders of unrelated subtrees.
+
+## Rules & Patterns
+
+### 1. State Colocation & Re-render Optimization
+
+- **State Colocation**: Keep state as close as possible to the components that consume it.
+- **Composition to Prevent Re-renders**: Pass expensive static subtrees as `children` to wrapper components holding state so the children do not re-render when the wrapper updates.
+
+```tsx
+export function ExpandableCard({ title, children }: { title: string; children: React.ReactNode }) {
+  const [isOpen, setIsOpen] = useState(false);
+
+  return (
+    <div className="rounded-xl border p-4">
+      <button 
+        type="button"
+        onClick={() => setIsOpen(v => !v)}
+        className="flex w-full justify-between font-semibold"
+        aria-expanded={isOpen}
+      >
+        <span>{title}</span>
+        <span>{isOpen ? '−' : '+'}</span>
+      </button>
+      {isOpen && <div className="mt-3 pt-3 border-t">{children}</div>}
+    </div>
+  );
+}
+```
+
+### 2. Optimistic UI Updates & Concurrent Actions (`useOptimistic`, `useTransition`)
+
+- Provide instantaneous visual feedback for user actions without waiting for server network roundtrips.
+
+```tsx
+import { useOptimistic, useTransition } from 'react';
+
+export function TodoList({ todos, onAdd }: { todos: Todo[]; onAdd: (text: string) => Promise<void> }) {
+  const [isPending, startTransition] = useTransition();
+  const [optimisticTodos, addOptimisticTodo] = useOptimistic(
+    todos,
+    (state, newText: string) => [...state, { id: 'temp-' + Date.now(), text: newText, isPending: true }]
+  );
+
+  const handleAction = async (formData: FormData) => {
+    const text = formData.get('todo') as string;
+    if (!text?.trim()) return;
+
+    startTransition(async () => {
+      addOptimisticTodo(text);
+      await onAdd(text);
+    });
+  };
+
+  return (
+    <form action={handleAction} className="space-y-4">
+      <input name="todo" placeholder="Add a new task..." className="border p-2 rounded" />
+      <button type="submit" disabled={isPending} className="bg-primary text-white px-4 py-2 rounded">
+        {isPending ? 'Saving...' : 'Add'}
+      </button>
+      <ul className="divide-y">
+        {optimisticTodos.map(todo => (
+          <li key={todo.id} className={todo.isPending ? 'opacity-50 italic' : ''}>
+            {todo.text}
+          </li>
+        ))}
+      </ul>
+    </form>
+  );
+}
+```
+
+### 3. Derived State vs. Effects Anti-Pattern
+
+```tsx
+// [GOOD] Computed directly during render (or memoized if expensive)
+function SearchResults({ query, items }: { query: string; items: Item[] }) {
+  const filtered = useMemo(() => {
+    const q = query.trim().toLowerCase();
+    if (!q) return items;
+    return items.filter(i => i.title.toLowerCase().includes(q));
+  }, [query, items]);
+
+  return <List items={filtered} />;
+}
+```
+
+## Code Examples
+
+See `EXAMPLES.md` for detailed code examples and hook implementations.
+
+## Validation Checklist
+
+- [ ] Zero `useEffect` hooks used for derived calculations.
+- [ ] Every list mapping has a unique, non-index entity ID key.
+- [ ] Subcomponents declared in parent render functions are extracted to top-level scope.
+- [ ] Effects with event listeners, timers, or abortable requests include clean-up returns.
+- [ ] Reusable components are composed cleanly via `children` or render props.
+
+## Common Mistakes
+
+- Setting state inside `useEffect` based on prop changes rather than deriving values inline.
+- Declaring nested components within component bodies.
+- Using index keys causing input focus loss or animations breaking on list mutations.
+
+## Integration Notes
+
+- Pairs with `typescript` for type safety on props, generics, and ref forwarding.
+- Pairs with `ui-ux-pro` and `web-accessibility` for UI tokens and ARIA standards.

package/.agents/core/skills/react/TROUBLESHOOTING.md

@@ -0,0 +1,19 @@
+# react Troubleshooting & Common Mistakes
+
+## 1. Infinite Render Loops in useEffect
+
+- **Symptom**: Browser freezes, "Maximum update depth exceeded" error.
+- **Root Cause**: Creating new object or array literals inside component body and passing them to useEffect dependency array.
+- **Fix**: Colocate state, compute derived state during render without useEffect, or use primitive dependency values.
+
+## 2. Stale Closures in Callbacks
+
+- **Symptom**: Event handler or setTimeout accesses outdated state values.
+- **Root Cause**: Callback closing over initial state without updated dependency.
+- **Fix**: Use functional state updates (`setCount(c => c + 1)`) or `useRef` for mutable references.
+
+## 3. Prop Drilling vs Context Performance
+
+- **Symptom**: Changing a small state variable causes the entire component tree to re-render.
+- **Root Cause**: Storing rapidly changing state in a single monolithic React Context.
+- **Fix**: Split contexts by domain or migrate client UI state to Zustand with granular selectors.

package/.agents/core/skills/react/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/react/react.md

@@ -0,0 +1,93 @@
+# React — Best Practices
+
+## Component Architecture
+
+- **Prefer function components** with hooks over class components
+- **One component per file** — name file same as component
+- **Composition over inheritance** — use children and render props
+- **Keep components small** — if > 150 lines, split it
+
+## Hooks
+
+- **useState** for local state, **useReducer** for complex state
+- **useEffect** — always specify dependencies, clean up subscriptions
+- **Custom hooks** — extract reusable logic into `use*` functions
+- **useMemo/useCallback** — only when you have measured a performance problem
+
+## State Management
+
+- **Local state first** — don't reach for global state until you need it
+- **Lift state up** — find the closest common ancestor
+- **Context** — for cross-cutting concerns (theme, auth, locale)
+- **External store** (Zustand, Jotai) — for truly global, frequently updated state
+
+## Patterns
+
+### Container/Presenter
+
+```tsx
+// Container — handles logic
+function UserListContainer() {
+  const users = useUsers();
+  return <UserList users={users} />;
+}
+
+// Presenter — handles display
+function UserList({ users }: { users: User[] }) {
+  return <ul>{users.map(u => <UserItem key={u.id} user={u} />)}</ul>;
+}
+```
+
+### Error Boundaries
+
+- Wrap major sections in Error Boundaries
+- Provide meaningful fallback UI
+- Log errors to monitoring service
+
+### Loading States
+
+- Always handle: `loading`, `error`, `empty`, `data` states
+- Use Suspense where supported
+- Show skeleton screens, not spinners
+
+## Performance
+
+- **React.memo** — only for expensive renders with stable props
+- **Code splitting** — lazy load routes and heavy components
+- **Virtualization** — for lists > 100 items
+- **Image optimization** — use next/image or lazy loading
+- **Avoid** — inline object/array creation in JSX props
+
+## Anti-Patterns (Avoid)
+
+- [FAIL] Props drilling more than 2 levels — use Context or state management
+- [FAIL] useEffect for derived state — use useMemo instead
+- [FAIL] Index as key — use stable unique IDs
+- [FAIL] Mutating state directly — always create new references
+- [FAIL] God components — split into smaller, focused components
+- [FAIL] Business logic in components — extract to hooks or services
+
+## Testing
+
+- **React Testing Library** — test behavior, not implementation
+- Test user interactions, not component internals
+- Mock API calls, not React hooks
+- Use `screen.getByRole` over `getByTestId`
+
+## File Structure
+
+```
+components/
+  Button/
+    Button.tsx
+    Button.test.tsx
+    Button.module.css
+    index.ts
+hooks/
+  useAuth.ts
+  useDebounce.ts
+services/
+  api.ts
+types/
+  user.ts
+```

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

@@ -0,0 +1,10 @@
+id: react
+name: React
+category: frontend
+tags: [frontend, spa, jsx, components, hooks]
+requires: [typescript]
+optional: [tailwind, react-query, zustand, next-auth]
+conflicts: [vue, angular, svelte]
+weight: 8
+documents:
+  - react.md