orca-multiagent-kit 0.0.0-stage → 1.2.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 (73) hide show
  1. package/AI_INSTALL.md +49 -0
  2. package/CHANGELOG.md +79 -0
  3. package/GUIA.html +401 -0
  4. package/LICENSE +21 -0
  5. package/README.md +240 -2
  6. package/VERSION +1 -0
  7. package/bin/omk.js +175 -0
  8. package/bin/ui.js +165 -0
  9. package/core/AGENTS.md +80 -0
  10. package/docs/MANUAL.md +208 -0
  11. package/install.sh +403 -0
  12. package/output-styles/csr-minimal.md +14 -0
  13. package/package.json +23 -4
  14. package/rules/00-router.md +28 -0
  15. package/rules/10-communication.md +58 -0
  16. package/rules/20-clean-code.md +59 -0
  17. package/rules/30-security.md +81 -0
  18. package/rules/31-security-audit.md +58 -0
  19. package/rules/40-testing.md +48 -0
  20. package/rules/50-done-gate.md +66 -0
  21. package/rules/60-git-workflow.md +49 -0
  22. package/rules/70-performance.md +36 -0
  23. package/rules/75-reliability.md +36 -0
  24. package/rules/80-supply-chain.md +35 -0
  25. package/rules/90-docs-comments.md +36 -0
  26. package/rules/95-multi-agent.md +56 -0
  27. package/rules/lang/cpp.md +26 -0
  28. package/rules/lang/csharp.md +27 -0
  29. package/rules/lang/dart-flutter.md +26 -0
  30. package/rules/lang/go.md +30 -0
  31. package/rules/lang/infra.md +33 -0
  32. package/rules/lang/java.md +29 -0
  33. package/rules/lang/kotlin.md +25 -0
  34. package/rules/lang/php.md +27 -0
  35. package/rules/lang/python.md +33 -0
  36. package/rules/lang/react.md +32 -0
  37. package/rules/lang/ruby.md +23 -0
  38. package/rules/lang/rust.md +32 -0
  39. package/rules/lang/shell.md +24 -0
  40. package/rules/lang/sql.md +29 -0
  41. package/rules/lang/swift.md +31 -0
  42. package/rules/lang/typescript.md +32 -0
  43. package/rules/lang/web.md +31 -0
  44. package/skills/csr-audit/SKILL.md +14 -0
  45. package/skills/csr-gate/SKILL.md +16 -0
  46. package/skills/csr-stack/SKILL.md +23 -0
  47. package/skills/kit-init/SKILL.md +61 -0
  48. package/skills/orca/SKILL.md +88 -0
  49. package/skills/orca/references/adapters/artifact.md +32 -0
  50. package/skills/orca/references/adapters/chat.md +33 -0
  51. package/skills/orca/references/adapters/native-plan.md +18 -0
  52. package/skills/orca/references/adapters/plan-file.md +20 -0
  53. package/skills/orca/references/adapters/speckit.md +42 -0
  54. package/skills/orca/references/engine-manual.md +30 -0
  55. package/skills/orca/references/engine-orca.md +36 -0
  56. package/skills/orca/references/engine-subagents.md +19 -0
  57. package/skills/orca/references/integrate.md +37 -0
  58. package/skills/orca/references/plan.md +48 -0
  59. package/skills/orca/references/race.md +35 -0
  60. package/skills/orca/references/setup.md +26 -0
  61. package/skills/orca/references/units.md +44 -0
  62. package/skills/orca/references/worker-contract.md +49 -0
  63. package/skills/speckit-orca-implement/SKILL.md +17 -0
  64. package/speckit-extension/orca/README.md +15 -0
  65. package/speckit-extension/orca/commands/implement.md +16 -0
  66. package/speckit-extension/orca/extension.yml +26 -0
  67. package/templates/.worktreeinclude +4 -0
  68. package/templates/AGENTS.md +13 -0
  69. package/templates/CLAUDE.md +4 -0
  70. package/templates/ORCHESTRATION.md +49 -0
  71. package/templates/STACK.md +91 -0
  72. package/templates/claude-settings.json +27 -0
  73. package/templates/orca.yaml +5 -0
package/README.md CHANGED
@@ -1,3 +1,241 @@
1
- # Temporary Holding Version
1
+ <div align="center">
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
3
+ <a href="https://fernandobaqueroo.github.io/orca-multiagent-kit/"><img src="assets/banner.svg" alt="MULTIAGENT_KIT — Orca · CSR + MAW: una fuente de reglas y skills para Claude, Gemini, Codex, Copilot y Cursor" width="100%"></a>
4
+
5
+ <sub>Pulsa el banner para abrir la versión interactiva.</sub>
6
+
7
+ # Orca Multiagent Kit
8
+
9
+ **Una sola fuente de reglas y skills para todos tus agentes de programación.<br>Calidad profesional en cada tarea, y varios agentes trabajando en paralelo sin pisarse.**
10
+
11
+ [![Release](https://img.shields.io/github/v/release/FernandoBaqueroo/orca-multiagent-kit?style=for-the-badge&labelColor=050605&color=c6ff3d&label=release)](https://github.com/FernandoBaqueroo/orca-multiagent-kit/releases/latest)
12
+ [![CI](https://img.shields.io/github/actions/workflow/status/FernandoBaqueroo/orca-multiagent-kit/ci.yml?branch=main&style=for-the-badge&labelColor=050605&color=9be22d&label=CI)](https://github.com/FernandoBaqueroo/orca-multiagent-kit/actions/workflows/ci.yml)
13
+ [![Licencia MIT](https://img.shields.io/badge/licencia-MIT-e4ff8f?style=for-the-badge&labelColor=050605)](LICENSE)
14
+ [![Descargas](https://img.shields.io/github/downloads/FernandoBaqueroo/orca-multiagent-kit/total?style=for-the-badge&labelColor=050605&color=5c8a12&label=descargas)](https://github.com/FernandoBaqueroo/orca-multiagent-kit/releases)
15
+
16
+ ![Claude Code](https://img.shields.io/badge/Claude_Code-050605?style=flat-square&logo=anthropic&logoColor=c6ff3d)
17
+ ![Antigravity](https://img.shields.io/badge/Antigravity-050605?style=flat-square&logo=googlegemini&logoColor=c6ff3d)
18
+ ![Codex](https://img.shields.io/badge/Codex-050605?style=flat-square&logo=openai&logoColor=c6ff3d)
19
+ ![Copilot CLI](https://img.shields.io/badge/Copilot_CLI-050605?style=flat-square&logo=githubcopilot&logoColor=c6ff3d)
20
+ ![Cursor](https://img.shields.io/badge/Cursor-050605?style=flat-square&logo=cursor&logoColor=c6ff3d)
21
+ ![Node](https://img.shields.io/badge/node-%E2%89%A518-050605?style=flat-square&logo=nodedotjs&logoColor=c6ff3d)
22
+ ![Bash](https://img.shields.io/badge/bash-%E2%89%A53.2-050605?style=flat-square&logo=gnubash&logoColor=c6ff3d)
23
+
24
+ [![npm](https://img.shields.io/npm/v/orca-multiagent-kit?style=for-the-badge&labelColor=050605&color=c6ff3d&logo=npm&logoColor=c6ff3d&label=npm)](https://www.npmjs.com/package/orca-multiagent-kit)
25
+
26
+ [**Descargar ZIP**](https://github.com/FernandoBaqueroo/orca-multiagent-kit/releases/latest/download/orca-multiagent-kit.zip) · [Web interactiva](https://fernandobaqueroo.github.io/orca-multiagent-kit/) · [Guía visual](https://fernandobaqueroo.github.io/orca-multiagent-kit/guia.html) · [Manual](docs/MANUAL.md) · [Changelog](CHANGELOG.md)
27
+
28
+ </div>
29
+
30
+ ```bash
31
+ npx orca-multiagent-kit install
32
+ ```
33
+
34
+ ---
35
+
36
+ ## Índice
37
+
38
+ - [Qué es](#que-es)
39
+ - [Instalar](#instalar)
40
+ - [Comandos `omk`](#comandos)
41
+ - [Agentes soportados](#agentes)
42
+ - [Skills](#skills)
43
+ - [Flujo de trabajo](#flujo)
44
+ - [Estructura del repositorio](#estructura)
45
+ - [Documentación](#documentacion)
46
+ - [Contribuir](#contribuir)
47
+ - [Autores](#autores)
48
+ - [Licencia](#licencia)
49
+
50
+ <a id="que-es"></a>
51
+ ## <img src="assets/icons/about.svg" width="22" height="22" alt=""> Qué es
52
+
53
+ **Orca Multiagent Kit** reúne en `~/.agents/` las reglas y skills de todos tus agentes de programación. Tiene dos partes:
54
+
55
+ | Parte | Qué aporta |
56
+ |:--|:--|
57
+ | **CSR — Claude Session Rules** | Código de calidad profesional, auditado en seguridad (OWASP Top 10 2025, ASVS 5.0, CWE Top 25) y con tests. Una puerta de validez en 8 fases y una tabla de gates al cerrar cada tarea. Respuestas mínimas: el agente gasta tokens en pensar, no en hablar. |
58
+ | **MAW — Multi-Agent Work** | Varios agentes a la vez sin pisarse, sin que tengas que coordinarlos. El agente detecta cuándo una tarea se puede repartir, la divide, lanza un agente por parte en su propio worktree ([Orca](https://www.onorca.dev), subagentes nativos o worktrees a mano) e integra el resultado. Con spec-kit, `/speckit.implement` lo hace solo. |
59
+
60
+ | Sin el kit | Con el kit |
61
+ |:--|:--|
62
+ | Una copia de las reglas por agente, que acaban divergiendo | **Una fuente**: cada agente importa o enlaza `~/.agents` |
63
+ | Claude cargaba todas las reglas en **cada mensaje** | Reglas **bajo demanda**; solo un núcleo de ~80 líneas está siempre cargado |
64
+ | Un agente, una tarea cada vez | Varios agentes en paralelo, con coordinador, informes e integración segura |
65
+
66
+ <a id="instalar"></a>
67
+ ## <img src="assets/icons/download.svg" width="22" height="22" alt=""> Instalar
68
+
69
+ Cuatro formas. Todas instalan lo mismo, hacen backup de lo que tocan y se deshacen con `omk restore`.
70
+
71
+ **1. npx** (Node ≥ 18, sin instalar nada global)
72
+ ```bash
73
+ npx orca-multiagent-kit install --dry-run # qué haría
74
+ npx orca-multiagent-kit install
75
+ ```
76
+
77
+ **2. npm global**: deja el comando `omk` disponible siempre
78
+ ```bash
79
+ npm install -g orca-multiagent-kit
80
+ omk install
81
+ ```
82
+
83
+ **3. curl** (sin Node)
84
+ ```bash
85
+ curl -fsSL https://raw.githubusercontent.com/FernandoBaqueroo/orca-multiagent-kit/main/scripts/get.sh | bash
86
+ ```
87
+
88
+ **4. ZIP**
89
+ ```bash
90
+ curl -LO https://github.com/FernandoBaqueroo/orca-multiagent-kit/releases/latest/download/orca-multiagent-kit.zip
91
+ unzip orca-multiagent-kit.zip && cd orca-multiagent-kit
92
+ ./install.sh --dry-run && ./install.sh
93
+ ```
94
+ Cada [release](https://github.com/FernandoBaqueroo/orca-multiagent-kit/releases) publica `orca-multiagent-kit-vX.Y.Z.zip` y `SHA256SUMS`. Para comprobar la integridad: `shasum -a 256 -c SHA256SUMS`.
95
+
96
+ Después, reinicia tus agentes y escribe en cada proyecto **«inicializa el proyecto»**. La skill `kit-init` detecta el stack leyendo el repo, crea `AGENTS.md`, `STACK.md` y `ORCHESTRATION.md`, y te hace como mucho 4 preguntas.
97
+
98
+ Requisitos: macOS, Linux, WSL o Git Bash, con bash ≥ 3.2.
99
+
100
+ <a id="comandos"></a>
101
+ ## <img src="assets/icons/cli.svg" width="22" height="22" alt=""> Comandos `omk`
102
+
103
+ | Comando | Qué hace |
104
+ |:--|:--|
105
+ | `omk install [--agents a,b] [--dry-run]` | Instala o migra la fuente única para los agentes detectados |
106
+ | `omk init [ruta]` | Prepara un proyecto (por defecto, la carpeta actual) |
107
+ | `omk verify` | Comprueba enlaces, imports y que no queden copias divergentes |
108
+ | `omk adopt <carpeta-skill>` | Comparte una skill externa (p. ej. impeccable) con todos los agentes |
109
+ | `omk backups` | Lista las copias de seguridad |
110
+ | `omk restore <fecha>` | Deshace una instalación |
111
+ | `omk update` | Actualiza a la última versión y reinstala |
112
+ | `omk where` · `omk version` · `omk help` | Rutas, versión y ayuda |
113
+
114
+ Sin Node, cada comando tiene su equivalente en `./install.sh` (`--verify`, `--project`, `--adopt`, `--restore`, `--dry-run`).
115
+
116
+ <a id="agentes"></a>
117
+ ## <img src="assets/icons/agents.svg" width="22" height="22" alt=""> Agentes soportados
118
+
119
+ | Agente | Reglas globales | Skills | Estado |
120
+ |:--|:--|:--|:--|
121
+ | ![](https://img.shields.io/badge/-Claude_Code-050605?style=flat-square&logo=anthropic&logoColor=c6ff3d) | `@~/.agents/AGENTS.md` importado en `~/.claude/CLAUDE.md` | enlaces en `~/.claude/skills` | soportado |
122
+ | ![](https://img.shields.io/badge/-Antigravity-050605?style=flat-square&logo=googlegemini&logoColor=c6ff3d) | `~/.gemini/GEMINI.md` → enlace | enlaces en `~/.gemini/config/skills` | soportado |
123
+ | ![](https://img.shields.io/badge/-Codex-050605?style=flat-square&logo=openai&logoColor=c6ff3d) | `~/.codex/AGENTS.md` → enlace | nativo en `~/.agents/skills` | soportado |
124
+ | ![](https://img.shields.io/badge/-Copilot_CLI-050605?style=flat-square&logo=githubcopilot&logoColor=c6ff3d) | `~/.copilot/copilot-instructions.md` → enlace | nativo en `~/.agents/skills` | soportado |
125
+ | ![](https://img.shields.io/badge/-Cursor-050605?style=flat-square&logo=cursor&logoColor=c6ff3d) | una línea en *Settings → Rules* (no usa ficheros) | nativo en `~/.agents/skills` | soportado |
126
+ | ![](https://img.shields.io/badge/-Devin_CLI-050605?style=flat-square) | `~/.config/devin/AGENTS.md` → enlace | — | opcional (`--agents devin`) |
127
+
128
+ En cada proyecto, las reglas van en `AGENTS.md`, que leen todos los agentes. `CLAUDE.md` solo contiene `@AGENTS.md`.
129
+
130
+ <a id="skills"></a>
131
+ ## <img src="assets/icons/skills.svg" width="22" height="22" alt=""> Skills
132
+
133
+ Solo tienes que conocer dos frases. El resto lo deciden los agentes.
134
+
135
+ | Skill | Cuándo se usa | Cómo |
136
+ |:--|:--|:--|
137
+ | `kit-init` | Proyecto nuevo, o con reglas antiguas | «inicializa el proyecto» |
138
+ | `orca` | Tareas con varias partes independientes: user stories, sprints, módulos, pantallas | **Sola**, por iniciativa del agente. O «hazlo en paralelo», «carrera entre Claude y Gemini», «planifica en sprints» |
139
+ | `speckit-orca-implement` | Hook de spec-kit: decide si `/speckit.implement` se reparte | **Automática** al escribir `/speckit.implement` |
140
+ | `csr-stack` · `csr-gate` · `csr-audit` | Ficha del stack, puerta de validez, auditoría de seguridad | Automáticas al cerrar tareas, o «pasa los gates» / «audita» |
141
+
142
+ **Autonomía** (en `ORCHESTRATION.md`): `semi` por defecto. Confirmas el plan de rondas y el merge final, y nada más salvo decisiones de producto. `manual` pide confirmación en cada ronda; `auto`, solo el merge final. En ningún nivel se mergea a la rama por defecto ni se hace push sin tu confirmación.
143
+
144
+ Convive con skills externas como **impeccable**, **supabase**, **spec-kit** y las de la app **Orca**: cada una manda en su terreno, y la puerta de validez y las prohibiciones se aplican siempre.
145
+
146
+ <a id="flujo"></a>
147
+ ## <img src="assets/icons/flow.svg" width="22" height="22" alt=""> Flujo de trabajo
148
+
149
+ **Con spec-kit** haces tus specs como siempre. Al implementar, el kit reparte el trabajo solo:
150
+
151
+ ```mermaid
152
+ %%{init: {"theme":"base","themeVariables":{"primaryColor":"#0b0e0a","primaryTextColor":"#e8f0e2","primaryBorderColor":"#c6ff3d","lineColor":"#9be22d","secondaryColor":"#22330a","tertiaryColor":"#050605","fontFamily":"monospace"}}}%%
153
+ flowchart LR
154
+ S["/speckit.specify → plan → tasks"] --> IMP["/speckit.implement"]
155
+ IMP --> H{"hook orca<br/>¿compensa?"}
156
+ H -- "no" --> SEQ["implement normal<br/>un agente"]
157
+ H -- "sí" --> OK1(["tú: plan de rondas"])
158
+ OK1 --> U0["U0 · base común"]
159
+ U0 --> W1["US1 · Claude Code"] & W2["US2 · Antigravity"] & W3["US3 · Codex"]
160
+ W1 & W2 & W3 --> INT["integración<br/>revisión · gates · [x] en tasks.md"]
161
+ INT --> OK2(["tú: merge final"])
162
+ ```
163
+
164
+ **Sin spec-kit** es lo mismo: pide la tarea con normalidad («añade el módulo de notificaciones») y, si tiene partes independientes, el agente propone el reparto. Un plan por sprints, un plan del modo plan de Claude o de Antigravity, o un mockup sirven igual de entrada.
165
+
166
+ **Las reglas que nunca se rompen:**
167
+ - Una unidad = un worktree = una rama.
168
+ - Los ficheros compartidos los toca una sola unidad por ronda.
169
+ - Los workers no editan `tasks.md`, planes ni `STACK.md`, y no hacen merge.
170
+ - Sin informe no hay unidad.
171
+ - Nunca `PASS` de algo no ejecutado.
172
+ - Lo pequeño no se orquesta.
173
+
174
+ <a id="estructura"></a>
175
+ ## <img src="assets/icons/folder.svg" width="22" height="22" alt=""> Estructura del repositorio
176
+
177
+ ```text
178
+ orca-multiagent-kit/
179
+ ├── bin/omk.js CLI omk (npm / npx), sin dependencias
180
+ ├── core/AGENTS.md núcleo siempre cargado (~80 líneas)
181
+ ├── rules/ 00-router … 95-multi-agent + lang/ (17 lenguajes)
182
+ ├── skills/ kit-init · orca · speckit-orca-implement · csr-*
183
+ ├── speckit-extension/ extensión de spec-kit (hook before_implement)
184
+ ├── templates/ AGENTS.md · CLAUDE.md · STACK.md · ORCHESTRATION.md · orca.yaml · .worktreeinclude
185
+ ├── output-styles/ csr-minimal (Claude Code)
186
+ ├── install.sh instala · migra · verifica · restaura · adopta
187
+ ├── GUIA.html guía visual del flujo
188
+ ├── site/ web interactiva (GitHub Pages)
189
+ ├── docs/MANUAL.md manual completo
190
+ ├── AI_INSTALL.md instrucciones para que una IA lo instale
191
+ ├── tests/ pruebas del instalador y del CLI en un $HOME desechable
192
+ ├── scripts/ check.sh · build-release.sh · get.sh · banner.py
193
+ └── .github/ CI (Linux + macOS), releases con zip, web, plantillas de issues y PR
194
+ ```
195
+
196
+ <a id="documentacion"></a>
197
+ ## <img src="assets/icons/docs.svg" width="22" height="22" alt=""> Documentación
198
+
199
+ | Documento | Para quién |
200
+ |:--|:--|
201
+ | [Web interactiva](https://fernandobaqueroo.github.io/orca-multiagent-kit/) | Presentación, instalación y comandos |
202
+ | [Guía visual](https://fernandobaqueroo.github.io/orca-multiagent-kit/guia.html) ([`GUIA.html`](GUIA.html)) | El flujo de trabajo completo, con esquemas |
203
+ | [`docs/MANUAL.md`](docs/MANUAL.md) | Instalación detallada, migración, convivencia y problemas frecuentes |
204
+ | [`AI_INSTALL.md`](AI_INSTALL.md) | Una IA que tiene que instalar o integrar el kit |
205
+ | [`CHANGELOG.md`](CHANGELOG.md) | Historial de versiones ([SemVer](https://semver.org/lang/es/)) |
206
+
207
+ <a id="contribuir"></a>
208
+ ## <img src="assets/icons/merge.svg" width="22" height="22" alt=""> Contribuir
209
+
210
+ Las contribuciones son bienvenidas. Lee [`CONTRIBUTING.md`](CONTRIBUTING.md): principios, cómo añadir skills o reglas, versionado y releases. Antes de abrir un PR:
211
+
212
+ ```bash
213
+ npm test # check.sh + pruebas del instalador + pruebas del CLI
214
+ ```
215
+
216
+ [Código de conducta](CODE_OF_CONDUCT.md) · [Seguridad](SECURITY.md) · [Soporte](SUPPORT.md)
217
+
218
+ <a id="autores"></a>
219
+ ## <img src="assets/icons/authors.svg" width="22" height="22" alt=""> Autores
220
+
221
+ <table>
222
+ <tr>
223
+ <td align="center" width="50%" valign="top">
224
+ <a href="https://github.com/Necro-Coder"><img src="https://github.com/Necro-Coder.png?size=160" width="100" alt="Necro-Coder"><br><b>Necro-Coder</b></a><br>
225
+ <sub>Autor de <b>CSR — Claude Session Rules</b></sub>
226
+ <p align="left"><sub>Diseñó la base de calidad del kit: el protocolo de respuesta de consumo mínimo, la carga progresiva de reglas, la puerta de validez en 8 fases, los módulos de clean code, seguridad (OWASP, ASVS, CWE), testing, rendimiento, fiabilidad y cadena de suministro, las 17 guías por lenguaje y las skills <code>csr-stack</code>, <code>csr-gate</code> y <code>csr-audit</code>.</sub></p>
227
+ </td>
228
+ <td align="center" width="50%" valign="top">
229
+ <a href="https://github.com/FernandoBaqueroo"><img src="https://github.com/FernandoBaqueroo.png?size=160" width="100" alt="Fernando Baquero"><br><b>Fernando Baquero</b></a><br>
230
+ <sub>Autor de <b>Orca Multiagent Kit</b> y <b>MAW — Multi-Agent Work</b></sub>
231
+ <p align="left"><sub>Convirtió CSR en una fuente única para varios proveedores (Claude Code, Antigravity, Codex, Copilot, Cursor y Devin). Creó la capa de orquestación multiagente (unidades de trabajo, worktrees, Orca y spec-kit), <code>kit-init</code>, el CLI <code>omk</code>, el instalador con migración, verificación y restauración, y la guía visual.</sub></p>
232
+ </td>
233
+ </tr>
234
+ </table>
235
+
236
+ <a id="licencia"></a>
237
+ ## <img src="assets/icons/license.svg" width="22" height="22" alt=""> Licencia
238
+
239
+ [MIT](LICENSE) © 2026 Fernando Baquero y Necro-Coder.
240
+
241
+ Las marcas Claude, Gemini/Antigravity, Codex/OpenAI, GitHub Copilot, Cursor y Orca pertenecen a sus respectivos propietarios. Se usan solo para indicar compatibilidad; este proyecto no está afiliado a ninguno de ellos.
package/VERSION ADDED
@@ -0,0 +1 @@
1
+ 1.2.0
package/bin/omk.js ADDED
@@ -0,0 +1,175 @@
1
+ #!/usr/bin/env node
2
+ // omk — CLI de Orca Multiagent Kit. Sin dependencias: envuelve install.sh con comandos cortos.
3
+ 'use strict';
4
+
5
+ const { spawn, spawnSync } = require('node:child_process');
6
+ const fs = require('node:fs');
7
+ const os = require('node:os');
8
+ const path = require('node:path');
9
+
10
+ const KIT = path.resolve(__dirname, '..');
11
+ const VERSION = fs.readFileSync(path.join(KIT, 'VERSION'), 'utf8').trim();
12
+ const REPO = 'orca-multiagent-kit';
13
+ const AGENTS_HOME = process.env.AGENT_KIT_HOME || path.join(os.homedir(), '.agents');
14
+
15
+ const color = process.stdout.isTTY && !process.env.NO_COLOR;
16
+ const lime = (s) => (color ? `\x1b[38;5;154m${s}\x1b[0m` : s);
17
+ const dim = (s) => (color ? `\x1b[2m${s}\x1b[0m` : s);
18
+ const bold = (s) => (color ? `\x1b[1m${s}\x1b[0m` : s);
19
+
20
+ const HELP = `
21
+ ${lime(bold('omk'))} ${dim('v' + VERSION)} — Orca Multiagent Kit
22
+
23
+ ${bold('Uso')}
24
+ omk <comando> [opciones]
25
+
26
+ ${bold('Comandos')}
27
+ ${lime('install')} [--agents a,b] [--dry-run] Instala o migra la fuente única en ~/.agents
28
+ ${lime('init')} [ruta] Prepara un proyecto (por defecto, la carpeta actual)
29
+ ${lime('verify')} Comprueba enlaces, imports y copias divergentes
30
+ ${lime('adopt')} <carpeta-skill> Comparte una skill externa con todos los agentes
31
+ ${lime('backups')} Lista las copias de seguridad
32
+ ${lime('restore')} <fecha> Deshace una instalación (fecha de "omk backups")
33
+ ${lime('update')} Actualiza a la última versión de npm y reinstala
34
+ ${lime('where')} Muestra dónde está cada cosa
35
+ ${lime('version')} Muestra la versión
36
+ ${lime('help')} Esta ayuda
37
+
38
+ ${bold('Agentes')} claude · antigravity · codex · copilot · cursor · devin (opcional)
39
+
40
+ ${bold('Ejemplos')}
41
+ npx orca-multiagent-kit install --dry-run
42
+ omk install
43
+ omk init ~/Dev/mi-app
44
+ omk adopt ~/.gemini/config/plugins/user-workflows/skills/impeccable
45
+ `;
46
+
47
+ function die(msg, code = 1) {
48
+ process.stderr.write(`omk: ${msg}\n`);
49
+ process.exit(code);
50
+ }
51
+
52
+ function findBash() {
53
+ if (process.platform !== 'win32') return 'bash';
54
+ const candidates = [
55
+ process.env.OMK_BASH,
56
+ 'C:\\Program Files\\Git\\bin\\bash.exe',
57
+ 'C:\\Program Files (x86)\\Git\\bin\\bash.exe',
58
+ ].filter(Boolean);
59
+ for (const c of candidates) if (fs.existsSync(c)) return c;
60
+ const probe = spawnSync('bash', ['--version'], { stdio: 'ignore' });
61
+ if (probe.status === 0) return 'bash';
62
+ die('Windows necesita Git Bash o WSL. Instala Git for Windows o ejecuta omk desde WSL (o define OMK_BASH).');
63
+ }
64
+
65
+ function runInstaller(args) {
66
+ const child = spawn(findBash(), [path.join(KIT, 'install.sh'), ...args], {
67
+ stdio: ['inherit', 'pipe', 'pipe'],
68
+ env: { ...process.env, OMK_CLI: '1', OMK_EVENTS: '1' },
69
+ });
70
+ child.on('error', (e) => die(e.message));
71
+ // Ctrl+C: deja la terminal limpia (sin el spinner a medias)
72
+ process.on('SIGINT', () => { process.stdout.write('\r\x1b[2K'); child.kill('SIGINT'); process.exit(130); });
73
+ require('./ui').render(child).then((code) => process.exit(code));
74
+ }
75
+
76
+ function listBackups() {
77
+ const dir = path.join(AGENTS_HOME, 'backups');
78
+ if (!fs.existsSync(dir)) return [];
79
+ return fs.readdirSync(dir).filter((d) => /^\d{8}-\d{6}$/.test(d)).sort();
80
+ }
81
+
82
+ const [cmd = 'help', ...rest] = process.argv.slice(2);
83
+
84
+ switch (cmd) {
85
+ case 'install':
86
+ case 'i':
87
+ runInstaller(rest);
88
+ break;
89
+
90
+ case 'init': {
91
+ const target = path.resolve(rest[0] || process.cwd());
92
+ if (!fs.existsSync(target)) die(`no existe la carpeta ${target}`);
93
+ runInstaller(['--project-only', target, ...rest.slice(1)]);
94
+ break;
95
+ }
96
+
97
+ case 'verify':
98
+ case 'doctor':
99
+ runInstaller(['--verify', ...rest]);
100
+ break;
101
+
102
+ case 'adopt':
103
+ if (!rest[0]) die('falta la carpeta de la skill: omk adopt <carpeta>');
104
+ runInstaller(['--adopt', path.resolve(rest[0])]);
105
+ break;
106
+
107
+ case 'backups': {
108
+ const b = listBackups();
109
+ if (!b.length) { console.log('No hay copias de seguridad en ' + path.join(AGENTS_HOME, 'backups')); break; }
110
+ for (const d of b) console.log(d.replace(/^(\d{4})(\d{2})(\d{2})-(\d{2})(\d{2})(\d{2})$/, `$& ${dim('$3/$2/$1 $4:$5:$6')}`));
111
+ console.log(dim(`\nDeshacer: omk restore ${b[0]} (la más antigua es el estado previo a la primera instalación)`));
112
+ break;
113
+ }
114
+
115
+ case 'restore':
116
+ if (!rest[0]) die('falta la fecha: omk restore <fecha> (consulta "omk backups")');
117
+ runInstaller(['--restore', rest[0]]);
118
+ break;
119
+
120
+ case 'update': {
121
+ const npm = process.platform === 'win32' ? 'npm.cmd' : 'npm';
122
+ const sh = { encoding: 'utf8', shell: process.platform === 'win32' };
123
+ const latest = (spawnSync(npm, ['view', REPO, 'version'], sh).stdout || '').trim();
124
+ if (!latest) die('no se pudo consultar npm. ¿Hay conexión?');
125
+ if (latest === VERSION && !rest.includes('--force')) {
126
+ console.log(`${lime('✓')} Ya tienes la última versión (${VERSION}). Reaplicando la instalación…`);
127
+ } else {
128
+ console.log(`${lime('›')} Actualizando ${dim(VERSION)} → ${lime(latest)}`);
129
+ const prefix = (spawnSync(npm, ['prefix', '-g'], sh).stdout || '').trim();
130
+ const libdir = process.platform === 'win32' ? prefix : path.join(prefix, 'lib', 'node_modules');
131
+ let writable = true;
132
+ try {
133
+ fs.accessSync(libdir, fs.constants.W_OK);
134
+ if (fs.existsSync(path.join(libdir, REPO))) fs.accessSync(path.join(libdir, REPO), fs.constants.W_OK);
135
+ } catch { writable = false; }
136
+ if (!writable) {
137
+ die(`no tienes permiso para escribir en ${libdir} (instalaste omk con sudo o Node está en una carpeta del sistema).
138
+
139
+ Rápido: sudo npm i -g ${REPO}@latest && omk install
140
+ Recomendado: que npm instale en tu carpeta de usuario, una sola vez:
141
+ mkdir -p ~/.npm-global && npm config set prefix ~/.npm-global
142
+ echo 'export PATH="$HOME/.npm-global/bin:$PATH"' >> ~/.zshrc && source ~/.zshrc
143
+ sudo npm rm -g ${REPO} && npm i -g ${REPO}`);
144
+ }
145
+ const u = spawnSync(npm, ['install', '-g', `${REPO}@latest`], { stdio: 'inherit', shell: sh.shell });
146
+ if (u.status !== 0) die('no se pudo actualizar con npm. Prueba: npx ' + REPO + '@latest install');
147
+ }
148
+ const r = spawnSync('omk', ['install', ...rest.filter((a) => a !== '--force')], { stdio: 'inherit', shell: process.platform === 'win32' });
149
+ process.exit(r.status === null ? 1 : r.status);
150
+ }
151
+
152
+ case 'where':
153
+ console.log(`${bold('kit')} ${KIT}`);
154
+ console.log(`${bold('fuente')} ${AGENTS_HOME}`);
155
+ console.log(`${bold('núcleo')} ${path.join(AGENTS_HOME, 'AGENTS.md')}`);
156
+ console.log(`${bold('reglas')} ${path.join(AGENTS_HOME, 'rules')}`);
157
+ console.log(`${bold('skills')} ${path.join(AGENTS_HOME, 'skills')}`);
158
+ console.log(`${bold('backups')} ${path.join(AGENTS_HOME, 'backups')}`);
159
+ break;
160
+
161
+ case 'version':
162
+ case '-v':
163
+ case '--version':
164
+ console.log(VERSION);
165
+ break;
166
+
167
+ case 'help':
168
+ case '-h':
169
+ case '--help':
170
+ console.log(HELP);
171
+ break;
172
+
173
+ default:
174
+ die(`comando desconocido: ${cmd}\n${HELP}`, 2);
175
+ }
package/bin/ui.js ADDED
@@ -0,0 +1,165 @@
1
+ // Render de la salida de install.sh para omk: spinner por fase, color y resumen final.
2
+ // install.sh emite (con OMK_EVENTS=1) líneas «::tipo::campo::campo»; lo demás se muestra tal cual.
3
+ 'use strict';
4
+
5
+ const readline = require('node:readline');
6
+
7
+ const tty = Boolean(process.stdout.isTTY) && !process.env.NO_COLOR && process.env.TERM !== 'dumb';
8
+ const truecolor = /truecolor|24bit/i.test(process.env.COLORTERM || '');
9
+ const paint = (code) => (s) => (tty ? `\x1b[${code}m${s}\x1b[0m` : String(s));
10
+ const c = {
11
+ lime: paint(truecolor ? '38;2;198;255;61' : '38;5;154'),
12
+ limeDk: paint(truecolor ? '38;2;92;138;18' : '38;5;64'),
13
+ grey: paint(truecolor ? '38;2;139;147;132' : '38;5;245'),
14
+ amber: paint(truecolor ? '38;2;255;210;90' : '38;5;221'),
15
+ red: paint(truecolor ? '38;2;255;107;107' : '38;5;203'),
16
+ bold: paint('1'),
17
+ dim: paint('2'),
18
+ };
19
+ const sym = {
20
+ ok: c.lime('✓'), fail: c.red('✗'), warn: c.amber('!'), add: c.lime('+'), keep: c.grey('='), dry: c.amber('~'),
21
+ todo: c.amber('›'), info: c.grey('·'), dot: c.grey('·'),
22
+ };
23
+ const FRAMES = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
24
+ const MIN_PHASE_MS = 160; // que cada fase se vea, aunque tarde menos
25
+ const cols = () => Math.max(50, Math.min(process.stdout.columns || 80, 110));
26
+ const out = (s = '') => process.stdout.write(s + '\n');
27
+
28
+ const vis = (s) => s.replace(/\x1b\[[0-9;]*m/g, '');
29
+
30
+ // Corta una línea larga en varias con sangría colgante.
31
+ function wrap(text, first, rest) {
32
+ const width = cols() - rest.length - 1;
33
+ const words = text.split(' ');
34
+ const lines = [];
35
+ let line = '';
36
+ for (const w of words) {
37
+ if (line && vis(line + ' ' + w).length > width) { lines.push(line); line = w; } else line = line ? line + ' ' + w : w;
38
+ }
39
+ if (line) lines.push(line);
40
+ return lines.map((l, i) => (i === 0 ? first : rest) + l).join('\n');
41
+ }
42
+
43
+ // Separa «Agente: texto» para resaltar el agente.
44
+ function lead(text) {
45
+ const m = /^([^:]{2,40}):\s(.*)$/.exec(text);
46
+ return m ? `${c.bold(m[1])}${c.dim(':')} ${m[2]}` : text;
47
+ }
48
+
49
+ function header(title, sub) {
50
+ const [name, ver] = title.split(/ (?=v\d)/);
51
+ out();
52
+ out(` ${c.lime('◆')} ${c.bold(c.lime(name.toUpperCase()))}${ver ? ' ' + c.grey(ver) : ''}`);
53
+ if (sub) out(` ${c.grey(sub)}`);
54
+ out();
55
+ }
56
+
57
+ function section(label, color, items, mark) {
58
+ out();
59
+ out(` ${color(c.bold(label))} ${c.grey('(' + items.length + ')')}`);
60
+ for (const t of items) out(wrap(lead(t), ` ${mark} `, ' '));
61
+ }
62
+
63
+ function footer(kind, stamp, dry, todos, infos, started) {
64
+ if (todos.length) section('Pendiente', c.amber, todos, sym.todo);
65
+ if (infos.length) section('Para tu información', c.grey, infos, sym.info);
66
+ out();
67
+ if (dry === '1') { out(` ${c.amber('Simulación:')} no se ha escrito nada. Para aplicarlo, quita ${c.bold('--dry-run')}.`); out(); return; }
68
+ const secs = ((Date.now() - started) / 1000).toFixed(1);
69
+ const rows = [];
70
+ if (kind === 'restore') { out(` ${sym.ok} ${c.bold('Restaurado')} ${c.grey('en ' + secs + ' s')}`); out(); return; }
71
+ out(` ${sym.ok} ${c.bold(todos.length ? 'Hecho, con ' + todos.length + ' pendiente' + (todos.length > 1 ? 's' : '') : 'Hecho')} ${c.grey('en ' + secs + ' s')}`);
72
+ if (kind === 'global') {
73
+ rows.push(['comprobar', 'omk verify']);
74
+ rows.push(['proyectos', 'omk init ' + c.grey('(dentro de cada proyecto)')]);
75
+ } else {
76
+ rows.push(['siguiente', 'en el agente: «inicializa el proyecto»']);
77
+ }
78
+ if (stamp) rows.push(['deshacer', 'omk restore ' + stamp]);
79
+ for (const [k, v] of rows) out(` ${c.grey(k.padEnd(10))} ${c.lime(v)}`);
80
+ out();
81
+ }
82
+
83
+ /** Ejecuta install.sh dibujando sus eventos. Devuelve el código de salida. */
84
+ function render(child) {
85
+ const started = Date.now();
86
+ const queue = [];
87
+ let wake = null;
88
+ let closed = false;
89
+ let code = 0;
90
+ const push = (ev) => { queue.push(ev); if (wake) { wake(); wake = null; } };
91
+ const next = () => (queue.length ? Promise.resolve(queue.shift()) : closed ? Promise.resolve(null) : new Promise((r) => { wake = () => r(queue.shift() ?? null); }));
92
+
93
+ readline.createInterface({ input: child.stdout }).on('line', (l) => push({ src: 'out', l }));
94
+ readline.createInterface({ input: child.stderr }).on('line', (l) => push({ src: 'err', l }));
95
+ child.on('close', (status) => { code = status === null ? 1 : status; closed = true; if (wake) { wake(); wake = null; } });
96
+
97
+ const todos = [];
98
+ const infos = [];
99
+ let phase = null; // { label, items, since, timer, frame, warn }
100
+ let checks = { ok: 0, fail: 0 };
101
+
102
+ const spin = () => {
103
+ if (!tty || !phase) return;
104
+ phase.frame = (phase.frame + 1) % FRAMES.length;
105
+ process.stdout.write(`\r\x1b[2K ${c.lime(FRAMES[phase.frame])} ${phase.label}${c.grey('…')}`);
106
+ };
107
+ const startPhase = (label) => {
108
+ phase = { label, items: [], since: Date.now(), frame: 0, warn: false, timer: null };
109
+ if (tty) { spin(); phase.timer = setInterval(spin, 80); }
110
+ };
111
+ const endPhase = async (summary) => {
112
+ if (!phase) return;
113
+ const wait = MIN_PHASE_MS - (Date.now() - phase.since);
114
+ if (tty && wait > 0) await new Promise((r) => setTimeout(r, wait));
115
+ if (phase.timer) clearInterval(phase.timer);
116
+ if (tty) process.stdout.write('\r\x1b[2K');
117
+ const mark = phase.items.some((i) => i.kind === 'fail') ? sym.fail : phase.warn ? sym.warn : sym.ok;
118
+ const label = c.bold(phase.label);
119
+ const pad = Math.max(2, 30 - phase.label.length);
120
+ out(` ${mark} ${label}${summary ? ' '.repeat(pad) + c.grey(summary) : ''}`);
121
+ const dry = phase.items.filter((i) => i.kind === 'dry');
122
+ for (const i of phase.items.filter((x) => x.kind !== 'dry')) out(wrap(i.kind === 'keep' ? c.grey(i.text) : i.text, ` ${sym[i.kind] || sym.dot} `, ' '));
123
+ if (dry.length) {
124
+ for (const i of dry.slice(0, 4)) out(wrap(c.grey(i.text), ` ${sym.dry} `, ' '));
125
+ if (dry.length > 4) out(` ${c.grey('… y ' + (dry.length - 4) + ' acciones más')}`);
126
+ }
127
+ phase = null;
128
+ };
129
+
130
+ return (async () => {
131
+ for (;;) {
132
+ const ev = await next();
133
+ if (!ev) break;
134
+ if (ev.src === 'err') { if (phase && tty) process.stdout.write('\r\x1b[2K'); out(` ${c.red(ev.l)}`); continue; }
135
+ if (!ev.l.startsWith('::')) { if (ev.l.trim()) { if (phase && tty) process.stdout.write('\r\x1b[2K'); out(` ${c.grey('│ ' + ev.l)}`); } continue; }
136
+ const [type, ...f] = ev.l.slice(2).split('::');
137
+ switch (type) {
138
+ case 'title': header(f[0], f[1]); break;
139
+ case 'begin': await endPhase(); startPhase(f[0]); break;
140
+ case 'item': if (phase) { phase.items.push({ kind: f[0], text: f.slice(1).join('::') }); if (f[0] === 'warn') phase.warn = true; } break;
141
+ case 'end': await endPhase(f.join('::')); break;
142
+ case 'todo': todos.push(f.join('::')); break;
143
+ case 'info': infos.push(f.join('::')); break;
144
+ case 'check': {
145
+ const [k, ...t] = f;
146
+ checks[k === 'fail' ? 'fail' : 'ok'] += k === 'info' ? 0 : 1;
147
+ out(wrap(lead(t.join('::')), ` ${k === 'ok' ? sym.ok : k === 'fail' ? sym.fail : sym.info} `, ' '));
148
+ break;
149
+ }
150
+ case 'result':
151
+ out();
152
+ if (checks.fail === 0) out(` ${sym.ok} ${c.bold('Todo correcto')} ${c.grey(checks.ok + ' comprobaciones')}`);
153
+ else out(` ${sym.fail} ${c.bold(c.red(checks.fail + (checks.fail > 1 ? ' fallos' : ' fallo')))} ${c.grey('repáralos con')} ${c.lime('omk install')}`);
154
+ out();
155
+ break;
156
+ case 'footer': await endPhase(); footer(f[0], f[1], f[2], todos, infos, started); break;
157
+ default: break;
158
+ }
159
+ }
160
+ await endPhase();
161
+ return code;
162
+ })();
163
+ }
164
+
165
+ module.exports = { render, c, sym, tty };