@qubiit/lmagent 2.5.0

package/templates/tasks.yaml

@@ -0,0 +1,330 @@
+# Tasks Template (SPEC DRIVEN Development)
+# LMAgent Framework v3.0 - SPEC+LM Methodology
+#
+# This template breaks down a plan.yaml into executable tasks.
+# Each task is assigned to a persona and can be executed in parallel.
+# Use with `/dev` persona.
+#
+# Usage:
+#   1. Requires: specs/[feature-name]/plan.yaml (approved)
+#   2. Copy to: specs/[feature-name]/tasks.yaml
+#   3. Execute tasks in dependency order
+
+---
+metadata:
+  title: "Tasks: [Feature Name]"
+  spec_reference: "specs/[feature-name]/spec.yaml"
+  plan_reference: "specs/[feature-name]/plan.yaml"
+  version: "1.0"
+  author: "[Dev Name or Agent ID]"
+  created: "[YYYY-MM-DD]"
+  status: in_progress  # pending | in_progress | completed
+
+# ============================================
+# TASK SUMMARY
+# ============================================
+
+summary:
+  total_tasks: 0
+  completed_tasks: 0
+  in_progress_tasks: 0
+  blocked_tasks: 0
+  estimated_hours: 0
+  actual_hours: 0
+
+# ============================================
+# PHASE 1: [Foundation & Setup]
+# ============================================
+
+phase_1:
+  name: "Foundation & Setup"
+  status: pending  # pending | in_progress | completed
+  started_at: null
+  completed_at: null
+  
+  tasks:
+    - id: "T001"
+      title: "[Create project structure]"
+      description: |
+        [Detailed description of what needs to be done.
+        Include specific files to create, patterns to follow,
+        and expected outcomes.]
+      persona: "/dev"
+      priority: 1
+      estimated_hours: 0.5
+      actual_hours: null
+      status: pending  # pending | in_progress | completed | blocked
+      
+      # Files this task will create/modify
+      file_operations:
+        create:
+          - "path/to/new/file.py"
+          - "path/to/another/file.py"
+        modify:
+          - "path/to/existing/file.py"
+        delete: []
+      
+      # Dependencies
+      dependencies: []
+      blocks: ["T002", "T003"]
+      
+      # Acceptance criteria (from spec)
+      acceptance_criteria:
+        - "[ ] [Criterion 1]"
+        - "[ ] [Criterion 2]"
+      
+      # Commands to run
+      commands:
+        setup: []
+        validate:
+          - "pytest tests/test_structure.py -v"
+      
+      # Notes for the implementing agent
+      implementation_notes: |
+        - Use the standard project template
+        - Follow code-style.md guidelines
+        - Reference: rules/stack.md
+      
+      # Completion tracking
+      started_at: null
+      completed_at: null
+      completed_by: null
+      
+    - id: "T002"
+      title: "[Set up database]"
+      description: "[Create migrations, seed data]"
+      persona: "/dev"
+      priority: 1
+      estimated_hours: 1.0
+      status: pending
+      dependencies: ["T001"]
+      blocks: ["T004"]
+      file_operations:
+        create:
+          - "migrations/001_initial.sql"
+        modify: []
+        delete: []
+      acceptance_criteria:
+        - "[ ] Migrations run without errors"
+        - "[ ] Schema matches design"
+      commands:
+        validate:
+          - "alembic upgrade head"
+          - "alembic check"
+
+# ============================================
+# PHASE 2: [Core Logic]
+# ============================================
+
+phase_2:
+  name: "Core Logic"
+  status: pending
+  depends_on_phases: [1]
+  
+  tasks:
+    - id: "T003"
+      title: "[Implement service layer]"
+      description: "[Business logic implementation]"
+      persona: "/dev"
+      priority: 1
+      estimated_hours: 3.0
+      status: pending
+      dependencies: ["T001"]
+      blocks: ["T005"]
+      
+      # TDD approach
+      tdd:
+        test_first: true
+        test_file: "tests/unit/test_service.py"
+        test_cases:
+          - "test_create_entity"
+          - "test_read_entity"
+          - "test_update_entity"
+          - "test_delete_entity"
+          - "test_validation_errors"
+      
+      file_operations:
+        create:
+          - "src/services/entity_service.py"
+          - "tests/unit/test_service.py"
+        modify: []
+      
+      acceptance_criteria:
+        - "[ ] All CRUD operations work"
+        - "[ ] Validation errors handled"
+        - "[ ] Unit tests passing"
+        - "[ ] Coverage >80%"
+      
+      commands:
+        validate:
+          - "pytest tests/unit/ -v --cov=src/services"
+          - "ruff check src/services/"
+
+# ============================================
+# PHASE 3: [API Layer]
+# ============================================
+
+phase_3:
+  name: "API Layer"
+  status: pending
+  depends_on_phases: [2]
+  
+  # Parallel execution group
+  parallel_execution:
+    enabled: true
+    groups:
+      - name: "Endpoints"
+        tasks: ["T004", "T005"]
+        rationale: "Independent endpoints"
+      - name: "Supporting"
+        tasks: ["T006"]
+        can_run_with: ["Endpoints"]
+  
+  tasks:
+    - id: "T004"
+      title: "[Create REST endpoints]"
+      description: "[FastAPI/NestJS endpoints]"
+      persona: "/dev"
+      priority: 1
+      estimated_hours: 2.0
+      status: pending
+      dependencies: ["T002", "T003"]
+      
+      file_operations:
+        create:
+          - "src/routers/entity.py"
+          - "tests/integration/test_api.py"
+      
+      acceptance_criteria:
+        - "[ ] GET /entities works"
+        - "[ ] POST /entities works"
+        - "[ ] PUT /entities/{id} works"
+        - "[ ] DELETE /entities/{id} works"
+        - "[ ] OpenAPI schema generated"
+      
+      commands:
+        validate:
+          - "pytest tests/integration/ -v"
+          - "curl http://localhost:8000/docs"
+          
+    - id: "T005"
+      title: "[Add authentication]"
+      description: "[JWT/OAuth middleware]"
+      persona: "/dev"
+      priority: 2
+      estimated_hours: 1.5
+      status: pending
+      dependencies: ["T003"]
+      
+      security_considerations:
+        - "Use bcrypt for password hashing"
+        - "JWT expiry: 15 minutes"
+        - "Refresh token rotation"
+      
+      acceptance_criteria:
+        - "[ ] Login endpoint works"
+        - "[ ] Protected routes require auth"
+        - "[ ] Tokens expire correctly"
+        
+    - id: "T006"
+      title: "[Generate API documentation]"
+      description: "[Swagger/OpenAPI docs]"
+      persona: "/dev"
+      priority: 3
+      estimated_hours: 0.5
+      status: pending
+      dependencies: ["T004"]
+      
+      acceptance_criteria:
+        - "[ ] /docs endpoint available"
+        - "[ ] All endpoints documented"
+        - "[ ] Examples provided"
+
+# ============================================
+# PHASE 4: [Testing & Polish]
+# ============================================
+
+phase_4:
+  name: "Testing & Polish"
+  status: pending
+  depends_on_phases: [2, 3]
+  
+  tasks:
+    - id: "T007"
+      title: "[E2E tests]"
+      description: "[Full flow testing]"
+      persona: "/qa"
+      priority: 1
+      estimated_hours: 2.0
+      status: pending
+      dependencies: ["T004", "T005"]
+      
+      test_scenarios:
+        - scenario: "Happy path"
+          steps:
+            - "Create user"
+            - "Login"
+            - "Create entity"
+            - "Read entity"
+            - "Delete entity"
+            - "Logout"
+          expected: "All operations succeed"
+          
+        - scenario: "Error path"
+          steps:
+            - "Try invalid login"
+            - "Try unauthorized access"
+            - "Try invalid data"
+          expected: "Appropriate errors returned"
+      
+      acceptance_criteria:
+        - "[ ] Happy path passes"
+        - "[ ] Error paths handled"
+        - "[ ] Performance acceptable"
+        
+    - id: "T008"
+      title: "[Code review & refactor]"
+      description: "[Final polish]"
+      persona: "/lead"
+      priority: 2
+      estimated_hours: 1.0
+      status: pending
+      dependencies: ["T007"]
+      
+      review_checklist:
+        - "[ ] No TODO comments left"
+        - "[ ] No hardcoded values"
+        - "[ ] Consistent naming"
+        - "[ ] Proper error handling"
+        - "[ ] Security best practices"
+      
+      acceptance_criteria:
+        - "[ ] Linting passes"
+        - "[ ] Type checking passes"
+        - "[ ] Security scan passes"
+
+# ============================================
+# EXECUTION LOGS
+# ============================================
+
+execution_log:
+  - timestamp: null
+    task_id: null
+    action: null
+    agent: null
+    result: null
+    notes: null
+
+# ============================================
+# BLOCKERS & ISSUES
+# ============================================
+
+blockers:
+  - id: "B001"
+    task_id: null
+    description: null
+    severity: null  # critical | major | minor
+    status: null  # open | resolved | wontfix
+    resolution: null
+    created_at: null
+    resolved_at: null

package/workflows/bugfix-backend.md

@@ -0,0 +1,380 @@
+---
+description: Workflow para analizar y arreglar bugs en servicios backend Python/Node
+level: 1-2
+personas: [backend-engineer, qa-engineer]
+version: 2.1
+type: workflow
+---
+
+# Bugfix Backend Workflow
+
+> **Tiempo estimado**: 30 min - 2 horas | **Level**: 1-2
+
+Este workflow guía el proceso de análisis y corrección de bugs en backends.
+
+## Pre-requisitos
+
+1. Leer [AGENTS.md](../AGENTS.md)
+2. Leer [rules/workflow.md](../rules/workflow.md)
+3. Leer [personas/backend-engineer.md](../personas/backend-engineer.md)
+
+## Información Requerida
+
+Proporciona la siguiente información sobre el bug:
+
+1. **Descripción del bug**: ¿Qué está pasando?
+2. **Comportamiento esperado**: ¿Qué debería pasar?
+3. **Pasos para reproducir**: ¿Cómo se reproduce?
+4. **Ambiente**: ¿Dev, staging, producción?
+5. **Logs/Errores**: ¿Hay mensajes de error?
+6. **Frecuencia**: ¿Siempre ocurre o es intermitente?
+7. **Impacto**: ¿Crítico, alto, medio, bajo?
+
+---
+
+## Paso 1: Reproducir el Bug
+
+### 1.1 Crear Script de Reproducción
+
+```python
+# reproduce_bug.py
+
+"""
+Script para reproducir el bug descrito en [issue/ticket].
+
+Bug: [Descripción breve]
+Comportamiento esperado: [...]
+Comportamiento actual: [...]
+"""
+
+import asyncio
+import httpx
+
+async def reproduce():
+    """Intenta reproducir el bug."""
+    async with httpx.AsyncClient(base_url="http://localhost:8000") as client:
+        # Configurar estado inicial si es necesario
+        
+        # Ejecutar acción que causa el bug
+        response = await client.post("/endpoint", json={
+            # Datos que causan el bug
+        })
+        
+        print(f"Status: {response.status_code}")
+        print(f"Response: {response.json()}")
+        
+        # Verificar si el bug ocurrió
+        # assert ... 
+
+if __name__ == "__main__":
+    asyncio.run(reproduce())
+```
+
+### 1.2 Ejecutar y Confirmar
+
+```bash
+# Ejecutar script de reproducción
+python reproduce_bug.py
+
+# Si el bug no se reproduce, revisar:
+# - ¿Datos correctos?
+# - ¿Ambiente correcto?
+# - ¿Estado previo necesario?
+```
+
+---
+
+## Paso 2: Localizar el Problema
+
+### 2.1 Analizar Logs
+
+```bash
+# Buscar errores relacionados
+grep -r "ERROR" logs/ | grep -i "[keyword del bug]"
+
+# Ver logs recientes
+tail -f logs/app.log | grep -i "[keyword]"
+```
+
+### 2.2 Trazar el Código
+
+```
+1. Identificar endpoint afectado
+2. Seguir flujo: Router → Service → Repository
+3. Identificar punto exacto de fallo
+4. Verificar inputs/outputs en cada paso
+```
+
+### 2.3 Buscar Código Relacionado
+
+```bash
+# Buscar funciones/clases relacionadas
+grep -rn "function_name" app/
+
+# Buscar usos de la entidad afectada
+grep -rn "EntityName" app/
+```
+
+---
+
+## Paso 3: Analizar Causa Raíz
+
+### Checklist de Causas Comunes
+
+```
+[ ] Validación de input faltante
+[ ] Manejo de null/None incorrecto
+[ ] Error en lógica condicional
+[ ] Race condition
+[ ] Timeout no manejado
+[ ] Excepción no capturada
+[ ] Error de tipo/casting
+[ ] Query SQL incorrecta
+[ ] Estado inconsistente
+[ ] Configuración incorrecta
+```
+
+### Documentar Análisis
+
+```markdown
+## Análisis del Bug
+
+### Síntoma
+[Qué se observa]
+
+### Localización
+- Archivo: `app/services/xyz.py`
+- Función: `process_data()`
+- Línea: 42
+
+### Causa Raíz
+[Por qué ocurre]
+
+### Impacto
+[Qué afecta]
+
+### Solución Propuesta
+[Cómo arreglar]
+```
+
+---
+
+## Paso 4: Escribir Test que Falla
+
+Antes de arreglar, escribir test que demuestra el bug:
+
+```python
+# tests/test_bug_{issue_number}.py
+
+import pytest
+
+class TestBug{IssueNumber}:
+    """
+    Test para bug #{issue_number}.
+    
+    Bug: [Descripción]
+    Causa: [Causa raíz]
+    """
+    
+    @pytest.mark.asyncio
+    async def test_bug_scenario(self, client):
+        """El escenario que causa el bug."""
+        # Arrange - Configurar estado
+        
+        # Act - Ejecutar acción que causa bug
+        response = await client.post("/endpoint", json={
+            # Datos que causan el bug
+        })
+        
+        # Assert - Verificar comportamiento CORRECTO
+        # Este test FALLA antes del fix
+        assert response.status_code == 200  # o el esperado
+        assert response.json()["field"] == "expected_value"
+```
+
+---
+
+## Paso 5: Implementar Fix
+
+### 5.1 Aplicar Corrección
+
+```python
+# Antes (código con bug)
+def process_data(data):
+    result = data["field"]  # Falla si field no existe
+    return result
+
+# Después (código corregido)
+def process_data(data):
+    result = data.get("field")
+    if result is None:
+        raise ValidationError("field is required")
+    return result
+```
+
+### 5.2 Verificar que Test Pasa
+
+```bash
+# Ejecutar test específico
+pytest tests/test_bug_{issue_number}.py -v
+
+# Debería pasar ahora
+```
+
+### 5.3 Verificar que Otros Tests No Fallan
+
+```bash
+# Ejecutar todos los tests
+pytest --cov=app --cov-fail-under=80
+
+# Verificar que no hay regresiones
+```
+
+---
+
+## Paso 6: Verificar Fix
+
+### 6.1 Re-ejecutar Script de Reproducción
+
+```bash
+python reproduce_bug.py
+
+# Debería mostrar comportamiento correcto ahora
+```
+
+### 6.2 Test Manual (si aplica)
+
+1. Probar escenario del bug
+2. Probar casos edge relacionados
+3. Verificar que funcionalidad general sigue bien
+
+---
+
+## Paso 7: Documentar y Commit
+
+### 7.1 Commit Message
+
+```
+fix(module): descripción corta del fix
+
+Fixes #{issue_number}
+
+- [Cambio 1]
+- [Cambio 2]
+
+Root cause: [Explicación breve de la causa]
+```
+
+### 7.2 Actualizar Documentación (si aplica)
+
+- [ ] README si hay cambios de comportamiento
+- [ ] Docstrings si hay nuevos parámetros
+- [ ] Changelog si es fix significativo
+
+---
+
+## Paso 8: Code Review
+
+### Checklist para Reviewer
+
+- [ ] Test reproduce el bug original
+- [ ] Fix es minimal y enfocado
+- [ ] No hay regresiones
+- [ ] Código sigue estándares
+- [ ] Documentación actualizada
+
+---
+
+## Templates
+
+### Bug Report Template
+
+```markdown
+## Bug Report
+
+### Descripción
+[Qué está pasando]
+
+### Pasos para Reproducir
+1. [Paso 1]
+2. [Paso 2]
+3. [Paso 3]
+
+### Comportamiento Esperado
+[Qué debería pasar]
+
+### Comportamiento Actual
+[Qué pasa actualmente]
+
+### Ambiente
+- OS: [...]
+- Python/Node: [versión]
+- Branch: [...]
+
+### Logs/Screenshots
+```
+[Logs de error]
+```
+
+### Impacto
+- [ ] Crítico - Sistema caído
+- [ ] Alto - Feature principal afectado
+- [ ] Medio - Feature secundario afectado
+- [ ] Bajo - Edge case, workaround existe
+```
+
+### Fix PR Template
+
+```markdown
+## Fix: [Título del Bug]
+
+Fixes #{issue_number}
+
+### Causa Raíz
+[Explicación de por qué ocurría el bug]
+
+### Solución
+[Qué se cambió y por qué]
+
+### Testing
+- [x] Test que reproduce el bug
+- [x] Test pasa después del fix
+- [x] Sin regresiones en otros tests
+
+### Checklist
+- [ ] Código sigue estándares
+- [ ] Tests completos
+- [ ] Documentación actualizada
+```
+
+---
+
+## Checklist Final
+
+- [ ] Bug reproducido localmente
+- [ ] Causa raíz identificada
+- [ ] Test escrito que falla antes del fix
+- [ ] Fix implementado
+- [ ] Test pasa después del fix
+- [ ] Sin regresiones
+- [ ] Commit con mensaje descriptivo
+- [ ] PR creado para review
+
+---
+
+## 🛠️ Herramientas Sugeridas
+
+| Fase | Herramienta |
+|------|-------------|
+| Reproducción | `run_command` (scripts), `grep_search` |
+| Análisis | `view_file`, `grep_search`, logs |
+| Fix | `replace_file_content`, `write_to_file` |
+| Validación | `run_command` (pytest) |
+
+## ⚠️ Errores Comunes
+
+| Error | Solución |
+|-------|----------|
+| Arreglar sin reproducir primero | SIEMPRE reproducir antes de tocar código |
+| No escribir test de regresión | El test debe fallar ANTES del fix |
+| Fix muy amplio | Cambiar solo lo necesario, mínima intervención |