Orchestration Patterns - Savvy AI

Guia para elegir y configurar la estrategia de paralelizacion correcta segun la tarea.

Decision Matrix: Subagents vs Agent Teams

Usar Subagents (90% de los casos)

Subagents corren dentro de la sesion principal y devuelven resultados resumidos.

Cuando elegir:

• Tareas enfocadas donde solo importa el resultado
• Busquedas, lectura de archivos, verificaciones
• Trabajo en archivos independientes sin coordinacion
• Menor costo de tokens
• No se necesita comunicacion entre workers

Ejemplos en Savvy AI:

• Implementar features en carpetas separadas (lib/features/recurrence/, lib/features/insights/)
• Correr tests en paralelo
• Buscar patrones en el codebase
• Generar codigo boilerplate para multiples entidades

Usar Agent Teams (tareas complejas colaborativas)

Agent Teams son sesiones Claude independientes que se comunican entre si.

Cuando elegir:

• Review multi-perspectiva (seguridad, performance, tests)
• Debugging con hipotesis competitivas
• Features cross-layer (frontend + backend + tests en paralelo)
• Investigacion con debate (evaluar trade-offs tecnicos)
• Coordinacion donde teammates necesitan compartir hallazgos

Ejemplos en Savvy AI:

• Code review del PR completo (seguridad financiera, performance de BD, coverage de tests)
• Debugging de un bug que cruza BLoC + Repository + Drift
• Implementar feature nueva donde UI, logica de negocio y tests se informan mutuamente
• Evaluar migracion tecnologica (e.g., Supabase vs Firebase)

Comparacion Rapida

Agent Teams: Conceptos Clave

Arquitectura

• Team Lead: La sesion principal que crea el equipo, asigna tareas y sintetiza resultados
• Teammates: Sesiones Claude independientes con su propio contexto
• Task List: Lista compartida con estados (pending, in_progress, completed) y dependencias
• Mailbox: Sistema de mensajes para comunicacion inter-agente

Modos de Visualizacion

• In-process (default): Todos los teammates en el mismo terminal. Shift+Up/Down para navegar.
• Split panes: Cada teammate en su propio panel (requiere tmux o iTerm2).

Delegate Mode (Shift+Tab)

Restringe al lead a solo coordinar (spawn, mensajes, tasks). Evita que el lead implemente codigo directamente. Util para tareas donde todo el trabajo lo hacen los teammates.

Plan Approval

Se puede requerir que un teammate planifique antes de implementar. El lead revisa y aprueba/rechaza el plan antes de que el teammate proceda.

Mejores Practicas

1. Contexto en spawn prompts: Los teammates NO heredan el historial del lead. Incluir todo el contexto necesario en el prompt de spawn.
2. 5-6 tasks por teammate: Mantiene a todos productivos y permite reasignar trabajo.
3. File ownership distinto: Dos teammates editando el mismo archivo causa overwrites. Dividir por carpeta/feature.
4. Monitorear y redirigir: Revisar progreso periodicamente, redirigir enfoques que no funcionan.
5. Empezar con research/review: Si es la primera vez, usar teams para tareas sin escritura de codigo primero.

Limitaciones

• No se puede resumir sesion con teammates in-process
• Un solo team por sesion
• No se pueden anidar teams (teammates no crean sub-teams)
• El lead es fijo (no se puede promover un teammate)
• Permisos se heredan del lead al crear; se pueden cambiar individualmente despues

Team Compositions para Savvy AI

1. Financial Feature Sprint

Proposito: Implementar un feature financiero nuevo end-to-end.

Prompt para el lead:

Crea un agent team para implementar [FEATURE]. Spawn 4 teammates:
1. Domain Expert: Crea entidades, use cases y repository interfaces en lib/features/[feature]/domain/
2. Data Implementer: Implementa data sources, repository impls y services en lib/features/[feature]/data/
3. UI Builder: Crea BLoC, pages y widgets en lib/features/[feature]/presentation/
4. Test Writer: Escribe tests unitarios y widget tests en test/features/[feature]/

Domain Expert completa primero, luego Data Implementer y UI Builder en paralelo, luego Test Writer.
Requiere plan approval para Domain Expert.

Dependencias:

• Domain Expert -> Data Implementer, UI Builder (paralelo)
• Data Implementer + UI Builder -> Test Writer

File ownership:

• Domain: lib/features/[x]/domain/
• Data: lib/features/[x]/data/
• UI: lib/features/[x]/presentation/
• Tests: test/features/[x]/

2. Multi-Perspective Code Review

Proposito: Revisar un PR o set de cambios desde multiples angulos criticos para fintech.

Prompt para el lead:

Crea un agent team para revisar los cambios en [archivos/PR]. Spawn 3 reviewers:
1. Security Reviewer: Revisa seguridad financiera - manejo de montos, cifrado, validacion de inputs, inyeccion SQL en Drift, API keys expuestas, almacenamiento seguro
2. Performance Reviewer: Revisa queries Drift, uso de streams, rebuilds innecesarios de widgets, manejo de listas grandes, memory leaks en BLoC
3. Architecture Reviewer: Revisa adherencia a Clean Architecture, separacion de capas, uso correcto de BLoC, Equatable en states, manejo de errores con Either

Cada reviewer reporta hallazgos con severidad (critico/alto/medio/bajo).

Sin dependencias - los 3 trabajan en paralelo.

3. Competing Hypothesis Debugging

Proposito: Debuggear un issue complejo donde la causa raiz no es clara.

Prompt para el lead:

Los usuarios reportan [PROBLEMA]. Crea un agent team con 3 investigadores:
1. Hypothesis A: El problema esta en [capa/componente A]. Investiga [archivos].
2. Hypothesis B: El problema esta en [capa/componente B]. Investiga [archivos].
3. Hypothesis C: El problema esta en [capa/componente C]. Investiga [archivos].

Los investigadores deben compartir hallazgos entre si y intentar refutar las hipotesis de los demas.
Actualiza un documento de hallazgos con el consenso.

4. Cross-Layer Feature

Proposito: Implementar un cambio que cruza multiples capas (Drift schema + Repository + BLoC + UI).

Prompt para el lead:

Crea un agent team para implementar [CAMBIO CROSS-LAYER]. Spawn 3 teammates:
1. Backend: Modifica schema Drift, migraciones, data sources y repositories en lib/features/[x]/data/
2. Logic: Actualiza BLoC events/states, use cases y logica de negocio
3. Frontend: Actualiza UI pages y widgets para reflejar los cambios

Backend completa primero (schema es dependencia). Luego Logic y Frontend en paralelo.
Usa delegate mode para que yo solo coordine.

5. Research & Evaluate

Proposito: Evaluar una decision tecnica con multiples perspectivas.

Prompt para el lead:

Necesito evaluar [DECISION TECNICA] para Savvy AI. Crea un agent team:
1. Advocate: Investiga y argumenta A FAVOR de [opcion A]. Busca documentacion, benchmarks, casos de exito.
2. Critic: Investiga y argumenta EN CONTRA de [opcion A] y a favor de alternativas. Busca limitaciones, costos ocultos, problemas.
3. Integrator: Evalua ambas perspectivas, analiza el impacto especifico en nuestra arquitectura Clean + BLoC + Drift, y recomienda la mejor opcion con justificacion.

Advocate y Critic trabajan en paralelo, comparten hallazgos, debaten. Integrator sintetiza al final.

6. Sprint Implementation (Large)

Proposito: Implementar multiples features independientes en paralelo (como Sprint 7).

Prompt para el lead:

Crea un agent team para implementar Sprint [N]. Spawn teammates para cada feature:
1. [Feature A] Developer: Implementa [descripcion] en lib/features/[a]/ con tests en test/features/[a]/
2. [Feature B] Developer: Implementa [descripcion] en lib/features/[b]/ con tests en test/features/[b]/
3. [Feature C] Developer: Implementa [descripcion] en lib/features/[c]/ con tests en test/features/[c]/
4. Integrator: Despues de que terminen los 3, integra en dashboard/DI y corre flutter analyze.

Features 1-3 en paralelo, Integrator espera a que terminen.
Cada developer debe seguir Clean Architecture (domain -> data -> presentation).
Consultar los skills relevantes en .claude/skills/.

Referencia Rapida

Comandos del Lead

• Spawn: "Crea un teammate para [tarea]"
• Assign: "Asigna la tarea X al teammate Y"
• Message: "Dile a [teammate] que [instruccion]"
• Broadcast: "Dile a todos que [mensaje]"
• Plan approval: "Requiere plan approval para [teammate]"
• Shutdown: "Pide a [teammate] que termine"
• Cleanup: "Limpia el equipo"

Atajos de Teclado (In-Process Mode)

• Shift+Up/Down: Navegar entre teammates
• Shift+Tab: Toggle delegate mode
• Enter: Ver sesion de un teammate
• Escape: Interrumpir turno del teammate
• Ctrl+T: Toggle task list