@damenor/agent-docs 0.1.0

package/templates/modules/agents/.agents/skills/doc-scaffold/SKILL.md

@@ -0,0 +1,277 @@
+---
+name: doc-scaffold
+description: >
+  Inicializa la documentación completa para un proyecto nuevo o existente.
+  Detecta el stack tecnológico, crea la estructura de archivos esenciales y genera
+  documentación inicial con contenido real basado en el análisis del código.
+  TRIGGER: Cuando el usuario dice "inicializar docs", "nuevo proyecto", "scaffold docs",
+  "crear documentación", "setup docs", o se detecta un proyecto sin documentación.
+license: Apache-2.0
+metadata:
+  author: damenordev
+  version: "1.0"
+---
+
+# doc-scaffold
+
+## Cuándo Usar
+
+- **Proyecto nuevo**: Se crea un proyecto desde cero y necesita documentación inicial
+- **Proyecto existente sin docs**: Se detecta un proyecto que ya tiene código pero carece de documentación estructurada
+- **Migración de docs**: Se reorganiza documentación existente hacia la estructura Diátaxis + ADR
+- **Post-setup**: Después de inicializar un repositorio, antes de empezar a desarrollar features
+
+## Patrones Críticos
+
+### REGLA #1: NUNCA crear carpetas vacías
+
+Solo se crean archivos con contenido real y verificable. Si no hay contenido para un archivo, no se crea.
+
+```
+❌ MAL: mkdir docs/api/  # carpeta vacía
+✅ BIEN: Crear docs/api/endpoints.md SOLO cuando hay endpoints documentables
+```
+
+### REGLA #2: Detectar antes de crear
+
+Siempre analizar el proyecto ANTES de generar documentación:
+
+- Detectar lenguaje: `package.json` → Node, `requirements.txt` → Python, `go.mod` → Go, `Cargo.toml` → Rust, `pom.xml` → Java
+- Detectar framework: imports en código principal, dependencias
+- Verificar docs existentes: NO sobreescribir documentación existente sin preguntar
+- Identificar términos del dominio: buscar en código, nombres de módulos, variables clave
+
+### REGLA #3: Archivos esenciales únicamente
+
+Crear SOLO estos archivos con contenido real:
+
+| Archivo | Propósito | Cuándo crear |
+|---------|-----------|-------------|
+| `README.md` | Entry point del proyecto | Siempre |
+| `CHANGELOG.md` | Historial de versiones | Siempre (con entrada inicial) |
+| `AGENTS.md` | Protocolo para agentes IA | Siempre |
+| `docs/README.md` | Mapa de documentación + reglas de crecimiento | Siempre |
+| `docs/CONTEXT.md` | Términos del dominio encontrados en código | Siempre |
+| `docs/adr/TEMPLATE.md` | Plantilla para ADRs | Siempre |
+| `docs/adr/001-*.md` | Primer ADR si aplica | Si hay decisiones arquitectónicas |
+| `tutorials/quick-start.md` | Tutorial de inicio rápido | Siempre |
+
+### REGLA #4: CONTEXT.md se genera analizando el código
+
+No inventar términos. Extraer del código:
+
+1. Buscar nombres de módulos, clases, funciones principales
+2. Identificar abreviaturas y su significado
+3. Mapear relaciones entre componentes
+4. Detectar términos ambiguos y documentarlos
+
+### REGLA #5: Frontmatter YAML obligatorio
+
+Todo archivo de documentación debe incluir frontmatter:
+
+```yaml
+---
+created: "2024-01-15"
+status: active
+type: tutorial | how-to | reference | explanation
+tags: [tag1, tag2]
+---
+```
+
+### REGLA #6: Manifest de crecimiento en docs/README.md
+
+Incluir reglas explícitas de cuándo y cómo agregar nueva documentación.
+
+## Flujo del Proceso
+
+### Paso 1: Detectar stack
+
+Usar la tabla de detección automática de `AGENTS.md` § Stack. Además, analizar:
+
+```
+Analizar:
+├── Lenguaje principal (package.json, go.mod, requirements.txt, Cargo.toml, pom.xml)
+├── Framework (imports, dependencias, config files)
+├── Estructura de carpetas existente
+├── Herramientas de build/test (detectar comandos del ecosistema)
+└── Docs existentes (NO sobreescribir)
+```
+
+### Paso 2: Verificar documentación existente
+
+```
+Revisar:
+├── ¿Existe README.md? → NO sobreescribir, sugerir mejoras
+├── ¿Existe CHANGELOG.md? → NO sobreescribir
+├── ¿Existe docs/? → Integrar, no reemplazar
+├── ¿Existen ADRs? → Preservar numeración
+└── ¿Existe AGENTS.md? → Preservar, sugerir adiciones
+```
+
+### Paso 3: Crear AGENTS.md con protocolo
+
+```markdown
+# AGENTS.md — Protocolo de Documentación
+
+## Antes de empezar una tarea
+1. Leer docs/CONTEXT.md para entender el dominio
+2. Leer docs/README.md para ubicarse en la documentación
+3. Revisar ADRs relevantes en docs/adr/
+
+## Después de completar una tarea
+1. Actualizar CONTEXT.md si surgieron nuevos términos
+2. Actualizar docs/README.md si se agregaron/eliminaron archivos
+3. Evaluar si se necesita un ADR (¿es difícil de revertir? ¿es sorprendente? ¿hay trade-off?)
+4. Pasar el protocolo al subagente si se delega trabajo
+
+## Al delegar trabajo
+1. Incluir este protocolo en el prompt del subagente
+2. Especificar qué archivos de doc actualizar
+3. Verificar que el subagente cumplió el protocolo
+```
+
+### Paso 4: Crear docs/README.md
+
+Incluir:
+- Mapa completo de archivos de documentación (generado, no placeholder)
+- Reglas de crecimiento: cuándo agregar cada tipo de doc
+- Convenciones de nomenclatura
+- Enlaces a skills relacionados: `doc-write`, `doc-review`, `doc-maintain`
+
+### Paso 5: Crear docs/CONTEXT.md
+
+Generar con términos reales del dominio detectados en el código:
+- Tabla de términos con definiciones
+- Relaciones entre términos
+- Términos ambiguos señalados
+- Origen: análisis del código fuente
+
+### Paso 6: Crear docs/adr/TEMPLATE.md + primer ADR
+
+- TEMPLATE.md: plantilla reutilizable
+- Primer ADR: solo si ya existe una decisión arquitectónica que cumpla los 3 criterios (difícil de revertir, sorprendente, trade-off real)
+
+### Paso 7: Crear tutorials/quick-start.md
+
+Basado en el stack detectado:
+- Prerequisitos específicos del stack
+- Pasos de instalación reales
+- Primer ejemplo ejecutable
+- Verificación en cada paso
+
+### Paso 8: Crear archivos de referencia esenciales
+
+Solo los que apliquen al stack detectado:
+- Si hay API: `reference/api.md`
+- Si hay configuración: `reference/configuration.md`
+- Si hay CLI: `reference/cli.md`
+
+### Paso 9: Reportar resultado
+
+```
+✅ Creados:
+  - README.md (entry point)
+  - CHANGELOG.md (inicializado)
+  - AGENTS.md (protocolo)
+  - docs/README.md (mapa + reglas)
+  - docs/CONTEXT.md (X términos del dominio)
+  - docs/adr/TEMPLATE.md
+  - tutorials/quick-start.md (basado en {stack})
+
+⏭️ Pendientes (agregar cuando haya contenido):
+  - docs/adr/001-*.md (cuando haya una decisión arquitectónica)
+  - reference/api.md (cuando haya endpoints documentables)
+  - how-to/ (cuando surjan problemas repetibles)
+```
+
+## Comandos
+
+### Archivos a crear (en orden)
+
+```bash
+# Archivos raíz
+README.md
+CHANGELOG.md
+AGENTS.md
+
+# Estructura docs/
+docs/README.md
+docs/CONTEXT.md
+docs/adr/TEMPLATE.md
+
+# Tutoriales
+tutorials/quick-start.md
+
+# Referencia (solo si aplica)
+reference/api.md          # Solo si hay API
+reference/configuration.md # Solo si hay config
+```
+
+### Verificación post-creación
+
+```
+1. Verificar que TODO archivo tiene contenido real (no placeholders)
+2. Verificar que TODO archivo tiene frontmatter YAML
+3. Verificar que CONTEXT.md contiene términos reales del código
+4. Verificar que quick-start.md es ejecutable para el stack detectado
+5. Verificar que docs/README.md mapea todos los archivos creados
+```
+
+## Ejemplo Concreto
+
+### Input: Proyecto React + Express detectado
+
+```
+Detección:
+├── package.json → Node.js, React 18, Express 4
+├── tsconfig.json → TypeScript 5
+├── tailwind.config.ts → Tailwind CSS
+├── prisma/schema.prisma → Prisma ORM, PostgreSQL
+└── .github/workflows/ci.yml → {{TECH_STACK}} CI/CD
+```
+
+### Output: Archivos creados
+
+```
+✅ README.md
+   - "Plataforma web construida con React 18 y Express 4"
+   - Stack table con React, Express, PostgreSQL, {{TECH_STACK}}
+   - Commands: npm run dev, npm run build, npm run test, npm run lint
+
+✅ CHANGELOG.md
+   - Entrada inicial: "## [0.1.0] - 2026-05-07 / ### Added / - Initial release"
+
+✅ AGENTS.md
+   - Stack: React 18, Express 4, PostgreSQL, Prisma, Tailwind, {{TECH_STACK}}
+   - Commands: npm run dev/build/test/lint/typecheck
+   - Protocolo completo (antes/después/subdelegar)
+
+✅ docs/README.md
+   - Mapa con 8 archivos creados
+   - Growth rules: "Crear reference/api.md cuando haya 5+ endpoints"
+   - Tabla Diátaxis: tutorials/ ✅, guides/ ⏭️, reference/ ⏭️, explanation/ ⏭️
+
+✅ docs/CONTEXT.md
+   - 6 términos extraídos: User, Session, Workspace, Role, Permission, Token
+   - Relaciones: User → Session, User ← Role ← Permission
+   - ⚠️ AMBIGUO: "workspace" (puede ser equipo o proyecto)
+
+✅ docs/adr/TEMPLATE.md
+   - Formato minimal listo para usar
+
+✅ docs/tutorials/quick-start.md
+   - Prerequisitos: Node 20+, {{TECH_STACK}}, npm
+   - Pasos: clone → npm install → cp .env.example .env → npx prisma migrate dev → npm run dev
+   - Verificación: "Abre http://localhost:3000 — deberías ver la landing"
+
+⏭️ Pendientes (lazy):
+   - docs/adr/0001-*.md → cuando haya una decisión arquitectónica
+   - docs/DESIGN.md → cuando se definan tokens de diseño
+   - docs/reference/api.md → cuando haya 5+ endpoints estables
+   - docs/guides/deployment.md → cuando haya proceso de deploy
+```
+
+## Recursos
+
+- [Diátaxis Quick Reference](references/diataxis-quick-ref.md) — Resumen del framework Diátaxis con árbol de decisión
+- Skills relacionados: `doc-write` (escribir docs), `doc-review` (auditar docs), `doc-maintain` (mantener docs sincronizados)

package/templates/modules/agents/.agents/skills/doc-scaffold/references/diataxis-quick-ref.md

@@ -0,0 +1,149 @@
+---
+created: "2024-01-15"
+status: active
+type: reference
+tags: [diataxis, framework, documentacion, referencia]
+---
+
+# Diátaxis — Referencia Rápida
+
+## Los 4 Cuadrantes
+
+Diátaxis clasifica la documentación en 4 tipos según dos ejes:
+
+- **Eje horizontal**: Estudio (aprender) vs Trabajo (aplicar)
+- **Eje vertical**: Práctico (acción) vs Teórico (conocimiento)
+
+```
+                    │ Práctico (acción)
+                    │
+         Tutorial   │   How-to
+      (Aprender     │  (Aplicar
+       haciendo)    │   soluciones)
+                    │
+────────────────────┼────────────────────
+                    │
+      Explicación   │  Referencia
+     (Entender el   │ (Buscar
+       porqué)      │  información)
+                    │
+                    │ Teórico (conocimiento)
+```
+
+### Tutorial
+
+- **Orientación**: Aprendizaje
+- **Propósito**: Guiar al principiante paso a paso para adquirir una habilidad
+- **Tono**: Didáctico, paciente, alentador
+- **Ejemplo**: "Tu primera API con Express.js" — el usuario aprende mientras construye
+
+### How-to (Guía práctica)
+
+- **Orientación**: Práctica
+- **Propósito**: Resolver un problema específico concreto
+- **Tono**: Directo, asume conocimiento previo
+- **Ejemplo**: "Cómo configurar autenticación con JWT" — el usuario ya sabe Express, necesita JWT
+
+### Referencia
+
+- **Orientación**: Información
+- **Propósito**: Describir la maquinaria de forma factual y completa
+- **Tono**: Neutral, estructurado, sin narrativa
+- **Ejemplo**: "API de endpoints" — tablas con métodos, parámetros, respuestas
+
+### Explicación
+
+- **Orientación**: Comprensión
+- **Propósito**: Aclarar el porqué, dar contexto, conectar conceptos
+- **Tono**: Discursivo, analítico
+- **Ejemplo**: "Por qué elegimos event-sourcing" — contexto histórico, alternativas, trade-offs
+
+## Cuándo Usar Cada Tipo
+
+| Situación | Tipo | Carpeta |
+|-----------|------|---------|
+| Usuario nuevo quiere empezar | Tutorial | `tutorials/` |
+| Usuario tiene un problema específico | How-to | `how-to/` |
+| Usuario necesita consultar un detalle | Referencia | `reference/` |
+| Usuario pregunta "¿por qué?" | Explicación | `explanation/` |
+| Onboarding de nuevo dev | Tutorial | `tutorials/` |
+| Configurar algo que ya se conoce | How-to | `how-to/` |
+| Buscar parámetros de una función | Referencia | `reference/` |
+| Entender una decisión arquitectónica | Explicación | `explanation/` |
+
+## Árbol de Decisión
+
+```
+¿El lector necesita aprender algo nuevo desde cero?
+├── SÍ → ¿Se aprende mejor haciendo?
+│   ├── SÍ → TUTORIAL → tutorials/
+│   └── NO → EXPLICACIÓN → explanation/
+└── NO → ¿Necesita resolver un problema práctico?
+    ├── SÍ → ¿Necesita pasos concretos?
+    │   ├── SÍ → HOW-TO → how-to/
+    │   └── NO → EXPLICACIÓN → explanation/
+    └── NO → ¿Necesita buscar información específica?
+        ├── SÍ → REFERENCIA → reference/
+        └── NO → Replantear la necesidad
+```
+
+## Ejemplos por Tipo en Proyectos Web
+
+### Tutorial (tutorials/)
+
+| Título | Qué enseña |
+|--------|------------|
+| `quick-start.md` | Crear el primer endpoint, levantar el proyecto |
+| `first-component.md` | Crear un componente React/Vue desde cero |
+| `database-setup.md` | Configurar la base de datos por primera vez |
+| `deploy-guide.md` | Hacer el primer deploy paso a paso |
+
+### How-to (how-to/)
+
+| Título | Qué resuelve |
+|---------|-------------|
+| `add-auth.md` | Agregar autenticación a una API existente |
+| `custom-middleware.md` | Crear middleware personalizado |
+| `migrate-database.md` | Ejecutar una migración de base de datos |
+| `configure-ci.md` | Configurar pipeline de CI/CD |
+| `add-new-endpoint.md` | Agregar un nuevo endpoint REST |
+| `debug-connection.md` | Diagnosticar problemas de conexión |
+
+### Referencia (reference/)
+
+| Título | Qué documenta |
+|---------|-------------|
+| `api.md` | Todos los endpoints: método, ruta, params, respuesta |
+| `configuration.md` | Todas las variables de configuración y sus valores |
+| `cli.md` | Todos los comandos CLI con flags y ejemplos |
+| `events.md` | Todos los eventos del sistema con payload |
+| `errors.md` | Códigos de error con significado y resolución |
+
+### Explicación (explanation/)
+
+| Título | Qué explica |
+|---------|------------|
+| `architecture.md` | Visión general de la arquitectura y sus capas |
+| `authentication-flow.md` | Cómo funciona el flujo de auth end-to-end |
+| `database-design.md` | Por qué se eligió el esquema actual |
+| `caching-strategy.md` | Estrategia de caché y sus trade-offs |
+| `adr/001-event-sourcing.md` | Decisión arquitectónica con contexto |
+
+## Tabla Rápida: Objetivo del Usuario → Tipo → Ubicación
+
+| Objetivo del usuario | Tipo de doc | Ubicación |
+|---------------------|------------|-----------|
+| "Quiero aprender a usar esto" | Tutorial | `tutorials/` |
+| "Quiero hacer X cosa específica" | How-to | `how-to/` |
+| "Necesito consultar un dato" | Referencia | `reference/` |
+| "Quiero entender por qué es así" | Explicación | `explanation/` |
+| "¿Cómo se decide la arquitectura?" | ADR | `docs/adr/` |
+| "¿Qué significa este término?" | CONTEXT | `docs/CONTEXT.md` |
+| "¿Cómo se ve el sistema?" | Diseño | `DESIGN.md` |
+| "¿Qué cambió en cada versión?" | Changelog | `CHANGELOG.md` |
+
+## Regla de Oro
+
+**Un documento = Un propósito = Un tipo Diátaxis.**
+
+Si un documento intenta ser tutorial Y referencia al mismo tiempo, ninguno de los dos funciona bien. Separar es mejorar.