@damenor/agent-docs 0.1.2 → 0.4.1

package/templates/modules/agents/.agents/skills/doc-review/references/health-checklist.md

@@ -1,13 +1,13 @@
 ---
-created: "2024-01-15"
+created: '2024-01-15'
 status: active
 type: reference
-tags: [auditoria, checklist, salud, documentacion]
+tags: [audit, checklist, health, documentation]
 ---
 
-# Checklist de Salud de Documentación
+# Documentation Health Checklist
 
-## Checklist por Tipo de Archivo
+## Checklist by File Type
 
 ### README.md
 
@@ -104,187 +104,190 @@ tags: [auditoria, checklist, salud, documentacion]
 
 ---
 
-## Rúbrica de Puntuación
+## Scoring Rubric
 
-### Completitud (máximo: 30 puntos)
+### Completeness (max: 30 points)
 
-| Criterio | 10 | 5 | 0 |
-|----------|-----|-----|-----|
-| Archivos esenciales | Todos existen | Faltan 1-2 | Faltan 3+ |
-| Secciones con contenido | Todas tienen contenido real | 1-2 secciones vacías | 3+ secciones vacías |
-| Features documentadas | Todas las features públicas | >75% documentadas | <75% documentadas |
+| Criterion             | 10                    | 5                  | 0                 |
+| --------------------- | --------------------- | ------------------ | ----------------- |
+| Essential files       | All exist             | 1-2 missing        | 3+ missing        |
+| Sections with content | All have real content | 1-2 empty sections | 3+ empty sections |
+| Documented features   | All public features   | >75% documented    | <75% documented   |
 
-### Actualidad (máximo: 20 puntos)
+### Timeliness (max: 20 points)
 
-| Criterio | Puntos | Cómo verificar |
-|----------|--------|----------------|
-| Docs reflejan código actual | 0-10 | Comparar con `git log --since="3 months ago"` |
-| CHANGELOG al día | 0-5 | Comparar con git tags |
-| Sin referencias obsoletas | 0-5 | Buscar versiones viejas de librerías |
+| Criterion                 | Points | How to check                                  |
+| ------------------------- | ------ | --------------------------------------------- |
+| Docs reflect current code | 0-10   | Compare with `git log --since="3 months ago"` |
+| CHANGELOG up to date      | 0-5    | Compare with git tags                         |
+| No obsolete references    | 0-5    | Search for old library versions               |
 
-### Consistencia (máximo: 20 puntos)
+### Consistency (max: 20 points)
 
-| Criterio | Puntos | Cómo verificar |
-|----------|--------|----------------|
-| CONTEXT.md coincide con código | 0-5 | Comparar términos definidos vs usados |
-| DESIGN.md coincide con estilos | 0-5 | Comparar tokens vs CSS vars/Tailwind |
-| docs/README.md refleja archivos | 0-5 | Comparar mapa vs filesystem |
-| Formato consistente | 0-5 | Verificar frontmatter, idioma, nomenclatura |
+| Criterion                     | Points | How to check                        |
+| ----------------------------- | ------ | ----------------------------------- |
+| CONTEXT.md matches code       | 0-5    | Compare defined vs used terms       |
+| DESIGN.md matches styles      | 0-5    | Compare tokens vs CSS vars/Tailwind |
+| docs/README.md reflects files | 0-5    | Compare map vs filesystem           |
+| Consistent format             | 0-5    | Check frontmatter, language, naming |
 
-### Cobertura (máximo: 20 puntos)
+### Coverage (max: 20 points)
 
-| Criterio | Puntos | Cómo verificar |
-|----------|--------|----------------|
-| Diátaxis 4 cuadrantes | 0-10 | Al menos un archivo en cada carpeta |
-| API/endpoints documentados | 0-5 | Comparar rutas de código con reference/ |
-| Componentes UI en DESIGN.md | 0-5 | Comparar componentes de código con DESIGN.md |
+| Criterion                  | Points | How to check                           |
+| -------------------------- | ------ | -------------------------------------- |
+| Diátaxis 4 quadrants       | 0-10   | At least one file in each folder       |
+| API/endpoints documented   | 0-5    | Compare code routes with reference/    |
+| UI components in DESIGN.md | 0-5    | Compare code components with DESIGN.md |
 
-### Calidad (máximo: 10 puntos)
+### Quality (max: 10 points)
 
-| Criterio | Puntos | Cómo verificar |
-|----------|--------|----------------|
-| Sin placeholders/TODOs | 0-5 | `rg "TODO|TBD|PENDIENTE|agregar" --type md` |
-| Ejemplos ejecutables | 0-3 | Verificar código en tutoriales/how-tos |
-| Sin duplicación | 0-2 | Buscar contenido idéntico entre archivos |
+| Criterion             | Points | How to check                               |
+| --------------------- | ------ | ------------------------------------------ | --- | --------- | ------------------- |
+| No placeholders/TODOs | 0-5    | `rg "TODO                                  | TBD | PENDIENTE | agregar" --type md` |
+| Executable examples   | 0-3    | Verify code in tutorials/how-tos           |
+| No duplication        | 0-2    | Search for identical content between files |
 
 ---
 
-## Problemas Comunes y Soluciones
+## Common Problems and Solutions
 
-### Problema: Archivo con solo título y frontmatter
+### Problem: File with only title and frontmatter
 
-**Causa**: Se creó como placeholder y nunca se completó
+**Cause**: Created as a placeholder and never completed
 
-**Solución**: Usar `doc-write` para escribir contenido real o eliminar el archivo
+**Solution**: Use `doc-write` to write real content or delete the file
 
-### Problema: CONTEXT.md desactualizado
+### Problem: CONTEXT.md outdated
 
-**Causa**: Se agregaron términos al código sin actualizar CONTEXT
+**Cause**: Terms were added to code without updating CONTEXT
 
-**Solución**: Usar `doc-write` para agregar términos faltantes. Buscar en código: nombres de módulos, clases, interfaces, tipos principales
+**Solution**: Use `doc-write` to add missing terms. Search code for: module names, classes, interfaces, main types
 
-### Problema: DESIGN.md no coincide con CSS
+### Problem: DESIGN.md doesn't match CSS
 
-**Causa**: Se cambiaron estilos sin actualizar DESIGN.md
+**Cause**: Styles were changed without updating DESIGN.md
 
-**Solución**: Usar `doc-design` para re-extraer tokens del código y actualizar
+**Solution**: Use `doc-design` to re-extract tokens from code and update
 
-### Problema: ADRs sin status
+### Problem: ADRs without status
 
-**Causa**: Se crearon como proposed y nunca se actualizó el status
+**Cause**: Created as proposed and status was never updated
 
-**Solución**: Revisar cada ADR y actualizar status según la realidad actual
+**Solution**: Review each ADR and update status according to current reality
 
-### Problema: Wikilinks rotos
+### Problem: Broken wikilinks
 
-**Causa**: Se renombró o eliminó un archivo sin actualizar las referencias
+**Cause**: A file was renamed or deleted without updating references
 
-**Solución**: Buscar todos los `[[enlace]]` y verificar que el archivo existe
+**Solution**: Search all `[[links]]` and verify the file exists
 
-### Problema: How-to que explica conceptos
+### Problem: How-to that explains concepts
 
-**Causa**: Confusión entre how-to y explanation
+**Cause**: Confusion between how-to and explanation
 
-**Solución**: Extraer las explicaciones a explanation/ y dejar solo los pasos en how-to
+**Solution**: Extract explanations to explanation/ and leave only steps in how-to
 
-### Problema: Tutorial sin verificación por paso
+### Problem: Tutorial without per-step verification
 
-**Causa**: Se escribió sin seguir el patrón de tutorial
+**Cause**: Written without following the tutorial pattern
 
-**Solución**: Agregar sección "✅ Verificación" al final de cada paso
+**Solution**: Add "✅ Verification" section at the end of each step
 
-### Problema: Referencia con prosa narrativa
+### Problem: Reference with narrative prose
 
-**Causa**: Se escribió referencia como si fuera tutorial
+**Cause**: Reference written as if it were a tutorial
 
-**Solución**: Convertir prosa a tablas y listas. Mover narrativa a explanation/
+**Solution**: Convert prose to tables and lists. Move narrative to explanation/
 
 ---
 
-## Plantilla de Reporte de Salud
+## Health Report Template
 
 ```markdown
-# 🏥 Reporte de Salud — Documentación
+# 🏥 Health Report — Documentation
 
-**Fecha**: [YYYY-MM-DD]
-**Revisor**: [agente/humano]
-**Proyecto**: [nombre]
+**Date**: [YYYY-MM-DD]
+**Reviewer**: [agent/human]
+**Project**: [name]
 
 ---
 
-## 📊 Puntuación General: [XX]/100 [🟢🟡🟠🔴]
+## 📊 Overall Score: [XX]/100 [🟢🟡🟠🔴]
 
-| Dimensión | Puntos | Máximo | Estado |
-|-----------|--------|--------|--------|
-| Completitud | XX | 30 | 🟢🟡🟠🔴 |
-| Actualidad | XX | 20 | 🟢🟡🟠🔴 |
-| Consistencia | XX | 20 | 🟢🟡🟠🔴 |
-| Cobertura | XX | 20 | 🟢🟡🟠🔴 |
-| Calidad | XX | 10 | 🟢🟡🟠🔴 |
+| Dimension    | Points | Max | Status   |
+| ------------ | ------ | --- | -------- |
+| Completeness | XX     | 30  | 🟢🟡🟠🔴 |
+| Timeliness   | XX     | 20  | 🟢🟡🟠🔴 |
+| Consistency  | XX     | 20  | 🟢🟡🟠🔴 |
+| Coverage     | XX     | 20  | 🟢🟡🟠🔴 |
+| Quality      | XX     | 10  | 🟢🟡🟠🔴 |
 
 ---
 
-## 🔴 Crítico (resolver inmediatamente)
+## 🔴 Critical (resolve immediately)
 
-1. **[problema]** → [archivo afectado] → [acción sugerida]
+1. **[problem]** → [affected file] → [suggested action]
 
-## 🟡 Importante (resolver este sprint)
+## 🟡 Important (resolve this sprint)
 
-1. **[problema]** → [archivo afectado] → [acción sugerida]
+1. **[problem]** → [affected file] → [suggested action]
 
-## 🟢 Mejora (resolver cuando sea posible)
+## 🟢 Improvement (resolve when possible)
 
-1. **[problema]** → [archivo afectado] → [acción sugerida]
+1. **[problem]** → [affected file] → [suggested action]
 
 ---
 
-## 📁 Detalle por Archivo
+## 📁 Detail by File
 
-| Archivo | Estado | Puntuación | Issues |
-|---------|--------|------------|--------|
-| README.md | ✅ | 10/10 | — |
-| docs/CONTEXT.md | ⚠️ | 6/10 | 3 términos faltantes |
-| ... | ... | ... | ... |
+| File            | Status | Score | Issues          |
+| --------------- | ------ | ----- | --------------- |
+| README.md       | ✅     | 10/10 | —               |
+| docs/CONTEXT.md | ⚠️     | 6/10  | 3 missing terms |
+| ...             | ...    | ...   | ...             |
 
 ---
 
-## 📋 Acciones Recomendadas
+## 📋 Recommended Actions
 
-### Prioridad Inmediata
-- [ ] [acción 1] → usar skill `[skill-name]`
-- [ ] [acción 2] → usar skill `[skill-name]`
+### Immediate Priority
 
-### Esta Semana
-- [ ] [acción 3] → usar skill `[skill-name]`
+- [ ] [action 1] → use skill `[skill-name]`
+- [ ] [action 2] → use skill `[skill-name]`
 
-### Este Sprint
-- [ ] [acción 4] → usar skill `[skill-name]`
+### This Week
+
+- [ ] [action 3] → use skill `[skill-name]`
+
+### This Sprint
+
+- [ ] [action 4] → use skill `[skill-name]`
 
 ---
 
-*Próxima revisión sugerida: [YYYY-MM-DD]*
+_Suggested next review: [YYYY-MM-DD]_
 ```
 
 ---
 
-## Cuándo Escalar
+## When to Escalate
 
-### Gaps críticos que bloquean
+### Critical gaps that block
 
-| Gap | Impacto | Acción |
-|-----|---------|--------|
-| Sin tutorial de quick-start | Onboarding bloqueado | Crear con `doc-write` inmediatamente |
-| Sin referencia de API | Integradores bloqueados | Crear con `doc-write` |
-| CHANGELOG vacío | No hay historial de cambios | Crear entradas para cada versión |
-| Sin CONTEXT.md | Términos ambiguos | Crear con `doc-write` |
-| Sin AGENTS.md | Agentes sin protocolo | Crear con `doc-scaffold` |
-| DESIGN.md desincronizado >5 tokens | Inconsistencias visuales | Arreglar con `doc-design` |
+| Gap                          | Impact                  | Action                              |
+| ---------------------------- | ----------------------- | ----------------------------------- |
+| No quick-start tutorial      | Onboarding blocked      | Create with `doc-write` immediately |
+| No API reference             | Integrators blocked     | Create with `doc-write`             |
+| Empty CHANGELOG              | No change history       | Create entries for each version     |
+| No CONTEXT.md                | Ambiguous terms         | Create with `doc-write`             |
+| No AGENTS.md                 | Agents without protocol | Create with `doc-scaffold`          |
+| DESIGN.md desynced >5 tokens | Visual inconsistencies  | Fix with `doc-design`               |
 
-### Gaps importantes que degradan
+### Important gaps that degrade
 
-| Gap | Impacto | Acción |
-|-----|---------|--------|
-| Cuadrante Diátaxis vacío | Cobertura incompleta | Crear contenido con `doc-write` |
-| ADRs sin status | Confusión sobre decisiones | Actualizar status |
-| 3+ TODOs en docs | Contenido incompleto | Completar o eliminar |
-| docs/README.md desactualizado | Mapa incorrecto | Actualizar |
+| Gap                     | Impact                    | Action                          |
+| ----------------------- | ------------------------- | ------------------------------- |
+| Empty Diátaxis quadrant | Incomplete coverage       | Create content with `doc-write` |
+| ADRs without status     | Confusion about decisions | Update status                   |
+| 3+ TODOs in docs        | Incomplete content        | Complete or delete              |
+| docs/README.md outdated | Wrong map                 | Update                          |

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

@@ -9,7 +9,7 @@ description: >
 license: Apache-2.0
 metadata:
   author: damenordev
-  version: "1.0"
+  version: '1.0'
 ---
 
 # doc-scaffold
@@ -45,16 +45,16 @@ Always analyze the project BEFORE generating documentation:
 
 Create ONLY these files with real content:
 
-| File | Purpose | When to create |
-|------|---------|----------------|
-| `README.md` | Project entry point | Always |
-| `CHANGELOG.md` | Version history | Always (with initial entry) |
-| `AGENTS.md` | Protocol for AI agents | Always |
-| `docs/README.md` | Documentation map + growth rules | Always |
-| `docs/CONTEXT.md` | Domain terms found in code | Always |
-| `docs/adr/TEMPLATE.md` | Template for ADRs | Always |
-| `docs/adr/001-*.md` | First ADR if applicable | When there are architectural decisions |
-| `tutorials/quick-start.md` | Quick start tutorial | Always |
+| File                       | Purpose                          | When to create                         |
+| -------------------------- | -------------------------------- | -------------------------------------- |
+| `README.md`                | Project entry point              | Always                                 |
+| `CHANGELOG.md`             | Version history                  | Always (with initial entry)            |
+| `AGENTS.md`                | Protocol for AI agents           | Always                                 |
+| `docs/README.md`           | Documentation map + growth rules | Always                                 |
+| `docs/CONTEXT.md`          | Domain terms found in code       | Always                                 |
+| `docs/adr/TEMPLATE.md`     | Template for ADRs                | Always                                 |
+| `docs/adr/001-*.md`        | First ADR if applicable          | When there are architectural decisions |
+| `tutorials/quick-start.md` | Quick start tutorial             | Always                                 |
 
 ### RULE #4: CONTEXT.md is generated by analyzing code
 
@@ -71,7 +71,7 @@ Every documentation file must include frontmatter:
 
 ```yaml
 ---
-created: "2024-01-15"
+created: '2024-01-15'
 status: active
 type: tutorial | how-to | reference | explanation
 tags: [tag1, tag2]
@@ -114,17 +114,20 @@ Check:
 # AGENTS.md — Documentation Protocol
 
 ## Before starting a task
+
 1. Read docs/CONTEXT.md to understand the domain
 2. Read docs/README.md to navigate the documentation
 3. Review relevant ADRs in docs/adr/
 
 ## After completing a task
+
 1. Update CONTEXT.md if new terms emerged
 2. Update docs/README.md if files were added/removed
 3. Evaluate if an ADR is needed (is it hard to reverse? is it surprising? is there a trade-off?)
 4. Pass the protocol to the subagent if work is delegated
 
 ## When delegating work
+
 1. Include this protocol in the subagent's prompt
 2. Specify which doc files to update
 3. Verify the subagent followed the protocol
@@ -133,6 +136,7 @@ Check:
 ### Step 4: Create docs/README.md
 
 Include:
+
 - Complete map of documentation files (generated, not placeholder)
 - Growth rules: when to add each type of doc
 - Naming conventions
@@ -141,6 +145,7 @@ Include:
 ### Step 5: Create docs/CONTEXT.md
 
 Generate with real domain terms detected in the code:
+
 - Table of terms with definitions
 - Relationships between terms
 - Flagged ambiguous terms
@@ -154,6 +159,7 @@ Generate with real domain terms detected in the code:
 ### Step 7: Create tutorials/quick-start.md
 
 Based on the detected stack:
+
 - Stack-specific prerequisites
 - Real installation steps
 - First runnable example
@@ -162,6 +168,7 @@ Based on the detected stack:
 ### Step 8: Create essential reference files
 
 Only those applicable to the detected stack:
+
 - If there is an API: `reference/api.md`
 - If there is configuration: `reference/configuration.md`
 - If there is a CLI: `reference/cli.md`