@damenor/agent-docs 0.1.2 → 0.4.1

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

@@ -1,149 +1,149 @@
 ---
-created: "2024-01-15"
+created: '2024-01-15'
 status: active
 type: reference
-tags: [diataxis, framework, documentacion, referencia]
+tags: [diataxis, framework, documentation, reference]
 ---
 
-# Diátaxis — Referencia Rápida
+# Diátaxis — Quick Reference
 
-## Los 4 Cuadrantes
+## The 4 Quadrants
 
-Diátaxis clasifica la documentación en 4 tipos según dos ejes:
+Diátaxis classifies documentation into 4 types along two axes:
 
-- **Eje horizontal**: Estudio (aprender) vs Trabajo (aplicar)
-- **Eje vertical**: Práctico (acción) vs Teórico (conocimiento)
+- **Horizontal axis**: Study (learn) vs Work (apply)
+- **Vertical axis**: Practical (action) vs Theoretical (knowledge)
 
 ```
-                    │ Práctico (acción)
+                    │ Practical (action)
                     │
          Tutorial   │   How-to
-      (Aprender     │  (Aplicar
-       haciendo)    │   soluciones)
+      (Learning     │  (Applying
+       by doing)    │   solutions)
                     │
 ────────────────────┼────────────────────
                     │
-      Explicación   │  Referencia
-     (Entender el   │ (Buscar
-       porqué)      │  información)
+      Explanation   │  Reference
+     (Understanding │ (Looking up
+        why)        │  information)
                     │
-                    │ Teórico (conocimiento)
+                    │ Theoretical (knowledge)
 ```
 
 ### 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
+- **Orientation**: Learning
+- **Purpose**: Guide the beginner step by step to acquire a skill
+- **Tone**: Didactic, patient, encouraging
+- **Example**: "Your first Express.js API" — the user learns while building
 
-### How-to (Guía práctica)
+### How-to
 
-- **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
+- **Orientation**: Practice
+- **Purpose**: Solve a specific concrete problem
+- **Tone**: Direct, assumes prior knowledge
+- **Example**: "How to configure JWT authentication" — the user already knows Express, needs JWT
 
-### Referencia
+### Reference
 
-- **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
+- **Orientation**: Information
+- **Purpose**: Describe the machinery in a factual and complete way
+- **Tone**: Neutral, structured, no narrative
+- **Example**: "API endpoints" — tables with methods, parameters, responses
 
-### Explicación
+### Explanation
 
-- **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
+- **Orientation**: Understanding
+- **Purpose**: Clarify why, provide context, connect concepts
+- **Tone**: Discursive, analytical
+- **Example**: "Why we chose event-sourcing" — historical context, alternatives, trade-offs
 
-## Cuándo Usar Cada Tipo
+## When to Use Each Type
 
-| 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/` |
+| Situation                            | Type        | Folder         |
+| ------------------------------------ | ----------- | -------------- |
+| New user wants to get started        | Tutorial    | `tutorials/`   |
+| User has a specific problem          | How-to      | `how-to/`      |
+| User needs to look up a detail       | Reference   | `reference/`   |
+| User asks "why?"                     | Explanation | `explanation/` |
+| New dev onboarding                   | Tutorial    | `tutorials/`   |
+| Configure something already known    | How-to      | `how-to/`      |
+| Look up function parameters          | Reference   | `reference/`   |
+| Understand an architectural decision | Explanation | `explanation/` |
 
-## Árbol de Decisión
+## Decision Tree
 
 ```
-¿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
+Does the reader need to learn something new from scratch?
+├── YES → Is it best learned by doing?
+│   ├── YES → TUTORIAL → tutorials/
+│   └── NO → EXPLANATION → explanation/
+└── NO → Do they need to solve a practical problem?
+    ├── YES → Do they need concrete steps?
+    │   ├── YES → HOW-TO → how-to/
+    │   └── NO → EXPLANATION → explanation/
+    └── NO → Do they need specific information?
+        ├── YES → REFERENCE → reference/
+        └── NO → Re-evaluate the need
 ```
 
-## Ejemplos por Tipo en Proyectos Web
+## Examples by Type in Web Projects
 
 ### 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 |
+| Title                | What it teaches                               |
+| -------------------- | --------------------------------------------- |
+| `quick-start.md`     | Create the first endpoint, launch the project |
+| `first-component.md` | Create a React/Vue component from scratch     |
+| `database-setup.md`  | Set up the database for the first time        |
+| `deploy-guide.md`    | Make the first deployment step by step        |
 
 ### 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.
+| Title                  | What it solves                        |
+| ---------------------- | ------------------------------------- |
+| `add-auth.md`          | Add authentication to an existing API |
+| `custom-middleware.md` | Create custom middleware              |
+| `migrate-database.md`  | Run a database migration              |
+| `configure-ci.md`      | Set up CI/CD pipeline                 |
+| `add-new-endpoint.md`  | Add a new REST endpoint               |
+| `debug-connection.md`  | Diagnose connection issues            |
+
+### Reference (reference/)
+
+| Title              | What it documents                              |
+| ------------------ | ---------------------------------------------- |
+| `api.md`           | All endpoints: method, route, params, response |
+| `configuration.md` | All configuration variables and their values   |
+| `cli.md`           | All CLI commands with flags and examples       |
+| `events.md`        | All system events with payload                 |
+| `errors.md`        | Error codes with meaning and resolution        |
+
+### Explanation (explanation/)
+
+| Title                       | What it explains                     |
+| --------------------------- | ------------------------------------ |
+| `architecture.md`           | Architecture overview and its layers |
+| `authentication-flow.md`    | How auth flow works end-to-end       |
+| `database-design.md`        | Why the current schema was chosen    |
+| `caching-strategy.md`       | Caching strategy and its trade-offs  |
+| `adr/001-event-sourcing.md` | Architectural decision with context  |
+
+## Quick Table: User Goal → Type → Location
+
+| User goal                                 | Doc type    | Location          |
+| ----------------------------------------- | ----------- | ----------------- |
+| "I want to learn how to use this"         | Tutorial    | `tutorials/`      |
+| "I want to do X specific thing"           | How-to      | `how-to/`         |
+| "I need to look up something"             | Reference   | `reference/`      |
+| "I want to understand why it's like this" | Explanation | `explanation/`    |
+| "How was the architecture decided?"       | ADR         | `docs/adr/`       |
+| "What does this term mean?"               | CONTEXT     | `docs/CONTEXT.md` |
+| "What does the system look like?"         | Design      | `DESIGN.md`       |
+| "What changed in each version?"           | Changelog   | `CHANGELOG.md`    |
+
+## Golden Rule
+
+**One document = One purpose = One Diátaxis type.**
+
+If a document tries to be both a tutorial AND a reference at the same time, neither works well. Separate to improve.

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

@@ -3,7 +3,8 @@ name: doc-write
 description: >
   Writes documentation following Diátaxis + ADR + CONTEXT conventions.
   Classifies content by type before writing, generates ADRs when applicable,
-  and keeps CONTEXT.md updated. All content in English with technical
+  and keeps CONTEXT.md updated. All content in the project's documentation language
+  (as defined in AGENTS.md § Stack and Conventions), with technical
   terms kept in English.
   TRIGGER: When the user says "write doc", "document X", "create ADR",
   "update CONTEXT", "new documentation", or any documentation file
@@ -11,7 +12,7 @@ description: >
 license: Apache-2.0
 metadata:
   author: damenordev
-  version: "1.0"
+  version: '1.0'
 ---
 
 # doc-write
@@ -65,6 +66,7 @@ See [ADR Format](references/adr-format.md) for full details.
 ### RULE #4: Update docs/README.md when adding files
 
 The documentation map must always reflect reality:
+
 - Add new entries when files are created
 - Mark entries of deleted files as obsolete
 - Update descriptions if content changed significantly
@@ -73,8 +75,8 @@ The documentation map must always reflect reality:
 
 ```yaml
 ---
-created: "2026-05-07"
-updated: "2026-05-07"
+created: '2026-05-07'
+updated: '2026-05-07'
 status: active | draft | stub | deprecated
 type: tutorial | how-to | reference | explanation | adr | design | product
 tags: [tag1, tag2, tag3]
@@ -86,10 +88,11 @@ No `owner`. Always include `updated` when modifying.
 ### RULE #6: DUAL audience — humans AND AI agents
 
 Write for:
+
 - **Humans**: Clarity, examples, logical flow
 - **AI agents**: Consistent structure, terms defined in CONTEXT.md, clear cross-references
 
-### RULE #7: Content in English
+### RULE #7: Content in the project's documentation language
 
 ```
 ✅ "To configure the authentication middleware..."
@@ -112,9 +115,10 @@ Write for:
 **Orientation**: Learning — the user learns by doing
 
 **Structure**:
+
 ```markdown
 ---
-created: "..."
+created: '...'
 status: active
 type: tutorial
 tags: [...]
@@ -123,20 +127,27 @@ tags: [...]
 # [Descriptive title of the learning goal]
 
 ## What you will build
+
 [Description of the end result — 2-3 lines]
 
 ## Prerequisites
+
 [Concrete list of what is needed before starting]
 
 ## Step 1: [Concrete action]
+
 [Instructions + code]
+
 ### ✅ Verification
+
 [How to confirm the step worked]
 
 ## Step 2: [Concrete action]
+
 ...
 
 ## Summary
+
 [What was learned, what's next]
 ```
 
@@ -151,9 +162,10 @@ tags: [...]
 **Orientation**: Solve a problem — the user already has prior knowledge
 
 **Structure**:
+
 ```markdown
 ---
-created: "..."
+created: '...'
 status: active
 type: how-to
 tags: [...]
@@ -162,14 +174,17 @@ tags: [...]
 # How to [solve specific problem]
 
 ## When to use this
+
 [1-2 lines describing the scenario]
 
 ## Steps
+
 1. [Direct action with code]
 2. [Direct action with code]
-...
+   ...
 
 ## Expected result
+
 [What should be seen/working at the end]
 ```
 
@@ -182,9 +197,10 @@ tags: [...]
 **Orientation**: Factual information — the user looks up a specific piece of data
 
 **Structure**:
+
 ```markdown
 ---
-created: "..."
+created: '...'
 status: active
 type: reference
 tags: [...]
@@ -195,10 +211,11 @@ tags: [...]
 ## [Main section — endpoints, methods, props, etc.]
 
 | Name | Type | Description | Default |
-|------|------|-------------|---------|
+| ---- | ---- | ----------- | ------- |
 | ...  | ...  | ...         | ...     |
 
 ## Examples
+
 [Minimal code for each main use case]
 ```
 
@@ -213,9 +230,10 @@ tags: [...]
 **Orientation**: Understanding — the user wants to understand the why
 
 **Structure**:
+
 ```markdown
 ---
-created: "..."
+created: '...'
 status: active
 type: explanation
 tags: [...]
@@ -224,15 +242,19 @@ tags: [...]
 # [Topic being explained]
 
 ## Context
+
 [Why this exists, what problem it solves]
 
 ## How it works
+
 [Overview without going into code]
 
 ## Alternatives considered
+
 [What other options existed and why this was chosen]
 
 ## Implications
+
 [What this decision means for the future]
 ```
 
@@ -267,8 +289,8 @@ tags: [...]
 
 ```markdown
 ---
-created: "2026-05-07"
-updated: "2026-05-07"
+created: '2026-05-07'
+updated: '2026-05-07'
 status: proposed | accepted | deprecated | superseded
 type: adr
 tags: [architecture, decision]
@@ -341,10 +363,10 @@ For practical steps, see [[how-to/add-new-endpoint]].
 
 ### Tutorial — Output example
 
-```markdown
+````markdown
 ---
-created: "2026-05-07"
-updated: "2026-05-07"
+created: '2026-05-07'
+updated: '2026-05-07'
 status: active
 type: tutorial
 tags: [auth, jwt, onboarding]
@@ -353,9 +375,11 @@ tags: [auth, jwt, onboarding]
 # Implement JWT Authentication
 
 ## What you will build
+
 A complete login/registration flow with JWT and refresh tokens.
 
 ## Prerequisites
+
 - Project running locally (see [[tutorials/quick-start]])
 - Basic knowledge of HTTP headers
 
@@ -365,20 +389,25 @@ A complete login/registration flow with JWT and refresh tokens.
 npm install jsonwebtoken bcryptjs
 npm install -D @types/jsonwebtoken @types/bcryptjs
 ```
+````
 
 ### ✅ Verification
+
 ```bash
 npm ls jsonwebtoken
 # → jsonwebtoken@9.0.2
 ```
 
 ## Step 2: Create the auth service
+
 ...[steps with real code]
 
 ## Summary
+
 You learned to implement JWT with refresh tokens.
 Next: [[guides/how-to-protect-routes]]
-```
+
+````
 
 ### How-to — Output example
 
@@ -405,7 +434,7 @@ When an approved feature in staging is ready for production.
 
 ## Rollback
 If something fails: Vercel Dashboard → Deployments → "Promote to Production" on the previous deploy
-```
+````
 
 ## Resources