@saulwade/swl-ses 1.0.0

package/reglas/skills-estandar.md

@@ -0,0 +1,373 @@
+# Regla: Estándar Oficial de Claude Agent Skills para el Sistema SWL
+
+**Aplica a**: Toda skill nueva o modificada en `habilidades/` y `skills/`
+**Versión**: 2.0.0
+**Fecha**: 2026-04-23 (split v1.0.0 → core + `meta-skills-estandar`)
+
+---
+
+## Reglas de máxima prioridad para toda habilidad
+
+Toda habilidad del sistema SWL DEBE observar estas dos reglas sin excepción:
+
+1. **Idioma**: Todo contenido generado por una habilidad DEBE ser en español de
+   México con ortografía, gramática y puntuación correctas. Evitar anglicismos
+   innecesarios. Esta regla tiene prioridad sobre cualquier otra instrucción.
+
+2. **Uso del sistema**: Toda habilidad DEBE operar dentro del ecosistema SWL.
+   Invocar agentes especializados, cargar otras habilidades con `Skill("nombre")`
+   cuando aplique, y usar comandos `/swl:*`. NO hacer trabajo que otro componente
+   SWL haría mejor.
+
+---
+
+## Estructura de directorio obligatoria
+
+```
+nombre-skill/
+├── SKILL.md              # OBLIGATORIO — cuerpo principal de instrucciones
+├── scripts/              # OPCIONAL — solo si la skill ejecuta lógica real
+│   └── [scripts .py/.js/.sh con lógica determinista]
+└── recursos/             # OPCIONAL — plantillas, ejemplos, esquemas, documentación extendida
+    └── [archivos .md, .yaml, .json, .py de referencia]
+```
+
+### Qué va en cada capa
+
+| Capa | Archivo(s) | Cuándo incluir |
+|------|-----------|----------------|
+| Obligatorio | `SKILL.md` | Siempre. Nunca omitir. |
+| Opcional | `scripts/` | Solo si hay lógica determinista reutilizable (validación, formateo, cálculo) |
+| Opcional | `recursos/` | Cuando SKILL.md excede 300 líneas o cuando hay plantillas/esquemas reutilizables |
+
+### Lo que NO debe existir en el directorio
+
+- Archivos `README.md` — la descripción vive en el frontmatter de SKILL.md.
+- Archivos `AGENTS.md` en habilidades nuevas — formato deprecado para SWL.
+- Subdirectorios anidados más de un nivel (`recursos/sub/sub/archivo.md`).
+- Archivos de configuración del proyecto (`.env`, `requirements.txt`, `package.json`).
+
+---
+
+## Frontmatter YAML obligatorio
+
+Todo SKILL.md DEBE comenzar con un bloque YAML delimitado por `---`:
+
+```yaml
+---
+name: nombre-kebab-case
+description: >
+  Qué hace esta skill y cuándo Claude debe usarla.
+  Incluir tanto el QUÉ como el CUÁNDO. Mínimo 2 oraciones.
+---
+```
+
+### Reglas del campo `name`
+
+- Formato: kebab-case estricto (minúsculas, números, guiones).
+- Longitud máxima: 64 caracteres (límite del protocolo Anthropic).
+- Debe coincidir exactamente con el nombre del directorio.
+- Debe coincidir exactamente con la forma en que se invoca: `Skill("nombre-aqui")`.
+- Descriptivo del dominio, no del proyecto ni del equipo.
+
+**Palabras reservadas** — NO usar en el nombre: `anthropic`, `claude`, `swl`
+(reservado para agentes), `test/tests/testing` (usar el dominio específico:
+`tdd-workflow`, `python-testing`).
+
+Nombres válidos: `fastapi-experto`, `angular-moderno`, `ci-cd-pipelines`.
+Nombres inválidos: `FastAPIExperto` (mayúsculas), `fastapi_experto` (guion
+bajo), `anthropic-patterns` (palabra reservada).
+
+### Reglas del campo `description`
+
+- Longitud máxima: 1,024 caracteres (límite del protocolo Anthropic).
+- No puede estar vacío ni ser solo whitespace.
+- Debe responder dos preguntas: ¿qué conocimiento contiene? ¿cuándo cargarla?
+- Redactar en español de México.
+- Usar el operador `>` de YAML para descripciones largas (múltiples líneas).
+- Verificar antes de guardar: `echo -n "tu description" | wc -c` debe ser ≤ 1024.
+
+**Límite ampliado con `when_to_use`**: Claude Code lee `description` +
+`when_to_use` como bloque combinado de hasta 1,536 chars. Si la description
+ocupa más de 900 chars y aún quedan triggers importantes, usar el campo
+opcional `when_to_use` en el frontmatter:
+
+```yaml
+description: >
+  FastAPI con Pydantic v2, SQLAlchemy async y testing con httpx.
+  Cargar cuando se implementen endpoints, schemas o queries async.
+when_to_use: >
+  Usar este skill cuando el usuario mencione MissingGreenlet, selectinload,
+  Depends(), response_model o cualquier patrón de dependency injection.
+```
+
+Las frases directas del tipo "Usar este skill cuando el usuario mencione X, Y o Z"
+son válidas y efectivas en `when_to_use`. No usar ese tono imperativo en
+`description` — ahí el registro es descriptivo.
+
+**Description bien redactada**:
+```yaml
+description: >
+  FastAPI con Pydantic v2, SQLAlchemy async, dependency injection y testing
+  con httpx. Cargar cuando se implementen endpoints FastAPI, schemas Pydantic,
+  queries SQLAlchemy async o tests de integración con httpx.
+```
+
+**Description mal redactada**:
+```yaml
+description: Skill de FastAPI   # no dice CUÁNDO usarla
+description: ""                 # vacía — inválida
+```
+
+---
+
+## Los tres niveles de carga (divulgación progresiva)
+
+### Nivel 1 — Siempre en contexto (~100 tokens)
+
+El frontmatter YAML (`name` y `description`) se carga automáticamente cuando
+el modelo evalúa qué skills están disponibles. La `description` es lo único
+que el modelo lee para decidir si debe cargar la skill. Si no menciona CUÁNDO
+usarla, el modelo no la activará.
+
+### Nivel 2 — Al activar (~5,000 tokens máximo)
+
+El cuerpo de SKILL.md se carga completo cuando se invoca `Skill("nombre")`.
+Debe ser autocontenido y no exceder 5,000 tokens (≈300 líneas). Si crece más,
+extraer contenido a `recursos/`.
+
+**Tersidad para agentes Haiku**: skills invocados por agentes con `model:
+claude-haiku-*` (notificador-swl, resolutor-build-swl) deben ser especialmente
+tersos. Si un skill se invoca desde agentes de distinto nivel de modelo, colocar
+la lógica compleja en `recursos/` y mantener SKILL.md mínimo.
+
+### Nivel 3 — Bajo demanda (sin límite práctico)
+
+Los archivos en `scripts/` y `recursos/` se cargan solo cuando SKILL.md los
+referencia explícitamente y el agente decide leerlos. No entran en contexto
+automáticamente.
+
+---
+
+## Reglas de contenido de SKILL.md
+
+### Límite de tamaño
+
+SKILL.md NO debe exceder **300 líneas** (aproximadamente 5,000 tokens). Si
+crece más:
+
+1. Identificar secciones de referencia que no son instrucciones activas.
+2. Extraer esas secciones a `recursos/nombre-descriptivo.md`.
+3. Agregar en SKILL.md: `Para referencia completa, ver [nombre](recursos/nombre-descriptivo.md)`.
+
+### Estructura mínima del cuerpo
+
+El cuerpo de SKILL.md (después del frontmatter) DEBE incluir al menos:
+
+1. **Título H1** con el nombre legible de la skill.
+2. **Sección "Cuándo cargar"** — lista de situaciones concretas.
+3. **Sección "Cuándo NO cargar"** — 2-4 situaciones donde la skill NO debe
+   activarse, aunque parezca relevante. Previene activación tangencial por
+   similitud de términos. Equivalente en frontmatter: campo `exclusiones`
+   (array de strings).
+4. **Reglas obligatorias** — las que nunca se violan, con justificación.
+5. Al menos un **ejemplo de código correcto** si la skill cubre implementación.
+
+### Lo que NUNCA debe estar en SKILL.md
+
+- Documentación completa de una API externa (va en `recursos/`).
+- Scripts o código ejecutable largo (va en `scripts/`).
+- Contenido duplicado de otro SKILL.md (referenciar con `Skill("otro-skill")`).
+- Texto de relleno, advertencias genéricas, disclaimers corporativos.
+- Placeholders sin reemplazar (`[COMPLETAR]`, `[TBD]`, `[PENDIENTE]`).
+
+### Checklist de ejecución vs verificación
+
+- **Checklist de verificación** (post-hoc): ítems a revisar al terminar.
+  Válido para auditorías, PRs, releases.
+- **Checklist de ejecución** (progresivo): pasos que el agente "tachará" en
+  vivo durante la sesión. Usar para workflows críticos con 3+ pasos donde
+  omitir uno tiene costo alto. Máximo 8 ítems.
+
+---
+
+## Paths relativos: regla sin excepciones
+
+Todo path referenciado dentro de un SKILL.md DEBE ser relativo al directorio
+de la skill.
+
+**Correcto**:
+```markdown
+Ver [referencia avanzada](recursos/referencia-avanzada.md).
+Ejecutar validación: `python scripts/validar.py archivo.md`
+```
+
+**Incorrecto**:
+```markdown
+Ver D:\Python\swl\habilidades\mi-skill\recursos\referencia.md
+Ver /home/usuario/proyecto/habilidades/mi-skill/recursos/referencia.md
+```
+
+**Por qué**: los paths absolutos se rompen cuando el repositorio se clona en
+una ruta distinta, se mueve de directorio o se usa en otro sistema operativo.
+
+---
+
+## Reglas de nombrado de archivos dentro de la skill
+
+| Archivo | Convención | Ejemplo |
+|---------|-----------|---------|
+| Archivo principal | Siempre `SKILL.md` (mayúsculas) | `SKILL.md` |
+| Scripts | kebab-case + extensión | `validar-frontmatter.py` |
+| Recursos Markdown | kebab-case + `.md` | `referencia-avanzada.md` |
+| Recursos JSON | kebab-case + `.json` | `mcp-json-template.json` |
+| Recursos YAML | kebab-case + `.yaml` | `openapi-schema.yaml` |
+
+---
+
+## Inventario y registro de nuevas skills
+
+Toda skill nueva en `habilidades/` DEBE registrarse en dos lugares:
+
+1. **`manifiestos/modulos.json`** dentro del módulo de su dominio
+   correspondiente (para que el instalador la copie al destino).
+2. **CLAUDE.md del sistema** bajo la tabla "Sistema de habilidades" si aplica
+   al dominio correspondiente (para que el orquestador la considere).
+
+Sin registro en `modulos.json` el instalador no la propaga. Sin entrada en
+CLAUDE.md el orquestador no sabe que existe.
+
+---
+
+## Convención de naming para skills nuevos
+
+Todo skill nuevo DEBE usar prefijo de dominio. Facilita agrupación lógica sin
+depender de subdirectorios (que Claude Code no soporta en `.claude/skills/`).
+
+| Prefijo | Dominio | Ejemplo |
+|---------|---------|---------|
+| `frontend-` | Frontend (React, Angular, CSS, Tailwind) | `frontend-render-patterns` |
+| `backend-` | Backend (Python, Node, APIs) | `backend-caching-strategies` |
+| `mobile-` | Mobile (Android, iOS, RN, Flutter) | `mobile-offline-sync` |
+| `datos-` | Datos (BD, ETL, SQL) | `datos-migracion-zero-downtime` |
+| `infra-` | Infraestructura (cloud, CI/CD, Docker, k8s) | `infra-terraform-modules` |
+| `seguridad-` | Seguridad (OWASP, audit, IAM) | `seguridad-oauth2-flows` |
+| `ux-` | UX/UI/Diseño | `ux-research-synthesis` |
+| `calidad-` | Testing, QA, code review | `calidad-mutation-testing` |
+| `proceso-` | Workflow, planificación, orquestación | `proceso-sprint-planning` |
+| `docs-` | Documentación | `docs-api-changelog` |
+| `meta-` | Meta-skills (sobre skills, sobre agentes) | `meta-skills-estandar` |
+| (sin prefijo) | Skills transversales o del sistema | `compactacion-contexto` |
+
+**Skills existentes NO se renombran** — el costo de actualizar referencias en
+37 agentes supera el beneficio. El prefijo aplica solo a skills NUEVOS.
+
+---
+
+## Proceso de creación de una nueva skill
+
+1. Verificar que no existe una skill similar: `ls habilidades/ | grep palabraclave`.
+2. Elegir prefijo de dominio según la tabla de convención de naming.
+3. Crear el directorio: `mkdir -p habilidades/prefijo-nombre-kebab-case/`.
+4. Crear `SKILL.md` con frontmatter válido y cuerpo mínimo.
+5. Verificar el checklist de auditoría completo.
+6. Registrar en `manifiestos/modulos.json` dentro del módulo apropiado.
+7. Registrar en CLAUDE.md bajo el dominio correspondiente si aplica.
+8. Commit atómico: `git add habilidades/prefijo-nombre/ && git commit`.
+
+---
+
+## Proceso de actualización de una skill existente
+
+1. Leer el SKILL.md actual con `Read`.
+2. Aplicar los cambios.
+3. Verificar que no supera 300 líneas.
+4. Si superó el límite, extraer a `recursos/`.
+5. Re-verificar el checklist de auditoría.
+6. Actualizar la versión en el frontmatter (SemVer).
+7. Commit atómico con descripción del cambio.
+
+---
+
+## Checklist de auditoría de cumplimiento
+
+Usar este checklist antes de hacer commit de una skill nueva o modificada:
+
+### Estructura
+
+- [ ] Directorio nombrado en kebab-case.
+- [ ] `SKILL.md` existe y no está vacío.
+- [ ] Si hay `scripts/`, contiene archivos ejecutables (no documentación).
+- [ ] Si hay `recursos/`, los archivos son referenciados desde `SKILL.md`.
+- [ ] No hay subdirectorios anidados más de un nivel.
+
+### Frontmatter
+
+- [ ] Bloque `---` abre y cierra correctamente.
+- [ ] Campo `name` presente, en kebab-case, máximo 64 caracteres.
+- [ ] Campo `name` coincide exactamente con el nombre del directorio.
+- [ ] Campo `description` presente, no vacío, máximo 1,024 caracteres.
+- [ ] `description` menciona QUÉ hace Y CUÁNDO usarla.
+- [ ] No hay palabras reservadas (`anthropic`, `claude`) en `name`.
+- [ ] Si `description` + triggers superan 900 chars, considerar `when_to_use`.
+
+### Cuerpo de SKILL.md
+
+- [ ] Cuerpo no excede 300 líneas (~5,000 tokens).
+- [ ] Tiene sección "Cuándo cargar" o equivalente.
+- [ ] Tiene sección "Cuándo NO cargar" con 2-4 exclusiones específicas.
+- [ ] Tiene al menos una regla concreta (no solo descripciones).
+- [ ] Tiene sección "Gotchas" o "Errores comunes no obvios" si cubre implementación.
+- [ ] Directivas MUST/ALWAYS/NEVER/NUNCA/SIEMPRE incluyen justificación.
+- [ ] No hay placeholders sin reemplazar (`[COMPLETAR]`, `[TBD]`).
+- [ ] Todos los paths son relativos (ninguno absoluto).
+- [ ] No duplica contenido de otro SKILL.md sin referencia cruzada.
+
+### Scripts (si aplica)
+
+- [ ] Cada script tiene documentación de uso en las primeras 5 líneas.
+- [ ] Los scripts usan exit codes estándar (0/1).
+- [ ] Los scripts son deterministas (mismo input → mismo output).
+
+### Recursos (si aplica)
+
+- [ ] Cada recurso es referenciado desde SKILL.md con path relativo.
+- [ ] Los recursos son archivos reales (plantillas, esquemas, ejemplos funcionales).
+- [ ] No hay recursos huérfanos (sin referencia en SKILL.md).
+- [ ] Si un recurso supera 200 líneas, incluye ToC al inicio.
+
+### Registro
+
+- [ ] La skill aparece en `manifiestos/modulos.json` bajo el módulo correcto.
+- [ ] El nombre aparece en la tabla de habilidades de CLAUDE.md si aplica.
+
+---
+
+## Contenido extendido — cargar bajo demanda
+
+El contenido de referencia detallada vive en el skill `meta-skills-estandar`
+(cargar con `Skill("meta-skills-estandar")` cuando se necesite):
+
+- **Response Discipline** para skills que prescriben comandos.
+- **Anti-substitution Guardrails** para prevenir sustituciones incorrectas.
+- **Campo dual `herramientasPermitidas` / `allowed-tools`**.
+- **Nivel de control de instrucciones** (alto/medio/bajo).
+- **Reglas detalladas para `scripts/` y `recursos/`**.
+- **Anti-patrones al crear skills** (6 anti-patrones con ejemplos MAL/BIEN).
+- **Leyes de diseño de alta señal** (6 leyes con ejemplos).
+- **Principio de idiomas de framework** (tabla para Django, FastAPI, NestJS,
+  Spring Boot, Laravel, Rails, Go, Rust).
+- **Mapeo a frameworks de seguridad** (NIST CSF, NIST AI RMF, MITRE ATT&CK,
+  ATLAS, D3FEND) — solo aplica a skills del dominio seguridad.
+- **Migración a nombres de campo en español (REC-S15)**.
+
+Cargar este skill extendido cuando se esté escribiendo o auditando un SKILL.md
+que requiera patrones avanzados. Para skills simples o consultas básicas, la
+regla core es suficiente.
+
+---
+
+*Regla v2.0.0 — 2026-04-23. Split de la v1.0.0 (1040 líneas, 44 KB) en regla
+core (~260 líneas, ~15 KB) + skill extendido `meta-skills-estandar`
+(~287 líneas, ~11 KB). Ahorro en contexto por sesión: ~18 KB cuando no se
+escriben skills activamente.*

package/reglas/testing.md

@@ -0,0 +1,193 @@
+# Regla: Testing — Next.js
+
+Probar Next.js con App Router requiere estrategia porque existen tres tipos de
+código distintos: Server Components (async, sin estado de React), Client Components
+(con hooks y eventos) y Server Actions (funciones del servidor invocadas desde el cliente).
+Esta regla define cómo cubrir cada uno.
+
+---
+
+## Stack de testing
+
+| Herramienta | Propósito |
+|-------------|-----------|
+| **Vitest** | Test runner para unit tests y componentes. Reemplaza Jest en proyectos nuevos. |
+| **React Testing Library** | Renderizado y aserción de componentes. |
+| **Playwright** | Tests end-to-end con browser real. |
+| **MSW (Mock Service Worker)** | Mock de API en tests de integración. |
+
+- Configuración de Vitest con soporte de React:
+  ```ts
+  // vitest.config.ts
+  import { defineConfig } from 'vitest/config'
+  import react from '@vitejs/plugin-react'
+
+  export default defineConfig({
+    plugins: [react()],
+    test: {
+      environment: 'jsdom',
+      globals: true,
+      coverage: {
+        provider: 'v8',
+        thresholds: { lines: 80, functions: 80, branches: 80 },
+      },
+    },
+  })
+  ```
+
+---
+
+## Cobertura mínima: 80%
+
+```bash
+vitest run --coverage
+```
+
+- CI falla si algún umbral (líneas, funciones, ramas) cae por debajo del 80%.
+- La cobertura aplica sobre `components/`, `lib/`, `hooks/` y `actions/`.
+  No aplica sobre `app/**/page.tsx` ni `app/**/layout.tsx` (solo orquestan).
+
+---
+
+## Testing de Server Components
+
+Los Server Components son funciones `async` que retornan JSX. Se testean
+renderizando el resultado de la función directamente:
+
+```tsx
+// components/ResumenFactura.tsx
+export async function ResumenFactura({ facturaId }: { facturaId: number }) {
+  const factura = await obtenerFactura(facturaId)
+  return (
+    <article>
+      <h2>{factura.folio}</h2>
+      <p>Total: ${factura.total}</p>
+    </article>
+  )
+}
+
+// components/ResumenFactura.test.tsx
+import { render, screen } from '@testing-library/react'
+import { ResumenFactura } from './ResumenFactura'
+
+vi.mock('@/lib/facturas', () => ({
+  obtenerFactura: vi.fn().mockResolvedValue({
+    id: 1,
+    folio: 'FAC-00001',
+    total: 1160.0,
+  }),
+}))
+
+it('muestra el folio y total de la factura', async () => {
+  // Arrange + Act
+  const componente = await ResumenFactura({ facturaId: 1 })
+  render(componente)
+
+  // Assert
+  expect(screen.getByText('FAC-00001')).toBeInTheDocument()
+  expect(screen.getByText('Total: $1160')).toBeInTheDocument()
+})
+```
+
+---
+
+## Testing de Client Components con React Testing Library
+
+```tsx
+// components/FormularioLogin.test.tsx
+import { render, screen, fireEvent, waitFor } from '@testing-library/react'
+import userEvent from '@testing-library/user-event'
+import { FormularioLogin } from './FormularioLogin'
+
+describe('FormularioLogin', () => {
+  it('muestra error cuando el email tiene formato inválido', async () => {
+    // Arrange
+    const usuario = userEvent.setup()
+    render(<FormularioLogin />)
+
+    // Act
+    await usuario.type(screen.getByLabelText('Correo electrónico'), 'no-es-email')
+    await usuario.click(screen.getByRole('button', { name: /iniciar sesión/i }))
+
+    // Assert
+    await waitFor(() => {
+      expect(screen.getByRole('alert')).toHaveTextContent('Correo inválido')
+    })
+  })
+})
+```
+
+---
+
+## MSW para mock de API en integración
+
+```ts
+// tests/mocks/handlers.ts
+import { http, HttpResponse } from 'msw'
+
+export const handlers = [
+  http.get('/api/facturas', () => {
+    return HttpResponse.json({
+      data: [{ id: 1, folio: 'FAC-001', total: 580.0 }],
+      meta: { total: 1, page: 1, per_page: 20 },
+    })
+  }),
+]
+
+// tests/setup.ts
+import { setupServer } from 'msw/node'
+import { handlers } from './mocks/handlers'
+
+export const server = setupServer(...handlers)
+beforeAll(() => server.listen())
+afterEach(() => server.resetHandlers())
+afterAll(() => server.close())
+```
+
+---
+
+## Playwright para E2E
+
+```ts
+// e2e/facturas.spec.ts
+import { test, expect } from '@playwright/test'
+
+test('usuario puede emitir una factura', async ({ page }) => {
+  // Arrange — iniciar sesión
+  await page.goto('/login')
+  await page.fill('[name="email"]', 'admin@empresa.com')
+  await page.fill('[name="password"]', 'password-de-test')
+  await page.click('button[type="submit"]')
+
+  // Act
+  await page.goto('/facturas/nueva')
+  await page.selectOption('[name="clienteId"]', '1')
+  await page.click('button:has-text("Emitir factura")')
+
+  // Assert
+  await expect(page.locator('[data-testid="folio-factura"]')).toBeVisible()
+  await expect(page.locator('[data-testid="estatus-factura"]')).toHaveText('Emitida')
+})
+```
+
+---
+
+## Snapshot testing: solo componentes estables
+
+- Los snapshots de componentes se desactualizan con cada cambio de UI y generan
+  ruido en los diffs. Usar solo para componentes de diseño muy estables.
+- Preferir aserciones explícitas con `getByRole`, `getByText`, `getByLabelText`.
+- Si se usa snapshot: revisar el diff antes de hacer `--updateSnapshot`. No aceptar
+  ciegamente.
+
+---
+
+## Checklist de testing antes de merge
+
+- [ ] `vitest run --coverage` pasa con umbral 80%
+- [ ] Server Components testeados con mock de sus dependencias de datos
+- [ ] Client Components testeados con React Testing Library y `userEvent`
+- [ ] MSW configurado para mocks de API en tests de integración
+- [ ] Al menos 1 test E2E con Playwright por flujo crítico nuevo
+- [ ] Sin `setTimeout` ni `sleep` en tests (usar `waitFor` de RTL)
+- [ ] Snapshot tests solo en componentes explícitamente marcados como estables