@damenor/agent-docs 0.1.2 → 0.4.1

package/templates/modules/tutorials/docs/tutorials/environment-setup.md

@@ -1,212 +0,0 @@
----
-created: "2025-01-01"
-status: active
-type: tutorial
-tags: [tutorial, setup, entorno, configuración, onboarding]
----
-
-# Configuración del Entorno de Desarrollo
-
-Este tutorial te guía paso a paso para configurar tu entorno de desarrollo completo. Al terminar, tendrás todas las herramientas necesarias para trabajar en el proyecto de forma eficiente.
-
-**Tiempo estimado**: 30 minutos.
-**Audiencia**: Developers que se incorporan al proyecto.
-**Prerrequisito**: Haber completado [`quick-start.md`](quick-start.md).
-
----
-
-## Prerrequisitos
-
-Verificar que tienes las herramientas base instaladas (ver tabla en [`quick-start.md`](quick-start.md)).
-
----
-
-## Paso 1: Configurar el editor
-
-### VS Code *(recomendado)*
-
-Instalar las siguientes extensiones:
-
-| Extensión | Para qué | ID |
-|-----------|----------|----|
-| **[ESLint / Linter]** | Mostrar errores de lint en el editor | `[dbaeumer.vscode-eslint]` |
-| **[Prettier / Formatter]** | Formatear código al guardar | `[esbenp.prettier-vscode]` |
-| **[Tailwind CSS IntelliSense]** | Autocompletado de clases | `[bradlc.vscode-tailwindcss]` |
-| **[GitLens]** | Ver historial de cambios inline | `[eamodio.gitlens]` |
-
-Configurar format-on-save. Añadir a `.vscode/settings.json`:
-
-```json
-{
-  "editor.formatOnSave": true,
-  "editor.defaultFormatter": "[esbenp.prettier-vscode]",
-  "editor.codeActionsOnSave": {
-    "source.fixAll.[eslint]": true
-  }
-}
-```
-
-### Otros editores
-
-Si usas otro editor, asegúrate de configurar:
-- Linter integrado
-- Formateo automático al guardar
-- Integración con git
-
----
-
-## Paso 2: Configurar herramientas de línea de comandos
-
-### Git hooks
-
-Los hooks de git se instalan automáticamente al ejecutar `[npm install]`. Verificar:
-
-```bash
-ls .git/hooks/
-# Debería mostrar: pre-commit, commit-msg, etc.
-```
-
-### CLI tools recomendadas
-
-| Herramienta | Para qué | Instalación |
-|------------|----------|-------------|
-| **[gh]** | GitHub CLI (PRs, issues desde terminal) | `brew install gh` / `winget install GitHub.cli` |
-| **[ herramienta 2 ]** | [Descripción] | `[comando de instalación]` |
-
----
-
-## Paso 3: Configurar variables de entorno completas
-
-Copiar y configurar el archivo de entorno:
-
-```bash
-cp .env.example .env
-```
-
-### Variables obligatorias
-
-| Variable | Descripción | Ejemplo | Cómo obtener el valor |
-|----------|-------------|---------|----------------------|
-| `APP_ENV` | Entorno de ejecución | `development` | Fijo |
-| `[DATABASE_URL]` | Conexión a la base de datos local | `postgresql://user:pass@localhost:5432/dbname` | Ver Paso 4 |
-| `[API_KEY_EXTERNA]` | API key para servicios externos | `[valor]` | Pedir al tech lead |
-
-### Variables opcionales
-
-| Variable | Default | Descripción |
-|----------|---------|-------------|
-| `LOG_LEVEL` | `info` | Nivel de logging (debug, info, warn, error) |
-| `PORT` | `[3000]` | Puerto del servidor de desarrollo |
-
-Ver la referencia completa en [`docs/reference/configuration.md`](../reference/configuration.md).
-
----
-
-## Paso 4: Configurar la base de datos local
-
-### Instalación *(si no la tienes)*
-
-```bash
-# macOS
-brew install [postgresql]
-
-# Windows
-winget install PostgreSQL.PostgreSQL
-
-# Linux
-sudo apt install postgresql
-```
-
-### Crear la base de datos
-
-```bash
-# Conectarse a PostgreSQL
-psql -U postgres
-
-# Crear base de datos y usuario
-CREATE DATABASE [nombre_db];
-CREATE USER [usuario] WITH PASSWORD '[password]';
-GRANT ALL PRIVILEGES ON DATABASE [nombre_db] TO [usuario];
-\q
-```
-
-### Ejecutar migraciones
-
-```bash
-[comando de migración — ej. npm run db:migrate]
-```
-
-### Cargar datos de desarrollo
-
-```bash
-[comando de seed — ej. npm run db:seed]
-```
-
-Esto carga datos de ejemplo para poder trabajar localmente.
-
----
-
-## Paso 5: Verificar la configuración
-
-Ejecuta esta lista de verificación:
-
-```bash
-# 1. Tests pasan
-[npm run test]
-
-# 2. Lint pasa
-[npm run lint]
-
-# 3. Build funciona
-[npm run build]
-
-# 4. Servidor arranca
-[npm run dev]
-```
-
-Si todo pasa sin errores, tu entorno está listo.
-
----
-
-## Paso 6: Configuración adicional *(opcional)*
-
-### Docker *(si el proyecto lo usa)*
-
-```bash
-docker-compose up -d
-```
-
-Verifica que los contenedores estén corriendo:
-
-```bash
-docker-compose ps
-```
-
-### HTTPS local *(si es necesario)*
-
-```bash
-# Generar certificado local
-[comando para generar cert]
-
-# Arrancar con HTTPS
-[comando específico]
-```
-
----
-
-## Problemas comunes
-
-| Problema | Solución |
-|----------|----------|
-| `EADDRINUSE` (puerto en uso) | Cambiar el puerto en `.env` o matar el proceso: `lsof -i :3000` |
-| Tests fallan por conexión a DB | Verificar que PostgreSQL esté corriendo: `pg_isready` |
-| `npm install` falla | Borrar `node_modules` y `package-lock.json`, verificar versión de Node |
-| Hook de git falla | Reinstalar hooks: `npm install` |
-
-Más soluciones en [`docs/guides/troubleshooting.md`](../guides/troubleshooting.md).
-
----
-
-## Siguiente paso
-
-Ahora que tu entorno está listo, haz tu primera contribución: [`first-task.md`](first-task.md).

package/templates/modules/tutorials/docs/tutorials/first-task.md

@@ -1,246 +0,0 @@
----
-created: "2025-01-01"
-status: active
-type: tutorial
-tags: [tutorial, primera-tarea, contribución, PR, git]
----
-
-# Tu Primera Tarea — End to End
-
-Este tutorial te guía a través del ciclo completo de desarrollo: desde crear una branch hasta mergear tu PR. Lo harás con una tarea real (o un ejercicio de prueba).
-
-**Tiempo estimado**: 30-45 minutos.
-**Audiencia**: Developers que hacen su primera contribución al proyecto.
-**Prerrequisitos**: Haber completado [`quick-start.md`](quick-start.md) y [`environment-setup.md`](environment-setup.md).
-
----
-
-## Qué vas a construir
-
-[Descripción de la tarea de ejemplo. Ejemplo: "Vas a añadir un componente de 'Alerta' al design system que muestre mensajes de éxito, warning y error con estilo consistente."]
-
-Al terminar, habrás practicado:
-- Crear una branch
-- Escribir código siguiendo las convenciones del proyecto
-- Escribir tests
-- Crear un Pull Request
-- Responder a code review
-
----
-
-## Paso 1: Actualizar main y crear tu branch
-
-```bash
-# Asegúrate de estar en main
-git checkout main
-
-# Actualiza con los últimos cambios
-git pull origin main
-
-# Crea tu branch de trabajo
-git checkout -b feature/[nombre-de-tu-feature]
-```
-
-Nombrar la branch siguiendo las convenciones de [`dev-workflow.md`](../dev-workflow.md):
-- `feature/` para features nuevas
-- `fix/` para bug fixes
-- `refactor/` para refactors
-
----
-
-## Paso 2: Leer la documentación relevante
-
-Antes de escribir código, leer:
-
-1. [`docs/CONTEXT.md`](../CONTEXT.md) — Vocabulario del dominio.
-2. [`docs/explanation/architecture.md`](../explanation/architecture.md) — Cómo está estructurado el proyecto.
-3. [`docs/DESIGN.md`](../DESIGN.md) — Si tu tarea involucra UI (colores, tipografía, componentes).
-4. [`docs/adr/`](../adr/) — Verificar si hay ADRs relacionados con tu tarea.
-
-Esto te dará el contexto necesario para escribir código que sigue las convenciones del proyecto.
-
----
-
-## Paso 3: Implementar
-
-### 3.1 Identificar dónde va tu cambio
-
-Mirar la estructura del proyecto (ver `AGENTS.md`) y encontrar el lugar correcto:
-
-```
-src/
-├── components/     ← Si es un componente UI
-├── pages/          ← Si es una página nueva
-├── services/       ← Si es lógica de negocio
-├── utils/          ← Si es una utilidad reutilizable
-└── types/          ← Si necesitas definir tipos nuevos
-```
-
-### 3.2 Escribir el código
-
-Seguir las convenciones:
-
-- **Nombres en inglés** (variables, funciones, archivos).
-- **Comentarios en español** cuando sean necesarios.
-- **Tipado** (si el proyecto usa TypeScript): tipar todo lo que se pueda.
-- **Accesibilidad**: si es UI, incluir `aria-labels`, roles semánticos, contraste adecuado.
-
-### 3.3 Verificar mientras desarrollas
-
-```bash
-# En una terminal, mantener el servidor corriendo
-[npm run dev]
-
-# En otra terminal, ejecutar lint después de cambios significativos
-[npm run lint]
-```
-
----
-
-## Paso 4: Escribir tests
-
-Todo código nuevo debe incluir tests. Ver las reglas en [`dev-workflow.md`](../dev-workflow.md).
-
-### Qué testear
-
-- **Happy path**: el caso principal donde todo funciona correctamente.
-- **Edge cases**: datos vacíos, valores límite, inputs inesperados.
-- **Error cases**: qué pasa cuando algo falla.
-
-### Ejemplo
-
-```typescript
-// [archivo de test — ej. src/components/Alert.test.tsx]
-describe('Alert', () => {
-  it('muestra el mensaje correctamente', () => {
-    // Test del happy path
-  });
-
-  it('aplica el estilo según la variante', () => {
-    // Test de cada variante (success, warning, error)
-  });
-
-  it('es accesible', () => {
-    // Test de accesibilidad (aria-label, role)
-  });
-});
-```
-
-### Ejecutar los tests
-
-```bash
-[npm run test]
-
-# Si quieres ejecutar solo los tests de tu cambio:
-[comando específico — ej. npm run test -- --grep "Alert"]
-```
-
----
-
-## Paso 5: Commit y push
-
-### Hacer commit
-
-Seguir el formato de Conventional Commits (ver [`dev-workflow.md`](../dev-workflow.md)):
-
-```bash
-git add [archivos modificados]
-git commit -m "feat([alcance]): descripción breve del cambio"
-```
-
-Ejemplos:
-
-```bash
-git commit -m "feat(ui): se añadió componente Alert con variantes success, warning y error"
-git commit -m "test(ui): se añadieron tests unitarios para componente Alert"
-```
-
-### Hacer push
-
-```bash
-git push -u origin feature/[nombre-de-tu-feature]
-```
-
----
-
-## Paso 6: Crear el Pull Request
-
-### En GitHub
-
-1. Ir al repositorio en GitHub.
-2. Click en "Compare & pull request".
-3. Llenar el template de PR (definido en [`dev-workflow.md`](../dev-workflow.md)):
-
-```markdown
-## Qué hace
-[Añadí el componente Alert con 3 variantes: success, warning y error.]
-
-## Por qué
-[El design system no tenía un componente estándar para alertas. Cada página implementaba su propio estilo.]
-
-## Cómo probar
-1. Arrancar el servidor con `npm run dev`
-2. Ir a la página de demo: `/demo/alerts`
-3. Verificar que las 3 variantes se renderizan correctamente
-4. Verificar que los tests pasan: `npm run test`
-
-## Checklist
-- [x] Tests añadidos
-- [x] Lint pasa sin errores
-- [ ] Documentación actualizada (verificar si DESIGN.md necesita update)
-```
-
-### Asignar reviewers
-
-Asignar al menos un reviewer según el área:
-- **UI/UX**: [Nombre del diseñador/a o frontend lead]
-- **Backend**: [Nombre del backend lead]
-- **General**: [Tech lead]
-
----
-
-## Paso 7: Responder al code review
-
-Es normal recibir comentarios. No tomarlos personalmente.
-
-1. **Leer todos los comentarios** antes de empezar a responder.
-2. **Clasificar**: blocker (🔴), sugerencia (🟡), nit (🟢).
-3. **Corregir** los blockers primero, luego las sugerencias.
-4. **Hacer commit** con los cambios:
-   ```bash
-   git commit -m "refactor([alcance]): se aplicó feedback del code review"
-   git push
-   ```
-5. **Pedir re-review** cuando termines.
-
----
-
-## Paso 8: Merge
-
-Una vez que el PR esté aprobado y CI pase:
-
-1. Hacer **squash merge** desde GitHub (o pedir a quien tenga permisos).
-2. Borrar la branch remota.
-3. Actualizar tu local:
-
-```bash
-git checkout main
-git pull origin main
-```
-
----
-
-## Checklist final
-
-Después de mergear, verificar:
-
-- [ ] ¿Se actualizó la documentación afectada? (Ver [`AGENTS.md`](../../AGENTS.md) checklist post-tarea.)
-- [ ] ¿Se añadió un término nuevo al dominio? → Actualizar [`CONTEXT.md`](../CONTEXT.md).
-- [ ] ¿Se tomó una decisión técnica? → Crear ADR en [`docs/adr/`](../adr/TEMPLATE.md).
-- [ ] ¿Se cambió algo visual? → Actualizar [`DESIGN.md`](../DESIGN.md).
-
----
-
-## Felicidades
-
-Acabas de completar tu primera contribución end-to-end. Ya conoces el flujo completo del proyecto. Para siguientes tareas, el proceso es el mismo: branch → código → tests → PR → review → merge.

package/templates/modules/tutorials/docs/tutorials/quick-start.md

@@ -1,146 +0,0 @@
----
-created: "2025-01-01"
-status: active
-type: tutorial
-tags: [tutorial, quick-start, inicio, setup]
----
-
-# Quick Start — Arrancar en 15 minutos
-
-Este tutorial te lleva desde cero hasta tener el proyecto corriendo localmente. Al terminar, tendrás el servidor de desarrollo funcionando y podrás hacer tu primer cambio.
-
-**Tiempo estimado**: 15 minutos.
-**Audiencia**: Developers que se incorporan al proyecto por primera vez.
-
----
-
-## Prerrequisitos
-
-Antes de empezar, necesitas tener instalado:
-
-| Herramienta | Versión mínima | Cómo verificar | Cómo instalar |
-|------------|---------------|----------------|---------------|
-| **[Node.js / Python / etc.]** | [versión] | `[node --version]` | [nodejs.org / enlace] |
-| **[Git]** | [versión] | `git --version` | [git-scm.com] |
-| **[Package manager]** | [versión] | `[npm --version]` | Viene con Node.js |
-| **[Editor recomendado]** | — | — | [VS Code / etc.] |
-
-Si necesitas ayuda con la instalación completa, ver [`environment-setup.md`](environment-setup.md).
-
----
-
-## Paso 1: Clonar el repositorio
-
-```bash
-git clone [URL_DEL_REPOSITORIO]
-cd [NOMBRE_DEL_PROYECTO]
-```
-
-Verificar que estás en la branch correcta:
-
-```bash
-git branch
-# Debería mostrar: * main
-```
-
----
-
-## Paso 2: Instalar dependencias
-
-```bash
-[npm install]
-```
-
-Este comando descarga todas las dependencias del proyecto. Si hay errores:
-
-- Verificar que la versión de [Node / Python] sea la correcta.
-- Borrar `[node_modules]` y `[package-lock.json]` y volver a ejecutar.
-- Si persiste, ver [`troubleshooting.md`](../guides/troubleshooting.md).
-
----
-
-## Paso 3: Configurar variables de entorno
-
-Copiar el archivo de ejemplo:
-
-```bash
-cp .env.example .env
-```
-
-Abrir `.env` y completar los valores necesarios. Los valores mínimos para desarrollo local son:
-
-```env
-# Obligatorios para arrancar
-APP_ENV=development
-APP_PORT=3000
-[DATABASE_URL]=[URL de desarrollo local]
-
-# Opcionales (tienen defaults para desarrollo)
-[LOG_LEVEL]=debug
-```
-
-Ver la referencia completa de variables en [`docs/reference/configuration.md`](../reference/configuration.md).
-
----
-
-## Paso 4: Inicializar la base de datos *(si aplica)*
-
-```bash
-[comando de migración — ej. npm run db:migrate]
-```
-
-Opcionalmente, cargar datos de prueba:
-
-```bash
-[comando de seed — ej. npm run db:seed]
-```
-
----
-
-## Paso 5: Arrancar el servidor de desarrollo
-
-```bash
-[npm run dev]
-```
-
-Deberías ver algo como:
-
-```
-✓ Servidor iniciado en http://localhost:3000
-✓ Hot-reload activo
-```
-
-Abrir `http://localhost:3000` en el navegador. Deberías ver [la página principal / el dashboard / la landing].
-
----
-
-## Paso 6: Verificar que todo funciona
-
-Ejecutar los tests:
-
-```bash
-[npm run test]
-```
-
-Todos deberían pasar (verde). Si algún test falla:
-
-- Verificar que la base de datos esté configurada correctamente.
-- Verificar que las variables de entorno estén completas.
-- Ver [`troubleshooting.md`](../guides/troubleshooting.md).
-
-Ejecutar el linter:
-
-```bash
-[npm run lint]
-```
-
-No debería mostrar errores.
-
----
-
-## Siguientes pasos
-
-- Para configurar tu entorno completo (editor, extensiones, herramientas): [`environment-setup.md`](environment-setup.md).
-- Para hacer tu primera contribución (branch → código → PR): [`first-task.md`](first-task.md).
-- Para entender la arquitectura del proyecto: [`docs/explanation/architecture.md`](../explanation/architecture.md).
-- Para conocer el vocabulario del dominio: [`docs/CONTEXT.md`](../CONTEXT.md).