@iaforged/context-code 1.0.84 → 1.0.86

package/docs/TEAMS_AND_ORCHESTRATION.md

@@ -0,0 +1,626 @@
+## Equipos con varios proveedores
+
+Esta parte permite usar varios proveedores como si fueran un equipo de trabajo. No necesitas aprender terminos internos: piensa en cuatro niveles simples.
+
+- `workspace`: representa un proveedor dentro del sistema de equipos, por ejemplo `claude`, `openai`, `minimax` u `ollama`.
+- `agent`: es un perfil operativo dentro de un proveedor. Ejemplo: `claude/frontend-lead` o `openai/backend-lead`.
+- `team`: es el equipo completo para un objetivo. Ejemplo: `core-dev`.
+- `equipo interno`: es un grupo de trabajo dentro del team. Ejemplos: `frontend`, `backend`, `docs`, `planning`, `tests`, `review`, `database`. Cuando creas un team con `/workspace setup`, el sistema arma 4 equipos internos por defecto (`frontend`, `backend`, `docs`, `planning`); los que no asignes a un agente quedaran como warnings al ejecutar.
+- `ejecucion` (`run` internamente): es una ejecucion guardada de un objetivo. Tiene tareas, mensajes, resultados y estado. En los comandos veras `<run-id>` porque es el identificador tecnico.
+
+Mini glosario para no confundirse con los roles internos:
+
+- `orquestador global`: el agente que coordina todo el team. Lee el objetivo del usuario, lo descompone, asigna trabajo a cada equipo interno y consolida los reportes finales para entregartelos a ti.
+- `orquestador local`: por equipo interno. Recibe la parte del objetivo que le toca, decide como dividirla entre los miembros del equipo (o como hacerla solo en `modo autonomo`) y reporta de vuelta al orquestador global.
+- `lead`: el agente principal de un equipo interno. En la mayoria de los flujos, el `orquestador local` y el `lead` son el mismo agente.
+- `modo autonomo`: cuando un equipo interno no tiene miembros extra, el orquestador local asume internamente los roles que necesite (planner, executor, reviewer, etc.) sin necesitar mas agentes configurados.
+- `global-plan` / `squad-plan` / `task.completed` / `run-report`: tipos de mensajes que se guardan en la ejecucion. El primero lo emite el orquestador global al planear, el segundo cada orquestador local cuando recibe su tarea, y los reportes son lo que devuelven cuando terminan. Los puedes ver con `/run messages <run-id>`.
+
+Orden normal de uso:
+
+1. Configuras un proveedor y un perfil con `/provider`, `/login` y `/model`.
+2. Ejecutas `/workspace setup` para crear el equipo base sin hacer todo a mano.
+3. Revisas el equipo con `/team show`.
+4. Generas una ejecucion con `/orchestrate`.
+5. Ejecutas o revisas la ejecucion con `/run`.
+6. Si quieres seleccion automatica o fallback, usas `/policy`.
+
+### `/workspace`
+
+`/workspace` sirve para revisar que proveedores pueden participar en equipos. Un workspace no es una carpeta del proyecto; aqui significa "este proveedor esta disponible para tener agentes".
+
+Comandos:
+
+```sh
+/workspace
+/workspace list
+/workspace show minimax
+/workspace enable claude
+/workspace disable openrouter
+/workspace setup
+/workspace orchestrator
+/workspace setup core-dev orchestrator=backend claude/main:frontend openai/work:backend
+```
+
+Uso practico:
+
+- `/workspace list` muestra los proveedores registrados para equipos.
+- `/workspace show minimax` muestra si MiniMax esta habilitado para equipos.
+- `/workspace enable claude` permite que agentes de Claude participen en equipos.
+- `/workspace disable openrouter` evita que OpenRouter sea usado por la orquestacion.
+- `/workspace setup` abre el wizard interactivo.
+- `/workspace orchestrator` abre un selector para elegir equipo y cambiar su orquestador principal.
+- `/workspace setup core-dev orchestrator=backend claude/main:frontend openai/work:backend` salta el wizard y crea una base de equipo lista para usar.
+
+El wizard de `/workspace setup` tiene opciones para:
+
+- preparar un proveedor/perfil
+- abrir login o configuracion si faltan credenciales
+- llevarte a seleccionar modelo usando `/model`
+- escribir el nombre del equipo
+- escoger el orquestador principal desde perfiles existentes, crear/activar un perfil nuevo, elegir un area o usar un valor personalizado
+- crear el comando base para armar el equipo con autocompletado
+- mostrar workspaces disponibles
+- mostrar ayuda y ejemplo
+
+Cuando ya tienes perfiles listos, el modo rapido hace esto por ti:
+
+1. Habilita cada proveedor como workspace.
+2. Crea un agente por area con nombre `<area>-lead`.
+3. Conecta cada agente al perfil que escribiste.
+4. Crea el equipo si todavia no existe.
+5. Usa `orchestrator=...` como coordinador principal, o el primer agente si no lo indicas.
+6. Crea o actualiza las areas del equipo.
+
+El input tambien ayuda con autocompletado para `/workspace`: subcomandos, proveedores, perfiles guardados y areas comunes como `frontend`, `backend`, `docs`, `tests`, `review`, `database` y `devops`.
+
+Para cambiar el orquestador principal despues de crear el equipo:
+
+```sh
+/workspace orchestrator
+```
+
+Ese wizard primero muestra los equipos guardados y luego los agentes disponibles para asignar uno como coordinador global. Si prefieres hacerlo directo:
+
+```sh
+/workspace orchestrator core-dev openai/backend-lead
+```
+
+Formato rapido:
+
+```text
+/workspace setup <equipo> [orchestrator=<area|proveedor/agente>] <proveedor/perfil:area> [...]
+```
+
+Ejemplo:
+
+```sh
+/workspace setup core-dev orchestrator=backend claude/main:frontend openai/work:backend minimax/main:docs
+```
+
+En ese ejemplo:
+
+- `core-dev` es el equipo.
+- `claude/main:frontend` crea o reutiliza `claude/frontend-lead`.
+- `openai/work:backend` crea o reutiliza `openai/backend-lead`.
+- `minimax/main:docs` crea o reutiliza `minimax/docs-lead`.
+- `orchestrator=backend` pone a `openai/backend-lead` como coordinador principal.
+
+Cuando usarlo:
+
+- si un proveedor no aparece como opcion para agentes
+- si quieres desactivar temporalmente un proveedor
+- si quieres confirmar que el sistema reconoce un proveedor antes de crear agentes
+- si quieres armar un equipo rapido sin recordar `/agent` y `/team`
+
+### `/team-auto` — wizard automatico
+
+Si todavia no sabes que equipo asignar a cada proveedor, `/team-auto` lo decide por ti. Detecta los perfiles ya logueados y arma un team con equipos internos estandar (`frontend`, `backend`, `docs`, `planning`):
+
+```sh
+/team-auto              # crea un team llamado "default-team"
+/team-auto core-dev     # crea (o actualiza) un team llamado "core-dev"
+```
+
+Que pasa al ejecutarlo:
+
+1. Detecta los `provider profile` activos (los que ya tienen credencial).
+2. Aplica una heuristica de reparto: Claude -> `frontend`, OpenAI -> `backend`, MiniMax/Z.AI -> `docs`, Ollama/OpenRouter -> `planning`. Si solo tienes 1 proveedor, ese hace TODOS los equipos internos en `modo autonomo`.
+3. Te muestra el plan en pantalla (que equipos va a crear, que agentes va a reusar, quien sera el orquestador global).
+4. Pulsas `Enter` y aplica los cambios, o `Esc` y cancela sin tocar nada.
+
+Cuando un equipo interno queda sin agente compatible (por ejemplo no tienes ningun proveedor que mapee a `docs`), se reporta `sin asignar` en el plan y queda como warning. Despues puedes asignarlo manualmente con `/team equipo <team> docs <provider>/<agent>`.
+
+Si el team ya existe, `/team-auto` solo lo actualiza: no borra agentes ni miembros que ya tuvieras.
+
+Cuando quieras configurarlo todo a mano, sigue habiendo `/workspace setup` (wizard guiado, mas detallado) o el formato corto `/workspace setup <team> orchestrator=... <provider/profile:equipo>...`.
+
+### `/agent`
+
+`/agent` crea nombres de trabajo dentro de cada proveedor. Un agente siempre apunta a un provider profile real.
+
+Ejemplo: si tienes `claude/main`, puedes crear `claude/frontend-lead`. Ese agente usara las credenciales y modelo del perfil `main`, salvo que le pongas un modelo propio.
+
+Comandos:
+
+```sh
+/agent
+/agent list
+/agent list claude
+/agent create claude frontend-lead main
+/agent show claude frontend-lead
+/agent set-role claude frontend-lead frontend
+/agent set-orchestrator claude frontend-lead true
+/agent set-model claude frontend-lead claude-sonnet-4-6
+```
+
+Uso practico:
+
+- `/agent create claude frontend-lead main` crea un agente llamado `frontend-lead` dentro de Claude usando el perfil `main`.
+- `/agent set-role claude frontend-lead frontend` indica que ese agente se especializa en frontend.
+- `/agent set-orchestrator claude frontend-lead true` permite que ese agente coordine trabajo.
+- `/agent set-model claude frontend-lead <modelo>` fuerza un modelo solo para ese agente.
+
+Formato para referirse a un agente:
+
+```text
+provider/agent
+```
+
+Ejemplos:
+
+```text
+claude/frontend-lead
+openai/backend-lead
+minimax/docs-runner
+ollama/local-coder
+```
+
+### `/team`
+
+`/team` arma un equipo usando agentes. El team tiene un coordinador principal y puede dividir el trabajo por areas.
+
+En esta documentacion llamamos `equipo interno` a cada grupo de trabajo. Ejemplos: `frontend`, `backend`, `docs`, `review`, `tests`, `database`.
+
+Comandos:
+
+```sh
+/team
+/team list
+/team create core-dev
+/team orchestrator
+/team orchestrator core-dev claude/frontend-lead
+/team equipo core-dev frontend claude/frontend-lead
+/team equipo core-dev backend openai/backend-lead
+/team add-member core-dev frontend claude/ui-reviewer reviewer
+/team show core-dev
+```
+
+Uso practico:
+
+- `/team create core-dev` crea un equipo llamado `core-dev`.
+- `/team orchestrator` abre un selector para escoger equipo y luego orquestador principal.
+- `/team orchestrator core-dev claude/frontend-lead` define quien coordina todo el equipo.
+- `/team equipo core-dev frontend claude/frontend-lead` dice que el area frontend la lidera `claude/frontend-lead`.
+- `/team equipo core-dev backend openai/backend-lead` dice que backend lo lidera `openai/backend-lead`.
+- `/team add-member core-dev frontend claude/ui-reviewer reviewer` agrega un miembro extra al area frontend.
+- `/team show core-dev` muestra como quedo armado el equipo.
+
+Cuando usas `/team equipo`, ese agente queda como orquestador local y lead del equipo interno al mismo tiempo. Eso significa que usa el perfil/modelo vinculado a ese agente para coordinar su propia area. Por ejemplo, `openai/backend-lead` puede ser el equipo autonomo de backend aunque no tenga miembros extra.
+
+Si un equipo interno no tiene miembros extra, no esta roto. En ese caso opera en modo autonomo: el orquestador local divide internamente el trabajo segun su funcion principal. Backend puede asumir roles temporales como API, base de datos, validaciones y pruebas; frontend puede asumir UI, componentes, estado y pruebas; docs puede asumir guia tecnica y README. Los miembros extra son opcionales cuando quieres dividir mas el trabajo.
+
+Ejemplo mental simple:
+
+- Claude puede coordinar frontend.
+- OpenAI puede coordinar backend.
+- MiniMax puede hacer documentacion o tareas rapidas.
+- Ollama puede actuar como ejecutor local.
+- El coordinador principal mira el objetivo completo y recibe reportes de cada area.
+
+## Crear y ejecutar una ejecucion
+
+Una ejecucion es un objetivo guardado con sus tareas, mensajes, resultados y estado. Por ejemplo: "crear login con UI y API". Internamente se guarda como `run` en SQLite, por eso puedes cerrar la app y luego volver a revisarla.
+
+### `/orchestrate`
+
+`/orchestrate` toma un team y un objetivo, planifica el trabajo, **te muestra el plan en pantalla** y te pregunta si quieres ejecutarlo ya:
+
+```sh
+/orchestrate core-dev crear endpoint de login y UI de acceso
+```
+
+Que pasa cuando lo ejecutas:
+
+1. El sistema valida el team, el orquestador global y los equipos internos.
+2. Crea la ejecucion y todas sus tareas en estado `ready` o `blocked` segun la configuracion del equipo.
+3. **Te muestra el plan**: tareas por equipo, agentes asignados, advertencias de configuracion.
+4. Te ofrece dos teclas:
+   - **`Enter`**: ejecuta inmediatamente las tareas `ready`. Veras progreso en vivo (equipo que esta trabajando, agente activo, fase) y al final un reporte consolidado.
+   - **`Esc`**: deja la ejecucion en `planned`. Puedes revisar con `/run show <run-id>` o ejecutar mas tarde con `/run resume <run-id>`.
+
+Cuando confirmas con Enter, el flujo interno es: orquestador global delega a cada orquestador local -> cada orquestador local ejecuta o subdelega en `modo autonomo` -> cada uno devuelve su reporte de tarea -> el orquestador global consolida y emite el `run-report` final que ves tu.
+
+Si pulsas Esc o no hay tareas `ready` (todo quedo bloqueado), la ejecucion se queda en estado `planned` y el comando termina mostrando los siguientes pasos sugeridos. En ese caso normalmente sigues con:
+
+```sh
+/run show <run-id>     # revisar el plan en detalle
+/run resume <run-id>   # ejecutar despues
+```
+
+### `/run`
+
+`/run` sirve para revisar, ejecutar, reintentar, reasignar o cancelar una ejecucion.
+
+Comandos principales:
+
+```sh
+/run
+/run list
+/run show <run-id>
+/run messages <run-id>
+/run tasks <run-id>
+/run task <task-id>
+/run equipo <run-id> <equipo>
+/run resume <run-id>
+/run cancel <run-id>
+```
+
+Comandos de recuperacion:
+
+```sh
+/run retry <run-id> [task-id]
+/run cancel-task <task-id>
+/run reassign <task-id> <provider>/<agent>
+```
+
+Que hace cada comando:
+
+- `/run list` muestra las ejecuciones guardadas.
+- `/run show <run-id>` muestra resumen, estado, tareas y ultimos mensajes.
+- `/run tasks <run-id>` muestra todas las tareas de la ejecucion.
+- `/run task <task-id>` muestra una tarea concreta con sus mensajes y resultados.
+- `/run equipo <run-id> frontend` muestra solo el area `frontend`.
+- `/run messages <run-id>` muestra la bitacora completa.
+- `/run resume <run-id>` ejecuta tareas listas.
+- `/run cancel <run-id>` detiene la ejecucion.
+- `/run retry <run-id>` reintenta tareas fallidas o bloqueadas.
+- `/run retry <run-id> <task-id>` reintenta una tarea concreta.
+- `/run cancel-task <task-id>` bloquea una tarea para que no continue.
+- `/run reassign <task-id> openai/backend-lead` cambia el agente responsable.
+
+Estados de una ejecucion:
+
+- `planned`: fue creada pero aun no se ejecuto.
+- `in_progress`: esta en ejecucion.
+- `completed`: termino sin tareas abiertas.
+- `failed`: alguna tarea fallo o quedo bloqueada.
+- `cancelled`: fue cancelada por el usuario.
+
+Estados de una tarea:
+
+- `pending`: aun no esta lista.
+- `ready`: puede ejecutarse.
+- `in_progress`: esta ejecutandose.
+- `completed`: termino con resultado.
+- `failed`: fallo al ejecutar.
+- `blocked`: falta configuracion, credenciales, modelo, endpoint o agente valido.
+
+### Ejemplo completo
+
+```sh
+# 1. Configurar dos proveedores y sus perfiles
+/provider claude profile main
+/login
+/model
+
+/provider openai profile work
+/login
+/model
+
+# 2. Crear el team con frontend en Claude y backend en OpenAI
+/workspace setup core-dev orchestrator=backend claude/main:frontend openai/work:backend
+/team show core-dev
+
+# 3. Pedir el objetivo. /orchestrate planifica, muestra el plan
+#    en pantalla y pregunta si ejecutar ya:
+#    [Enter] = ejecuta y veras progreso + reporte final
+#    [Esc]   = solo planifica, queda en estado 'planned'
+/orchestrate core-dev crear login con UI y API
+
+# 4. (Opcional) revisar la bitacora completa de mensajes
+/run list
+/run messages <run-id>
+```
+
+Notas importantes:
+
+- Si `/workspace setup` solo asigno agente a `frontend` y `backend`, los equipos `docs` y `planning` apareceran como `blocked` con warnings al planear. **No es un error**: las tareas ready se ejecutan igual al pulsar Enter, y las bloqueadas las puedes asignar despues con `/team equipo core-dev docs <provider>/<agent>` y reintentar con `/run retry <run-id>`.
+- El reporte final que ves al terminar viene del orquestador global. Si quieres ver lo que cada orquestador local respondio, usa `/run messages <run-id>` o `/run equipo <run-id> <equipo>`.
+
+## Seleccion automatica y fallback
+
+La seleccion automatica permite que Context Code recomiende o aplique que agente debe tomar una tarea. El fallback permite cambiar una tarea fallida o bloqueada a otro agente compatible.
+
+### `/policy`
+
+`/policy` muestra politicas predefinidas. Una politica indica como elegir agentes.
+
+```sh
+/policy list
+/policy show score-with-fallback:quality
+```
+
+Modos disponibles:
+
+- `manual`: usa el agente que ya estaba asignado.
+- `score`: elige el mejor agente por puntaje.
+- `score-with-fallback`: elige el mejor agente y guarda candidatos alternos.
+- `fallback-only`: mantiene la asignacion inicial y solo cambia si algo falla.
+
+Objetivos disponibles:
+
+- `balanced`: equilibrio general.
+- `cost`: prioriza costo.
+- `latency`: prioriza velocidad.
+- `quality`: prioriza calidad.
+- `capability`: prioriza especialidad declarada.
+- `resilience`: prioriza estabilidad y opciones de recuperacion.
+
+Formato:
+
+```text
+modo:objetivo
+```
+
+Ejemplos:
+
+```text
+score-with-fallback:quality
+score:capability
+score-with-fallback:resilience
+manual:balanced
+```
+
+### Comandos de Fase 4
+
+```sh
+/run optimize <run-id> [policy]
+/run assign <run-id> [policy]
+/run fallback <run-id> [task-id] [policy]
+/run explain <run-id>
+```
+
+Que hace cada uno:
+
+- `/run optimize <run-id> score-with-fallback:quality` simula la seleccion y muestra candidatos. No cambia tareas.
+- `/run assign <run-id> score:capability` aplica la seleccion y asigna tareas abiertas.
+- `/run fallback <run-id> <task-id> score-with-fallback:resilience` busca otro agente para una tarea fallida o bloqueada.
+- `/run explain <run-id>` muestra las decisiones guardadas como mensajes `policy.*`.
+
+Reglas importantes:
+
+- cada decision automatica queda guardada en SQLite
+- `/run optimize` es seguro porque solo muestra recomendaciones
+- `/run assign` y `/run fallback` si cambian tareas
+- un agente deshabilitado no debe ser elegido
+- si falta perfil, modelo o credenciales, la tarea puede quedar `blocked`
+- errores de autenticacion no deben reintentarse agresivamente
+
+## Ejemplo completo de flujo de trabajo
+
+Este ejemplo muestra un flujo real de principio a fin. Puedes cambiar `claude`, `openai`, `minimax` u `ollama` por los proveedores que tengas configurados.
+
+### 1. Preparar el primer proveedor
+
+Activa el proveedor, inicia sesion y elige modelo.
+
+```sh
+/provider claude profile main
+/login
+/model
+```
+
+Verifica que quedo activo:
+
+```sh
+/status
+```
+
+Debes revisar que aparezcan proveedor, perfil activo, modelo guardado y credenciales configuradas.
+
+### 2. Preparar otro proveedor
+
+Repite el proceso para otro proveedor. En este ejemplo OpenAI sera backend.
+
+```sh
+/provider openai profile work
+/login
+/model
+/status
+```
+
+Si usas Ollama local, normalmente seria:
+
+```sh
+/provider ollama profile local
+/model
+/status
+```
+
+### 3. Crear el equipo con el wizard
+
+Abre el wizard:
+
+```sh
+/workspace setup
+```
+
+Desde ahi puedes elegir:
+
+- `Preparar proveedor/perfil`: seleccionas proveedor, escribes perfil y el sistema lanza `/provider`. Si faltan credenciales, se abre login/configuracion; despues te lleva a `/model`.
+- `Crear equipo y elegir orquestador`: escribes el nombre del equipo, eliges si el orquestador sale de un perfil existente, de un perfil nuevo, de un area o de un agente ya creado, y luego el input queda listo para completar proveedores, perfiles y areas con autocompletado.
+
+Si ya sabes los perfiles y areas, puedes saltarte el wizard y crear el equipo base en un solo comando:
+
+```sh
+/workspace setup core-dev orchestrator=backend claude/main:frontend openai/work:backend
+/team show core-dev
+```
+
+En este ejemplo:
+
+- `core-dev` es el equipo.
+- `claude/frontend-lead` coordina el equipo completo.
+- `frontend` queda asignado a Claude.
+- `backend` queda asignado a OpenAI.
+
+Si quieres hacerlo a mano, todavia puedes usar `/workspace enable`, `/agent create`, `/agent set-role`, `/team create`, `/team orchestrator` y `/team equipo`. El wizard solo junta esos pasos para evitar errores.
+
+### 4. Crear una ejecucion y revisar el plan en pantalla
+
+```sh
+/orchestrate core-dev crear login con UI y API
+```
+
+A diferencia de versiones anteriores, **`/orchestrate` no se queda en silencio**: te muestra una vista resumen con la ejecucion creada, las tareas por equipo, advertencias y un prompt:
+
+```text
+Plan listo para core-dev
+Ejecucion: 1b4fb901-...
+Objetivo: crear login con UI y API
+Orquestador global: openai/backend-lead
+
+Tareas por equipo
+- backend  -> ready   | assigned=openai/backend-lead
+- docs     -> blocked | assigned=sin asignar
+- frontend -> ready   | assigned=claude/frontend-lead
+- planning -> blocked | assigned=sin asignar
+
+Listas: 2 | Bloqueadas: 2
+
+Advertencias
+- docs: warning -> No hay agente asignable para este equipo.
+- planning: warning -> No hay agente asignable para este equipo.
+
+[Enter] Ejecutar ahora (las bloqueadas se omiten)  |  [Esc] Solo planificar
+```
+
+### 5. Decidir: ejecutar ya, o revisar y ejecutar despues
+
+- **Pulsa `Enter`** y empezara la ejecucion al instante. Solo se disparan las tareas `ready`. Mientras corren, veras lineas de progreso por equipo. Al final llega el reporte consolidado.
+- **Pulsa `Esc`** si prefieres revisar antes. La ejecucion queda en `planned`. Despues puedes inspeccionarla con:
+
+```sh
+/run show <run-id>
+/run tasks <run-id>
+/run equipo <run-id> frontend
+/run equipo <run-id> backend
+```
+
+Si una tarea aparece `blocked`, normalmente falta agente, workspace, perfil, modelo o credencial. Asigna lo que falte y vuelve.
+
+### 6. Ejecutar manualmente cuando hayas pulsado Esc
+
+```sh
+/run resume <run-id>
+```
+
+Luego revisa resultados:
+
+```sh
+/run show <run-id>
+/run messages <run-id>
+```
+
+Si quieres ver una tarea concreta:
+
+```sh
+/run task <task-id>
+```
+
+### 7. Usar seleccion automatica antes de reasignar
+
+Si quieres ver que agente recomienda el sistema sin cambiar nada:
+
+```sh
+/policy list
+/policy show score-with-fallback:quality
+/run optimize <run-id> score-with-fallback:quality
+```
+
+Si la recomendacion te parece correcta, puedes aplicarla:
+
+```sh
+/run assign <run-id> score:capability
+```
+
+Para ver por que se tomaron decisiones:
+
+```sh
+/run explain <run-id>
+```
+
+### 8. Recuperar errores o bloqueos
+
+Si una tarea fallo o quedo bloqueada, puedes reintentar:
+
+```sh
+/run retry <run-id>
+```
+
+O reintentar solo una tarea:
+
+```sh
+/run retry <run-id> <task-id>
+```
+
+Si quieres cambiarla a otro agente manualmente:
+
+```sh
+/run reassign <task-id> claude/frontend-lead
+/run resume <run-id>
+```
+
+Si quieres que el sistema busque otro agente compatible:
+
+```sh
+/run fallback <run-id> <task-id> score-with-fallback:resilience
+/run resume <run-id>
+```
+
+### 9. Cerrar o cancelar
+
+Si todo termino bien:
+
+```sh
+/run show <run-id>
+```
+
+Si necesitas detener la ejecucion:
+
+```sh
+/run cancel <run-id>
+```
+
+### Resumen corto
+
+```sh
+/provider claude profile main
+/login
+/model
+
+/provider openai profile work
+/login
+/model
+
+/workspace setup core-dev orchestrator=backend claude/main:frontend openai/work:backend
+/team show core-dev
+
+/orchestrate core-dev crear login con UI y API
+# Aqui ves el plan en pantalla.
+# [Enter] ejecuta ya y muestra el reporte final.
+# [Esc]   te deja la ejecucion en 'planned'; ejecuta despues con /run resume <run-id>.
+
+/run messages <run-id>   # bitacora completa cuando quieras revisarla
+```

package/docs/TROUBLESHOOTING.md

@@ -0,0 +1,72 @@
+## Limitaciones actuales
+
+- La calidad de la ejecucion depende de que cada agente tenga perfil, modelo y credenciales validas.
+- La seleccion automatica ya existe, pero las politicas personalizadas editables todavia no estan persistidas con `/policy create`.
+- El fallback es auditable y controlado, no un sistema de retries infinitos.
+- Si varios proveedores producen respuestas incompatibles, el usuario debe revisar el consolidado antes de cerrar la ejecucion.
+
+## Cuando algo no avanza
+
+Sintomas comunes despues de `/orchestrate` o `/run resume`, y como salir de cada uno.
+
+### "El plan se quedo en `planned` y no pasa nada"
+
+Pulsaste `Esc` (o cerraste la vista) en lugar de `Enter`. La ejecucion existe pero no se ejecuto. Reanuda cuando quieras:
+
+```sh
+/run resume <run-id>
+```
+
+### "Aparecen equipos `blocked` que yo no pedi"
+
+Cuando creas un team con `/workspace setup` y solo das agente a algunos equipos (por ejemplo `frontend` y `backend`), los demas (`docs`, `planning`, etc.) se crean igual y quedan sin asignar. Al planear se reportan como `blocked` con el warning `No hay agente asignable para este equipo.`. Tienes dos salidas:
+
+- **Ignorarlos**: pulsas Enter, las tareas `ready` se ejecutan y las `blocked` se quedan asi. La ejecucion se reporta como `failed` o `completed` segun lo que avance.
+- **Asignar agente y reintentar**:
+  ```sh
+  /team equipo <team> docs <provider>/<agent>
+  /team equipo <team> planning <provider>/<agent>
+  /run retry <run-id>
+  ```
+
+### "Mi proveedor devolvio `usage_limit_reached` o `rate_limit`"
+
+Pasa cuando un proveedor alcanza el limite de tokens/segundo o de plan. La tarea afectada queda `failed`. Opciones:
+
+- Cambiar de perfil del mismo proveedor con `/profile use <proveedor> <otro-perfil>` y reintentar.
+- Reasignar la tarea a otro agente:
+  ```sh
+  /run reassign <task-id> <provider>/<agent>
+  /run resume <run-id>
+  ```
+- Pedir al sistema que busque un agente alterno:
+  ```sh
+  /run fallback <run-id> <task-id> score-with-fallback:resilience
+  /run resume <run-id>
+  ```
+
+### "Faltan credenciales o el modelo no esta configurado"
+
+Verifica el estado del perfil:
+
+```sh
+/status
+```
+
+Si falta token, modelo o base URL, vuelve a `/login` y `/model` para ese perfil. La tarea queda `blocked` hasta que el agente tenga todo lo que necesita.
+
+### "Quiero detener una ejecucion en marcha"
+
+```sh
+/run cancel <run-id>
+```
+
+### "Quiero ver que dijo cada orquestador local antes del reporte final"
+
+```sh
+/run messages <run-id>
+/run equipo <run-id> <equipo>
+/run task <task-id>
+```
+
+`/run messages` te lista en orden cronologico todos los `global-plan`, `squad-plan`, `task.completed`, `run-report` y eventos de policy de la ejecucion.