@damenor/agent-docs 0.1.1 → 0.4.0

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

@@ -1,228 +1,235 @@
 ---
 name: doc-scaffold
 description: >
-  Inicializa la documentación completa para un proyecto nuevo o existente.
-  Detecta el stack tecnológico, crea la estructura de archivos esenciales y genera
-  documentación inicial con contenido real basado en el análisis del código.
-  TRIGGER: Cuando el usuario dice "inicializar docs", "nuevo proyecto", "scaffold docs",
-  "crear documentación", "setup docs", o se detecta un proyecto sin documentación.
+  Initializes complete documentation for a new or existing project.
+  Detects the tech stack, creates essential file structure, and generates
+  initial documentation with real content based on code analysis.
+  TRIGGER: When the user says "initialize docs", "new project", "scaffold docs",
+  "create documentation", "setup docs", or a project without documentation is detected.
 license: Apache-2.0
 metadata:
   author: damenordev
-  version: "1.0"
+  version: '1.0'
 ---
 
 # doc-scaffold
 
-## Cuándo Usar
+## When to Use
 
-- **Proyecto nuevo**: Se crea un proyecto desde cero y necesita documentación inicial
-- **Proyecto existente sin docs**: Se detecta un proyecto que ya tiene código pero carece de documentación estructurada
-- **Migración de docs**: Se reorganiza documentación existente hacia la estructura Diátaxis + ADR
-- **Post-setup**: Después de inicializar un repositorio, antes de empezar a desarrollar features
+- **New project**: A project is created from scratch and needs initial documentation
+- **Existing project without docs**: A project with code but lacking structured documentation is detected
+- **Docs migration**: Existing documentation is reorganized toward the Diátaxis + ADR structure
+- **Post-setup**: After initializing a repository, before starting to develop features
 
-## Patrones Críticos
+## Critical Patterns
 
-### REGLA #1: NUNCA crear carpetas vacías
+### RULE #1: NEVER create empty folders
 
-Solo se crean archivos con contenido real y verificable. Si no hay contenido para un archivo, no se crea.
+Only create files with real, verifiable content. If there is no content for a file, do not create it.
 
 ```
-❌ MAL: mkdir docs/api/  # carpeta vacía
-✅ BIEN: Crear docs/api/endpoints.md SOLO cuando hay endpoints documentables
+❌ BAD: mkdir docs/api/  # empty folder
+✅ GOOD: Create docs/api/endpoints.md ONLY when there are documentable endpoints
 ```
 
-### REGLA #2: Detectar antes de crear
+### RULE #2: Detect before creating
 
-Siempre analizar el proyecto ANTES de generar documentación:
+Always analyze the project BEFORE generating documentation:
 
-- Detectar lenguaje: `package.json` → Node, `requirements.txt` → Python, `go.mod` → Go, `Cargo.toml` → Rust, `pom.xml` → Java
-- Detectar framework: imports en código principal, dependencias
-- Verificar docs existentes: NO sobreescribir documentación existente sin preguntar
-- Identificar términos del dominio: buscar en código, nombres de módulos, variables clave
+- Detect language: `package.json` → Node, `requirements.txt` → Python, `go.mod` → Go, `Cargo.toml` → Rust, `pom.xml` → Java
+- Detect framework: imports in main code, dependencies
+- Check existing docs: DO NOT overwrite existing documentation without asking
+- Identify domain terms: search in code, module names, key variables
 
-### REGLA #3: Archivos esenciales únicamente
+### RULE #3: Essential files only
 
-Crear SOLO estos archivos con contenido real:
+Create ONLY these files with real content:
 
-| Archivo | Propósito | Cuándo crear |
-|---------|-----------|-------------|
-| `README.md` | Entry point del proyecto | Siempre |
-| `CHANGELOG.md` | Historial de versiones | Siempre (con entrada inicial) |
-| `AGENTS.md` | Protocolo para agentes IA | Siempre |
-| `docs/README.md` | Mapa de documentación + reglas de crecimiento | Siempre |
-| `docs/CONTEXT.md` | Términos del dominio encontrados en código | Siempre |
-| `docs/adr/TEMPLATE.md` | Plantilla para ADRs | Siempre |
-| `docs/adr/001-*.md` | Primer ADR si aplica | Si hay decisiones arquitectónicas |
-| `tutorials/quick-start.md` | Tutorial de inicio rápido | Siempre |
+| 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                                 |
 
-### REGLA #4: CONTEXT.md se genera analizando el código
+### RULE #4: CONTEXT.md is generated by analyzing code
 
-No inventar términos. Extraer del código:
+Do not invent terms. Extract from code:
 
-1. Buscar nombres de módulos, clases, funciones principales
-2. Identificar abreviaturas y su significado
-3. Mapear relaciones entre componentes
-4. Detectar términos ambiguos y documentarlos
+1. Search for module names, classes, main functions
+2. Identify abbreviations and their meaning
+3. Map relationships between components
+4. Detect ambiguous terms and document them
 
-### REGLA #5: Frontmatter YAML obligatorio
+### RULE #5: YAML frontmatter required
 
-Todo archivo de documentación debe incluir frontmatter:
+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]
 ---
 ```
 
-### REGLA #6: Manifest de crecimiento en docs/README.md
+### RULE #6: Growth manifest in docs/README.md
 
-Incluir reglas explícitas de cuándo y cómo agregar nueva documentación.
+Include explicit rules for when and how to add new documentation.
 
-## Flujo del Proceso
+## Process Flow
 
-### Paso 1: Detectar stack
+### Step 1: Detect stack
 
-Usar la tabla de detección automática de `AGENTS.md` § Stack. Además, analizar:
+Use the auto-detection table from `AGENTS.md` § Stack. Additionally, analyze:
 
 ```
-Analizar:
-├── Lenguaje principal (package.json, go.mod, requirements.txt, Cargo.toml, pom.xml)
-├── Framework (imports, dependencias, config files)
-├── Estructura de carpetas existente
-├── Herramientas de build/test (detectar comandos del ecosistema)
-└── Docs existentes (NO sobreescribir)
+Analyze:
+├── Primary language (package.json, go.mod, requirements.txt, Cargo.toml, pom.xml)
+├── Framework (imports, dependencies, config files)
+├── Existing folder structure
+├── Build/test tools (detect ecosystem commands)
+└── Existing docs (DO NOT overwrite)
 ```
 
-### Paso 2: Verificar documentación existente
+### Step 2: Verify existing documentation
 
 ```
-Revisar:
-├── ¿Existe README.md? → NO sobreescribir, sugerir mejoras
-├── ¿Existe CHANGELOG.md? → NO sobreescribir
-├── ¿Existe docs/? → Integrar, no reemplazar
-├── ¿Existen ADRs? → Preservar numeración
-└── ¿Existe AGENTS.md? → Preservar, sugerir adiciones
+Check:
+├── Does README.md exist? → DO NOT overwrite, suggest improvements
+├── Does CHANGELOG.md exist? → DO NOT overwrite
+├── Does docs/ exist? → Integrate, do not replace
+├── Do ADRs exist? → Preserve numbering
+└── Does AGENTS.md exist? → Preserve, suggest additions
 ```
 
-### Paso 3: Crear AGENTS.md con protocolo
+### Step 3: Create AGENTS.md with protocol
 
 ```markdown
-# AGENTS.md — Protocolo de Documentación
-
-## Antes de empezar una tarea
-1. Leer docs/CONTEXT.md para entender el dominio
-2. Leer docs/README.md para ubicarse en la documentación
-3. Revisar ADRs relevantes en docs/adr/
-
-## Después de completar una tarea
-1. Actualizar CONTEXT.md si surgieron nuevos términos
-2. Actualizar docs/README.md si se agregaron/eliminaron archivos
-3. Evaluar si se necesita un ADR (¿es difícil de revertir? ¿es sorprendente? ¿hay trade-off?)
-4. Pasar el protocolo al subagente si se delega trabajo
-
-## Al delegar trabajo
-1. Incluir este protocolo en el prompt del subagente
-2. Especificar qué archivos de doc actualizar
-3. Verificar que el subagente cumplió el protocolo
+# 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
 ```
 
-### Paso 4: Crear docs/README.md
+### 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
+- Links to related skills: `doc-write`, `doc-review`, `doc-maintain`
+
+### Step 5: Create docs/CONTEXT.md
+
+Generate with real domain terms detected in the code:
 
-Incluir:
-- Mapa completo de archivos de documentación (generado, no placeholder)
-- Reglas de crecimiento: cuándo agregar cada tipo de doc
-- Convenciones de nomenclatura
-- Enlaces a skills relacionados: `doc-write`, `doc-review`, `doc-maintain`
+- Table of terms with definitions
+- Relationships between terms
+- Flagged ambiguous terms
+- Source: source code analysis
 
-### Paso 5: Crear docs/CONTEXT.md
+### Step 6: Create docs/adr/TEMPLATE.md + first ADR
 
-Generar con términos reales del dominio detectados en el código:
-- Tabla de términos con definiciones
-- Relaciones entre términos
-- Términos ambiguos señalados
-- Origen: análisis del código fuente
+- TEMPLATE.md: reusable template
+- First ADR: only if an architectural decision already exists that meets the 3 criteria (hard to reverse, surprising, real trade-off)
 
-### Paso 6: Crear docs/adr/TEMPLATE.md + primer ADR
+### Step 7: Create tutorials/quick-start.md
 
-- TEMPLATE.md: plantilla reutilizable
-- Primer ADR: solo si ya existe una decisión arquitectónica que cumpla los 3 criterios (difícil de revertir, sorprendente, trade-off real)
+Based on the detected stack:
 
-### Paso 7: Crear tutorials/quick-start.md
+- Stack-specific prerequisites
+- Real installation steps
+- First runnable example
+- Verification at each step
 
-Basado en el stack detectado:
-- Prerequisitos específicos del stack
-- Pasos de instalación reales
-- Primer ejemplo ejecutable
-- Verificación en cada paso
+### Step 8: Create essential reference files
 
-### Paso 8: Crear archivos de referencia esenciales
+Only those applicable to the detected stack:
 
-Solo los que apliquen al stack detectado:
-- Si hay API: `reference/api.md`
-- Si hay configuración: `reference/configuration.md`
-- Si hay CLI: `reference/cli.md`
+- If there is an API: `reference/api.md`
+- If there is configuration: `reference/configuration.md`
+- If there is a CLI: `reference/cli.md`
 
-### Paso 9: Reportar resultado
+### Step 9: Report results
 
 ```
-✅ Creados:
+✅ Created:
   - README.md (entry point)
-  - CHANGELOG.md (inicializado)
-  - AGENTS.md (protocolo)
-  - docs/README.md (mapa + reglas)
-  - docs/CONTEXT.md (X términos del dominio)
+  - CHANGELOG.md (initialized)
+  - AGENTS.md (protocol)
+  - docs/README.md (map + rules)
+  - docs/CONTEXT.md (X domain terms)
   - docs/adr/TEMPLATE.md
-  - tutorials/quick-start.md (basado en {stack})
+  - tutorials/quick-start.md (based on {stack})
 
-⏭️ Pendientes (agregar cuando haya contenido):
-  - docs/adr/001-*.md (cuando haya una decisión arquitectónica)
-  - reference/api.md (cuando haya endpoints documentables)
-  - how-to/ (cuando surjan problemas repetibles)
+⏭️ Pending (add when there is content):
+  - docs/adr/001-*.md (when there is an architectural decision)
+  - reference/api.md (when there are documentable endpoints)
+  - how-to/ (when repeatable problems arise)
 ```
 
-## Comandos
+## Commands
 
-### Archivos a crear (en orden)
+### Files to create (in order)
 
 ```bash
-# Archivos raíz
+# Root files
 README.md
 CHANGELOG.md
 AGENTS.md
 
-# Estructura docs/
+# docs/ structure
 docs/README.md
 docs/CONTEXT.md
 docs/adr/TEMPLATE.md
 
-# Tutoriales
+# Tutorials
 tutorials/quick-start.md
 
-# Referencia (solo si aplica)
-reference/api.md          # Solo si hay API
-reference/configuration.md # Solo si hay config
+# Reference (only if applicable)
+reference/api.md          # Only if there is an API
+reference/configuration.md # Only if there is config
 ```
 
-### Verificación post-creación
+### Post-creation verification
 
 ```
-1. Verificar que TODO archivo tiene contenido real (no placeholders)
-2. Verificar que TODO archivo tiene frontmatter YAML
-3. Verificar que CONTEXT.md contiene términos reales del código
-4. Verificar que quick-start.md es ejecutable para el stack detectado
-5. Verificar que docs/README.md mapea todos los archivos creados
+1. Verify that EVERY file has real content (no placeholders)
+2. Verify that EVERY file has YAML frontmatter
+3. Verify that CONTEXT.md contains real terms from the code
+4. Verify that quick-start.md is runnable for the detected stack
+5. Verify that docs/README.md maps all created files
 ```
 
-## Ejemplo Concreto
+## Concrete Example
 
-### Input: Proyecto React + Express detectado
+### Input: React + Express project detected
 
 ```
-Detección:
+Detection:
 ├── package.json → Node.js, React 18, Express 4
 ├── tsconfig.json → TypeScript 5
 ├── tailwind.config.ts → Tailwind CSS
@@ -230,48 +237,48 @@ Detección:
 └── .github/workflows/ci.yml → {{TECH_STACK}} CI/CD
 ```
 
-### Output: Archivos creados
+### Output: Created files
 
 ```
 ✅ README.md
-   - "Plataforma web construida con React 18 y Express 4"
-   - Stack table con React, Express, PostgreSQL, {{TECH_STACK}}
+   - "Web platform built with React 18 and Express 4"
+   - Stack table with React, Express, PostgreSQL, {{TECH_STACK}}
    - Commands: npm run dev, npm run build, npm run test, npm run lint
 
 ✅ CHANGELOG.md
-   - Entrada inicial: "## [0.1.0] - 2026-05-07 / ### Added / - Initial release"
+   - Initial entry: "## [0.1.0] - 2026-05-07 / ### Added / - Initial release"
 
 ✅ AGENTS.md
    - Stack: React 18, Express 4, PostgreSQL, Prisma, Tailwind, {{TECH_STACK}}
    - Commands: npm run dev/build/test/lint/typecheck
-   - Protocolo completo (antes/después/subdelegar)
+   - Complete protocol (before/after/delegate)
 
 ✅ docs/README.md
-   - Mapa con 8 archivos creados
-   - Growth rules: "Crear reference/api.md cuando haya 5+ endpoints"
-   - Tabla Diátaxis: tutorials/ ✅, guides/ ⏭️, reference/ ⏭️, explanation/ ⏭️
+   - Map with 8 created files
+   - Growth rules: "Create reference/api.md when there are 5+ endpoints"
+   - Diátaxis table: tutorials/ ✅, guides/ ⏭️, reference/ ⏭️, explanation/ ⏭️
 
 ✅ docs/CONTEXT.md
-   - 6 términos extraídos: User, Session, Workspace, Role, Permission, Token
-   - Relaciones: User → Session, User ← Role ← Permission
-   - ⚠️ AMBIGUO: "workspace" (puede ser equipo o proyecto)
+   - 6 terms extracted: User, Session, Workspace, Role, Permission, Token
+   - Relationships: User → Session, User ← Role ← Permission
+   - ⚠️ AMBIGUOUS: "workspace" (could be team or project)
 
 ✅ docs/adr/TEMPLATE.md
-   - Formato minimal listo para usar
+   - Minimal format ready to use
 
 ✅ docs/tutorials/quick-start.md
-   - Prerequisitos: Node 20+, {{TECH_STACK}}, npm
-   - Pasos: clone → npm install → cp .env.example .env → npx prisma migrate dev → npm run dev
-   - Verificación: "Abre http://localhost:3000 — deberías ver la landing"
-
-⏭️ Pendientes (lazy):
-   - docs/adr/0001-*.md → cuando haya una decisión arquitectónica
-   - docs/DESIGN.md → cuando se definan tokens de diseño
-   - docs/reference/api.md → cuando haya 5+ endpoints estables
-   - docs/guides/deployment.md → cuando haya proceso de deploy
+   - Prerequisites: Node 20+, {{TECH_STACK}}, npm
+   - Steps: clone → npm install → cp .env.example .env → npx prisma migrate dev → npm run dev
+   - Verification: "Open http://localhost:3000 — you should see the landing"
+
+⏭️ Pending (lazy):
+   - docs/adr/0001-*.md → when there is an architectural decision
+   - docs/DESIGN.md → when design tokens are defined
+   - docs/reference/api.md → when there are 5+ stable endpoints
+   - docs/guides/deployment.md → when there is a deploy process
 ```
 
-## Recursos
+## Resources
 
-- [Diátaxis Quick Reference](references/diataxis-quick-ref.md) — Resumen del framework Diátaxis con árbol de decisión
-- Skills relacionados: `doc-write` (escribir docs), `doc-review` (auditar docs), `doc-maintain` (mantener docs sincronizados)
+- [Diátaxis Quick Reference](references/diataxis-quick-ref.md) — Summary of the Diátaxis framework with decision tree
+- Related skills: `doc-write` (write docs), `doc-review` (audit docs), `doc-maintain` (keep docs synced)