@cristiancorreau/forge 2.1.0

package/assets/core/skills/browser-test/SKILL.md

@@ -0,0 +1,177 @@
+# Skill: browser-test
+
+Automatización de navegador para verificar UI en desarrollo, testear visualmente
+flujos críticos y capturar evidencia. Usa `agent-browser` (CLI en Rust sobre CDP).
+
+Triggers: /browser-test, "abrir en browser", "screenshot de", "verificar que
+renderiza", "testear visualmente", "navegar a", "probar el flujo de", "ver cómo
+se ve", "revisar esta URL", "capturar pantalla de", "test visual", "open <url>".
+
+Prerequisito: `agent-browser` instalado globalmente.
+  Instalar: `npm i -g agent-browser && agent-browser install`
+  Verificar: `agent-browser --version`
+
+---
+
+## Cuándo usar este skill
+
+- Verificar que una página renderiza correctamente antes de dar una tarea por terminada
+- Testear visualmente flujos críticos (login, onboarding, formularios)
+- Inspeccionar una URL que el usuario proporciona
+- Capturar screenshots como evidencia de implementación o compliance
+- Hacer diff visual entre dos versiones de una misma página
+- Testear responsive en viewport mobile sin abrir DevTools manualmente
+- Extraer contenido de una URL pública para investigación
+
+---
+
+## Flujo core
+
+```bash
+# 1. Navegar y ver qué hay
+agent-browser open <url>
+agent-browser snapshot -i           # accessibility tree — interactive elements only
+                                    # produce refs @e1, @e2... para interactuar
+
+# 2. Interactuar con refs del snapshot
+agent-browser click @e3
+agent-browser fill @e4 "texto"
+agent-browser snapshot -i           # re-snapshot SIEMPRE después de un cambio de página
+
+# 3. Capturar estado
+agent-browser screenshot            # guarda a /tmp auto-named
+agent-browser screenshot page.png   # o a un path específico
+agent-browser close
+```
+
+Los refs (`@e1`, `@e2`...) se vuelven stale al cambiar la página. Siempre
+re-snapshot antes del siguiente ref interaction.
+
+---
+
+## Casos de uso frecuentes
+
+### Verificar que una ruta dev renderiza
+
+```bash
+agent-browser open http://localhost:3000/ruta
+agent-browser snapshot -i            # leer si hay errores o elementos esperados
+agent-browser screenshot check.png
+agent-browser close
+```
+
+### Diff visual entre dos versiones
+
+```bash
+# Tomar baseline antes del cambio
+agent-browser open http://localhost:3000/pagina && agent-browser screenshot baseline.png
+
+# Después del cambio
+agent-browser open http://localhost:3000/pagina && agent-browser diff screenshot --baseline baseline.png
+```
+
+### Testear en mobile viewport
+
+```bash
+agent-browser set device "iPhone 14"
+agent-browser open <url>
+agent-browser screenshot mobile.png
+agent-browser close
+```
+
+### Extraer contenido de una URL
+
+```bash
+agent-browser open <url>
+agent-browser snapshot                  # árbol completo, sin filtro -i
+agent-browser get text "#main"          # extraer texto de un selector
+agent-browser close
+```
+
+### Verificar web vitals
+
+```bash
+agent-browser vitals <url> --json       # LCP, CLS, TTFB, FCP, INP
+```
+
+### Inspeccionar network requests
+
+```bash
+agent-browser open <url>
+agent-browser wait --load networkidle
+agent-browser network requests --type xhr,fetch --json   # APIs llamadas
+agent-browser network requests --method POST --json       # solo POSTs
+```
+
+---
+
+## Selección de elementos
+
+```bash
+# Por ref del snapshot (recomendado — determinístico)
+agent-browser click @e2
+
+# Por CSS selector
+agent-browser click "#submit-btn"
+agent-browser click ".card:first-child"
+
+# Por semántica (más robusto que CSS en apps dinámicas)
+agent-browser find role button click --name "Guardar"
+agent-browser find label "Email" fill "test@test.com"
+agent-browser find text "Aceptar todo" click
+```
+
+---
+
+## Captura de screenshots
+
+```bash
+agent-browser screenshot                          # PNG a /tmp, auto-named
+agent-browser screenshot ./shots/page.png         # path específico
+agent-browser screenshot --full                   # full page scroll
+agent-browser screenshot --annotate               # overlay con refs numerados
+agent-browser pdf report.pdf                      # PDF de la página actual
+```
+
+Con `--annotate`, los labels `[N]` corresponden a `@eN` — útil para debuggear
+qué elemento es qué en páginas densas.
+
+---
+
+## Opciones útiles para testing local
+
+```bash
+# Ignorar HTTPS self-signed (localhost con cert local)
+agent-browser --ignore-https-errors open https://localhost:3000
+
+# Dark/Light mode
+agent-browser set media dark
+agent-browser screenshot dark-mode.png
+
+# Viewport custom
+agent-browser set viewport 1440 900
+agent-browser set viewport 375 812    # iPhone SE
+```
+
+---
+
+## Diagnóstico si algo falla
+
+```bash
+agent-browser doctor --quick         # verifica instalación de Chrome y daemon
+agent-browser console                # ver errores de JS en la página
+agent-browser errors                 # uncaught exceptions
+agent-browser --headed open <url>    # abrir visible para debuggear manualmente
+```
+
+Si el binario no está en PATH:
+- Buscar con: `which agent-browser` o `npm root -g`
+- Invocar con ruta completa mientras se resuelve el PATH
+
+---
+
+## Relación con otros skills
+
+- `security-audit`: usar browser-test para verificar visualmente que no hay info sensible expuesta en la UI.
+- `new-feature`: al terminar una feature con UI, correr browser-test para capturar screenshot de evidencia.
+- No depende de otros skills (es standalone).

package/assets/core/skills/db-migrate/SKILL.md

@@ -0,0 +1,163 @@
+# Skill: db-migrate
+
+Flujo seguro para ejecutar migraciones de base de datos. Compatible con Prisma, Drizzle,
+ActiveRecord (Rails), Alembic (Python) y Goose (Go).
+
+Triggers: /db-migrate, "migrar schema", "actualizar base de datos", "migrar BD",
+"cambios en schema", "nueva migración".
+
+---
+
+## Cuándo usar este skill
+
+- Al modificar el schema de la base de datos
+- Antes y después de agregar modelos, columnas o índices
+- Al resolver conflictos de migración entre branches
+
+---
+
+## Paso 1 — Determinar ambiente y ORM
+
+El ORM está en `project.yaml` bajo `stack.database`. El ambiente determina el flujo:
+
+| Ambiente | Objetivo |
+|----------|---------|
+| **Desarrollo local** | Iteración rápida, puede reiniciarse |
+| **Staging** | Igual que producción, con datos de prueba |
+| **Producción** | Sin pérdida de datos, con backup previo |
+
+---
+
+## Paso 2 — Validar antes de migrar (siempre)
+
+### Prisma
+```bash
+npx prisma validate          # verifica que el schema compila
+npx tsc --noEmit             # verifica que los tipos siguen siendo válidos
+```
+
+### Drizzle
+```bash
+npx drizzle-kit check        # detecta drift entre schema y BD
+npx tsc --noEmit
+```
+
+### ActiveRecord (Rails)
+```bash
+rails db:migrate:status      # ver migraciones pendientes
+```
+
+### Alembic (Python)
+```bash
+alembic check                # compara heads con BD actual
+```
+
+### Goose (Go)
+```bash
+goose status                 # ver migraciones pendientes
+```
+
+---
+
+## Paso 3 — Ejecutar migración
+
+### Desarrollo
+
+**Prisma**
+```bash
+npx prisma migrate dev --name <descripcion-snake-case>
+# o para sync rápido sin historial:
+npx prisma db push
+```
+
+**Drizzle**
+```bash
+npx drizzle-kit push         # sync directo
+# o con historial:
+npx drizzle-kit generate && npx drizzle-kit migrate
+```
+
+**Rails**
+```bash
+rails db:migrate
+```
+
+**Alembic**
+```bash
+alembic revision --autogenerate -m "descripcion"
+alembic upgrade head
+```
+
+**Goose**
+```bash
+goose create descripcion sql
+goose up
+```
+
+---
+
+### Producción — pasos adicionales obligatorios
+
+1. **Backup ANTES de migrar**
+   ```bash
+   # PostgreSQL genérico:
+   pg_dump $DATABASE_URL > backup_$(date +%Y%m%d_%H%M%S).sql
+
+   # O usar el script del proyecto si existe (db:backup:prod)
+   ```
+
+2. **Verificar que la migración no es destructiva**
+   ```bash
+   # Leer el archivo SQL generado antes de aplicar
+   # Señales de peligro: DROP COLUMN, DROP TABLE, TRUNCATE, NOT NULL sin default
+   ```
+
+3. **Aplicar en producción**
+
+   **Prisma**: `npx prisma migrate deploy` (nunca `db push` en prod)
+
+   **Drizzle**: `npx drizzle-kit migrate` (el proyecto debe tener un script dedicado)
+
+   **Rails**: `RAILS_ENV=production rails db:migrate`
+
+   **Alembic**: `alembic upgrade head` (con DATABASE_URL de producción)
+
+   **Goose**: `goose -env production up`
+
+---
+
+## Paso 4 — Post-migración (siempre)
+
+1. **Regenerar cliente/tipos** (si aplica)
+   ```bash
+   npx prisma generate          # Prisma
+   npx drizzle-kit generate     # Drizzle (si usa tipos generados)
+   ```
+
+2. **Verificar que el build sigue pasando**
+   ```bash
+   # TypeScript: pnpm build / npm run build
+   # Python: mypy . / pytest
+   # Go: go build ./...
+   ```
+
+3. **Actualizar documentación** — si el proyecto tiene knowledge base (Obsidian, wiki), actualizar la sección de base de datos.
+
+---
+
+## Señales de alerta — STOP y consultar
+
+```
+✗ La migración contiene DROP COLUMN o DROP TABLE en producción sin backup confirmado
+✗ El ORM reporta "drift" entre schema y BD — investigar causa antes de continuar
+✗ npx prisma migrate reset o rails db:schema:load en producción → borra todo
+✗ --force-reset / --force en cualquier contexto productivo
+```
+
+---
+
+## Relación con otros skills
+
+- `new-feature` lo invoca cuando la feature requiere cambios de schema.
+- No depende de otros skills (es standalone).
+- Si el proyecto usa Obsidian, actualizar vault después de migrar en producción.

package/assets/core/skills/local2prod/SKILL.md

@@ -0,0 +1,147 @@
+# Skill: local2prod
+
+Flujo completo de publicación a producción. Compatible con Vercel, Railway, Fly.io,
+GitHub Actions y pipelines custom.
+
+NUNCA dar una tarea por terminada sin que el deploy esté en estado READY/SUCCESS.
+
+Triggers: /local2prod, "publicar", "deploy", "subir a producción", "push a prod",
+"lanzar cambios", "ir a producción".
+
+---
+
+## Cuándo usar este skill
+
+Al terminar una feature y querer desplegarla a producción.
+El provider de deploy está en `project.yaml` bajo `deploy.provider`.
+
+---
+
+## Paso 1 — Commit
+
+Si hay cambios sin commitear:
+
+```bash
+git add <archivos relevantes>   # preferir archivos específicos, no git add -A
+git status                      # confirmar qué va al commit
+
+git commit -m "tipo(scope): descripción en imperativo
+
+Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>"
+```
+
+Si ya hay un commit listo, ir directo al Paso 2.
+
+---
+
+## Paso 2 — Push
+
+```bash
+git push origin <branch>
+```
+
+En proyectos con trunk-based development, el push a `main` trigerea el deploy automáticamente.
+En proyectos con PRs, el deploy se crea al mergear.
+
+---
+
+## Paso 3 — Esperar deploy READY
+
+**Regla de polling — OBLIGATORIA**:
+1. Hacer UNA verificación, leer el resultado, reportar el estado.
+2. Si sigue en Building/Running: decirle al usuario el estado actual y esperar **~60 segundos** antes de la siguiente verificación.
+3. **NUNCA** encadenar verificaciones automáticamente sin pausa.
+4. Máximo 1 verificación por minuto.
+
+### Por provider
+
+**Vercel** (leer provider config de project.yaml o env vars):
+```bash
+vercel ls --scope <teamId> 2>&1 | head -8
+# Columna Status: ● Building → esperar | ● Ready → OK | ✗ Error → ver logs
+```
+
+**Railway**:
+```bash
+railway status
+# o: railway run --service <name> -- echo OK
+```
+
+**Fly.io**:
+```bash
+fly status --app <app-name>
+# Buscar: Machines running
+```
+
+**GitHub Actions**:
+```bash
+gh run list --limit 3
+gh run watch <run-id>    # bloquea hasta que termine
+```
+
+**Custom / otro**:
+```bash
+# Usar el comando definido en project.yaml bajo deploy.check_command
+```
+
+### Si hay ERROR
+
+```bash
+# Vercel:
+vercel inspect <deployment-url> --logs 2>&1 | tail -40
+
+# GitHub Actions:
+gh run view <run-id> --log-failed
+
+# Railway / Fly:
+# Ver logs en el dashboard del provider
+```
+
+1. Identificar el error (build, typecheck, runtime)
+2. Corregir el código
+3. Volver al Paso 1
+
+---
+
+## Paso 4 — Verificar runtime logs
+
+Una vez que el deploy está READY, verificar que no haya errores de runtime (500, crashes, errores de DB):
+
+```bash
+# Vercel:
+vercel logs <deployment-url> 2>&1 | tail -20
+
+# Fly:
+fly logs --app <app-name>
+
+# Railway:
+railway logs
+```
+
+Si hay errores → corregir y repetir desde Paso 1.
+
+---
+
+## Paso 5 — Actualizar documentación [OPCIONAL]
+
+Si el proyecto tiene un knowledge base configurado (Obsidian, wiki, Notion):
+
+- Si hubo cambios de infra (nuevas env vars, cambios de schema, nuevas rutas) → actualizar la sección de deploy/infra.
+- Si el proyecto usa `obsidian-sync` → invocar ese skill ahora.
+
+---
+
+## Reglas críticas
+
+- **NUNCA** declarar la tarea terminada sin `state: READY / SUCCESS` confirmado.
+- **NUNCA** asumir que el push implica deploy exitoso — siempre verificar.
+- Si el deploy falla 3 veces seguidas → notificar al usuario y detener. No seguir en loop automático.
+- Si el pipeline queda en QUEUED por más de 2 minutos → investigar si hay otro deploy bloqueando.
+
+---
+
+## Relación con otros skills
+
+- `new-feature` lo invoca como último paso del flujo de implementación.
+- `obsidian-sync` puede ser invocado en el Paso 5 si está configurado (opcional).
+- No tiene dependencias obligatorias — puede usarse standalone.

package/assets/core/skills/new-feature/SKILL.md

@@ -0,0 +1,155 @@
+# Skill: new-feature
+
+Checklist completo para implementar una nueva feature desde planificación hasta deploy.
+Orquesta los otros skills del proyecto en el orden correcto.
+
+Triggers: /new-feature, "nueva feature", "quiero agregar", "implementar", 
+"agregar funcionalidad", "nueva sección", "empezar feature".
+
+---
+
+## Cuándo usar este skill
+
+Al comenzar a implementar cualquier feature nueva, por pequeña que sea.
+Asegura que no se saltee la spec, la seguridad ni el deploy.
+
+---
+
+## Fase 1 — Verificar que existe la spec
+
+```
+¿Existe docs/specs/<ID>-<nombre>.md con estado APPROVED?
+  → Sí: continuar
+  → No: STOP — usar el skill /spec para crear la spec primero
+```
+
+Leer la spec antes de escribir una sola línea de código.
+Identificar qué módulos toca: BD, API, UI, infra, auth.
+
+---
+
+## Fase 2 — Leer documentación existente del área
+
+Si el proyecto tiene un knowledge base (Obsidian, wiki, docs/):
+
+| Si la feature toca... | Leer primero... |
+|-----------------------|-----------------|
+| API / endpoints | docs de API del proyecto |
+| Schema de BD | docs de BD / migraciones previas |
+| UI / componentes | design system del proyecto |
+| Auth / sesiones | docs de auth del proyecto |
+| Deploy / infra | docs de infra / variables de entorno |
+
+Si el proyecto usa `obsidian-sync`: leer las notas del vault antes de implementar.
+
+---
+
+## Fase 3 — Evaluar si crear agent team
+
+**Crear team de agentes cuando**:
+- La feature toca más de 3 archivos en capas distintas (BD + API + UI)
+- El trabajo es paralelizable (backend y frontend pueden ir en paralelo)
+- La feature tiene criterios de compliance que requieren review independiente
+
+**NO crear team cuando**:
+- Es un cambio en 1-2 archivos
+- Es un bug fix puntual
+- Es una consulta o lectura de código
+
+Si se crea team → usar el skill `phase-kickoff` para coordinar el spawn de agentes.
+
+---
+
+## Fase 4 — Checklist de seguridad antes de implementar API routes
+
+Invocar el skill `/security-audit` como checklist mental antes de escribir cualquier endpoint:
+
+- [ ] ¿El endpoint verifica autenticación?
+- [ ] ¿El endpoint verifica autorización por rol?
+- [ ] ¿Si accede por ID, verifica ownership del recurso?
+- [ ] ¿El input del body está validado con un schema explícito?
+- [ ] ¿Las queries usan parámetros preparados (no interpolación)?
+
+---
+
+## Fase 5 — Orden de implementación recomendado
+
+```
+1. Schema de BD (si hay modelos nuevos)
+   → Invocar skill /db-migrate para el flujo seguro
+
+2. Types / interfaces compartidos
+   → Definir antes del backend para que el frontend pueda consumirlos
+
+3. Backend — API / servicios
+   → Tests junto con el código, no al final
+
+4. Frontend — UI / componentes
+   → Consume los tipos ya definidos
+
+5. Build check
+   → Verificar que no hay errores de compilación antes de commitear
+```
+
+---
+
+## Fase 6 — Post-implementación (no saltear)
+
+1. **Actualizar la spec** con decisiones tomadas durante la implementación
+   (agregar en sección "Notas de implementación" del archivo de spec)
+
+2. **Verificación visual** [si la feature tiene UI]
+   - Si el proyecto tiene `browser-test` activo → invocar `/browser-test` para tomar screenshot de evidencia
+   - Verificar estados: loading, error, vacío, con datos
+
+3. **Actualizar documentación del proyecto** [si aplica]
+   - Si el proyecto usa `obsidian-sync` → invocar ese skill ahora
+   - Si hay wiki o docs/ → actualizar la sección correspondiente
+
+4. **Deploy** → invocar skill `/local2prod`
+   - Esperar estado READY/SUCCESS antes de declarar la feature terminada
+
+5. **Marcar spec como IMPLEMENTED**
+   ```bash
+   # En docs/specs/<ID>-<nombre>.md, cambiar:
+   # > Estado: APPROVED
+   # por:
+   # > Estado: IMPLEMENTED
+   ```
+
+5. **Actualizar CLAUDE.md** — mover el ID de spec de "En curso" a "Completadas"
+
+---
+
+## Checklist final
+
+- [ ] Spec leída y estado APPROVED verificado
+- [ ] Documentación del área leída antes de implementar
+- [ ] Checklist de seguridad aplicado a endpoints nuevos
+- [ ] DB migrada correctamente (dev y prod si aplica)
+- [ ] Build pasando sin errores
+- [ ] Screenshot de evidencia tomado (si hay UI y `browser-test` activo)
+- [ ] Spec actualizada con decisiones de implementación
+- [ ] Documentación del proyecto actualizada
+- [ ] Deploy exitoso (estado READY confirmado)
+- [ ] Spec marcada como IMPLEMENTED
+
+---
+
+## Relación con otros skills
+
+Este skill orquesta los siguientes — no los reemplaza, los invoca en orden:
+
+```
+new-feature
+├── spec (Fase 1 — verificar/crear spec)
+├── phase-kickoff (Fase 3 — si se crea team de agentes)
+├── security-audit (Fase 4 — checklist de seguridad)
+├── db-migrate (Fase 5 — si hay cambios de schema)
+├── browser-test (Fase 6 — [OPCIONAL] screenshot de evidencia si hay UI)
+├── obsidian-sync (Fase 6 — [OPCIONAL] si el proyecto lo tiene configurado)
+└── local2prod (Fase 6 — deploy a producción)
+```
+
+Dependencias opcionales: `browser-test` solo se invoca si está en `project.yaml` bajo `skills.active`.
+`obsidian-sync` solo se invoca si está en `project.yaml` bajo `skills.integrations`.