@damenor/agent-docs 0.1.2 → 0.4.0

package/templates/modules/guides/docs/guides/runbooks/TEMPLATE.md

@@ -1,86 +0,0 @@
----
-created: "2026-05-07"
-updated: "2026-05-07"
-status: active
-type: how-to
-tags: [ops, runbooks, template]
----
-
-# Template de Runbook
-
-> [!info] Cuándo crear un runbook
-> Crea un runbook cuando un proceso operativo se repite o cuando necesitas documentar pasos para resolver un incidente específico. Guárdalo en `docs/guides/runbooks/`.
-
-## Nombre del Runbook
-
-**Tipo**: [operativo | incidente | mantenimiento]
-**Severidad**: [baja | media | alta | crítica]
-**Frecuencia**: [diario | semanal | mensual | bajo demanda]
-
-## Contexto
-
-¿Qué es este proceso? ¿Por qué existe? ¿Cuándo se ejecuta?
-
-## Síntomas / Triggers
-
-¿Qué indica que hay que ejecutar este runbook?
-
-- Síntoma 1
-- Síntoma 2
-- Alerta de monitoring que lo dispara
-
-## Prerrequisitos
-
-- [ ] Acceso a [sistema/servidor]
-- [ ] Permisos de [rol]
-- [ ] Herramientas: [lista]
-
-## Pasos
-
-### Paso 1: [Título del paso]
-
-**Acción**: Descripción clara de qué hacer
-**Comando** (si aplica):
-```bash
-comando-aquí
-```
-**Verificación**: Cómo confirmar que el paso salió bien
-
-### Paso 2: [Título del paso]
-
-**Acción**: Descripción clara
-**Comando**:
-```bash
-siguiente-comando
-```
-**Verificación**: Qué esperar
-
-### Paso N: Verificación final
-
-Confirmar que el proceso se completó exitosamente:
-
-- [ ] Check 1
-- [ ] Check 2
-
-## Rollback
-
-Si algo sale mal, cómo revertir:
-
-1. Paso de rollback 1
-2. Paso de rollback 2
-
-## Escalación
-
-Si no puedes resolver:
-
-| Nivel   | Contacto             | Cuándo escalar                    |
-|---------|----------------------|------------------------------------|
-| L1      | [Equipo/dev]         | Si los pasos del runbook fallan    |
-| L2      | [Tech lead]          | Si el problema requiere acceso especial |
-| L3      | [CTO/Infra lead]     | Si hay riesgo de pérdida de datos  |
-
-## Notas
-
-- Cualquier consideración especial
-- Lecciones aprendidas de ejecuciones anteriores
-- Enlaces a ADRs o docs relacionados

package/templates/modules/guides/docs/guides/troubleshooting.md

@@ -1,65 +0,0 @@
----
-created: "2026-05-07"
-updated: "2026-05-07"
-status: active
-type: how-to
-tags: [ops, troubleshooting, debugging]
----
-
-# Troubleshooting
-
-Problemas comunes encontrados durante el desarrollo y sus soluciones.
-
-> [!tip] Cómo usar esta guía
-> Busca tu problema en la tabla o por las secciones. Si encuentras un problema nuevo y lo resuelves, añádelo aquí para que el próximo developer no pierda tiempo.
-
-## Problemas de Entorno
-
-| Problema | Causa probable | Solución |
-|----------|---------------|----------|
-| `npm install` falla con EACCES | Permisos de npm global | Usa `nvm` o reinstala Node con permisos correctos |
-| `command not found: node` | Node no instalado o no en PATH | Instala con `nvm install --lts` y reinicia terminal |
-| Puerto 3000 ocupado | Otro proceso usando el puerto | `lsof -i :3000` (macOS) o `netstat -ano | findstr :3000` (Windows) y mata el proceso |
-| Variables de entorno no cargadas | Falta archivo `.env` | Copia `.env.example` a `.env` y configura los valores |
-
-## Problemas de Build
-
-| Problema | Causa probable | Solución |
-|----------|---------------|----------|
-| Error de tipos TypeScript | Tipos incompatibles o faltantes | Ejecuta `[npm run typecheck]` para ver errores específicos |
-| Build falla en CI pero no local | Diferencia de entorno (Node version, deps) | Verifica que `.nvmrc` o `engines` en package.json coincida con CI |
-| Error "Module not found" | Dependencia no instalada o path incorrecto | `rm -rf node_modules && npm install` o verifica import paths |
-| Out of memory en build | Proyecto grande sin suficiente RAM | Aumenta memoria: `NODE_OPTIONS="--max-old-space-size=4096" npm run build` |
-
-## Problemas de Runtime
-
-| Problema | Causa probable | Solución |
-|----------|---------------|----------|
-| CORS error en API calls | Backend no configurado para el origen del frontend | Verifica configuración CORS en el backend |
-| 401 Unauthorized | Token expirado o no enviado | Verifica que el token se envía en headers y no ha expirado |
-| Pantalla blanca en producción | Error JS no capturado, assets no cargan | Revisa consola del navegador, verifica que los assets se deployaron |
-| Hydration mismatch (SSR) | HTML server != HTML client | Verifica que no haya `Date.now()`, `Math.random()` o APIs del navegador en SSR |
-
-## Problemas de Base de Datos
-
-| Problema | Causa probable | Solución |
-|----------|---------------|----------|
-| Connection refused | BD no arrancada o URL incorrecta | Verifica que el servicio esté corriendo y la URL en `.env` sea correcta |
-| Migration error | Migración pendiente o conflicto | Ejecuta migraciones pendientes o resetea la BD local |
-| Timeout en queries | Query ineficiente o locks | Revisa el query plan, añade índices si es necesario |
-
-## Problemas de Git
-
-| Problema | Causa probable | Solución |
-|----------|---------------|----------|
-| Merge conflict | Cambios en mismas líneas | Resuelve manualmente: busca `<<<<<<<`, elige el correcto, elimina marcadores |
-| `git push` rechazado | Branch remota tiene commits nuevos | `git pull --rebase origin <branch>` y resuelve conflictos si hay |
-| Hook pre-commit falla | Linting o formatting falla | Ejecuta `npm run lint:fix` y vuelve a commitear |
-
-## Cómo añadir nuevos problemas
-
-Cuando resuelvas un problema que no esté aquí:
-
-1. Añade una fila a la tabla correspondiente
-2. Incluye: problema, causa, solución
-3. Si la solución es compleja, crea un how-to separado en `docs/guides/` y enlázalo aquí

package/templates/modules/operations/docs/operations/README.md

@@ -1,115 +0,0 @@
----
-created: "2026-05-07"
-updated: "2026-05-07"
-status: active
-type: how-to
-tags: [ops, operations, monitoring, incidents, production]
----
-
-# Operaciones
-
-Centro de operaciones para el proyecto en producción.
-
-> [!warning] Solo para entornos con producción
-> Esta sección se crea cuando el proyecto tiene entorno de producción. Si el proyecto aún no está en producción, puedes ignorar esta sección.
-
-## Monitorización
-
-### Dashboards
-
-| Dashboard | URL | Qué monitoriza |
-|-----------|-----|----------------|
-| Principal | [URL] | Health checks, uptime, errores |
-| Rendimiento | [URL] | Latencia, throughput, recursos |
-| Business | [URL] | Métricas de negocio |
-
-### Alertas Configuradas
-
-| Alerta | Severidad | Umbral | Canal de notificación |
-|--------|-----------|--------|-----------------------|
-| Servicio caído | Crítica | Health check fail > 2 min | [Slack/Email/PagerDuty] |
-| Error rate alto | Alta | >5% de requests con error 5xx | [Slack/Email] |
-| Latencia alta | Media | p95 > 2 segundos | [Slack] |
-| Disco lleno | Alta | >90% uso de disco | [Slack/Email] |
-| Certificado SSL por expirar | Media | <30 días | [Email] |
-
-## SLAs y SLOs
-
-| Métrica | SLO | Ventana | Medición |
-|---------|-----|---------|----------|
-| Disponibilidad | 99.9% | 30 días | Uptime checks |
-| Latencia p95 | <500ms | 30 días | APM |
-| Latencia p99 | <2s | 30 días | APM |
-| Error rate | <0.1% | 7 días | Log aggregation |
-| Tiempo de respuesta API | <200ms | 30 días | Synthetic monitoring |
-
-## Gestión de Incidentes
-
-### Niveles de Severidad
-
-| Nivel | Definición | Ejemplo | Tiempo de respuesta |
-|-------|------------|---------|-------------------|
-| P0 - Crítico | Servicio completamente caído, afecta a todos los usuarios | Sitio no carga, BD inaccesible | <15 min |
-| P1 - Alto | Funcionalidad principal no funciona, afecta muchos usuarios | Login roto, checkout falla | <1 hora |
-| P2 - Medio | Funcionalidad secundaria afectada, workaround disponible | Búsqueda lenta, email no envía | <4 horas |
-| P3 - Bajo | Problema cosmético o menor | Typo, UI glitch | Próximo sprint |
-
-### Proceso de Incidente
-
-1. **Detección**: Alerta automática o reporte de usuario
-2. **Triage**: Asignar severidad y responsable
-3. **Comunicación**: Notificar al equipo en canal de incidencias
-4. **Resolución**: Diagnosticar, aplicar fix, verificar
-5. **Post-mortem**: Documentar qué pasó, por qué, y cómo prevenirlo
-
-### Plantilla de Post-mortem
-
-Guardar en `docs/operations/post-mortems/YYYY-MM-DD-titulo.md`:
-
-```markdown
-## Resumen
-[1-2 oraciones: qué pasó, impacto, duración]
-
-## Timeline
-- HH:MM - Detección
-- HH:MM - Investigación empieza
-- HH:MM - Causa raíz identificada
-- HH:MM - Fix aplicado
-- HH:MM - Servicio restaurado
-
-## Causa Raíz
-[Qué causó el incidente, no qué síntomas se vieron]
-
-## Impacto
-- Duración: X horas/minutos
-- Usuarios afectados: X
-- Datos perdidos: Sí/No
-
-## Acciones Preventivas
-- [ ] Acción 1 — Responsable — Fecha límite
-- [ ] Acción 2 — Responsable — Fecha límite
-
-## Lecciones Aprendidas
-[Qué aprendimos que cambie cómo trabajamos]
-```
-
-## Backups
-
-| Recurso | Frecuencia | Retención | Ubicación |
-|---------|-----------|-----------|-----------|
-| Base de datos | Diaria | 30 días | [Proveedor/Ubicación] |
-| Assets estáticos | En cada deploy | Últimos 10 deploys | [CDN/Storage] |
-| Configuración | Versionada en git | Completa | Repositorio |
-
-## On-Call
-
-Si el proyecto tiene rotación de on-call:
-
-| Día | Responsable | Horario | Contacto |
-|-----|-------------|---------|----------|
-| Lunes | [Nombre] | 9:00 - 18:00 | [Canal contacto] |
-| ... | ... | ... | ... |
-
-## Runbooks Relacionados
-
-Los runbooks operativos están en `docs/guides/runbooks/`. Cada uno documenta un procedimiento específico para resolver problemas o realizar tareas operativas.

package/templates/modules/product/docs/product/overview.md

@@ -1,90 +0,0 @@
----
-created: "2025-01-01"
-status: active
-type: product-context
-tags: [producto, visión, negocio, stakeholders, métricas]
----
-
-# Visión del Producto
-
-## Qué es
-
-{{PROJECT_NAME}} es [descripción de una oración: qué tipo de producto es y para qué sirve]. Es un proyecto de tipo [web app / landing / portal / plataforma] orientado a [segmento: corporativo / B2B / B2C / interno].
-
-## Por qué existe
-
-**Problema que resuelve**: [Describir el problema o necesidad que motivó la creación del proyecto. ¿Qué hacía el cliente/equipo antes? ¿Qué fricción existía?]
-
-**Oportunidad**: [Por qué ahora. Qué cambió en el mercado, la organización o la tecnología que hace que este proyecto tenga sentido en este momento.]
-
-## Usuarios objetivo
-
-| Perfil | Quién es | Necesidad principal | Frecuencia de uso |
-|--------|----------|--------------------|--------------------|
-| **[Usuario primario]** | [Descripción: rol, contexto, nivel técnico] | [Qué viene a hacer al sistema. La tarea #1.] | [Diaria / Semanal / Mensual] |
-| **[Usuario secundario]** | [Descripción] | [Qué viene a hacer] | [Frecuencia] |
-| **[Usuario administrador]** | [Descripción] | [Gestionar configuración, usuarios, datos maestros] | [Frecuencia] |
-
-## Valor que aporta
-
-Para cada perfil de usuario:
-
-| Usuario | Antes (sin el proyecto) | Después (con el proyecto) | Medible en |
-|---------|------------------------|--------------------------|-----------|
-| **[Perfil 1]** | [Cómo resolvía el problema antes — manual, Excel, otro sistema] | [Cómo lo resuelve ahora — automatizado, centralizado, más rápido] | [Métrica: tiempo, errores, costos] |
-| **[Perfil 2]** | [Situación anterior] | [Situación nueva] | [Métrica] |
-
-## Stakeholders
-
-| Nombre / Rol | Responsabilidad en el proyecto | Decisiones que aprueba | Contacto |
-|-------------|-------------------------------|----------------------|----------|
-| **[Product Owner]** | Define prioridades y acepta entregas | Features, alcance, release dates | [email / slack] |
-| **[Tech Lead]** | Guía decisiones técnicas | Arquitectura, stack, deuda técnica | [email / slack] |
-| **[Diseñador/a]** | Define la experiencia visual y de interacción | UI/UX, design system, flujos | [email / slack] |
-| **[Stakeholder de negocio]** | Representa las necesidades del cliente final | Funcionalidad de negocio, priorización | [email / slack] |
-
-## Métricas de éxito
-
-### Métricas primarias (KPIs)
-
-| Métrica | Objetivo | Medición | Frecuencia |
-|---------|----------|----------|------------|
-| **[Métrica 1 — ej. Tasa de adopción]** | [Valor objetivo — ej. 80% de usuarios activos en 3 meses] | [Cómo se mide — ej. analytics de login] | [Mensual] |
-| **[Métrica 2 — ej. Tiempo de tarea]** | [Valor objetivo — ej. reducir de 30min a 5min] | [Cómo se mide] | [Semanal] |
-
-### Métricas de calidad
-
-| Métrica | Objetivo | Medición |
-|---------|----------|----------|
-| **Uptime** | 99.9% | Monitoreo de infraestructura |
-| **Tiempo de carga (LCP)** | < 2.5s | Lighthouse / Web Vitals |
-| **Errores en producción** | < 0.1% de requests | Error tracking (Sentry, etc.) |
-| **Cobertura de tests** | > 80% | CI/CD pipeline |
-
-### Métricas de satisfacción
-
-| Métrica | Objetivo | Medición |
-|---------|----------|----------|
-| **NPS / CSAT** | [Valor] | [Encuesta / feedback in-app] |
-| **Tickets de soporte** | Reducir X% vs. sistema anterior | Help desk |
-
----
-
-## Contexto regulatorio y restricciones
-
-- **Privacidad**: [Indicar si aplica GDPR, LFPDPPP, etc. Qué datos personales se manejan.]
-- **Accesibilidad**: Nivel WCAG 2.1 AA como mínimo.
-- **Seguridad**: [Normas de seguridad corporativas. Ej. OWASP Top 10, pen testing anual.]
-- **Compliance**: [Otras restricciones del sector — ej. PCI DSS para pagos, SOC 2 para SaaS.]
-
----
-
-## Evolución esperada
-
-Este producto está pensado para crecer en las siguientes direcciones:
-
-1. **Corto plazo (0-3 meses)**: [MVP o versión inicial con funcionalidad core.]
-2. **Mediano plazo (3-6 meses)**: [Features complementarias, integraciones.]
-3. **Largo plazo (6-12 meses)**: [Escalabilidad, nuevos módulos, expansión.]
-
-Ver el detalle de features planificados en [`docs/roadmap.md`](../roadmap.md).

package/templates/modules/product/docs/roadmap.md

@@ -1,80 +0,0 @@
----
-created: "2025-01-01"
-status: active
-type: planning
-tags: [roadmap, planificación, features, backlog]
----
-
-# Roadmap
-
-## Estado actual
-
-**Versión actual**: [versión — ej. 0.1.0]
-**Fase**: [Discovery / MVP / Growth / Maintenance]
-**Último release**: [fecha — ej. 2025-01-15]
-**Próximo release planificado**: [fecha o "Por definir"]
-
-Resumen del estado: [1-2 oraciones describiendo dónde está el proyecto ahora. Ej. "MVP funcional con autenticación y CRUD básico. Pendiente de integración con sistema de pagos."]
-
----
-
-## Próximos features
-
-| Feature | Descripción | Prioridad | Estado | Responsable | Target |
-|---------|-------------|-----------|--------|-------------|--------|
-| [Feature 1] | [Descripción breve de qué hace y por qué] | 🔴 Alta | [Estado: Planificado / En progreso / En QA / Listo] | [Nombre o rol] | [Fecha o sprint] |
-| [Feature 2] | [Descripción] | 🟡 Media | [Estado] | [Responsable] | [Target] |
-| [Feature 3] | [Descripción] | 🟢 Baja | [Estado] | [Responsable] | [Target] |
-
-### Detalle por feature
-
-#### [Feature 1]
-- **Por qué**: [Justificación de negocio o técnica.]
-- **Criterios de aceptación**:
-  - [ ] [Criterio 1]
-  - [ ] [Criterio 2]
-  - [ ] [Criterio 3]
-- **Dependencias**: [Otros features, equipos, servicios externos.]
-- **Riesgos**: [Qué podría salir mal. Mitigación.]
-
----
-
-## Backlog
-
-Ideas y features que se quieren hacer pero que no tienen fecha asignada aún.
-
-| Feature | Descripción | Fuente de la idea |
-|---------|-------------|------------------|
-| [Feature idea 1] | [Qué es y por qué sería valioso] | [Stakeholder / usuario / equipo] |
-| [Feature idea 2] | [Descripción] | [Fuente] |
-| [Feature idea 3] | [Descripción] | [Fuente] |
-
----
-
-## Decisiones pendientes
-
-| Decisión | Contexto | Opciones consideradas | Plazo para decidir | Responsable |
-|----------|----------|----------------------|-------------------|-------------|
-| [Decisión 1] | [Por qué hay que tomar esta decisión. Qué pasa si no se decide.] | [Opción A, Opción B] | [Fecha] | [Quién decide] |
-| [Decisión 2] | [Contexto] | [Opciones] | [Fecha] | [Responsable] |
-
----
-
-## Historial de releases
-
-| Versión | Fecha | Cambios principales | Notas |
-|---------|-------|-------------------|-------|
-| [0.1.0] | [2025-01-15] | Inicialización del proyecto, estructura base | Primer release |
-| [0.2.0] | [YYYY-MM-DD] | [Features principales del release] | [Notas adicionales] |
-
-Ver el detalle completo de cambios en [`CHANGELOG.md`](../../CHANGELOG.md).
-
----
-
-## Cómo actualizar este archivo
-
-- **Al planificar un sprint**: Actualizar la tabla de "Próximos features" con prioridades y responsables.
-- **Al iniciar un feature**: Cambiar estado a "En progreso".
-- **Al completar un feature**: Cambiar estado a "Listo", mover a "Historial de releases".
-- **Al recibir un request nuevo**: Añadir al Backlog si no es inmediato, o a "Próximos features" si sí.
-- **Al tomar una decisión técnica**: Mover de "Decisiones pendientes" y crear un ADR en `docs/adr/`.

package/templates/modules/reference/docs/reference/api.md

@@ -1,131 +0,0 @@
----
-created: "2026-05-07"
-updated: "2026-05-07"
-status: active
-type: reference
-tags: [api, reference, endpoints]
----
-
-# Referencia de API
-
-Documentación de referencia de los endpoints del proyecto.
-
-> [!tip] Convención
-> Si la API crece a más de 10 endpoints, convierte este archivo en una carpeta `api/` con un archivo por dominio.
-
-## Autenticación
-
-| Método | Descripción | Header |
-|--------|-------------|--------|
-| Bearer Token | JWT enviado en header | `Authorization: Bearer <token>` |
-
-**Flujo**:
-1. Cliente envía credenciales a `/auth/login`
-2. Server devuelve `{ token, refreshToken }`
-3. Cliente incluye `Authorization: Bearer <token>` en requests siguientes
-4. Si token expira, usar refresh token en `/auth/refresh`
-
-## Endpoints
-
-### [Recurso]
-
-#### `GET /api/[recurso]`
-
-Lista recursos con paginación.
-
-**Headers**:
-| Header | Requerido | Descripción |
-|--------|-----------|-------------|
-| `Authorization` | Sí | Bearer token |
-
-**Query Parameters**:
-| Param | Tipo | Default | Descripción |
-|-------|------|---------|-------------|
-| `page` | number | 1 | Página actual |
-| `limit` | number | 20 | Items por página (max 100) |
-| `sort` | string | `-createdAt` | Campo de orden (`-` para desc) |
-
-**Response 200**:
-```json
-{
-  "data": [
-    {
-      "id": "string",
-      "name": "string",
-      "createdAt": "ISO 8601"
-    }
-  ],
-  "meta": {
-    "page": 1,
-    "limit": 20,
-    "total": 100
-  }
-}
-```
-
-#### `POST /api/[recurso]`
-
-Crea un nuevo recurso.
-
-**Body**:
-```json
-{
-  "name": "string (required, max 200)",
-  "description": "string (optional)"
-}
-```
-
-**Response 201**:
-```json
-{
-  "id": "string",
-  "name": "string",
-  "description": "string",
-  "createdAt": "ISO 8601",
-  "updatedAt": "ISO 8601"
-}
-```
-
-## Códigos de Error
-
-| Status | Código | Descripción |
-|--------|--------|-------------|
-| 400 | `VALIDATION_ERROR` | Datos de entrada inválidos |
-| 401 | `UNAUTHORIZED` | Token ausente o inválido |
-| 403 | `FORBIDDEN` | Sin permisos para el recurso |
-| 404 | `NOT_FOUND` | Recurso no encontrado |
-| 409 | `CONFLICT` | Recurso ya existe |
-| 422 | `UNPROCESSABLE` | Entidad no procesable |
-| 429 | `RATE_LIMITED` | Demasiados requests |
-| 500 | `INTERNAL_ERROR` | Error interno del servidor |
-
-**Formato de error**:
-```json
-{
-  "error": {
-    "code": "VALIDATION_ERROR",
-    "message": "Descripción legible del error",
-    "details": [
-      { "field": "name", "message": "Name is required" }
-    ]
-  }
-}
-```
-
-## Rate Limiting
-
-| Tier | Requests/minuto | Burst |
-|------|-----------------|-------|
-| Standard | 60 | 10 |
-| Premium | 300 | 50 |
-
-Headers de respuesta:
-- `X-RateLimit-Limit`: Límite por ventana
-- `X-RateLimit-Remaining`: Requests restantes
-- `X-RateLimit-Reset`: Timestamp cuando se resetea
-
-## Versionado
-
-La API usa versionado en URL: `/api/v1/`, `/api/v2/`.
-
-Versiones anteriores se mantienen durante 6 meses después del release de una nueva versión mayor.