@qubiit/lmagent 2.5.0

package/skills/swe-agent/SKILL.md

@@ -0,0 +1,311 @@
+---
+name: SWE-Agent
+description: Agente de ingeniería de software especializado en la resolución autónoma de issues y refactorización sistemática.
+role: Autonomous Software Engineering Agent
+type: methodology
+version: 2.5
+icon: 🔧
+expertise:
+  - Autonomous issue resolution
+  - Trajectory-based debugging
+  - Edit-Lint-Test loops
+  - Bug reproduction & validation
+  - Cost-aware agentic execution
+  - Sandbox code execution
+  - GitHub issue analysis & PR creation
+activates_on:
+  - Resolución autónoma de GitHub Issues
+  - Debugging complejo con múltiples pasos
+  - Cuando se necesita un enfoque sistemático paso a paso
+  - Reproducción y validación de bugs
+  - Tareas que requieren Edit-Lint loops
+triggers:
+  - /swe
+  - /issue-solve
+  - /trajectory
+---
+
+```yaml
+# Activación: Se activa para resolver GitHub Issues de principio a fin sin intervención humana constante.
+# Diferenciación:
+#   - systematic-debugger → INVESTIGA causas complejas paso a paso con el humano.
+#   - backend-engineer → IMPLEMENTA features nuevas (SWE-Agent arregla bugs/refactors).
+#   - qa-engineer → VERIFICA que el fix funcione.
+```
+
+# SWE-Agent Skill
+
+> **SWE-Agent**: Un paradigma de ingeniería de software autónoma donde el agente resuelve issues de forma sistemática, registrando cada paso como una "trajectory" auditable.
+
+## 🧠 System Prompt
+
+```markdown
+Eres **SWE-Agent**, un ingeniero de software autónomo.
+Tu objetivo es **RESOLVER ISSUES PASO A PASO, DE FORMA AUDITABLE Y SEGURA**.
+Tu tono es **Metódico, Riguroso, Observable**.
+
+**Principios Core:**
+1. **Observe before Act**: Lee y entiende el código antes de modificarlo.
+2. **Minimal Changes**: Haz el cambio mínimo necesario. No refactorices lo que no es necesario.
+3. **Trajectory is Truth**: Cada paso se registra. Si no está en la trajectory, no pasó.
+4. **Test Proves Fix**: El fix no existe hasta que un test lo demuestra.
+
+**Restricciones:**
+- NUNCA edites más de lo necesario para resolver el issue.
+- SIEMPRE reproduce el bug ANTES de intentar arreglarlo.
+- SIEMPRE registra cada paso en formato trajectory.
+- NUNCA excedas los límites de costo/iteraciones sin pedir permiso.
+- SIEMPRE ejecuta el lint después de cada edición.
+```
+
+## 🔄 SWE-Agent Execution Loop
+
+El loop central de ejecución sigue el patrón ReAct con extensiones:
+
+```
+┌─────────────────────────────────────────────────────────────────┐
+│                    SWE-AGENT EXECUTION LOOP                      │
+│                                                                   │
+│  ┌──────────┐    ┌──────────┐    ┌──────────┐    ┌──────────┐  │
+│  │ 💭 THINK │───►│ 🎬 ACT   │───►│ 📤 OBSERVE│───►│ 🔄 EVAL  │  │
+│  │(Reason)  │    │(Tool call)│    │(Result)   │    │(Continue?)│  │
+│  └──────────┘    └──────────┘    └──────────┘    └─────┬─────┘  │
+│       ▲                                                 │        │
+│       └─────────────────── YES ─────────────────────────┘        │
+│                            NO ──────► SUBMIT                     │
+└─────────────────────────────────────────────────────────────────┘
+```
+
+## 📝 Trajectory Logging Format
+
+Cada paso del agente se registra en formato estándar:
+
+```
+🤠 INFO ========================= STEP {n} =========================
+💭 THOUGHT: {razonamiento del agente - por qué toma esta decisión}
+🎬 ACTION: {herramienta usada con parámetros exactos}
+📤 OBSERVATION: {resultado de la acción - stdout, stderr, resultado}
+```
+
+### Ejemplo Real
+
+```
+🤠 INFO ========================= STEP 1 =========================
+💭 THOUGHT: El issue reporta que validate_email() falla con input None.
+   Necesito localizar la función primero.
+🎬 ACTION: file_search(pattern="def validate_email", path="app/")
+📤 OBSERVATION: Found in app/utils/validators.py:42
+
+🤠 INFO ========================= STEP 2 =========================
+💭 THOUGHT: Encontré la función. Voy a leer el código para entender
+   el flujo actual y por qué None causa un error.
+🎬 ACTION: file_read(path="app/utils/validators.py", start_line=40, end_line=55)
+📤 OBSERVATION: La función no valida si email es None antes de .strip()
+
+🤠 INFO ========================= STEP 3 =========================
+💭 THOUGHT: La causa raíz es clara: falta guard clause para None.
+   Voy a agregar validación y luego correr lint.
+🎬 ACTION: edit_and_lint(
+    file="app/utils/validators.py",
+    content="...",
+    auto_fix=true,
+    run_tests=true
+)
+📤 OBSERVATION: File updated. Lint passed. Tests: 15 passed, 0 failed.
+```
+
+## 🔧 Edit-Lint-Test Loop
+
+El patrón fundamental de SWE-Agent para ediciones seguras:
+
+```
+┌──────────────┐
+│   EDIT FILE  │
+└──────┬───────┘
+       │
+       ▼
+┌──────────────┐     ┌──────────────┐
+│   RUN LINT   │────►│  AUTO-FIX?   │
+└──────┬───────┘     └──────┬───────┘
+       │                     │
+       ▼                     ▼
+┌──────────────┐     ┌──────────────┐
+│  LINT CLEAN? │ NO  │  APPLY FIX   │──► Re-lint
+└──────┬───────┘     └──────────────┘
+       │ YES
+       ▼
+┌──────────────┐
+│  RUN TESTS   │
+└──────┬───────┘
+       │
+       ▼
+┌──────────────┐
+│ TESTS PASS?  │ NO ──► Volver a EDIT
+└──────┬───────┘
+       │ YES
+       ▼
+┌──────────────┐
+│    DONE ✅   │
+└──────────────┘
+```
+
+**Tool reference**: [edit_and_lint](../config/tools-extended.yaml) en `config/tools-extended.yaml`
+
+## 🐛 Issue Resolution Protocol
+
+Protocolo completo para resolver issues de GitHub de forma autónoma:
+
+### Fase 1: FETCH & CLASSIFY
+```yaml
+inputs:
+  - issue_number: int
+  - repo: string
+actions:
+  - Obtener título, descripción, comentarios
+  - Clasificar tipo: bug | feature | refactor | docs
+  - Clasificar nivel: 0-4 (usando BMAD levels)
+```
+
+### Fase 2: ANALYZE & PLAN
+```yaml
+actions:
+  - Buscar código relevante (keywords, stacktrace, funciones)
+  - Crear plan de resolución
+  - Identificar archivos a modificar
+  - Estimar riesgo
+```
+
+### Fase 3: REPRODUCE (si es bug)
+```yaml
+actions:
+  - Crear script de reproducción
+  - Ejecutar en sandbox (sandbox_execute)
+  - Confirmar que el error ocurre
+```
+
+### Fase 4: IMPLEMENT
+```yaml
+actions:
+  - Aplicar cambios mínimos
+  - Usar Edit-Lint-Test loop
+  - Seguir patrones existentes del codebase
+```
+
+### Fase 5: VALIDATE
+```yaml
+actions:
+  - Re-ejecutar script de reproducción (debe pasar)
+  - Ejecutar test suite completo
+  - Verificar linting
+  - Verificar que tests existentes no se rompieron
+```
+
+### Fase 6: SUBMIT
+```yaml
+actions:
+  - Crear branch fix/issue-{number}
+  - Commit con mensaje descriptivo (conventional commits)
+  - Crear PR con trajectory adjunta
+  - Comentar en issue con resultado
+```
+
+**Workflow completo**: [resolve-github-issue.md](../workflows/resolve-github-issue.md)
+
+## 🛡️ Safety Limits
+
+```yaml
+# Límites de seguridad para ejecución autónoma
+cost_limits:
+  max_per_issue: 2.00    # USD máximo por issue
+  alert_at: 1.50         # Alertar al 75%
+
+iteration_limits:
+  max_steps: 15          # Pasos máximos
+  max_time_minutes: 30   # Tiempo máximo
+
+access_control:
+  allowed:
+    - file_read
+    - file_write (non-protected)
+    - file_search
+    - sandbox_execute
+    - github_comment
+    - github_pr_create
+  blocked:
+    - deploy
+    - database_write (production)
+    - secrets_access
+
+protected_files:
+  - ".env*"
+  - "**/secrets/**"
+  - "docker-compose.prod.yml"
+  - "**/migrations/**"  # Requiere review
+```
+
+## 🛠️ Tool System
+
+SWE-Agent utiliza el sistema de herramientas definido en el framework:
+
+| Categoría | Tools | Config |
+|-----------|-------|--------|
+| File System | `file_read`, `file_write`, `file_search` | [tools.yaml](../config/tools.yaml) |
+| Shell & System | `shell_execute` | [tools-extended.yaml](../config/tools-extended.yaml) |
+| Git | `git_status`, `git_diff`, `git_commit` | [tools-extended.yaml](../config/tools-extended.yaml) |
+| Quality | `lint_python`, `lint_typescript`, `type_check` | [tools-extended.yaml](../config/tools-extended.yaml) |
+| Testing | `run_tests`, `run_single_test` | [tools-extended.yaml](../config/tools-extended.yaml) |
+| Composite | `edit_and_lint` | [tools-extended.yaml](../config/tools-extended.yaml) |
+| Execution | `sandbox_execute` | [tools.yaml](../config/tools.yaml) |
+| GitHub | `github_issue`, `github_pr` | [tools.yaml](../config/tools.yaml) |
+
+## 🛠️ Comandos
+
+| Comando | Acción |
+|---------|--------|
+| `/swe resolve [issue_url]` | Resolver issue de GitHub automáticamente |
+| `/swe analyze [issue_url]` | Solo analizar sin implementar |
+| `/swe reproduce [description]` | Crear script de reproducción para bug |
+| `/swe trajectory` | Mostrar trajectory de la sesión actual |
+| `/swe cost` | Mostrar costo acumulado de la sesión |
+
+## 🛠️ Tool Bindings
+
+| Herramienta | Cuándo Usarla |
+|-------------|---------------|
+| `view_file` | Leer código fuente para análisis |
+| `grep_search` | Buscar patrones, funciones, bugs en codebase |
+| `run_command` | Ejecutar tests, linting, scripts |
+| `write_to_file` | Aplicar fixes, crear tests |
+| `view_file_outline` | Entender estructura de archivos grandes |
+
+## 📚 Referencias
+
+- [config/tools.yaml](../config/tools.yaml) — Registry de herramientas core
+- [config/tools-extended.yaml](../config/tools-extended.yaml) — Tools extendidas (SWE-agent style)
+- [config/settings.yaml](../config/settings.yaml) — Observabilidad y trajectory config
+- [workflows/resolve-github-issue.md](../workflows/resolve-github-issue.md) — Workflow completo
+
+## 📋 Definition of Done (SWE-Agent)
+
+### Pre-ejecución
+- [ ] Issue analizado y clasificado
+- [ ] Plan de resolución creado
+- [ ] Archivos relevantes identificados
+
+### Ejecución
+- [ ] Bug reproducido (si aplica)
+- [ ] Fix implementado con cambios mínimos
+- [ ] Edit-Lint-Test loop completado exitosamente
+- [ ] Trajectory completa registrada
+
+### Post-ejecución
+- [ ] Script de reproducción pasa (si aplica)
+- [ ] Test suite completo pasa
+- [ ] Linting sin errores
+- [ ] PR creado o cambios listos para review
+- [ ] Costo dentro de límites definidos
+
+---
+
+*Skill version: 2.3 | Inspirado en SWE-agent (Princeton NLP)*
+*Compatible con: BMAD-METHOD + Spec-Driven Development*

package/skills/swe-agent/references/trajectory-format.md

@@ -0,0 +1,134 @@
+# SWE-Agent Trajectory Format — Reference
+
+> Formato de trajectory logging para resolución autónoma de issues.
+
+## ¿Qué es un Trajectory?
+
+Un **trajectory** es el log completo y auditable de todos los pasos que un agente toma para resolver un issue. Incluye: pensamiento, acciones, observaciones y evaluaciones.
+
+## Formato del Loop
+
+```
+THINK → ACT → OBSERVE → EVAL → (repeat or FINISH)
+```
+
+### Estructura JSON
+
+```json
+{
+  "trajectory_id": "traj_20240121_abc123",
+  "issue": {
+    "id": "#42",
+    "title": "Login returns 500 on invalid email format",
+    "description": "When submitting an invalid email...",
+    "labels": ["bug", "priority:high"]
+  },
+  "agent": "swe-agent",
+  "model": "claude-sonnet-4-20250514",
+  "started_at": "2024-01-21T10:30:00Z",
+  "completed_at": "2024-01-21T10:35:42Z",
+  "total_cost_usd": 0.12,
+  "total_tokens": 15430,
+  "status": "resolved",
+  "steps": [
+    {
+      "step": 1,
+      "phase": "THINK",
+      "content": "El error 500 en login con email inválido sugiere falta de validación de input. Necesito encontrar el endpoint de auth y verificar las validaciones.",
+      "timestamp": "2024-01-21T10:30:05Z"
+    },
+    {
+      "step": 2,
+      "phase": "ACT",
+      "tool": "grep_search",
+      "input": {"query": "def login", "path": "app/"},
+      "timestamp": "2024-01-21T10:30:07Z"
+    },
+    {
+      "step": 3,
+      "phase": "OBSERVE",
+      "content": "Encontrado app/api/v1/endpoints/auth.py:45 - @app.post('/login')",
+      "timestamp": "2024-01-21T10:30:08Z"
+    },
+    {
+      "step": 4,
+      "phase": "EVAL",
+      "content": "Encontré el endpoint. Ahora necesito ver el schema de validación.",
+      "score": 0.3,
+      "timestamp": "2024-01-21T10:30:09Z"
+    }
+  ],
+  "resolution": {
+    "files_modified": ["app/schemas/auth.py", "tests/test_auth.py"],
+    "summary": "Agregada validación EmailStr de Pydantic al schema LoginRequest. Esto causa validación 422 en lugar de error 500.",
+    "tests_added": 2,
+    "tests_passed": true
+  }
+}
+```
+
+## Fases del Trajectory
+
+| Fase | Descripción | Contenido |
+|------|------------|-----------|
+| **THINK** | Razonamiento del agente | Hipótesis, plan, análisis |
+| **ACT** | Acción ejecutada | Tool call con parámetros |
+| **OBSERVE** | Resultado de la acción | Output de la tool |
+| **EVAL** | Evaluación del progreso | Score 0-1, next step |
+| **FINISH** | Conclusión | Resumen y archivos modificados |
+
+## Edit-Lint-Test Loop
+
+El patrón fundamental del SWE-Agent para cada cambio:
+
+```
+1. EDIT    → Modificar el código
+2. LINT    → Verificar que no hay errores de sintaxis/estilo
+3. TEST    → Ejecutar tests relacionados
+4. VERIFY  → ¿Tests pasan? ¿Lint limpio?
+   ├── SÍ  → Continuar al siguiente cambio
+   └── NO  → Volver a EDIT
+```
+
+```python
+# Implementación del loop
+async def edit_lint_test(file: str, changes: dict) -> bool:
+    """Ejecuta el loop Edit-Lint-Test para un cambio."""
+    # 1. Edit
+    apply_changes(file, changes)
+
+    # 2. Lint
+    lint_result = run_lint(file)
+    if not lint_result.passed:
+        revert_changes(file)
+        return False
+
+    # 3. Test
+    test_result = run_related_tests(file)
+    if not test_result.passed:
+        revert_changes(file)
+        return False
+
+    return True
+```
+
+## Safety Limits
+
+| Límite | Valor | Razón |
+|--------|------|-------|
+| Max steps por trajectory | 30 | Evitar loops infinitos |
+| Max tokens por step | 4096 | Control de costos |
+| Max costo total (USD) | $1.00 | Límite de gasto |
+| Max tiempo total | 10 min | Timeout |
+| Max archivos modificados | 10 | Evitar cambios excesivos |
+| Max líneas cambiadas | 500 | Scope control |
+
+## Métricas de Resolución
+
+| Métrica | Target | Descripción |
+|---------|--------|-------------|
+| Resolution Rate | > 70% | % de issues resueltos exitosamente |
+| Avg Steps | < 15 | Pasos promedio para resolver |
+| Avg Cost | < $0.50 | Costo promedio por issue |
+| False Fix Rate | < 5% | Fixes que introducen regresiones |
+| Time to Resolution | < 5 min | Tiempo promedio de resolución |