@damenor/agent-docs 0.1.0 → 0.1.2

package/templates/base/README.md

@@ -1,110 +1,105 @@
----
-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."]
+<!-- Badges — update or remove as needed -->
+[![license](https://img.shields.io/badge/license-MIT-blue)](LICENSE)
+[![status](https://img.shields.io/badge/status-active-success)()
+
+> One-line description of what this project does and who it's for.
 
 ---
 
-## Inicio rápido
+## 🚀 Quick Start
 
 ```bash
-# Clonar el repositorio
-git clone https://github.com/org/{{PROJECT_NAME}} && cd [NOMBRE_DEL_PROYECTO]
+# Clone the repository
+git clone https://github.com/org/{{PROJECT_NAME}}.git && cd {{PROJECT_NAME}}
 
-# Instalar dependencias
-[comando de instalación]
+# Install dependencies
+npm install
 
-# Iniciar servidor de desarrollo
-[comando de dev]
+# Start development server
+npm run dev
 ```
 
-El proyecto debería estar disponible en `http://localhost:3000`.
+The project should be available at `http://localhost:3000`.
 
 ---
 
-## Mapa de documentación
+## 📖 Documentation Map
 
-Toda la documentación detallada vive en [`docs/`](docs/README.md).
+All documentation lives in [`docs/`](docs/README.md).
 
-| Sección | Qué encontrarás | Ir a |
+| Section | What you'll find | Link |
 |---------|-----------------|------|
-| 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) |
+| Product | Vision, roadmap, stakeholders | [`docs/product/`](docs/product/overview.md) |
+| Tutorials | Quick start, setup, first task | [`docs/tutorials/`](docs/tutorials/quick-start.md) |
+| Guides | Deployment, troubleshooting, runbooks | [`docs/guides/`](docs/guides/deployment.md) |
+| Reference | API, configuration, infrastructure | [`docs/reference/`](docs/reference/api.md) |
+| Explanation | Architecture, decisions (ADRs) | [`docs/explanation/`](docs/explanation/architecture.md) |
+| Operations | Monitoring, incidents, SLAs | [`docs/operations/`](docs/operations/README.md) |
 
-Archivos clave en la raíz:
+Key files:
 
-- [`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)
+- [`AGENTS.md`](AGENTS.md) — Operational protocol for AI agents
+- [`CHANGELOG.md`](CHANGELOG.md) — Project changelog
+- [`docs/CONTEXT.md`](docs/CONTEXT.md) — Domain vocabulary and glossary
+- [`docs/DESIGN.md`](docs/DESIGN.md) — Design system tokens and components
 
 ---
 
-## 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).
+## 🏗 Architecture
 
-Resumen rápido:
+> See [`docs/explanation/architecture.md`](docs/explanation/architecture.md) for the full picture.
 
 ```
-[DIAGRAMA SIMPLIFICADO DE LA ARQUITECTURA]
-
-Cliente (Browser)
-  ↓
+[Client / Browser]
+       ↓
 [Frontend Framework]
-  ↓
+       ↓
 [API / Backend]
-  ↓
-[Base de datos]
+       ↓
+[Database]
 ```
 
-Las decisiones de arquitectura se documentan como ADRs en [`docs/adr/`](docs/adr/TEMPLATE.md).
+Architecture decisions are documented as ADRs in [`docs/adr/`](docs/adr/TEMPLATE.md).
 
 ---
 
-## Stack
+## 🛠 Stack
+
+| Layer | Technology | Version |
+|-------|-----------|---------|
+| Language | — | — |
+| Frontend | — | — |
+| Backend | — | — |
+| Database | — | — |
+| CI/CD | — | — |
+| Hosting | — | — |
+
+---
 
-| 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] |
+## 📁 Project Structure
+
+```
+{{PROJECT_NAME}}/
+├── docs/                  # Documentation (Diátaxis framework)
+├── src/                   # Application source code
+├── tests/                 # Test suites
+├── AGENTS.md              # AI agent protocol
+├── CHANGELOG.md           # Changelog
+└── README.md              # This file
+```
 
 ---
 
-## Contribuir
+## 🤝 Contributing
 
-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.
+1. Read [`docs/dev-workflow.md`](docs/dev-workflow.md) for the internal workflow.
+2. Read [`AGENTS.md`](AGENTS.md) if you work with AI agents.
+3. Read [`docs/tutorials/first-task.md`](docs/tutorials/first-task.md) for your first contribution.
 
 ---
 
-## Licencia
+## 📄 License
 
-[TIPO DE LICENCIA — Ejemplo: Privada. Todos los derechos reservados.]
+[MIT](LICENSE) © {{PROJECT_NAME}} contributors

package/templates/base/docs/CONTEXT.md

@@ -1,111 +1,111 @@
----
-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.
+---
+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.