npm - @damenor/agent-docs - Versions diffs - 0.1.1 → 0.4.0 - Mend

@damenor/agent-docs 0.1.1 → 0.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (41) hide show

package/templates/modules/agents/.agents/skills/doc-maintain/SKILL.md CHANGED Viewed

@@ -1,345 +1,355 @@
 ---
 name: doc-maintain
 description: >
-  Mantiene la documentación sincronizada con los cambios en el código.
-  Se ejecuta DESPUÉS de cada tarea que modifica código, usando la tabla de
-  triggers para determinar qué documentación actualizar. Sigue el protocolo
-  post-tarea de AGENTS.md.
-  TRIGGER: Cuando el usuario dice "sincronizar docs", "actualizar docs post-cambio",
-  "post-feature", "post-release", "post-incident", o automáticamente después de
-  cualquier tarea que cambie código.
+  Keeps documentation synchronized with code changes.
+  Runs AFTER each task that modifies code, using the trigger
+  table to determine which documentation to update. Follows the
+  post-task protocol from AGENTS.md.
+  TRIGGER: When the user says "sync docs", "update docs post-change",
+  "post-feature", "post-release", "post-incident", or automatically after
+  any task that changes code.
 license: Apache-2.0
 metadata:
   author: damenordev
-  version: "1.0"
+  version: '1.0'
 ---
 # doc-maintain
-## Cuándo Usar
+## When to Use
-- **Post-feature**: Después de implementar una feature nueva
-- **Post-release**: Después de hacer un release a producción
-- **Post-incident**: Después de resolver un incidente en producción
-- **Post-refactor**: Después de refactorizar código
-- **Post-hire**: Cuando un nuevo dev revisa la documentación
-- **Post-design-change**: Después de cambios en estilos/UI
-- **Post-API-change**: Después de agregar/modificar/eliminar endpoints
-- **Post-config-change**: Después de cambiar configuración
+- **Post-feature**: After implementing a new feature
+- **Post-release**: After making a release to production
+- **Post-incident**: After resolving a production incident
+- **Post-refactor**: After refactoring code
+- **Post-hire**: When a new dev reviews the documentation
+- **Post-design-change**: After changes to styles/UI
+- **Post-API-change**: After adding/modifying/removing endpoints
+- **Post-config-change**: After changing configuration
-## Patrones Críticos
+## Critical Patterns
-### REGLA #1: Esta skill se ejecuta DESPUÉS de cada tarea que cambia código
+### RULE #1: This skill runs AFTER every task that changes code
 ```
-Código cambió → doc-maintain se ejecuta
+Code changed → doc-maintain runs
 ```
-No es opcional. No es "cuando haya tiempo". Es parte del Definition of Done.
+It is not optional. It is not "when there's time". It is part of the Definition of Done.
-### REGLA #2: Verificar qué cambió y actualizar docs correspondientes
+### RULE #2: Verify what changed and update corresponding docs
 ```
-1. Identificar qué archivos cambiaron (git diff, lista de cambios)
-2. Mapear cambios a documentación afectada (ver tabla de triggers)
-3. Actualizar cada archivo de doc afectado
-4. Verificar consistencia
+1. Identify which files changed (git diff, change list)
+2. Map changes to affected documentation (see trigger table)
+3. Update each affected doc file
+4. Verify consistency
 ```
-### REGLA #3: NUNCA saltar actualización de docs
+### RULE #3: NEVER skip doc updates
 ```
-Código cambia = Documentación cambia
+Code changes = Documentation changes
 ```
-Si no hay tiempo para actualizar docs, no hay tiempo para hacer el cambio de código.
+If there's no time to update docs, there's no time to make the code change.
-### REGLA #4: Seguir el protocolo post-tarea de AGENTS.md
+### RULE #4: Follow the post-task protocol from AGENTS.md
-Ejecutar el **árbol post-tarea** definido en `AGENTS.md` § DESPUÉS de cada tarea. Ese árbol es la fuente de verdad de qué documentación actualizar según qué cambió.
+Execute the **post-task tree** defined in `AGENTS.md` § AFTER each task. That tree is the source of truth for which documentation to update based on what changed.
-### REGLA #5: Si no se sabe qué actualizar, ejecutar doc-review primero
+### RULE #5: If unsure what to update, run doc-review first
 ```
-¿No está claro qué docs se ven afectadas?
-→ Ejecutar skill doc-review
-→ Identificar gaps
-→ Actualizar según el reporte
+Not clear which docs are affected?
+→ Run doc-review skill
+→ Identify gaps
+→ Update based on the report
 ```
-## Tabla de Triggers y Acciones
+## Trigger and Action Table
 ### Post-feature
-**Qué detectar**: Se agregó una feature nueva (nuevo módulo, nueva funcionalidad, nuevo endpoint)
+**What to detect**: A new feature was added (new module, new functionality, new endpoint)
-**Docs a actualizar**:
+**Docs to update**:
-| Documento | Cuándo | Prioridad | Skill |
-|-----------|--------|-----------|-------|
-| `docs/CONTEXT.md` | Si hay términos nuevos | Crítica | doc-write |
-| `docs/README.md` | Si se crearon/eliminaron archivos de doc | Crítica | doc-write |
-| `docs/adr/` | Si se tomó una decisión arquitectónica | Alta | doc-write |
-| `how-to/` | Si hay un problema repetible que la feature resuelve | Media | doc-write |
-| `reference/` | Si se agregaron endpoints/funciones/props | Alta | doc-write |
-| `tutorials/` | Si la feature cambia el onboarding | Baja | doc-write |
-| `CHANGELOG.md` | Si la feature va a salir en un release | Alta | doc-write |
+| Document          | When                                                | Priority | Skill     |
+| ----------------- | --------------------------------------------------- | -------- | --------- |
+| `docs/CONTEXT.md` | If there are new terms                              | Critical | doc-write |
+| `docs/README.md`  | If doc files were created/removed                   | Critical | doc-write |
+| `docs/adr/`       | If an architectural decision was made               | High     | doc-write |
+| `how-to/`         | If there is a repeatable problem the feature solves | Medium   | doc-write |
+| `reference/`      | If endpoints/functions/props were added             | High     | doc-write |
+| `tutorials/`      | If the feature changes onboarding                   | Low      | doc-write |
+| `CHANGELOG.md`    | If the feature will be in a release                 | High     | doc-write |
 ### Post-release
-**Qué detectar**: Se hizo un deploy a producción, se creó un tag de versión
+**What to detect**: A deploy to production was made, a version tag was created
-**Docs a actualizar**:
+**Docs to update**:
-| Documento | Cuándo | Prioridad | Skill |
-|-----------|--------|-----------|-------|
-| `CHANGELOG.md` | Siempre | Crítica | doc-write |
-| `docs/guides/deployment.md` | Si cambió el proceso de deploy | Alta | doc-write |
-| `docs/README.md` | Si cambió la estructura de docs | Media | doc-write |
-| `README.md` | Si hay cambios visibles al usuario | Alta | doc-write |
+| Document                    | When                              | Priority | Skill     |
+| --------------------------- | --------------------------------- | -------- | --------- |
+| `CHANGELOG.md`              | Always                            | Critical | doc-write |
+| `docs/guides/deployment.md` | If the deploy process changed     | High     | doc-write |
+| `docs/README.md`            | If the doc structure changed      | Medium   | doc-write |
+| `README.md`                 | If there are user-visible changes | High     | doc-write |
+**CHANGELOG entry**:
-**Entrada de CHANGELOG**:
 ```markdown
 ## [X.Y.Z] - YYYY-MM-DD
 ### Added
-- Descripción de feature nueva
+- Description of new feature
 ### Changed
-- Descripción de cambio
+- Description of change
 ### Fixed
-- Descripción de fix
+- Description of fix
 ### Breaking
-- ⚠️ Descripción de breaking change
+- ⚠️ Description of breaking change
 ```
 ### Post-incident
-**Qué detectar**: Se resolvió un incidente en producción (outage, bug crítico, data loss)
+**What to detect**: A production incident was resolved (outage, critical bug, data loss)
-**Docs a actualizar**:
+**Docs to update**:
-| Documento | Cuándo | Prioridad | Skill |
-|-----------|--------|-----------|-------|
-| `operations/post-mortems/YYYY-MM-DD-titulo.md` | Siempre | Crítica | doc-write |
-| `operations/runbooks/` | Si hay pasos de resolución que repetir | Alta | doc-write |
-| `docs/CONTEXT.md` | Si se descubrieron términos del dominio | Media | doc-write |
-| `reference/configuration.md` | Si se cambiaron configs durante el incidente | Alta | doc-write |
-| `how-to/troubleshooting.md` | Si el fix es aplicable a futuro | Alta | doc-write |
+| Document                                      | When                                        | Priority | Skill     |
+| --------------------------------------------- | ------------------------------------------- | -------- | --------- |
+| `operations/post-mortems/YYYY-MM-DD-title.md` | Always                                      | Critical | doc-write |
+| `operations/runbooks/`                        | If there are resolution steps to repeat     | High     | doc-write |
+| `docs/CONTEXT.md`                             | If domain terms were discovered             | Medium   | doc-write |
+| `reference/configuration.md`                  | If configs were changed during the incident | High     | doc-write |
+| `how-to/troubleshooting.md`                   | If the fix is applicable in the future      | High     | doc-write |
+**Post-mortem format**:
-**Formato de post-mortem**:
 ```markdown
 ---
-created: "YYYY-MM-DD"
+created: 'YYYY-MM-DD'
 status: active
 type: explanation
 tags: [post-mortem, incident, sev-N]
 ---
-# Post-mortem: [Título del incidente]
+# Post-mortem: [Incident title]
+**Date**: YYYY-MM-DD
+**Severity**: SEV-N
+**Duration**: X hours/minutes
+**Impact**: Description of user impact
+## Timeline
+- HH:MM — Detection
+- HH:MM — Diagnosis
+- HH:MM — Mitigation
+- HH:MM — Resolution
+## Root cause
-**Fecha**: YYYY-MM-DD
-**Severidad**: SEV-N
-**Duración**: X horas/minutos
-**Impacto**: Descripción del impacto en usuarios
+[Description]
-## Línea de tiempo
-- HH:MM — Detección
-- HH:MM — Diagnóstico
-- HH:MM — Mitigación
-- HH:MM — Resolución
+## Preventive actions
-## Causa raíz
-[Descripción]
+- [ ] [Action 1] — Responsible — Deadline
+- [ ] [Action 2] — Responsible — Deadline
-## Acciones preventivas
-- [ ] [Acción 1] — Responsable — Fecha límite
-- [ ] [Acción 2] — Responsable — Fecha límite
+## Lessons learned
-## Lecciones aprendidas
-[Qué aprendimos]
+[What we learned]
 ```
 ### Post-refactor
-**Qué detectar**: Se refactorizó código (renombrar, mover, cambiar patrones)
+**What to detect**: Code was refactored (renamed, moved, changed patterns)
-**Docs a actualizar**:
+**Docs to update**:
-| Documento | Cuándo | Prioridad | Skill |
-|-----------|--------|-----------|-------|
-| `docs/adr/` | Si el refactor implica un cambio de patrón | Alta | doc-write |
-| `docs/explanation/architecture.md` | Si cambió la arquitectura | Alta | doc-write |
-| `docs/CONTEXT.md` | Si cambiaron nombres/términos | Crítica | doc-write |
-| `docs/README.md` | Si se movieron archivos | Media | doc-write |
-| ADRs existentes | Verificar que sigan siendo válidos | Alta | doc-write |
+| Document                           | When                                     | Priority | Skill     |
+| ---------------------------------- | ---------------------------------------- | -------- | --------- |
+| `docs/adr/`                        | If the refactor implies a pattern change | High     | doc-write |
+| `docs/explanation/architecture.md` | If the architecture changed              | High     | doc-write |
+| `docs/CONTEXT.md`                  | If names/terms changed                   | Critical | doc-write |
+| `docs/README.md`                   | If files were moved                      | Medium   | doc-write |
+| Existing ADRs                      | Verify they are still valid              | High     | doc-write |
 ### Post-hire
-**Qué detectar**: Un nuevo dev se unió al equipo y revisa la documentación
+**What to detect**: A new dev joined the team and reviews the documentation
-**Docs a actualizar**:
+**Docs to update**:
-| Documento | Cuándo | Prioridad | Skill |
-|-----------|--------|-----------|-------|
-| `tutorials/quick-start.md` | Si el nuevo dev no pudo seguir el tutorial | Crítica | doc-write |
-| `docs/CONTEXT.md` | Si el nuevo dev encontró términos confusos | Alta | doc-write |
-| Cualquier doc | Si el nuevo dev encontró info incorrecta | Alta | doc-write |
+| Document                   | When                                        | Priority | Skill     |
+| -------------------------- | ------------------------------------------- | -------- | --------- |
+| `tutorials/quick-start.md` | If the new dev couldn't follow the tutorial | Critical | doc-write |
+| `docs/CONTEXT.md`          | If the new dev found confusing terms        | High     | doc-write |
+| Any doc                    | If the new dev found incorrect info         | High     | doc-write |
 ### Post-design-change
-**Qué detectar**: Se cambiaron estilos, tokens de diseño, o componentes UI
+**What to detect**: Styles, design tokens, or UI components were changed
-**Docs a actualizar**:
+**Docs to update**:
-| Documento | Cuándo | Prioridad | Skill |
-|-----------|--------|-----------|-------|
-| `DESIGN.md` | Siempre | Crítica | doc-design |
-| `docs/CONTEXT.md` | Si hay términos de diseño nuevos | Media | doc-write |
+| Document          | When                          | Priority | Skill      |
+| ----------------- | ----------------------------- | -------- | ---------- |
+| `DESIGN.md`       | Always                        | Critical | doc-design |
+| `docs/CONTEXT.md` | If there are new design terms | Medium   | doc-write  |
-**Usar skill `doc-design`** para re-extraer tokens y actualizar DESIGN.md.
+**Use skill `doc-design`** to re-extract tokens and update DESIGN.md.
 ### Post-API-change
-**Qué detectar**: Se agregaron, modificaron o eliminaron endpoints
+**What to detect**: Endpoints were added, modified, or removed
-**Docs a actualizar**:
+**Docs to update**:
-| Documento | Cuándo | Prioridad | Skill |
-|-----------|--------|-----------|-------|
-| `reference/api.md` | Siempre | Crítica | doc-write |
-| `CHANGELOG.md` | Si hay breaking changes | Crítica | doc-write |
-| `docs/adr/` | Si se cambió la estructura de la API | Alta | doc-write |
-| `how-to/` | Si hay nuevos flujos de uso | Media | doc-write |
+| Document           | When                          | Priority | Skill     |
+| ------------------ | ----------------------------- | -------- | --------- |
+| `reference/api.md` | Always                        | Critical | doc-write |
+| `CHANGELOG.md`     | If there are breaking changes | Critical | doc-write |
+| `docs/adr/`        | If the API structure changed  | High     | doc-write |
+| `how-to/`          | If there are new usage flows  | Medium   | doc-write |
 ### Post-config-change
-**Qué detectar**: Se cambiaron variables de entorno, configuraciones, o infraestructura
+**What to detect**: Environment variables, configurations, or infrastructure were changed
-**Docs a actualizar**:
+**Docs to update**:
-| Documento | Cuándo | Prioridad | Skill |
-|-----------|--------|-----------|-------|
-| `reference/configuration.md` | Siempre | Crítica | doc-write |
-| `docs/guides/deployment.md` | Si afecta el deploy | Alta | doc-write |
-| `docs/adr/` | Si es un cambio de infraestructura significativo | Alta | doc-write |
-| `.env.example` | Si se agregaron variables | Alta | directo |
+| Document                     | When                                         | Priority | Skill     |
+| ---------------------------- | -------------------------------------------- | -------- | --------- |
+| `reference/configuration.md` | Always                                       | Critical | doc-write |
+| `docs/guides/deployment.md`  | If it affects deploy                         | High     | doc-write |
+| `docs/adr/`                  | If it is a significant infrastructure change | High     | doc-write |
+| `.env.example`               | If variables were added                      | High     | direct    |
-## Flujo del Proceso
+## Process Flow
-### Paso 1: Identificar qué cambió
+### Step 1: Identify what changed
 ```bash
-# Opción A: Git diff
+# Option A: Git diff
 git diff --name-only HEAD~1 HEAD
 git diff --name-only --staged
-# Opción B: Lista manual de archivos cambiados
-[lista proporcionada por el agente/humano]
+# Option B: Manual list of changed files
+[list provided by agent/human]
 ```
-### Paso 2: Mapear cambios a docs afectadas
+### Step 2: Map changes to affected docs
 ```
-Para cada archivo cambiado:
-├── ¿Es código fuente? → Verificar reference/, CONTEXT.md
-├── ¿Es estilo/CSS? → Verificar DESIGN.md
-├── ¿Es configuración? → Verificar reference/configuration.md
-├── ¿Es un módulo nuevo? → Verificar CONTEXT.md, docs/README.md
-├── ¿Es un fix? → Verificar CHANGELOG.md, troubleshooting
-├── ¿Es infraestructura? → Verificar deployment.md, ADRs
-└── ¿Es un test? → Generalmente no requiere doc update
+For each changed file:
+├── Is it source code? → Check reference/, CONTEXT.md
+├── Is it styles/CSS? → Check DESIGN.md
+├── Is it configuration? → Check reference/configuration.md
+├── Is it a new module? → Check CONTEXT.md, docs/README.md
+├── Is it a fix? → Check CHANGELOG.md, troubleshooting
+├── Is it infrastructure? → Check deployment.md, ADRs
+└── Is it a test? → Generally no doc update needed
 ```
-### Paso 3: Actualizar cada doc afectada
+### Step 3: Update each affected doc
 ```
-1. Abrir el archivo de doc afectado
-2. Identificar la sección que necesita cambio
-3. Hacer el cambio manteniendo el formato existente
-4. Verificar que el cambio es consistente con el resto del archivo
+1. Open the affected doc file
+2. Identify the section that needs changing
+3. Make the change maintaining the existing format
+4. Verify the change is consistent with the rest of the file
 ```
-### Paso 4: Verificar consistencia
+### Step 4: Verify consistency
 ```
-1. CONTEXT.md: ¿Los términos nuevos están? ¿Los eliminados se marcaron?
-2. docs/README.md: ¿El mapa refleja los archivos actuales?
-3. ADRs: ¿Los cambios invalidan algún ADR existente?
-4. DESIGN.md: ¿Los tokens siguen coincidiendo? (si cambiaron estilos)
-5. reference/api.md: ¿Los endpoints documentados coinciden con el código?
+1. CONTEXT.md: Are the new terms there? Are removed ones marked?
+2. docs/README.md: Does the map reflect current files?
+3. ADRs: Do the changes invalidate any existing ADR?
+4. DESIGN.md: Do tokens still match? (if styles changed)
+5. reference/api.md: Do documented endpoints match the code?
 ```
-### Paso 5: Reportar qué se actualizó
+### Step 5: Report what was updated
 ```
-✅ Documentación actualizada:
-  - docs/CONTEXT.md: Agregados 2 términos (UserService, RateLimit)
-  - docs/README.md: Agregado how-to/rate-limiting.md al mapa
-  - reference/api.md: Actualizado endpoint /api/users con nuevo campo
-ℹ️ Sin cambios necesarios:
-  - CHANGELOG.md: Feature aún no es release
-  - DESIGN.md: No hubo cambios de estilos
+✅ Documentation updated:
+  - docs/CONTEXT.md: Added 2 terms (UserService, RateLimit)
+  - docs/README.md: Added how-to/rate-limiting.md to map
+  - reference/api.md: Updated endpoint /api/users with new field
+ℹ️ No changes needed:
+  - CHANGELOG.md: Feature not yet released
+  - DESIGN.md: No style changes
 ```
-## Actualización por Lotes
+## Batch Updates
-Cuando múltiples cambios ocurren juntos (ej: fin de sprint):
+When multiple changes occur together (e.g., end of sprint):
 ```
-1. Listar TODOS los cambios desde la última actualización
-2. Agrupar por tipo de trigger (feature, refactor, fix, etc.)
-3. Actualizar cada doc UNA VEZ con todos los cambios acumulados
-4. Ejecutar doc-review al final para verificar consistencia
+1. List ALL changes since the last update
+2. Group by trigger type (feature, refactor, fix, etc.)
+3. Update each doc ONCE with all accumulated changes
+4. Run doc-review at the end to verify consistency
 ```
-### Ejemplo: Fin de sprint
+### Example: End of sprint
 ```
-Cambios del sprint:
-- 3 features nuevas
-- 1 refactor de auth
+Sprint changes:
+- 3 new features
+- 1 auth refactor
 - 2 bug fixes
-- 1 cambio de configuración
-Docs a actualizar:
-1. CHANGELOG.md → Entrada completa del sprint
-2. CONTEXT.md → Términos de las 3 features + auth refactor
-3. reference/api.md → Nuevos endpoints
-4. docs/adr/ → ADR del refactor de auth (si aplica)
-5. reference/configuration.md → Config cambiada
-6. docs/README.md → Si se agregaron/eliminaron docs
+- 1 configuration change
+Docs to update:
+1. CHANGELOG.md → Complete sprint entry
+2. CONTEXT.md → Terms from 3 features + auth refactor
+3. reference/api.md → New endpoints
+4. docs/adr/ → Auth refactor ADR (if applicable)
+5. reference/configuration.md → Changed config
+6. docs/README.md → If docs were added/removed
 ```
-## Comandos
+## Commands
-### Identificar cambios
+### Identify changes
 ```bash
-# Archivos modificados en el último commit
+# Files modified in the last commit
 git diff --name-only HEAD~1
-# Archivos modificados (staged + unstaged)
+# Modified files (staged + unstaged)
 git diff --name-only; git diff --name-only --staged
-# Cambios en un rango de commits
+# Changes in a range of commits
 git diff --name-only commit1..commit2
 ```
-### Verificar consistencia post-actualización
+### Post-update consistency verification
 ```
-1. ¿CONTEXT.md tiene todos los términos nuevos del código?
-2. ¿docs/README.md lista todos los archivos de doc existentes?
-3. ¿ADRs son consistentes con la implementación actual?
-4. ¿DESIGN.md coincide con estilos actuales?
-5. ¿reference/api.md refleja endpoints actuales?
+1. Does CONTEXT.md have all the new terms from code?
+2. Does docs/README.md list all existing doc files?
+3. Are ADRs consistent with the current implementation?
+4. Does DESIGN.md match current styles?
+5. Does reference/api.md reflect current endpoints?
 ```
-## Recursos
+## Resources
-- [Triggers Reference](references/triggers.md) — Tabla completa de eventos → docs a actualizar con ejemplos
-- Skills relacionados: `doc-write` (escribir/actualizar docs), `doc-review` (auditar después de actualizar), `doc-design` (actualizar DESIGN.md), `doc-scaffold` (si falta estructura)
+- [Triggers Reference](references/triggers.md) — Complete table of events → docs to update with examples
+- Related skills: `doc-write` (write/update docs), `doc-review` (audit after updating), `doc-design` (update DESIGN.md), `doc-scaffold` (if structure is missing)