claude-code-arcane 1.0.1 → 1.1.0

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+# [1.1.0](https://github.com/SebastianLuser/claude-code-arcane/compare/v1.0.1...v1.1.0) (2026-06-12)
+
+
+### Features
+
+* add backend-nestjs and backend-nextjs profiles with skills, rules and agents ([39e11f2](https://github.com/SebastianLuser/claude-code-arcane/commit/39e11f29825645afa64d686a5da7da853ba939b8))
+
 ## [1.0.1](https://github.com/SebastianLuser/claude-code-arcane/compare/v1.0.0...v1.0.1) (2026-06-05)
 
 

package/agents/engineering/e2e-tester.md

@@ -0,0 +1,65 @@
+---
+name: e2e-tester
+description: "Specialist en testing end-to-end para apps web y APIs: Playwright (Next.js/web) y supertest (NestJS/Node). Diseña suites e2e, cubre flujos críticos, guards/pipes/middleware y casos de borde."
+tools: Read, Glob, Grep, Write, Edit, Bash
+model: sonnet
+maxTurns: 15
+memory: project
+skills: [testing]
+---
+
+Sos el **E2E Tester**. Diseñás y escribís tests end-to-end que ejercitan el sistema completo: para frontend/Next.js con Playwright, para APIs NestJS/Node con supertest. Cubrís el ciclo real request→response incluyendo middleware, guards y pipes.
+
+## Expertise Areas
+
+- **Playwright** — flujos de usuario, fixtures, page objects, auth state reuse, visual/trace debugging
+- **supertest** — tests e2e de API NestJS con `createNestApplication`, setup/teardown, DB de test
+- **Estrategia** — qué cubrir e2e vs unit; priorizar flujos críticos (auth, checkout, CRUD core)
+- **Datos de test** — seeding, mocks de servicios externos (nunca llamar APIs/DBs reales de prod), cleanup
+- **CI** — correr e2e en pipeline, paralelización, retry de flaky, artifacts (traces/screenshots)
+
+## Principios
+
+- **Cubrir flujos, no implementación** — el e2e valida comportamiento de usuario/cliente
+- **Aislar dependencias externas** — mockear APIs de terceros con escenarios realistas (éxito, error, timeout)
+- **Determinismo** — sin sleeps arbitrarios; usar waits basados en condición. Atacar flakiness en la raíz
+- **Setup/teardown limpio** — cada test parte de estado conocido; cerrar la app/conexiones al final
+
+## Patterns
+
+### Playwright (Next.js)
+```ts
+test('user can sign in and see dashboard', async ({ page }) => {
+  await page.goto('/login');
+  await page.getByLabel('Email').fill('a@b.com');
+  await page.getByRole('button', { name: 'Sign in' }).click();
+  await expect(page.getByRole('heading', { name: 'Dashboard' })).toBeVisible();
+});
+```
+
+### supertest (NestJS)
+```ts
+const app = moduleRef.createNestApplication();
+await app.init();
+await request(app.getHttpServer())
+  .post('/auth/login').send({ email, password }).expect(201)
+  .expect(res => expect(res.body.accessToken).toBeDefined());
+await app.close();
+```
+
+## Code Review Bar
+
+**Veto:**
+- Tests que llaman APIs/DBs reales de producción
+- Sleeps arbitrarios en vez de waits por condición
+- Sin teardown (conexiones/apps colgadas)
+
+**Comment-only:**
+- Selectores frágiles (preferir roles/labels accesibles)
+- Cobertura ausente en un flujo crítico
+
+## Delegation Map
+
+**Report to:** `qa-director`, `lead-programmer`.
+**Coordina con:** `nextjs-engineer`, `nestjs-engineer`.
+**No delegate down.** Tier 3 specialist.

package/agents/engineering/nestjs-engineer.md

@@ -0,0 +1,74 @@
+---
+name: nestjs-engineer
+description: "Specialist en NestJS production-ready: arquitectura por feature modules, DI, guards/pipes/interceptors, Prisma/Drizzle, auth JWT, testing. Implementa APIs backend guiadas por backend-architect."
+tools: Read, Glob, Grep, Write, Edit, Bash
+model: sonnet
+maxTurns: 15
+memory: project
+skills: [nestjs-scaffold, nestjs-best-practices, pgvector-search]
+---
+
+Sos el **NestJS Engineer**. Implementás APIs backend en NestJS con TypeScript estricto, arquitectura modular y DI, siguiendo decisions del `backend-architect` y `database-architect`.
+
+## Expertise Areas
+
+- **Arquitectura** — feature modules, módulos compartidos con singleton, repository pattern, event-driven
+- **DI** — constructor injection, provider scopes, injection tokens para interfaces
+- **HTTP** — controllers finos, DTOs + `ValidationPipe`, guards, pipes, interceptors, exception filters
+- **Auth** — JWT + refresh tokens, guards declarativos (`@Roles`), passport strategies
+- **Data** — Prisma (default) / Drizzle / TypeORM, transacciones, sin N+1, migraciones
+- **Async** — colas (BullMQ), eventos, lifecycle hooks async
+- **Testing** — `Test.createTestingModule` (unit), supertest (e2e), mocks de dependencias externas
+- **Microservicios** — message/event patterns, health checks, graceful shutdown
+
+## Idioms y Anti-Patterns
+
+### Idiomatic NestJS
+- Feature modules, no organización por capa técnica
+- Constructor injection siempre; `DEFAULT` scope salvo necesidad real de `REQUEST`
+- Servicios lanzan `HttpException`, no retornan error objects
+- `ValidationPipe` global + DTOs decorados
+- Guards declarativos, no checks manuales
+
+### Anti-Patterns
+- `forwardRef()` para parchear ciclos en vez de rediseñar
+- Lógica de negocio en controllers
+- `ModuleRef.get()` / service locator en runtime
+- `synchronize: true` en producción
+- Devolver entidades de ORM crudas como respuesta
+- N+1 queries por falta de eager loading
+
+## Stack Defaults
+
+| Componente | Default |
+|------------|---------|
+| Framework | NestJS 10+ |
+| ORM | Prisma |
+| DB | PostgreSQL |
+| Auth | JWT + refresh tokens |
+| Validación | class-validator + ValidationPipe |
+| Testing | Jest + supertest |
+| Colas | BullMQ |
+| Deploy | Docker |
+
+## Code Review Bar
+
+**Veto:**
+- Dependencias circulares entre módulos
+- Constructor injection ausente / service locator
+- Endpoints sin `ValidationPipe` + DTO
+- Auth/authz manual en vez de guards
+- `synchronize: true` contra prod
+- Secrets hardcodeados
+- N+1 queries evitables
+
+**Comment-only:**
+- Servicio con múltiples responsabilidades
+- Falta de DTO de respuesta (exposición de campos)
+- Logging no estructurado
+
+## Delegation Map
+
+**Report to:** `backend-architect`, `database-architect`, `lead-programmer`.
+**Coordina con:** `e2e-tester` (cobertura e2e), `sql-specialist` (optimización de queries).
+**No delegate down.** Tier 3 specialist.

package/agents/engineering/nextjs-engineer.md

@@ -0,0 +1,72 @@
+---
+name: nextjs-engineer
+description: "Specialist en Next.js 15+ App Router: React Server Components, Server Actions, streaming, caching, SEO y performance. Implementa apps Next full-stack guiadas por frontend-architect / backend-architect."
+tools: Read, Glob, Grep, Write, Edit, Bash
+model: sonnet
+maxTurns: 15
+memory: project
+skills: [nextjs-scaffold, nextjs-best-practices, seo-nextjs, ai-sdk-setup]
+---
+
+Sos el **Next.js Engineer**. Implementas apps Next.js 15+ con App Router y TypeScript estricto, priorizando Server Components y performance. Seguís decisions del `frontend-architect` y `backend-architect`.
+
+## Expertise Areas
+
+- **App Router** — layouts anidados, route groups, parallel/intercepting routes, loading/error boundaries
+- **RSC** — Server Components por defecto, `'use client'` empujado a las hojas, composición server/client
+- **Server Actions** — mutaciones type-safe, `revalidatePath`/`revalidateTag`, auth por action
+- **Data fetching** — fetch paralelo, `React.cache()`, streaming con Suspense, estrategias de cache
+- **Rendering** — static/dynamic/PPR, ISR, `generateStaticParams`
+- **SEO** — Metadata API, `generateMetadata`, sitemap/robots, JSON-LD
+- **UI** — shadcn/ui + Tailwind, `next/image`, `next/font`
+- **IA** — Vercel AI SDK con Claude (streaming, tools, structured)
+
+## Idioms y Anti-Patterns
+
+### Idiomatic Next/RSC
+- Server Components por defecto; `'use client'` solo en hojas interactivas
+- Fetch en el server, pasar solo los campos necesarios a Client Components
+- `Promise.all` para fetches independientes — nunca cascada
+- Server Actions con validación Zod + auth check adentro
+- `next/image` + `generateMetadata` siempre
+
+### Anti-Patterns
+- `'use client'` en la raíz del árbol
+- `useEffect` + `fetch` para datos que podían venir del server
+- Barrel imports en el critical path
+- Pasar objetos de DB crudos a Client Components
+- Server Actions sin verificación de auth
+
+## Stack Defaults
+
+| Componente | Default |
+|------------|---------|
+| Framework | Next.js 15+ App Router |
+| Lenguaje | TypeScript estricto |
+| UI | shadcn/ui + Tailwind |
+| Data | Server Actions + RSC |
+| ORM | Prisma |
+| Auth | Auth.js |
+| Testing | Vitest + Playwright (e2e) |
+| Deploy | Vercel |
+
+## Code Review Bar
+
+**Veto:**
+- Server Action sin auth/authz
+- `'use client'` innecesario que arrastra el árbol entero al cliente
+- Waterfalls de fetch evitables
+- Barrel imports pesados en el bundle inicial
+- Secrets que cruzan a código cliente
+- Sin `generateMetadata` en pages indexables
+
+**Comment-only:**
+- Falta `next/dynamic` en componentes pesados
+- Resource hints ausentes
+- Naming inconsistente
+
+## Delegation Map
+
+**Report to:** `frontend-architect`, `backend-architect`, `lead-programmer`.
+**Coordina con:** `nextjs-reviewer` (review de performance), `e2e-tester` (cobertura e2e).
+**No delegate down.** Tier 3 specialist.

package/agents/engineering/nextjs-reviewer.md

@@ -0,0 +1,40 @@
+---
+name: nextjs-reviewer
+description: "Reviewer especializado en Next.js/React: audita performance (waterfalls, bundle, re-render), correcto uso de RSC/Server Actions, SEO y seguridad. Aplica las 64 reglas de Vercel priorizadas por impacto."
+tools: Read, Glob, Grep, Bash
+model: sonnet
+maxTurns: 12
+memory: project
+skills: [nextjs-best-practices]
+---
+
+Sos el **Next.js Reviewer**. Auditás código React/Next.js contra las 64 reglas de performance de Vercel Engineering (skill `nextjs-best-practices`) y las rules `nextjs-code` / `react-perf`. Sos read-only: encontrás y reportás, no implementás.
+
+## Metodología (dirigida por impacto)
+
+1. **Medir/localizar primero** — si hay métricas (Lighthouse, Web Vitals, bundle analyzer), empezar por lo que señalan. No revisar todo a ciegas.
+2. **Recorrer por prioridad de impacto:**
+   - CRITICAL: waterfalls de fetch, bundle size (barrel imports, dynamic imports), Server Actions sin auth
+   - HIGH: server-side (module state, serialización RSC), componentes definidos dentro de componentes, resource hints
+   - MEDIUM/LOW: re-render, rendering, micro-opts JS
+3. **Reportar con severidad** — cada finding: archivo:línea, regla violada, impacto estimado, fix sugerido.
+
+## Qué buscar (alto impacto primero)
+
+- **Waterfalls:** `await` secuenciales que podrían ser `Promise.all`; fetches anidados innecesarios
+- **Bundle:** barrel imports, componentes pesados sin `next/dynamic`, libs third-party bloqueando el inicial
+- **RSC:** `'use client'` demasiado arriba en el árbol; objetos de DB crudos cruzando el boundary
+- **Server Actions:** falta de auth/authz adentro de la action
+- **Re-render:** componentes definidos dentro de componentes; `useEffect` que debería ser handler
+- **SEO:** falta `generateMetadata`, canonical, sitemap
+- **Seguridad:** secrets en código cliente, input sin validar en actions/handlers
+
+## Output
+
+Reporte agrupado por severidad (CRITICAL → LOW), con conteo y top fixes recomendados. No aplica cambios — entrega el plan de optimización a `nextjs-engineer`.
+
+## Delegation Map
+
+**Report to:** `frontend-architect`, `lead-programmer`.
+**Entrega findings a:** `nextjs-engineer` para implementar.
+**No delegate down.** Tier 3 specialist (read-only).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-code-arcane",
-  "version": "1.0.1",
+  "version": "1.1.0",
   "description": "Skills, agents, hooks and rules for Claude Code — installable via npx arcane",
   "type": "module",
   "bin": {

package/profiles/backend-nestjs.yaml

@@ -0,0 +1,58 @@
+name: backend-nestjs
+description: "Backend NestJS — feature modules, DI, guards/pipes, Prisma, JWT, testing, microservicios. Best practices priorizadas por impacto."
+type: base
+
+skills:
+  # NestJS-specific (nuevas)
+  - nestjs-scaffold
+  - nestjs-best-practices
+  - pgvector-search
+  # API & data
+  - database
+  - database-indexing
+  - data-migrations
+  - api-design
+  - api-docs
+  - api-versioning
+  - caching-strategy
+  - webhooks
+  - rate-limiting
+  # Auth & security
+  - auth-strategy
+  - jwt-strategy
+  - oauth-setup
+  - rbac-abac
+  - audit-log
+  # Ops & quality
+  - testing
+  - contract-testing
+  - deps-audit
+  - env-sync
+  - observability
+  - performance
+  - async-ops
+  - ci-cd-setup
+
+rules:
+  universal:
+    - backend-code
+    - api-code
+    - nestjs-code
+    - migration-code
+  gamedev:
+    []
+
+agents:
+  - engineering
+
+permissions:
+  allow:
+    - "Bash(npm *)"
+    - "Bash(yarn *)"
+    - "Bash(pnpm *)"
+    - "Bash(npx *)"
+    - "Bash(nest *)"
+    - "Bash(docker ps*)"
+    - "Bash(docker images*)"
+  deny:
+    []

package/profiles/backend-nextjs.yaml

@@ -0,0 +1,56 @@
+name: backend-nextjs
+description: "Next.js full-stack — App Router, RSC, Server Actions, SEO, AI SDK, performance (64 reglas de Vercel). Front + back en un solo runtime."
+type: base
+
+skills:
+  # Next.js-specific (nuevas)
+  - nextjs-scaffold
+  - nextjs-best-practices
+  - seo-nextjs
+  - ai-sdk-setup
+  - pgvector-search
+  # Backend / API (Next es full-stack)
+  - api-design
+  - database
+  - caching-strategy
+  - rate-limiting
+  # Auth & security
+  - auth-strategy
+  - jwt-strategy
+  - oauth-setup
+  - web-security
+  - csp-headers
+  # Frontend quality
+  - accessibility
+  - performance
+  # Ops & quality
+  - testing
+  - deps-audit
+  - env-sync
+  - observability
+  - ci-cd-setup
+  - cdn-setup
+
+rules:
+  universal:
+    - nextjs-code
+    - react-perf
+    - frontend-code
+    - backend-code
+    - api-code
+  gamedev:
+    []
+
+agents:
+  - engineering
+
+permissions:
+  allow:
+    - "Bash(npm *)"
+    - "Bash(yarn *)"
+    - "Bash(pnpm *)"
+    - "Bash(npx *)"
+    - "Bash(docker ps*)"
+    - "Bash(docker images*)"
+  deny:
+    []

package/rules/nestjs-code.md

@@ -0,0 +1,73 @@
+---
+paths:
+  - "src/**/*.ts"
+  - "**/*.module.ts"
+  - "**/*.controller.ts"
+  - "**/*.service.ts"
+  - "**/*.guard.ts"
+  - "**/*.pipe.ts"
+  - "**/*.interceptor.ts"
+  - "**/*.dto.ts"
+  - "apps/**"
+  - "libs/**"
+---
+
+# NestJS Code Rules
+
+Reglas production-ready para NestJS, ordenadas por impacto. Catálogo completo (40 reglas, 10 categorías) + ejemplos incorrecto/correcto: skill `nestjs-best-practices`.
+
+## CRITICAL — Arquitectura & DI
+
+- **Cero dependencias circulares entre módulos** — causa #1 de crashes en runtime. Si aparece `forwardRef()`, es señal de mal diseño: refactorizar.
+- **Organizar por feature modules**, no por capas técnicas (`users/`, no `controllers/` + `services/` globales).
+- **Exportar servicios desde módulos dedicados** para garantizar instancias singleton y evitar estado inconsistente.
+- **Single Responsibility por servicio** — un servicio = un concepto de dominio.
+- **Constructor injection siempre.** Nunca `ModuleRef.get()` en runtime (service locator anti-pattern). Dependencias explícitas, tipadas, testeables.
+- **Provider scopes**: `DEFAULT` (singleton) por defecto; `REQUEST` scope solo cuando se necesita contexto de request (tiene costo de performance).
+- **Injection tokens (símbolos o abstract classes) para interfaces** — las interfaces de TS no existen en runtime.
+
+## HIGH — Error handling & Security
+
+- **Servicios lanzan `HttpException` subclasses**, no retornan objetos de error.
+- **Manejar errores async explícitamente** — fire-and-forget y background tasks deben atrapar errores (no unhandled rejections).
+- **Exception filters** para formato de respuesta de error centralizado y consistente.
+- **`ValidationPipe` global + DTOs decorados** — rechazar input malformado antes de procesarlo. `whitelist: true`, `forbidNonWhitelisted: true`.
+- **Guards declarativos para auth/authz**, no chequeos manuales en cada handler.
+- **JWT seguro**: tokens de vida corta + refresh tokens, secretos en env/secret manager, nunca data sensible en el payload.
+- **Rate limiting con `@nestjs/throttler`**, límites por endpoint.
+- **Sanitizar output** (XSS) y setear `Content-Type` correcto.
+
+## HIGH — Performance & Data
+
+- **Evitar N+1**: eager loading con relations o joins de QueryBuilder.
+- **Optimizar queries**: seleccionar solo columnas necesarias, índices apropiados, no over-fetch de relaciones.
+- **Caching estratégico** con TTL apropiado e invalidación basada en eventos.
+- **Transacciones para operaciones multi-step** dependientes (consistencia ante fallos).
+- **Migraciones versionadas** — nunca `synchronize: true` en producción.
+- **Async lifecycle hooks** retornan promesas; constructores síncronos (no bloquear el arranque).
+
+## MEDIUM — API, Microservices, DevOps
+
+- **DTOs + serialización** (`ClassSerializerInterceptor`) para respuestas — controlar exposición, evitar referencias circulares.
+- **Interceptors para cross-cutting concerns** (logging, transformación, formato de respuesta).
+- **Pipes para transformación/validación** de input.
+- **API versioning** para cambios breaking.
+- **Health checks** (readiness/liveness) para orquestadores.
+- **Message queues para jobs largos** — no bloquear handlers de request.
+- **Graceful shutdown**: escuchar SIGTERM, drenar requests in-flight antes de salir.
+- **`ConfigModule` para configuración** por entorno — nada hardcodeado.
+- **Structured logging (JSON)** para parseo/filtrado en producción.
+
+## Anti-Patterns
+
+- `forwardRef()` para parchear dependencias circulares en vez de rediseñar
+- Lógica de negocio en controllers (solo parsean input, llaman service, dan shape a la respuesta)
+- `synchronize: true` contra una DB de producción
+- `ModuleRef.get()` / service locator en runtime
+- Validación manual de input en cada handler en vez de `ValidationPipe` + DTO
+- Devolver entidades de ORM crudas como respuesta HTTP
+- `REQUEST` scope sin necesidad real (penaliza performance)
+
+---
+
+_Derivado de [kadajett/agent-nestjs-skills](https://github.com/kadajett/agent-nestjs-skills) (nestjs-best-practices). Condensado al formato Arcane._

package/rules/nextjs-code.md

@@ -0,0 +1,60 @@
+---
+paths:
+  - "app/**"
+  - "src/app/**"
+  - "pages/**"
+  - "src/pages/**"
+  - "**/*.tsx"
+  - "**/route.ts"
+  - "next.config.*"
+---
+
+# Next.js Code Rules
+
+Reglas de performance y arquitectura para Next.js App Router (RSC, data fetching, caching). Ordenadas por impacto. Catálogo completo + ejemplos: skill `nextjs-best-practices`.
+
+## CRITICAL — Eliminar waterfalls
+
+- **Server Components por defecto.** `'use client'` solo cuando se necesita interactividad/estado/efectos/browser APIs. Empujar el boundary client lo más abajo posible en el árbol.
+- **Fetch paralelo, no secuencial.** Operaciones independientes con `Promise.all()`. Nunca `await` en serie cuando no hay dependencia entre llamadas.
+- **Iniciar promesas temprano, await tarde.** En route handlers y RSC, disparar el fetch independiente al inicio y await recién donde se usa el dato.
+- **Composición para fetch paralelo.** Reestructurar componentes para que fetches independientes corran simultáneamente; fetches dependientes se anidan dentro de la promesa de cada item, no en serie global.
+- **Suspense boundaries estratégicos.** Envolver subárboles con `<Suspense>` para mostrar shell rápido mientras streamea el contenido.
+
+## CRITICAL — Bundle size
+
+- **No barrel imports.** Importar directo del archivo fuente (`lodash/debounce`, no `lodash`); los barrels (`index.ts` que re-exportan todo) arrastran miles de módulos sin usar.
+- **`next/dynamic` para componentes pesados** no necesarios en el render inicial (charts, editores, modales).
+- **Diferir libs third-party no críticas** (analytics, logging, error tracking) a post-hydration; no bloquear el bundle inicial.
+- **Paths estáticamente analizables.** Imports con paths literales/mapas explícitos, no construidos dinámicamente.
+
+## HIGH — Server
+
+- **Autenticar cada Server Action como un API route.** Verificar auth/authz dentro de la action, no confiar solo en middleware.
+- **No module-level mutable state para datos de request.** Mantener datos de request locales al árbol de render; las variables a nivel módulo se comparten entre requests → data leaks.
+- **Minimizar serialización en boundaries RSC→Client.** Pasar solo los campos que el cliente realmente usa, no el objeto entero.
+- **`React.cache()` para dedupe por request**; LRU cache para datos compartidos entre requests dentro de una ventana de tiempo.
+- **`after()` para trabajo no bloqueante** (logging, analytics, cleanup) que corre después de enviar la respuesta.
+- **Hoist I/O estático a nivel módulo** para evitar lecturas redundantes en cada request.
+
+## HIGH — Rendering & data
+
+- **`generateMetadata` para todo el SEO** (title, description, OG, canonical). Nunca tags manuales en el body.
+- **`next/image` siempre** — width/height explícitos, `priority` para LCP, formatos modernos.
+- **Caching explícito.** Conocer y declarar `fetch` cache (`force-cache` / `no-store` / `revalidate`), `revalidatePath`/`revalidateTag` para invalidación.
+- **`content-visibility: auto`** para listas largas off-screen.
+- **Resource hints** (`preload`, `preconnect`) para recursos críticos.
+
+## Anti-Patterns
+
+- `'use client'` en la raíz del árbol (mata todo el beneficio de RSC)
+- `useEffect` + `fetch` en el cliente para datos que podían venir del server
+- Fetches en cascada (cada componente espera al padre sin necesidad)
+- `export *` barrel files en libs internas
+- Pasar objetos de DB crudos como props a Client Components
+- Hardcodear `revalidate`/cache sin entender la estrategia
+- Secrets o lógica sensible en código que cruza a `'use client'`
+
+---
+
+_Derivado de [vercel-labs/agent-skills](https://github.com/vercel-labs/agent-skills) (react-best-practices, MIT). Condensado al formato Arcane._

package/rules/react-perf.md

@@ -0,0 +1,59 @@
+---
+paths:
+  - "**/*.tsx"
+  - "**/*.jsx"
+  - "src/components/**"
+  - "src/hooks/**"
+  - "components/**"
+  - "hooks/**"
+---
+
+# React Performance Rules
+
+Reglas de re-render, rendering y micro-optimización JS para React. Ordenadas por impacto. Catálogo completo (64 reglas) + ejemplos: skill `nextjs-best-practices`.
+
+## HIGH — Estructura de componentes
+
+- **No definir componentes dentro de componentes.** Definir a nivel módulo o extraer; definirlos inline los remonta en cada render (pierde estado, mata performance).
+- **`content-visibility: auto`** para listas largas — difiere render y paint de lo que está off-screen.
+- **`defer`/`async` en `<script>`** para no bloquear el render durante el parsing.
+- **Resource hints de React DOM** (`preload`, `preconnect`, `prefetchDNS`) para recursos críticos.
+
+## MEDIUM — Re-render optimization
+
+- **Calcular derived state durante el render**, no guardarlo en `useState` (se desincroniza y genera renders extra).
+- **Leer state dinámico en el callback**, no suscribirse en render time cuando solo se usa en un handler.
+- **Functional `setState`** (`setX(prev => ...)`) para operar sobre el último valor y crear callbacks estables.
+- **Lazy state init**: pasar función a `useState(() => expensive())` para no recomputar en cada render.
+- **`useTransition` para updates no urgentes**; `useDeferredValue` para mantener inputs responsivos durante cómputo pesado.
+- **`useRef` para valores transitorios** (no-UI) que cambian seguido y no deben disparar render.
+- **Extraer defaults no-primitivos** de componentes memoizados a constantes a nivel módulo (preserva la memoización).
+- **Side effects de interacción van en event handlers**, no en `useEffect`.
+- **Dependencias de effect primitivas y estrechas**, no objetos enteros.
+
+## LOW-MEDIUM — useMemo / JS
+
+- **No envolver expresiones simples en `useMemo`** — el overhead del hook supera el cómputo.
+- **Index maps (`Map`) para lookups repetidos** en vez de `.find()`/`.includes()` en loops → O(1).
+- **`.flatMap()`** en lugar de `.map().filter(Boolean)`; combinar iteraciones múltiples de array en un solo loop.
+- **Hoist de `RegExp`** a nivel módulo (no recrear en cada render).
+- **Early return** cuando el resultado ya está determinado; chequear `length` antes de operaciones caras (sort).
+- **`.toSorted()`** en vez de `.sort()` para inmutabilidad.
+
+## Hydration
+
+- Evitar mismatch sin flicker con scripts inline síncronos cuando se actualiza el DOM antes de hidratar.
+- `suppressHydrationWarning` solo para diferencias server/client intencionales (fechas, IDs).
+- Conditional rendering explícito con ternario, no `&&` (evita renderizar `0` u otros falsy).
+
+## Anti-Patterns
+
+- Componentes definidos dentro del render de otro componente
+- `useMemo`/`useCallback` por default "por las dudas" sin medir
+- `useEffect` para lógica que pertenece a un event handler
+- Guardar en state lo que se puede derivar de props/state existentes
+- `.find()` dentro de `.map()` (O(n²)) sobre listas grandes
+
+---
+
+_Derivado de [vercel-labs/agent-skills](https://github.com/vercel-labs/agent-skills) (react-best-practices, MIT). Condensado al formato Arcane._

package/skills/ai-sdk-setup/SKILL.md

@@ -0,0 +1,82 @@
+---
+name: ai-sdk-setup
+description: "Integrar features de IA en Next.js con el Vercel AI SDK: streaming de chat, tool calling, structured output, agents y RAG. Default a modelos Claude. Usar al agregar chat, generación o agentes a una app Next/Node."
+category: "ai"
+argument-hint: "[chat|stream|tools|structured|agent|rag]"
+user-invocable: true
+allowed-tools: Read, Glob, Grep, Bash, Write, Edit, Task
+---
+# ai-sdk-setup — Vercel AI SDK con Claude
+
+## MANDATORY WORKFLOW
+
+> **Antes de codear features LLM, leer la skill `claude-api`** para model IDs vigentes, params y pricing. No asumir de memoria.
+
+### Step 0: Gather Requirements
+1. **Caso:** chat / generación one-shot / extracción structured / agente con tools / RAG
+2. **Streaming** al cliente o respuesta completa
+3. **Modelo:** Opus 4.8 (`claude-opus-4-8`, razonamiento) / Sonnet 4.6 (`claude-sonnet-4-6`, balance) / Haiku 4.5 (`claude-haiku-4-5-20251001`, rápido/barato)
+4. ¿Necesita tool calling / structured output / RAG (ver skill `pgvector-search`)?
+
+### Step 1: Instalar
+```bash
+pnpm add ai @ai-sdk/anthropic zod
+# env: ANTHROPIC_API_KEY (validar con Zod en src/lib/env.ts, nunca hardcodear)
+```
+
+### Step 2: Chat con streaming (Route Handler)
+```ts
+// app/api/chat/route.ts
+import { anthropic } from '@ai-sdk/anthropic';
+import { streamText, convertToModelMessages } from 'ai';
+
+export async function POST(req: Request) {
+  const { messages } = await req.json();
+  const result = streamText({
+    model: anthropic('claude-sonnet-4-6'),
+    messages: convertToModelMessages(messages),
+  });
+  return result.toUIMessageStreamResponse();
+}
+```
+Cliente: `useChat()` de `@ai-sdk/react`.
+
+### Step 3: Structured output (Zod)
+```ts
+const { object } = await generateObject({
+  model: anthropic('claude-sonnet-4-6'),
+  schema: z.object({ sentiment: z.enum(['pos','neg','neutral']), score: z.number() }),
+  prompt: text,
+});
+```
+
+### Step 4: Tool calling / agente
+```ts
+const result = await generateText({
+  model: anthropic('claude-opus-4-8'),
+  tools: {
+    search: tool({
+      description: 'Buscar docs', inputSchema: z.object({ q: z.string() }),
+      execute: async ({ q }) => searchDocs(q),
+    }),
+  },
+  stopWhen: stepCountIs(5),   // loop multi-step controlado
+  prompt,
+});
+```
+
+### Step 5: Buenas prácticas
+- **Server-only** la API key — nunca exponer al cliente
+- Auth en el route handler (como cualquier API route — ver rule `nextjs-code`)
+- Rate limiting en endpoints de IA (costo $)
+- Prompt caching para system prompts grandes (ver skill `claude-api`)
+- Manejar errores de stream y abort (`AbortController`)
+- Validar/parsear toda salida structured con Zod antes de usarla
+
+## Cierre
+
+Probar el endpoint con streaming real, verificar manejo de errores/abort y que la API key nunca llega al cliente. Endpoint funcionando + key server-only → integración **READY**. Confirmar el approach con el usuario antes de escribir código. Siguiente paso: skill `claude-api` para tuning de modelo/caching, o `pgvector-search` para RAG.
+
+---
+
+_Inspirado en las skills de AI SDK de [laguagu/claude-code-nextjs-skills](https://github.com/laguagu/claude-code-nextjs-skills). Adaptado al formato Arcane y a modelos Claude. Verificar API/SDK contra la skill `claude-api`._