@qubiit/lmagent 2.5.0

package/workflows/new-automation.md

@@ -0,0 +1,374 @@
+---
+description: Workflow para crear una nueva automatización que involucra backend + n8n + opcionalmente agentes IA
+level: 2-3
+personas: [automation-engineer, backend-engineer, ai-agent-engineer]
+version: 2.1
+type: workflow
+---
+
+# New Automation Workflow
+
+> **Tiempo estimado**: 2-6 horas | **Level**: 2-3
+
+Este workflow guía la creación de una nueva automatización end-to-end.
+
+## Pre-requisitos
+
+1. Leer [AGENTS.md](../AGENTS.md)
+2. Leer [rules/automations-n8n.md](../rules/automations-n8n.md)
+3. Leer [rules/stack.md](../rules/stack.md)
+
+## Información Requerida
+
+Antes de comenzar, necesito entender:
+
+1. **Descripción de negocio**: ¿Qué proceso se quiere automatizar?
+2. **Trigger**: ¿Qué inicia la automatización? (webhook, schedule, evento)
+3. **Sistemas involucrados**: ¿Qué APIs/servicios se conectan?
+4. **Output esperado**: ¿Cuál es el resultado final?
+5. **Requisitos de fiabilidad**: ¿Crítico? ¿Tolerancia a fallos?
+6. **Latencia aceptable**: ¿Tiempo máximo de ejecución?
+7. **¿Involucra agentes IA?**: ¿Necesita procesamiento con LLM?
+
+---
+
+## Paso 1: Analizar y Clasificar
+
+### Determinar Nivel
+- **Level 2**: Automatización simple (1-2 sistemas, sin IA)
+- **Level 3**: Automatización compleja (3+ sistemas, con IA, crítica)
+
+### Activar Personas
+```
+Automatización simple  → Automation Engineer
+Con backend custom     → + Backend Engineer
+Con agentes IA         → + AI Agent Engineer
+```
+
+---
+
+## Paso 2: Diseñar Arquitectura
+
+### 2.1 Diagrama de Flujo
+
+```mermaid
+sequenceDiagram
+    participant T as Trigger
+    participant N as n8n
+    participant B as Backend API
+    participant A as Agent (opcional)
+    participant E as External API
+    participant D as Database
+
+    T->>N: Inicia workflow
+    N->>B: POST /webhooks/process
+    B->>D: Consultar datos
+    D-->>B: Datos
+    
+    alt Requiere IA
+        B->>A: Procesar con agente
+        A-->>B: Resultado
+    end
+    
+    B->>E: Llamar API externa
+    E-->>B: Respuesta
+    B->>D: Guardar resultado
+    B-->>N: Respuesta
+    N->>T: Notificar/Callback
+```
+
+### 2.2 Definir Componentes
+
+| Componente | Tipo | Descripción |
+|------------|------|-------------|
+| Trigger | [Webhook/Schedule/Event] | [Descripción] |
+| n8n Workflow | [Nombre] | [Pasos principales] |
+| Backend Endpoint | [POST /webhooks/xxx] | [Procesamiento] |
+| Agente IA | [Nombre o N/A] | [Tarea del agente] |
+| Sistemas externos | [Lista] | [APIs/servicios] |
+| Storage | [DB/Redis/Files] | [Qué se guarda] |
+
+---
+
+## Paso 3: Crear Plan de Implementación
+
+### Archivos a Crear/Modificar
+
+```markdown
+## Backend
+
+### Nuevos archivos
+- [ ] `app/routers/webhooks/{automation_name}.py` - Endpoint del webhook
+- [ ] `app/services/{automation_name}_service.py` - Lógica de negocio
+- [ ] `app/schemas/{automation_name}.py` - Schemas de request/response
+
+### Modificaciones
+- [ ] `app/routers/__init__.py` - Registrar nuevo router
+- [ ] `tests/test_{automation_name}.py` - Tests
+
+## n8n
+
+### Nuevo workflow
+- [ ] `automations/n8n/workflows/{automation_name}.json` - Export del workflow
+
+### Documentación
+- [ ] `automations/docs/{automation_name}.md` - Documentación completa
+
+## Agente (si aplica)
+
+- [ ] `agents/config/agents.yaml` - Registrar nuevo agente
+- [ ] `agents/python/prompts/{agent_name}.md` - Prompt del agente
+```
+
+### Orden de Implementación
+
+1. **Schemas** - Definir estructuras de datos
+2. **Service** - Implementar lógica de negocio
+3. **Endpoint** - Crear webhook
+4. **Tests** - Escribir tests
+5. **n8n Workflow** - Crear flujo en n8n
+6. **Documentación** - Documentar para el equipo
+
+---
+
+## Paso 4: Implementar
+
+### 4.1 Crear Endpoint (FastAPI)
+
+```python
+# app/routers/webhooks/{automation_name}.py
+
+from fastapi import APIRouter, BackgroundTasks
+from pydantic import BaseModel
+from datetime import datetime
+from uuid import uuid4
+
+router = APIRouter(tags=["webhooks"])
+
+class {AutomationName}Request(BaseModel):
+    """Request para {automation_name}."""
+    # Definir campos según requerimientos
+    pass
+
+class {AutomationName}Response(BaseModel):
+    """Response para {automation_name}."""
+    success: bool
+    request_id: str
+    message: str
+    processed_at: datetime
+
+@router.post("/{automation-name}")
+async def handle_{automation_name}(
+    request: {AutomationName}Request,
+    background_tasks: BackgroundTasks
+) -> {AutomationName}Response:
+    """
+    Webhook para {descripción}.
+    
+    ## Uso en n8n
+    [Documentar aquí cómo usar desde n8n]
+    """
+    request_id = str(uuid4())
+    
+    background_tasks.add_task(
+        process_{automation_name},
+        request_id=request_id,
+        data=request
+    )
+    
+    return {AutomationName}Response(
+        success=True,
+        request_id=request_id,
+        message="Queued for processing",
+        processed_at=datetime.utcnow()
+    )
+```
+
+### 4.2 Crear Service
+
+```python
+# app/services/{automation_name}_service.py
+
+from app.schemas.{automation_name} import {AutomationName}Request
+import structlog
+
+logger = structlog.get_logger()
+
+async def process_{automation_name}(
+    request_id: str,
+    data: {AutomationName}Request
+) -> dict:
+    """
+    Procesa la automatización {automation_name}.
+    """
+    logger.info(
+        "{automation_name}_start",
+        request_id=request_id
+    )
+    
+    try:
+        # 1. Validar datos
+        # 2. Procesar lógica de negocio
+        # 3. Llamar APIs externas si necesario
+        # 4. Guardar resultados
+        
+        result = {}
+        
+        logger.info(
+            "{automation_name}_complete",
+            request_id=request_id
+        )
+        
+        return result
+        
+    except Exception as e:
+        logger.error(
+            "{automation_name}_error",
+            request_id=request_id,
+            error=str(e)
+        )
+        raise
+```
+
+### 4.3 Crear Workflow n8n
+
+1. Abrir n8n
+2. Crear nuevo workflow
+3. Agregar nodos según el diseño
+4. Configurar credenciales
+5. Probar con datos de ejemplo
+6. Exportar JSON a `automations/n8n/workflows/`
+
+---
+
+## Paso 5: Testing
+
+### Tests Unitarios
+```python
+# tests/test_{automation_name}.py
+
+import pytest
+from httpx import AsyncClient
+
+@pytest.mark.asyncio
+async def test_{automation_name}_success(client: AsyncClient):
+    """Test caso exitoso."""
+    response = await client.post(
+        "/webhooks/{automation-name}",
+        json={
+            # Datos de prueba
+        }
+    )
+    
+    assert response.status_code == 200
+    data = response.json()
+    assert data["success"] is True
+    assert "request_id" in data
+
+@pytest.mark.asyncio
+async def test_{automation_name}_invalid_payload(client: AsyncClient):
+    """Test payload inválido."""
+    response = await client.post(
+        "/webhooks/{automation-name}",
+        json={}  # Payload vacío
+    )
+    
+    assert response.status_code == 422  # Validation error
+```
+
+### Test E2E con n8n
+1. Ejecutar workflow de prueba en n8n
+2. Verificar que el webhook recibe correctamente
+3. Verificar procesamiento completo
+4. Verificar resultado final
+
+---
+
+## Paso 6: Documentación
+
+### Crear documentación en `automations/docs/{automation_name}.md`
+
+```markdown
+# {Automation Name}
+
+## Descripción
+[Qué hace esta automatización]
+
+## Trigger
+- **Tipo**: [Webhook | Schedule | Event]
+- **Endpoint**: POST /webhooks/{automation-name}
+- **Schedule**: [Cron expression si aplica]
+
+## Flujo
+1. [Paso 1]
+2. [Paso 2]
+3. [Paso 3]
+
+## Sistemas Involucrados
+- **Backend**: [Endpoint y función]
+- **n8n**: [Nombre del workflow]
+- **APIs externas**: [Lista]
+- **Base de datos**: [Tablas afectadas]
+
+## Request/Response
+
+### Request
+```json
+{
+    "field1": "value",
+    "field2": 123
+}
+```
+
+### Response
+```json
+{
+    "success": true,
+    "request_id": "uuid",
+    "message": "processed"
+}
+```
+
+## Manejo de Errores
+| Error | Causa | Solución |
+|-------|-------|----------|
+| [Error 1] | [Causa] | [Solución] |
+
+## Monitoreo
+- **Logs**: Buscar por request_id
+- **Métricas**: [Métricas a monitorear]
+- **Alertas**: [Condiciones de alerta]
+```
+
+---
+
+## Checklist Final
+
+- [ ] Endpoint implementado y desplegado
+- [ ] Service con lógica completa
+- [ ] Tests unitarios pasando (>80% coverage)
+- [ ] Workflow n8n creado y probado
+- [ ] Documentación completa
+- [ ] Credenciales configuradas
+- [ ] Monitoreo/alertas configuradas
+- [ ] Review de código completado
+
+---
+
+## 🛠️ Herramientas Sugeridas
+
+| Fase | Herramienta |
+|------|-------------|
+| Diseño | `write_to_file` (schemas, docs) |
+| Backend | `run_command` (pytest), `grep_search` |
+| n8n | `browser_subagent` (probar workflows) |
+| Validación | `run_command` (curl, pytest) |
+
+## ⚠️ Errores Comunes
+
+| Error | Solución |
+|-------|----------|
+| Webhook sin idempotencia | Diseñar para re-ejecución segura |
+| Sin manejo de errores en n8n | Agregar Error Workflow o nodo IF |
+| Credenciales hardcodeadas | Usar credentials store de n8n |
+| Respuesta > 60s sin async | Usar background task + polling/callback |

package/workflows/new-feature.md

@@ -0,0 +1,290 @@
+---
+description: Workflow para implementar una nueva feature completa
+level: 2-3
+personas: [backend-engineer, frontend-engineer, qa-engineer]
+version: 2.1
+type: workflow
+---
+
+# New Feature Implementation Workflow
+
+> **Tiempo estimado**: 2-8 horas | **Level**: 2-3
+
+Este workflow guía la implementación de una feature completa de principio a fin.
+
+## Pre-requisitos
+
+1. Feature definida y aprobada (PRD o issue)
+2. Diseño UI aprobado (si aplica)
+3. Arquitectura validada (si es compleja)
+
+---
+
+## Fase 1: Planificación
+
+### 1.1 Entender el Alcance
+
+- [ ] Leer PRD/issue completo
+- [ ] Identificar componentes afectados
+- [ ] Listar dependencias
+
+### 1.2 Breakdown de Tareas
+
+```markdown
+## Feature: {nombre}
+
+### Backend
+- [ ] Modelo de datos
+- [ ] Migraciones
+- [ ] Endpoints API
+- [ ] Tests
+
+### Frontend
+- [ ] Componentes UI
+- [ ] Integración API
+- [ ] Estados (loading/error)
+- [ ] Tests
+
+### Otros
+- [ ] Documentación
+- [ ] Feature flags (si aplica)
+```
+
+### 1.3 Crear Rama
+
+```bash
+git checkout develop
+git pull origin develop
+git checkout -b feature/{nombre-feature}
+```
+
+---
+
+## Fase 2: Backend
+
+### 2.1 Modelo de Datos
+
+```python
+# models/{feature}.py
+class Feature(Base):
+    __tablename__ = "features"
+    
+    id: Mapped[uuid.UUID] = mapped_column(primary_key=True)
+    name: Mapped[str]
+    # ...
+```
+
+### 2.2 Migración
+
+```bash
+alembic revision -m "add_feature_table"
+alembic upgrade head
+```
+
+### 2.3 Schemas
+
+```python
+# schemas/{feature}.py
+class FeatureCreate(BaseModel):
+    name: str
+
+class FeatureResponse(BaseModel):
+    id: str
+    name: str
+```
+
+### 2.4 Servicio
+
+```python
+# services/{feature}_service.py
+class FeatureService:
+    async def create(self, data: FeatureCreate) -> Feature:
+        ...
+```
+
+### 2.5 Endpoints
+
+```python
+# routes/{feature}.py
+@router.post("/", response_model=FeatureResponse, status_code=201)
+async def create_feature(data: FeatureCreate):
+    return await service.create(data)
+```
+
+### 2.6 Tests Backend
+
+```python
+# tests/test_{feature}.py
+async def test_create_feature(client):
+    response = await client.post("/api/v1/features", json={...})
+    assert response.status_code == 201
+```
+
+---
+
+## Fase 3: Frontend
+
+### 3.1 Tipos
+
+```typescript
+// types/{feature}.ts
+interface Feature {
+  id: string;
+  name: string;
+}
+```
+
+### 3.2 API Client
+
+```typescript
+// lib/api/{feature}.ts
+export const featuresApi = {
+  getAll: () => api.get<Feature[]>('/features'),
+  create: (data: CreateFeatureDto) => api.post<Feature>('/features', data),
+};
+```
+
+### 3.3 Custom Hook
+
+```typescript
+// hooks/use-{feature}.ts
+export function useFeatures() {
+  return useQuery({ queryKey: ['features'], queryFn: featuresApi.getAll });
+}
+```
+
+### 3.4 Componentes
+
+```typescript
+// components/features/{feature}/
+├── feature-list.tsx
+├── feature-card.tsx
+├── feature-form.tsx
+└── index.ts
+```
+
+### 3.5 Página
+
+```typescript
+// app/(dashboard)/features/page.tsx
+export default function FeaturesPage() {
+  const { data: features } = useFeatures();
+  return <FeatureList features={features} />;
+}
+```
+
+### 3.6 Tests Frontend
+
+```typescript
+// __tests__/feature-card.test.tsx
+it('renders feature name', () => {
+  render(<FeatureCard feature={mockFeature} />);
+  expect(screen.getByText(mockFeature.name)).toBeInTheDocument();
+});
+```
+
+---
+
+## Fase 4: Integración
+
+### 4.1 E2E Tests
+
+```typescript
+// e2e/features.spec.ts
+test('user can create feature', async ({ page }) => {
+  await page.goto('/features');
+  await page.click('button:has-text("New")');
+  await page.fill('input[name="name"]', 'Test Feature');
+  await page.click('button:has-text("Create")');
+  await expect(page.locator('text=Test Feature')).toBeVisible();
+});
+```
+
+### 4.2 Manual Testing
+
+- [ ] Happy path funciona
+- [ ] Edge cases manejados
+- [ ] Error states funcionan
+- [ ] Mobile responsive
+
+---
+
+## Fase 5: Finalización
+
+### 5.1 Cleanup
+
+- [ ] Remover console.logs
+- [ ] Remover código comentado
+- [ ] Verificar imports no usados
+
+### 5.2 Documentación
+
+- [ ] README actualizado (si aplica)
+- [ ] API docs actualizados
+- [ ] Changelog entry
+
+### 5.3 Code Review
+
+```bash
+git push origin feature/{nombre}
+# Crear PR
+```
+
+### 5.4 Merge
+
+- [ ] PR aprobado
+- [ ] CI pasando
+- [ ] Sin conflictos
+- [ ] Squash & merge
+
+---
+
+## Checklist Final
+
+```markdown
+## Feature: {nombre}
+
+### Backend
+- [ ] Modelo creado
+- [ ] Migración aplicada
+- [ ] Endpoints funcionando
+- [ ] Tests pasando (>80% cov)
+
+### Frontend
+- [ ] Componentes creados
+- [ ] Integración API
+- [ ] Estados handling
+- [ ] Tests pasando
+
+### Quality
+- [ ] Linter pasando
+- [ ] E2E tests
+- [ ] Manual testing
+- [ ] Documentación
+
+### Deploy
+- [ ] PR aprobado
+- [ ] Merged a develop
+- [ ] Tested en staging
+- [ ] Ready for production
+```
+
+---
+
+## 🛠️ Herramientas Sugeridas
+
+| Fase | Herramienta |
+|------|-------------|
+| Planificación | `write_to_file` (crear plan), `view_file` (revisar existente) |
+| Backend | `run_command` (alembic, pytest), `grep_search` |
+| Frontend | `run_command` (npm test), `browser_subagent` |
+| Validación | `run_command` (pytest, ruff, eslint) |
+
+## ⚠️ Errores Comunes
+
+| Error | Solución |
+|-------|----------|
+| Empezar sin PRD aprobado | Validar requerimientos primero |
+| Backend y Frontend en paralelo sin contrato | Definir API contract primero |
+| Olvidar estados (loading/error/empty) | Usar checklist de estados |
+| Tests solo happy path | Agregar tests de errores y edge cases |