imMamdouhaboammar/agentic-workflow

AgenticWorkflow: Cadena de Herramientas Universal de Ejecución y Habilidad Agéntica

Un marco de células madre pluripotentes y motor de ejecución multi-agente que convierte tareas complejas en flujos de trabajo autónomos, deterministas y autoverificables.

Invariante de Ejecución

$$\text{Intención} \xrightarrow{\text{Investigación}} \text{Plan (SOT state.yaml)} \xrightarrow{\text{Implementación}} \text{Compuertas de Calidad de 4 Capas} \xrightarrow{\text{Delta pACS}} \text{Entregable Verificado}$$

---

⚡ Enrutador de Modo Dinámico

Detecta el modo deseado a partir del contexto o indicadores explícitos:

Modo	Frases de Activación	Flujo de Ejecución Central
1. DISEÑO	"diseñar flujo de trabajo", "nuevo pipeline", "workflow.md"	Investigación → Planificación → Implementación (generación de plano en 3 etapas)
2. EJECUTAR	"ejecutar flujo de trabajo", "ejecutar pipeline", "iniciar paso"	Controlador de máquina de estados SOT con generación de entregables paso a paso
3. PILOTO AUTOMÁTICO	"piloto automático", "completamente automatizado", "sin intervención"	Autoaprobación de puntos de control (human) con registros de decisión; imponer ganchos de seguridad
4. ULW	"ulw", "ultratrabajo", "máximo rigor"	3 Intensificadores: Persistencia de Sísifo, Descomposición Obligatoria, Escalada de Reintentos
5. VERIFICAR	"verificar paso", "compuertas de calidad", "ejecutar pacs"	L0 Anti-Salto → L1 Verificación → L1.5 pACS → L2 Revisión Adversaria
6. OPTIMIZAR	"optimizar flujo de trabajo", "reducir tiempo de ciclo", "agilizar"	Análisis de cuellos de botella ajustado, puntuación de automatización, compresión del tiempo de ciclo

---

3 Criterios Absolutos (Canon Constitucional)

Cada flujo de trabajo, herramienta y subagente creado o gobernado por esta habilidad hereda estrictamente los 3 Criterios Absolutos:

1. Criterio Absoluto 1: Calidad del Entregable Final

   La velocidad, el costo de tokens, la carga de trabajo y los límites de longitud se ignoran por completo. El único criterio para cada decisión es la calidad del entregable final.

2. Criterio Absoluto 2: SOT de Archivo Único + Memoria Jerárquica

   Todo el estado compartido se concentra en un solo archivo (state.yaml). El permiso de escritura del SOT pertenece exclusivamente al Orquestador / Líder del Equipo. Los agentes paralelos nunca mutan archivos compartidos simultáneamente.

3. Criterio Absoluto 3: Protocolo de Cambio de Código (CCP)

   Antes de escribir, modificar, agregar o eliminar código, realizar internamente: Paso 1 (Entender la Intención) → Paso 2 (Análisis de Efecto Dominó) → Paso 3 (Plan de Cambio). Regido por los Puntos de Anclaje de Codificación (CAP-1~4).

---

Pila de Aseguramiento de Calidad de 4 Capas

flowchart TD
    StepStart["Ejecución del Paso"] --> L0["L0: Guardia Física Anti-Salto (Archivo existe y >= 100 bytes)"]
    L0 -->|PASA| L1["L1: Compuerta de Verificación (100% de logro del objetivo funcional)"]
    L0 -->|FALLA| Diag["Diagnóstico Abductivo"]
    L1 -->|PASA| L15["L1.5: Autoevaluación pACS (Puntuación F/C/L pre-mortem)"]
    L1 -->|FALLA| Diag
    L15 -->|ROJO: <50| Diag
    L15 -->|VERDE / AMARILLO| L2["L2: Revisión Adversaria (@revisor + @verificador-de-hechos)"]
    L2 -->|PASA| SOT["Avanzar SOT (current_step + 1)"]
    L2 -->|FALLA| Diag
    Diag --> Reintentar["Reintentar con Hipótesis Alternativa (Máximo 3)"]

1. Guardia Anti-Salto L0: Verifica deterministamente que el entregable existe en disco y no está vacío (MIN_OUTPUT_SIZE >= 100 bytes).
2. Compuerta de Verificación L1: Verificación semántica de que todos los criterios de aceptación se logran al 100%.
3. L1.5 pACS (Puntuación de Confianza Predictiva del Agente): Evaluación pre-mortem en Fidelidad, Completitud, Lógica. $pACS = \min(F, C, L)$.
   • VERDE (>= 70): Avance automático.
   • AMARILLO (50 - 69): Marcar dimensión débil en el Registro de Decisiones y continuar.
   • ROJO (< 50): Detenerse y desencadenar retrabajo.
4. Revisión Adversaria L2: Evaluación independiente Generador-Crítico por @revisor y @verificador-de-hechos.

---

Motor de Optimización de Flujo de Trabajo (Ajustado y Automatización)

Al analizar u optimizar flujos de trabajo:

• Gravedad del Cuello de Botella: Puntuar cuellos de botella del 1 al 5.
• Potencial de Automatización: Cuantificar tareas manuales para delegación agéntica.
• Reducción de Errores: Implementar compuertas de calidad en las causas raíz antes de la propagación de fallos.
• Reducción del Tiempo de Ciclo: Apuntar a una reducción >= 40% del tiempo de ciclo mientras se aumenta la calidad del entregable.

---

Motor Autónomo de Autoabastecimiento y Disyuntor

El sistema opera como un motor autónomo de extremo a extremo con gestión de energía incorporada:

1. Bucle de Autoabastecimiento y Energía: Monitoreo dinámico de tokens y margen de contexto con compactación automática del estado RLM y puntos de control de reabastecimiento antes del agotamiento del contexto.
2. Disyuntor de Fábula: Transiciones de estado CERRADO → ABIERTO → MEDIO ABIERTO. Detiene automáticamente el thrashing especulativo cuando la racha de fallos consecutivos es >= 2, aísla las causas raíz mediante Diagnóstico Abductivo (diagnose_context.py), y ejecuta una recuperación estructurada.
3. Guardia de Código Limpio: Pase de guardia AST automático que verifica los 24 imperativos de Código Limpio (funciones pequeñas, nombres que revelan intención, máximo 4 parámetros, sin excepciones tragadas, sin mocks de éxito falsos).
4. Evaluación de Ingeniería de IA: Pruebas integradas de impacto desproporcionado de cuatro quintos ($\ge 0.80$), monitoreo de desviación de distribución PSI y sanitización adversaria de inyección de indicaciones.

---

CLI e Integración de Cadena de Herramientas

# Lanzar flujo de trabajo autónomo de extremo a extremo en piloto automático con gestión de energía y autoabastecimiento
agentic-workflow autopilot --title "Pipeline de Producción" --goal "Entrega Autónoma"

# Ejecutar pase de auditoría de Guardia de Código Limpio (SOLID, 24 Imperativos, modos de fallo de IA)
agentic-workflow guard [directorio]

# Ejecutar compuertas de evaluación de Ingeniería de IA: equidad, desviación e inyección de indicaciones
agentic-workflow eval

# Consultar registros de trazas y spans observables multi-agente
agentic-workflow traces

# Inicializar infraestructura, directorios de tiempo de ejecución SOT y comprobaciones de salud
agentic-workflow init

# Validar esquema de flujo de trabajo, integridad SOT y registros pACS
agentic-workflow validate

# Verificar panel de control de flujo de trabajo en vivo y métricas de observabilidad
agentic-workflow status

# Ejecutar suite de pruebas automatizadas completa (seguridad, guardia, MAS, evaluador)
agentic-workflow test

---

Mapa de Referencia

• Arquitectura y ADN: soul.md, AGENTICWORKFLOW-ARCHITECTURE-AND-PHILOSOPHY.md
• Manual de Operación: AGENTICWORKFLOW-USER-MANUAL.md
• Directiva Común: AGENTS.md, CLAUDE.md, GEMINI.md
• Protocolos: docs/protocols/ (ejecución-autopiloto, compuertas-de-calidad, modo-ulw, protocolo-de-cambio-de-código, detalle-de-preservación-de-contexto)
• Subagentes: .claude/agents/ (revisor, verificador-de-hechos, traductor)
• Scripts: .claude/hooks/scripts/ (context_guard, validate_pacs, validate_review, etc.)