orca-multiagent-kit 1.6.0 → 1.7.1

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.
Files changed (71) hide show
  1. package/AI_INSTALL.md +4 -3
  2. package/CHANGELOG.md +47 -1
  3. package/GUIA.html +11 -9
  4. package/README.md +22 -23
  5. package/VERSION +1 -1
  6. package/bin/backup.js +44 -0
  7. package/bin/fetch.js +243 -0
  8. package/bin/hooks.js +187 -0
  9. package/bin/omk.js +147 -51
  10. package/bin/run/cleanup.js +402 -0
  11. package/bin/run/git.js +641 -0
  12. package/bin/run/glob.js +193 -0
  13. package/bin/run/ledger.js +243 -0
  14. package/bin/run/plan.js +328 -0
  15. package/bin/run/units.js +101 -0
  16. package/bin/run/util.js +116 -0
  17. package/bin/run.js +224 -0
  18. package/bin/setup.js +81 -8
  19. package/bin/sync.js +222 -0
  20. package/bin/ui.js +8 -4
  21. package/bin/update.js +169 -0
  22. package/core/AGENTS.md +7 -7
  23. package/docs/EJECUTABLE.md +5 -4
  24. package/docs/MANUAL.md +16 -3
  25. package/docs/ORQUESTADOR.md +59 -1
  26. package/docs/PLUGIN-ORCA.md +34 -16
  27. package/hooks/orca-gate.cjs +402 -0
  28. package/install.sh +26 -13
  29. package/orca-plugin/README.md +3 -1
  30. package/orca-plugin/orca-plugin.json +2 -2
  31. package/orca-plugin/src/kit.test.ts +35 -13
  32. package/orca-plugin/src/kit.ts +64 -19
  33. package/orca-plugin/src/panel-state.ts +11 -3
  34. package/orca-plugin/src/panel.check.ts +71 -0
  35. package/orca-plugin/src/panel.test.tsx +69 -4
  36. package/orca-plugin/src/panel.tsx +32 -16
  37. package/orca-plugin/src/protocol.ts +39 -0
  38. package/orca-plugin/src/tabs/autonomy.tsx +3 -1
  39. package/orca-plugin/src/tabs/history.test.tsx +1 -0
  40. package/orca-plugin/src/tabs/history.tsx +1 -0
  41. package/orca-plugin/src/tabs/notices.test.tsx +1 -0
  42. package/orca-plugin/src/tabs/worktrees.test.tsx +1 -0
  43. package/orca-plugin/src/ui/action-card.tsx +112 -0
  44. package/orca-plugin/src/worker/actions.test.ts +288 -0
  45. package/orca-plugin/src/worker/actions.ts +292 -0
  46. package/orca-plugin/src/worker/context.ts +4 -1
  47. package/orca-plugin/src/worker/history.ts +3 -3
  48. package/orca-plugin/src/worker/notices.ts +1 -4
  49. package/orca-plugin/src/worker.test.ts +24 -6
  50. package/orca-plugin/src/worker.ts +79 -83
  51. package/output-styles/csr-minimal.md +1 -0
  52. package/package.json +3 -3
  53. package/rules/50-done-gate.md +1 -1
  54. package/rules/95-multi-agent.md +13 -3
  55. package/skills/kit-init/SKILL.md +16 -4
  56. package/skills/orca/SKILL.md +27 -5
  57. package/skills/orca/references/adapters/artifact.md +2 -0
  58. package/skills/orca/references/adapters/chat.md +2 -0
  59. package/skills/orca/references/adapters/native-plan.md +6 -0
  60. package/skills/orca/references/adapters/plan-file.md +2 -0
  61. package/skills/orca/references/engine-manual.md +7 -5
  62. package/skills/orca/references/engine-subagents.md +4 -4
  63. package/skills/orca/references/integrate.md +14 -2
  64. package/skills/orca/references/ledger.md +1 -1
  65. package/skills/orca/references/olimpo.md +1 -1
  66. package/skills/orca/references/plan.md +2 -1
  67. package/skills/orca/references/units.md +1 -1
  68. package/skills/orca/references/worker-contract.md +2 -2
  69. package/templates/AGENTS.md +2 -2
  70. package/templates/CLAUDE.md +1 -1
  71. package/templates/claude-settings.json +25 -0
package/bin/update.js ADDED
@@ -0,0 +1,169 @@
1
+ // omk update: pone al día todo lo que el kit instala, con un solo comando y sea cual sea la forma en
2
+ // que se instaló. El propio kit (npm o el ejecutable autónomo: bin/fetch.js), la fuente única de
3
+ // ~/.agents, el proyecto de la carpeta actual (bloques de AGENTS.md y CLAUDE.md, ficheros que falten
4
+ // y los apartados nuevos de ORCHESTRATION.md y STACK.md: bin/sync.js), los hooks de reparto de Claude
5
+ // Code (bin/hooks.js) y el plugin de Orca.
6
+ 'use strict';
7
+
8
+ const { spawnSync } = require('node:child_process');
9
+ const fs = require('node:fs');
10
+ const path = require('node:path');
11
+ const { backupRel, makeBackup } = require('./backup');
12
+ const { fetchExecutable, fetchPackage, globalEntry, kitSource, newer } = require('./fetch');
13
+ const { applyHooks } = require('./hooks');
14
+ const { refreshPlugin } = require('./setup');
15
+ const { syncFile } = require('./sync');
16
+ const { c, sym } = require('./ui');
17
+
18
+ // Ficheros de proyecto que se ponen al día con su plantilla, y qué hacer la primera vez (sin sello).
19
+ // ORCHESTRATION.md recibe todo lo que le falte: omk team y la skill orca cuentan con esos campos.
20
+ // STACK.md pide borrar lo que no aplique, así que la primera vez solo se sella: a partir de ahí
21
+ // recibe lo que la plantilla estrene.
22
+ const SYNCED = [
23
+ { name: 'ORCHESTRATION.md', firstRun: 'add' },
24
+ { name: 'STACK.md', firstRun: 'stamp' },
25
+ ];
26
+ const PROJECT_BLOCK = /<!-- AGENTS:BEGIN project/;
27
+
28
+ const out = (s = '') => process.stdout.write(s + '\n');
29
+ const ok = (s) => out(` ${sym.ok} ${s}`);
30
+ const warn = (s) => out(` ${sym.warn} ${s}`);
31
+ const fail = (s) => out(` ${sym.fail} ${c.red(s)}`);
32
+ const todo = (s) => out(` ${sym.todo} ${s}`);
33
+ const detail = (s) => out(` ${sym.info} ${c.grey(s)}`);
34
+ const heading = (s) => { out(); out(` ${c.lime('◆')} ${c.bold(s)}`); };
35
+
36
+ /** Separa las opciones de omk update de las que van a install.sh (--agents, --dry-run…). */
37
+ function parseOptions(args) {
38
+ const own = { offline: false, force: false, yes: false, noProject: false, noPlugin: false, noHooks: false, dryRun: false };
39
+ const rest = [];
40
+ for (const a of args) {
41
+ if (a === '--offline') own.offline = true;
42
+ else if (a === '--force') own.force = true;
43
+ else if (a === '--yes' || a === '-y') own.yes = true;
44
+ else if (a === '--no-project') own.noProject = true;
45
+ else if (a === '--no-plugin') own.noPlugin = true;
46
+ else if (a === '--no-hooks') own.noHooks = true;
47
+ else { if (a === '--dry-run') own.dryRun = true; rest.push(a); }
48
+ }
49
+ return { ...own, rest };
50
+ }
51
+
52
+ /** La carpeta, si es un proyecto preparado con el kit: tiene ORCHESTRATION.md o el bloque del kit en AGENTS.md. */
53
+ function kitProject(dir) {
54
+ if (fs.existsSync(path.join(dir, 'ORCHESTRATION.md'))) return dir;
55
+ try {
56
+ return PROJECT_BLOCK.test(fs.readFileSync(path.join(dir, 'AGENTS.md'), 'utf8')) ? dir : null;
57
+ } catch (e) {
58
+ // Sin AGENTS.md no es un proyecto del kit; cualquier otro fallo de lectura sí se cuenta.
59
+ if (e.code === 'ENOENT') return null;
60
+ throw e;
61
+ }
62
+ }
63
+
64
+ /** Deja al día con su plantilla los ficheros de `SYNCED` que existan. Devuelve si todo fue bien. */
65
+ function syncProject({ kit, project, agentsHome, dryRun }) {
66
+ heading(`Plantillas del proyecto ${c.grey(path.basename(project))}`);
67
+ const { stamp, backup } = makeBackup(agentsHome);
68
+ let good = true;
69
+ for (const { name, firstRun } of SYNCED) {
70
+ const file = path.join(project, name);
71
+ if (!fs.existsSync(file)) continue;
72
+ let added;
73
+ let changed;
74
+ try {
75
+ ({ added, changed } = syncFile(path.join(kit, 'templates', name), file, { dryRun, backup, firstRun }));
76
+ } catch (e) {
77
+ fail(`${name}: no se pudo poner al día (${e.message})`);
78
+ good = false;
79
+ continue;
80
+ }
81
+ if (added.length === 0) {
82
+ ok(`${name} ya tiene todos los apartados de la plantilla`);
83
+ // Solo cambió el sello: la primera vez, o la plantilla estrena algo que este fichero ya tenía.
84
+ if (changed) detail(`${dryRun ? 'Se anotaría' : 'Anotado'} al final qué apartados de la plantilla conoce: lo que borres no volverá.`);
85
+ continue;
86
+ }
87
+ const count = `${added.length} ${added.length === 1 ? 'apartado nuevo' : 'apartados nuevos'}`;
88
+ if (dryRun) warn(`${name}: se añadirían ${count}`);
89
+ else ok(`${name}: ${count} ${c.grey('(lo que ya tenías no se toca)')}`);
90
+ for (const item of added) out(` ${sym.add} ${item}`);
91
+ if (dryRun) continue;
92
+ todo('Llevan el valor de la plantilla: revísalos, o pide al agente «inicializa el proyecto» para que los rellene.');
93
+ detail(`Copia anterior: omk restore ${stamp}`);
94
+ }
95
+ return good;
96
+ }
97
+
98
+ // Lo que dice «omk update» mientras trae la versión nueva.
99
+ const say = {
100
+ current: (version, note) => out(` ${sym.ok} Ya tienes la última versión (${version})${note ? ` (${note})` : ''}. Reaplicando la instalación…`),
101
+ updating: (version, latest) => out(` ${c.lime('›')} Actualizando ${c.grey(version)} → ${c.lime(latest)}`),
102
+ };
103
+
104
+ /**
105
+ * Trae la versión nueva del kit según cómo se instaló. Devuelve la orden con la que sigue el omk
106
+ * nuevo (`[programa, ...argumentos]`), o `null` si esta copia ya es la última y sigue ella.
107
+ */
108
+ async function fetchKit({ kit, version, standalone, force }) {
109
+ const source = kitSource(kit, standalone);
110
+ if (source === 'exe') {
111
+ out(` ${c.lime('›')} Buscando la última versión del ejecutable…`);
112
+ const latest = await fetchExecutable({ version, target: process.execPath, force });
113
+ if (latest === null) { say.current(version, ''); return null; }
114
+ say.updating(version, latest);
115
+ detail('Descargado y comprobado con su SHA-256. Sigue el ejecutable nuevo.');
116
+ return [process.execPath];
117
+ }
118
+ if (source === 'npm') {
119
+ if (!fetchPackage(version, force, say)) return null;
120
+ // El omk recién instalado, por su ruta y con este mismo Node; si no se encuentra, el del PATH.
121
+ const entry = globalEntry();
122
+ return entry ? [process.execPath, entry] : ['omk'];
123
+ }
124
+ out(` ${sym.info} Esta copia del kit (${kit}) no viene de npm ni es el ejecutable: se actualiza como la obtuviste`);
125
+ detail('(git pull, o el zip de la última release). Reaplicando ahora esta versión…');
126
+ return null;
127
+ }
128
+
129
+ /** omk update. Devuelve el código de salida. */
130
+ async function update({ kit, version, args, installer, standalone, agentsHome, cwd = process.cwd() }) {
131
+ const opts = parseOptions(args);
132
+ if (!opts.offline) {
133
+ const next = await fetchKit({ kit, version, standalone, force: opts.force });
134
+ if (next) {
135
+ // El resto lo hace el omk recién instalado: es el que trae las plantillas y el plugin nuevos.
136
+ const [program, ...prefix] = next;
137
+ const forwarded = args.filter((a) => a !== '--force');
138
+ const run = spawnSync(program, [...prefix, 'update', '--offline', ...forwarded], {
139
+ stdio: 'inherit', shell: program === 'omk' && process.platform === 'win32',
140
+ });
141
+ if (run.error) throw new Error(`no pude seguir con el omk nuevo (${run.error.message}). Repite: omk update --offline`);
142
+ return run.status === null ? 1 : run.status;
143
+ }
144
+ }
145
+
146
+ const project = opts.noProject ? null : kitProject(cwd);
147
+ const code = await installer(project ? [...opts.rest, '--project', project] : opts.rest);
148
+ if (code !== 0) return code;
149
+
150
+ let good = true;
151
+ if (project) good = syncProject({ kit, project, agentsHome, dryRun: opts.dryRun }) && good;
152
+ else if (!opts.noProject) {
153
+ heading('Proyecto');
154
+ detail(`${cwd} no es un proyecto preparado con el kit: no hay nada que poner al día aquí.`);
155
+ detail('Para prepararlo: omk init, o «inicializa el proyecto» en el agente.');
156
+ }
157
+ const omkBinary = standalone ? require('./setup').installedOmk() : null;
158
+ good = applyHooks({ kit, agentsHome, project, dryRun: opts.dryRun, skip: opts.noHooks, omkBinary }) && good;
159
+ if (!opts.noPlugin) good = (await refreshPlugin({ kit, yes: opts.yes, dryRun: opts.dryRun })) && good;
160
+
161
+ out();
162
+ if (opts.dryRun) out(` ${c.amber('Simulación:')} no se ha escrito nada.`);
163
+ else if (good) out(` ${sym.ok} ${c.bold(`Kit al día (v${version})`)}`);
164
+ else out(` ${sym.fail} ${c.bold(c.red('La actualización ha terminado con fallos'))} ${c.grey('(arriba, con ✗)')}`);
165
+ out();
166
+ return good ? 0 : 1;
167
+ }
168
+
169
+ module.exports = { update, parseOptions, newer, kitProject, backupRel };
package/core/AGENTS.md CHANGED
@@ -1,4 +1,4 @@
1
- # Reglas operativas globales (Orca Multiagent Kit v1.6.0 · CSR + MAW)
1
+ # Reglas operativas globales (Orca Multiagent Kit v1.7.1 · CSR + MAW)
2
2
  <!-- Fuente única para todos los agentes (import o enlace). Edita el kit y reinstala; no edites copias. -->
3
3
 
4
4
  ## 0. Precedencia
@@ -39,7 +39,7 @@ Ningún código es válido hasta pasar, en orden y sin saltos (módulos en `~/.a
39
39
  4. **Autorrevisión adversarial**: `50-done-gate.md` §4.
40
40
  5. **Seguridad**: `30-security.md` siempre; `31-security-audit.md` si toca entrada de usuario, auth, autorización, cripto, ficheros, red, SQL, deserialización, procesos, secretos o dependencias; `32-ai-security.md` si llama a un LLM o define agentes, herramientas o servidores MCP.
41
41
  6. **Tests**: `40-testing.md`. Código nuevo sin test ⇒ no está hecho, salvo veto explícito del usuario.
42
- 7. **Gates**: format → lint → typecheck → build → test → coverage → sec-scan → deps (comandos de `STACK.md`).
42
+ 7. **Gates**: format → lint → typecheck → build → test → coverage → sec-scan → deps-audit (comandos de `STACK.md`).
43
43
  8. **Reporte** (formato de `50-done-gate.md` §8): tabla `gate | cmd | PASS/FAIL/SKIPPED/N/A`. Nunca `PASS` de algo no ejecutado: `SKIPPED (motivo)`. Si un gate falla, arregla la causa y repite desde ese gate.
44
44
 
45
45
  ## 5. Prohibiciones duras — YOU MUST NOT
@@ -53,12 +53,12 @@ Ningún código es válido hasta pasar, en orden y sin saltos (módulos en `~/.a
53
53
  - Comandos destructivos (`rm -rf`, `push --force`, `DROP`, `reset --hard`, borrar ramas/tablas/buckets) sin confirmación explícita previa.
54
54
  - Concatenar entrada de usuario en SQL, shell, HTML, rutas o plantillas. Criptografía propia o parámetros no recomendados.
55
55
 
56
- ## 6. Trabajo multiagente (Orca) — IMPORTANT
57
- - **Usa la skill `orca` por iniciativa propia**, sin esperar a que te lo pidan, cuando la tarea tenga ≥2 partes independientes de >15 min (varias user stories, sprints, módulos o pantallas) o el usuario mencione paralelo, Orca, worktrees o varios agentes. Ella decide si compensa y, si no, lo dice en una línea y sigues tú.
58
- - En proyectos con spec-kit, `/speckit.implement` llama a `orca` automáticamente (hook `before_implement`). No hace falta pedirlo.
59
- - Cambio único y claro ⇒ sin orquestar: hazlo y pasa `csr-gate`.
56
+ ## 6. Trabajo multiagente (Orca) — YOU MUST
57
+ - **Puerta de reparto**: antes de la primera edición de todo trabajo de implementación —prompt de chat, plan aprobado (modo plan de Claude Code, `implementation_plan.md` de Antigravity), plan en fichero (`planes/*.md`), artefacto o ticket— cuenta sus entregables separables (user stories, sprints, módulos, pantallas, endpoints, secciones del plan). Con **≥2**, carga la skill `orca` (sin herramienta de skills: lee `~/.agents/skills/orca/SKILL.md`) y, **antes de la primera edición**, deja su veredicto escrito en el chat (texto visible: decidirlo solo en el razonamiento no cuenta) en una línea: `ORCA: secuencial — <motivo>`, u `ORCA: <N> unidades · …` seguida del plan de rondas, y entonces no se edita nada hasta la respuesta del usuario (salvo autonomía `auto`). En Claude Code lo impone un hook (`omk gate`): regístrala además con `echo "ORCA: …"` (la misma línea), o la edición se deniega. Si compensa (tiempos, solapes) lo decide la skill con sus datos, no tú antes de cargarla. También la cargas si el usuario menciona paralelo, Orca, worktrees o varios agentes.
58
+ - **Todo plan que escribas** (modo plan, `implementation_plan.md`, `planes/*.md`, artefacto) termina con una sección `Reparto` con ese veredicto y, si reparte, la tabla `unidad | ficheros | depende`: lo ve quien lo aprueba y no se pierde al cambiar de contexto. «Implementa el plan» ⇒ se ejecuta según esa sección; si falta, pasa la puerta antes de editar.
59
+ - No pasan por la puerta (y no llevan línea `ORCA:`): preguntas, un solo entregable (hazlo y pasa `csr-gate`), un worker con su unidad (`UNIT:`) y `/speckit.implement`, que llama a `orca` con su hook `before_implement`.
60
60
  - Respeta la autonomía de `./ORCHESTRATION.md` (por defecto `semi`: el usuario confirma el plan de rondas, el merge final y la limpieza de worktrees y ramas; nada más, salvo decisiones de producto).
61
- - **Invariantes — YOU MUST**: (1) una unidad = un worktree = una rama; (2) los ficheros `shared` de `ORCHESTRATION.md` los toca una sola unidad por ronda o el coordinador; (3) un worker no edita `tasks.md`, `planes/*.md`, `ORCHESTRATION.md`, `STACK.md`, lockfiles ni migraciones ajenas; (4) un worker no mergea, ni hace push, ni borra ramas; (5) todo worker entrega su informe; (6) salir del alcance ⇒ `BLOCKED:` y preguntar; (7) nunca merge a la rama por defecto ni push sin confirmación; (8) ningún worktree nace de una rama local sin contrastar con `origin`, y todo worktree integrado se ofrece para borrar al cerrar el run.
61
+ - **Invariantes — YOU MUST**: (1) una unidad = un worktree = una rama; (2) los ficheros `shared` de `ORCHESTRATION.md` los toca una sola unidad por ronda o el coordinador; (3) un worker no edita `tasks.md`, `planes/*.md`, `ORCHESTRATION.md`, `STACK.md`, lockfiles, ficheros generados ni migraciones ajenas; (4) un worker no mergea, ni hace push, ni borra ramas; (5) todo worker entrega su informe; (6) salir del alcance ⇒ `BLOCKED:` y preguntar; (7) nunca merge a la rama por defecto ni push sin confirmación; (8) ningún worktree nace de una rama local sin contrastar con `origin`, y todo worktree integrado se ofrece para borrar al cerrar el run.
62
62
  Detalle: `~/.agents/rules/95-multi-agent.md`.
63
63
 
64
64
  ## 7. Router (leer bajo demanda, no todo a la vez)
@@ -6,7 +6,9 @@
6
6
 
7
7
  | Paso | Qué pasa | Si falla |
8
8
  |---|---|---|
9
- | 1. Kit | `omk install` (con backup, como siempre; acepta `--agents` y `--dry-run`) | Se para con el código de `install.sh` |
9
+ | 0. Solo con npx | El kit corre desde una caché que npm borra cuando quiere: instala `omk` de forma permanente (`npm install -g orca-multiagent-kit@<versión>`) y sigue desde ahí | Dice cómo hacerlo a mano y sale con error |
10
+ | 1. Kit | Reglas y skills en `~/.agents` (con backup, como siempre; acepta `--agents` y `--dry-run`) | Se para con el código de `install.sh` |
11
+ | 1b. Reparto en Claude Code | Si usas Claude Code, fusiona en `~/.claude/settings.json` los hooks que recuerdan la puerta de reparto y la puerta obligatoria (`--no-hooks` para omitirlo). Sin Node en el PATH, la puerta se ejecuta con el propio `omk` (`omk gate hook`) | Un `settings.json` que no es JSON no se toca, y lo dice |
10
12
  | 2. `omk` en el `PATH` (solo el ejecutable) | Se copia a sí mismo a `%LOCALAPPDATA%\Programs\orca-multiagent-kit\omk.exe` (Windows) o `~/.local/bin/omk`, y en Windows añade esa carpeta al `Path` de tu usuario | No pisa un `omk` que no sea el del kit; lo dice y sale con error |
11
13
  | 3. Orca | Busca su CLI (`PATH`, o donde lo deja el instalador de Orca; `OMK_ORCA` para indicar otro) y comprueba que su versión cumple `engines.orca` del plugin | Dice qué falta (instalar o actualizar Orca) y sale con error |
12
14
  | 4. App | Si Orca no está abierto, `orca open` y espera a que arranque | Sale con error |
@@ -39,7 +41,7 @@ Es un [Node SEA](https://nodejs.org/api/single-executable-applications.html): el
39
41
 
40
42
  - Solo extrae cuando cambia la build (sello `.omk-build` con el SHA-256 del kit embebido). Extrae en `<carpeta>.new` y la cambia por la anterior al final: una extracción a medias no deja un kit roto.
41
43
  - No pisa una carpeta que no sea una copia del kit (sin `VERSION` e `install.sh`). En macOS y Linux es la misma carpeta que usa `scripts/get.sh`: la versión que quede es la del último que se ejecutó.
42
- - `omk update` en el ejecutable no descarga nada: te da el enlace de la última release y vuelve a aplicar la instalación de su versión.
44
+ - `omk update` en el ejecutable se actualiza a sí mismo: mira cuál es la última release, descarga el ejecutable de tu sistema junto al que está en marcha (`omk.new`), comprueba que su SHA-256 es el del `.sha256` publicado y solo entonces lo cambia (en Windows renombra el que está en marcha a `omk.exe.old`, que se borra en la siguiente actualización). Después el ejecutable nuevo extrae su kit y pone al día `~/.agents`, el proyecto de la carpeta actual y el plugin de Orca. Si la descarga o la comprobación fallan, el ejecutable queda como estaba. Solo descarga por HTTPS de GitHub. `omk update --offline` no descarga nada.
43
45
  - Sigue necesitando bash para `install.sh`: en Windows, Git for Windows (Orca usa Git para los worktrees, así que suele estar ya).
44
46
  - Pesa ~90 MiB, porque lleva Node entero.
45
47
 
@@ -61,10 +63,9 @@ Pasos: empaqueta en `kit.json.gz` lo mismo que el zip de la release; genera el b
61
63
  ## Pruebas
62
64
 
63
65
  - `tests/test_orca.sh`: `omk setup` y `omk plugin` contra `tests/fixtures/fake-orca.js`, un doble del CLI de Orca (`OMK_ORCA` apunta siempre a él: las pruebas nunca hablan con tu Orca). Cubre la aprobación (sin `--yes` ni terminal no aprueba; con `--yes` usa la huella de Orca; una huella con formato inesperado se rechaza), cada estado del plugin, Orca ausente o antigua, y `setup` completo, en simulación y sin aprobación.
64
- - `tests/test_exe.sh`: el ejecutable (extracción, sello, carpeta ajena, `install --dry-run`, `update`, `setup` copiándose a `OMK_BIN_DIR` sin tocar el `PATH`, un `omk` ajeno que no se pisa).
66
+ - `tests/test_exe.sh`: el ejecutable (extracción, sello, carpeta ajena, `install --dry-run`, `update --offline`, `setup` copiándose a `OMK_BIN_DIR` sin tocar el `PATH`, un `omk` ajeno que no se pisa, y la autoactualización de extremo a extremo: una «release» servida en la propia máquina (`OMK_RELEASE_BASE`, que solo admite HTTPS o HTTP contra `127.0.0.1`) de la que el ejecutable en marcha se descarga, se comprueba, se sustituye y sigue).
65
67
  - La CI ejecuta las dos en Linux, macOS y Windows (job `exe`).
66
68
 
67
69
  DEFERRED:
68
- - **Autoactualización del ejecutable**: `omk update` en el ejecutable da el enlace a la release, no descarga. Descargar y sustituir un binario en ejecución exige verificar su integridad (firma o checksum publicado) y en Windows renombrarlo en caliente; queda para otro PR.
69
70
  - **Firma de código** (Authenticode, notarización de Apple): necesita certificados del proyecto.
70
71
  - **Linux arm64 y macOS x64**: la release construye los runners por defecto de GitHub (`ubuntu-latest` x64, `macos-latest` arm64, `windows-latest` x64).
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 · 60-git-workflow ·
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
- Con Node ≥ 18 lo más cómodo es el CLI: `npx orca-multiagent-kit install`, o `npm install -g orca-multiagent-kit` para tener `omk` siempre (`omk install`, `omk init`, `omk verify`, `omk adopt`, `omk restore`, `omk update`). Sin Node, con el zip o un clon:
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
 
@@ -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 10 min por unidad y 10 min por ronda, con penalización por cada fichero `shared` que obligue a serializar. En caso de duda, secuencial.
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`).
@@ -8,9 +8,9 @@ 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` | `terminal.create` con el literal `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`) |
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
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
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
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) |
@@ -18,13 +18,25 @@ Requisitos: Orca ≥ 1.4.248 (hooks y barra de estado) con los plugins activados
18
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
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
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 cuatro 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` |
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) |
22
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* |
23
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) |
24
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` |
25
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 |
26
27
 
27
- Si `omk` no está en el `PATH`, el terminal muestra el error del shell y, en unos 15 s, 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), avisa y no ejecuta nada: es preferible no lanzar nada a lanzarlo en otro workspace.
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`).
28
40
 
29
41
  ### Nombres de los agentes
30
42
 
@@ -38,9 +50,9 @@ El workspace sale de `workspace.list`. Los eventos de agentes lo identifican a v
38
50
 
39
51
  ### Repartir siempre
40
52
 
41
- Sin el plugin, la orquestación solo arranca sola con spec-kit (el hook `before_implement` de `/speckit.implement`); en el resto de casos depende de que el agente decida usar la skill `orca`, y a menudo no lo hace. 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
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
42
54
 
43
- > [Orca Multiagent Kit] Antes de empezar, aplica la skill orca (~/.agents/skills/orca/SKILL.md) a esta tarea: decide si compensa repartirla entre agentes y, si compensa, repártela. La entrada es este prompt (adaptador de chat): no hace falta spec-kit. Si no compensa, hazla tú directamente.
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.
44
56
 
45
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:
46
58
 
@@ -111,17 +123,19 @@ Es un plugin `trusted-worker`: Orca ejecuta `src/worker.ts` en un proceso Node a
111
123
  |---|---|---|
112
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 |
113
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 |
114
- | `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 (`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 |
115
- | `terminal:read` | Leer la salida de **ese** terminal para detectar que `omk` no existe y avisar, y las últimas líneas del terminal de un agente que espera, para su aviso | El fallo se ve en el terminal, pero no llega la notificación, y los avisos salen sin contexto |
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 |
116
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 |
117
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` |
118
130
  | `notifications:show` | Avisos accionables (sin `omk`, sin workspace, fallos de Orca, agente bloqueado, run terminado) | Los avisos solo quedan en `orca plugin logs` |
119
- | `settings:own` | Leer los cuatro ajustes del plugin, y cambiarlos desde el panel | Se usan los valores por defecto y el panel no puede guardarlos |
120
- | `storage:own` | Guardar el historial (las 200 últimas entradas, clave `history.v1`) | El historial solo dura hasta que se reinicia el plugin |
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 |
121
133
 
122
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).
123
135
 
124
- 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, `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. 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`).
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.
125
139
 
126
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.
127
141
 
@@ -170,7 +184,9 @@ Sin plugin, el kit sigue funcionando igual. Solo se pierden la paleta, la barra
170
184
  ## Limitaciones
171
185
 
172
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`).
173
- - **Detección de `omk` ausente**: es heurística. Busca durante ~15 s 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 el terminal pero no llega la notificación.
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.
174
190
  - En un workspace remoto (SSH), `omk` se ejecuta en ese host, que es donde se usa el kit en ese workspace.
175
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»).
176
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.
@@ -187,14 +203,16 @@ DEFERRED:
187
203
 
188
204
  ```bash
189
205
  orca plugin validate orca-plugin --json # manifiesto como lo carga Orca
190
- orca plugin test orca-plugin --json # 106 pruebas: src/kit.test.ts, src/worker.test.ts y src/panel.test.tsx
206
+ orca plugin test orca-plugin --json # 210 pruebas: src/**/*.test.ts(x)
191
207
  bash tests/test_team.sh # omk team sobre una copia de templates/ORCHESTRATION.md
192
- orca plugin check orca-plugin --json
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)
193
211
  orca plugin inspect orca-plugin --json # qué aporta y qué acceso pide
194
212
  bash scripts/check.sh # comprobación estática del manifiesto, también en CI (sin Orca)
195
213
  ```
196
214
 
197
- 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.
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.
198
216
 
199
217
  Para probarlo en Orca sin instalarlo: `orca plugin dev watch orca-plugin --json`. También pide aprobación, y `Ctrl-C` lo descarga.
200
218