@damenor/agent-docs 0.1.0

package/templates/modules/product/docs/roadmap.md

@@ -0,0 +1,80 @@
+---
+created: "2025-01-01"
+status: active
+type: planning
+tags: [roadmap, planificación, features, backlog]
+---
+
+# Roadmap
+
+## Estado actual
+
+**Versión actual**: [versión — ej. 0.1.0]
+**Fase**: [Discovery / MVP / Growth / Maintenance]
+**Último release**: [fecha — ej. 2025-01-15]
+**Próximo release planificado**: [fecha o "Por definir"]
+
+Resumen del estado: [1-2 oraciones describiendo dónde está el proyecto ahora. Ej. "MVP funcional con autenticación y CRUD básico. Pendiente de integración con sistema de pagos."]
+
+---
+
+## Próximos features
+
+| Feature | Descripción | Prioridad | Estado | Responsable | Target |
+|---------|-------------|-----------|--------|-------------|--------|
+| [Feature 1] | [Descripción breve de qué hace y por qué] | 🔴 Alta | [Estado: Planificado / En progreso / En QA / Listo] | [Nombre o rol] | [Fecha o sprint] |
+| [Feature 2] | [Descripción] | 🟡 Media | [Estado] | [Responsable] | [Target] |
+| [Feature 3] | [Descripción] | 🟢 Baja | [Estado] | [Responsable] | [Target] |
+
+### Detalle por feature
+
+#### [Feature 1]
+- **Por qué**: [Justificación de negocio o técnica.]
+- **Criterios de aceptación**:
+  - [ ] [Criterio 1]
+  - [ ] [Criterio 2]
+  - [ ] [Criterio 3]
+- **Dependencias**: [Otros features, equipos, servicios externos.]
+- **Riesgos**: [Qué podría salir mal. Mitigación.]
+
+---
+
+## Backlog
+
+Ideas y features que se quieren hacer pero que no tienen fecha asignada aún.
+
+| Feature | Descripción | Fuente de la idea |
+|---------|-------------|------------------|
+| [Feature idea 1] | [Qué es y por qué sería valioso] | [Stakeholder / usuario / equipo] |
+| [Feature idea 2] | [Descripción] | [Fuente] |
+| [Feature idea 3] | [Descripción] | [Fuente] |
+
+---
+
+## Decisiones pendientes
+
+| Decisión | Contexto | Opciones consideradas | Plazo para decidir | Responsable |
+|----------|----------|----------------------|-------------------|-------------|
+| [Decisión 1] | [Por qué hay que tomar esta decisión. Qué pasa si no se decide.] | [Opción A, Opción B] | [Fecha] | [Quién decide] |
+| [Decisión 2] | [Contexto] | [Opciones] | [Fecha] | [Responsable] |
+
+---
+
+## Historial de releases
+
+| Versión | Fecha | Cambios principales | Notas |
+|---------|-------|-------------------|-------|
+| [0.1.0] | [2025-01-15] | Inicialización del proyecto, estructura base | Primer release |
+| [0.2.0] | [YYYY-MM-DD] | [Features principales del release] | [Notas adicionales] |
+
+Ver el detalle completo de cambios en [`CHANGELOG.md`](../../CHANGELOG.md).
+
+---
+
+## Cómo actualizar este archivo
+
+- **Al planificar un sprint**: Actualizar la tabla de "Próximos features" con prioridades y responsables.
+- **Al iniciar un feature**: Cambiar estado a "En progreso".
+- **Al completar un feature**: Cambiar estado a "Listo", mover a "Historial de releases".
+- **Al recibir un request nuevo**: Añadir al Backlog si no es inmediato, o a "Próximos features" si sí.
+- **Al tomar una decisión técnica**: Mover de "Decisiones pendientes" y crear un ADR en `docs/adr/`.

package/templates/modules/reference/docs/reference/api.md

@@ -0,0 +1,131 @@
+---
+created: "2026-05-07"
+updated: "2026-05-07"
+status: active
+type: reference
+tags: [api, reference, endpoints]
+---
+
+# Referencia de API
+
+Documentación de referencia de los endpoints del proyecto.
+
+> [!tip] Convención
+> Si la API crece a más de 10 endpoints, convierte este archivo en una carpeta `api/` con un archivo por dominio.
+
+## Autenticación
+
+| Método | Descripción | Header |
+|--------|-------------|--------|
+| Bearer Token | JWT enviado en header | `Authorization: Bearer <token>` |
+
+**Flujo**:
+1. Cliente envía credenciales a `/auth/login`
+2. Server devuelve `{ token, refreshToken }`
+3. Cliente incluye `Authorization: Bearer <token>` en requests siguientes
+4. Si token expira, usar refresh token en `/auth/refresh`
+
+## Endpoints
+
+### [Recurso]
+
+#### `GET /api/[recurso]`
+
+Lista recursos con paginación.
+
+**Headers**:
+| Header | Requerido | Descripción |
+|--------|-----------|-------------|
+| `Authorization` | Sí | Bearer token |
+
+**Query Parameters**:
+| Param | Tipo | Default | Descripción |
+|-------|------|---------|-------------|
+| `page` | number | 1 | Página actual |
+| `limit` | number | 20 | Items por página (max 100) |
+| `sort` | string | `-createdAt` | Campo de orden (`-` para desc) |
+
+**Response 200**:
+```json
+{
+  "data": [
+    {
+      "id": "string",
+      "name": "string",
+      "createdAt": "ISO 8601"
+    }
+  ],
+  "meta": {
+    "page": 1,
+    "limit": 20,
+    "total": 100
+  }
+}
+```
+
+#### `POST /api/[recurso]`
+
+Crea un nuevo recurso.
+
+**Body**:
+```json
+{
+  "name": "string (required, max 200)",
+  "description": "string (optional)"
+}
+```
+
+**Response 201**:
+```json
+{
+  "id": "string",
+  "name": "string",
+  "description": "string",
+  "createdAt": "ISO 8601",
+  "updatedAt": "ISO 8601"
+}
+```
+
+## Códigos de Error
+
+| Status | Código | Descripción |
+|--------|--------|-------------|
+| 400 | `VALIDATION_ERROR` | Datos de entrada inválidos |
+| 401 | `UNAUTHORIZED` | Token ausente o inválido |
+| 403 | `FORBIDDEN` | Sin permisos para el recurso |
+| 404 | `NOT_FOUND` | Recurso no encontrado |
+| 409 | `CONFLICT` | Recurso ya existe |
+| 422 | `UNPROCESSABLE` | Entidad no procesable |
+| 429 | `RATE_LIMITED` | Demasiados requests |
+| 500 | `INTERNAL_ERROR` | Error interno del servidor |
+
+**Formato de error**:
+```json
+{
+  "error": {
+    "code": "VALIDATION_ERROR",
+    "message": "Descripción legible del error",
+    "details": [
+      { "field": "name", "message": "Name is required" }
+    ]
+  }
+}
+```
+
+## Rate Limiting
+
+| Tier | Requests/minuto | Burst |
+|------|-----------------|-------|
+| Standard | 60 | 10 |
+| Premium | 300 | 50 |
+
+Headers de respuesta:
+- `X-RateLimit-Limit`: Límite por ventana
+- `X-RateLimit-Remaining`: Requests restantes
+- `X-RateLimit-Reset`: Timestamp cuando se resetea
+
+## Versionado
+
+La API usa versionado en URL: `/api/v1/`, `/api/v2/`.
+
+Versiones anteriores se mantienen durante 6 meses después del release de una nueva versión mayor.

package/templates/modules/reference/docs/reference/code-style.md

@@ -0,0 +1,275 @@
+---
+created: "2026-05-07"
+updated: "2026-05-07"
+status: active
+type: reference
+tags: [code-style, conventions, reference, standards]
+---
+
+# Code Style
+
+Convenciones de código del proyecto. Todo código nuevo DEBE seguir estas reglas.
+
+> [!important] Regla general
+> Lo que se puede automatizar (linter, formatter), se automatiza. Lo que no, se documenta aquí.
+
+## Automatización
+
+El proyecto usa estas herramientas para enforcear estilo automáticamente:
+
+| Herramienta | Qué enforcea | Archivo config |
+|-------------|-------------|----------------|
+| [ESLint / Pylint / etc.] | Reglas de código | [config file] |
+| [Prettier / Black / etc.] | Formateo | [config file] |
+| [TypeScript / mypy / etc.] | Tipos | [config file] |
+| EditorConfig | Configuración del editor | `.editorconfig` |
+
+**Si el linter pasa, el estilo es correcto.** No discutir estilo que el linter ya resuelve.
+
+## Nombramiento
+
+### Archivos y Carpetas
+
+| Tipo | Convención | Ejemplo |
+|------|-----------|---------|
+| Componentes UI | `PascalCase` | `Button.tsx`, `NavBar.vue` |
+| Utilidades | `camelCase` | `formatDate.ts`, `parseConfig.js` |
+| Tests | `[nombre].test/spec.[ext]` | `auth.test.ts`, `api.spec.ts` |
+| Tipos/Interfaces | `PascalCase` | `User.ts`, `ApiResponse.ts` |
+| Constantes | `UPPER_SNAKE_CASE` | `API_URLS.ts`, `MAX_RETRIES.ts` |
+| Páginas/Rutas | `kebab-case` | `user-profile.tsx`, `about.vue` |
+
+### Variables y Funciones
+
+| Tipo | Convención | Ejemplo |
+|------|-----------|---------|
+| Variables | `camelCase` | `userName`, `isActive` |
+| Constantes | `UPPER_SNAKE_CASE` | `MAX_RETRIES`, `API_BASE_URL` |
+| Funciones | `camelCase` | `getUser()`, `calculateTotal()` |
+| Booleanos | `is`/`has`/`should` prefix | `isLoading`, `hasPermission` |
+| Clases | `PascalCase` | `UserService`, `HttpClient` |
+| Interfaces/Types | `PascalCase` | `User`, `ApiResponse` |
+| Enums | `PascalCase` | `UserRole`, `OrderStatus` |
+| Eventos | `on` prefix | `onClick`, `onSubmit` |
+
+## Imports
+
+### Orden de imports
+
+```typescript
+// 1. Librerías externas
+import { useState, useEffect } from 'react'
+import axios from 'axios'
+
+// 2. Imports internos (alias si están configurados)
+import { Button } from '@/components/ui/Button'
+import { useAuth } from '@/hooks/useAuth'
+
+// 3. Tipos
+import type { User, ApiResponse } from '@/types'
+
+// 4. Estilos (si aplica)
+import './styles.css'
+```
+
+### Reglas
+
+- Imports agrupados con línea en blanco entre grupos
+- Sin imports wildcard (`import *`) a menos que sea necesario
+- Usar alias de path configurados (`@/`, `~`, etc.)
+- Imports de tipos con `import type` cuando sea solo tipo
+
+## Estructura de Código
+
+### Componentes UI
+
+```typescript
+// Orden dentro de un componente:
+// 1. Types/Interfaces
+// 2. Constantes
+// 3. Componente principal
+// 4. Subcomponentes (si son pequeños)
+// 5. Export
+
+interface ButtonProps {
+  variant?: 'primary' | 'secondary'
+  children: React.ReactNode
+  onClick?: () => void
+}
+
+const VARIANT_STYLES = {
+  primary: 'bg-blue-600 text-white',
+  secondary: 'bg-gray-200 text-gray-800',
+}
+
+export function Button({ variant = 'primary', children, onClick }: ButtonProps) {
+  return (
+    <button className={VARIANT_STYLES[variant]} onClick={onClick}>
+      {children}
+    </button>
+  )
+}
+```
+
+### Funciones de API / Servicios
+
+```typescript
+// Orden:
+// 1. Validación de inputs
+// 2. Lógica de negocio
+// 3. Side effects (logs, métricas)
+// 4. Return
+
+export async function createUser(input: CreateUserInput): Promise<User> {
+  // Validación
+  validateCreateUserInput(input)
+
+  // Lógica
+  const hashedPassword = await hashPassword(input.password)
+  const user = await db.user.create({ ...input, password: hashedPassword })
+
+  // Side effects
+  logger.info('User created', { userId: user.id })
+
+  return user
+}
+```
+
+## Comentarios
+
+### Cuándo comentar
+
+Comentar el **por qué**, no el **qué**:
+
+```typescript
+// ❌ Mal: Restate lo que el código ya dice
+counter += 1
+
+// ✅ Bien: Explica por qué
+if (now - windowStart > WINDOW_SIZE_MS) {
+  counter = 0
+  windowStart = now
+}
+```
+
+### Cuándo NO comentar
+
+- Código auto-explicativo
+- TODOs que deberías hacer ahora
+- Código comentado (elimínalo, git tiene historia)
+- **No usar comentarios inline** para explicar decisiones — usar JSDoc/docstring
+
+### JSDoc / Docstrings
+
+**OBLIGATORIO** para funciones públicas del módulo y componentes complejos. Explicar el POR QUÉ, no el qué:
+
+```typescript
+/**
+ * Creates a new user with hashed password.
+ * Uses bcrypt with 12 rounds — chose this over argon2 because
+ * we don't need GPU-resistant hashing for internal users.
+ *
+ * @param input - User creation data
+ * @returns Created user without password
+ * @throws {ValidationError} If email is invalid or already exists
+ */
+```
+
+```typescript
+/**
+ * Debounced search that cancels previous requests.
+ * Needed because the API has a rate limit of 10 req/min
+ * and users type fast in the search bar.
+ */
+export function useSearch(query: string, delay = 300) { ... }
+```
+
+**Cuando escribir JSDoc**:
+- Funciones exportadas / públicas del módulo
+- Componentes UI complejos (props no obvias, comportamiento especial)
+- Hooks custom con lógica no trivial
+- Funciones que resuelven un problema específico (documentar el problema)
+- Funciones donde se tomó una decisión de implementación no obvia
+
+## Manejo de Errores
+
+- Nunca usar `any` como tipo de error
+- Siempre manejar errores en el nivel apropiado
+- Logear errores con contexto suficiente
+- No swallow errors silenciosamente
+
+```typescript
+// ❌ Mal
+try {
+  await doSomething()
+} catch (e) {}
+
+// ✅ Bien
+try {
+  await doSomething()
+} catch (error) {
+  logger.error('Failed to do something', { error, context })
+  throw new AppError('Something went wrong', { cause: error })
+}
+```
+
+## Testing
+
+### Convenciones de Tests
+
+- Archivos de test junto al archivo que testean o en carpeta `__tests__/`
+- Nombre descriptivo: `should [expected behavior] when [condition]`
+- Patrón AAA: Arrange → Act → Assert
+- Un assertion conceptual por test
+
+```typescript
+describe('createUser', () => {
+  it('should create user with hashed password when input is valid', async () => {
+    // Arrange
+    const input = { email: 'test@test.com', password: 'password123' }
+
+    // Act
+    const user = await createUser(input)
+
+    // Assert
+    expect(user.email).toBe(input.email)
+    expect(user.password).not.toBe(input.password)
+  })
+})
+```
+
+## Git
+
+### Mensajes de Commit
+
+Seguir [Conventional Commits](https://www.conventionalcommits.org/):
+
+```
+tipo(alcance): descripción breve
+
+tipo: feat | fix | docs | style | refactor | perf | test | chore
+alcance: módulo o componente afectado (opcional)
+```
+
+Ejemplos:
+```
+feat(auth): add JWT refresh token rotation
+fix(api): handle null user in response
+docs(readme): update setup instructions
+refactor(utils): extract date formatting to shared util
+```
+
+### Nombres de Branches
+
+```
+tipo/descripción-corta
+
+tipos: feat | fix | refactor | docs | chore
+```
+
+Ejemplos:
+```
+feat/user-profile
+fix/login-redirect
+refactor/api-error-handling
+```

package/templates/modules/reference/docs/reference/configuration.md

@@ -0,0 +1,117 @@
+---
+created: "2025-01-01"
+status: active
+type: reference
+tags: [referencia, configuración, variables, entorno, env]
+---
+
+# Referencia de Configuración
+
+Listado completo de variables de entorno y opciones de configuración del proyecto.
+
+---
+
+## Variables de entorno
+
+### Aplicación
+
+| Variable | Requerida | Default | Descripción | Ejemplo |
+|----------|-----------|---------|-------------|---------|
+| `APP_ENV` | Sí | `development` | Entorno de ejecución. Valores: `development`, `staging`, `production` | `production` |
+| `APP_PORT` | No | `[3000]` | Puerto donde escucha el servidor | `8080` |
+| `APP_URL` | Sí (prod) | `http://localhost:3000` | URL pública de la aplicación | `https://[dominio]` |
+| `APP_NAME` | No | `{{PROJECT_NAME}}` | Nombre de la aplicación para logs y metadata | `Mi Proyecto` |
+| `LOG_LEVEL` | No | `info` | Nivel de logging. Valores: `debug`, `info`, `warn`, `error` | `debug` |
+
+### Base de datos
+
+| Variable | Requerida | Default | Descripción | Ejemplo |
+|----------|-----------|---------|-------------|---------|
+| `DATABASE_URL` | Sí | — | Connection string completo de la base de datos | `postgresql://user:pass@host:5432/dbname?ssl=true` |
+| `DATABASE_POOL_SIZE` | No | `10` | Tamaño del pool de conexiones | `20` |
+| `DATABASE_SSL` | No | `false` | Habilitar SSL para la conexión | `true` |
+
+### Autenticación
+
+| Variable | Requerida | Default | Descripción | Ejemplo |
+|----------|-----------|---------|-------------|---------|
+| `JWT_SECRET` | Sí | — | Secret para firmar JWTs. **Debe ser único por entorno y nunca commiteado.** | `[string aleatorio de 32+ caracteres]` |
+| `JWT_EXPIRES_IN` | No | `1h` | Tiempo de expiración del token de acceso | `30m` |
+| `JWT_REFRESH_EXPIRES_IN` | No | `7d` | Tiempo de expiración del refresh token | `30d` |
+
+### Servicios externos
+
+| Variable | Requerida | Default | Descripción | Ejemplo |
+|----------|-----------|---------|-------------|---------|
+| `[SERVICIO]_API_KEY` | Sí (prod) | — | API key para [servicio externo] | `[key]` |
+| `[SERVICIO]_API_URL` | No | `[URL default]` | URL base de la API del servicio | `https://api.servicio.com/v1` |
+| `[SERVICIO]_TIMEOUT` | No | `5000` | Timeout en ms para requests al servicio | `10000` |
+
+### Email *(si aplica)*
+
+| Variable | Requerida | Default | Descripción | Ejemplo |
+|----------|-----------|---------|-------------|---------|
+| `SMTP_HOST` | No | — | Host del servidor SMTP | `smtp.gmail.com` |
+| `SMTP_PORT` | No | `587` | Puerto SMTP | `465` |
+| `SMTP_USER` | No | — | Usuario SMTP | `noreply@[dominio]` |
+| `SMTP_PASSWORD` | No | — | Contraseña SMTP | `[password]` |
+| `EMAIL_FROM` | No | `noreply@[dominio]` | Email remitente por defecto | `contacto@[dominio]` |
+
+### Storage / CDN *(si aplica)*
+
+| Variable | Requerida | Default | Descripción | Ejemplo |
+|----------|-----------|---------|-------------|---------|
+| `STORAGE_BUCKET` | No | — | Nombre del bucket de storage | `mi-proyecto-assets` |
+| `STORAGE_REGION` | No | — | Región del bucket | `us-east-1` |
+| `CDN_URL` | No | — | URL del CDN para assets | `https://cdn.[dominio]` |
+
+---
+
+## Valores por entorno
+
+| Variable | Development | Staging | Production |
+|----------|-------------|---------|------------|
+| `APP_ENV` | `development` | `staging` | `production` |
+| `LOG_LEVEL` | `debug` | `info` | `warn` |
+| `DATABASE_URL` | Local DB | Staging DB | Production DB |
+| `JWT_SECRET` | Cualquier valor para dev | Secret de staging | Secret de producción (rotado regularmente) |
+| `[API_KEY]` | Key de testing | Key de staging | Key de producción |
+
+---
+
+## Archivos de configuración
+
+### `.env.example`
+
+El archivo `.env.example` en la raíz del proyecto contiene **todas las variables posibles** con valores de ejemplo o placeholders. Se commitea al repo y sirve como referencia.
+
+**Regla**: Si se añade una variable nueva, actualizar `.env.example` primero.
+
+### Archivos de config del framework
+
+| Archivo | Propósito | Formato |
+|---------|-----------|---------|
+| `[tsconfig.json / pyproject.toml / etc.]` | Configuración del lenguaje/framework | [JSON / TOML / YAML] |
+| `[tailwind.config.js / etc.]` | Configuración de estilos | [JS / CSS] |
+| `[docker-compose.yml]` | Servicios de desarrollo local | YAML |
+| `[Dockerfile]` | Imagen Docker para producción | Dockerfile |
+
+---
+
+## Reglas de configuración
+
+1. **Nunca commitear secrets**: Todo valor sensible (passwords, API keys, secrets) va en `.env` que está en `.gitignore`.
+2. **Defaults seguros**: Las variables que tienen default deben funcionar "out of the box" para desarrollo local.
+3. **Fail fast**: Si una variable requerida no está configurada, la aplicación debe fallar al arrancar con un mensaje claro que diga cuál falta.
+4. **Validación al inicio**: Las variables se validan al arrancar la aplicación, no en cada request.
+5. **Documentar cambios**: Si se añade una variable nueva, actualizar este archivo y `.env.example` en el mismo commit.
+
+---
+
+## Cómo añadir una variable nueva
+
+1. Añadir la variable a `.env.example` con un valor de ejemplo o placeholder.
+2. Añadir la variable a este archivo (`configuration.md`) en la sección correspondiente.
+3. Implementar la lectura de la variable en código (con valor default si aplica).
+4. Configurar la variable en los entornos de staging y production (CI/CD secrets, dashboard del hosting, etc.).
+5. Commit todo junto (código + docs + `.env.example`).