@iaforged/context-code 1.0.84 → 1.0.86

package/docs/MULTI_SQUAD_ORCHESTRATION_PLAN.md

@@ -0,0 +1,639 @@
+# Plan De Mejora: Orquestacion Jerarquica Multi-Proveedor
+
+## Objetivo
+
+Llevar `Context Code` desde el estado actual de `multi-provider + multi-profile + SQLite` a una arquitectura de trabajo por escuadrones, donde:
+
+- cada proveedor funciona como un `workspace` o `escuadron`
+- cada escuadron puede tener multiples perfiles
+- cada escuadron puede tener multiples subagentes internos
+- cada escuadron tiene su propio orquestador local
+- existe un orquestador principal que coordina a todos los escuadrones
+- todo el estado operativo persiste en SQLite
+
+La meta no es solo cambiar de proveedor. La meta es poder montar un `equipo de desarrollo agentico` con estructura real.
+
+## Vision
+
+La arquitectura final debe verse asi:
+
+- `Orquestador principal`
+  decide la estrategia general, reparte trabajo por dominios y consolida resultados
+- `Orquestador de escuadron`
+  pertenece a un proveedor concreto y reparte tareas entre subagentes internos de ese proveedor
+- `Subagentes de escuadron`
+  ejecutan tareas especializadas
+- `Perfiles de proveedor`
+  representan cuentas, modelos, base URLs y credenciales
+- `SQLite`
+  almacena configuracion, equipos, asignaciones, ejecuciones y trazabilidad
+
+Ejemplo conceptual:
+
+- `Claude squad`
+  - `claude-orchestrator`
+  - `frontend-lead`
+  - `ui-reviewer`
+  - `ux-polish`
+- `OpenAI squad`
+  - `openai-orchestrator`
+  - `backend-lead`
+  - `api-architect`
+  - `refactorer`
+- `MiniMax squad`
+  - `minimax-orchestrator`
+  - `rapid-implementer`
+  - `docs-helper`
+  - `test-writer`
+- `Global orchestrator`
+  - asigna frontend a Claude
+  - asigna backend a OpenAI
+  - asigna docs o pruebas a otro escuadron
+
+## Principios De Diseño
+
+1. No mezclar proveedor, perfil, agente y rol.
+2. El orquestador principal no depende de un proveedor fijo.
+3. Cada escuadron puede evolucionar sin romper la organizacion global.
+4. Los secretos siguen fuera del estado visible y se manejan por la capa de credenciales ya migrada a SQLite cifrado local.
+5. La primera version debe priorizar control manual y trazabilidad antes que automatizacion completa.
+
+## Capas Del Sistema
+
+### 1. Provider Workspace
+
+Representa al proveedor como unidad organizacional.
+
+Ejemplos:
+
+- `claude`
+- `openai`
+- `minimax`
+- `zai`
+- `openrouter`
+
+Un workspace define:
+
+- nombre visible
+- foco principal del escuadron
+- si esta habilitado
+- reglas de seleccion de perfiles y agentes
+
+### 2. Provider Profile
+
+Representa una cuenta o configuracion concreta dentro del workspace.
+
+Ejemplos:
+
+- `claude/main`
+- `claude/team-a`
+- `openai/work`
+- `minimax/fast-lane`
+
+Un profile define:
+
+- credenciales
+- modelo por defecto
+- base URL
+- estado operativo
+- preferencias runtime
+
+### 3. Provider Agent
+
+Representa un subagente interno de un escuadron.
+
+Ejemplos:
+
+- `claude/frontend-lead`
+- `claude/ui-reviewer`
+- `openai/backend-lead`
+- `openai/api-architect`
+
+Un agent define:
+
+- rol
+- prompt base
+- herramientas permitidas
+- modelo override opcional
+- capacidades
+- si es o no orquestador local
+
+### 4. Team
+
+Representa un equipo de trabajo transversal.
+
+Ejemplos:
+
+- `core-dev`
+- `release-team`
+- `feature-squad`
+
+### 5. Orchestration Run
+
+Representa una ejecucion real:
+
+- objetivo
+- equipo usado
+- orquestador global
+- subtareas
+- asignaciones
+- resultados
+
+## Modelo De Orquestacion
+
+### Orquestador Principal
+
+Responsabilidades:
+
+- entender la meta global
+- descomponer trabajo por dominio
+- asignar trabajo al escuadron correcto
+- consolidar respuestas de los escuadrones
+- decidir reintentos, escalaciones y cierres
+
+### Orquestador De Escuadron
+
+Responsabilidades:
+
+- recibir trabajo del orquestador principal
+- descomponerlo internamente
+- seleccionar subagentes del mismo proveedor
+- validar el output del escuadron
+- devolver un resultado consolidado al orquestador principal
+
+### Subagentes Del Escuadron
+
+Responsabilidades:
+
+- ejecutar tareas concretas
+- reportar al orquestador del escuadron
+- no coordinar fuera de su escuadron en v1
+
+## Modelo SQLite Propuesto
+
+### Tablas Base
+
+#### `provider_workspaces`
+
+- `id`
+- `provider`
+- `display_name`
+- `domain_focus`
+- `is_enabled`
+- `created_at`
+- `updated_at`
+
+#### `provider_profiles`
+
+- `id`
+- `workspace_id`
+- `provider`
+- `name`
+- `agent_name`
+- `base_url`
+- `default_model`
+- `is_active`
+- `created_at`
+- `updated_at`
+
+Nota:
+
+- esta tabla puede extender o reemplazar gradualmente la estructura actual de perfiles ya existente en SQLite
+
+#### `provider_agents`
+
+- `id`
+- `workspace_id`
+- `profile_id`
+- `name`
+- `role_kind`
+- `system_prompt`
+- `model_override`
+- `tool_policy`
+- `autonomy_level`
+- `is_orchestrator`
+- `is_enabled`
+- `created_at`
+- `updated_at`
+
+#### `provider_agent_capabilities`
+
+- `id`
+- `agent_id`
+- `capability`
+- `weight`
+
+Ejemplos de `capability`:
+
+- `frontend`
+- `backend`
+- `review`
+- `docs`
+- `testing`
+- `speed`
+- `quality`
+- `tools`
+
+#### `teams`
+
+- `id`
+- `name`
+- `description`
+- `global_orchestrator_agent_id`
+- `is_enabled`
+- `created_at`
+- `updated_at`
+
+#### `team_domains`
+
+- `id`
+- `team_id`
+- `domain_name`
+- `workspace_id`
+- `local_orchestrator_agent_id`
+- `lead_agent_id`
+- `selection_mode`
+- `required`
+
+Ejemplos de `domain_name`:
+
+- `frontend`
+- `backend`
+- `qa`
+- `docs`
+- `architecture`
+
+#### `team_domain_members`
+
+- `id`
+- `team_domain_id`
+- `agent_id`
+- `duty`
+- `priority`
+
+#### `orchestration_runs`
+
+- `id`
+- `team_id`
+- `goal`
+- `global_orchestrator_agent_id`
+- `status`
+- `created_at`
+- `started_at`
+- `finished_at`
+
+#### `orchestration_tasks`
+
+- `id`
+- `run_id`
+- `parent_task_id`
+- `scope_type`
+- `team_domain_id`
+- `assigned_agent_id`
+- `title`
+- `instructions`
+- `status`
+- `result_summary`
+- `created_at`
+- `finished_at`
+
+#### `orchestration_messages`
+
+- `id`
+- `run_id`
+- `task_id`
+- `from_agent_id`
+- `to_agent_id`
+- `message_type`
+- `content`
+- `created_at`
+
+## Modulos De Aplicacion A Crear
+
+### 1. `ProviderWorkspaceStore`
+
+Responsable de:
+
+- workspaces de proveedor
+- perfiles asociados
+- metadatos del escuadron
+
+### 2. `ProviderAgentStore`
+
+Responsable de:
+
+- CRUD de subagentes
+- capacidades
+- politica de herramientas
+- prompt base
+
+### 3. `TeamStore`
+
+Responsable de:
+
+- equipos
+- dominios
+- leads
+- miembros
+- orquestador global
+
+### 4. `OrchestrationPlanner`
+
+Responsable de:
+
+- partir una meta en dominios
+- decidir a que escuadron va cada frente
+- construir tareas para orquestadores locales
+
+### 5. `GlobalOrchestratorRuntime`
+
+Responsable de:
+
+- correr el flujo del orquestador principal
+- crear `runs`
+- crear tareas
+- pedir consolidaciones
+
+### 6. `SquadOrchestratorRuntime`
+
+Responsable de:
+
+- repartir tareas internas del escuadron
+- seleccionar subagentes internos
+- consolidar trabajo del escuadron
+
+### 7. `AgentExecutionRuntime`
+
+Responsable de:
+
+- ejecutar agentes concretos con el provider/profile correcto
+- resolver modelo, credenciales, tools y contexto
+
+## Comandos CLI Recomendados
+
+### Fase Inicial
+
+- `/workspace`
+- `/workspace list`
+- `/workspace show <provider>`
+- `/agent`
+- `/agent list <provider>`
+- `/agent create <provider> <name>`
+- `/agent edit <provider> <name>`
+- `/team`
+- `/team create <name>`
+- `/team show <name>`
+- `/team orchestrator <team> <provider>/<agent>`
+- `/team domain <team> <domain> <provider>/<agent>`
+
+### Fase De Orquestacion
+
+- `/orchestrate <team> "<objetivo>"`
+- `/run list`
+- `/run show <id>`
+- `/run cancel <id>`
+
+## Fases De Implementacion
+
+### Fase 1: Modelo Organizacional
+
+Objetivo:
+
+- modelar escuadrones, agentes y equipos sin ejecutar orquestacion real
+
+Entregables:
+
+- tablas SQLite nuevas
+- stores nuevos
+- comandos `/workspace`, `/agent`, `/team`
+- UI/CLI para asignar:
+  - orquestador principal
+  - orquestador local de escuadron
+  - miembros por dominio
+
+Criterio de cierre:
+
+- se puede definir un equipo completo en SQLite
+- se puede inspeccionar desde CLI
+
+### Fase 2: Orquestacion Global Basica
+
+Objetivo:
+
+- introducir el orquestador principal y la asignacion por dominio
+
+Entregables:
+
+- `orchestration_runs`
+- `orchestration_tasks`
+- `GlobalOrchestratorRuntime`
+- `/orchestrate`
+
+Regla de v1:
+
+- el orquestador principal asigna trabajo al `lead agent` o al `local orchestrator`
+- no hay subdelegacion profunda aun
+
+Criterio de cierre:
+
+- una meta puede dividirse por dominios y asignarse a distintos escuadrones
+
+### Fase 3: Orquestadores De Escuadron
+
+Objetivo:
+
+- habilitar que cada proveedor tenga su propia mini-orquestacion
+
+Entregables:
+
+- `SquadOrchestratorRuntime`
+- seleccion de subagentes internos
+- consolidacion interna por escuadron
+- trazabilidad en `orchestration_messages`
+
+Criterio de cierre:
+
+- el orquestador global delega a un escuadron
+- el escuadron decide internamente quien hace cada parte
+- el escuadron responde consolidado
+
+### Fase 4: Politicas Inteligentes
+
+Objetivo:
+
+- agregar seleccion semiautomatica y fallback
+
+Entregables:
+
+- ranking por capacidad
+- costo
+- latencia
+- calidad
+- soporte de tools
+- fallback entre profiles y agentes
+
+Criterio de cierre:
+
+- el sistema puede sugerir o elegir automaticamente quien ocupa cada cargo
+
+### Fase 5: UX Y Gobierno
+
+Objetivo:
+
+- hacer el sistema utilizable y operable en el dia a dia
+
+Entregables:
+
+- comandos de diagnostico
+- vista de equipo actual
+- vista de topologia
+- historial de runs
+- confirmaciones y validaciones
+
+Criterio de cierre:
+
+- la orquestacion se puede usar sin inspeccionar la base manualmente
+
+## Cantidad Recomendada De Agentes Para Desarrollarlo
+
+### Equipo minimo: 4 agentes
+
+Recomendado si se quiere avanzar con cuidado y poco solapamiento.
+
+- `Agente 1`: SQLite y stores
+- `Agente 2`: CLI y comandos
+- `Agente 3`: runtime de orquestacion
+- `Agente 4`: validacion, tests y documentacion
+
+### Equipo recomendado: 6 agentes
+
+Es la opcion mas equilibrada para construir esto bien y rapido.
+
+- `Agente A`: esquema SQLite y migraciones
+- `Agente B`: `ProviderWorkspaceStore` y `ProviderAgentStore`
+- `Agente C`: `TeamStore` y comandos `/team`
+- `Agente D`: comandos `/workspace` y `/agent`
+- `Agente E`: `GlobalOrchestratorRuntime`
+- `Agente F`: `SquadOrchestratorRuntime`, trazabilidad y pruebas
+
+### Equipo agresivo: 8 agentes
+
+Solo vale la pena si se controla muy bien la coordinacion.
+
+- separa runtime, stores, CLI, tests, docs, visualizacion y migraciones
+- aumenta riesgo de conflictos si no se define ownership exacto de archivos
+
+## Recomendacion De Ejecucion
+
+Para este repo, la recomendacion real es trabajar con `6 agentes`.
+
+Motivo:
+
+- el problema ya no es pequeno
+- ya existe infraestructura SQLite previa
+- hay que tocar almacenamiento, runtime y UX
+- pero aun se puede dividir en write scopes claros
+
+## Reparto Recomendado De Ownership
+
+### Worker 1
+
+Responsable de:
+
+- `src/utils/model/providerProfilesDb.ts`
+- nuevas tablas y migraciones SQLite
+- stores base de workspaces/agentes/equipos
+
+### Worker 2
+
+Responsable de:
+
+- `src/commands/workspace/*`
+- `src/commands/agent/*`
+- registro de comandos y ayudas
+
+### Worker 3
+
+Responsable de:
+
+- `src/commands/team/*`
+- resolucion de equipos y dominios
+
+### Worker 4
+
+Responsable de:
+
+- `src/services/orchestration/global/*`
+- `GlobalOrchestratorRuntime`
+
+### Worker 5
+
+Responsable de:
+
+- `src/services/orchestration/squad/*`
+- `SquadOrchestratorRuntime`
+- seleccion de subagentes internos
+
+### Worker 6
+
+Responsable de:
+
+- pruebas
+- fixtures SQLite
+- diagnosticos
+- README y documentacion tecnica
+
+## Riesgos Tecnicos
+
+1. Mezclar profile con agent
+   Rompe la separacion entre cuenta y rol.
+
+2. Hacer asignacion automatica demasiado pronto
+   Lleva a comportamiento dificil de depurar.
+
+3. No registrar trazabilidad de decisiones
+   Hace imposible entender por que un escuadron eligio cierto subagente.
+
+4. Delegacion recursiva sin limites
+   Puede producir loops o explosion de tareas.
+
+5. Acoplar demasiado el orquestador principal a un solo proveedor
+   Mata la flexibilidad del sistema.
+
+## Reglas De Seguridad Operativa
+
+- toda tarea debe tener `owner agent`
+- toda tarea debe tener `status`
+- toda subdelegacion debe quedar registrada
+- cada orquestador local solo puede delegar a miembros de su escuadron
+- el orquestador principal no ejecuta trabajo de dominio si existe escuadron asignado
+
+## Definicion De Exito
+
+El proyecto se considera bien implementado cuando:
+
+- existe un orquestador principal configurable
+- cada escuadron tiene su propio orquestador local
+- cada proveedor puede tener varios subagentes internos
+- los equipos se pueden definir desde CLI
+- las ejecuciones se registran en SQLite
+- los resultados se pueden inspeccionar sin leer logs crudos
+
+## Orden Recomendado Inmediato
+
+1. Fase 1 completa
+2. Fase 2 minima operativa
+3. Fase 3 sobre un solo flujo controlado
+4. luego automatizacion
+
+## Siguiente Paso Concreto
+
+El siguiente paso correcto no es implementar todo de una vez.
+
+El siguiente paso correcto es:
+
+1. crear tablas nuevas en SQLite
+2. crear `ProviderWorkspaceStore`, `ProviderAgentStore` y `TeamStore`
+3. exponer comandos manuales para definir la topologia
+
+Cuando eso exista, la orquestacion se vuelve una capa encima de una estructura ya estable.