orca-multiagent-kit 0.0.0-stage → 1.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/AI_INSTALL.md +49 -0
- package/CHANGELOG.md +56 -0
- package/GUIA.html +401 -0
- package/LICENSE +21 -0
- package/README.md +238 -2
- package/VERSION +1 -0
- package/bin/omk.js +147 -0
- package/core/AGENTS.md +80 -0
- package/docs/MANUAL.md +208 -0
- package/install.sh +297 -0
- package/output-styles/csr-minimal.md +14 -0
- package/package.json +23 -4
- package/rules/00-router.md +28 -0
- package/rules/10-communication.md +58 -0
- package/rules/20-clean-code.md +59 -0
- package/rules/30-security.md +81 -0
- package/rules/31-security-audit.md +58 -0
- package/rules/40-testing.md +48 -0
- package/rules/50-done-gate.md +66 -0
- package/rules/60-git-workflow.md +49 -0
- package/rules/70-performance.md +36 -0
- package/rules/75-reliability.md +36 -0
- package/rules/80-supply-chain.md +35 -0
- package/rules/90-docs-comments.md +36 -0
- package/rules/95-multi-agent.md +56 -0
- package/rules/lang/cpp.md +26 -0
- package/rules/lang/csharp.md +27 -0
- package/rules/lang/dart-flutter.md +26 -0
- package/rules/lang/go.md +30 -0
- package/rules/lang/infra.md +33 -0
- package/rules/lang/java.md +29 -0
- package/rules/lang/kotlin.md +25 -0
- package/rules/lang/php.md +27 -0
- package/rules/lang/python.md +33 -0
- package/rules/lang/react.md +32 -0
- package/rules/lang/ruby.md +23 -0
- package/rules/lang/rust.md +32 -0
- package/rules/lang/shell.md +24 -0
- package/rules/lang/sql.md +29 -0
- package/rules/lang/swift.md +31 -0
- package/rules/lang/typescript.md +32 -0
- package/rules/lang/web.md +31 -0
- package/skills/csr-audit/SKILL.md +14 -0
- package/skills/csr-gate/SKILL.md +16 -0
- package/skills/csr-stack/SKILL.md +23 -0
- package/skills/kit-init/SKILL.md +61 -0
- package/skills/orca/SKILL.md +88 -0
- package/skills/orca/references/adapters/artifact.md +32 -0
- package/skills/orca/references/adapters/chat.md +33 -0
- package/skills/orca/references/adapters/native-plan.md +18 -0
- package/skills/orca/references/adapters/plan-file.md +20 -0
- package/skills/orca/references/adapters/speckit.md +42 -0
- package/skills/orca/references/engine-manual.md +30 -0
- package/skills/orca/references/engine-orca.md +36 -0
- package/skills/orca/references/engine-subagents.md +19 -0
- package/skills/orca/references/integrate.md +37 -0
- package/skills/orca/references/plan.md +48 -0
- package/skills/orca/references/race.md +35 -0
- package/skills/orca/references/setup.md +26 -0
- package/skills/orca/references/units.md +44 -0
- package/skills/orca/references/worker-contract.md +49 -0
- package/skills/speckit-orca-implement/SKILL.md +17 -0
- package/speckit-extension/orca/README.md +15 -0
- package/speckit-extension/orca/commands/implement.md +16 -0
- package/speckit-extension/orca/extension.yml +26 -0
- package/templates/.worktreeinclude +4 -0
- package/templates/AGENTS.md +13 -0
- package/templates/CLAUDE.md +4 -0
- package/templates/ORCHESTRATION.md +49 -0
- package/templates/STACK.md +91 -0
- package/templates/claude-settings.json +27 -0
- package/templates/orca.yaml +5 -0
package/README.md
CHANGED
|
@@ -1,3 +1,239 @@
|
|
|
1
|
-
|
|
1
|
+
<div align="center">
|
|
2
2
|
|
|
3
|
-
|
|
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
|
+
[](https://github.com/FernandoBaqueroo/orca-multiagent-kit/releases/latest)
|
|
12
|
+
[](https://github.com/FernandoBaqueroo/orca-multiagent-kit/actions/workflows/ci.yml)
|
|
13
|
+
[](LICENSE)
|
|
14
|
+
[](https://github.com/FernandoBaqueroo/orca-multiagent-kit/releases)
|
|
15
|
+
|
|
16
|
+

|
|
17
|
+

|
|
18
|
+

|
|
19
|
+

|
|
20
|
+

|
|
21
|
+

|
|
22
|
+

|
|
23
|
+
|
|
24
|
+
[**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)
|
|
25
|
+
|
|
26
|
+
</div>
|
|
27
|
+
|
|
28
|
+
```bash
|
|
29
|
+
npx github:FernandoBaqueroo/orca-multiagent-kit install
|
|
30
|
+
```
|
|
31
|
+
|
|
32
|
+
---
|
|
33
|
+
|
|
34
|
+
## Índice
|
|
35
|
+
|
|
36
|
+
- [Qué es](#que-es)
|
|
37
|
+
- [Instalar](#instalar)
|
|
38
|
+
- [Comandos `omk`](#comandos)
|
|
39
|
+
- [Agentes soportados](#agentes)
|
|
40
|
+
- [Skills](#skills)
|
|
41
|
+
- [Flujo de trabajo](#flujo)
|
|
42
|
+
- [Estructura del repositorio](#estructura)
|
|
43
|
+
- [Documentación](#documentacion)
|
|
44
|
+
- [Contribuir](#contribuir)
|
|
45
|
+
- [Autores](#autores)
|
|
46
|
+
- [Licencia](#licencia)
|
|
47
|
+
|
|
48
|
+
<a id="que-es"></a>
|
|
49
|
+
## <img src="assets/icons/about.svg" width="22" height="22" alt=""> Qué es
|
|
50
|
+
|
|
51
|
+
**Orca Multiagent Kit** reúne en `~/.agents/` las reglas y skills de todos tus agentes de programación. Tiene dos partes:
|
|
52
|
+
|
|
53
|
+
| Parte | Qué aporta |
|
|
54
|
+
|:--|:--|
|
|
55
|
+
| **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. |
|
|
56
|
+
| **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. |
|
|
57
|
+
|
|
58
|
+
| Sin el kit | Con el kit |
|
|
59
|
+
|:--|:--|
|
|
60
|
+
| Una copia de las reglas por agente, que acaban divergiendo | **Una fuente**: cada agente importa o enlaza `~/.agents` |
|
|
61
|
+
| Claude cargaba todas las reglas en **cada mensaje** | Reglas **bajo demanda**; solo un núcleo de ~80 líneas está siempre cargado |
|
|
62
|
+
| Un agente, una tarea cada vez | Varios agentes en paralelo, con coordinador, informes e integración segura |
|
|
63
|
+
|
|
64
|
+
<a id="instalar"></a>
|
|
65
|
+
## <img src="assets/icons/download.svg" width="22" height="22" alt=""> Instalar
|
|
66
|
+
|
|
67
|
+
Cuatro formas. Todas instalan lo mismo, hacen backup de lo que tocan y se deshacen con `omk restore`.
|
|
68
|
+
|
|
69
|
+
**1. npx** (Node ≥ 18, sin instalar nada global)
|
|
70
|
+
```bash
|
|
71
|
+
npx github:FernandoBaqueroo/orca-multiagent-kit install --dry-run # qué haría
|
|
72
|
+
npx github:FernandoBaqueroo/orca-multiagent-kit install
|
|
73
|
+
```
|
|
74
|
+
|
|
75
|
+
**2. npm global**: deja el comando `omk` disponible siempre
|
|
76
|
+
```bash
|
|
77
|
+
npm install -g github:FernandoBaqueroo/orca-multiagent-kit
|
|
78
|
+
omk install
|
|
79
|
+
```
|
|
80
|
+
|
|
81
|
+
**3. curl** (sin Node)
|
|
82
|
+
```bash
|
|
83
|
+
curl -fsSL https://raw.githubusercontent.com/FernandoBaqueroo/orca-multiagent-kit/main/scripts/get.sh | bash
|
|
84
|
+
```
|
|
85
|
+
|
|
86
|
+
**4. ZIP**
|
|
87
|
+
```bash
|
|
88
|
+
curl -LO https://github.com/FernandoBaqueroo/orca-multiagent-kit/releases/latest/download/orca-multiagent-kit.zip
|
|
89
|
+
unzip orca-multiagent-kit.zip && cd orca-multiagent-kit
|
|
90
|
+
./install.sh --dry-run && ./install.sh
|
|
91
|
+
```
|
|
92
|
+
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`.
|
|
93
|
+
|
|
94
|
+
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.
|
|
95
|
+
|
|
96
|
+
Requisitos: macOS, Linux, WSL o Git Bash, con bash ≥ 3.2.
|
|
97
|
+
|
|
98
|
+
<a id="comandos"></a>
|
|
99
|
+
## <img src="assets/icons/cli.svg" width="22" height="22" alt=""> Comandos `omk`
|
|
100
|
+
|
|
101
|
+
| Comando | Qué hace |
|
|
102
|
+
|:--|:--|
|
|
103
|
+
| `omk install [--agents a,b] [--dry-run]` | Instala o migra la fuente única para los agentes detectados |
|
|
104
|
+
| `omk init [ruta]` | Prepara un proyecto (por defecto, la carpeta actual) |
|
|
105
|
+
| `omk verify` | Comprueba enlaces, imports y que no queden copias divergentes |
|
|
106
|
+
| `omk adopt <carpeta-skill>` | Comparte una skill externa (p. ej. impeccable) con todos los agentes |
|
|
107
|
+
| `omk backups` | Lista las copias de seguridad |
|
|
108
|
+
| `omk restore <fecha>` | Deshace una instalación |
|
|
109
|
+
| `omk update` | Actualiza a la última versión y reinstala |
|
|
110
|
+
| `omk where` · `omk version` · `omk help` | Rutas, versión y ayuda |
|
|
111
|
+
|
|
112
|
+
Sin Node, cada comando tiene su equivalente en `./install.sh` (`--verify`, `--project`, `--adopt`, `--restore`, `--dry-run`).
|
|
113
|
+
|
|
114
|
+
<a id="agentes"></a>
|
|
115
|
+
## <img src="assets/icons/agents.svg" width="22" height="22" alt=""> Agentes soportados
|
|
116
|
+
|
|
117
|
+
| Agente | Reglas globales | Skills | Estado |
|
|
118
|
+
|:--|:--|:--|:--|
|
|
119
|
+
|  | `@~/.agents/AGENTS.md` importado en `~/.claude/CLAUDE.md` | enlaces en `~/.claude/skills` | soportado |
|
|
120
|
+
|  | `~/.gemini/GEMINI.md` → enlace | enlaces en `~/.gemini/config/skills` | soportado |
|
|
121
|
+
|  | `~/.codex/AGENTS.md` → enlace | nativo en `~/.agents/skills` | soportado |
|
|
122
|
+
|  | `~/.copilot/copilot-instructions.md` → enlace | nativo en `~/.agents/skills` | soportado |
|
|
123
|
+
|  | una línea en *Settings → Rules* (no usa ficheros) | nativo en `~/.agents/skills` | soportado |
|
|
124
|
+
|  | `~/.config/devin/AGENTS.md` → enlace | — | opcional (`--agents devin`) |
|
|
125
|
+
|
|
126
|
+
En cada proyecto, las reglas van en `AGENTS.md`, que leen todos los agentes. `CLAUDE.md` solo contiene `@AGENTS.md`.
|
|
127
|
+
|
|
128
|
+
<a id="skills"></a>
|
|
129
|
+
## <img src="assets/icons/skills.svg" width="22" height="22" alt=""> Skills
|
|
130
|
+
|
|
131
|
+
Solo tienes que conocer dos frases. El resto lo deciden los agentes.
|
|
132
|
+
|
|
133
|
+
| Skill | Cuándo se usa | Cómo |
|
|
134
|
+
|:--|:--|:--|
|
|
135
|
+
| `kit-init` | Proyecto nuevo, o con reglas antiguas | «inicializa el proyecto» |
|
|
136
|
+
| `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» |
|
|
137
|
+
| `speckit-orca-implement` | Hook de spec-kit: decide si `/speckit.implement` se reparte | **Automática** al escribir `/speckit.implement` |
|
|
138
|
+
| `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» |
|
|
139
|
+
|
|
140
|
+
**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.
|
|
141
|
+
|
|
142
|
+
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.
|
|
143
|
+
|
|
144
|
+
<a id="flujo"></a>
|
|
145
|
+
## <img src="assets/icons/flow.svg" width="22" height="22" alt=""> Flujo de trabajo
|
|
146
|
+
|
|
147
|
+
**Con spec-kit** haces tus specs como siempre. Al implementar, el kit reparte el trabajo solo:
|
|
148
|
+
|
|
149
|
+
```mermaid
|
|
150
|
+
%%{init: {"theme":"base","themeVariables":{"primaryColor":"#0b0e0a","primaryTextColor":"#e8f0e2","primaryBorderColor":"#c6ff3d","lineColor":"#9be22d","secondaryColor":"#22330a","tertiaryColor":"#050605","fontFamily":"monospace"}}}%%
|
|
151
|
+
flowchart LR
|
|
152
|
+
S["/speckit.specify → plan → tasks"] --> IMP["/speckit.implement"]
|
|
153
|
+
IMP --> H{"hook orca<br/>¿compensa?"}
|
|
154
|
+
H -- "no" --> SEQ["implement normal<br/>un agente"]
|
|
155
|
+
H -- "sí" --> OK1(["tú: plan de rondas"])
|
|
156
|
+
OK1 --> U0["U0 · base común"]
|
|
157
|
+
U0 --> W1["US1 · Claude Code"] & W2["US2 · Antigravity"] & W3["US3 · Codex"]
|
|
158
|
+
W1 & W2 & W3 --> INT["integración<br/>revisión · gates · [x] en tasks.md"]
|
|
159
|
+
INT --> OK2(["tú: merge final"])
|
|
160
|
+
```
|
|
161
|
+
|
|
162
|
+
**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.
|
|
163
|
+
|
|
164
|
+
**Las reglas que nunca se rompen:**
|
|
165
|
+
- Una unidad = un worktree = una rama.
|
|
166
|
+
- Los ficheros compartidos los toca una sola unidad por ronda.
|
|
167
|
+
- Los workers no editan `tasks.md`, planes ni `STACK.md`, y no hacen merge.
|
|
168
|
+
- Sin informe no hay unidad.
|
|
169
|
+
- Nunca `PASS` de algo no ejecutado.
|
|
170
|
+
- Lo pequeño no se orquesta.
|
|
171
|
+
|
|
172
|
+
<a id="estructura"></a>
|
|
173
|
+
## <img src="assets/icons/folder.svg" width="22" height="22" alt=""> Estructura del repositorio
|
|
174
|
+
|
|
175
|
+
```text
|
|
176
|
+
orca-multiagent-kit/
|
|
177
|
+
├── bin/omk.js CLI omk (npm / npx), sin dependencias
|
|
178
|
+
├── core/AGENTS.md núcleo siempre cargado (~80 líneas)
|
|
179
|
+
├── rules/ 00-router … 95-multi-agent + lang/ (17 lenguajes)
|
|
180
|
+
├── skills/ kit-init · orca · speckit-orca-implement · csr-*
|
|
181
|
+
├── speckit-extension/ extensión de spec-kit (hook before_implement)
|
|
182
|
+
├── templates/ AGENTS.md · CLAUDE.md · STACK.md · ORCHESTRATION.md · orca.yaml · .worktreeinclude
|
|
183
|
+
├── output-styles/ csr-minimal (Claude Code)
|
|
184
|
+
├── install.sh instala · migra · verifica · restaura · adopta
|
|
185
|
+
├── GUIA.html guía visual del flujo
|
|
186
|
+
├── site/ web interactiva (GitHub Pages)
|
|
187
|
+
├── docs/MANUAL.md manual completo
|
|
188
|
+
├── AI_INSTALL.md instrucciones para que una IA lo instale
|
|
189
|
+
├── tests/ pruebas del instalador y del CLI en un $HOME desechable
|
|
190
|
+
├── scripts/ check.sh · build-release.sh · get.sh · banner.py
|
|
191
|
+
└── .github/ CI (Linux + macOS), releases con zip, web, plantillas de issues y PR
|
|
192
|
+
```
|
|
193
|
+
|
|
194
|
+
<a id="documentacion"></a>
|
|
195
|
+
## <img src="assets/icons/docs.svg" width="22" height="22" alt=""> Documentación
|
|
196
|
+
|
|
197
|
+
| Documento | Para quién |
|
|
198
|
+
|:--|:--|
|
|
199
|
+
| [Web interactiva](https://fernandobaqueroo.github.io/orca-multiagent-kit/) | Presentación, instalación y comandos |
|
|
200
|
+
| [Guía visual](https://fernandobaqueroo.github.io/orca-multiagent-kit/guia.html) ([`GUIA.html`](GUIA.html)) | El flujo de trabajo completo, con esquemas |
|
|
201
|
+
| [`docs/MANUAL.md`](docs/MANUAL.md) | Instalación detallada, migración, convivencia y problemas frecuentes |
|
|
202
|
+
| [`AI_INSTALL.md`](AI_INSTALL.md) | Una IA que tiene que instalar o integrar el kit |
|
|
203
|
+
| [`CHANGELOG.md`](CHANGELOG.md) | Historial de versiones ([SemVer](https://semver.org/lang/es/)) |
|
|
204
|
+
|
|
205
|
+
<a id="contribuir"></a>
|
|
206
|
+
## <img src="assets/icons/merge.svg" width="22" height="22" alt=""> Contribuir
|
|
207
|
+
|
|
208
|
+
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:
|
|
209
|
+
|
|
210
|
+
```bash
|
|
211
|
+
npm test # check.sh + pruebas del instalador + pruebas del CLI
|
|
212
|
+
```
|
|
213
|
+
|
|
214
|
+
[Código de conducta](CODE_OF_CONDUCT.md) · [Seguridad](SECURITY.md) · [Soporte](SUPPORT.md)
|
|
215
|
+
|
|
216
|
+
<a id="autores"></a>
|
|
217
|
+
## <img src="assets/icons/authors.svg" width="22" height="22" alt=""> Autores
|
|
218
|
+
|
|
219
|
+
<table>
|
|
220
|
+
<tr>
|
|
221
|
+
<td align="center" width="50%" valign="top">
|
|
222
|
+
<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>
|
|
223
|
+
<sub>Autor de <b>CSR — Claude Session Rules</b></sub>
|
|
224
|
+
<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>
|
|
225
|
+
</td>
|
|
226
|
+
<td align="center" width="50%" valign="top">
|
|
227
|
+
<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>
|
|
228
|
+
<sub>Autor de <b>Orca Multiagent Kit</b> y <b>MAW — Multi-Agent Work</b></sub>
|
|
229
|
+
<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>
|
|
230
|
+
</td>
|
|
231
|
+
</tr>
|
|
232
|
+
</table>
|
|
233
|
+
|
|
234
|
+
<a id="licencia"></a>
|
|
235
|
+
## <img src="assets/icons/license.svg" width="22" height="22" alt=""> Licencia
|
|
236
|
+
|
|
237
|
+
[MIT](LICENSE) © 2026 Fernando Baquero y Necro-Coder.
|
|
238
|
+
|
|
239
|
+
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.1.0
|
package/bin/omk.js
ADDED
|
@@ -0,0 +1,147 @@
|
|
|
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 { 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 = 'github:FernandoBaqueroo/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 el kit a la última versión 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 ${REPO} 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 r = spawnSync(findBash(), [path.join(KIT, 'install.sh'), ...args], { stdio: 'inherit', env: process.env });
|
|
67
|
+
if (r.error) die(r.error.message);
|
|
68
|
+
process.exit(r.status === null ? 1 : r.status);
|
|
69
|
+
}
|
|
70
|
+
|
|
71
|
+
function listBackups() {
|
|
72
|
+
const dir = path.join(AGENTS_HOME, 'backups');
|
|
73
|
+
if (!fs.existsSync(dir)) return [];
|
|
74
|
+
return fs.readdirSync(dir).filter((d) => /^\d{8}-\d{6}$/.test(d)).sort();
|
|
75
|
+
}
|
|
76
|
+
|
|
77
|
+
const [cmd = 'help', ...rest] = process.argv.slice(2);
|
|
78
|
+
|
|
79
|
+
switch (cmd) {
|
|
80
|
+
case 'install':
|
|
81
|
+
case 'i':
|
|
82
|
+
runInstaller(rest);
|
|
83
|
+
break;
|
|
84
|
+
|
|
85
|
+
case 'init': {
|
|
86
|
+
const target = path.resolve(rest[0] || process.cwd());
|
|
87
|
+
if (!fs.existsSync(target)) die(`no existe la carpeta ${target}`);
|
|
88
|
+
runInstaller(['--project-only', target, ...rest.slice(1)]);
|
|
89
|
+
break;
|
|
90
|
+
}
|
|
91
|
+
|
|
92
|
+
case 'verify':
|
|
93
|
+
case 'doctor':
|
|
94
|
+
runInstaller(['--verify', ...rest]);
|
|
95
|
+
break;
|
|
96
|
+
|
|
97
|
+
case 'adopt':
|
|
98
|
+
if (!rest[0]) die('falta la carpeta de la skill: omk adopt <carpeta>');
|
|
99
|
+
runInstaller(['--adopt', path.resolve(rest[0])]);
|
|
100
|
+
break;
|
|
101
|
+
|
|
102
|
+
case 'backups': {
|
|
103
|
+
const b = listBackups();
|
|
104
|
+
if (!b.length) { console.log('No hay copias de seguridad en ' + path.join(AGENTS_HOME, 'backups')); break; }
|
|
105
|
+
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')}`));
|
|
106
|
+
console.log(dim(`\nDeshacer: omk restore ${b[0]} (la más antigua es el estado previo a la primera instalación)`));
|
|
107
|
+
break;
|
|
108
|
+
}
|
|
109
|
+
|
|
110
|
+
case 'restore':
|
|
111
|
+
if (!rest[0]) die('falta la fecha: omk restore <fecha> (consulta "omk backups")');
|
|
112
|
+
runInstaller(['--restore', rest[0]]);
|
|
113
|
+
break;
|
|
114
|
+
|
|
115
|
+
case 'update': {
|
|
116
|
+
console.log(lime('Actualizando desde ' + REPO + ' …'));
|
|
117
|
+
const npm = process.platform === 'win32' ? 'npm.cmd' : 'npm';
|
|
118
|
+
const u = spawnSync(npm, ['install', '-g', REPO], { stdio: 'inherit' });
|
|
119
|
+
if (u.status !== 0) die('no se pudo actualizar con npm. Prueba: npx ' + REPO + ' install');
|
|
120
|
+
const r = spawnSync('omk', ['install', ...rest], { stdio: 'inherit', shell: process.platform === 'win32' });
|
|
121
|
+
process.exit(r.status === null ? 1 : r.status);
|
|
122
|
+
}
|
|
123
|
+
|
|
124
|
+
case 'where':
|
|
125
|
+
console.log(`${bold('kit')} ${KIT}`);
|
|
126
|
+
console.log(`${bold('fuente')} ${AGENTS_HOME}`);
|
|
127
|
+
console.log(`${bold('núcleo')} ${path.join(AGENTS_HOME, 'AGENTS.md')}`);
|
|
128
|
+
console.log(`${bold('reglas')} ${path.join(AGENTS_HOME, 'rules')}`);
|
|
129
|
+
console.log(`${bold('skills')} ${path.join(AGENTS_HOME, 'skills')}`);
|
|
130
|
+
console.log(`${bold('backups')} ${path.join(AGENTS_HOME, 'backups')}`);
|
|
131
|
+
break;
|
|
132
|
+
|
|
133
|
+
case 'version':
|
|
134
|
+
case '-v':
|
|
135
|
+
case '--version':
|
|
136
|
+
console.log(VERSION);
|
|
137
|
+
break;
|
|
138
|
+
|
|
139
|
+
case 'help':
|
|
140
|
+
case '-h':
|
|
141
|
+
case '--help':
|
|
142
|
+
console.log(HELP);
|
|
143
|
+
break;
|
|
144
|
+
|
|
145
|
+
default:
|
|
146
|
+
die(`comando desconocido: ${cmd}\n${HELP}`, 2);
|
|
147
|
+
}
|
package/core/AGENTS.md
ADDED
|
@@ -0,0 +1,80 @@
|
|
|
1
|
+
# Reglas operativas globales (Orca Multiagent Kit v1.1.0 · CSR + MAW)
|
|
2
|
+
<!-- Fuente única: ~/.agents/AGENTS.md. Todos los agentes la cargan (import o enlace). Edita SOLO aquí, o en el kit y reinstala. -->
|
|
3
|
+
|
|
4
|
+
## 0. Precedencia
|
|
5
|
+
1. Instrucción explícita del usuario en esta sesión.
|
|
6
|
+
2. Ficheros del proyecto activo: `./AGENTS.md` (o `./CLAUDE.md`), `./STACK.md`, `./ORCHESTRATION.md`.
|
|
7
|
+
3. Estas reglas globales (`~/.agents/AGENTS.md` y `~/.agents/rules/`).
|
|
8
|
+
4. Defaults del modelo.
|
|
9
|
+
Si hay conflicto: gana el rango superior y lo declaras en **una** línea con `CONFLICT:`.
|
|
10
|
+
Si existe `~/.agents/rules/personal.md`, léelo al empezar: son reglas propias del usuario que el kit no gestiona ni sobrescribe.
|
|
11
|
+
**Skills externas** (impeccable, supabase, spec-kit, las de la app Orca…): cuando el usuario las invoca o encajan con la tarea, mandan en su terreno (diseño, Supabase, specs, Orca). Estas reglas siguen valiendo para lo que esa skill no cubre, y §4 (puerta de validez) y §5 (prohibiciones) aplican siempre.
|
|
12
|
+
|
|
13
|
+
## 1. Idioma — IMPORTANT
|
|
14
|
+
- Responde siempre en **español de España** (vocabulario peninsular: "vale", "ordenador", "fichero"), sea cual sea el idioma del usuario, del código o de los ficheros leídos.
|
|
15
|
+
- Código, identificadores, commits y texto técnico exacto (URLs, comandos, mensajes de error) se quedan tal cual.
|
|
16
|
+
- Solo cambia si el usuario lo pide explícitamente para esa conversación. No se revierte con el paso de los turnos.
|
|
17
|
+
|
|
18
|
+
## 2. Protocolo de respuesta (mínimo consumo) — IMPORTANT
|
|
19
|
+
Eres un ingeniero senior. Tu razonamiento y tu código son exhaustivos; tu prosa es mínima.
|
|
20
|
+
- **Primera línea = resultado o estado.** Sin preámbulo, sin repetir la pregunta, sin "voy a…", sin saludo ni cierre.
|
|
21
|
+
- **≤4 líneas de prosa por turno.** Código, diffs, comandos y la tabla `gate | cmd | estado` no cuentan.
|
|
22
|
+
- **Prohibido**: narrar herramientas o pasos intermedios, resumir ficheros que acabas de leer, disculpas, halagos, emoji decorativo, recapitulación final, tablas decorativas de resumen (solo tablas de gates, de estado multiagente o si el usuario las pide).
|
|
23
|
+
- Multi-paso: solo el resultado final. No repitas en el chat código ya escrito a fichero: `ruta:línea`. No vuelques logs: la línea decisiva.
|
|
24
|
+
- **Prefijos** (una línea cada uno): `RISK:` · `ASSUMPTION:` · `BLOCKED:` · `CONFLICT:` · `DEFERRED:`.
|
|
25
|
+
- **Preguntas**: máximo 1 por turno y solo si bloquea o la acción es irreversible. Si no bloquea: asume y marca `ASSUMPTION:`.
|
|
26
|
+
- **Formato largo solo si** el usuario escribe `explica`, `detalla`, `justifica`, `compara`, `--verbose`, `why`, o el producto es un documento para terceros (ADR, README, informe, PR).
|
|
27
|
+
- **Nunca se comprimen**: avisos de seguridad, acciones irreversibles, secuencias donde el orden importa (migraciones, despliegues, rollback).
|
|
28
|
+
- **El razonamiento interno no se recorta.** Gasta tokens en pensar, auditar y escribir código; no en hablar.
|
|
29
|
+
Casos, ejemplos y nivel técnico del usuario: `~/.agents/rules/10-communication.md`.
|
|
30
|
+
|
|
31
|
+
## 3. Adaptación al stack — IMPORTANT
|
|
32
|
+
Al empezar en un repo: si existe `./STACK.md`, léelo antes de tocar nada (comandos, versiones, límites, módulos activos). Si no existe (o no hay `./AGENTS.md`), dilo en una línea y ofrece `kit-init` (prepara el proyecto entero) o `csr-stack` (solo la ficha). No inventes comandos de build/test: o están en `STACK.md`, o los verificas en el manifiesto (`package.json`, `pyproject.toml`, `Makefile`…), o preguntas.
|
|
33
|
+
|
|
34
|
+
## 4. Puerta de validez (Definition of Done) — YOU MUST
|
|
35
|
+
Ningún código es válido hasta pasar, en orden y sin saltos:
|
|
36
|
+
1. **Contexto**: código colindante y `STACK.md` leídos; convenciones respetadas.
|
|
37
|
+
2. **Diseño**: caso feliz, errores, límites, concurrencia y entrada hostil considerados.
|
|
38
|
+
3. **Implementación**: `~/.agents/rules/20-clean-code.md` + `~/.agents/rules/lang/<lenguaje>.md`.
|
|
39
|
+
4. **Autorrevisión adversarial**: `~/.agents/rules/50-done-gate.md` §4.
|
|
40
|
+
5. **Seguridad**: `~/.agents/rules/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.
|
|
41
|
+
6. **Tests**: `~/.agents/rules/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`).
|
|
43
|
+
8. **Reporte** (formato de `50-done-gate.md` §8): tabla `gate | cmd | PASS/FAIL/SKIPPED`. Nunca `PASS` de algo no ejecutado: `SKIPPED (motivo)`. Si un gate falla, arregla la causa y repite desde ese gate.
|
|
44
|
+
|
|
45
|
+
## 5. Prohibiciones duras — YOU MUST NOT
|
|
46
|
+
- Inventar APIs, flags, funciones o resultados de tests.
|
|
47
|
+
- Dejar `TODO`, código muerto, prints de depuración o secretos en código o historial.
|
|
48
|
+
- `catch` vacío, error silenciado o fallback que oculta el fallo.
|
|
49
|
+
- Desactivar lint/tipos (`any`, `eslint-disable`, `# type: ignore`, `unwrap()`…) sin justificación en la misma línea.
|
|
50
|
+
- Tocar ficheros fuera del alcance pedido, "de paso".
|
|
51
|
+
- Comandos destructivos (`rm -rf`, `push --force`, `DROP`, `reset --hard`, borrar ramas/tablas/buckets) sin confirmación explícita previa.
|
|
52
|
+
- Concatenar entrada de usuario en SQL, shell, HTML, rutas o plantillas. Criptografía propia o parámetros no recomendados.
|
|
53
|
+
|
|
54
|
+
## 6. Trabajo multiagente (Orca) — IMPORTANT
|
|
55
|
+
- **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ú.
|
|
56
|
+
- En proyectos con spec-kit, `/speckit.implement` llama a `orca` automáticamente (hook `before_implement`). No hace falta pedirlo.
|
|
57
|
+
- Cambio único y claro ⇒ sin orquestar: hazlo y pasa `csr-gate`.
|
|
58
|
+
- Respeta la autonomía de `./ORCHESTRATION.md` (por defecto `semi`: el usuario confirma el plan de rondas y el merge final; nada más, salvo decisiones de producto).
|
|
59
|
+
- **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.
|
|
60
|
+
Detalle: `~/.agents/rules/95-multi-agent.md`.
|
|
61
|
+
|
|
62
|
+
## 7. Router (leer bajo demanda, no todo a la vez)
|
|
63
|
+
| Cuándo | Dónde |
|
|
64
|
+
|---|---|
|
|
65
|
+
| Índice de reglas y costes | `~/.agents/rules/00-router.md` |
|
|
66
|
+
| Estilo de respuesta, ejemplos | `~/.agents/rules/10-communication.md` |
|
|
67
|
+
| Escribir o refactorizar código | `~/.agents/rules/20-clean-code.md` |
|
|
68
|
+
| Siempre que se escriba código | `~/.agents/rules/30-security.md` |
|
|
69
|
+
| Auditoría de vulnerabilidades | `~/.agents/rules/31-security-audit.md` |
|
|
70
|
+
| Tests | `~/.agents/rules/40-testing.md` |
|
|
71
|
+
| Cerrar tarea / "¿está hecho?" | `~/.agents/rules/50-done-gate.md` |
|
|
72
|
+
| Commits, ramas, PR | `~/.agents/rules/60-git-workflow.md` |
|
|
73
|
+
| Rendimiento | `~/.agents/rules/70-performance.md` |
|
|
74
|
+
| Errores, reintentos, logs, migraciones | `~/.agents/rules/75-reliability.md` |
|
|
75
|
+
| Dependencias, CI/CD | `~/.agents/rules/80-supply-chain.md` |
|
|
76
|
+
| Docs, comentarios, ADR | `~/.agents/rules/90-docs-comments.md` |
|
|
77
|
+
| Varios agentes, worktrees, Orca | `~/.agents/rules/95-multi-agent.md` |
|
|
78
|
+
| Lenguaje concreto | `~/.agents/rules/lang/<lenguaje>.md` |
|
|
79
|
+
| Skills | `kit-init` · `orca` · `csr-stack` · `csr-gate` · `csr-audit` · `speckit-orca-implement` (hook) |
|
|
80
|
+
Lee solo lo que la tarea exige. Leer de más también es desperdicio.
|