@damenor/agent-docs 0.1.1 → 0.4.0

package/templates/base/AGENTS.md

@@ -1,177 +0,0 @@
----
-project: "{{PROJECT_NAME}}"
-stack: "{{TECH_STACK}}"
-created: "2025-01-01"
-updated: "2026-05-07"
-status: active
-type: agent-protocol
-tags: [agents, protocolo, operativo, ia]
----
-
-# AGENTS.md — Protocolo Operativo
-
-Reglas que TODO agente de IA debe seguir al trabajar en este proyecto. Guía extendida: `docs/internal/agent-guide.md`.
-
----
-
-## STOP — Lee esto ANTES de hacer nada
-
-1. **TRIAGE**: Clasifica la tarea (SMALL/MEDIUM/LARGE). No saltes este paso.
-2. **LEE**: Lee la documentación indicada en la tabla ANTES de escribir código.
-3. **PREGUNTA**: Si hay ambigüedad, haz TODAS las preguntas en UN solo mensaje.
-4. **NO IMPLEMENTES** sin seguir el protocolo completo (MEDIUM/LARGE).
-5. **@reviewer**: Invoca ANTES de marcar la tarea como completada (MEDIUM/LARGE).
-
----
-
-## Triage de tarea
-
-Antes de ejecutar el protocolo, clasificar la tarea:
-
-| Tamaño | Criterio | Protocolo |
-|--------|----------|-----------|
-| **SMALL** | ≤2 archivos, <50 líneas | Leer CONTEXT.md → implementar → lint → done |
-| **MEDIUM** | 3-10 archivos, feature moderada | Protocolo completo (sin subdelegación) |
-| **LARGE** | Multi-día, arquitectural | Protocolo completo + ADR + subdelegación |
-
-**Ejemplos**: SMALL = fix typo, cambiar color, corregir import. MEDIUM = nuevo endpoint, nuevo componente, nuevo servicio simple. LARGE = sistema de auth, integración con provider externo, sistema de notificaciones multi-canal.
-
-Si empiezas SMALL y la tarea crece → escalar a MEDIUM.
-
----
-
-## Stack y convenciones
-
-### Stack
-- **Frontend**: [framework y versión — ej. {{FRAMEWORK}}]
-- **Backend**: [framework y versión — ej. {{FRAMEWORK}}]
-- **Base de datos**: [tipo y versión — ej. {{TECH_STACK}}]
-- **CI/CD**: [plataforma — ej. {{TECH_STACK}}]
-
-### Detección automática de stack
-
-Si el stack no está rellenado arriba, el agente debe detectarlo:
-
-| Archivo detectado | Ecosistema | Comandos probables |
-|-------------------|------------|--------------------|
-| `package.json` | Node.js (npm/pnpm/yarn) | `npm run dev`, `npm run build` |
-| `requirements.txt` / `pyproject.toml` | Python (pip/poetry) | `python manage.py runserver`, `pytest` |
-| `go.mod` | Go | `go run .`, `go test ./...` |
-| `Cargo.toml` | Rust | `cargo run`, `cargo test` |
-| `pom.xml` / `build.gradle` | Java/Kotlin | `mvn spring-boot:run`, `gradle bootRun` |
-
-### Convenios obligatorios
-1. **Idioma**: Código en **inglés**. Comentarios y docs en **español**.
-2. **Nombramiento**: [convención de nombres — ej. camelCase variables/funciones, PascalCase componentes]
-3. **Estructura**: [convención — ej. feature-based folders]
-4. **Testing**: Todo código nuevo DEBE incluir tests.
-5. **Linting**: Pasar `npm run lint` sin errores antes de completar.
-6. **Commits**: Conventional Commits en español: `tipo(alcance): descripción`.
-7. **Seguridad**: Nunca commitear secrets. Usar variables de entorno.
-8. **Dependencias**: No añadir sin justificación. Si se añade → documentar en ADR.
-9. **Accesibilidad**: Todo componente UI cumple WCAG 2.1 AA.
-
-### Comandos
-
-| Comando | Uso |
-|---------|-----|
-| `npm run dev` | Desarrollo con hot-reload |
-| `npm run build` | Build producción |
-| `npm run test` | Tests unitarios e integración |
-| `npm run test:e2e` | Tests end-to-end |
-| `npm run lint` | Linter (debe pasar sin errores) |
-| `npm run typecheck` | Verificación de tipos |
-
-> **Detalle completo** de convenciones de git, commits, PRs y testing en [`docs/dev-workflow.md`](docs/dev-workflow.md).
-
----
-
-## ANTES de cada tarea (MEDIUM/LARGE)
-
-### 1. Leer docs según tipo de tarea
-
-| Tipo de tarea | Documentación a leer primero |
-|---------------|------------------------------|
-| Cualquier tarea | `docs/CONTEXT.md` |
-| Feature nueva | `docs/roadmap.md`, `docs/explanation/architecture.md`, ADRs relevantes |
-| Bug/UI/Estilo | `docs/DESIGN.md`, `docs/CONTEXT.md` |
-| API/Backend | `docs/reference/api.md`, `docs/reference/configuration.md` |
-| Deploy/Infra | `docs/guides/deployment.md`, `docs/reference/infrastructure.md` |
-| Arquitectura | `docs/explanation/architecture.md`, `docs/adr/` (todos) |
-
-### 2. Verificar ADRs existentes
-
-Buscar en `docs/adr/` antes de tomar decisiones:
-- **Existe ADR aceptado** → SEGUIRLO. No reinventar.
-- **Contradice lo que vas a hacer** → Plantear discusión antes.
-- **No existe** → Evaluar si merece ADR (ver criterio y ejemplos en [`docs/adr/TEMPLATE.md`](docs/adr/TEMPLATE.md)).
-
-### 3. Verificar CONTEXT.md
-
-Si la tarea usa términos que no están en `docs/CONTEXT.md` → preparar para actualizar al terminar.
-
-Si `CONTEXT.md` tiene `completeness < 50%` → prioridad: completar CONTEXT.md antes de implementar features.
-
-### 4. Preguntar si hay ambigüedad
-
-Si después de leer la documentación hay ambigüedad → **batch TODAS las preguntas en un solo mensaje**. Cada pregunta con opciones cuando sea posible. No preguntar una por una.
-
-No preguntes si la tarea está clara, es implementación estándar, o la info está en los docs.
-
----
-
-## DESPUÉS de cada tarea (MEDIUM/LARGE)
-
-### Árbol post-tarea
-
-```
-¿Tomaste una decisión?
-  ├── Arquitectónica → docs/adr/ (ADR formal)
-  ├── Implementación no obvia → JSDoc + docs/adr/ai-decisions.md
-  └── No → siguiente
-¿Términos nuevos del dominio? → docs/CONTEXT.md
-¿Endpoints cambiados? → docs/reference/api.md
-¿UI/UX cambiada? → docs/DESIGN.md
-¿Deploy a producción? → CHANGELOG.md + docs/guides/deployment.md
-¿Feature completado? → docs/roadmap.md
-¿Gotcha descubierto? → docs/guides/troubleshooting.md
-¿Refactor de patrones? → Revisar architecture.md y ADRs
-```
-
-> **Guía extendida** con diagramas y ejemplos en [`docs/internal/agent-guide.md`](docs/internal/agent-guide.md).
-> **Alternativa**: Invocar skill `doc-maintain` para detectar cambios y sugerir actualizaciones automáticamente.
-
-**Regla de oro**: Si cambias el código, cambias la documentación.
-
----
-
-## Quality Gate — @reviewer (MEDIUM/LARGE)
-
-**ANTES de completar**, invocar `@reviewer` para verificar:
-- ✅ Code style conforme a convenciones
-- ✅ Sin duplicación — usa componentes/utilidades existentes
-- ✅ Sigue la arquitectura del proyecto y respeta ADRs
-- ✅ Sin vulnerabilidades de seguridad
-- ✅ Tests incluidos para código nuevo
-- ✅ Documentación actualizada
-- ✅ Sin problemas de performance evidentes
-
-- **❌ BLOQUEANTE** → arreglar antes de completar.
-- **⚠️ SUGERIDO** → recomendado pero no bloquea.
-
----
-
-## Subdelegación
-
-Instrucciones mínimas al subagente:
-> Lee AGENTS.md y sigue el protocolo completo. Tarea: [descripción]. Docs relevantes: [lista].
-
-No repitas convenciones — ya están en AGENTS.md. Ver ejemplo completo en `docs/internal/agent-guide.md`.
-
----
-
-## Skills y agentes disponibles
-
-- **Skills**: `doc-scaffold`, `doc-write`, `doc-design`, `doc-review`, `doc-maintain` — ver `.agents/skills/`
-- **Agentes**: `@reviewer` (quality gate), `@doc-writer`, `@doc-reviewer`, `@doc-designer`, `@doc-maintainer` — ver `.agents/agents/`
-- **Guía extendida**: `docs/internal/agent-guide.md`

package/templates/base/CHANGELOG.md

@@ -1,86 +0,0 @@
----
-created: "2025-01-01"
-status: active
-type: changelog
-tags: [changelog, cambios, versiones]
----
-
-# Changelog
-
-Todos los cambios notables de este proyecto se documentarán en este archivo.
-
-El formato está basado en [Keep a Changelog](https://keepachangelog.com/es-ES/1.1.0/),
-y este proyecto adhiere a [Versionado Semántico](https://semver.org/lang/es/).
-
----
-
-## [Sin publicar]
-
-<!-- 
-  Sección para cambios que ya están en main pero que aún no se publican.
-  Mover las entradas aquí al momento de hacer un release.
--->
-
-### Añadido
-- `TEMPLATE-README.md` con instrucciones paso a paso para usar este template.
-- `.editorconfig` para formato consistente entre editores.
-- `.markdownlint.json` para linting de archivos Markdown.
-- `.github/workflows/docs-check.yml` — CI que verifica frontmatter, archivos vacíos, links rotos y completeness de CONTEXT.md.
-- Tabla de detección automática de stack en `AGENTS.md` (soporte multi-lenguaje: Node, Python, Go, Rust, Java).
-- Diagramas Mermaid en `architecture.md` y `agent-guide.md` (reemplazan ASCII art).
-- Cross-references entre archivos para reducir duplicación interna.
-
-### Cambiado
-- `agent-flow.md` fusionado en `agent-guide.md` — el archivo original redirige.
-- `DESIGN.md` — bloque YAML ahora indica explícitamente que son valores de ejemplo.
-- `AGENTS.md` — criterio ADR referencia `TEMPLATE.md` en vez de duplicarlo.
-- `doc-maintain` skill — checklist post-tarea referencia `AGENTS.md` en vez de duplicar.
-- `doc-scaffold` skill — detección de stack ahora referencia tabla de `AGENTS.md`.
-
-### Corregido
-- Bug de caracteres chinos en `docs/README.md` ("命名" → "nomenclatura").
-
-### Cambiado
-<!-- Cambios en funcionalidad existente. Ejemplo: - Se actualizó el flujo de registro para incluir verificación por email. -->
-
-### Corregido
-<!-- Corrección de bugs. Ejemplo: - Se corrigió error 500 al enviar formularios con caracteres especiales. -->
-
-### Eliminado
-<!-- Funcionalidades eliminadas. Ejemplo: - Se eliminó el endpoint deprecated /api/v1/users. -->
-
----
-
-## [0.1.0] - 2025-01-15
-
-### Añadido
-- Inicialización del proyecto con estructura base.
-- Configuración de CI/CD pipeline.
-- Documentación completa del proyecto (ver `docs/`).
-
----
-
-<!-- 
-  GUÍA DE FORMATO:
-  
-  Tipos de cambios permitidos:
-  
-  - **Añadido**: para funcionalidades nuevas.
-  - **Cambiado**: para cambios en funcionalidad existente.
-  - **Deprecado**: para funcionalidades que serán eliminadas en futuras versiones.
-  - **Eliminado**: para funcionalidades eliminadas en esta versión.
-  - **Corregido**: para corrección de bugs.
-  - **Seguridad**: para correcciones de vulnerabilidades.
-  
-  Reglas:
-  
-  1. Cada versión tiene su fecha en formato YYYY-MM-DD.
-  2. La sección "Sin publicar" siempre está primero.
-  3. Los enlaces de comparación van al final del archivo.
-  4. Una entrada por cambio, prefijada con "- ".
-  5. Ordenar cambios: Añadido > Cambiado > Deprecado > Eliminado > Corregido > Seguridad.
-  6. Actualizar al momento de deploy (no al momento de codear).
--->
-
-[0.1.0]: https://github.com/org/{{PROJECT_NAME}}/releases/tag/v0.1.0
-<!-- [Sin publicar]: https://github.com/org/{{PROJECT_NAME}}/compare/v0.1.0...HEAD -->

package/templates/base/README.md

@@ -1,110 +0,0 @@
----
-created: "2025-01-01"
-status: active
-type: project-overview
-tags: [readme, proyecto, índice]
----
-
-# {{PROJECT_NAME}}
-
-> [Una línea que describe qué hace este proyecto y para quién. Ejemplo: "Portal web corporativo para la gestión de trámites internos del sector finanzas."]
-
----
-
-## Inicio rápido
-
-```bash
-# Clonar el repositorio
-git clone https://github.com/org/{{PROJECT_NAME}} && cd [NOMBRE_DEL_PROYECTO]
-
-# Instalar dependencias
-[comando de instalación]
-
-# Iniciar servidor de desarrollo
-[comando de dev]
-```
-
-El proyecto debería estar disponible en `http://localhost:3000`.
-
----
-
-## Mapa de documentación
-
-Toda la documentación detallada vive en [`docs/`](docs/README.md).
-
-| Sección | Qué encontrarás | Ir a |
-|---------|-----------------|------|
-| Producto | Visión, roadmap, stakeholders | [`docs/product/`](docs/product/overview.md) |
-| Tutoriales | Quick start, setup, primera tarea | [`docs/tutorials/`](docs/tutorials/quick-start.md) |
-| Guías | Deploy, troubleshooting, runbooks | [`docs/guides/`](docs/guides/deployment.md) |
-| Referencia | API, configuración, infraestructura | [`docs/reference/`](docs/reference/api.md) |
-| Explicación | Arquitectura, decisiones (ADRs) | [`docs/explanation/`](docs/explanation/architecture.md) |
-| Operaciones | Monitoreo, incidentes, SLAs | [`docs/operations/`](docs/operations/README.md) |
-
-Archivos clave en la raíz:
-
-- [`AGENTS.md`](AGENTS.md) — Protocolo operativo para agentes de IA
-- [`CHANGELOG.md`](CHANGELOG.md) — Registro de cambios del proyecto
-- [`docs/CONTEXT.md`](docs/CONTEXT.md) — Vocabulario y lenguaje del dominio
-- [`docs/DESIGN.md`](docs/DESIGN.md) — Sistema de diseño (colores, tipografía, componentes)
-
----
-
-## Comandos
-
-| Comando | Descripción |
-|---------|-------------|
-| `[npm run dev]` | Inicia el servidor de desarrollo con hot-reload |
-| `[npm run build]` | Genera la build de producción |
-| `[npm run test]` | Ejecuta la suite de tests |
-| `[npm run lint]` | Ejecuta el linter y el formateador |
-| `[npm run test:e2e]` | Ejecuta tests end-to-end |
-
-> **Fuente de verdad**: [`AGENTS.md`](AGENTS.md) § Comandos. Actualizar ahí primero.
-
-## Arquitectura
-
-Para entender cómo está construido el proyecto, leer [`docs/explanation/architecture.md`](docs/explanation/architecture.md).
-
-Resumen rápido:
-
-```
-[DIAGRAMA SIMPLIFICADO DE LA ARQUITECTURA]
-
-Cliente (Browser)
-  ↓
-[Frontend Framework]
-  ↓
-[API / Backend]
-  ↓
-[Base de datos]
-```
-
-Las decisiones de arquitectura se documentan como ADRs en [`docs/adr/`](docs/adr/TEMPLATE.md).
-
----
-
-## Stack
-
-| Capa | Tecnología | Versión |
-|------|-----------|---------|
-| Frontend | [framework] | [versión] |
-| Backend | [framework] | [versión] |
-| Base de datos | [tipo] | [versión] |
-| CI/CD | [plataforma] | — |
-| Hosting | [proveedor] | — |
-| Lenguaje | [lenguaje] | [versión] |
-
----
-
-## Contribuir
-
-1. Lee [`docs/dev-workflow.md`](docs/dev-workflow.md) para el flujo de trabajo interno.
-2. Lee [`AGENTS.md`](AGENTS.md) si trabajas con agentes de IA.
-3. Lee [`docs/tutorials/first-task.md`](docs/tutorials/first-task.md) para tu primera contribución.
-
----
-
-## Licencia
-
-[TIPO DE LICENCIA — Ejemplo: Privada. Todos los derechos reservados.]

package/templates/base/docs/CONTEXT.md

@@ -1,111 +0,0 @@
----
-created: "2025-01-01"
-updated: "2025-01-01"
-status: active
-completeness: "15%"
-type: domain-language
-tags: [contexto, dominio, vocabulario, glosario]
----
-
-# CONTEXT.md — Lenguaje del Dominio
-
-Este archivo define el vocabulario compartido que se usa en este proyecto. Todo término de negocio o concepto clave del dominio debe estar documentado aquí.
-
-Si un término aparece en el código, la documentación o las conversaciones del equipo y NO está en este archivo, es un gap que debe cubrirse.
-
----
-
-## Lenguaje del dominio
-
-### Entidades principales
-
-| Término | Definición | Ejemplo de uso | Equivalente técnico |
-|---------|-----------|----------------|-------------------|
-| **[Término 1]** | [Qué es, en una oración, desde la perspectiva del negocio] | "El [término] se vence el viernes." | `[nombre_en_codigo]` |
-| **[Término 2]** | [Qué es, en una oración, desde la perspectiva del negocio] | "Cada [término] puede tener múltiples [otro término]." | `[nombre_en_codigo]` |
-| **[Término 3]** | [Qué es, en una oración, desde la perspectiva del negocio] | "El sistema genera un [término] automáticamente." | `[nombre_en_codigo]` |
-
-### Estados y flujos
-
-| Término | Significa | Transiciones posibles |
-|---------|-----------|----------------------|
-| **[Estado A]** | [Qué significa este estado en términos de negocio] | → [Estado B], → [Estado C] |
-| **[Estado B]** | [Qué significa este estado en términos de negocio] | → [Estado C] |
-| **[Estado C]** | [Estado final — qué implica] | — |
-
-### Roles y permisos
-
-| Rol | Quién es | Qué puede hacer |
-|-----|----------|----------------|
-| **[Rol 1]** | [Descripción del perfil de usuario] | [Lista de permisos clave] |
-| **[Rol 2]** | [Descripción del perfil de usuario] | [Lista de permisos clave] |
-| **Admin** | Administrador del sistema con acceso total | Gestiona usuarios, configuración global, y puede asumir cualquier rol |
-
-### Términos de negocio
-
-| Término | Definición | Notas |
-|---------|-----------|-------|
-| **[Término de negocio]** | [Definición desde la perspectiva del negocio, no técnica] | [Contexto adicional o advertencias] |
-| **[Otro término]** | [Definición] | [Ejemplo: "No confundir con [término similar]. Ver [otra sección]."] |
-
-### Términos técnicos internos
-
-| Término | Definición | Por qué existe |
-|---------|-----------|----------------|
-| **[Término técnico]** | [Qué es y cómo se usa en este proyecto específicamente] | [Motivo por el que se introdujo o contexto de la decisión] |
-
----
-
-## Relaciones entre conceptos
-
-```
-[Entidad 1] ─── 1:N ───→ [Entidad 2]
-                         └──→ [Entidad 3] (a través de [Entidad 4])
-
-[Rol 1] ─── puede ───→ [Acción A] sobre [Entidad 1]
-                     └──→ [Acción B] sobre [Entidad 2]
-
-[Estado A] ──→ [Estado B] ──→ [Estado C] ──→ [Estado D]
-                                              └──→ [Estado E] (reversión)
-```
-
----
-
-## Ejemplo de diálogo usando el dominio
-
-Este ejemplo muestra cómo se usa el vocabulario en una conversación real del equipo:
-
-> **Product Manager**: "El cliente necesita que los [Término 1] en estado [Estado A] se puedan convertir automáticamente en [Término 2] cuando pasen a [Estado B]."
->
-> **Developer**: "Entendido. ¿Esa conversación aplica para todos los [Rol 1] o solo para los que tienen permiso de [acción]?"
->
-> **Product Manager**: "Solo para [Rol 1]. Los [Rol 2] solo ven el [Término 1] pero no pueden convertirlo."
->
-> **Developer**: "Perfecto. Voy a añadir un botón de conversión en la vista de [Término 1] para [Rol 1], visible solo cuando esté en [Estado A]. ¿El [Término 2] resultante empieza en [Estado C]?"
->
-> **Product Manager**: "Sí, empieza en [Estado C] y necesita aprobación de un [Rol 2] para pasar a [Estado D]."
-
----
-
-## Ambigüedades flagadas
-
-Estos términos tienen significados que podrían confundirse. Prestar atención al contexto:
-
-| Término | Confusión posible | Aclaración |
-|---------|-------------------|-----------|
-| **[Término ambiguo]** | Se podría confundir con [otro término] | En este proyecto significa [definición precisa]. No es lo mismo que [otro término]. |
-| **[Otro término ambiguo]** | Significa cosas distintas según el contexto | Cuando dice "[término]" en el contexto de [área 1] significa [X]. En el contexto de [área 2] significa [Y]. |
-
----
-
-## Cómo actualizar este archivo
-
-Cuando se añada un nuevo término al dominio:
-
-1. Identificar si es una **entidad**, un **estado**, un **rol**, un **término de negocio** o un **término técnico**.
-2. Añadirlo en la sección correspondiente con: definición, ejemplo de uso, y equivalente técnico.
-3. Si tiene relaciones con otras entidades, actualizar el diagrama de relaciones.
-4. Si es ambiguo o se confunde con otro término, añadirlo en "Ambigüedades flagadas".
-5. Si se introdujo un nuevo estado o flujo, actualizar la tabla de estados.
-
-**Regla**: Todo término que aparezca en código, APIs, UI o conversaciones del equipo DEBE estar aquí. Si no está, es un bug de documentación.

package/templates/base/docs/README.md

@@ -1,131 +0,0 @@
----
-created: "2025-01-01"
-status: active
-type: doc-map
-tags: [documentación, índice, mapa, diátaxis]
----
-
-# Mapa de Documentación
-
-Este directorio contiene **toda la documentación** del proyecto, organizada siguiendo el framework Diátaxis.
-
----
-
-## Estructura de directorios
-
-```
-docs/
-├── README.md                           # ← ESTE ARCHIVO. Mapa y reglas de la documentación.
-├── CONTEXT.md                          # Vocabulario y lenguaje del dominio.
-├── DESIGN.md                           # Sistema de diseño (colores, tipografía, componentes).
-├── roadmap.md                          # Planificación y estado de features.
-├── dev-workflow.md                     # Convenciones internas de desarrollo.
-│
-├── product/                            # CONTEXTO DE PRODUCTO
-│   └── overview.md                     # Visión, usuarios, valor, métricas.
-│
-├── tutorials/                          # APRENDER — Orientados a aprendizaje
-│   ├── quick-start.md                  # Arrancar el proyecto en 15 minutos.
-│   ├── environment-setup.md            # Configurar el entorno de desarrollo.
-│   └── first-task.md                   # Hacer tu primera contribución end-to-end.
-│
-├── guides/                             # APLICAR — Orientados a tareas
-│   ├── deployment.md                   # Cómo hacer deploy a cada entorno.
-│   ├── troubleshooting.md              # Problemas comunes y soluciones.
-│   └── runbooks/                       # Runbooks para incidentes.
-│       └── TEMPLATE.md                 # Plantilla para crear runbooks nuevos.
-│
-├── reference/                          # CONSULTAR — Información objetiva
-│   ├── api.md                          # Referencia completa de la API.
-│   ├── code-style.md                   # Convenciones de código (naming, imports, etc.)
-│   ├── configuration.md                # Variables de entorno y configuración.
-│   └── infrastructure.md               # Entornos, URLs, acceso, CI/CD.
-│
-├── explanation/                        # ENTENDER — Orientados a comprensión
-│   ├── agent-flow.md                   # → Redirige a docs/internal/agent-guide.md
-│   └── architecture.md                 # Cómo y por qué está diseñado el sistema.
-│
-├── adr/                                # DECISIONES — Architecture Decision Records
-│   ├── TEMPLATE.md                     # Plantilla para crear ADRs nuevos.
-│   └── 0001-record-architecture-decisions.md  # Meta-ADR: por qué usamos ADRs.
-│
-└── operations/                         # OPERACIONES — Monitoreo e incidentes
-    └── README.md                       # Hub de operaciones: SLAs, monitoreo, post-mortems.
-```
-
----
-
-## Clasificación Diátaxis
-
-La documentación se organiza en cuatro cuadrantes según su propósito:
-
-| Carpeta | Cuadrante | Propósito | Se lee cuando... |
-|---------|-----------|-----------|------------------|
-| `tutorials/` | **Aprender** | Guías paso a paso para aprender haciendo | "Quiero aprender cómo funciona esto" |
-| `guides/` | **Aplicar** | Instrucciones para completar una tarea específica | "Necesito hacer X, ¿cómo?" |
-| `reference/` | **Consultar** | Información técnica objetiva y completa | "¿Cuáles son los parámetros de esta función?" |
-| `explanation/` | **Entender** | Contexto, porqués, decisiones de diseño | "¿Por qué se diseñó así?" |
-
-Archivos transversales que no pertenecen a un cuadrante:
-
-| Archivo | Propósito |
-|---------|-----------|
-| `CONTEXT.md` | Define el vocabulario compartido del dominio. Se consulta constantemente. |
-| `DESIGN.md` | Sistema de diseño visual. Referencia para todo cambio de UI. |
-| `roadmap.md` | Estado de features y planificación. Se actualiza con cada sprint. |
-| `dev-workflow.md` | Convenciones internas: git, commits, PRs, code review. |
-| `product/` | Contexto de negocio: visión, usuarios, stakeholders, métricas. |
-| `adr/` | Registro de decisiones técnicas. Se consulta antes de tomar decisiones. |
-| `operations/` | Monitoreo, incidentes, SLAs. Se consulta durante y después de incidentes. |
-
----
-
-## Reglas de crecimiento
-
-La documentación crece orgánicamente. **No crear archivos vacíos "por si acaso".**
-
-### Cuándo crear un archivo nuevo
-
-| Se crea cuando... | Dónde va | Tipo |
-|-------------------|----------|------|
-| Hay un nuevo tutorial paso a paso que no existe | `tutorials/` | Aprender |
-| Hay una tarea operativa recurrente sin guía | `guides/` | Aplicar |
-| Hay un componente/servicio nuevo que consultar | `reference/` | Consultar |
-| Hay un concepto que necesita explicación de fondo | `explanation/` | Entender |
-| Hay una decisión técnica con trade-offs | `adr/` | Decisión |
-| Hay un incidente recurrente que necesita pasos fijos | `guides/runbooks/` | Runbook |
-
-### Cuándo NO crear un archivo
-
-- Si la información ya existe en otro lado → **enlazar, no duplicar**.
-- Si es un "TODO" sin contenido real → **no crear el archivo hasta tener contenido**.
-- Si la información cambia constantemente → **mejor ponerla en código (ej. config en `.env.example`)**.
-
-### Reglas de nomenclatura
-
-- **Tutoriales**: Verbos en infinitivo, descriptivos. Ej. `quick-start.md`, `environment-setup.md`.
-- **Guías**: Sustantivos que describan la tarea. Ej. `deployment.md`, `troubleshooting.md`.
-- **Referencia**: Sustantivos del sistema. Ej. `api.md`, `configuration.md`, `infrastructure.md`.
-- **Explicación**: Conceptos amplios. Ej. `architecture.md`, `auth-flow.md`.
-- **ADRs**: Numerados. Ej. `0001-record-architecture-decisions.md`.
-- **Runbooks**: Nombre del incidente/servicio. Ej. `database-connection-timeout.md`.
-
----
-
-## Convenciones de formato
-
-1. **Todo archivo** tiene YAML frontmatter con `created`, `status`, `type`, `tags`.
-2. **Todo archivo** empieza con un H1 (`#`) con el título del documento.
-3. **Contenido en español**, términos técnicos y nombres de archivos en inglés.
-4. **Enlaces relativos** entre archivos de documentación (no absolutos).
-5. **Una fuente de verdad**: cada dato vive en UN archivo. En los demás, enlazar.
-
----
-
-## Mantenimiento
-
-La documentación se mantiene actualizada siguiendo el protocolo definido en [`AGENTS.md`](../AGENTS.md). Después de cada tarea, verificar la checklist post-tarea para actualizar los archivos afectados.
-
-Para auditar el estado de la documentación, usar la skill `doc-review`.
-
-Para validación automática en CI, ver [`.github/workflows/docs-check.yml`](../.github/workflows/docs-check.yml).