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.
Files changed (72) hide show
  1. package/AI_INSTALL.md +49 -0
  2. package/CHANGELOG.md +56 -0
  3. package/GUIA.html +401 -0
  4. package/LICENSE +21 -0
  5. package/README.md +238 -2
  6. package/VERSION +1 -0
  7. package/bin/omk.js +147 -0
  8. package/core/AGENTS.md +80 -0
  9. package/docs/MANUAL.md +208 -0
  10. package/install.sh +297 -0
  11. package/output-styles/csr-minimal.md +14 -0
  12. package/package.json +23 -4
  13. package/rules/00-router.md +28 -0
  14. package/rules/10-communication.md +58 -0
  15. package/rules/20-clean-code.md +59 -0
  16. package/rules/30-security.md +81 -0
  17. package/rules/31-security-audit.md +58 -0
  18. package/rules/40-testing.md +48 -0
  19. package/rules/50-done-gate.md +66 -0
  20. package/rules/60-git-workflow.md +49 -0
  21. package/rules/70-performance.md +36 -0
  22. package/rules/75-reliability.md +36 -0
  23. package/rules/80-supply-chain.md +35 -0
  24. package/rules/90-docs-comments.md +36 -0
  25. package/rules/95-multi-agent.md +56 -0
  26. package/rules/lang/cpp.md +26 -0
  27. package/rules/lang/csharp.md +27 -0
  28. package/rules/lang/dart-flutter.md +26 -0
  29. package/rules/lang/go.md +30 -0
  30. package/rules/lang/infra.md +33 -0
  31. package/rules/lang/java.md +29 -0
  32. package/rules/lang/kotlin.md +25 -0
  33. package/rules/lang/php.md +27 -0
  34. package/rules/lang/python.md +33 -0
  35. package/rules/lang/react.md +32 -0
  36. package/rules/lang/ruby.md +23 -0
  37. package/rules/lang/rust.md +32 -0
  38. package/rules/lang/shell.md +24 -0
  39. package/rules/lang/sql.md +29 -0
  40. package/rules/lang/swift.md +31 -0
  41. package/rules/lang/typescript.md +32 -0
  42. package/rules/lang/web.md +31 -0
  43. package/skills/csr-audit/SKILL.md +14 -0
  44. package/skills/csr-gate/SKILL.md +16 -0
  45. package/skills/csr-stack/SKILL.md +23 -0
  46. package/skills/kit-init/SKILL.md +61 -0
  47. package/skills/orca/SKILL.md +88 -0
  48. package/skills/orca/references/adapters/artifact.md +32 -0
  49. package/skills/orca/references/adapters/chat.md +33 -0
  50. package/skills/orca/references/adapters/native-plan.md +18 -0
  51. package/skills/orca/references/adapters/plan-file.md +20 -0
  52. package/skills/orca/references/adapters/speckit.md +42 -0
  53. package/skills/orca/references/engine-manual.md +30 -0
  54. package/skills/orca/references/engine-orca.md +36 -0
  55. package/skills/orca/references/engine-subagents.md +19 -0
  56. package/skills/orca/references/integrate.md +37 -0
  57. package/skills/orca/references/plan.md +48 -0
  58. package/skills/orca/references/race.md +35 -0
  59. package/skills/orca/references/setup.md +26 -0
  60. package/skills/orca/references/units.md +44 -0
  61. package/skills/orca/references/worker-contract.md +49 -0
  62. package/skills/speckit-orca-implement/SKILL.md +17 -0
  63. package/speckit-extension/orca/README.md +15 -0
  64. package/speckit-extension/orca/commands/implement.md +16 -0
  65. package/speckit-extension/orca/extension.yml +26 -0
  66. package/templates/.worktreeinclude +4 -0
  67. package/templates/AGENTS.md +13 -0
  68. package/templates/CLAUDE.md +4 -0
  69. package/templates/ORCHESTRATION.md +49 -0
  70. package/templates/STACK.md +91 -0
  71. package/templates/claude-settings.json +27 -0
  72. package/templates/orca.yaml +5 -0
@@ -0,0 +1,49 @@
1
+ # Contrato del worker (va dentro de cada brief)
2
+
3
+ Copia este texto en el mensaje de cada worker de motores `subagents` y `manual`. Con Orca, copia solo §2 (alcance): Orca ya le da el contrato de `worker_done`, preguntas y heartbeats.
4
+
5
+ Eres un worker de un run orquestado. Ejecutas **una** unidad.
6
+
7
+ ## 1. Arranque (antes de editar nada)
8
+ 1. Confirma que estás en un worktree propio: `git rev-parse --show-toplevel` y `git branch --show-current` ≠ rama por defecto. Si estás en el checkout principal o en `main`: `BLOCKED: no estoy aislado` y para.
9
+ 2. Lee `STACK.md` y las reglas del proyecto (`AGENTS.md` / `CLAUDE.md`). Lee los ficheros de `read` de tu unidad.
10
+ 3. Comprueba que el entorno arranca: el comando `install`/`typecheck` de `STACK.md` §3. Si falla por entorno (no por código), repórtalo como `BLOCKED:` en vez de "arreglar" configuración compartida.
11
+ 4. Si el motor es Orca: checkpoint `orca worktree set --worktree active --comment "U2: empezando" --workspace-status in-progress --json`.
12
+
13
+ ## 2. Alcance — YOU MUST
14
+ - Escribes **solo** en `write`. Necesitas otro fichero ⇒ pregunta al coordinador (Orca: `orca orchestration ask`; otros motores: `BLOCKED:` en el informe) y espera o sigue con lo demás.
15
+ - No tocas: `shared` (salvo los listados en tu unidad), `tasks.md`, `planes/*.md`, `ORCHESTRATION.md`, `STACK.md`, lockfiles. Si necesitas una dependencia nueva: pídela, no la instales.
16
+ - No reabres decisiones de `notes`. Si crees que una está mal: `RISK:` en el informe, e implementas lo decidido.
17
+ - No haces merge, push, rebase sobre otras ramas ni borras ramas. Commits locales en tu rama **solo** si `ORCHESTRATION.md` §1 dice «Commits locales de workers: sí» (o el brief lo autoriza); entonces atómicos según `60-git-workflow.md`. Si no, deja los cambios sin commitear en tu worktree e indícalo en el informe (`commits: 0`).
18
+ - Requisito ambiguo que no resuelven `acceptance` ni `notes`: pregunta. No inventes.
19
+
20
+ ## 3. Implementación
21
+ - CSR completo: `20-clean-code`, `30-security`, reglas de lenguaje, tests (`40-testing`).
22
+ - Tareas paralelizables dentro de tu unidad (`[P]` de spec-kit): puedes usar tus propios subagentes, sobre **tu** worktree y respetando tu `write`.
23
+ - Checkpoint en cada cambio de fase (investigar → implementar → verificar), una línea.
24
+
25
+ ## 4. Verificación
26
+ `csr-gate` sobre tu diff. Además ejecuta cada comando de `verify` y comprueba cada punto de `acceptance` (marca cuál se verificó ejecutando y cuál solo razonando).
27
+
28
+ ## 5. Informe (formato fijo — es lo único que lee el coordinador)
29
+ ```
30
+ UNIT: U2 · RUN: <run-id> · outcome: succeeded|failed|blocked
31
+ branch: maw/<run>/u2 · commits: <n> · head: <sha>
32
+ done: <1–2 líneas: qué existe ahora>
33
+ files: <ruta> (+X/-Y), ... # todos los tocados
34
+ out_of_write: <ficheros fuera de write, o "ninguno">
35
+ acceptance:
36
+ - [x] <criterio> — verificado: <cmd o prueba>
37
+ - [ ] <criterio> — motivo
38
+ gate | cmd | estado
39
+ ... | ... | PASS / FAIL / SKIPPED (motivo)
40
+ RISK: / ASSUMPTION: / DEFERRED: / BLOCKED: (una línea cada uno, si aplica)
41
+ needs_from_coordinator: <cambios en shared, dependencias, decisiones>, o "nada"
42
+ ```
43
+ Entrega por el canal del motor:
44
+ - Orca: `orca orchestration send --type worker_done --task-id <id> --dispatch-id <id> --outcome succeeded|failed --subject "U2 <título>" --body "<informe>" --files-modified "<rutas>" --json` (valida flags con `orca skills get orchestration`). Exactamente **una** vez, también si falla.
45
+ - Subagente: el informe es tu mensaje final, sin nada más.
46
+ - Manual: escríbelo en `.work/REPORT.md` de tu worktree.
47
+
48
+ ## Honestidad
49
+ `outcome: succeeded` exige gates sin `FAIL` y todos los `acceptance` marcados. Lo demás es `failed` o `blocked`, con el resto del trabajo entregado.
@@ -0,0 +1,17 @@
1
+ ---
2
+ name: speckit-orca-implement
3
+ description: Hook before_implement de spec-kit (extensión orca). Se ejecuta automáticamente al lanzar /speckit.implement. Decide si la feature compensa implementarla en paralelo con varios agentes y, si compensa, la implementa de forma orquestada con la skill orca; si no, deja que /speckit.implement siga normal.
4
+ ---
5
+
6
+ # speckit-orca-implement — Implementación orquestada desde spec-kit
7
+
8
+ Te ha invocado el hook `before_implement` (o el usuario directamente) en un proyecto con spec-kit.
9
+
10
+ 1. Carga la skill **`orca`** y síguela con estas condiciones:
11
+ - **Entrada**: spec-kit; la feature activa es la que resuelve `.specify/scripts/bash/check-prerequisites.sh --json --require-tasks --include-tasks` (`FEATURE_DIR`).
12
+ - **Paso 1 (¿compensa?)** con las user stories pendientes de `tasks.md`. Las tareas ya marcadas `[x]` no cuentan.
13
+ - **No** vuelvas a invocar `/speckit.implement` ni `/speckit-implement`: ya estás dentro de él.
14
+ 2. Resultado, siempre en **una línea** al final:
15
+ - `ORCA: secuencial — <motivo>. Continúa /speckit.implement.` → el flujo de implement sigue con su Outline normal.
16
+ - `ORCA: orquestado — <n> tareas completadas en <r> rondas. /speckit.implement solo debe validar y ejecutar sus hooks posteriores.` → implement encontrará todas las tareas en `[x]`.
17
+ - `ORCA: cancelado por el usuario. Continúa /speckit.implement en modo secuencial.` si en la confirmación 1 el usuario dice que no.
@@ -0,0 +1,15 @@
1
+ # Extensión de spec-kit: orca
2
+
3
+ Hace que `/speckit.implement` reparta las user stories entre varios agentes cuando compensa. Usa el hook `before_implement`, que es obligatorio.
4
+
5
+ ## Instalar en un proyecto
6
+ - Con **Orca Multiagent Kit** instalado: abre tu agente en el proyecto y escribe «inicializa el proyecto» (`kit-init`), o ejecuta `omk init`.
7
+ - A mano, con el CLI de spec-kit:
8
+ ```bash
9
+ specify extension add --dev ~/.agents/speckit-ext/orca
10
+ ```
11
+
12
+ El comando `speckit.orca.implement` delega en la skill global `orca` del kit, que tiene que estar instalada (`omk install`).
13
+
14
+ ## Desactivar
15
+ En `.specify/extensions.yml`, pon `enabled: false` en el hook `before_implement` de `orca`. `/speckit.implement` volverá a ser secuencial.
@@ -0,0 +1,16 @@
1
+ ---
2
+ description: "Decide si compensa implementar la feature en paralelo y, si compensa, la orquesta con varios agentes."
3
+ ---
4
+
5
+ # speckit-orca-implement — Implementación orquestada desde spec-kit
6
+
7
+ Te ha invocado el hook `before_implement` (o el usuario directamente) en un proyecto con spec-kit.
8
+
9
+ 1. Carga la skill **`orca`** y síguela con estas condiciones:
10
+ - **Entrada**: spec-kit; la feature activa es la que resuelve `.specify/scripts/bash/check-prerequisites.sh --json --require-tasks --include-tasks` (`FEATURE_DIR`).
11
+ - **Paso 1 (¿compensa?)** con las user stories pendientes de `tasks.md`. Las tareas ya marcadas `[x]` no cuentan.
12
+ - **No** vuelvas a invocar `/speckit.implement` ni `/speckit-implement`: ya estás dentro de él.
13
+ 2. Resultado, siempre en **una línea** al final:
14
+ - `ORCA: secuencial — <motivo>. Continúa /speckit.implement.` → el flujo de implement sigue con su Outline normal.
15
+ - `ORCA: orquestado — <n> tareas completadas en <r> rondas. /speckit.implement solo debe validar y ejecutar sus hooks posteriores.` → implement encontrará todas las tareas en `[x]`.
16
+ - `ORCA: cancelado por el usuario. Continúa /speckit.implement en modo secuencial.` si en la confirmación 1 el usuario dice que no.
@@ -0,0 +1,26 @@
1
+ schema_version: "1.0"
2
+
3
+ extension:
4
+ id: orca
5
+ name: "Orca Multiagent"
6
+ version: "1.1.0"
7
+ description: "Implementa specs en paralelo con varios agentes (Orca, subagentes o worktrees) desde /speckit.implement."
8
+ author: "Fernando Baquero"
9
+ repository: "https://github.com/FernandoBaqueroo/orca-multiagent-kit"
10
+ license: "MIT"
11
+ homepage: "https://fernandobaqueroo.github.io/orca-multiagent-kit/"
12
+
13
+ requires:
14
+ speckit_version: ">=1.0.0"
15
+
16
+ provides:
17
+ commands:
18
+ - name: speckit.orca.implement
19
+ file: commands/implement.md
20
+ description: "Decide si compensa implementar la feature en paralelo y, si compensa, la orquesta con varios agentes."
21
+
22
+ hooks:
23
+ before_implement:
24
+ command: speckit.orca.implement
25
+ optional: false
26
+ description: "Orquestación multiagente: reparte las user stories entre agentes si compensa; si no, implement sigue normal."
@@ -0,0 +1,4 @@
1
+ # Ficheros gitignorados que Orca COPIA en cada worktree nuevo.
2
+ # Solo rutas literales (sin globs). Solo entorno de DESARROLLO: nunca credenciales de producción,
3
+ # porque los agentes pueden ejecutarse sin confirmación dentro del worktree.
4
+ .env.local
@@ -0,0 +1,13 @@
1
+ <!-- AGENTS:BEGIN project v1.0.0 -->
2
+ # Reglas del proyecto
3
+
4
+ 1. Lee `./STACK.md` antes de la primera edición de cada sesión: versiones, comandos y límites. Comandos: solo los de `STACK.md` §3; si falta uno, dilo, no lo inventes.
5
+ 2. Aplican las reglas globales (`~/.agents/AGENTS.md`) y su router (`~/.agents/rules/`). Lee bajo demanda, no todo. Si tu agente no las tiene cargadas, léelas ahora.
6
+ 3. Ningún cambio se da por terminado sin `~/.agents/rules/50-done-gate.md` y la tabla de gates.
7
+ 4. Respuestas mínimas: resultado primero, ≤4 líneas de prosa, sin narrar herramientas. Detalle solo si se pide.
8
+ 5. Trabajo multiagente: antes de repartir, lee `./ORCHESTRATION.md`. Una unidad = un worktree = una rama; los ficheros `shared` solo los toca una unidad por ronda; los workers no editan `tasks.md`, `planes/*.md`, `ORCHESTRATION.md`, `STACK.md` ni lockfiles, no mergean ni hacen push, y entregan informe. Briefs e informes en `.work/` (ignorado por git).
9
+
10
+ ## Overrides de este proyecto
11
+ <!-- Solo lo que se desvía de las reglas globales. Si está vacío, mejor. -->
12
+ -
13
+ <!-- AGENTS:END -->
@@ -0,0 +1,4 @@
1
+ <!-- AGENTS:BEGIN project-claude v1.0.0 -->
2
+ <!-- Claude Code lee CLAUDE.md en vez de AGENTS.md cuando existen los dos: este import hace que lea las mismas reglas que el resto de agentes. No añadas reglas aquí: van en AGENTS.md. -->
3
+ @AGENTS.md
4
+ <!-- AGENTS:END -->
@@ -0,0 +1,49 @@
1
+ # ORCHESTRATION.md — Cómo se reparte el trabajo entre agentes
2
+ > La lee la skill `orca` (coordinador) antes de repartir trabajo. Generar o actualizar: «inicializa el proyecto» (`kit-init`).
3
+ > Mantenla corta (≤ ~80 líneas). Complementa a `STACK.md`; no repite sus comandos.
4
+
5
+ ## 0. Autonomía
6
+ - Nivel: semi <!-- manual | semi | auto -->
7
+ - manual: confirmas el plan de rondas, cada ronda y cada merge
8
+ - semi: confirmas el plan de rondas y el merge final (recomendado)
9
+ - auto: solo confirmas el merge final
10
+ - Nunca se mergea a la rama por defecto ni se hace push sin confirmación, en ningún nivel.
11
+
12
+ ## 1. Agentes
13
+ | Capa / área | Agente por defecto | Alternativa | Motivo |
14
+ |---|---|---|---|
15
+ | UI (componentes, páginas, estilos) | | | |
16
+ | API / lógica de servidor | | | |
17
+ | Datos (esquema, migraciones, SQL) | coordinador | — | toca `shared` |
18
+ | Tests E2E / verificación en navegador | | | |
19
+ | Revisión de diffs al integrar | | | segundo proveedor = segunda opinión |
20
+ - Máximo de workers simultáneos: 3
21
+ - Motor preferido: orca | subagents | manual
22
+ - Commits locales de workers: sí | no
23
+
24
+ ## 2. Shared — ficheros que solo toca una unidad por ronda o el coordinador
25
+ ```
26
+ # rutas o globs estrechos, uno por línea
27
+ package.json
28
+ pnpm-lock.yaml
29
+ ```
30
+
31
+ ## 3. Entorno de worktree
32
+ - Dependencias: symlink vía `orca.yaml` (`sharedDirectories`) | `pnpm install` en setup
33
+ - Variables de entorno: `.worktreeinclude` copia → `.env.local` (solo desarrollo)
34
+ - Base de datos: compartida, migra solo una unidad por ronda | una BD/esquema por worktree (`DATABASE_URL=..._<unit>`)
35
+ - `PORT_BASE`: 3100 (worker n usa 3100+n)
36
+ - Setup tras crear worktree (si no lo hace Orca):
37
+ ```
38
+ TODO:
39
+ ```
40
+
41
+ ## 4. Flujo por defecto
42
+ - Entrada habitual: spec-kit | plan por sprints | chat
43
+ - Rama de integración: `feat/<feature>` (nunca directo a la rama por defecto)
44
+ - Quién mergea: coordinador tras "sí" del usuario
45
+
46
+ ## 5. No delegar nunca
47
+ - Migraciones destructivas, cambios de auth/permisos, despliegues, rotación de secretos.
48
+
49
+ ## 6. Última actualización: YYYY-MM-DD
@@ -0,0 +1,91 @@
1
+ # STACK.md — Ficha técnica del proyecto
2
+ > Fuente de verdad del stack. El agente la lee ANTES de tocar nada.
3
+ > Rellena lo que aplique, borra lo que no. Mantenla corta: si crece de ~120 líneas, mueve detalle a `docs/`.
4
+ > Regenerar o actualizar: `/csr-stack`.
5
+
6
+ ## 1. Identidad
7
+ - **Proyecto**:
8
+ - **Qué es** (1 línea):
9
+ - **Tipo**: web | API | CLI | escritorio | móvil | librería | monorepo | datos/ML
10
+ - **Estado**: prototipo | desarrollo | producción
11
+ - **Usuarios y datos**: ¿hay datos personales, dinero o credenciales? sí/no →
12
+ - **Nivel de seguridad objetivo (ASVS)**: L1 | L2 | L3
13
+
14
+ ## 2. Stack
15
+ | Capa | Tecnología | Versión exacta |
16
+ |---|---|---|
17
+ | Lenguaje(s) | | |
18
+ | Runtime | | |
19
+ | Framework | | |
20
+ | UI | | |
21
+ | Base de datos | | |
22
+ | ORM / acceso a datos | | |
23
+ | Gestor de paquetes | | |
24
+ | Build / bundler | | |
25
+ | Tests | | |
26
+ | Lint / format | | |
27
+ | Infra / despliegue | | |
28
+ | CI | | |
29
+
30
+ ## 3. Comandos canónicos (el agente NO debe inventar otros)
31
+ ```
32
+ install :
33
+ dev :
34
+ build :
35
+ test :
36
+ test:watch :
37
+ coverage :
38
+ lint :
39
+ format :
40
+ typecheck :
41
+ sec-scan :
42
+ deps-audit :
43
+ migrate :
44
+ run-app :
45
+ ```
46
+ Si un comando no existe, escribe `N/A` — no lo dejes en blanco.
47
+
48
+ ## 4. Mapa del repo (máx. 12 líneas)
49
+ ```
50
+ src/
51
+ domain/ lógica pura, sin I/O
52
+ ...
53
+ tests/
54
+ ```
55
+
56
+ ## 5. Convenciones del proyecto
57
+ - Estilo de nombres:
58
+ - Estructura de módulos:
59
+ - Manejo de errores:
60
+ - Gestión de estado:
61
+ - Formato de commits:
62
+ - Idioma de código/comentarios/UI:
63
+
64
+ ## 6. Límites y prohibiciones específicas
65
+ - No tocar:
66
+ - No añadir dependencias de:
67
+ - Decisiones cerradas (no reabrir):
68
+ - Restricciones duras del producto (offline, sin nube, presupuesto, plataformas):
69
+
70
+ ## 7. Seguridad del proyecto
71
+ - Datos sensibles que se manejan:
72
+ - Dónde viven los secretos:
73
+ - Modelo de autenticación/autorización:
74
+ - Amenazas principales (3):
75
+ - Auditoría obligatoria en cambios que toquen:
76
+
77
+ ## 8. Rendimiento
78
+ - Presupuestos (latencia, tamaño, memoria, arranque):
79
+ - Puntos calientes conocidos:
80
+
81
+ ## 9. Módulos CSR activos
82
+ Siempre: `20-clean-code`, `30-security`, `50-done-gate`.
83
+ Lenguaje: `lang/…`
84
+ Extra: `40-testing`, `70-performance`, `75-reliability`, `80-supply-chain`, `31-security-audit`
85
+ Desactivados para este proyecto (con motivo):
86
+
87
+ ## 10. Estado actual
88
+ - En curso:
89
+ - Bloqueado por:
90
+ - Deuda técnica conocida:
91
+ - Última actualización de esta ficha: YYYY-MM-DD
@@ -0,0 +1,27 @@
1
+ {
2
+ "$schema": "https://json.schemastore.org/claude-code-settings.json",
3
+ "permissions": {
4
+ "allow": [
5
+ "Read(**)",
6
+ "Grep(**)",
7
+ "Glob(**)",
8
+ "Bash(git status:*)",
9
+ "Bash(git diff:*)",
10
+ "Bash(git log:*)"
11
+ ],
12
+ "ask": [
13
+ "Bash(git push:*)",
14
+ "Bash(git commit:*)"
15
+ ],
16
+ "deny": [
17
+ "Read(./.env)",
18
+ "Read(./.env.*)",
19
+ "Read(./secrets/**)",
20
+ "Read(./**/*.pem)",
21
+ "Read(./**/*.key)",
22
+ "Bash(rm -rf:*)",
23
+ "Bash(git push --force:*)",
24
+ "Bash(curl:* | bash)"
25
+ ]
26
+ }
27
+ }
@@ -0,0 +1,5 @@
1
+ # Orca: directorios gitignorados que cada worktree comparte (symlink) con el checkout principal.
2
+ # Solo se aplican si existen en el checkout principal Y están en .gitignore. kit-init ajusta esta lista.
3
+ worktree:
4
+ sharedDirectories:
5
+ - node_modules