orca-multiagent-kit 1.2.0 → 1.3.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.
Files changed (62) hide show
  1. package/AI_INSTALL.md +3 -0
  2. package/CHANGELOG.md +28 -1
  3. package/README.md +4 -0
  4. package/VERSION +1 -1
  5. package/bin/omk.js +15 -9
  6. package/core/AGENTS.md +32 -29
  7. package/docs/CSR.md +95 -0
  8. package/docs/INSTALADOR-ORCA-WINDOWS.md +101 -0
  9. package/docs/MANUAL.md +2 -0
  10. package/docs/ORQUESTADOR.md +123 -0
  11. package/docs/PLUGIN-ORCA.md +102 -0
  12. package/install.sh +104 -20
  13. package/orca-plugin/.gitattributes +1 -0
  14. package/orca-plugin/README.md +12 -0
  15. package/orca-plugin/orca-plugin.json +80 -0
  16. package/orca-plugin/src/kit.test.ts +174 -0
  17. package/orca-plugin/src/kit.ts +141 -0
  18. package/orca-plugin/src/worker.test.ts +155 -0
  19. package/orca-plugin/src/worker.ts +182 -0
  20. package/orca-plugin/tsconfig.json +6 -0
  21. package/package.json +2 -2
  22. package/rules/00-router.md +2 -1
  23. package/rules/10-communication.md +11 -12
  24. package/rules/20-clean-code.md +7 -3
  25. package/rules/30-security.md +1 -1
  26. package/rules/31-security-audit.md +6 -2
  27. package/rules/32-ai-security.md +59 -0
  28. package/rules/40-testing.md +7 -0
  29. package/rules/50-done-gate.md +20 -17
  30. package/rules/60-git-workflow.md +1 -1
  31. package/rules/75-reliability.md +3 -3
  32. package/rules/80-supply-chain.md +18 -11
  33. package/rules/95-multi-agent.md +30 -9
  34. package/rules/lang/cpp.md +1 -1
  35. package/rules/lang/csharp.md +4 -4
  36. package/rules/lang/dart-flutter.md +1 -1
  37. package/rules/lang/infra.md +3 -4
  38. package/rules/lang/kotlin.md +1 -1
  39. package/rules/lang/php.md +1 -1
  40. package/rules/lang/shell.md +17 -1
  41. package/skills/csr-audit/SKILL.md +6 -5
  42. package/skills/csr-gate/SKILL.md +12 -8
  43. package/skills/csr-stack/SKILL.md +6 -3
  44. package/skills/orca/SKILL.md +17 -12
  45. package/skills/orca/references/adapters/artifact.md +1 -1
  46. package/skills/orca/references/adapters/chat.md +1 -1
  47. package/skills/orca/references/adapters/native-plan.md +1 -1
  48. package/skills/orca/references/adapters/plan-file.md +1 -1
  49. package/skills/orca/references/adapters/speckit.md +2 -0
  50. package/skills/orca/references/engine-manual.md +5 -5
  51. package/skills/orca/references/engine-orca.md +64 -23
  52. package/skills/orca/references/engine-subagents.md +13 -4
  53. package/skills/orca/references/integrate.md +27 -15
  54. package/skills/orca/references/ledger.md +56 -0
  55. package/skills/orca/references/race.md +1 -0
  56. package/skills/orca/references/setup.md +3 -2
  57. package/skills/orca/references/units.md +7 -0
  58. package/skills/orca/references/worker-contract.md +24 -11
  59. package/skills/speckit-orca-implement/SKILL.md +2 -0
  60. package/speckit-extension/orca/commands/implement.md +2 -0
  61. package/templates/ORCHESTRATION.md +4 -0
  62. package/templates/STACK.md +2 -2
@@ -0,0 +1,102 @@
1
+ # Plugin de Orca
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 cambio en los despachos de orquestación y un indicador en la barra de estado.
4
+
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
+
7
+ ## Qué hace
8
+
9
+ | Pieza | Qué ves | Cómo funciona |
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`) |
14
+ | **Orca Multiagent Kit: estado de los agentes** | Una línea por agente activo: título y estado | Lo que ha ido contando la barra de estado |
15
+ | **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` |
16
+ | **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 |
17
+
18
+ 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 `./install.sh`). 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.
19
+
20
+ ### Por qué el contrato del worker
21
+
22
+ Con el motor Orca, la skill `orca` solo copia en el despacho el alcance del contrato (§2), porque Orca ya le explica al worker cómo preguntar y cómo cerrar con `worker_done`. El resto del contrato (arranque, verificación con `csr-gate` y el formato fijo del informe que lee el coordinador) se quedaba fuera. El hook añade una línea que remite al fichero completo. Para eso:
23
+
24
+ - Solo actúa sobre prompts que Orca marca como despacho de orquestación (`inputKind: "orchestration"`). Nunca toca lo que escribes tú, los prompts de arranque de un agente ni `orca terminal send`.
25
+ - En el modo por defecto (*Solo despachos del kit*), además, el despacho tiene que llevar la cabecera de la skill `orca` (`UNIT: U<n> …` al principio de una línea y `RUN: …`). Los despachos de otros coordinadores pasan intactos. *Todos los despachos* lo añade a cualquiera; *Desactivado* lo apaga.
26
+ - Si el prompt ya cita `worker-contract.md`, no lo repite.
27
+ - **No deniega nunca** y falla en abierto (`"onError": "pass"`): si el worker del plugin falla o tarda más de 2 s, Orca envía el prompt sin cambios. Es una ayuda para el worker, no un control de seguridad.
28
+
29
+ ## Permisos que pide
30
+
31
+ Es un plugin `trusted-worker`: Orca ejecuta `src/worker.ts` en un proceso Node aparte, con el acceso de tu usuario a la máquina. Por eso pide aprobación al instalarlo. Las capacidades, y para qué se usa cada una:
32
+
33
+ | Capacidad | Para qué | Si no la concedes |
34
+ |---|---|---|
35
+ | `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 |
36
+ | `terminal:send` | Abrir un terminal con `omk verify` / `omk update` (`terminal.create`) | No hay comandos de verificar ni actualizar |
37
+ | `terminal:read` | Leer la salida de **ese** terminal para detectar que `omk` no existe y avisar | El fallo se ve en el terminal, pero no llega la notificación |
38
+ | `agent:launch` | Lanzar el agente de «inicializar proyecto» (`agent.launch`) | No hay comando de inicializar |
39
+ | `agent:read` | Contar agentes por estado para la barra (`agents.list`, `agent.status.changed`) | La barra se queda en `MAW` |
40
+ | `notifications:show` | Avisos accionables (sin `omk`, sin workspace, fallos de Orca) | Los avisos solo quedan en `orca plugin logs` |
41
+ | `settings:own` | Leer los tres ajustes del plugin | Se usan los valores por defecto |
42
+
43
+ Lo que **no** hace: no envía al terminal texto que venga de un usuario, de un agente o de un fichero (los dos comandos son literales fijos). El id de agente del ajuste se valida (`^[a-z0-9][a-z0-9-]{0,39}$`) antes de pasarlo a `agent.launch`. No usa red, secretos ni almacenamiento, no lee ficheros del proyecto y no importa módulos de Node (`fs`, `child_process`…): todo pasa por la API de Orca y sus capacidades.
44
+
45
+ ## Instalar
46
+
47
+ El manifiesto está en `orca-plugin/`, no en la raíz del repo, así que se instala desde una carpeta (ver *Limitaciones*). Elige la que tengas:
48
+
49
+ ```bash
50
+ # Desde un clon o el zip de la release
51
+ orca plugin install ./orca-plugin --json
52
+
53
+ # Con el kit instalado por npm (npm i -g orca-multiagent-kit)
54
+ orca plugin install "$(npm root -g)/orca-multiagent-kit/orca-plugin" --json
55
+ ```
56
+
57
+ La primera vez termina con `approval_required` (código de salida 3). `error.data` lista lo que concedería (la tabla de arriba) y el comando exacto para repetirlo con `--approve <fingerprint>`. Revísalo y, si estás de acuerdo, ejecuta ese comando tal cual. La huella está ligada a esta versión, sus ficheros y su acceso: si una versión nueva pide algo más, Orca vuelve a preguntar. El plugin queda como `local.multiagent-kit`.
58
+
59
+ Ajustes en *Settings → Plugins → Orca Multiagent Kit*:
60
+
61
+ | Ajuste | Por defecto | Valores |
62
+ |---|---|---|
63
+ | Contrato del worker en los despachos | Solo despachos del kit | Solo del kit · Todos · Desactivado |
64
+ | Agentes en la barra de estado | Activado | sí / no |
65
+ | Agente para inicializar | `claude` | Id de agente de Orca (`claude`, `codex`…) |
66
+
67
+ ## Desactivar o quitar
68
+
69
+ ```bash
70
+ orca plugin disable local.multiagent-kit --json # deja de ejecutarse; se reactiva con enable
71
+ orca plugin uninstall local.multiagent-kit --json # lo quita
72
+ ```
73
+
74
+ Sin plugin, el kit sigue funcionando igual. Solo se pierden la paleta, la barra y la línea del contrato en los despachos.
75
+
76
+ ## Limitaciones
77
+
78
+ - **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`).
79
+ - **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.
80
+ - En un workspace remoto (SSH), `omk` se ejecuta en ese host, que es donde se usa el kit en ese workspace.
81
+
82
+ DEFERRED:
83
+ - **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`).
84
+ - **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`.
85
+ - **Instalación automática** con `install.sh` / `omk install`: ahora se instala a mano. Para hacerlo automático hay que tocar el instalador, y se deja para otro PR.
86
+ - **Preparar worktrees nuevos** (`workspace.create.after`): ya lo hacen `orca.yaml` y `worker-start --setup run`, así que un hook duplicaría ese trabajo.
87
+
88
+ ## Probarlo
89
+
90
+ ```bash
91
+ orca plugin validate orca-plugin --json # manifiesto como lo carga Orca
92
+ orca plugin test orca-plugin --json # 37 pruebas: src/kit.test.ts y src/worker.test.ts
93
+ orca plugin check orca-plugin --json
94
+ orca plugin inspect orca-plugin --json # qué aporta y qué acceso pide
95
+ bash scripts/check.sh # comprobación estática del manifiesto, también en CI (sin Orca)
96
+ ```
97
+
98
+ 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) y la barra (eventos, siembra inicial, desactivada). La detección de `omk` ausente se prueba con los mensajes reales de cada shell.
99
+
100
+ Para probarlo en Orca sin instalarlo: `orca plugin dev watch orca-plugin --json`. También pide aprobación, y `Ctrl-C` lo descarga.
101
+
102
+ RISK: con Orca 1.4.252, `orca plugin test` falla al importar `orca-runtime.mjs` cuando la ruta del plugin contiene una carpeta que empieza por punto (por ejemplo `.claude/worktrees/…`). Si te pasa, copia `orca-plugin/` a una ruta sin carpetas ocultas y ejecútalo allí.
package/install.sh CHANGED
@@ -12,10 +12,33 @@
12
12
  set -Eeuo pipefail
13
13
 
14
14
  SRC="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
15
- AG="${AGENT_KIT_HOME:-$HOME/.agents}"
16
- CLAUDE_DIR="${CLAUDE_CONFIG_DIR:-$HOME/.claude}"
17
- GEMINI_DIR="${GEMINI_DIR:-$HOME/.gemini}"
18
- CODEX_DIR="${CODEX_HOME:-$HOME/.codex}"
15
+
16
+ # Ruta en formato Windows (C:\..., la que inyectan Orca o PowerShell) -> formato POSIX de este bash.
17
+ to_posix() { # $1 ruta -> stdout
18
+ case "$1" in
19
+ [A-Za-z]:[\\/]*|[A-Za-z]:|*\\*) ;;
20
+ *) printf '%s' "$1"; return 0 ;;
21
+ esac
22
+ if command -v cygpath >/dev/null 2>&1; then cygpath -u "$1"; return 0; fi
23
+ if command -v wslpath >/dev/null 2>&1; then wslpath -u "$1"; return 0; fi
24
+ local p d
25
+ p="$(printf '%s' "$1" | tr '\\' '/')"
26
+ case "$p" in [A-Za-z]:*) d="$(printf '%s' "${p%%:*}" | tr '[:upper:]' '[:lower:]')"; p="/$d/${p#?:}"; p="$(printf '%s' "$p" | tr -s '/')" ;; esac
27
+ printf '%s' "${p%/}"
28
+ }
29
+
30
+ # En Git Bash/MSYS/Cygwin, ln -s COPIA por defecto: una copia rompe la fuente única sin avisar.
31
+ # nativestrict crea un enlace nativo de Windows o falla (y entonces lo decimos).
32
+ case "$(uname -s 2>/dev/null)" in
33
+ MINGW*|MSYS*) export MSYS="${MSYS:+$MSYS }winsymlinks:nativestrict"; WINLINKS=1 ;;
34
+ CYGWIN*) export CYGWIN="${CYGWIN:+$CYGWIN }winsymlinks:nativestrict"; WINLINKS=1 ;;
35
+ *) WINLINKS=0 ;;
36
+ esac
37
+
38
+ AG="$(to_posix "${AGENT_KIT_HOME:-$HOME/.agents}")"
39
+ CLAUDE_DIR="$(to_posix "${CLAUDE_CONFIG_DIR:-$HOME/.claude}")"
40
+ GEMINI_DIR="$(to_posix "${GEMINI_DIR:-$HOME/.gemini}")"
41
+ CODEX_DIR="$(to_posix "${CODEX_HOME:-$HOME/.codex}")"
19
42
  COPILOT_DIR="$HOME/.copilot"
20
43
  CURSOR_DIR="$HOME/.cursor"
21
44
  DEVIN_DIR="$HOME/.config/devin"
@@ -32,13 +55,13 @@ OLD_LANGS="cpp csharp dart-flutter go infra java kotlin php python react ruby ru
32
55
  PROJECT=""; PROJECT_ONLY=0; VERIFY=0; DRY=0; AGENTS=""; RESTORE=""; ADOPT=""
33
56
  while [ $# -gt 0 ]; do
34
57
  case "$1" in
35
- --project) PROJECT="${2:-}"; shift 2 ;;
36
- --project-only) PROJECT="${2:-}"; PROJECT_ONLY=1; shift 2 ;;
58
+ --project) PROJECT="$(to_posix "${2:-}")"; shift 2 ;;
59
+ --project-only) PROJECT="$(to_posix "${2:-}")"; PROJECT_ONLY=1; shift 2 ;;
37
60
  --agents) AGENTS="${2:-}"; shift 2 ;;
38
61
  --verify) VERIFY=1; shift ;;
39
62
  --dry-run) DRY=1; shift ;;
40
63
  --restore) RESTORE="${2:-}"; shift 2 ;;
41
- --adopt) ADOPT="${2:-}"; shift 2 ;;
64
+ --adopt) ADOPT="$(to_posix "${2:-}")"; shift 2 ;;
42
65
  -h|--help) sed -n '2,12p' "$0"; exit 0 ;;
43
66
  *) echo "Opcion desconocida: $1" >&2; exit 2 ;;
44
67
  esac
@@ -94,11 +117,19 @@ agent_names() { local o="" a; for a in $(printf '%s' "$AGENTS" | tr ',' ' '); do
94
117
  o="${o:+$o · }$a"; done; printf '%s' "$o"; }
95
118
  has_agent() { case ",$AGENTS," in *",$1,"*) return 0 ;; *) return 1 ;; esac; }
96
119
 
97
- # Mueve una ruta al backup conservando su ruta relativa a $HOME.
120
+ # Ruta dentro del backup: relativa a $HOME si cuelga de el; si no, bajo _abs/ con su ruta absoluta (--restore la deshace).
121
+ backup_rel() { # $1 ruta absoluta -> stdout
122
+ case "$1" in
123
+ "$HOME"/*) printf '%s' "${1#"$HOME"/}" ;;
124
+ /*) printf '_abs%s' "$1" ;;
125
+ *) echo "Ruta no absoluta, no se puede respaldar: $1" >&2; return 1 ;;
126
+ esac
127
+ }
128
+ # Mueve una ruta al backup.
98
129
  stash() {
99
130
  local p="$1" rel
100
131
  [ -e "$p" ] || [ -L "$p" ] || return 0
101
- rel="${p#$HOME/}"
132
+ rel="$(backup_rel "$p")"
102
133
  run mkdir -p "$BK/$(dirname "$rel")"
103
134
  run mv "$p" "$BK/$rel"
104
135
  MOVED=$((MOVED+1))
@@ -107,17 +138,28 @@ stash() {
107
138
  snapshot() {
108
139
  local p="$1" rel
109
140
  [ -e "$p" ] || return 0
110
- rel="${p#$HOME/}"
141
+ rel="$(backup_rel "$p")"
111
142
  run mkdir -p "$BK/$(dirname "$rel")"
112
143
  run cp -a "$p" "$BK/$rel"
113
144
  }
145
+ LINK_HELP="En Windows, activa el Modo de desarrollador (Configuracion > Sistema > Para programadores) o abre Git Bash como administrador, y repite. Lo ya movido esta en el backup: ./install.sh --restore $STAMP"
114
146
  # Deja $2 como enlace simbolico a $1. Si habia otra cosa, va al backup.
115
147
  link() {
116
148
  local target="$1" l="$2"
117
149
  if [ -L "$l" ] && [ "$(readlink "$l")" = "$target" ]; then return 0; fi
118
150
  stash "$l"
119
151
  run mkdir -p "$(dirname "$l")"
120
- run ln -s "$target" "$l"
152
+ run ln -s "$target" "$l" || { echo "No se pudo crear el enlace $l -> $target. $LINK_HELP" >&2; exit 1; }
153
+ }
154
+ # Antes de tocar nada: en Windows, comprueba que se pueden crear enlaces nativos.
155
+ check_links() {
156
+ [ "$WINLINKS" -eq 1 ] || return 0
157
+ local t; t="$(mktemp -d)"
158
+ mkdir "$t/destino"
159
+ if ln -s "$t/destino" "$t/enlace" 2>/dev/null && [ -L "$t/enlace" ]; then rm -rf "$t"; return 0; fi
160
+ rm -rf "$t"
161
+ echo "Este Windows no deja crear enlaces simbolicos, y el kit no instala copias (acabarian divergiendo). ${LINK_HELP%% Lo ya movido*}" >&2
162
+ exit 1
121
163
  }
122
164
  # Quita los bloques gestionados (CSR, MAW, AGENTS) de un fichero, conservando el resto.
123
165
  strip_blocks() { # $1 fichero -> stdout
@@ -140,6 +182,25 @@ write_file() { # $1 destino, stdin contenido
140
182
 
141
183
  [ -f "$SRC/core/AGENTS.md" ] || { echo "No encuentro core/AGENTS.md en $SRC" >&2; exit 1; }
142
184
 
185
+ # ------------------------------------------------------------------ perfil de Claude de Orca
186
+ # Orca lanza Claude con CLAUDE_CONFIG_DIR apuntando a un perfil propio (orca/claude-profiles/<id>/home) que
187
+ # importa @~/.claude/CLAUDE.md y enlaza skills/, rules/... a ~/.claude. Ese perfil es de Orca: el kit instala en
188
+ # ~/.claude y el perfil lo hereda. Si el perfil no importa ~/.claude, no se toca Claude (escribir ahi no duraria).
189
+ ORCA_PROFILE=""; CLAUDE_SKIP=0
190
+ is_orca_profile() { # $1 ruta POSIX
191
+ case "$1" in */[Oo]rca/claude-profiles/*) return 0 ;; esac
192
+ [ -n "${ORCA_CLAUDE_INJECTED_CONFIG_DIR:-}" ] && [ "$(to_posix "$ORCA_CLAUDE_INJECTED_CONFIG_DIR")" = "$1" ]
193
+ }
194
+ if [ "$CLAUDE_DIR" != "$HOME/.claude" ] && is_orca_profile "$CLAUDE_DIR"; then
195
+ ORCA_PROFILE="$CLAUDE_DIR"
196
+ if grep -q '^@~/\.claude/CLAUDE\.md' "$ORCA_PROFILE/CLAUDE.md" 2>/dev/null; then
197
+ CLAUDE_DIR="$HOME/.claude"
198
+ else
199
+ CLAUDE_SKIP=1
200
+ todo "Claude Code: el perfil de Orca $(short "$ORCA_PROFILE") no importa @~/.claude/CLAUDE.md y no lo toco (es de Orca). Claude dentro de Orca no verá el kit hasta que ese perfil importe ~/.claude/CLAUDE.md."
201
+ fi
202
+ fi
203
+
143
204
  # ------------------------------------------------------------------ restore
144
205
  if [ -n "$RESTORE" ]; then
145
206
  R="$AG/backups/$RESTORE"; [ -d "$R" ] || { echo "No existe la copia $R (consulta: omk backups)" >&2; exit 1; }
@@ -148,10 +209,14 @@ if [ -n "$RESTORE" ]; then
148
209
  N=0
149
210
  while IFS= read -r rel; do
150
211
  [ -n "$rel" ] || continue
151
- dest="$HOME/$rel"
152
- # si algun directorio padre es ahora un enlace (p. ej. una skill enlazada), quita el enlace: no escribir a traves de el
212
+ case "$rel" in _abs/*) dest="/${rel#_abs/}" ;; *) dest="$HOME/$rel" ;; esac
213
+ # si algun directorio padre es ahora un enlace del kit (p. ej. una skill enlazada a ~/.agents), quitalo:
214
+ # no escribir a traves de el. Los enlaces ajenos (dotfiles, perfiles de Orca) se respetan.
153
215
  p="$(dirname "$dest")"
154
- while [ "$p" != "$HOME" ] && [ "$p" != "/" ]; do [ -L "$p" ] && run rm -f "$p"; p="$(dirname "$p")"; done
216
+ while [ "$p" != "$HOME" ] && [ "$p" != "/" ] && [ "$p" != "." ]; do
217
+ if [ -L "$p" ]; then case "$(readlink "$p")" in "$AG"/*) run rm -f "$p" ;; esac; fi
218
+ p="$(dirname "$p")"
219
+ done
155
220
  if [ -L "$dest" ] || [ -f "$dest" ]; then run rm -f "$dest"; fi
156
221
  run mkdir -p "$(dirname "$dest")"; run cp -a "$R/$rel" "$dest"
157
222
  N=$((N+1))
@@ -173,6 +238,11 @@ if [ -z "$AGENTS" ]; then
173
238
  [ -d "$CURSOR_DIR" ] && AGENTS="$AGENTS,cursor"
174
239
  AGENTS="${AGENTS#,}" # devin solo con --agents (opt-in)
175
240
  fi
241
+ if [ "$CLAUDE_SKIP" -eq 1 ]; then
242
+ AGENTS="$(printf ',%s,' "$AGENTS" | sed 's/,claude,/,/; s/^,//; s/,$//')"
243
+ fi
244
+ [ -n "$ORCA_PROFILE" ] && [ "$CLAUDE_SKIP" -eq 0 ] && has_agent claude && \
245
+ info "Claude Code: perfil de Orca detectado ($(short "$ORCA_PROFILE")); se instala en ~/.claude, que el perfil importa. El perfil no se toca."
176
246
 
177
247
  # ------------------------------------------------------------------ adopt
178
248
  if [ -n "$ADOPT" ]; then
@@ -183,10 +253,11 @@ if [ -n "$ADOPT" ]; then
183
253
  [ -e "$DEST" ] && { echo "Ya existe $DEST. Si es la misma skill, borra una de las dos copias antes." >&2; exit 1; }
184
254
  title "Adoptar skill" "$NAME"
185
255
  phase "Compartiendo $NAME con todos los agentes"
256
+ check_links
186
257
  run mkdir -p "$BK" "$AG/skills"
187
258
  run cp -a "$SKD" "$BK/$NAME.orig"
188
259
  run mv "$SKD" "$DEST"
189
- run ln -s "$DEST" "$SKD"
260
+ run ln -s "$DEST" "$SKD" || { echo "No se pudo crear el enlace $SKD -> $DEST. $LINK_HELP" >&2; exit 1; }
190
261
  item add "copia única en $(short "$DEST")"
191
262
  item add "en su sitio original queda un enlace"
192
263
  case "$SKD" in "$CLAUDE_DIR"/skills/*) ;; *) has_agent claude && { link "$DEST" "$CLAUDE_DIR/skills/$NAME"; item add "enlazada en Claude Code"; } ;; esac
@@ -203,8 +274,22 @@ if [ "$VERIFY" -eq 1 ]; then
203
274
  vok() { nok=$((nok+1)); if [ -n "$EV" ]; then ev "check::ok::$1"; else printf ' %s✓%s %s\n' "$C_L" "$C_0" "$1"; fi; }
204
275
  vfail() { bad=$((bad+1)); if [ -n "$EV" ]; then ev "check::fail::$1"; else printf ' %s✗ %s%s\n' "$C_R" "$1" "$C_0"; fi; }
205
276
  vinfo() { if [ -n "$EV" ]; then ev "check::info::$1"; else printf ' %s· %s%s\n' "$C_D" "$1" "$C_0"; fi; }
206
- chk_link() { if [ -L "$3" ] && [ "$(readlink "$3")" = "$2" ]; then vok "$1"; else vfail "$1: $(short "$3") no enlaza a $(short "$2")"; fi; }
277
+ chk_link() {
278
+ if [ -L "$3" ] && [ "$(readlink "$3")" = "$2" ]; then vok "$1"
279
+ elif [ -e "$3" ] && [ ! -L "$3" ]; then vfail "$1: $(short "$3") es una copia, no un enlace (acabará divergiendo; ejecuta omk install)"
280
+ else vfail "$1: $(short "$3") no enlaza a $(short "$2")"; fi; }
281
+ # Skills de un agente: separa las copias (divergen en silencio) de las que faltan o apuntan a otro sitio.
282
+ chk_skills() { # $1 agente · $2 carpeta de skills
283
+ local s ms="" cs=""
284
+ for s in $KIT_SKILLS; do
285
+ if [ -L "$2/$s" ] && [ "$(readlink "$2/$s")" = "$AG/skills/$s" ]; then continue; fi
286
+ if [ -e "$2/$s" ] && [ ! -L "$2/$s" ]; then cs="$cs $s"; else ms="$ms $s"; fi
287
+ done
288
+ [ -n "$cs" ] && vfail "$1: skills copiadas en vez de enlazadas (acabarán divergiendo; ejecuta omk install):$cs"
289
+ [ -n "$ms" ] && vfail "$1: skills sin enlazar:$ms"
290
+ [ -z "$cs$ms" ] && vok "$1: skills enlazadas"; return 0; }
207
291
  title "Verificación" "$(agent_names)"
292
+ [ "$CLAUDE_SKIP" -eq 1 ] && vfail "Claude Code: el perfil de Orca $(short "$ORCA_PROFILE") no importa ~/.claude/CLAUDE.md, así que Claude en Orca no ve el kit"
208
293
  [ -f "$AG/AGENTS.md" ] && vok "núcleo en ~/.agents/AGENTS.md (v$(cat "$AG/AGENT_KIT_VERSION" 2>/dev/null || echo '?'))" || vfail "falta ~/.agents/AGENTS.md: ejecuta omk install"
209
294
  n=$(ls -1 "$AG/rules/lang"/*.md 2>/dev/null | wc -l | tr -d ' '); [ "$n" -ge 17 ] && vok "$n guías de lenguaje" || vfail "guías de lenguaje: $n de 17"
210
295
  ms=""; for s in $KIT_SKILLS; do [ -f "$AG/skills/$s/SKILL.md" ] || ms="$ms $s"; done
@@ -215,15 +300,13 @@ if [ "$VERIFY" -eq 1 ]; then
215
300
  grep -q '@~/.agents/AGENTS.md' "$CLAUDE_DIR/CLAUDE.md" 2>/dev/null && vok "Claude Code: CLAUDE.md importa el núcleo" || vfail "Claude Code: CLAUDE.md no importa el núcleo"
216
301
  grep -Eq '<!-- (CSR|MAW):BEGIN' "$CLAUDE_DIR/CLAUDE.md" 2>/dev/null && vfail "Claude Code: CLAUDE.md conserva bloques CSR/MAW antiguos" || true
217
302
  for r in $OLD_RULES; do [ -e "$CLAUDE_DIR/rules/$r" ] && vfail "Claude Code: copia antigua $(short "$CLAUDE_DIR/rules/$r") (Claude la carga siempre)"; done
218
- ms=""; for s in $KIT_SKILLS; do [ -L "$CLAUDE_DIR/skills/$s" ] && [ "$(readlink "$CLAUDE_DIR/skills/$s")" = "$AG/skills/$s" ] || ms="$ms $s"; done
219
- [ -z "$ms" ] && vok "Claude Code: skills enlazadas" || vfail "Claude Code: skills sin enlazar:$ms"
303
+ chk_skills "Claude Code" "$CLAUDE_DIR/skills"
220
304
  fi
221
305
  if has_agent antigravity; then
222
306
  chk_link "Antigravity: GEMINI.md es el núcleo" "$AG/AGENTS.md" "$GEMINI_DIR/GEMINI.md"
223
307
  for r in $OLD_RULES; do [ -e "$GEMINI_DIR/rules/$r" ] && vfail "Antigravity: copia antigua $(short "$GEMINI_DIR/rules/$r")"; done
224
308
  [ -e "$GEMINI_DIR/config/plugins/claude-session-rules" ] && vfail "Antigravity: el plugin claude-session-rules sigue instalado (duplica csr-*)"
225
- ms=""; for s in $KIT_SKILLS; do [ -L "$GEMINI_DIR/config/skills/$s" ] && [ "$(readlink "$GEMINI_DIR/config/skills/$s")" = "$AG/skills/$s" ] || ms="$ms $s"; done
226
- [ -z "$ms" ] && vok "Antigravity: skills enlazadas" || vfail "Antigravity: skills sin enlazar:$ms"
309
+ chk_skills "Antigravity" "$GEMINI_DIR/config/skills"
227
310
  fi
228
311
  has_agent codex && chk_link "Codex: AGENTS.md es el núcleo" "$AG/AGENTS.md" "$CODEX_DIR/AGENTS.md"
229
312
  has_agent copilot && chk_link "Copilot CLI: copilot-instructions.md es el núcleo" "$AG/AGENTS.md" "$COPILOT_DIR/copilot-instructions.md"
@@ -241,6 +324,7 @@ if [ "$PROJECT_ONLY" -eq 0 ]; then
241
324
  [ -n "$AGENTS" ] || { echo "No detecto ningún agente (Claude Code, Antigravity, Codex, Copilot o Cursor). Indica cuáles con --agents." >&2; exit 1; }
242
325
  SUB="$(agent_names)"; [ "$DRY" -eq 1 ] && SUB="$SUB · simulación, no se escribe nada"
243
326
  title "Orca Multiagent Kit v${VERSION}" "$SUB"
327
+ check_links
244
328
  run mkdir -p "$BK"
245
329
 
246
330
  # 1. Fuente canonica
@@ -0,0 +1 @@
1
+ * -text
@@ -0,0 +1,12 @@
1
+ # Plugin de Orca — Orca Multiagent Kit
2
+
3
+ Integra el kit en la app [Orca](https://www.onorca.dev) (≥ 1.4.248). Qué hace, qué permisos pide y cómo instalarlo: [`docs/PLUGIN-ORCA.md`](../docs/PLUGIN-ORCA.md).
4
+
5
+ ```sh
6
+ orca plugin validate . --json # manifiesto
7
+ orca plugin test . --json # src/*.test.ts con orca/testing
8
+ orca plugin inspect . --json # qué aporta y qué acceso pide
9
+ ```
10
+
11
+ - `src/kit.ts`: lógica pura (detección de despachos, mensajes de "comando no encontrado", resumen de agentes).
12
+ - `src/worker.ts`: el worker que Orca carga; solo habla con Orca por su API.
@@ -0,0 +1,80 @@
1
+ {
2
+ "manifestVersion": 2,
3
+ "id": "multiagent-kit",
4
+ "name": "Orca Multiagent Kit",
5
+ "version": "0.1.0",
6
+ "description": "Comandos del kit en la paleta, el contrato del worker en cada despacho de orquestación del kit y los agentes activos en la barra de estado.",
7
+ "author": {
8
+ "name": "Fernando Baquero y Necro-Coder",
9
+ "url": "https://github.com/FernandoBaqueroo/orca-multiagent-kit"
10
+ },
11
+ "repository": "https://github.com/FernandoBaqueroo/orca-multiagent-kit",
12
+ "homepage": "https://github.com/FernandoBaqueroo/orca-multiagent-kit/blob/main/docs/PLUGIN-ORCA.md",
13
+ "license": "MIT",
14
+ "engines": {
15
+ "orca": ">=1.4.248"
16
+ },
17
+ "execution": "trusted-worker",
18
+ "pluginApi": 1,
19
+ "main": "src/worker.ts",
20
+ "capabilities": [
21
+ { "kind": "workspace:read" },
22
+ { "kind": "terminal:send" },
23
+ { "kind": "terminal:read" },
24
+ { "kind": "agent:launch" },
25
+ { "kind": "agent:read" },
26
+ { "kind": "notifications:show" },
27
+ { "kind": "settings:own" }
28
+ ],
29
+ "contributes": {
30
+ "commands": [
31
+ { "id": "kit.verify", "title": "Orca Multiagent Kit: verificar instalación", "when": "workspace" },
32
+ { "id": "kit.init", "title": "Orca Multiagent Kit: inicializar proyecto", "when": "workspace" },
33
+ { "id": "kit.update", "title": "Orca Multiagent Kit: actualizar kit", "when": "workspace" },
34
+ { "id": "agents.status", "title": "Orca Multiagent Kit: estado de los agentes" }
35
+ ],
36
+ "hooks": [
37
+ { "event": "agent.prompt.before", "onError": "pass" }
38
+ ],
39
+ "events": [
40
+ { "on": "agent.status.changed" },
41
+ { "on": "workspace.removed" }
42
+ ],
43
+ "statusBarItems": [
44
+ {
45
+ "id": "agents",
46
+ "text": "MAW",
47
+ "icon": "bot",
48
+ "tooltip": "Orca Multiagent Kit: agentes activos",
49
+ "command": "agents.status"
50
+ }
51
+ ],
52
+ "settings": [
53
+ {
54
+ "key": "contractHint",
55
+ "title": "Contrato del worker en los despachos",
56
+ "description": "Añade a cada despacho de orquestación una línea que remite a ~/.agents/skills/orca/references/worker-contract.md. «Solo del kit» actúa en los despachos de la skill orca (cabecera UNIT/RUN).",
57
+ "type": "string",
58
+ "default": "kit",
59
+ "enum": ["kit", "all", "off"],
60
+ "enumLabels": ["Solo despachos del kit", "Todos los despachos", "Desactivado"]
61
+ },
62
+ {
63
+ "key": "statusBar",
64
+ "title": "Agentes en la barra de estado",
65
+ "description": "Muestra cuántos agentes trabajan, están bloqueados o esperan, en todos los workspaces.",
66
+ "type": "boolean",
67
+ "default": true
68
+ },
69
+ {
70
+ "key": "initAgent",
71
+ "title": "Agente para inicializar",
72
+ "description": "Id del agente que lanza «inicializar proyecto» con el prompt «inicializa el proyecto» (skill kit-init), por ejemplo claude o codex.",
73
+ "type": "string",
74
+ "default": "claude",
75
+ "maxLength": 40,
76
+ "placeholder": "claude"
77
+ }
78
+ ]
79
+ }
80
+ }
@@ -0,0 +1,174 @@
1
+ import { assert, describe, test } from 'orca/testing'
2
+ import {
3
+ CONTRACT_HINT,
4
+ describeAgents,
5
+ isKitDispatch,
6
+ isMissingCommand,
7
+ isValidAgentId,
8
+ parseContractHintMode,
9
+ pollUntil,
10
+ resolveFocusedWorkspaceId,
11
+ summarizeAgents,
12
+ withContractHint
13
+ } from './kit.ts'
14
+
15
+ const KIT_SPEC = 'UNIT: U2 — Endpoint POST /recargas RUN: 20261107-recargas BASE: abc123\n...'
16
+
17
+ describe('withContractHint', () => {
18
+ test('añade la referencia a un despacho de la skill orca', () => {
19
+ assert.equal(withContractHint(KIT_SPEC, 'orchestration', 'kit'), `${KIT_SPEC}\n\n${CONTRACT_HINT}`)
20
+ })
21
+
22
+ test('no toca despachos ajenos al kit en modo kit, sí en modo all', () => {
23
+ const foreign = 'Task T1 · Dispatch D1\nRevisa el PR 42 y responde con worker_done.'
24
+ assert.equal(withContractHint(foreign, 'orchestration', 'kit'), null)
25
+ assert.equal(withContractHint(foreign, 'orchestration', 'all'), `${foreign}\n\n${CONTRACT_HINT}`)
26
+ })
27
+
28
+ test('nunca toca prompts que no son despachos de orquestación', () => {
29
+ assert.equal(withContractHint(KIT_SPEC, 'launch', 'all'), null)
30
+ assert.equal(withContractHint(KIT_SPEC, 'driving', 'all'), null)
31
+ })
32
+
33
+ test('desactivado no cambia nada', () => {
34
+ assert.equal(withContractHint(KIT_SPEC, 'orchestration', 'off'), null)
35
+ })
36
+
37
+ test('es idempotente y respeta un contrato ya citado', () => {
38
+ const once = withContractHint(KIT_SPEC, 'orchestration', 'kit') ?? ''
39
+ assert.equal(withContractHint(once, 'orchestration', 'kit'), null)
40
+ const cited = `${KIT_SPEC}\nContrato: skills/orca/references/worker-contract.md`
41
+ assert.equal(withContractHint(cited, 'orchestration', 'all'), null)
42
+ })
43
+
44
+ test('detecta la cabecera del kit solo con UNIT y RUN', () => {
45
+ assert.equal(isKitDispatch(KIT_SPEC), true)
46
+ assert.equal(isKitDispatch('UNIT: U2 sin run'), false)
47
+ assert.equal(isKitDispatch('RUN: x pero sin unidad'), false)
48
+ assert.equal(isKitDispatch('la UNIT: U2 va en mitad de la línea RUN: x'), false)
49
+ })
50
+ })
51
+
52
+ describe('parseContractHintMode', () => {
53
+ test('acepta los tres modos y vuelve a kit ante cualquier otra cosa', () => {
54
+ assert.equal(parseContractHintMode('all'), 'all')
55
+ assert.equal(parseContractHintMode('off'), 'off')
56
+ assert.equal(parseContractHintMode('kit'), 'kit')
57
+ assert.equal(parseContractHintMode('ALL'), 'kit')
58
+ assert.equal(parseContractHintMode(undefined), 'kit')
59
+ assert.equal(parseContractHintMode(3), 'kit')
60
+ })
61
+ })
62
+
63
+ describe('isMissingCommand', () => {
64
+ const cases: [string, string][] = [
65
+ ['bash', 'bash: omk: command not found'],
66
+ ['zsh', 'zsh: command not found: omk'],
67
+ ['fish', 'fish: Unknown command: omk'],
68
+ ['cmd', "'omk' is not recognized as an internal or external command,"],
69
+ ['cmd es', "'omk' no se reconoce como un comando interno o externo,"],
70
+ ['pwsh', "omk: The term 'omk' is not recognized as a name of a cmdlet, function, script file"],
71
+ ['pwsh es', "omk : El término 'omk' no se reconoce como nombre de un cmdlet"],
72
+ ['bash es', 'bash: omk: orden no encontrada']
73
+ ]
74
+ for (const [shell, line] of cases) {
75
+ test(`reconoce el error de ${shell}`, () => {
76
+ assert.equal(isMissingCommand(['$ omk verify', line]), true)
77
+ })
78
+ }
79
+
80
+ test('no confunde la salida normal de omk ni otros comandos', () => {
81
+ assert.equal(isMissingCommand(['$ omk verify', '[kit] OK CLAUDE.md importa AGENTS.md']), false)
82
+ assert.equal(isMissingCommand(['bash: omkx: command not found']), false)
83
+ assert.equal(isMissingCommand(['bash: git: command not found']), false)
84
+ assert.equal(isMissingCommand([]), false)
85
+ })
86
+ })
87
+
88
+ describe('resolveFocusedWorkspaceId', () => {
89
+ const workspaces = [
90
+ { id: 'w1', name: 'app', branch: 'main' },
91
+ { id: 'w2', name: 'app', branch: 'feat/x' },
92
+ { id: 'w3', name: 'notas', branch: null }
93
+ ]
94
+
95
+ test('cruza nombre y rama', () => {
96
+ assert.equal(resolveFocusedWorkspaceId({ displayName: 'app', branch: 'feat/x' }, workspaces), 'w2')
97
+ })
98
+
99
+ test('una carpeta sin rama casa con branch vacío', () => {
100
+ assert.equal(resolveFocusedWorkspaceId({ displayName: 'notas', branch: '' }, workspaces), 'w3')
101
+ })
102
+
103
+ test('sin foco, sin coincidencia o con coincidencia ambigua no adivina', () => {
104
+ assert.equal(resolveFocusedWorkspaceId(null, workspaces), null)
105
+ assert.equal(resolveFocusedWorkspaceId({ displayName: 'otro', branch: 'main' }, workspaces), null)
106
+ const twice = [...workspaces, { id: 'w4', name: 'app', branch: 'main' }]
107
+ assert.equal(resolveFocusedWorkspaceId({ displayName: 'app', branch: 'main' }, twice), null)
108
+ })
109
+ })
110
+
111
+ describe('isValidAgentId', () => {
112
+ test('acepta ids simples y rechaza lo demás', () => {
113
+ assert.equal(isValidAgentId('claude'), true)
114
+ assert.equal(isValidAgentId('cursor-agent'), true)
115
+ assert.equal(isValidAgentId(''), false)
116
+ assert.equal(isValidAgentId('claude; rm -rf ~'), false)
117
+ assert.equal(isValidAgentId('Claude'), false)
118
+ assert.equal(isValidAgentId('a'.repeat(41)), false)
119
+ assert.equal(isValidAgentId(null), false)
120
+ })
121
+ })
122
+
123
+ describe('summarizeAgents', () => {
124
+ test('sin agentes activos', () => {
125
+ const summary = summarizeAgents([{ workspaceId: null, title: 'x', state: 'done' }])
126
+ assert.deepEqual(summary, { text: 'MAW', tone: 'neutral', tooltip: 'Orca Multiagent Kit: ningún agente activo' })
127
+ })
128
+
129
+ test('cuenta por estado, en singular y plural, y avisa si hay bloqueados', () => {
130
+ const summary = summarizeAgents([
131
+ { workspaceId: 'a', title: 'U1', state: 'working' },
132
+ { workspaceId: 'b', title: 'U2', state: 'working' },
133
+ { workspaceId: 'c', title: 'U3', state: 'blocked' }
134
+ ])
135
+ assert.equal(summary.text, 'MAW · 2 trabajando · 1 bloqueado')
136
+ assert.equal(summary.tone, 'warning')
137
+ })
138
+
139
+ test('solo trabajando es accent', () => {
140
+ assert.equal(summarizeAgents([{ workspaceId: null, title: null, state: 'working' }]).tone, 'accent')
141
+ })
142
+ })
143
+
144
+ describe('describeAgents', () => {
145
+ test('una línea por agente activo', () => {
146
+ assert.equal(
147
+ describeAgents([
148
+ { workspaceId: null, title: 'U1 login', state: 'waiting' },
149
+ { workspaceId: null, title: null, state: 'blocked' },
150
+ { workspaceId: null, title: 'viejo', state: 'done' }
151
+ ]),
152
+ '- U1 login: esperando\n- agente sin título: bloqueado'
153
+ )
154
+ assert.equal(describeAgents([]), 'Ningún agente activo.')
155
+ })
156
+ })
157
+
158
+ describe('pollUntil', () => {
159
+ const instant = { attempts: 3, delayMs: 10, sleep: async () => undefined }
160
+
161
+ test('para en cuanto la salida coincide', async () => {
162
+ let reads = 0
163
+ const found = await pollUntil(async () => [String(++reads)], (lines) => lines[0] === '2', instant)
164
+ assert.equal(found, true)
165
+ assert.equal(reads, 2)
166
+ })
167
+
168
+ test('se rinde tras el número de intentos', async () => {
169
+ let reads = 0
170
+ const found = await pollUntil(async () => [String(++reads)], () => false, instant)
171
+ assert.equal(found, false)
172
+ assert.equal(reads, 3)
173
+ })
174
+ })