@damenor/agent-docs 0.1.0

package/templates/modules/agents/.agents/skills/doc-write/references/diataxis-patterns.md

@@ -0,0 +1,351 @@
+---
+created: "2024-01-15"
+status: active
+type: reference
+tags: [diataxis, patrones, documentacion, escritura]
+---
+
+# Diátaxis — Patrones Detallados por Tipo
+
+## Patrones de Tutorial
+
+### Estructura canónica
+
+```markdown
+# [Verbo + objeto del aprendizaje]
+
+## Qué vas a construir
+[Resultado tangible que el lector obtendrá]
+
+## Prerequisitos
+[Lista exacta: software, conocimientos, acceso]
+
+## Paso 1: [Acción concreta en infinitivo]
+[Instrucciones paso a paso]
+[Código completo y ejecutable]
+
+### ✅ Verificación
+[Comando o acción para confirmar que funciona]
+
+## Paso N: ...
+
+## Resumen
+[Qué se aprendió]
+[Próximos pasos sugeridos]
+```
+
+### Tono
+
+- **Didáctico y paciente**: No asumir conocimiento previo del tema
+- **Un concepto a la vez**: Cada paso introduce UNA cosa nueva
+- **Alentador**: Mostrar progreso visible y frecuentemente
+- **Concreto**: Usar ejemplos específicos, no abstractos
+
+### Longitud
+
+- **Ideal**: 500-1500 palabras
+- **Máximo**: 2000 palabras — si es más, dividir en tutoriales secuenciales
+- **Mínimo**: 300 palabras — si es menos, probablemente es un how-to
+
+### Cuándo escribir un tutorial
+
+- Un usuario nuevo necesita aprender una habilidad fundamental
+- Hay un flujo de onboarding que nadie ha documentado
+- Un concepto clave se enseña repetidamente a nuevas personas
+
+### Ejemplo concreto
+
+```markdown
+---
+created: "2024-03-10"
+status: active
+type: tutorial
+tags: [onboarding, api, express]
+---
+
+# Crear tu primer endpoint con Express
+
+## Qué vas a construir
+Un endpoint GET /api/health que responda con el estado del servidor.
+
+## Prerequisitos
+- Node.js 18+ instalado
+- Editor de código
+- Terminal
+
+## Paso 1: Inicializar el proyecto
+
+Crea una carpeta nueva e inicializa el proyecto:
+
+\`\`\`bash
+mkdir mi-api && cd mi-api
+npm init -y
+npm install express
+\`\`\`
+
+### ✅ Verificación
+Deberías ver `node_modules/` y `package.json` en la carpeta.
+
+## Paso 2: Crear el servidor
+
+Crea `index.js`:
+
+\`\`\`javascript
+const express = require('express');
+const app = express();
+
+app.get('/api/health', (req, res) => {
+  res.json({ status: 'ok', timestamp: new Date().toISOString() });
+});
+
+app.listen(3000, () => {
+  console.log('Servidor corriendo en http://localhost:3000');
+});
+\`\`\`
+
+### ✅ Verificación
+Ejecuta `node index.js` y abre `http://localhost:3000/api/health` en el navegador.
+Deberías ver `{"status":"ok","timestamp":"..."}`.
+
+## Resumen
+Aprendiste a crear un servidor Express con un endpoint GET.
+Próximo paso: [[tutorials/add-database]] para conectar una base de datos.
+```
+
+### Anti-patrones de tutorial
+
+| Anti-patrón | Por qué es malo | Qué hacer en su lugar |
+|-------------|----------------|----------------------|
+| Explicar teoría antes de practicar | Aburre al principiante | Explicar MIENTRAS se hace |
+| Saltarse pasos de verificación | El lector se pierde sin saberlo | Verificar después de CADA paso |
+| Asumir conocimiento previo | Frustra al principiante | Listar prerequisitos explícitos |
+| Código incompleto o seudo-código | No se puede ejecutar | Código SIEMPRE completo y ejecutable |
+| Cubrir múltiples temas | Satura al lector | Un tutorial = un tema |
+| Enlaces a docs externas para lo básico | Interrumpe el flujo | Incluir todo lo necesario inline |
+
+---
+
+## Patrones de How-to
+
+### Estructura canónica
+
+```markdown
+# Cómo [resolver problema específico]
+
+## Cuándo usar esto
+[1-3 líneas: escenario donde aplica esta guía]
+
+## Pasos
+1. [Acción directa]
+2. [Acción directa]
+...
+
+## Resultado esperado
+[Qué se obtiene al final]
+```
+
+### Tono
+
+- **Directo**: Al grano, sin preámbulos
+- **Asume conocimiento**: El lector ya conoce el sistema
+- **Práctico**: Pasos concretos, no explicaciones teóricas
+- **Sin justificación**: No explicar por qué — si el lector pregunta por qué, necesita una explicación, no un how-to
+
+### Cuándo dividir un how-to
+
+- Más de 10 pasos → dividir en how-tos más específicos
+- Cubre más de un problema → un how-to por problema
+- Tiene secciones de explicación → extraer la explicación a explanation/
+
+### Ejemplo concreto
+
+```markdown
+---
+created: "2024-03-10"
+status: active
+type: how-to
+tags: [auth, jwt, middleware]
+---
+
+# Cómo agregar autenticación JWT a una API existente
+
+## Cuándo usar esto
+Cuando tienes una API Express funcionando y necesitas proteger endpoints con JWT.
+
+## Pasos
+
+1. Instalar dependencias:
+
+\`\`\`bash
+npm install jsonwebtoken bcryptjs
+\`\`\`
+
+2. Crear middleware de auth en `src/middleware/auth.js`:
+
+\`\`\`javascript
+const jwt = require('jsonwebtoken');
+
+function authMiddleware(req, res, next) {
+  const token = req.headers.authorization?.split(' ')[1];
+  if (!token) return res.status(401).json({ error: 'Token requerido' });
+
+  try {
+    req.user = jwt.verify(token, process.env.JWT_SECRET);
+    next();
+  } catch {
+    res.status(401).json({ error: 'Token inválido' });
+  }
+}
+
+module.exports = authMiddleware;
+\`\`\`
+
+3. Proteger endpoints:
+
+\`\`\`javascript
+const auth = require('./middleware/auth');
+app.get('/api/profile', auth, (req, res) => { ... });
+\`\`\`
+
+## Resultado esperado
+Los endpoints protegidos requieren un JWT válido en el header `Authorization: Bearer <token>`.
+```
+
+### Anti-patrones de how-to
+
+| Anti-patrón | Por qué es malo | Qué hacer en su lugar |
+|-------------|----------------|----------------------|
+| Explicar conceptos básicos | El lector ya debería saberlo | Link a tutorial si necesita base |
+| Narrativa o storytelling | No es lo que busca el lector | Pasos directos y enumerados |
+| Múltiples soluciones alternativas | Confunde al lector | Una solución, la mejor práctica |
+| Prerequisitos extensos | Si necesita mucho setup, es un tutorial | Simplificar o link a tutorial |
+| "Opcionalmente puedes..." | Genera incertidumbre | Un camino claro |
+
+---
+
+## Patrones de Referencia
+
+### Estructura canónica
+
+```markdown
+# [Nombre del sistema/API/interfaz]
+
+## [Sección principal]
+
+| Parámetro | Tipo | Requerido | Descripción | Default |
+|-----------|------|-----------|-------------|---------|
+| ...       | ...  | ...       | ...         | ...     |
+
+## Códigos de respuesta
+
+| Código | Significado | Cuándo se retorna |
+|--------|------------|-------------------|
+| ...    | ...        | ...               |
+
+## Ejemplos
+[Un ejemplo mínimo por cada caso de uso principal]
+```
+
+### Tono
+
+- **Neutral y factual**: Sin opiniones, sin narrativa
+- **Estructurado**: Tablas > listas > prosa
+- **Completo**: Incluir TODOS los parámetros, TODOS los casos
+- **Sin explicaciones**: Si necesita explicarse, linkear a explanation/
+
+### Pistas para auto-generación
+
+Si el código tiene:
+- **OpenAPI/Swagger**: Generar referencia desde el spec
+- **TypeScript interfaces**: Extraer tipos y comentarios JSDoc
+- **JSON Schema**: Usar el schema como base
+- **CLI con `--help`**: Capturar la salida completa
+
+### Qué incluir siempre
+
+- Todos los parámetros/props/campos con tipo y descripción
+- Valores por defecto
+- Valores permitidos (enums)
+- Restricciones (min, max, formato)
+- Códigos de error
+- Ejemplos mínimos por cada caso principal
+
+### Anti-patrones de referencia
+
+| Anti-patrón | Por qué es malo | Qué hacer en su lugar |
+|-------------|----------------|----------------------|
+| Prosa narrativa | La referencia debe ser consultable | Tablas y listas |
+| Ejemplos sin contexto | No se sabe cuándo usar cada uno | Un ejemplo por caso de uso |
+| Parámetros parciales | El lector no puede confiar en la doc | Documentar TODO o indicar qué falta |
+| Explicar el porqué | No es el lugar | Link a explanation/ |
+| Obviar edge cases | Sorprende al lector | Documentar todos los casos |
+
+---
+
+## Patrones de Explicación
+
+### Estructura canónica
+
+```markdown
+# [Tema o pregunta que se responde]
+
+## Contexto
+[Por qué existe, qué problema aborda]
+
+## Cómo funciona
+[Vista general conceptual — sin código]
+
+## Alternativas consideradas
+[Qué otras opciones existían]
+
+## Implicaciones
+[Qué significa para el presente y futuro]
+```
+
+### Tono
+
+- **Discursivo y analítico**: Como una conversación con un colega experto
+- **Conectivo**: Relacionar con otros conceptos, ADRs, decisiones
+- **Histórico**: Contar la historia de por qué se llegó aquí
+- **Sin código** (o mínimo): El foco es el entendimiento, no la implementación
+
+### Cuándo es necesaria una explicación
+
+- Un ADR necesita más contexto del que cabe en 1-3 oraciones
+- Un concepto se referencia en múltiples how-tos/tutoriales y merece su propio espacio
+- Alguien preguntó "¿por qué hicimos esto así?" más de una vez
+- Hay confusión recurrente sobre un tema
+
+### Vinculación con ADRs
+
+```markdown
+Para la decisión formal, ver [[ADR-003-event-sourcing]].
+Este documento explica el contexto y las implicaciones en mayor detalle.
+```
+
+### Anti-patrones de explicación
+
+| Anti-patrón | Por qué es malo | Qué hacer en su lugar |
+|-------------|----------------|----------------------|
+| Instrucciones paso a paso | Eso es un tutorial o how-to | Enfocarse en el porqué |
+| Listar todas las opciones de config | Eso es referencia | Explicar la lógica detrás |
+| Sin contexto histórico | Pierde el valor de la explicación | Incluir cómo se llegó ahí |
+| Demasiado abstracto | No ayuda a entender | Usar analogías concretas |
+| Repetir el ADR palabra por palabra | No agrega valor | Expandir con contexto y matices |
+
+---
+
+## Anti-patrones Transversales
+
+### Anti-patrones que aplican a TODOS los tipos
+
+| Anti-patrón | Descripción | Solución |
+|-------------|-------------|----------|
+| **Documento camaleón** | Intenta ser dos tipos a la vez | Un doc = un tipo. Separar. |
+| **Contenido placeholder** | "TODO: agregar contenido" | Escribir contenido real o no crear |
+| **Sin frontmatter** | Archivo sin metadatos YAML | Siempre incluir frontmatter |
+| **Sin fecha** | No se sabe cuándo se creó | Siempre incluir `created` |
+| **Términos sin definir** | Jerga sin referencia a CONTEXT.md | Definir o linkear |
+| **Enlaces rotos** | Referencias a archivos que no existen | Verificar antes de publicar |
+| **Contenido duplicado** | Misma info en múltiples archivos | Referenciar, no duplicar |
+| **Sin verificación** | No hay forma de saber si está actualizado | Incluir `last-reviewed` en frontmatter |

package/templates/modules/ci/.github/workflows/docs-check.yml

@@ -0,0 +1,94 @@
+name: Docs Health Check
+
+on:
+  push:
+    paths:
+      - 'docs/**'
+      - 'AGENTS.md'
+      - 'README.md'
+      - 'CHANGELOG.md'
+  pull_request:
+    paths:
+      - 'docs/**'
+
+jobs:
+  docs-check:
+    runs-on: ubuntu-latest
+    name: Verificar documentación
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Verificar frontmatter YAML en todos los .md de docs/
+        run: |
+          echo "🔍 Verificando frontmatter YAML..."
+          errors=0
+          for file in $(find docs -name "*.md" -type f); do
+            if ! head -1 "$file" | grep -q "^---"; then
+              echo "❌ Sin frontmatter: $file"
+              errors=$((errors + 1))
+            fi
+          done
+          if [ $errors -gt 0 ]; then
+            echo "::error::$errors archivo(s) sin frontmatter YAML"
+            exit 1
+          fi
+          echo "✅ Todos los archivos tienen frontmatter"
+
+      - name: Verificar que no hay archivos vacíos en docs/
+        run: |
+          echo "🔍 Verificando archivos vacíos..."
+          errors=0
+          for file in $(find docs -name "*.md" -type f); do
+            # Un archivo con solo frontmatter tiene menos de 10 líneas útiles
+            content_lines=$(grep -v "^---$" "$file" | grep -v "^$" | wc -l)
+            if [ "$content_lines" -lt 3 ]; then
+              echo "⚠️ Archivo con poco contenido: $file ($content_lines líneas)"
+            fi
+          done
+          echo "✅ Verificación de archivos vacíos completada"
+
+      - name: Verificar links internos rotos
+        run: |
+          echo "🔍 Verificando links internos..."
+          errors=0
+          for file in $(find docs -name "*.md" -type f); do
+            # Extraer links relativos tipo [text](path.md)
+            links=$(grep -oP '\[.*?\]\(\K[^)]+' "$file" | grep -v "^http" | grep -v "^#" || true)
+            dir=$(dirname "$file")
+            for link in $links; do
+              # Resolver path relativo
+              target=$(realpath --relative-to=. "$dir/$link" 2>/dev/null || echo "")
+              if [ -n "$target" ] && [ ! -f "$target" ]; then
+                echo "❌ Link roto en $file → $link"
+                errors=$((errors + 1))
+              fi
+            done
+          done
+          if [ $errors -gt 0 ]; then
+            echo "::warning::$errors link(s) interno(s) rotos encontrados"
+          else
+            echo "✅ Todos los links internos son válidos"
+          fi
+
+      - name: Verificar CONTEXT.md tiene contenido
+        run: |
+          echo "🔍 Verificando CONTEXT.md..."
+          if [ -f "docs/CONTEXT.md" ]; then
+            completeness=$(grep -oP 'completeness:\s*"\K[0-9]+' docs/CONTEXT.md || echo "0")
+            if [ "$completeness" -lt 20 ]; then
+              echo "::warning::CONTEXT.md tiene completeness: ${completeness}%. Priorizar su actualización."
+            else
+              echo "✅ CONTEXT.md completeness: ${completeness}%"
+            fi
+          else
+            echo "::error::docs/CONTEXT.md no existe"
+            exit 1
+          fi
+
+      - name: Resumen
+        run: |
+          echo "📊 Resumen de documentación:"
+          echo "  Archivos .md en docs/: $(find docs -name '*.md' -type f | wc -l)"
+          echo "  ADRs: $(find docs/adr -name '*.md' -not -name 'TEMPLATE*' -type f 2>/dev/null | wc -l)"
+          echo "  Tutoriales: $(find docs/tutorials -name '*.md' -type f 2>/dev/null | wc -l)"
+          echo "  Guías: $(find docs/guides -name '*.md' -type f 2>/dev/null | wc -l)"

package/templates/modules/design/docs/DESIGN.md

@@ -0,0 +1,253 @@
+---
+created: "2025-01-01"
+status: active
+type: design-system
+tags: [diseño, ui, componentes, colores, tipografía, design-system]
+version: "1.0.0"
+name: "[Nombre del Design System]"
+description: "Sistema de diseño visual para {{PROJECT_NAME}}"
+---
+
+# Design System — {{PROJECT_NAME}}
+
+```yaml
+# ⚠️ VALORES DE EJEMPLO — NO SON LOS TOKENS DEL PROYECTO
+# Los valores abajo son ilustrativos (basados en paleta Tailwind).
+# Reemplazar con los tokens reales del proyecto.
+# Para extraer tokens automáticamente del código, usar la skill `doc-design`.
+
+colors:
+  primary:
+    50: "#eff6ff"    # Fondo claro
+    100: "#dbeafe"   # Hover sutil
+    500: "#3b82f6"   # Color principal
+    600: "#2563eb"   # Hover
+    700: "#1d4ed8"   # Activo / Pressed
+    900: "#1e3a5f"   # Texto sobre claro
+  secondary:
+    50: "#f8fafc"
+    500: "#64748b"
+    700: "#334155"
+    900: "#0f172a"
+  semantic:
+    success: "#22c55e"
+    warning: "#f59e0b"
+    error: "#ef4444"
+    info: "#3b82f6"
+  neutral:
+    white: "#ffffff"
+    gray-100: "#f1f5f9"
+    gray-300: "#cbd5e1"
+    gray-500: "#64748b"
+    gray-700: "#334155"
+    black: "#0f172a"
+  brand:
+    corporate: "#[COLOR_PRINCIPAL]"
+    accent: "#[COLOR_SECUNDARIO]"
+
+typography:
+  fontFamily:
+    base: "[Nombre de fuente], sans-serif"
+    heading: "[Nombre de fuente], sans-serif"
+    mono: "[Nombre de fuente monoespaciada], monospace"
+  fontSize:
+    xs: "0.75rem"     # 12px
+    sm: "0.875rem"    # 14px
+    base: "1rem"      # 16px
+    lg: "1.125rem"    # 18px
+    xl: "1.25rem"     # 20px
+    2xl: "1.5rem"     # 24px
+    3xl: "1.875rem"   # 30px
+    4xl: "2.25rem"    # 36px
+  fontWeight:
+    regular: "400"
+    medium: "500"
+    semibold: "600"
+    bold: "700"
+  lineHeight:
+    tight: "1.25"
+    base: "1.5"
+    relaxed: "1.75"
+
+rounded:
+  none: "0"
+  sm: "0.25rem"
+  md: "0.375rem"
+  lg: "0.5rem"
+  xl: "0.75rem"
+  full: "9999px"
+
+spacing:
+  unit: "0.25rem"     # Base: 4px
+  scale: [0, 1, 2, 3, 4, 5, 6, 8, 10, 12, 16, 20, 24]
+
+components:
+  button:
+    variants: [primary, secondary, ghost, danger]
+    sizes: [sm, md, lg]
+    borderRadius: "md"
+  input:
+    variants: [default, error, disabled]
+    borderRadius: "md"
+    height: "2.5rem"
+  card:
+    borderRadius: "lg"
+    shadow: "0 1px 3px rgba(0,0,0,0.1)"
+    padding: "1.5rem"
+  modal:
+    borderRadius: "xl"
+    maxWidth: "32rem"
+    overlay: "rgba(0,0,0,0.5)"
+  table:
+    headerBg: "gray-100"
+    rowHover: "gray-50"
+    borderColor: "gray-300"
+```
+
+---
+
+## Visión general
+
+Este documento es la fuente de verdad para las decisiones visuales del proyecto. Todo cambio de UI debe consultar este archivo primero. Si el cambio requiere un nuevo token o componente, actualizar este archivo antes de implementar.
+
+Los tokens de diseño viven aquí. Los componentes se implementan en código y **referencian** estos tokens.
+
+---
+
+## Colores
+
+### Paleta principal
+
+| Token | Valor | Uso |
+|-------|-------|-----|
+| `primary-500` | `#[valor]` | Botones principales, links activos, elementos de acción |
+| `primary-700` | `#[valor]` | Botones en estado hover/active |
+| `secondary-500` | `#[valor]` | Elementos secundarios, iconos, texto complementario |
+
+### Colores semánticos
+
+| Token | Valor | Cuándo usarlo |
+|-------|-------|---------------|
+| `success` | `#[valor]` | Operaciones exitosas, confirmaciones, estados positivos |
+| `warning` | `#[valor]` | Advertencias, datos que requieren atención sin ser error |
+| `error` | `#[valor]` | Errores, validaciones fallidas, operaciones fallidas |
+| `info` | `#[valor]` | Información contextual, tooltips, ayuda |
+
+### Reglas de contraste
+
+- Todo texto sobre fondos de color debe cumplir con **WCAG 2.1 nivel AA** (ratio mínimo 4.5:1 para texto normal, 3:1 para texto grande).
+- Verificar contraste con [WebAIM Contrast Checker](https://webaim.org/resources/contrastchecker/).
+- Nunca usar `gray-300` como color de texto sobre fondo blanco.
+
+---
+
+## Tipografía
+
+### Jerarquía
+
+| Elemento | Tamaño | Peso | Line-height | Uso |
+|----------|--------|------|-------------|-----|
+| H1 | `2.25rem` (36px) | Bold (700) | Tight (1.25) | Título de página. Una sola vez por página. |
+| H2 | `1.5rem` (24px) | Semibold (600) | Tight (1.25) | Título de sección. |
+| H3 | `1.25rem` (20px) | Semibold (600) | Base (1.5) | Título de subsección o card. |
+| H4 | `1.125rem` (18px) | Medium (500) | Base (1.5) | Títulos menores. |
+| Body | `1rem` (16px) | Regular (400) | Base (1.5) | Texto de párrafo. |
+| Small | `0.875rem` (14px) | Regular (400) | Base (1.5) | Texto secundario, labels, helpers. |
+| Caption | `0.75rem` (12px) | Regular (400) | Base (1.5) | Notas legales, timestamps, metadatos. |
+
+### Reglas
+
+- Máximo **3 niveles de headings** por página (H1 → H2 → H3).
+- No usar H1 más de una vez por vista.
+- Texto siempre en `base` (16px) como mínimo. No usar `xs` para texto funcional.
+
+---
+
+## Layout y espaciado
+
+### Grid
+
+- Grid base de **4px**. Todo espaciado debe ser múltiplo de 4.
+- Container máximo: `1280px` centrado.
+- Padding lateral del container: `1.5rem` en mobile, `2rem` en desktop.
+
+### Breakpoints
+
+| Nombre | Ancho | Dispositivo |
+|--------|-------|-------------|
+| `sm` | `640px` | Mobile horizontal |
+| `md` | `768px` | Tablet vertical |
+| `lg` | `1024px` | Tablet horizontal / laptop |
+| `xl` | `1280px` | Desktop |
+
+---
+
+## Elevación (Shadows)
+
+| Nivel | Sombra | Uso |
+|-------|--------|-----|
+| `none` | `none` | Elementos flat, backgrounds |
+| `sm` | `0 1px 2px rgba(0,0,0,0.05)` | Cards en reposo |
+| `md` | `0 4px 6px rgba(0,0,0,0.1)` | Cards con hover, dropdowns |
+| `lg` | `0 10px 15px rgba(0,0,0,0.1)` | Modales, popovers |
+| `xl` | `0 20px 25px rgba(0,0,0,0.15)` | Elementos flotantes destacados |
+
+---
+
+## Componentes
+
+### Botones
+
+| Variante | Fondo | Texto | Borde |
+|----------|-------|-------|-------|
+| **Primary** | `primary-500` | `white` | Ninguno |
+| **Secondary** | `white` | `gray-700` | `gray-300` |
+| **Ghost** | Transparente | `gray-700` | Ninguno |
+| **Danger** | `error` | `white` | Ninguno |
+
+| Tamaño | Height | Padding horizontal | Font size |
+|--------|--------|-------------------|-----------|
+| `sm` | `2rem` | `0.75rem` | `sm` |
+| `md` | `2.5rem` | `1rem` | `base` |
+| `lg` | `3rem` | `1.5rem` | `lg` |
+
+### Inputs
+
+- Altura: `2.5rem`
+- Border: `1px solid gray-300`
+- Border focus: `2px solid primary-500`
+- Border error: `2px solid error`
+- Placeholder: `gray-500`
+- Mensaje de error debajo del input en color `error`, tamaño `sm`.
+
+### Cards
+
+- Border radius: `lg`
+- Sombra: `sm` en reposo, `md` en hover
+- Padding interno: `1.5rem`
+- Separación entre cards: `1rem`
+
+---
+
+## Comportamiento responsive
+
+Principio: **Mobile first**. Se diseña para mobile y se escala hacia desktop.
+
+1. En mobile (< 768px): una sola columna, navegación colapsada, cards apiladas.
+2. En tablet (768px - 1024px): dos columnas donde aplique, sidebar colapsable.
+3. En desktop (> 1024px): layout completo con sidebar expandida.
+
+Regla: ningún elemento debe quedar fuera de viewport o requerir scroll horizontal en ningún breakpoint.
+
+---
+
+## Cómo actualizar este archivo
+
+Cuando se añada o cambie un elemento visual:
+
+1. Actualizar el token en el bloque YAML de arriba.
+2. Actualizar la tabla en la sección correspondiente.
+3. Verificar que los componentes que usan ese token sigan teniendo contraste adecuado.
+4. Si el cambio es significativo, crear un ADR explicando el motivo.
+
+Para gestión integral del design system, usar la skill `doc-design`.

package/templates/modules/explanation/docs/explanation/agent-flow.md

@@ -0,0 +1,15 @@
+---
+created: "2026-05-07"
+updated: "2026-05-07"
+status: deprecated
+type: redirect
+tags: [flujo, diagrama, agentes]
+---
+
+# ⚠️ Este archivo ha sido fusionado
+
+Todo el contenido de diagramas de flujo, estructura de agentes y flujos de decisión se ha consolidado en:
+
+→ **[`docs/internal/agent-guide.md`](../internal/agent-guide.md)**
+
+Este archivo se mantiene como redirect para no romper enlaces existentes.