orca-multiagent-kit 1.5.0 → 1.7.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/AI_INSTALL.md +4 -3
- package/CHANGELOG.md +70 -1
- package/GUIA.html +11 -9
- package/README.md +23 -23
- package/VERSION +1 -1
- package/bin/backup.js +44 -0
- package/bin/fetch.js +243 -0
- package/bin/hooks.js +187 -0
- package/bin/omk.js +134 -51
- package/bin/run/cleanup.js +402 -0
- package/bin/run/git.js +641 -0
- package/bin/run/glob.js +193 -0
- package/bin/run/ledger.js +243 -0
- package/bin/run/plan.js +328 -0
- package/bin/run/units.js +101 -0
- package/bin/run/util.js +116 -0
- package/bin/run.js +224 -0
- package/bin/setup.js +81 -8
- package/bin/sync.js +222 -0
- package/bin/team.js +353 -0
- package/bin/ui.js +8 -4
- package/bin/update.js +169 -0
- package/core/AGENTS.md +7 -7
- package/docs/EJECUTABLE.md +5 -4
- package/docs/MANUAL.md +16 -3
- package/docs/ORQUESTADOR.md +59 -1
- package/docs/PLUGIN-ORCA.md +131 -24
- package/hooks/orca-gate.cjs +402 -0
- package/install.sh +26 -13
- package/orca-plugin/README.md +7 -1
- package/orca-plugin/assets/logos/README.md +10 -0
- package/orca-plugin/assets/logos/agent.png +0 -0
- package/orca-plugin/assets/logos/aider.png +0 -0
- package/orca-plugin/assets/logos/amp.png +0 -0
- package/orca-plugin/assets/logos/antigravity.png +0 -0
- package/orca-plugin/assets/logos/claude.png +0 -0
- package/orca-plugin/assets/logos/cline.png +0 -0
- package/orca-plugin/assets/logos/codex.png +0 -0
- package/orca-plugin/assets/logos/copilot.png +0 -0
- package/orca-plugin/assets/logos/cursor.png +0 -0
- package/orca-plugin/assets/logos/devin.png +0 -0
- package/orca-plugin/assets/logos/droid.png +0 -0
- package/orca-plugin/assets/logos/gemini.png +0 -0
- package/orca-plugin/assets/logos/goose.png +0 -0
- package/orca-plugin/assets/logos/grok.png +0 -0
- package/orca-plugin/assets/logos/kimi.png +0 -0
- package/orca-plugin/assets/logos/kiro.png +0 -0
- package/orca-plugin/assets/logos/opencode.png +0 -0
- package/orca-plugin/assets/logos/qwen-code.png +0 -0
- package/orca-plugin/orca-plugin.json +25 -7
- package/orca-plugin/src/icons.test.ts +14 -0
- package/orca-plugin/src/icons.ts +30 -0
- package/orca-plugin/src/kit.test.ts +491 -22
- package/orca-plugin/src/kit.ts +687 -37
- package/orca-plugin/src/models.test.ts +28 -0
- package/orca-plugin/src/models.ts +29 -0
- package/orca-plugin/src/node.d.ts +40 -0
- package/orca-plugin/src/panel-state.ts +36 -0
- package/orca-plugin/src/panel.check.ts +71 -0
- package/orca-plugin/src/panel.test.tsx +296 -33
- package/orca-plugin/src/panel.tsx +501 -81
- package/orca-plugin/src/plan-card.test.ts +99 -0
- package/orca-plugin/src/plan-card.ts +107 -0
- package/orca-plugin/src/protocol.ts +205 -5
- package/orca-plugin/src/tabs/autonomy.tsx +72 -0
- package/orca-plugin/src/tabs/history.test.tsx +79 -0
- package/orca-plugin/src/tabs/history.tsx +119 -0
- package/orca-plugin/src/tabs/notices.test.tsx +184 -0
- package/orca-plugin/src/tabs/notices.tsx +274 -0
- package/orca-plugin/src/tabs/worktrees.test.tsx +131 -0
- package/orca-plugin/src/tabs/worktrees.tsx +138 -0
- package/orca-plugin/src/ui/action-card.tsx +112 -0
- package/orca-plugin/src/ui/agent-icon.tsx +13 -0
- package/orca-plugin/src/worker/actions.test.ts +288 -0
- package/orca-plugin/src/worker/actions.ts +292 -0
- package/orca-plugin/src/worker/context.test.ts +32 -0
- package/orca-plugin/src/worker/context.ts +95 -0
- package/orca-plugin/src/worker/history.test.ts +149 -0
- package/orca-plugin/src/worker/history.ts +181 -0
- package/orca-plugin/src/worker/notices.test.ts +356 -0
- package/orca-plugin/src/worker/notices.ts +288 -0
- package/orca-plugin/src/worker/system.test.ts +58 -0
- package/orca-plugin/src/worker/system.ts +122 -0
- package/orca-plugin/src/worker/worktrees.test.ts +177 -0
- package/orca-plugin/src/worker/worktrees.ts +188 -0
- package/orca-plugin/src/worker.test.ts +285 -24
- package/orca-plugin/src/worker.ts +344 -64
- package/output-styles/csr-minimal.md +1 -0
- package/package.json +3 -3
- package/rules/50-done-gate.md +1 -1
- package/rules/95-multi-agent.md +13 -3
- package/skills/kit-init/SKILL.md +16 -4
- package/skills/orca/SKILL.md +28 -5
- package/skills/orca/references/adapters/artifact.md +2 -0
- package/skills/orca/references/adapters/chat.md +2 -0
- package/skills/orca/references/adapters/native-plan.md +6 -0
- package/skills/orca/references/adapters/plan-file.md +2 -0
- package/skills/orca/references/engine-manual.md +7 -5
- package/skills/orca/references/engine-orca.md +1 -0
- package/skills/orca/references/engine-subagents.md +4 -4
- package/skills/orca/references/integrate.md +14 -2
- package/skills/orca/references/ledger.md +1 -1
- package/skills/orca/references/olimpo.md +2 -1
- package/skills/orca/references/plan-card.md +45 -0
- package/skills/orca/references/plan.md +2 -1
- package/skills/orca/references/units.md +1 -1
- package/skills/orca/references/worker-contract.md +2 -2
- package/templates/AGENTS.md +2 -2
- package/templates/CLAUDE.md +1 -1
- package/templates/claude-settings.json +25 -0
package/docs/MANUAL.md
CHANGED
|
@@ -54,8 +54,8 @@ orca-multiagent-kit/
|
|
|
54
54
|
├── core/AGENTS.md núcleo: precedencia, idioma, respuesta, stack, puerta de validez,
|
|
55
55
|
│ prohibiciones, multiagente, router
|
|
56
56
|
├── rules/ 00-router · 10-communication · 20-clean-code · 30-security ·
|
|
57
|
-
│ └── lang/ (17) 31-security-audit · 40-testing · 50-done-gate ·
|
|
58
|
-
│ 70-performance · 75-reliability · 80-supply-chain ·
|
|
57
|
+
│ └── lang/ (17) 31-security-audit · 32-ai-security · 40-testing · 50-done-gate ·
|
|
58
|
+
│ 60-git-workflow · 70-performance · 75-reliability · 80-supply-chain ·
|
|
59
59
|
│ 90-docs-comments · 95-multi-agent
|
|
60
60
|
├── skills/ kit-init · csr-stack · csr-gate · csr-audit
|
|
61
61
|
│ orca (entrada única) · speckit-orca-implement (hook)
|
|
@@ -69,7 +69,9 @@ orca-multiagent-kit/
|
|
|
69
69
|
|
|
70
70
|
## 4. Instalación (y migración desde CSR / MAW sueltos)
|
|
71
71
|
|
|
72
|
-
|
|
72
|
+
Lo normal es un solo comando, y los tres caminos acaban en `omk setup`: `npx orca-multiagent-kit setup` (Node ≥ 18; deja `omk` instalado con `npm install -g`), el ejecutable de la release (sin Node; se abre y ya) o `curl -fsSL https://raw.githubusercontent.com/FernandoBaqueroo/orca-multiagent-kit/main/scripts/get.sh | bash` (sin Node; baja ese ejecutable y comprueba su SHA-256). `omk setup` instala las reglas y las skills, deja `omk` en el PATH y, si usas Orca, instala su plugin y abre su panel. Después tienes `omk update` (lo actualiza todo), `omk init`, `omk verify`, `omk adopt`, `omk restore` y `omk team`. `omk install` hace solo la parte de `~/.agents`.
|
|
73
|
+
|
|
74
|
+
Sin Node y sin ejecutable para tu sistema, con el zip o un clon se instalan las reglas y las skills (no hay `omk` ni plugin de Orca):
|
|
73
75
|
|
|
74
76
|
```bash
|
|
75
77
|
cd ~/Documents/orca-multiagent-kit
|
|
@@ -100,6 +102,17 @@ Más opciones:
|
|
|
100
102
|
|
|
101
103
|
Reinstalar es idempotente: sirve también para actualizar después de editar el kit.
|
|
102
104
|
|
|
105
|
+
### Actualizar (`omk update`)
|
|
106
|
+
Un solo comando pone al día todo lo que el kit instala, en este orden:
|
|
107
|
+
|
|
108
|
+
1. **El kit**, según cómo lo instalaste. Con npm, si hay una versión posterior publicada, la instala y sigue con ella. Con el ejecutable, descarga el de la última release junto a sí mismo, comprueba que su SHA-256 es el del `.sha256` publicado y solo entonces se sustituye. Una copia suelta (un clon, el zip) no se toca: se actualiza como la obtuviste. `--offline` se salta este paso y reaplica la versión que ya tienes.
|
|
109
|
+
2. **`~/.agents`**: lo mismo que `omk install`.
|
|
110
|
+
3. **El proyecto de la carpeta actual**, si está preparado con el kit (tiene `ORCHESTRATION.md` o el bloque del kit en `AGENTS.md`): lo mismo que `omk init` y, además, añade a `ORCHESTRATION.md` las secciones y los campos que la plantilla tiene y tu fichero no. Solo añade: lo que escribiste no se cambia, no se mueve y no se borra, y cada campo nuevo entra junto a su vecino con el valor de la plantilla, para que lo revises (o se lo pidas al agente con «inicializa el proyecto»). La versión anterior queda en `~/.agents/backups/` (`omk restore <fecha>`). Al final del fichero queda un sello (`<!-- omk:plantilla … -->`) con los apartados de la plantilla que ya se le han ofrecido: lo que borres a propósito no vuelve, y en adelante solo entra lo que la plantilla estrene. `STACK.md` recibe el mismo trato, salvo que la primera vez solo se sella, porque su plantilla pide borrar lo que no aplique. `orca.yaml` y `.worktreeinclude` no se tocan si existen. `--no-project` se salta este paso.
|
|
111
|
+
4. **Los hooks de reparto de Claude Code**, si usas Claude Code: en `~/.claude/settings.json` y en el `.claude/settings.json` del proyecto quedan dos hooks del kit (`UserPromptSubmit` y `PostToolUse` sobre `ExitPlanMode`) que recuerdan al agente que un trabajo con 2 o más entregables pasa por la skill `orca` antes de editar. Es lo que hace que la orquestación se dispare con un prompt o un plan, y no solo con spec-kit. Se fusionan sin tocar tus otros hooks ni ajustes, con copia; un `settings.json` que no sea JSON válido no se toca. `--no-hooks` u `OMK_NO_HOOKS=1` los omiten. En la configuración global va además la **puerta obligatoria** (`~/.agents/hooks/orca-gate.cjs`): tras cargar la skill `orca`, Claude Code no edita el proyecto hasta que el veredicto `ORCA: …` esté registrado y, si reparte, hasta que respondas al plan de rondas. `omk gate off` la apaga sin tocar los recordatorios, `omk gate on` la vuelve a encender y `omk gate status` dice cómo está. Detalle en [`ORQUESTADOR.md`](ORQUESTADOR.md) §9. Una vez repartido, lo mecánico del run (estado, rondas, worktrees, alcance, merge y limpieza) lo hace `omk run` en vez del agente de memoria ([`ORQUESTADOR.md`](ORQUESTADOR.md) §10; `omk run help`).
|
|
112
|
+
5. **El plugin de Orca**, si está instalado y Orca está abierto: lo deja en la versión del kit. Si la versión nueva necesita tu aprobación, la pide como `omk plugin install` (`--yes` la da de antemano; sin respuesta en 10 minutos cuenta como «no»). No abre Orca ni instala un plugin que no tenías: eso es `omk setup`. `--no-plugin` se salta este paso.
|
|
113
|
+
|
|
114
|
+
`--dry-run` enseña lo que haría sin escribir nada. Desde Orca es el botón *Actualizar kit* del panel, que enseña la salida y te deja aprobar el plugin sin ir al terminal ([`PLUGIN-ORCA.md`](PLUGIN-ORCA.md#acción-en-curso)).
|
|
115
|
+
|
|
103
116
|
### Después de instalar
|
|
104
117
|
- **Reinicia** Claude Code y Antigravity (y Codex o Copilot si los usas).
|
|
105
118
|
|
package/docs/ORQUESTADOR.md
CHANGED
|
@@ -59,7 +59,7 @@ Comprobado contra `orca skills get orchestration` y el `--help` de cada subcoman
|
|
|
59
59
|
**Antes.** Cuatro condiciones cualitativas (≥2 unidades, `write` disjuntos, ≥15 min, verificables).
|
|
60
60
|
|
|
61
61
|
**Ahora** (`rules/95-multi-agent.md`), además:
|
|
62
|
-
- **Cuenta rápida**: ahorro por ronda (`Σ t − max t`) contra un coste de coordinación de
|
|
62
|
+
- **Cuenta rápida**: ahorro por ronda (`Σ t − max t`) contra un coste de coordinación de 5 min por unidad y 5 min por ronda (eran 10 y 10: con ellos dos unidades medianas nunca compensaban), con penalización por cada fichero `shared` que obligue a serializar. Ante un empate, se reparte.
|
|
63
63
|
- **Presupuesto por talla** (S ≤15 min, M 20–60 min, L dividir) y campo opcional `budget` en la unidad. «Atascado» se define: sin progreso durante el doble del presupuesto.
|
|
64
64
|
- **Reintentos**: como mucho uno automático por unidad, mismo agente si falló el entorno y otro proveedor si falló el razonamiento; después `BLOCKED`.
|
|
65
65
|
- **Ficheros generados** (clientes de API, tipos de BD, lockfiles): no van en el `write` de ninguna unidad; los regenera el coordinador tras integrar.
|
|
@@ -103,6 +103,64 @@ Nueva sección en `rules/95-multi-agent.md` (aplica `30-security.md` §C12 a la
|
|
|
103
103
|
- `setup.md` comprueba que Orca responde y que la orquestación está activada, y propone `orca skills install --skill orca-cli --skill orchestration` si faltan las skills.
|
|
104
104
|
- Nuevo test en `tests/test_speckit.sh` (se ejecuta siempre, sin el CLI `specify`): el comando de la extensión y la skill `speckit-orca-implement` deben tener el mismo cuerpo. Antes podían divergir sin que nada lo detectara.
|
|
105
105
|
|
|
106
|
+
## 9. Puerta de reparto: la orquestación se dispara en todas las entradas
|
|
107
|
+
|
|
108
|
+
**Antes.** Solo spec-kit tenía un disparador que no dependía del criterio del agente: el hook `before_implement` carga la skill `orca` siempre, y la skill decide con `tasks.md` delante. En el resto de entradas (prompt de chat, plan nativo de Claude Code o Antigravity, plan en fichero, artefacto) el núcleo pedía usar la skill «por iniciativa propia» cuando la tarea tuviera «≥2 partes independientes de >15 min»: el agente tenía que estimar el resultado de la skill antes de cargarla, sin datos, y casi siempre concluía en silencio que no compensaba. Los adaptadores de plan nativo y de artefacto existían, pero nada los llamaba en el momento de «implementa el plan».
|
|
109
|
+
|
|
110
|
+
**Ahora.**
|
|
111
|
+
- **Regla comprobable** (`core/AGENTS.md` §6): antes de la primera edición de un trabajo con ≥2 entregables separables, se carga la skill y su veredicto queda escrito en el chat en una línea `ORCA: …`: con el plan de rondas y antes de editar si reparte; como tarde al empezar la respuesta final si es secuencial. El umbral de tiempo sale del disparador y se queda en la skill, que es quien tiene las unidades delante. Un solo entregable no pasa por la puerta ni lleva línea.
|
|
112
|
+
- **El plan lleva su reparto**: todo plan que escribe el agente (modo plan, `implementation_plan.md`, `planes/*.md`, artefacto) termina con una sección `Reparto` con el veredicto. Lo ve quien aprueba el plan y sobrevive a un cambio de contexto o de agente. Es el mecanismo de Antigravity y Codex, donde el kit no instala hooks.
|
|
113
|
+
- **Hooks de Claude Code** (`templates/claude-settings.json`, comprobados contra la referencia de hooks de Claude Code y con una sesión real):
|
|
114
|
+
| Evento | Qué hace |
|
|
115
|
+
|---|---|
|
|
116
|
+
| `UserPromptSubmit` | Su salida estándar se añade al contexto junto a cada mensaje: recuerda la puerta de reparto y sus excepciones |
|
|
117
|
+
| `PostToolUse` con `matcher: "ExitPlanMode"` | Devuelve `hookSpecificOutput.additionalContext`, que llega junto al resultado de aprobar el plan: antes de la primera edición, la skill `orca` con el adaptador de plan nativo |
|
|
118
|
+
Son un `echo` de texto fijo en ASCII: funcionan igual en bash y en PowerShell, sin dependencias, y también para quien clone el proyecto sin tener el kit.
|
|
119
|
+
- `kit-init` crea `.claude/settings.json` desde la plantilla o le añade esos dos hooks sin tocar lo demás.
|
|
120
|
+
- La description de la skill `orca` nombra las entradas («implementa el plan», plan aprobado, plan en fichero, artefacto), y cada adaptador dice cuándo se usa.
|
|
121
|
+
|
|
122
|
+
- **Puerta obligatoria en Claude Code** (`hooks/orca-gate.cjs`, en la configuración global; `omk gate on|off|status`). Recordar no bastaba: la línea `ORCA: secuencial` visible solo salía en 4 de 16 ensayos, y un reparto podía empezar sin esperar el «sí». El hook lo impone:
|
|
123
|
+
| Evento | Qué hace |
|
|
124
|
+
|---|---|
|
|
125
|
+
| `UserPromptSubmit` | Apunta cuándo escribe la persona (las notificaciones de tareas en segundo plano no cuentan) |
|
|
126
|
+
| `PostToolUse` sobre `Skill` | Apunta cuándo se carga la skill `orca` |
|
|
127
|
+
| `PreToolUse` sobre `Edit`, `Write`, `MultiEdit`, `NotebookEdit`, `Bash`, `PowerShell`, `Agent` | Apunta el veredicto cuando el agente lo registra con `echo "ORCA: …"`. Tras cargar la skill, deniega editar el proyecto (fuera de `.work/`) y escribir desde la shell hasta que haya veredicto; si reparte, deniega además lanzar subagentes hasta que la persona responda al plan |
|
|
128
|
+
- **Por qué `echo`**: Claude Code escribe el transcript con retraso (a veces al acabar el turno), así que el hook no ve a tiempo la línea del chat. La orden sí llega en su propia entrada. El agente escribe la línea en el chat y la registra con `echo`; el motivo de cada denegación le dice cómo.
|
|
129
|
+
- **Qué no toca**: una sesión sin la skill cargada; un encargo anterior (si la persona ha escrito después de cargar la skill sin veredicto); un worker (primer mensaje `UNIT:`); autonomía `auto`; repetir un plan ya confirmado. Un plan distinto tras «cambia X» vuelve a pedir confirmación.
|
|
130
|
+
- **Nunca bloquea por un fallo suyo**: sin estado o con una carga de la skill anterior a instalarlo (sesión ya abierta), sin transcript ni registro, o ante un error interno, deja pasar y lo avisa (`~/.agents/state/gate/errors.log`). Cuesta lo que tarda Node en arrancar (unos 170 ms en Windows) en cada edición u orden de shell.
|
|
131
|
+
- Va solo en la configuración global (`~/.claude/settings.json`), no en la del proyecto: así un repositorio clonado sin el kit no ejecuta un script que no tiene. Con el ejecutable autónomo y sin Node en el PATH, la orden es el propio `omk gate hook`.
|
|
132
|
+
|
|
133
|
+
**Lo medido** (Claude Code en modo no interactivo, `claude -p`, sobre un repo de juguete; pocos ensayos, sirven de orientación y no de garantía):
|
|
134
|
+
| Qué | Sin la puerta | Con la puerta |
|
|
135
|
+
|---|---|---|
|
|
136
|
+
| La skill `orca` se carga antes de la primera edición con un encargo de 2 o más entregables | 19 de 19 | 6 de 6 |
|
|
137
|
+
| El veredicto queda a la vista (chat o `echo`) antes de la primera edición | 4 de 16 | 6 de 6, sin una sola denegación de más |
|
|
138
|
+
| Un reparto espera al «sí» antes de editar o lanzar workers | 1 de 2 | 2 de 2; tras el «sí», la primera edición pasa |
|
|
139
|
+
| Un cambio de un solo fichero no pasa por la puerta | 3 de 3 | 1 de 1 |
|
|
140
|
+
| El plan del modo plan termina en `Reparto`, y el hook de `ExitPlanMode` se ejecuta al aprobarlo | 2 de 2 y 1 de 1 | — |
|
|
141
|
+
| Antigravity (`agy --print`): primera lectura la skill, respuesta que empieza por `ORCA:` | 2 de 2 | (sin hook) |
|
|
142
|
+
|
|
143
|
+
**Límites.** En Antigravity y Codex no hay puerta obligatoria: manda la regla. Una skill cargada leyendo su `SKILL.md` (sin la herramienta Skill) solo se detecta cuando llega al transcript. Con `claude -p --no-session-persistence` no hay transcript y la puerta solo usa lo que apuntan sus hooks. Un hook de contexto no ejecuta la skill: se la recuerda al agente en el momento justo, igual que el hook de spec-kit es una instrucción que `/speckit.implement` lee. En Antigravity y Codex existen hooks propios, pero el kit no los instala todavía; ahí manda la regla del núcleo y la sección `Reparto` del plan.
|
|
144
|
+
|
|
145
|
+
## 10. Motor determinista: `omk run`
|
|
146
|
+
|
|
147
|
+
La puerta asegura que el reparto se decide; lo que pasa después (estado, rondas, worktrees, alcance, merge y limpieza) dependía de que el coordinador siguiera las referencias de memoria. Ahora lo hace código, en `bin/run.js` y `bin/run/`, sin dependencias, y la skill (`SKILL.md` §0, tabla «Motor `omk run`») dice qué orden toca en cada paso. Sin `omk` en el `PATH`, los pasos a mano siguen en cada referencia.
|
|
148
|
+
|
|
149
|
+
| Orden | Qué hace | Se niega (salida 1) o pregunta (salida 3) si… |
|
|
150
|
+
|---|---|---|
|
|
151
|
+
| `omk run new <run>` | Crea `.work/runs/<run>/run.md` con las unidades de `units.md` en `pending` | El run ya existe o `units.md` tiene errores de formato |
|
|
152
|
+
| `omk run plan <run>` | Valida `units.md` y calcula las rondas (dependencias, solapes de `write` y `shared` de `ORCHESTRATION.md` §2) y la cuenta «¿compensa?» de `95-multi-agent.md`, en texto o `--json` | Glob ancho, ruta absoluta o con `..`, ciclo, dependencia que no existe, falta `write`, `acceptance` o `verify`, `write` que pisa un `shared` sin declararlo |
|
|
153
|
+
| `omk run start <run> --parent <padre>` | Base fresca (tabla de `SKILL.md` §4) y rama de integración con `--no-track` | Fetch que falla (1); la local va por delante del remoto (3, `--from local\|remote`); árbol sucio; integración = padre o rama por defecto |
|
|
154
|
+
| `omk run worktree <run> <U>` | Rama `wt/<run>/<u>` y worktree en `../<repo>.wt/<run>/<u>` desde la cabeza de la integración; copia los `.env` de desarrollo de `.worktreeinclude` | La rama ya existe en otro sitio; la carpeta no está vacía. Omite (sin fallar) lo no ignorado, enlaces, `..`, rutas absolutas y lo que parece de producción |
|
|
155
|
+
| `omk run check <run> <U>` | Lo commiteado desde el merge-base con la integración y lo que quede sin commitear en su worktree, contra `write` ∪ `shared` | Algo fuera de alcance (también un fichero ya integrado que la rama revierte), prohibido a un worker sin distinguir mayúsculas (`tasks.md`, `planes/**`, `ORCHESTRATION.md`, `STACK.md`, lockfiles, `.work/`), sin commitear, o un worktree anotado que no existe |
|
|
156
|
+
| `omk run merge <run> <U>` | Ensayo con `merge-tree` y `merge --no-ff`; `run.md` a `merged` con su sha. Nunca push | Conflictos, fuera de la integración, árbol sucio, merge o rebase a medias, integración = rama por defecto, unidad sin `accepted`, `check` que falla, rama sin commits nuevos, fichero que pisaría uno ignorado o sin versionar del coordinador, git < 2.38 |
|
|
157
|
+
| `omk run cleanup <run> [--apply]` | Inventario desde git; con `--apply`, `git worktree remove` (sin `--force`) y `git branch -d` de lo integrado y limpio, y `cleanup: done\|pending` | Nunca toca la integración, la padre, la actual, la por defecto, ramas con upstream, el checkout del coordinador, rutas que git no lista ni lo de una unidad que no esté `merged`, `discarded` o `reverted` |
|
|
158
|
+
| `omk run set\|meta\|log\|status\|list` | Escriben y leen `run.md` respetando las transiciones de estado de `ledger.md` | Transición inválida (sin `--force`), «\|» o saltos de línea en un valor, `run.md` mal formado |
|
|
159
|
+
|
|
160
|
+
**Medido en su propio run** (`20261113-omk-run`, 6 unidades en 3 rondas, subagentes de Claude y Antigravity): U2 se integró con `omk run check` → `merge --dry-run` → `merge` sin git a mano, y `omk run plan` sobre el `units.md` del run dio las mismas rondas que el plan confirmado. El run destapó que el aislamiento por worktree de los subagentes de Claude Code no sirve para un run (nace de la rama por defecto y se borra si el subagente termina sin cambios): `engine-subagents.md` manda ahora crear el worktree con `omk run worktree` y lanzar el subagente sin aislamiento, con su ruta en la línea `WORKTREE:` del despacho. La revisión cruzada de `git.js` y `cleanup.js` (Casandra, Antigravity con gemini-4-carbon-high) encontró 17 hallazgos, 4 críticos (un `check` medido contra la base y no contra la integración, un `merge` que daba por integrada una rama sin commits, un `cleanup` que podía borrar la rama padre o el worktree de otra unidad nombrados en `run.md`); se corrigieron en un rework, cada uno con su prueba, salvo un caso aplazado: en un clon `--single-branch` cuyo refspec no trae la rama padre, `start` no detecta que `origin/<padre>` está desactualizada. Además, git 2.52 acepta `merge --no-overwrite-ignore` pero no lo cumple con la estrategia `ort`: `merge` lleva su propia guarda.
|
|
161
|
+
|
|
162
|
+
Pruebas: `tests/test_run.sh` (modelo y CLI), `test_run_plan.sh`, `test_run_git.sh` (con un remoto bare, casos hostiles de ramas, rutas, enlaces y `.env.production`) y `test_run_cleanup.sh`, en repositorios desechables.
|
|
163
|
+
|
|
106
164
|
## Compatibilidad
|
|
107
165
|
|
|
108
166
|
- Sin cambios en `~/.agents`, en el instalador ni en el núcleo. No hace falta migrar nada: basta con reinstalar (`omk update`).
|
package/docs/PLUGIN-ORCA.md
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
# Plugin de Orca
|
|
2
2
|
|
|
3
|
-
El kit funciona en [Orca](https://www.onorca.dev) sin plugin: las skills viven en `~/.agents/skills` (el mismo sitio donde Orca instala las suyas) y la skill `orca` usa `orca orchestration` como motor. El plugin `orca-plugin/` añade lo que solo puede hacer la propia app: comandos en la paleta, un panel lateral con acciones y ajustes, un cambio en los despachos de orquestación y un indicador en la barra de estado.
|
|
3
|
+
El kit funciona en [Orca](https://www.onorca.dev) sin plugin: las skills viven en `~/.agents/skills` (el mismo sitio donde Orca instala las suyas) y la skill `orca` usa `orca orchestration` como motor. El plugin `orca-plugin/` añade lo que solo puede hacer la propia app: comandos en la paleta, un panel lateral con los agentes, el equipo de roles, las acciones y los ajustes, un cambio en los despachos de orquestación, avisos y un indicador en la barra de estado.
|
|
4
4
|
|
|
5
5
|
Requisitos: Orca ≥ 1.4.248 (hooks y barra de estado) con los plugins activados (*Settings → Plugins → Turn on plugins*). Para los comandos, el kit instalado (`omk` en el `PATH`).
|
|
6
6
|
|
|
@@ -8,15 +8,103 @@ Requisitos: Orca ≥ 1.4.248 (hooks y barra de estado) con los plugins activados
|
|
|
8
8
|
|
|
9
9
|
| Pieza | Qué ves | Cómo funciona |
|
|
10
10
|
|---|---|---|
|
|
11
|
-
| **Orca Multiagent Kit: verificar instalación** | Un terminal nuevo en el workspace activo que ejecuta `omk verify
|
|
12
|
-
| **Orca Multiagent Kit: actualizar kit** | Lo mismo con `omk update` | `terminal.create` con el literal `omk update` |
|
|
13
|
-
| **Orca Multiagent Kit: inicializar proyecto** | Un agente nuevo en el workspace activo con el prompt «inicializa el proyecto» (skill `kit-init`) | `agent.launch`; el agente sale del ajuste *Agente para inicializar* (por defecto `claude`) |
|
|
14
|
-
| **Orca Multiagent Kit: estado de los agentes** | Una línea por agente activo:
|
|
15
|
-
| **Panel *Multiagent Kit
|
|
11
|
+
| **Orca Multiagent Kit: verificar instalación** | Un terminal nuevo en el workspace activo que ejecuta `omk verify`, y su estado y su salida en el panel | `terminal.create` con el literal `omk verify --exit-marker`. Ver [Acción en curso](#acción-en-curso) |
|
|
12
|
+
| **Orca Multiagent Kit: actualizar kit** | Lo mismo con `omk update`: pone al día el paquete, `~/.agents`, el proyecto activo (también los apartados nuevos de `ORCHESTRATION.md`) y este plugin | `terminal.create` con el literal `omk update --exit-marker`. Qué actualiza: [`MANUAL.md`](MANUAL.md#actualizar-omk-update) |
|
|
13
|
+
| **Orca Multiagent Kit: inicializar proyecto** | Un agente nuevo en el workspace activo con el prompt «inicializa el proyecto» (skill `kit-init`), seguido en el panel | `agent.launch`; el agente sale del ajuste *Agente para inicializar* (por defecto `claude`) |
|
|
14
|
+
| **Orca Multiagent Kit: estado de los agentes** | Una línea por agente activo: nombre, estado, agente y workspace | Lo que ha ido contando la barra de estado |
|
|
15
|
+
| **Panel *Multiagent Kit* · Agentes** (barra lateral derecha, icono de robot) | Los agentes activos con nombre, agrupados por run del kit o por workspace, los bloqueados primero (y abiertos). Cada uno se despliega en su ficha: estado y desde cuándo, agente, unidad, rol y nivel, run, título en Orca, workspace, rama, carpeta, si corre en un terminal o en un chat de Orca y cómo acabó su último turno; y un botón para ir a su workspace | Ver [Nombres de los agentes](#nombres-de-los-agentes) |
|
|
16
|
+
| **Panel · Avisos** (la etiqueta dice cuántos hay) | Lo que espera tu respuesta: la **tarjeta del plan de rondas** del coordinador (cabecera, rondas, cada unidad con su rol, nivel, agente con su icono, modelo y recurso en colores, notas) con «Sí, lánzalo» y «Pedir cambio»; y cada agente bloqueado o esperando, con las últimas líneas de su terminal, una caja para responderle, «Ir a su workspace» y «Descartar» | Ver [Avisos y tarjeta del plan](#avisos-y-tarjeta-del-plan) |
|
|
17
|
+
| **Panel · Worktrees** | Los worktrees de la orquestación agrupados por run (los demás con agentes, en «Otros»), con su rama y unidad, sus agentes con icono, estado y modelo, «Abrir worktree» y, para un Claude Code que espera, «Cambiar modelo» (opus, sonnet, haiku) | El modelo sale de `--model` en la orden de arranque (hook `agent.launch.before`); el cambio escribe `/model <alias>` + Intro en su terminal |
|
|
18
|
+
| **Panel · Historial** | Despachos, bloqueos y finales de unidad, runs terminados, planes, respuestas, cambios de modelo, repartos y autonomía, lo más reciente primero, con filtro y «Vaciar historial» (dos pasos) | Las 200 últimas entradas, en el almacenamiento del plugin (`storage:own`, clave `history.v1`) |
|
|
19
|
+
| **Panel · Repartir** | Repartir una tarea entre agentes: eliges de dónde sale el trabajo (lo que escribes, un plan del repo o spec-kit), el coordinador y, si quieres, otra autonomía solo para ese run | Ver [Repartir una tarea](#repartir-una-tarea) |
|
|
20
|
+
| **Panel · Equipo** | La autonomía del proyecto (manual, semi, auto) y quién hace cada rol: equipo predefinido o personalizado, proveedores activos (casillas), revisión cruzada, un proveedor por rol de Olimpo y roles propios del proyecto | «Guardar en el proyecto» abre un terminal con `omk team set --autonomy <nivel>`; «Aplicar al proyecto», con `omk team set --data …`; «Ver el del proyecto», con `omk team`. Ver [Equipo](#equipo) |
|
|
21
|
+
| **Panel · Kit** | Botones de verificar, inicializar y actualizar y los cinco ajustes del plugin (los agentes se eligen de una lista, no se escriben) | El panel pide las acciones al worker (`kit.run`, solo esas tres) y lee y escribe los ajustes con `settings` |
|
|
22
|
+
| **Panel · acción en curso** (encima de las pestañas) | Lo último que has lanzado desde el panel o la paleta: en curso, esperando tu respuesta, terminado o fallido, con las últimas líneas de su terminal y, si `omk` pregunta, «Aprobar» y «Rechazar» | Ver [Acción en curso](#acción-en-curso) |
|
|
23
|
+
| **Avisos** | «U2 · Ariadna — Pagos: bloqueado» al bloquearse un agente; «RUN …: unidades terminadas» cuando acaban todas las unidades lanzadas de un run | Transiciones de `agent.status.changed`; se apagan con *Avisos de agentes* |
|
|
24
|
+
| **Repartir siempre** | Todo agente que Orca arranca con una tarea (al crear un worktree con tarea, en una pestaña nueva, desde una issue) pasa primero por la skill `orca`: decide si compensa repartir y, si compensa, reparte. Sin spec-kit | Hook `agent.prompt.before` con `inputKind: "launch"`. Ver [Repartir siempre](#repartir-siempre) |
|
|
16
25
|
| **Contrato del worker** | Cada despacho de la skill `orca` lleva al final una línea que remite a `~/.agents/skills/orca/references/worker-contract.md` | Hook `agent.prompt.before` |
|
|
17
|
-
| **Barra de estado** `MAW · 2 trabajando · 1 bloqueado` | Agentes trabajando, bloqueados o esperando en todos los workspaces. Ámbar si hay alguno bloqueado. Al pulsarlo, el estado de los agentes | Evento `agent.status.changed` y `agents.list` al arrancar |
|
|
26
|
+
| **Barra de estado** `MAW · 2 trabajando · 1 bloqueado` | Agentes trabajando, bloqueados o esperando en todos los workspaces. Ámbar si hay alguno bloqueado. El tooltip nombra hasta seis. Al pulsarlo, el estado de los agentes | Evento `agent.status.changed` y `agents.list` al arrancar |
|
|
18
27
|
|
|
19
|
-
Si `omk` no está en el `PATH`, el terminal muestra el error del shell
|
|
28
|
+
Si `omk` no está en el `PATH`, el terminal muestra el error del shell, la acción queda como fallida en el panel y llega una notificación con cómo instalarlo (`npm install -g orca-multiagent-kit` o el ejecutable de la release, que se deja a sí mismo en el `PATH`). Si el plugin no identifica el workspace activo (ninguno enfocado, o dos con el mismo nombre y rama), lo dice y no ejecuta nada: es preferible no lanzar nada a lanzarlo en otro workspace. Desde el panel, cualquier fallo al lanzar sale como error («No se pudo»), no como respuesta.
|
|
29
|
+
|
|
30
|
+
### Acción en curso
|
|
31
|
+
|
|
32
|
+
La API de plugins abre los terminales en segundo plano y no tiene forma de traerlos al frente, así que el plugin trae el terminal al panel: encima de las pestañas hay una tarjeta con la última acción lanzada (desde el panel o desde la paleta).
|
|
33
|
+
|
|
34
|
+
- **Comandos `omk`** (verificar, actualizar, y los `omk team` de *Equipo*): el worker lee ese terminal cada segundo (`terminal.read`, las 400 últimas líneas) y enseña las 80 últimas, sin códigos de escape ni caracteres de control; el panel deja a la vista el final y pliega el resto en «Salida completa». Para saber cuándo y cómo ha terminado, lanza el comando con `--exit-marker`: con esa opción `omk` escribe al salir `[omk:fin] <comando> salida=<código>`. Código 0, «terminado»; otro, «falló». Pasados 20 minutos deja de seguirlo y lo dice.
|
|
35
|
+
- **Si `omk` pregunta** (`omk update` cuando el plugin nuevo necesita tu aprobación: enseña lo que concede y pregunta `¿Apruebas este acceso? [s/N]`), la tarjeta pasa a «espera tu respuesta», llega una notificación y salen «Aprobar» y «Rechazar». Escriben `s` o `n` e Intro en **ese** terminal, y solo si `omk` sigue preguntando en ese momento (el worker lo vuelve a leer antes de escribir). También puedes contestar en el terminal. Sin respuesta en 10 minutos, `omk` lo da por rechazado.
|
|
36
|
+
- **Agentes** (inicializar y *Repartir*): la tarjeta sigue el estado que cuenta Orca (trabajando; pide permiso o espera instrucciones, y entonces te manda a *Avisos*; terminado) y las 24 últimas líneas de su terminal.
|
|
37
|
+
- **Reinicio del plugin**: *Actualizar kit* cambia el propio plugin y Orca reinicia su worker a mitad del comando. Lo que se sigue está guardado (`storage:own`, clave `action.v1`: título, terminal y hora de inicio), y el worker nuevo retoma el mismo terminal.
|
|
38
|
+
- «Dejar de seguir» (o «Quitar», si ya acabó) quita la tarjeta; el terminal sigue como esté. Cada comando `omk` que termina queda en *Historial*.
|
|
39
|
+
- **`omk` anterior al plugin**: no conoce `--exit-marker` y lo rechaza. La tarjeta lo explica y dice cómo actualizarlo (`npm install -g orca-multiagent-kit@latest`).
|
|
40
|
+
|
|
41
|
+
### Nombres de los agentes
|
|
42
|
+
|
|
43
|
+
Orca no siempre manda título en `agent.status.changed`. El plugin junta lo que sabe de cada terminal, por este orden:
|
|
44
|
+
|
|
45
|
+
1. **Despacho del kit** (hook `agent.prompt.before`): la cabecera `UNIT: U2 — <título> RUN: <run>` y la línea `ROL: Ariadna · …` dan `U2 · Ariadna — <título>` y lo agrupan bajo `RUN <run>`.
|
|
46
|
+
2. **Título de Orca**, si llega; un cambio de estado sin título conserva el anterior.
|
|
47
|
+
3. **Qué agente es** (`claude`, `codex`…), de `agents.list` al arrancar, del hook `agent.launch.before` o, en los chats de agente de Orca (no tienen terminal), del nombre de su panel (`structured-agent-session-<agente>_…`).
|
|
48
|
+
|
|
49
|
+
El workspace sale de `workspace.list`. Los eventos de agentes lo identifican a veces como `<repo>::<ruta>` y la lista como `identity:…`; el plugin los cruza por la ruta. Títulos y despachos los escribe un agente: se quitan los caracteres de control y de formato y se acortan (80 caracteres) antes de enseñarlos. Lo aprendido de cada terminal vive en memoria (los 200 más recientes); si el plugin se reinicia, los agentes en curso se nombran con lo que vuelva a contar Orca.
|
|
50
|
+
|
|
51
|
+
### Repartir siempre
|
|
52
|
+
|
|
53
|
+
Sin el plugin, la orquestación arranca con spec-kit (el hook `before_implement` de `/speckit.implement`), con la «puerta de reparto» del núcleo (`~/.agents/AGENTS.md` §6) y, en Claude Code, con los hooks que el kit pone en `settings.json` (`UserPromptSubmit` y `ExitPlanMode`). El plugin añade lo que esas vías no ven: el prompt con el que Orca arranca un agente. El ajuste *Repartir al lanzar un agente con tarea* (activado por defecto) lo vuelve automático: a cada prompt con el que Orca arranca un agente le añade al final
|
|
54
|
+
|
|
55
|
+
> [Orca Multiagent Kit] Antes de empezar, y antes de la primera edición, carga la skill orca (~/.agents/skills/orca/SKILL.md) y escribe en el chat su veredicto en una línea `ORCA: …`: si la tarea tiene 2 o más entregables separables, repártela entre agentes. La entrada es este prompt (adaptador de chat): no hace falta spec-kit. Si es un solo entregable, hazla tú directamente.
|
|
56
|
+
|
|
57
|
+
Así, crear un worktree con una tarea ya es orquestar: la skill decide en menos de un minuto si compensa (`95-multi-agent.md` §Cuándo paralelizar) y, si no, el agente la hace solo como siempre. No se toca:
|
|
58
|
+
|
|
59
|
+
- lo que escribe una persona en el chat o el terminal (Orca no pasa esos prompts por los hooks);
|
|
60
|
+
- los despachos a workers (`inputKind: "orchestration"`), que llevan el contrato del worker en su lugar;
|
|
61
|
+
- los prompts que ya van por la skill `orca` (*Repartir* del panel), los de `kit-init` y un despacho del kit.
|
|
62
|
+
|
|
63
|
+
Falla en abierto como el resto de hooks: si el plugin falla o tarda más de 2 s, el prompt sale sin cambios.
|
|
64
|
+
|
|
65
|
+
### Repartir una tarea
|
|
66
|
+
|
|
67
|
+
Es la forma de arrancar un run multiagente sin abrir un chat y escribir el prompt a mano. Lanza el coordinador elegido (`agent.launch`) en el workspace activo con un prompt que invoca la skill `orca` y le dice de dónde sale el trabajo:
|
|
68
|
+
|
|
69
|
+
| De dónde sale el trabajo | Qué recibe el coordinador | Campo de texto |
|
|
70
|
+
|---|---|---|
|
|
71
|
+
| Lo que escribo aquí | La tarea, con el adaptador de chat | Obligatorio (máx. 4000 caracteres) |
|
|
72
|
+
| Un plan del repo | «reparte el plan de `planes/*.md`», adaptador plan-file | Opcional: qué plan |
|
|
73
|
+
| Tareas de spec-kit | «reparte `specs/<feature>/tasks.md`», adaptador speckit | Opcional: qué feature |
|
|
74
|
+
|
|
75
|
+
Las dos primeras dicen expresamente que **no hace falta spec-kit**: la skill `orca` reparte igual desde un texto o un plan. Después, el coordinador hace lo de siempre: decide si compensa repartir, te enseña el plan de rondas para que lo confirmes, lanza un agente por unidad en su worktree con su rol del equipo, integra y te pide confirmar el merge. Los agentes aparecen en la pestaña *Agentes*.
|
|
76
|
+
|
|
77
|
+
### Equipo
|
|
78
|
+
|
|
79
|
+
La pestaña *Equipo* edita un borrador (se guarda en el panel) y lo escribe en `ORCHESTRATION.md` §1 del proyecto activo con `omk team set --data <equipo>`, que es lo que la skill `orca` lee al repartir. `<equipo>` es el equipo en JSON y base64url: al terminal solo llegan letras, números, `-` y `_`, aunque los roles propios lleven texto libre; `omk team` lo valida otra vez entero antes de escribir.
|
|
80
|
+
|
|
81
|
+
| En el panel | En `ORCHESTRATION.md` §1 |
|
|
82
|
+
|---|---|
|
|
83
|
+
| Proveedores activos (casillas; al menos uno) | `- Proveedores activos: claude, codex` (conserva el comentario) |
|
|
84
|
+
| Revisión cruzada | `- Revisión cruzada (…): unidades L y sensibles` · `todas` · `nunca` |
|
|
85
|
+
| Un proveedor por rol de Olimpo | Una fila `Rol Casandra · Casandra / codex · equipo (omk team)` en «Excepciones al reparto por roles». `references/olimpo.md` la lee como «todas las unidades de ese rol van con ese proveedor» |
|
|
86
|
+
| Roles propios (hasta 10): nombre, qué hace, nivel, revisión, guardarraíl y proveedor | Una fila `**Hermes** · Traducciones · bajo · Argos · … <!-- omk team -->` en «Roles propios del proyecto» y, si lleva proveedor, su fila `Rol Hermes` en las excepciones. Se quitan `\|`, `<`, `>` y saltos de línea del texto |
|
|
87
|
+
| Coordinador | No se escribe: es el agente que lanza *Repartir* |
|
|
88
|
+
|
|
89
|
+
Los agentes se eligen de una lista: los habituales del catálogo de Orca (Claude Code, Codex, Gemini CLI, Antigravity, Copilot, Cursor, OpenCode…). Un nombre de rol propio no puede repetir uno de Olimpo ni otro propio.
|
|
90
|
+
|
|
91
|
+
Equipos predefinidos: *Solo Claude* (sin roles fijados; la revisión cruzada la hace una sesión nueva), *Claude + Codex revisor* (todo con Claude salvo Casandra, con Codex) y *Codex + Claude revisor* (al revés). Elegir uno conserva los roles propios; cualquier cambio a mano lo deja en *Personalizado*. `omk team` solo reescribe las filas que escribió él (`equipo (omk team)` y `<!-- omk team -->`); las que escribiste tú se quedan. Desde un terminal:
|
|
92
|
+
|
|
93
|
+
```bash
|
|
94
|
+
omk team # el equipo del proyecto
|
|
95
|
+
omk team set --provider claude --provider codex --cross todas --role casandra=codex
|
|
96
|
+
omk team set --role casandra=auto # vuelve a decidirlo el coordinador
|
|
97
|
+
omk team set --autonomy auto # §0: manual, semi o auto
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
La tarjeta *Autonomía* de la misma pestaña cambia la línea `- Nivel:` de `ORCHESTRATION.md` §0 (`omk team set --autonomy manual|semi|auto`; el terminal solo recibe uno de esos tres literales). En *Repartir*, «Autonomía de este run» la cambia solo para el coordinador que lanzas: va en su prompt y no toca el fichero.
|
|
101
|
+
|
|
102
|
+
### Avisos y tarjeta del plan
|
|
103
|
+
|
|
104
|
+
- **Tarjeta del plan**: antes de pedir la confirmación 1, la skill `orca` escribe el plan en `.work/runs/<run>/plan.json` ([formato](../skills/orca/references/plan-card.md)). El plugin lo ve en el hook `agent.tool.after` (la herramienta `Write` de Claude Code, con su contenido), lo valida campo a campo (hasta 60 unidades, 10 notas y 200 caracteres por texto; lo que no encaja se descarta y queda en `orca plugin logs`) y lo pinta en *Avisos*, con una notificación. «Sí, lánzalo» escribe `sí` en el terminal del coordinador; «Pedir cambio», `cambia: <lo que pidas>`. Es lo mismo que escribirlo tú en su chat.
|
|
105
|
+
- **Coordinador en un chat de Orca**: ahí no llega el hook, así que cuando el coordinador se queda esperando el plugin busca `.work/runs/*/plan.json` en su workspace (solo ficheros de verdad, no enlaces; hasta 64 KB y 50 runs; solo los escritos después de arrancar el plugin). Como la API de plugins no escribe en chats, la respuesta va por el buzón del Run de Orca de la tarjeta (`orcaRun`): `orca orchestration send --from run:<orcaRun> --to run:<orcaRun> --subject "Respuesta desde el panel: …" --body <tu texto>`, y Orca la entrega al chat del coordinador. Sin `orcaRun`, se le responde en su chat.
|
|
106
|
+
- **Agentes que esperan**: un agente bloqueado (pide permiso) o esperando instrucciones sale con las 12 últimas líneas de su terminal, sin códigos de escape ni caracteres de control. La respuesta va a **su** terminal (el worker no acepta un terminal que venga del panel), en una sola línea de hasta 2000 caracteres, sin saltos ni caracteres de control, y con Intro.
|
|
107
|
+
- Un aviso desaparece al responderlo, al descartarlo o cuando el agente vuelve a trabajar; uno descartado no vuelve hasta que el agente cambie de estado.
|
|
20
108
|
|
|
21
109
|
### Por qué el contrato del worker
|
|
22
110
|
|
|
@@ -33,15 +121,23 @@ Es un plugin `trusted-worker`: Orca ejecuta `src/worker.ts` en un proceso Node a
|
|
|
33
121
|
|
|
34
122
|
| Capacidad | Para qué | Si no la concedes |
|
|
35
123
|
|---|---|---|
|
|
36
|
-
| `workspace:read` | Saber qué workspace está enfocado (`workspace.readContext` + `workspace.list`) y enterarse de los que se eliminan | Los comandos no saben dónde ejecutarse |
|
|
37
|
-
| `
|
|
38
|
-
| `terminal:
|
|
39
|
-
| `
|
|
40
|
-
| `agent:
|
|
41
|
-
| `
|
|
42
|
-
| `
|
|
124
|
+
| `workspace:read` | Saber qué workspace está enfocado y cómo se llama cada uno (`workspace.readContext` + `workspace.list`) y enterarse de los que se eliminan | Los comandos no saben dónde ejecutarse y los agentes salen sin workspace |
|
|
125
|
+
| `workspace:write` | Abrir el workspace de un agente al pulsarlo en el panel (`workspace.open`). El plugin no renombra workspaces ni ejecuta comandos de Orca | Pulsar un agente no hace nada |
|
|
126
|
+
| `terminal:send` | Abrir un terminal con `omk verify`, `omk update` u `omk team` (`terminal.create`); escribir tu respuesta de *Avisos* o `/model <alias>` en el terminal de un agente que sigue el plugin, y `s` o `n` en el terminal de la acción en curso cuando `omk` pregunta (`terminal.sendText`) | No hay comandos de verificar ni actualizar, no se aplican el equipo ni la autonomía, y no se puede responder ni cambiar el modelo desde el panel |
|
|
127
|
+
| `terminal:read` | Leer la salida del terminal de la acción en curso (el que abrió el plugin, o el del agente que lanzó) para enseñarla y saber si terminó, si `omk` no existe o si pregunta; y las últimas líneas del terminal de un agente que espera, para su aviso | La acción en curso no tiene salida ni estado, el fallo de `omk` ausente solo se ve en el terminal, y los avisos salen sin contexto |
|
|
128
|
+
| `agent:launch` | Lanzar el agente de «inicializar proyecto» y el coordinador de *Repartir* (`agent.launch`) | No hay comando de inicializar ni botón de repartir |
|
|
129
|
+
| `agent:read` | Contar y nombrar agentes para la barra, el panel y los avisos (`agents.list`, `agent.status.changed`) | La barra se queda en `MAW` |
|
|
130
|
+
| `notifications:show` | Avisos accionables (sin `omk`, sin workspace, fallos de Orca, agente bloqueado, run terminado) | Los avisos solo quedan en `orca plugin logs` |
|
|
131
|
+
| `settings:own` | Leer los cinco ajustes del plugin, y cambiarlos desde el panel | Se usan los valores por defecto y el panel no puede guardarlos |
|
|
132
|
+
| `storage:own` | Guardar el historial (las 200 últimas entradas, clave `history.v1`) y qué acción se está siguiendo (clave `action.v1`) | El historial solo dura hasta que se reinicia el plugin, y *Actualizar kit* pierde el seguimiento cuando cambia el plugin |
|
|
133
|
+
|
|
134
|
+
Además observa dos hooks sin cambiar ni denegar nada: `agent.launch.before` (qué agente se lanza, en qué terminal y con qué `--model`) y `agent.tool.after` (solo le interesa un `Write` de `.work/runs/<run>/plan.json`; el resto de llamadas se descartan en el acto y no se guardan).
|
|
135
|
+
|
|
136
|
+
Lo que **no** hace: no envía a un **shell** texto libre de un usuario, de un agente o de un fichero. `omk verify` y `omk update` son literales fijos (con el literal `--exit-marker` detrás, como todos los `omk` que lanza), `omk team set --autonomy` lleva uno de tres literales, y `omk team set --data` solo lleva base64url (letras, números, `-` y `_`) de un equipo que el worker ya validó entero (ids con `^[a-z0-9][a-z0-9-]{0,39}$`, roles, niveles y revisiones de listas cerradas, texto de los roles propios sin `|`, `<`, `>` ni caracteres de control); `omk team` lo valida otra vez. El id de agente se valida igual antes de pasarlo a `agent.launch`. La tarea de *Repartir* va como prompt al agente que eliges. Lo único que se escribe en el terminal de un agente es lo que tú escribes en *Avisos* (una línea, sin caracteres de control) y `/model <id>` con un id de modelo validado, y solo en terminales de agentes que el plugin sigue. En el terminal de la acción en curso solo se escribe `s` o `n`, cuando pulsas «Aprobar» o «Rechazar» y `omk` está preguntando. La salida de un terminal se enseña como texto, sin códigos de escape ni caracteres de control, y nada de lo que diga se ejecuta ni se interpreta salvo la línea de cierre de `omk`. No usa red ni secretos. Fuera de la API de Orca solo hace dos cosas, ambas para el coordinador que corre como chat: lee `.work/runs/*/plan.json` (`node:fs`, solo esos ficheros, sin seguir enlaces) y ejecuta el `orca` que trae la propia app (`resources/bin` junto a `Orca.exe`) con `orchestration send` (`node:child_process`, `execFile` **sin shell**: cada argumento va aparte, el id del Run se valida con `^run_[a-z0-9]{4,40}$` y tu respuesta va como un único argumento `--body`).
|
|
137
|
+
|
|
138
|
+
> **Seguridad**: «Aprobar» en la tarjeta de *Actualizar kit* es tu aprobación del acceso que pide la versión nueva del plugin: léelo en la salida antes de pulsarlo (la tarjeta enseña entonces las 30 últimas líneas, donde `omk` lista lo que Orca concedería). El plugin no aprueba nada por su cuenta: `omk` solo sigue con un `s` y el worker solo lo escribe cuando lo pulsas.
|
|
43
139
|
|
|
44
|
-
|
|
140
|
+
> **Seguridad**: cualquier agente del Run puede escribir en su buzón con `--from run:<id>`, así que un mensaje «Respuesta desde el panel» no prueba que lo escribieras tú. La skill `orca` solo lo acepta para la confirmación 1 (lanzar el plan o cambiarlo); el merge final y la limpieza (confirmaciones 2 y 3) solo valen escritos en el chat.
|
|
45
141
|
|
|
46
142
|
## Instalar
|
|
47
143
|
|
|
@@ -70,9 +166,11 @@ Dos sitios, los mismos valores (cambiar uno cambia el otro, y el worker se enter
|
|
|
70
166
|
|
|
71
167
|
| Ajuste | Por defecto | Valores |
|
|
72
168
|
|---|---|---|
|
|
169
|
+
| Repartir al lanzar un agente con tarea | Activado | sí / no |
|
|
73
170
|
| Contrato del worker en los despachos | Solo despachos del kit | Solo del kit · Todos · Desactivado |
|
|
74
171
|
| Agentes en la barra de estado | Activado | sí / no |
|
|
75
|
-
|
|
|
172
|
+
| Avisos de agentes | Activado | sí / no |
|
|
173
|
+
| Agente para inicializar | Claude Code | Lista de agentes del catálogo de Orca |
|
|
76
174
|
|
|
77
175
|
## Desactivar o quitar
|
|
78
176
|
|
|
@@ -85,27 +183,36 @@ Sin plugin, el kit sigue funcionando igual. Solo se pierden la paleta, la barra
|
|
|
85
183
|
|
|
86
184
|
## Limitaciones
|
|
87
185
|
|
|
88
|
-
- **Barra de estado**: al arrancar solo conoce los agentes del workspace enfocado (`agents.list` no da más); los de los demás aparecen con su siguiente cambio de estado. Un agente cuyo terminal se cierra sin pasar a `done` sigue contando hasta que se elimina su workspace o se reinicia el plugin (`orca plugin restart local.multiagent-kit`).
|
|
89
|
-
- **
|
|
186
|
+
- **Barra de estado**: al arrancar solo conoce los agentes del workspace enfocado (`agents.list` no da más); los de los demás aparecen con su siguiente cambio de estado. Un agente que Orca solo identifica por su panel (sin `terminalId`) no recibe el nombre de su despacho. Un agente cuyo terminal se cierra sin pasar a `done` sigue contando hasta que se elimina su workspace o se reinicia el plugin (`orca plugin restart local.multiagent-kit`).
|
|
187
|
+
- **Terminal al frente**: la API de plugins no puede enfocar ni mostrar un terminal (`terminal.create` lo abre en segundo plano), así que la salida se trae al panel. El terminal sigue ahí, con el título del comando, si prefieres mirarlo.
|
|
188
|
+
- **Acción en curso**: una cada vez (la última lanzada sustituye a la anterior en la tarjeta; su terminal sigue). Lee lo que el terminal pinta, no la salida del proceso: un terminal muy estrecho corta las líneas, y si se cierra a mitad la tarjeta queda «sin seguimiento» con lo último que leyó. De un agente que Orca abre como chat (sin terminal) no llega salida.
|
|
189
|
+
- **Detección de `omk` ausente**: es heurística. Busca el mensaje de "comando no encontrado" de bash, zsh, fish, cmd y PowerShell, en inglés y español. Con otros idiomas o shells, el error se ve en la salida pero la acción se queda «en curso» hasta su plazo.
|
|
90
190
|
- En un workspace remoto (SSH), `omk` se ejecuta en ese host, que es donde se usa el kit en ese workspace.
|
|
191
|
+
- **Chats de Orca**: un agente que corre como chat de Orca (sin terminal; es lo que lanza Orca para los workers si así lo tienes en sus ajustes de pestañas de agente) sale en *Avisos* y *Worktrees*, pero la API de plugins no puede escribir en un chat. La tarjeta del plan del coordinador sí se contesta desde el panel, por el buzón del Run (ver [Avisos y tarjeta del plan](#avisos-y-tarjeta-del-plan)); a los demás chats se les responde y se les cambia el modelo desde su chat («Ir a su workspace»).
|
|
192
|
+
- **Tarjeta del plan**: en un terminal la lee del `Write` de Claude Code (hook `agent.tool.after`; otros agentes nombran distinto su herramienta de escritura); en un chat, del disco cuando el coordinador espera, y solo en workspaces locales. Orca aún no engancha agentes por SSH o WSL: con ellos el plan sale solo en el chat.
|
|
193
|
+
- **Cambiar el modelo**: solo Claude Code (`/model`), y solo mientras espera instrucciones: trabajando, el texto acabaría en su turno; bloqueado, en el diálogo de permiso.
|
|
91
194
|
|
|
92
195
|
DEFERRED:
|
|
93
|
-
- **Progreso del run en la barra** (`ronda 1 · 2/3 unidades`): exige leer `.work/runs/<run>/units.md`, y la API de Orca no da acceso a ficheros a los workers. Hoy el coordinador lo deja en el comentario del worktree (`orca worktree set --comment`).
|
|
196
|
+
- **Progreso del run en la barra** (`ronda 1 · 2/3 unidades`): exige leer `.work/runs/<run>/units.md`, y la API de Orca no da acceso a ficheros a los workers (el plugin solo lee `plan.json`, con Node, para los chats; ampliarlo a más ficheros del proyecto queda fuera). Hoy el coordinador lo deja en el comentario del worktree (`orca worktree set --comment`).
|
|
94
197
|
- **Instalación desde Git** (`orca plugin install FernandoBaqueroo/orca-multiagent-kit`): la ayuda de `orca plugin install` (1.4.252) no documenta instalar desde una subcarpeta del repositorio. Haría falta un repo propio para el plugin o confirmar que Orca acepta una URL `tree/<ref>/orca-plugin`.
|
|
95
198
|
- **Preparar worktrees nuevos** (`workspace.create.after`): ya lo hacen `orca.yaml` (`scripts.setup`, `sharedDirectories`), `.worktreeinclude` y `worker-start --setup run`, que la skill pasa siempre; un hook duplicaría ese trabajo.
|
|
96
|
-
- **
|
|
199
|
+
- **Nivel de modelo en el panel**: el rol sale del despacho y el modelo de `--model` al arrancar, pero el nivel de cada unidad solo está en `.work/runs/<run>/run.md`, que el plugin no lee (sí en la tarjeta del plan, mientras espera confirmación).
|
|
200
|
+
- **Leer el equipo del proyecto en el panel**: el plugin no lee ficheros del proyecto (salvo `plan.json`); «Ver el del proyecto» lo enseña en un terminal con `omk team`.
|
|
97
201
|
|
|
98
202
|
## Probarlo
|
|
99
203
|
|
|
100
204
|
```bash
|
|
101
205
|
orca plugin validate orca-plugin --json # manifiesto como lo carga Orca
|
|
102
|
-
orca plugin test orca-plugin --json #
|
|
103
|
-
|
|
206
|
+
orca plugin test orca-plugin --json # 210 pruebas: src/**/*.test.ts(x)
|
|
207
|
+
bash tests/test_team.sh # omk team sobre una copia de templates/ORCHESTRATION.md
|
|
208
|
+
bash tests/test_update.sh # omk update y la línea de cierre que lee el plugin
|
|
209
|
+
orca plugin check orca-plugin --json # dibuja el panel en cada escenario de src/panel.check.ts
|
|
210
|
+
orca plugin shot orca-plugin --scenario accion-pregunta # PNG de un escenario (con la ventana de Orca minimizada)
|
|
104
211
|
orca plugin inspect orca-plugin --json # qué aporta y qué acceso pide
|
|
105
212
|
bash scripts/check.sh # comprobación estática del manifiesto, también en CI (sin Orca)
|
|
106
213
|
```
|
|
107
214
|
|
|
108
|
-
Las pruebas usan `orca/testing`: `mountWorker` sobre un host simulado con las capacidades del manifiesto. Cubren el hook (con y sin cabecera del kit, otros `inputKind`, el modo apagado e idempotencia), los comandos (literal enviado, workspace sin identificar, fallo de Orca notificado, id de agente hostil)
|
|
215
|
+
Las pruebas usan `orca/testing`: `mountWorker` sobre un host simulado con las capacidades del manifiesto. Cubren el hook (con y sin cabecera del kit, otros `inputKind`, el modo apagado e idempotencia), los comandos (literal enviado, workspace sin identificar, fallo de Orca notificado, id de agente hostil) la barra (eventos, siembra inicial, desactivada), los nombres (título que no se pierde, despacho antes y después del estado, hook de lanzamiento), los avisos (bloqueo una sola vez, run terminado, apagados) y las peticiones del panel (abrir workspace, aplicar equipo en base64url con equipos hostiles rechazados, repartir con cada entrada). El panel se prueba con `mount`: fichas de agentes y botón de ir, repartir con y sin texto, equipos predefinidos, casillas de proveedores, roles propios incompletos y completos, ajustes con desplegables, cada botón con su acción y un fallo del worker enseñado; y el worker rechaza cualquier acción del panel fuera de las tres. La detección de `omk` ausente se prueba con los mensajes reales de cada shell. La acción en curso (`src/worker/actions.test.ts`) se prueba con un terminal simulado cuya salida va cambiando: fin con código 0 y distinto de 0, `omk` ausente o anterior, la pregunta y sus respuestas (también la que llega tarde), el plazo, el terminal que deja de leerse, el reinicio del worker y el agente de inicializar.
|
|
109
216
|
|
|
110
217
|
Para probarlo en Orca sin instalarlo: `orca plugin dev watch orca-plugin --json`. También pide aprobación, y `Ctrl-C` lo descarga.
|
|
111
218
|
|