@qubiit/lmagent 2.5.0

package/docs/how-to-start.md

@@ -0,0 +1,242 @@
+# Cómo Empezar un Proyecto con LMAgent
+
+> **LMAgent Framework v3.0 (SPEC+LM)**
+> 
+> Esta guía explica el proceso automatizado para iniciar un nuevo proyecto.
+
+---
+
+## 🎯 Resumen del Flujo
+
+```
+┌─────────────────────────────────────────────────────────────────────────────┐
+│                    FLUJO AUTOMATIZADO DE INICIO                              │
+│                                                                              │
+│   DESARROLLADOR                           AGENTE DE IA                       │
+│   ─────────────                           ─────────────                       │
+│                                                                              │
+│   1. Crear carpeta del proyecto                                              │
+│         │                                                                    │
+│         ▼                                                                    │
+│   2. Crear PROJECT_KICKOFF.md ──────────┐                                   │
+│      (5-10 minutos)                     │                                   │
+│                                          │                                   │
+│   3. Abrir en IDE agéntico              │                                   │
+│         │                                │                                   │
+│         ▼                               ▼                                   │
+│   ┌─────────────────────────────────────────────────────────────────────┐   │
+│   │                    AUTOMÁTICO (Sin intervención)                     │   │
+│   │                                                                      │   │
+│   │   4. Agente detecta PROJECT_KICKOFF.md                               │   │
+│   │   5. Ejecuta: lmagent init                                          │   │
+│   │   6. Ejecuta: /spec workflow                                         │   │
+│   │   7. Crea: spec.yaml → plan.yaml → tasks.yaml                       │   │
+│   │   8. Implementa código siguiendo tasks                               │   │
+│   │   9. Tests + Documentación                                           │   │
+│   │                                                                      │   │
+│   └─────────────────────────────────────────────────────────────────────┘   │
+│                                                                              │
+│   10. USUARIO: Revisar y aprobar cada fase                                  │
+│                                                                              │
+└─────────────────────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## 📋 Paso a Paso
+
+### Paso 1: Crear Carpeta del Proyecto
+
+```bash
+mkdir mi-nuevo-proyecto
+cd mi-nuevo-proyecto
+```
+
+### Paso 2: Crear PROJECT_KICKOFF.md
+
+Copia el template desde el repositorio de LMAgent:
+
+```bash
+# Si tienes LMAgent instalado globalmente:
+lmagent kickoff
+
+# O manualmente, copia el archivo:
+cp /path/to/lmagent/templates/PROJECT_KICKOFF.md ./PROJECT_KICKOFF.md
+```
+
+### Paso 3: Completar el Template (OPCIONAL)
+
+Abre `PROJECT_KICKOFF.md` y tienes DOS opciones:
+
+#### Opción A: Completar manualmente (5-10 minutos)
+Llena las secciones marcadas con `[...]`. Solo necesitas:
+- Nombre del proyecto
+- Descripción en una línea
+- Tipo de proyecto
+- Usuario principal
+- Problema a resolver
+- 2-5 features MUST HAVE
+
+#### Opción B: Dejar que el agente pregunte
+Si no completas el template, el agente detectará que está vacío y te hará las preguntas necesarias en el chat:
+
+```
+Agente: "Detecté que este es un proyecto nuevo. Voy a hacerte 
+        algunas preguntas para entender qué quieres construir."
+        
+        "¿Cómo se llama tu proyecto?"
+        
+Tú:     "NutriTrack AI"
+
+Agente: "En una frase, ¿qué es y para quién?"
+
+Tú:     "App para rastrear nutrición con IA que analiza fotos de comida"
+
+... (5-7 preguntas en total)
+```
+
+### Paso 4: Abrir en tu IDE Agéntico
+
+Abre la carpeta del proyecto en tu IDE favorito:
+
+| IDE | Cómo Abrir |
+|-----|-----------|
+| **Cursor** | `cursor .` |
+| **Claude Code** | `claude .` |
+| **Antigravity** | Abrir carpeta en VS Code + extensión |
+| **Copilot** | Abrir en VS Code |
+
+### Paso 5: El Agente Toma el Control 🤖
+
+Una vez que el IDE agéntico analice tu carpeta, detectará `PROJECT_KICKOFF.md` y comenzará automáticamente:
+
+1. **Detecta Framework** → Inicializa LMAgent
+2. **Lee tu Kickoff** → Entiende el proyecto
+3. **Ejecuta /spec** → Crea especificación formal
+4. **Te muestra spec.yaml** → Pide aprobación
+5. **Diseña arquitectura** → Crea plan.yaml
+6. **Te muestra el plan** → Pide aprobación
+7. **Crea tasks** → Desglose de implementación
+8. **Implementa** → Código real
+
+---
+
+## 🔄 Puntos de Aprobación
+
+El agente se detendrá y pedirá tu aprobación en estos puntos:
+
+```
+┌────────────────┐
+│  spec.yaml     │ ← "¿Está bien el alcance y las features?"
+└───────┬────────┘
+        │ ✅ Aprobado
+        ▼
+┌────────────────┐
+│  plan.yaml     │ ← "¿Está bien la arquitectura y el plan?"
+└───────┬────────┘
+        │ ✅ Aprobado
+        ▼
+┌────────────────┐
+│  tasks.yaml    │ ← "¿Puedo empezar a implementar?"
+└───────┬────────┘
+        │ ✅ Aprobado
+        ▼
+  🚀 IMPLEMENTACIÓN
+```
+
+---
+
+## 📂 Estructura Final del Proyecto
+
+Después del proceso, tu proyecto tendrá esta estructura:
+
+```
+mi-nuevo-proyecto/
+├── PROJECT_KICKOFF.md     # Tu input original
+├── AGENTS.md              # Main entry point de LMAgent
+├── .lmagent               # Marker del framework
+├── README.md              # Generado automáticamente
+│
+├── specs/
+│   └── mi-nuevo-proyecto/
+│       ├── spec.yaml      # Especificación formal
+│       ├── plan.yaml      # Plan de arquitectura
+│       └── tasks.yaml     # Tasks desglosadas
+│
+├── src/                   # Código fuente
+│   ├── app/              
+│   ├── services/
+│   └── ...
+│
+├── tests/                 # Tests automatizados
+│
+├── docs/                  # Documentación
+│   └── adr/               # Architecture Decision Records
+│
+├── docker-compose.yml     # Si aplica
+└── pyproject.toml         # O package.json
+```
+
+---
+
+## ⚡ Comandos Útiles
+
+Una vez que el proyecto está inicializado:
+
+| Comando | Qué Hace |
+|---------|----------|
+| `/spec status` | Ver estado del spec actual |
+| `/spec validate` | Validar implementación vs spec |
+| `/pm` | Activar Product Manager para cambios de requisitos |
+| `/arch` | Activar Architect para decisiones técnicas |
+| `/dev` | Activar Developer para implementar |
+| `/qa` | Activar QA para testing |
+
+---
+
+## ❓ FAQ
+
+### ¿Qué pasa si quiero cambiar algo después?
+
+Simplemente dile al agente:
+```
+"Quiero agregar feature X al proyecto"
+```
+El agente actualizará spec.yaml y te pedirá aprobación.
+
+### ¿Puedo usar LMAgent en un proyecto existente?
+
+Sí, ejecuta:
+```bash
+cd mi-proyecto-existente
+lmagent init
+```
+Luego crea un PROJECT_KICKOFF.md describiendo lo que quieres agregar.
+
+### ¿Qué IDEs son compatibles?
+
+- ✅ Cursor
+- ✅ Claude Code
+- ✅ Antigravity (VS Code)
+- ✅ GitHub Copilot
+- ✅ Windsurf
+- ✅ Roo Code
+
+---
+
+## 🎬 Video Demo (Conceptual)
+
+```
+00:00 - Crear carpeta y PROJECT_KICKOFF.md
+00:05 - Completar template (fast-forward)
+00:15 - Abrir en Cursor
+00:20 - Agente detecta y comienza
+00:30 - spec.yaml generado, revisión
+00:40 - plan.yaml generado, revisión
+00:50 - Implementación automática
+02:00 - Proyecto MVP funcionando 🎉
+```
+
+---
+
+*LMAgent v3.0 (SPEC+LM) - Build More, Automate Dreams* 🚀

package/docs/navigation-index.md

@@ -0,0 +1,227 @@
+# LMAgent Framework - Navigation Index
+
+> **Quick Reference**: Find any resource in the framework instantly.
+> 
+> **Versión**: 3.0 (SPEC+LM) | **Actualizado**: 2026-01
+
+---
+
+## 🎯 Entry Points (Start Here)
+
+| Archivo | Propósito | Cuándo Leer |
+|---------|-----------|-------------|
+| [AGENTS.md](../AGENTS.md) | **Main entry point** - Visual flow, commands, rules | ⭐ SIEMPRE primero |
+| [README.md](../README.md) | Overview del proyecto, instalación | Setup inicial |
+| [.agent/README.md](../.agent/README.md) | Config para Antigravity | Si usas Antigravity IDE |
+| [CLAUDE.md](../CLAUDE.md) | Config para Claude Code | Si usas Claude Code |
+| [.cursorrules](../.cursorrules) | Config para Cursor | Si usas Cursor |
+
+---
+
+## 👥 Personas & Metodologías (21 Total)
+
+### Roles de Producto & Gestión
+
+| Persona | Archivo | Trigger | Especialidad |
+|---------|---------|---------|--------------|
+| **Orchestrator** | [orchestrator.md](../personas/orchestrator.md) | `/orch` | Meta-routing, coordinación |
+| **Product Manager** | [product-manager.md](../personas/product-manager.md) | `/pm` | Requisitos, PRDs, spec.yaml |
+| **Scrum Master** | [scrum-master.md](../personas/scrum-master.md) | `/sm` | Agile, procesos, facilitación |
+| **Tech Lead** | [tech-lead.md](../personas/tech-lead.md) | `/lead` | Decisiones técnicas, mentoring |
+
+### Roles de Ingeniería
+
+| Persona | Archivo | Trigger | Especialidad |
+|---------|---------|---------|--------------|
+| **Architect** | [architect.md](../personas/architect.md) | `/arch` | Diseño de sistemas, ADRs |
+| **Backend Engineer** | [backend-engineer.md](../personas/backend-engineer.md) | `/dev` | Python, FastAPI, APIs |
+| **Frontend Engineer** | [frontend-engineer.md](../personas/frontend-engineer.md) | `/frontend` | React, TypeScript |
+| **Mobile Engineer** | [mobile-engineer.md](../personas/mobile-engineer.md) | `/mobile` | React Native |
+| **DevOps Engineer** | [devops-engineer.md](../personas/devops-engineer.md) | `/devops` | CI/CD, Docker, K8s |
+| **Data Engineer** | [data-engineer.md](../personas/data-engineer.md) | `/dba` | SQL, PostgreSQL, pipelines |
+
+### Roles de IA & Automatización
+
+| Persona | Archivo | Trigger | Especialidad |
+|---------|---------|---------|--------------|
+| **AI Agent Engineer** | [ai-agent-engineer.md](../personas/ai-agent-engineer.md) | `/ai` | Agentes, RAG, LangChain |
+| **Prompt Engineer** | [prompt-engineer.md](../personas/prompt-engineer.md) | `/prompt` | System prompts, CoT |
+| **Automation Engineer** | [automation-engineer.md](../personas/automation-engineer.md) | `/auto` | n8n, webhooks |
+
+### Roles de Calidad & Seguridad
+
+| Persona | Archivo | Trigger | Especialidad |
+|---------|---------|---------|--------------|
+| **QA Engineer** | [qa-engineer.md](../personas/qa-engineer.md) | `/qa` | Testing, E2E |
+| **Security Analyst** | [security-analyst.md](../personas/security-analyst.md) | `/sec` | OWASP, compliance |
+| **Performance Engineer** | [performance-engineer.md](../personas/performance-engineer.md) | `/perf` | Optimización |
+
+### Roles de Documentación & UX
+
+| Persona | Archivo | Trigger | Especialidad |
+|---------|---------|---------|--------------|
+| **Technical Writer** | [technical-writer.md](../personas/technical-writer.md) | `/writer` | Documentación |
+| **UX/UI Designer** | [ux-ui-designer.md](../personas/ux-ui-designer.md) | `/ux` | Diseño, a11y |
+
+### Metodologías
+
+| Metodología | Archivo | Trigger | Especialidad |
+|---------|---------|---------|--------------|
+| **BMAD Methodology** | [bmad-methodology](../skills/bmad-methodology/SKILL.md) | `/bmad` | Scale-Adaptive Intelligence, kickoff |
+| **SWE-Agent** | [swe-agent](../skills/swe-agent/SKILL.md) | `/swe` | Resolución autónoma de issues |
+| **Spec-Driven Dev** | [spec-driven-dev](../skills/spec-driven-dev/SKILL.md) | `/spec-dev` | Pipeline SPECIFY→PLAN→TASKS→IMPL→VERIFY |
+
+---
+
+## 📋 Workflows (13 Total)
+
+| Workflow | Archivo | Trigger | Nivel | Uso |
+|----------|---------|---------|-------|-----|
+| **SPEC DRIVEN** | [spec-driven.md](../workflows/spec-driven.md) | `/spec` | 2-4 | ⭐ Desarrollo completo |
+| New Automation | [new-automation.md](../workflows/new-automation.md) | `/new-auto` | 2-3 | Backend + n8n |
+| New AI Agent | [new-agent-ia.md](../workflows/new-agent-ia.md) | `/new-agent` | 2-3 | Crear agente IA |
+| Bugfix Backend | [bugfix-backend.md](../workflows/bugfix-backend.md) | `/fix` | 1-2 | Arreglar bugs |
+| Optimize Performance | [optimize-performance.md](../workflows/optimize-performance.md) | `/perf` | 2-3 | Optimización |
+| Resolve GitHub Issue | [resolve-github-issue.md](../workflows/resolve-github-issue.md) | `/issue` | 1-3 | Issues automáticos |
+| Security Review | [security-review.md](../workflows/security-review.md) | `/sec-review` | 2-4 | Auditoría |
+| Generate PRD | [generate-prd.md](../workflows/generate-prd.md) | `/prd` | 2 | Documentos de producto |
+| Ideation | [ideation.md](../workflows/ideation.md) | `/brainstorm` | 1-2 | Ideación |
+| New Feature | [new-feature.md](../workflows/new-feature.md) | `/feature` | 2-3 | Features nuevos |
+| Testing Strategy | [testing-strategy.md](../workflows/testing-strategy.md) | `/test-plan` | 2 | Estrategia de tests |
+| Third Party Integration | [third-party-integration.md](../workflows/third-party-integration.md) | `/integrate` | 2-3 | Integraciones |
+| Documentation | [documentation.md](../workflows/documentation.md) | `/docs` | 1-2 | Documentar |
+
+---
+
+## 📏 Rules (9 Total)
+
+| Regla | Archivo | Prioridad | Descripción |
+|-------|---------|-----------|-------------|
+| **Documentation** | [documentation.md](../rules/documentation.md) | ⚠️ CRÍTICA | Documentar cambios siempre |
+| Stack | [stack.md](../rules/stack.md) | Alta | Stack tecnológico |
+| Workflow | [workflow.md](../rules/workflow.md) | Alta | Flujo de trabajo |
+| Code Style | [code-style.md](../rules/code-style.md) | Alta | Guías de estilo |
+| Agents IA | [agents-ia.md](../rules/agents-ia.md) | Alta | Reglas para agentes |
+| Automations n8n | [automations-n8n.md](../rules/automations-n8n.md) | Media | n8n patterns |
+| API Design | [api-design.md](../rules/api-design.md) | Media | Diseño de APIs |
+| Security | [security.md](../rules/security.md) | Alta | Seguridad |
+| Testing | [testing.md](../rules/testing.md) | Alta | Estrategias de testing |
+
+---
+
+## ✅ Checklists (5 Niveles)
+
+| Nivel | Archivo | Tiempo | Confirmación |
+|-------|---------|--------|--------------|
+| Level 0: Trivial | [level-0-trivial.md](../checklists/level-0-trivial.md) | <5 min | No |
+| Level 1: Small | [level-1-small.md](../checklists/level-1-small.md) | 5-30 min | No |
+| Level 2: Medium | [level-2-medium.md](../checklists/level-2-medium.md) | 30m-2h | Sí |
+| Level 3: Complex | [level-3-complex.md](../checklists/level-3-complex.md) | 2-8h | Sí + Artefactos |
+| Level 4: Enterprise | [level-4-enterprise.md](../checklists/level-4-enterprise.md) | 8h+ | Governance |
+
+---
+
+## 📄 Templates (SPEC DRIVEN)
+
+| Template | Archivo | Cuándo Usar |
+|----------|---------|-------------|
+| **PROJECT_KICKOFF.md** | [PROJECT_KICKOFF.md](../templates/PROJECT_KICKOFF.md) | ⭐ **INICIO**: Entry point para proyectos nuevos |
+| **spec.yaml** | [spec.yaml](../templates/spec.yaml) | Fase 1: Especificación |
+| **plan.yaml** | [plan.yaml](../templates/plan.yaml) | Fase 2: Plan de implementación |
+| **tasks.yaml** | [tasks.yaml](../templates/tasks.yaml) | Fase 3: Tasks ejecutables |
+| **session.yaml** | [session.yaml](../templates/session.yaml) | Estado persistente del proyecto |
+| **checkpoint.yaml** | [checkpoint.yaml](../templates/checkpoint.yaml) | Auto-backups de estado |
+| Agent Python | [agent-python/](../templates/agent-python/) | Scaffold para agentes IA |
+| Backend Python | [backend-python/](../templates/backend-python/) | Scaffold para backend FastAPI |
+| Frontend React | [frontend-react/](../templates/frontend-react/) | Scaffold para frontend React |
+| Database | [database/](../templates/database/) | Esquemas de DB |
+
+**Flujo único**: `PROJECT_KICKOFF.md` → `spec.yaml` → `plan.yaml` → `tasks.yaml` → CODE
+
+---
+
+## ⚙️ Configuration
+
+| Config | Archivo | Descripción |
+|--------|---------|-------------|
+| Settings | [settings.yaml](../config/settings.yaml) | Configuración global |
+| Levels | [levels.yaml](../config/levels.yaml) | Sistema de niveles |
+| Tools | [tools.yaml](../config/tools.yaml) | Registry de herramientas |
+| Tools Extended | [tools-extended.yaml](../config/tools-extended.yaml) | Tools adicionales |
+| Commands | [commands.yaml](../config/commands.yaml) | Aliases de comandos |
+| Models | [models.yaml](../config/models.yaml) | Configuración de LLMs |
+
+---
+
+## 🔍 "What to Read When..."
+
+| Situación | Único Archivo a Leer |
+|-----------|---------------------|
+| **Proyecto nuevo (desde cero)** | `templates/PROJECT_KICKOFF.md` → completar → el agente hace el resto |
+| **Proyecto existente + LMAgent** | `AGENTS.md` (entry point) |
+| **Feature nuevo (L2+)** | Ejecutar `/spec [nombre]` |
+| **Bug fix rápido** | `workflows/bugfix-backend.md` |
+| **No sé qué persona usar** | Usar `/orch` (Orchestrator decide) |
+
+### Flujo Único para Proyectos Nuevos
+
+```
+DESARROLLADOR                              AGENTE
+────────────                               ──────
+     │
+     ▼
+Crear PROJECT_KICKOFF.md
+(5-10 minutos)
+     │
+     ▼
+Abrir en IDE ─────────────────────────────▶ Detecta PROJECT_KICKOFF.md
+                                                    │
+                                                    ▼
+                                            Ejecuta /spec workflow
+                                                    │
+                                                    ▼
+                                            spec.yaml (← Aprobación)
+                                                    │
+                                                    ▼
+                                            plan.yaml (← Aprobación)
+                                                    │
+                                                    ▼
+                                            tasks.yaml
+                                                    │
+                                                    ▼
+                                            CÓDIGO + TESTS
+                                                    │
+                                                    ▼
+                                            PROYECTO LISTO ✅
+```
+
+---
+
+## 🗺️ Relationship Map
+
+```
+                        ┌─────────────┐
+                        │  AGENTS.md  │ ← Main Entry Point
+                        └──────┬──────┘
+                               │
+          ┌────────────────────┼────────────────────┐
+          │                    │                    │
+          ▼                    ▼                    ▼
+    ┌───────────┐       ┌───────────┐       ┌───────────┐
+    │  personas │       │ workflows │       │   rules   │
+    │  (18)     │       │   (13)    │       │   (9)     │
+    └─────┬─────┘       └─────┬─────┘       └─────┬─────┘
+          │                   │                   │
+          │            ┌──────┴──────┐            │
+          │            │             │            │
+          ▼            ▼             ▼            ▼
+    ┌───────────┐ ┌───────────┐ ┌───────────┐ ┌───────────┐
+    │ templates │ │ checklists│ │  config   │ │   docs    │
+    │    (8)    │ │    (5)    │ │    (6)    │ │   (4)     │
+    └───────────┘ └───────────┘ └───────────┘ └───────────┘
+```
+
+---
+
+*LMAgent Framework v3.0 (SPEC+LM)*
+*Navigation Index - Updated 2026-01*

package/docs/usage-guide.md

@@ -0,0 +1,113 @@
+# Guía de Uso Completa de LMAgent
+
+Esta guía detalla cómo sacar el máximo provecho al framework LMAgent en tu día a día.
+
+## Flujo de Trabajo Mental
+
+Cuando le pidas algo al agente, sigue este patrón mental para obtener los mejores resultados:
+
+1. **¿QUIÉN debe hacerlo?** → Selecciona la Persona (`/dev`, `/pm`, `/arch`)
+2. **¿QUÉ tan complejo es?** → Define el Nivel (0-4)
+3. **¿CÓMO debe hacerlo?** → Selecciona un Workflow o Regla
+
+---
+
+## 1. Trabajando con Personas
+
+Las personas no son solo "prompts"; son contextos completos con instrucciones específicas.
+
+### Cómo activarlas
+Simplemente menciónalas en el chat o usa su trigger:
+
+> "Actúa como **/product-manager** para analizar este requerimiento."
+> "Hola **/arch**, necesito diseñar un nuevo microservicio."
+
+### Cuándo cambiar de persona
+Es común cambiar de persona durante una tarea compleja:
+
+1. **Inicio**: `/pm` analiza el pedido y crea User Stories.
+2. **Diseño**: `/arch` revisa las stories y define la estructura de DB y API.
+3. **Desarrollo**: `/dev` toma el diseño e implementa el código.
+4. **Revisión**: `/qa` escribe los tests para validar el código.
+5. **Prompting**: `/prompt` ajusta el system prompt del agente creado.
+6. **Cierre**: `/tech-writer` actualiza la documentación.
+
+---
+
+## 2. El Sistema de Niveles (The Thinking Process)
+
+El error #1 de los agentes es "correr a escribir código" sin entender el problema. Los niveles fuerzan un momento de planificación.
+
+### Tipos de Niveles
+
+| Nivel | Cuándo usarlo | Comportamiento del Agente |
+|-------|---------------|---------------------------|
+| **L0 (Trivial)** | Typos, logs, fixes obvios de 1 línea | Ejecuta directo. Sin preámbulos. |
+| **L1 (Small)** | Funciones pequeñas, tweaks de UI | Piensa brevemente, confirma, ejecuta. |
+| **L2 (Medium)** | Features completos, endpoints nuevos | **STOP & PLAN**. Crea `implementation_plan.md`. Pide OK. |
+| **L3 (Complex)** | Refactors grandes, integraciones | Plan extenso. Verifica impactos. Pide revisión de `/arch`. |
+| **L4 (Enterprise)** | Migraciones, cambios críticos de seguridad | Plan paranoico. Plan de rollback. Múltiples confirmaciones. |
+
+### Cómo usarlos
+Dile al agente explícitamente o deja que él clasifique:
+> "Esto es una tarea **Level 2**. Haz un plan primero."
+
+---
+
+## 3. Workflows: Autopistas al Éxito
+
+Los workflows son "recetas" paso a paso para tareas comunes. Garantizan consistencia.
+
+### Workflows más usados
+
+- **/new-feature**: Para crear algo nuevo de punta a punta.
+- **/fix**: Para debugging sistemático (no adivinar).
+- **/refactor**: Para mejorar código sin romper nada.
+- **/test**: Para generar estrategias de testing.
+
+### Cómo invocarlos
+> "Usa el workflow **/fix** para arreglar este error en producción."
+
+---
+
+## 4. Reglas y Documentación Continua
+
+LMAgent tiene una "memoria muscular" basada en reglas.
+
+### Reglas Globales (`.agent/rules/`)
+Aplican a todos los proyectos. Ej: "Siempre usar English para nombres de variables".
+
+### Reglas de Proyecto (`.agent/rules/project.md`)
+Específicas de ESTE proyecto. Ej: "Los endpoints deben empezar con `/api/v1`".
+
+### La Regla de Oro: Documentación Continua
+Si el agente o tú descubren algo nuevo (un truco, un bug recurrente, una decisión de diseño), **DEBEN** escribirlo en una nueva regla o actualizar la documentación.
+
+> "Agente, aprendimos que la librería X falla con Y. Crea una regla en `rules/tech-stack.md` para evitar esto en el futuro."
+
+---
+
+## 5. Artefactos (Tu Memoria Externa)
+
+El agente usa archivos Markdown para mantener el contexto entre sesiones.
+
+- **`task.md`**: El estado actual. Qué hicimos, qué falta.
+- **`implementation_plan.md`**: El plan detallado (para L2+).
+- **`tech_spec.md`**: Especificaciones técnicas complejas.
+- **`walkthrough.md`**: Guía visual de lo que se construyó (al final).
+
+**Tip**: Si el agente "olvida" algo, dile que lea los artefactos:
+> "Lee `task.md` y dime qué sigue."
+
+---
+
+## FAQ
+
+**Q: El agente se queda atascado en un bucle.**
+A: Dile "STOP". Pídele que revise sus últimos pasos, identifique el error y proponga un enfoque alternativo. Cambia a L2 para forzar planificación.
+
+**Q: El agente ignora mis reglas.**
+A: Recuérdaselo explícitamente: "Revisa `rules/code-style.md` antes de escribir código". Asegúrate que la regla sea clara y esté en la carpeta correcta.
+
+**Q: ¿Puedo crear mis propias personas?**
+A: ¡Sí! Crea un archivo `.md` en `.agent/personas/` siguiendo el formato de los existentes.