@qubiit/lmagent 2.5.0

package/docs/customization-guide.md

@@ -0,0 +1,445 @@
+# LMAgent Customization Guide
+
+Esta guía explica cómo personalizar el framework LMAgent para las necesidades de tu equipo.
+
+## Tabla de Contenidos
+
+1. [Configuración Inicial](#configuración-inicial)
+2. [Personalizar Niveles](#personalizar-niveles)
+3. [Crear Personas Custom](#crear-personas-custom)
+4. [Agregar Herramientas](#agregar-herramientas)
+5. [Crear Workflows Custom](#crear-workflows-custom)
+6. [Configurar Modelos LLM](#configurar-modelos-llm)
+7. [Extensiones](#extensiones)
+
+---
+
+## Configuración Inicial
+
+### 1. Clonar y Configurar
+
+```bash
+# Clonar el repo
+git clone https://github.com/tu-org/lmagent-template.git mi-proyecto
+cd mi-proyecto
+
+# Configurar información del proyecto
+# Editar config/settings.yaml
+```
+
+### 2. Personalizar settings.yaml
+
+```yaml
+# config/settings.yaml
+
+project:
+  name: "Mi Proyecto"
+  description: "Descripción de mi proyecto"
+  team: "Mi Equipo"
+  version: "0.1.0"
+
+agent_behavior:
+  language: "es"  # Idioma preferido
+  autonomy:
+    mode: "auto"  # auto, always_ask, never_ask
+```
+
+### 3. Variables de Entorno
+
+```bash
+# Copiar template
+cp .env.example .env
+
+# Configurar tus API keys
+OPENAI_API_KEY=sk-...
+DATABASE_URL=postgresql://...
+REDIS_URL=redis://...
+```
+
+---
+
+## Personalizar Niveles
+
+### Opción 1: Ajustar Tiempos
+
+Si tu equipo es más rápido o lento que el promedio:
+
+```yaml
+# config/settings.yaml
+levels:
+  time_multiplier: 1.5  # 1.5x más lento que default
+```
+
+### Opción 2: Crear Niveles Custom
+
+```yaml
+# config/levels-custom.yaml
+# Luego en settings.yaml:
+levels:
+  use_custom: true
+  custom_file: "config/levels-custom.yaml"
+```
+
+Ejemplo de level custom:
+
+```yaml
+levels:
+  0:
+    name: "Micro"
+    description: "Cambios de < 1 minuto"
+    planning_required: false
+    estimated_time: "< 1 min"
+    
+  5:
+    name: "Multi-Team"
+    description: "Proyectos que involucran múltiples equipos"
+    planning_required: true
+    planning_depth: "strategic"
+    estimated_time: "1+ mes"
+    human_review: true
+    human_approval_required: true
+    artifacts:
+      - project_charter.md
+      - implementation_plan.md
+      - architecture.md
+      - test_plan.md
+      - security_review.md
+      - rollback_plan.md
+      - communication_plan.md
+```
+
+### Agregar Reglas de Auto-Clasificación
+
+```yaml
+# config/settings.yaml
+levels:
+  auto_classification:
+    level_bumps:
+      # Tus patrones custom
+      - pattern: "*payment*"
+        min_level: 3
+        reason: "Cambios de pagos son críticos"
+      
+      - pattern: "*api/v2/*"
+        min_level: 2
+        reason: "API v2 requiere más cuidado"
+```
+
+---
+
+## Crear Personas Custom
+
+### 1. Crear Archivo de Persona
+
+```markdown
+# personas/custom/devops-engineer.md
+
+---
+name: DevOps Engineer
+role: Infrastructure and CI/CD
+expertise:
+  - Docker/Kubernetes
+  - CI/CD pipelines
+  - Cloud infrastructure
+  - Monitoring
+activates_on:
+  - Cambios de Dockerfile
+  - Configuración de CI/CD
+  - Infrastructure as Code
+---
+
+# DevOps Engineer Persona
+
+Eres un DevOps Engineer especializado en...
+
+## Responsabilidades
+1. ...
+
+## Stack
+- Docker, Kubernetes
+- GitHub Actions
+- Terraform
+- ...
+
+## Patrones
+...
+```
+
+### 2. Habilitar en Settings
+
+```yaml
+# config/settings.yaml
+personas:
+  allow_custom: true
+  custom_directory: "personas/custom"
+  enabled:
+    - product-manager
+    - architect
+    - backend-engineer
+    - devops-engineer  # Tu persona custom
+```
+
+---
+
+## Agregar Herramientas
+
+### 1. Definir en tools.yaml
+
+```yaml
+# config/tools.yaml
+
+tools:
+  # Tu herramienta custom
+  jira_integration:
+    name: "Jira Integration"
+    module: "agents.python.tools.jira_tool"
+    class: "JiraTool"
+    description: "Interact with Jira for issue management"
+    category: "project_management"
+    parameters:
+      - name: action
+        type: string
+        enum: [get_issue, create_issue, update_status]
+        required: true
+      - name: issue_key
+        type: string
+        required: false
+      - name: data
+        type: object
+        required: false
+    requires:
+      - JIRA_URL
+      - JIRA_API_TOKEN
+```
+
+### 2. Implementar la Herramienta
+
+```python
+# agents/python/tools/jira_tool.py
+
+from lmagent.tools.base import BaseTool, ToolResult
+from pydantic import Field
+import httpx
+
+class JiraTool(BaseTool):
+    """
+    Interactúa con Jira para gestión de issues.
+    
+    Usa esta herramienta cuando necesites:
+    - Obtener información de un issue
+    - Crear nuevos issues
+    - Actualizar estados
+    """
+    
+    name: str = "jira_integration"
+    description: str = "Interact with Jira for issue management"
+    
+    async def execute(
+        self,
+        action: str = Field(..., description="Action: get_issue, create_issue, update_status"),
+        issue_key: str = Field(None, description="Issue key for get/update"),
+        data: dict = Field(None, description="Data for create/update")
+    ) -> ToolResult:
+        """Execute Jira operation."""
+        # Implementación...
+        pass
+```
+
+### 3. Habilitar en Settings
+
+```yaml
+# config/settings.yaml
+tools:
+  default_enabled:
+    - http_request
+    - database_query
+    - jira_integration  # Tu tool
+```
+
+---
+
+## Crear Workflows Custom
+
+### 1. Crear Archivo de Workflow
+
+```markdown
+# workflows/custom/deploy-to-production.md
+
+---
+description: Workflow para deploy a producción
+level: 3
+personas: [devops-engineer, backend-engineer]
+---
+
+# Deploy to Production Workflow
+
+## Pre-requisitos
+1. Código mergeado a main
+2. Tests pasando
+3. Aprobación de QA
+
+## Paso 1: Pre-deploy Checks
+...
+
+## Paso 2: Deploy
+...
+
+## Paso 3: Verification
+...
+
+## Rollback
+...
+```
+
+### 2. Habilitar en Settings
+
+```yaml
+# config/settings.yaml
+workflows:
+  allow_custom: true
+  custom_directory: "workflows/custom"
+  enabled:
+    - new-automation
+    - deploy-to-production  # Tu workflow
+```
+
+---
+
+## Configurar Modelos LLM
+
+### Agregar Proveedor Custom
+
+```yaml
+# config/models.yaml
+
+providers:
+  # Tu proveedor custom
+  azure_openai:
+    name: "Azure OpenAI"
+    api_base: "https://your-resource.openai.azure.com/"
+    env_key: "AZURE_OPENAI_API_KEY"
+    models:
+      gpt-4:
+        name: "GPT-4 (Azure)"
+        context_window: 128000
+        max_output: 4096
+        cost_per_1k_input: 0.03
+        cost_per_1k_output: 0.06
+        supports_tools: true
+```
+
+### Configurar por Tipo de Tarea
+
+```yaml
+# config/models.yaml
+
+task_models:
+  # Tu configuración custom
+  financial_analysis:
+    primary: "openai/o1"
+    fallback: "anthropic/claude-sonnet-4"
+    reason: "O1 para análisis financiero complejo"
+```
+
+---
+
+## Extensiones
+
+### Estructura de Extensión
+
+```
+extensions/
+└── my-extension/
+    ├── extension.yaml    # Metadata
+    ├── __init__.py
+    ├── tools/            # Tools adicionales
+    ├── workflows/        # Workflows adicionales
+    └── personas/         # Personas adicionales
+```
+
+### extension.yaml
+
+```yaml
+name: "my-extension"
+version: "1.0.0"
+description: "Mi extensión custom"
+author: "Tu Nombre"
+
+# Qué agrega
+provides:
+  tools:
+    - my_custom_tool
+  workflows:
+    - my_custom_workflow
+  personas:
+    - my_custom_persona
+
+# Configuración
+settings:
+  api_url: ""
+  api_key_env: "MY_API_KEY"
+```
+
+### Habilitar Extensión
+
+```yaml
+# config/settings.yaml
+extensions:
+  enabled: true
+  installed:
+    - my-extension
+```
+
+---
+
+## Tips de Personalización
+
+### 1. Empezar Simple
+
+- Primero usa el framework como está
+- Identifica qué necesitas cambiar
+- Personaliza incrementalmente
+
+### 2. Documentar Cambios
+
+- Documenta por qué personalizaste algo
+- Facilita onboarding de nuevos miembros
+
+### 3. Mantener Compatibilidad
+
+- No modifiques archivos core directamente
+- Usa archivos custom y overrides
+- Facilita actualizar a nuevas versiones
+
+### 4. Compartir con el Equipo
+
+```bash
+# Commitear solo lo necesario
+git add config/settings.yaml
+git add personas/custom/
+git add workflows/custom/
+git add config/tools-custom.yaml
+git commit -m "chore: add team customizations"
+```
+
+---
+
+## Troubleshooting
+
+### Persona Custom No Funciona
+
+1. Verificar que está en `personas/custom/` o directorio correcto
+2. Verificar YAML frontmatter
+3. Verificar que está habilitada en settings.yaml
+
+### Tool Custom No Se Registra
+
+1. Verificar path del módulo en tools.yaml
+2. Verificar que la clase existe e importa
+3. Verificar las dependencias necesarias
+
+### Workflow No Aparece
+
+1. Verificar que está habilitado en settings.yaml
+2. Verificar YAML frontmatter
+3. Verificar path del archivo

package/docs/getting-started.md

@@ -0,0 +1,154 @@
+# Guía de Inicio Rápido (Getting Started)
+
+Bienvenido a **LMAgent**, tu framework para desarrollo asistido por IA. Esta guía te llevará desde cero hasta estar productivo con tus agentes.
+
+## 1. Instalación
+
+### Requisitos previos
+- Python 3.12+
+- Git
+- Un IDE agéntico (Antigravity, Cursor, Windsurf, VS Code + Claude/Copilot)
+- API Keys para tus LLMs (OpenAI, Anthropic, Google)
+
+### Instalación del CLI
+Para tener el comando `lmagent` disponible en tu terminal:
+
+1. Clona el repositorio oficial:
+```bash
+git clone https://github.com/QuBiit0/lmagent.git
+cd lmagent
+```
+
+2. Instala el paquete en modo editable:
+```bash
+pip install -e .
+```
+
+3. Verifica que funcione:
+```bash
+lmagent --version
+# Debería mostrar: LMAgent v2.0.0
+```
+
+### Opción A: Proyecto Nuevo (Desde Cero)
+```bash
+# 1. Crea el directorio
+mkdir mi-nuevo-proyecto
+cd mi-nuevo-proyecto
+
+# 2. Inicializa el framework
+lmagent init
+```
+Esto creará la estructura base y estarás listo para empezar.
+
+### Opción B: Proyecto Existente (Legacy/Brownfield)
+LMAgent es **no-intrusivo**. No tocará tu código fuente, solo agregará una capa de inteligencia.
+
+```bash
+# 1. Ve a la raíz de tu proyecto
+cd mi-proyecto-existente
+
+# 2. Inicializa el framework
+lmagent init
+```
+
+**¿Qué pasará?**
+- Se creará la carpeta `.agent/` (el cerebro del agente).
+- Se añadirán archivos de configuración para tu IDE (`CLAUDE.md`, `.cursorrules`).
+- **Tu código fuente (`src/`, `app/`, etc.) permanecerá intacto.**
+
+**Recomendación**: Después de inicializar, pídele al agente:
+> "Analiza la estructura de este proyecto y crea un `rules/project.md` con las convenciones que veas."
+
+## 2. Configuración Básica
+
+1. **Variables de Entorno**:
+   Copia el ejemplo y edita tus claves:
+   ```bash
+   cp .env.example .env
+   # Edita .env con tus API KEYS
+   ```
+
+2. **Verifica la instalación**:
+   ```bash
+   lmagent doctor
+   ```
+   Deberías ver "✨ All checks passed!".
+
+## 3. Tu Primera Tarea con el Agente
+
+LMAgent está diseñado para trabajar **contigo** en el chat de tu IDE.
+
+### Paso 1: Entender el Contexto
+Abre el chat y dile al agente:
+> "Hola, soy nuevo en este proyecto. ¿Puedes explicarme la estructura y qué personas tienes disponibles?"
+
+### Paso 2: Activar una Persona
+Si vas a trabajar en backend, activa al experto:
+> "Actúa como @Backend Engineer /dev"
+
+El agente adoptará el rol, conocimientos y reglas de esa persona.
+
+### Paso 3: Ejecutar un Workflow
+Vamos a crear una automatización simple. Dile al agente:
+> "Quiero crear una nueva automatización de n8n. Usa el workflow /new-automation"
+
+El agente:
+1. Leerá `workflows/new-automation.md`
+2. Te guiará paso a paso
+3. Creará los archivos necesarios
+
+## 4. Tu Primer Día: Guía Paso a Paso
+
+Si arrancas de cero, **no escribas código todavía**. Sigue este "script" de conversación con el agente:
+
+### Paso 0: El "Super Prompt" (Opcional pero Recomendado) 🚀
+Si ya tienes la idea clara, no pierdas tiempo chateando.
+
+1. Copia la plantilla de **`templates/project_brief.md`**.
+2. Llénala con tus datos.
+3. Pégala en el chat:
+   > "Hola **/orch**. Aquí está el brief de mi proyecto. Inicia el trabajo."
+
+El Orchestrator leerá todo y asignará tareas al PM y Arquitecto automáticamente.
+
+### Paso 1: Definir el "QUÉ" (con el Product Manager)
+Activa al PM y cuéntale tu idea abstracta.
+> "Hola **/pm**. Quiero crear una aplicación para gestionar gastos personales que sea muy simple. Ayúdame a definir los requerimientos y un MVP."
+
+El agente te hará preguntas. Respóndelas hasta que genere un **PRD** (Product Requirements Document).
+
+### Paso 2: Definir el "CÓMO" (con el Architect)
+Una vez tengas el PRD (o una idea clara), llama al Arquitecto.
+> "Hola **/arch**. Basado en lo que definimos con el PM, define el stack tecnológico ideal y crea la estructura de carpetas inicial. Crea también un archivo `rules/project.md` con las convenciones."
+
+### Paso 3: Empezar a Construir (con el Developer)
+Con el plan y las reglas listas, empieza a codear.
+> "Hola **/dev**. Vamos a implementar la estructura base que definió el arquitecto. Empieza por inicializar el proyecto (package.json o pyproject.toml)."
+
+---
+
+## 5. Conceptos Clave
+
+### 🎭 Personas
+Son roles especializados que el agente adopta. Cada uno tiene sus propias instrucciones y "superpoderes".
+- **/pm** - Product Manager (Define QUÉ hacer)
+- **/arch** - Architect (Define CÓMO hacerlo)
+- **/dev** - Backend Dev (Escribe el código)
+- **/qa** - QA Engineer (Escribe los tests)
+- **/prompt** - Prompt Engineer (Diseña la lógica cognitiva)
+
+### 📏 Niveles (Levels)
+Determinan cuánto "pensar" antes de "hacer".
+- **Level 0**: Trivial. Hazlo ya.
+- **Level 2**: Medium. Crea un plan (`implementation_plan.md`) y espera mi OK.
+- **Level 4**: Enterprise. Plan muy detallado, revisión de seguridad, aprobación humana obligatoria.
+
+### 📜 Reglas Proactivas
+El agente lee tus reglas en `.agent/rules/`. Si rompes una regla (ej. "No usar prints"), el agente te corregirá o lo arreglará automáticamente.
+
+## 5. Siguientes Pasos
+
+- Lee la [Guía de Uso Completa](usage-guide.md) para dominar el framework.
+- Explora las [Personas](../personas/) disponibles.
+- Revisa los [Workflows](../workflows/) para automatizar tus tareas repetitivas.