elsabro 2.0.0

package/references/source-hierarchy.md

@@ -0,0 +1,150 @@
+---
+name: source-hierarchy
+description: Referencia que define la prioridad de fuentes de información (Context7 > Docs > WebSearch > Training)
+---
+
+# Jerarquía de Fuentes
+
+Esta referencia define el orden de prioridad para buscar información antes de planificar o implementar.
+
+## Regla de Oro
+
+**NUNCA confiar solo en el conocimiento de entrenamiento de Claude para APIs específicas, versiones, o sintaxis.**
+
+El conocimiento de Claude puede tener 6-18 meses de antigüedad. Las librerías cambian constantemente.
+
+## Jerarquía de Confianza
+
+| Prioridad | Fuente | Confianza | Cuándo Usar |
+|-----------|--------|-----------|-------------|
+| 1 | **Context7** | HIGH | Cualquier librería/framework conocido |
+| 2 | **Documentación oficial** (WebFetch) | MEDIUM-HIGH | Si Context7 no tiene cobertura |
+| 3 | **WebSearch** | MEDIUM | Tendencias, comparaciones, problemas comunes |
+| 4 | **Training Data** | LOW | Solo como último recurso, marcar como "no verificado" |
+
+## Uso de Context7
+
+### Cuándo SIEMPRE usar
+
+- Sintaxis de API de cualquier librería
+- Configuración de frameworks
+- Patrones recomendados
+- Versiones actuales
+- Breaking changes recientes
+
+### Cómo usar
+
+```
+1. Resolver librería:
+   mcp__plugin_context7_context7__resolve-library-id
+   Input: nombre de librería (ej: "next.js", "prisma", "tailwindcss")
+   Output: ID exacto con versión
+
+2. Buscar documentación:
+   mcp__plugin_context7_context7__query-docs
+   Input: ID de librería + consulta específica
+   Output: Chunks de documentación + ejemplos
+```
+
+### Ejemplo
+
+```
+// Mal: Asumir sintaxis
+const router = useRouter(); // ¿Es correcto para Next.js 15?
+
+// Bien: Verificar primero
+1. resolve-library-id("next.js") → /vercel/next.js/v15.0.3
+2. query-docs(id, "useRouter app router") → [documentación actual]
+3. Usar sintaxis verificada
+```
+
+## Uso de WebSearch
+
+### Cuándo usar
+
+- Comparar opciones (ej: "Prisma vs Drizzle 2026")
+- Encontrar soluciones a errores específicos
+- Verificar tendencias actuales
+- Buscar artículos recientes
+
+### Cómo usar
+
+- SIEMPRE incluir el año actual en búsquedas
+- Verificar hallazgos con Context7 o docs oficiales
+- Marcar como MEDIUM confidence
+
+### Ejemplo
+
+```
+WebSearch: "best authentication library nextjs 2026"
+→ Encuentra: "NextAuth v5 es el estándar"
+→ Verificar: Context7 query-docs para NextAuth v5
+→ Usar: Información verificada
+```
+
+## Marcado de Confianza
+
+En RESEARCH.md y PLAN.md, siempre indicar:
+
+```markdown
+## Stack Verificado
+
+| Librería | Versión | Fuente | Confianza |
+|----------|---------|--------|-----------|
+| next.js | 15.0.3 | Context7 | HIGH |
+| prisma | 5.20.0 | Context7 | HIGH |
+| stripe | 14.0.0 | WebSearch + Context7 | HIGH |
+| custom-lib | 1.0.0 | GitHub README | MEDIUM |
+| otra-cosa | ? | Training data | LOW - VERIFICAR |
+```
+
+## Anti-Patrones
+
+### ❌ No hacer
+
+```
+// Asumir sin verificar
+"Usa el patrón estándar de Next.js..."
+
+// Inventar APIs
+"La función createUser() acepta..."
+
+// Mezclar versiones
+"En Next.js puedes usar getServerSideProps..."
+(Esto es Pages Router, no App Router)
+```
+
+### ✅ Hacer
+
+```
+// Verificar primero
+"Según Context7 (Next.js v15.0.3), el patrón actual es..."
+
+// Citar fuente
+"De acuerdo a la documentación oficial de Prisma 5.20..."
+
+// Especificar versión
+"Para Next.js 15 con App Router, usa Server Components..."
+```
+
+## Proceso de Investigación
+
+```
+1. ¿Es sobre una librería/framework?
+   SÍ → Context7 primero
+   NO → Continuar
+
+2. ¿Context7 tiene información?
+   SÍ → Usar como fuente principal
+   NO → WebFetch a docs oficiales
+
+3. ¿Necesito comparar opciones?
+   SÍ → WebSearch con año actual
+   NO → Continuar
+
+4. ¿La información es reciente?
+   SÍ → Marcar confianza apropiada
+   NO → Buscar fuente más reciente
+
+5. Documentar fuente y confianza
+```

package/references/token-optimization.md

@@ -0,0 +1,225 @@
+---
+name: token-optimization
+description: Estrategias para usar el contexto de Claude eficientemente (regla del 50%, lazy loading, waves)
+---
+
+# Optimización de Tokens
+
+Esta referencia define estrategias para usar el contexto de Claude de forma eficiente, manteniendo calidad.
+
+## El Problema
+
+Claude tiene una ventana de contexto limitada (~200K tokens). Cuando se llena:
+- La calidad de respuestas degrada
+- El modelo "olvida" instrucciones anteriores
+- Aumentan las alucinaciones
+
+## Solución: Context Budgeting
+
+### Regla del 50%
+
+**Cada plan debe poder ejecutarse usando máximo 50% del contexto.**
+
+¿Por qué 50%?
+- Deja espacio para el código generado
+- Deja espacio para errores y correcciones
+- Mantiene calidad consistente
+
+Si un plan necesita más:
+- Dividirlo en múltiples planes
+- Ejecutar en waves separadas
+
+### Presupuesto por Componente
+
+| Componente | Budget Máximo | Notas |
+|------------|---------------|-------|
+| PROJECT.md | 5% | Resumen del proyecto |
+| REQUIREMENTS.md | 5% | Lista de requisitos |
+| RESEARCH.md | 10% | Solo hallazgos relevantes |
+| PLAN.md | 15% | El plan actual |
+| Código existente | 10% | Solo archivos relevantes |
+| **Buffer** | 5% | Para imprevistos |
+| **Total en entrada** | ~50% | Dejar 50% para output |
+
+## Estrategias de Optimización
+
+### 1. Lazy Loading
+
+**NO hacer:**
+```
+Cargar TODO el codebase al inicio
+Cargar TODA la documentación
+```
+
+**SÍ hacer:**
+```
+Cargar solo archivos relevantes para ESTA tarea
+Cargar solo secciones de docs necesarias
+Usar @references que se resuelven on-demand
+```
+
+### 2. Compresión de Artifacts
+
+**RESEARCH.md debe ser:**
+```markdown
+## Stack: Next.js 15 + Prisma 5
+
+### Auth
+- Usar NextAuth v5
+- Patrón: middleware + session
+
+### Pitfalls
+- No usar jsonwebtoken (CommonJS issues)
+```
+
+**NO debe ser:**
+```markdown
+## Investigación Exhaustiva de Opciones de Autenticación
+
+Después de analizar múltiples opciones incluyendo
+Passport.js, Auth0, Clerk, y NextAuth, hemos determinado
+que para este proyecto específico considerando los
+requisitos de escalabilidad y facilidad de implementación...
+[300 líneas más]
+```
+
+### 3. Referencias, No Copias
+
+**NO hacer:**
+```markdown
+## Contexto
+[Copiar todo PROJECT.md aquí]
+[Copiar todo REQUIREMENTS.md aquí]
+```
+
+**SÍ hacer:**
+```markdown
+## Contexto
+@.planning/PROJECT.md
+@.planning/REQUIREMENTS.md
+
+Solo estos puntos relevantes:
+- Requisito R3: Autenticación
+- Decisión D2: Usar NextAuth
+```
+
+### 4. Agentes con Contexto Fresco
+
+**Patrón:** Spawnnear agentes especializados
+
+Cada agente obtiene ~200K tokens frescos.
+El orquestador mantiene solo el estado mínimo.
+
+```
+Orquestador (30% contexto):
+  - Coordina
+  - Mantiene estado
+  - Agrega resultados
+
+Agente 1 (100% fresco):
+  - Investiga tema A
+  - Retorna resumen
+
+Agente 2 (100% fresco):
+  - Investiga tema B
+  - Retorna resumen
+```
+
+### 5. Waves para Paralelización
+
+```
+Wave 1: [Planes independientes]
+  Plan 1: Contexto fresco
+  Plan 2: Contexto fresco
+
+Wave 2: [Dependen de Wave 1]
+  Plan 3: Contexto fresco + summaries de Wave 1
+```
+
+## Métricas de Salud
+
+### Señales de Contexto Sano
+
+- Respuestas coherentes y completas
+- Sigue instrucciones correctamente
+- No repite información
+- No "olvida" decisiones anteriores
+
+### Señales de Contexto Saturado
+
+- Respuestas vagas o incompletas
+- Olvida instrucciones recientes
+- Mezcla información de diferentes partes
+- Aumentan alucinaciones
+
+### Acción si Saturado
+
+```
+1. STOP - No seguir agregando contexto
+2. Crear nuevo plan más pequeño
+3. Spawnnear agente fresco
+4. Resumir lo hecho y continuar en nueva sesión
+```
+
+## Templates Optimizados
+
+### PLAN.md Optimizado
+
+```markdown
+---
+phase: 1
+plan: 1
+wave: 1
+must_haves:
+  truths: ["User can login"]
+  artifacts: [{path: "src/app/login/page.tsx"}]
+---
+
+# Login Page
+
+## Contexto
+@.planning/RESEARCH.md#auth
+
+## Tareas
+
+<task>
+  <name>Create login form</name>
+  <files>src/app/login/page.tsx</files>
+  <action>Form with email/password, NextAuth signIn()</action>
+  <verify>npm run build</verify>
+</task>
+```
+
+**Nota:** Solo referencias, no copias. Solo lo necesario.
+
+### SUMMARY.md Optimizado
+
+```markdown
+# Summary: Login (01-01)
+
+## Done
+- [x] Login form created
+- [x] NextAuth configured
+
+## Files
+- src/app/login/page.tsx
+- src/lib/auth.ts
+
+## Verify
+- [x] Build passes
+- [ ] User test: can login
+```
+
+**Nota:** Bullets, no prosa. Solo hechos.
+
+## Checklist Pre-Ejecución
+
+Antes de ejecutar un plan, verificar:
+
+- [ ] ¿El plan cabe en 50% del contexto?
+- [ ] ¿Las referencias son específicas (no "todo el archivo")?
+- [ ] ¿El research está resumido?
+- [ ] ¿Hay espacio para el código a generar?
+- [ ] ¿Puedo dividir en partes más pequeñas?
+
+Si cualquiera falla → Optimizar antes de ejecutar.

package/skills/api-setup.md

@@ -0,0 +1,315 @@
+---
+name: api-setup
+description: Skill para crear APIs y endpoints. Usa este skill cuando el usuario quiere crear una API, backend, o endpoints.
+---
+
+# Skill: Setup de API/Backend
+
+<when_to_use>
+Usar cuando el usuario menciona:
+- "API"
+- "backend"
+- "endpoints"
+- "servidor"
+- "REST"
+- "GraphQL"
+- "rutas" (en contexto de backend)
+</when_to_use>
+
+<before_starting>
+## Investigación Obligatoria
+
+**ANTES de crear la API, entender el contexto:**
+
+```
+1. Detectar tipo de proyecto:
+   - ¿Ya tiene Next.js? → API Routes
+   - ¿Ya tiene Expo? → Necesita backend separado
+   - ¿Proyecto nuevo? → Sugerir opciones
+
+2. Preguntar al usuario:
+   - ¿Qué datos va a manejar la API?
+   - ¿Necesita autenticación?
+   - ¿Va a ser pública o privada?
+
+3. Buscar en Context7:
+   mcp__plugin_context7_context7__resolve-library-id("hono")
+   mcp__plugin_context7_context7__query-docs(id, "getting started")
+```
+</before_starting>
+
+<options_by_context>
+## Opciones por Contexto
+
+### Ya tiene Next.js → API Routes
+
+**Pros:**
+- No necesita servidor adicional
+- Comparte tipos con frontend
+- Deploy junto con la app
+
+**Ubicación:**
+```
+src/app/api/[endpoint]/route.ts
+```
+
+### Proyecto nuevo → Hono (Recomendado)
+
+**Pros:**
+- Ligero y rápido
+- TypeScript nativo
+- Funciona en edge, Node, Deno, Bun
+- Similar a Express pero moderno
+
+**Setup:**
+```bash
+npm create hono@latest my-api
+```
+
+### Alternativas
+
+| Opción | Cuándo Usar |
+|--------|-------------|
+| Express | Equipo ya lo conoce |
+| Fastify | Necesita máximo rendimiento |
+| tRPC | Frontend y backend TypeScript |
+| GraphQL | Queries complejas, múltiples clientes |
+</options_by_context>
+
+<nextjs_api_setup>
+## API Routes en Next.js
+
+### Paso 1: Crear endpoint
+
+```typescript
+// src/app/api/users/route.ts
+// VERIFICAR con Context7 para sintaxis actual
+
+import { NextResponse } from 'next/server'
+
+export async function GET() {
+  // Tu lógica aquí
+  return NextResponse.json({ users: [] })
+}
+
+export async function POST(request: Request) {
+  const body = await request.json()
+  // Crear usuario
+  return NextResponse.json({ success: true })
+}
+```
+
+### Paso 2: Endpoint con parámetros
+
+```typescript
+// src/app/api/users/[id]/route.ts
+
+import { NextResponse } from 'next/server'
+
+export async function GET(
+  request: Request,
+  { params }: { params: { id: string } }
+) {
+  const id = params.id
+  // Buscar usuario por id
+  return NextResponse.json({ user: { id } })
+}
+```
+
+### Paso 3: Validación con Zod
+
+```typescript
+// src/app/api/users/route.ts
+import { z } from 'zod'
+import { NextResponse } from 'next/server'
+
+const createUserSchema = z.object({
+  email: z.string().email(),
+  name: z.string().min(2),
+})
+
+export async function POST(request: Request) {
+  const body = await request.json()
+
+  const result = createUserSchema.safeParse(body)
+  if (!result.success) {
+    return NextResponse.json(
+      { error: result.error.flatten() },
+      { status: 400 }
+    )
+  }
+
+  // Crear usuario con result.data
+  return NextResponse.json({ success: true })
+}
+```
+</nextjs_api_setup>
+
+<hono_setup>
+## Setup Hono (Standalone API)
+
+### Paso 1: Crear proyecto
+
+```bash
+npm create hono@latest my-api
+# Seleccionar: nodejs
+cd my-api
+npm install
+```
+
+### Paso 2: Estructura básica
+
+```typescript
+// src/index.ts
+// VERIFICAR con Context7
+
+import { Hono } from 'hono'
+import { cors } from 'hono/cors'
+
+const app = new Hono()
+
+// Middleware
+app.use('/*', cors())
+
+// Rutas
+app.get('/', (c) => c.json({ message: 'API funcionando' }))
+
+app.get('/users', (c) => {
+  return c.json({ users: [] })
+})
+
+app.post('/users', async (c) => {
+  const body = await c.req.json()
+  return c.json({ success: true })
+})
+
+export default app
+```
+
+### Paso 3: Validación con Zod
+
+```typescript
+import { Hono } from 'hono'
+import { zValidator } from '@hono/zod-validator'
+import { z } from 'zod'
+
+const app = new Hono()
+
+const createUserSchema = z.object({
+  email: z.string().email(),
+  name: z.string().min(2),
+})
+
+app.post(
+  '/users',
+  zValidator('json', createUserSchema),
+  async (c) => {
+    const data = c.req.valid('json')
+    // data está tipado y validado
+    return c.json({ success: true })
+  }
+)
+```
+
+### Paso 4: Ejecutar
+
+```bash
+npm run dev
+```
+</hono_setup>
+
+<verification>
+## Verificación
+
+### Automática
+```bash
+# Probar endpoint GET
+curl http://localhost:3000/api/users
+
+# Probar endpoint POST
+curl -X POST http://localhost:3000/api/users \
+  -H "Content-Type: application/json" \
+  -d '{"email":"test@example.com","name":"Test"}'
+```
+
+### Manual (para usuario)
+```
+Para ti (Usuario):
+
+1. Abre tu navegador
+2. Ve a: http://localhost:3000/api/users
+3. Deberías ver una respuesta JSON
+
+¿Ves datos JSON?
+- SÍ → La API está funcionando
+- NO → Verifica que el servidor esté corriendo
+```
+</verification>
+
+<common_patterns>
+## Patrones Comunes
+
+### Middleware de autenticación
+
+```typescript
+// middleware/auth.ts
+import { createMiddleware } from 'hono/factory'
+
+export const authMiddleware = createMiddleware(async (c, next) => {
+  const token = c.req.header('Authorization')?.replace('Bearer ', '')
+
+  if (!token) {
+    return c.json({ error: 'No autorizado' }, 401)
+  }
+
+  // Verificar token
+  // c.set('user', decodedUser)
+
+  await next()
+})
+```
+
+### Manejo de errores
+
+```typescript
+app.onError((err, c) => {
+  console.error(err)
+  return c.json(
+    { error: 'Error interno del servidor' },
+    500
+  )
+})
+```
+
+### Rate limiting
+
+```typescript
+import { rateLimiter } from 'hono-rate-limiter'
+
+app.use(
+  rateLimiter({
+    windowMs: 15 * 60 * 1000, // 15 minutos
+    limit: 100, // 100 requests por ventana
+    message: { error: 'Demasiadas solicitudes' },
+  })
+)
+```
+</common_patterns>
+
+<common_issues>
+## Problemas Comunes
+
+### "CORS error"
+- Agregar middleware de CORS
+- Verificar origin permitido
+- En Next.js: configurar headers en next.config.js
+
+### "404 Not Found"
+- Verificar ruta del archivo
+- En Next.js: debe estar en app/api/
+- Verificar nombre del archivo (route.ts)
+
+### "Method not allowed"
+- Exportar la función con el nombre correcto (GET, POST, etc.)
+- Verificar que el método existe en el archivo
+</common_issues>