AgentFlow
Resumen
AgentFlow convierte tu tablero Kanban existente en un pipeline de desarrollo de IA completamente autónomo. En lugar de construir infraestructura de orquestación personalizada, trata tu herramienta de gestión de proyectos (Asana, GitHub Projects, Linear) como una máquina de estados distribuida: las tareas avanzan por etapas, los agentes de IA leen y escriben estado mediante comentarios, y los humanos intervienen a través de la misma interfaz que ya utilizan.
El resultado es una observabilidad completa del pipeline desde tu teléfono, recuperación gratuita ante fallos (el estado reside en tu herramienta de gestión de proyectos, no en memoria) y anulación manual en cualquier punto simplemente arrastrando una tarjeta.
Cuándo Usar Esta Habilidad
- Úsala cuando necesites orquestar múltiples trabajadores de Claude Code en un ciclo de desarrollo completo (construir, revisar, probar, integrar)
- Úsala cuando quieras compuertas de calidad deterministas (tsc/eslint/tests) antes de la revisión de IA sobre código generado por IA
- Úsala cuando quieras visibilidad completa del pipeline desde tu tablero Kanban o teléfono
- Úsala cuando estés ejecutando un proyecto en solitario o en equipo que necesite despacho autónomo de tareas con seguimiento de costes
- Úsala cuando necesites orquestación a prueba de fallos que sobreviva a reinicios de sesión
Conceptos Clave
Pipeline Kanban de 7 Etapas
Las tareas fluyen a través de: Pendiente, Investigación, Construcción, Revisión, Pruebas, Integración, Terminado. Cada etapa tiene compuertas específicas. El tablero Kanban ES la capa de orquestación — sin base de datos separada, sin cola de mensajes, sin infraestructura personalizada.
Orquestador Sin Estado
Un barrido único impulsado por crontab se ejecuta cada 15 minutos. Sin demonio, sin dependencia de sesión. Si falla, el siguiente barrido retoma donde lo dejó porque todo el estado reside en tu herramienta de gestión de proyectos.
Determinista Antes que Probabilístico
Las compuertas duras (tsc + eslint + tests) se ejecutan antes de cualquier revisión de IA, detectando aproximadamente el 60% de los problemas a un coste casi nulo. La revisión de IA viene después, como una segunda capa.
Revisión Adversarial
Un agente de IA diferente revisa el código y debe listar 3 problemas antes de decidir aprobar. Esto evita aprobaciones automáticas.
Despacho por Prioridad Transitiva
Las tareas que desbloquean más trabajo downstream se construyen primero, calculando automáticamente la ruta crítica.
Habilidades / Comandos
/spec-to-board
Descompone una SPEC.md en tareas atómicas en tu tablero Kanban con dependencias mapeadas.
/sdlc-orchestrate
Despacha tareas a los trabajadores según prioridad transitiva y detección de conflictos. Se ejecuta como un barrido de crontab.
/sdlc-worker --slot <N>
Ejecuta un trabajador en una ranura de terminal que toma tareas, construye código y crea PRs. Ejecuta 3-4 trabajadores en paralelo.
/sdlc-health
Panel de estado del pipeline en tiempo real que muestra la etapa actual, el agente asignado, el número de reintentos y el coste acumulado de cada tarea.
/sdlc-stop
Apagado ordenado: los trabajadores activos terminan su tarea actual, las tareas no iniciadas vuelven a Pendiente.
Guía Paso a Paso
1. Escribe tu Especificación
Crea un SPEC.md para tu proyecto describiendo lo que quieres construir.
2. Descompón en Tareas
claude -p "/spec-to-board"
Esto lee tu SPEC.md, lo descompone en tareas atómicas, mapea dependencias y las crea en tu tablero Kanban.
3. Inicia los Trabajadores
Abre 3-4 ventanas de terminal, cada una como una ranura de trabajador:
# Terminal 2 — Constructor
claude -p "/sdlc-worker --slot T2"
# Terminal 3 — Constructor
claude -p "/sdlc-worker --slot T3"
# Terminal 4 — Revisor
claude -p "/sdlc-worker --slot T4"
# Terminal 5 — Probador
claude -p "/sdlc-worker --slot T5"
4. Inicia el Orquestador
# Añadir a crontab (se ejecuta cada 15 minutos)
crontab -e
# Añadir: */15 * * * * ~/.claude/sdlc/agentflow-cron.sh >> /tmp/agentflow-orchestrate.log 2>&1
5. Monitoriza e Interviene
Abre tu tablero Kanban en el teléfono. Observa cómo las tareas fluyen por el pipeline. Arrastra cualquier tarjeta a "Necesita Humano" para intervenir. Ejecuta /sdlc-health para un panel de terminal.
6. Detén el Pipeline
claude -p "/sdlc-stop"
Compuertas de Calidad
Cada etapa impone compuertas específicas antes de la promoción:
- Construcción a Revisión:
tsc+eslint+npm testdeben pasar todos (determinista) - Revisión a Pruebas: El revisor adversarial debe listar 3 problemas antes de aprobar
- Pruebas a Integración: Umbral de cobertura del 80% en archivos nuevos
- Integración a Terminado: Suite de pruebas completa en main después del merge; auto-reversión en caso de fallo
Seguimiento de Costes
Seguimiento de costes por tarea con límites por etapa (valores predeterminados de Sonnet):
- Investigación: ~$0.10
- Construcción: ~$0.40
- Revisión: ~$0.10
- Pruebas: ~$0.05
- Integración: ~$0.03
Protecciones automáticas: advertencia en $3/$8, parada dura en $10/$20 (Sonnet/Opus) con escalada a humano.
Seguridad y Recuperación
- Auto-reversión: Los fallos de integración activan
git revert(nuevo commit, nunca force-push) - Tareas bloqueadas: Después de 2 intentos fallidos, las tareas escalan a revisión humana
- Detección de agente inactivo: Heartbeat cada 5 min, reasignación tras 10 min de tiempo de espera
- Apagado ordenado:
/sdlc-stopdrena trabajadores, devuelve las tareas no iniciadas a la lista de pendientes - Detección de expansión del alcance: Los archivos diff del PR se comparan con la lista de archivos prevista
- Detección de desviación de la especificación: La comparación hash SHA-256 detecta cambios de requisitos a mitad del sprint
Instalación
# Clonar el repositorio
git clone https://github.com/UrRhb/agentflow.git
# Copiar las habilidades y prompts a la configuración de Claude Code
cp -r agentflow/skills/* ~/.claude/skills/
cp -r agentflow/prompts/* ~/.claude/sdlc/prompts/
cp agentflow/conventions.md ~/.claude/sdlc/conventions.md
O instalar como plugin de Claude Code:
/plugin marketplace add UrRhb/agentflow
/plugin install agentflow
Buenas Prácticas
- Haz: Escribe una SPEC.md clara antes de ejecutar
/spec-to-board - Haz: Comienza con 3-4 trabajadores para un proyecto típico
- Haz: Monitoriza desde tu tablero Kanban y arrastra las tarjetas a "Necesita Humano" cuando sea necesario
- Haz: Revisa LEARNINGS.md periódicamente — captura patrones comunes de fallo
- No Hagas: Saltarte las compuertas de calidad deterministas — detectan la mayoría de los problemas de forma económica
- No Hagas: Hacer force-push a main — AgentFlow usa
git revertpor seguridad - No Hagas: Ejecutar más trabajadores de los que el paralelismo de tu proyecto soporta
Solución de Problemas
Problema: El trabajador parece atascado o inactivo
Síntomas: La tarjeta de tarea no se ha movido en 15+ minutos, sin nuevos comentarios
Solución: El orquestador detecta agentes inactivos mediante heartbeat y reasigna después de 10 minutos. Si el problema persiste, ejecuta /sdlc-health para comprobar el estado y arrastra manualmente la tarjeta de vuelta a Pendiente.
Problema: Se activó la protección de costes
Síntomas: La tarea se movió a "Necesita Humano" con la etiqueta COST:CRITICAL Solución: Revisa el hilo de comentarios de la tarea para ver el contexto acumulado. Decide si aumentar el presupuesto, simplificar la tarea o dividirla en partes más pequeñas.
Problema: Falla la prueba de integración después del merge
Síntomas: La tarea se revirtió automáticamente desde main Solución: La auto-reversión preserva la estabilidad de main. Revisa el contexto de reintento de la tarea en los comentarios, que lleva registro de lo que se intentó y lo que falló. El siguiente trabajador asignado usará este contexto.
Habilidades Relacionadas
@brainstorming- Úsalo antes de AgentFlow para diseñar tu SPEC.md@writing-plans- Complementa la escritura de especificaciones para la descomposición de tareas@test-driven-development- Funciona bien con las compuertas de calidad de AgentFlow@subagent-driven-development- Enfoque alternativo para la coordinación multi-agente
Recursos Adicionales
- Repositorio de AgentFlow
- Documentación de Arquitectura
- Registro de Brechas (45 modos de fallo)
- Guía de Inicio
Limitaciones
- Usa esta habilidad solo cuando la tarea coincida claramente con el alcance descrito anteriormente.
- No trates el resultado como un sustituto de la validación específica del entorno, las pruebas o la revisión de expertos.
- Detente y pide aclaraciones si faltan las entradas requeridas, los permisos, los límites de seguridad o los criterios de éxito.