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
@@ -0,0 +1,32 @@
1
+ # Adaptador: artefacto, diseño o documento
2
+
3
+ Entrada visual o documental: mockup, captura, Figma/export, página HTML de referencia, artefacto de Claude, documento de requisitos, anotaciones de Orca Design Mode.
4
+
5
+ ## 1. Extrae requisitos verificables
6
+ - **Estructura**: secciones/componentes, jerarquía, orden.
7
+ - **Estados**: vacío, cargando, error, éxito, hover/focus, responsive (móvil/escritorio).
8
+ - **Tokens**: colores, tipografía, espaciado. Si el repo tiene design system o Tailwind config, **mapea a tokens existentes**; no copies hex sueltos.
9
+ - **Comportamiento**: qué hace cada interacción.
10
+ - **Contenido**: textos exactos que deben aparecer.
11
+ Lo que no se puede deducir de la imagen (datos reales, endpoints) → `ASSUMPTION:` o pregunta única.
12
+
13
+ ## 2. Unidades
14
+ - Componentes reutilizables nuevos → una unidad previa (`U0` o `round: 1`) si varias pantallas los usan.
15
+ - Una pantalla/vista = una unidad.
16
+ - Lógica de datos de esa pantalla puede ir aparte si hay contrato claro.
17
+
18
+ ## 3. Acceptance visual
19
+ `acceptance` debe poder comprobarse mirando:
20
+ - "En 390px de ancho la tarjeta ocupa el ancho completo con 16px de margen"
21
+ - "Estado vacío muestra el texto «Aún no tienes recargas» y el botón primario"
22
+ No: "se parece al diseño".
23
+ `verify` incluye, si existe navegador del agente o Orca: abrir la ruta en dev y capturar pantalla en móvil y escritorio. Si no se puede ejecutar: `SKIPPED (sin navegador)`.
24
+
25
+ ## Si existe la skill `impeccable`
26
+ Úsala para la parte de diseño: `impeccable shape` para planificar la UI antes de dividir, y su `PRODUCT.md`/`DESIGN.md` como fuente de tokens y criterios. Las unidades de UI llevan en `notes`: «aplica impeccable (craft-floor) al implementar». MAW decide el reparto; impeccable decide el diseño.
27
+
28
+ ## 4. Adjunta la referencia
29
+ El brief de cada unidad incluye la referencia visual (ruta de la imagen en el repo o en `.work/runs/<run>/assets/`). El worker la necesita; una descripción en texto pierde detalle.
30
+
31
+ ## Design Mode (Orca)
32
+ Las anotaciones de Design Mode ya traen elemento, estilos y fichero:línea. Cada grupo de anotaciones del mismo componente = una unidad pequeña; normalmente `ENGINE: inline` sobre el agente de ese worktree, sin repartir.
@@ -0,0 +1,33 @@
1
+ # Adaptador: prompt de chat o ticket
2
+
3
+ Un prompt suelto rara vez trae lo que un worker necesita. Este adaptador lo convierte en un brief bueno antes de repartir.
4
+
5
+ ## 1. Completa los huecos (sin preguntar lo deducible)
6
+ Para cada hueco, primero intenta deducirlo del repo; solo si cambia el resultado y no se puede deducir, pregunta. Máximo **una** pregunta con hasta 3 sub-puntos.
7
+ | Hueco | Dónde deducirlo |
8
+ |---|---|
9
+ | Qué ficheros/capa | grep/glob del dominio que nombra el usuario |
10
+ | Criterio de éxito | tests existentes, contratos, comportamiento actual |
11
+ | Comandos de verificación | `STACK.md` §3 |
12
+ | Restricciones | `STACK.md` §6, `ORCHESTRATION.md` |
13
+ | Fuera de alcance | lo que el usuario no ha pedido y está al lado |
14
+
15
+ ## 2. Reescribe la petición como brief
16
+ Antes de dividir, escribe en `.work/runs/<run>/request.md`:
17
+ ```
18
+ Objetivo: <qué existe al terminar>
19
+ Contexto: <por qué, para quién>
20
+ Restricciones: <stack, límites, decisiones cerradas>
21
+ Hecho cuando: <criterios observables>
22
+ Fuera de alcance: <...>
23
+ ASSUMPTION: <cada supuesto tomado>
24
+ ```
25
+ Muestra al usuario solo `Objetivo`, `Hecho cuando` y los `ASSUMPTION:` (≤6 líneas). Si los corrige, ajusta.
26
+
27
+ ## 3. Divide
28
+ - Por capa (datos / API / UI) si las capas tienen contrato claro entre ellas: primero el contrato (tipos, endpoint, esquema) en `U0`, luego capas en paralelo.
29
+ - Por funcionalidad vertical si las funcionalidades son independientes.
30
+ - Si no se divide limpio ⇒ una sola unidad, `ENGINE: inline`.
31
+
32
+ ## Ticket (GitHub/Linear/Jira)
33
+ Igual, tomando título → `goal`, descripción y criterios del ticket → `acceptance`, id del ticket → `source`. La rama del worker usa el id del ticket (`feat/<ticket>-<slug>`, `60-git-workflow.md`).
@@ -0,0 +1,18 @@
1
+ # Adaptador: plan nativo del agente
2
+
3
+ ## Claude Code (modo plan)
4
+ El plan aprobado está en la conversación (salida de plan mode). Pasos:
5
+ 1. Extrae los pasos numerados. Cada grupo de pasos que produce un incremento verificable = una unidad.
6
+ 2. Los ficheros que el plan menciona → `write`/`read`. Si el plan no los menciona, búscalos (grep/glob) antes de asignar; no los inventes.
7
+ 3. Persiste el plan original en `.work/runs/<run>/source-plan.md` para que no se pierda al compactar el contexto.
8
+
9
+ ## Antigravity (artefactos de planificación)
10
+ Antigravity genera `implementation_plan.md` y `task.md` como artefactos de la conversación.
11
+ 1. Pide al usuario que los adjunte o los copie, o léelos si están en el workspace. No asumas su ruta interna.
12
+ 2. `implementation_plan.md` → secciones "Proposed Changes" agrupadas por componente: cada componente = candidata a unidad; los ficheros `[NEW]`/`[MODIFY]` → `write`.
13
+ 3. `task.md` → checklist; las tareas sin marcar del componente van a `goal`/`notes`.
14
+ 4. "Verification Plan" → `verify` + `acceptance`.
15
+
16
+ ## Común
17
+ - Un plan nativo suele estar escrito para ejecución secuencial por un solo agente: revisa con especial cuidado los solapes de `write` antes de declarar paralelismo.
18
+ - Si el plan es corto (≤3 pasos, una capa) ⇒ `ENGINE: inline`, no repartas.
@@ -0,0 +1,20 @@
1
+ # Adaptador: plan en fichero (`planes/*.md`, `.plans/*.md`, salida de `plan.md`)
2
+
3
+ ## Formato esperado
4
+ El de `plan.md` (sprints con `Archivos`, `Depende de`, `Paralelo`, `Criterios de aceptación`). Si el plan es del antiguo `planificar` (sin esos campos), dedúcelos de la descripción del sprint y márcalos con `ASSUMPTION:`.
5
+
6
+ ## Mapeo
7
+ | Plan | Unidad |
8
+ |---|---|
9
+ | Sprint n | Unidad `Un` |
10
+ | `Archivos` (crear/modificar) | `write` |
11
+ | `Depende de: Sprint k` | `depends_on: [Uk]` |
12
+ | `Paralelo: sí` | candidato a misma ronda que sus hermanos (sujeto a solapes) |
13
+ | Criterios de aceptación | `acceptance` |
14
+ | Sprints marcados `[completado]` | se excluyen |
15
+
16
+ ## Diferencia clave con `planificar`
17
+ `planificar` exige aprobar el código de cada sprint en el chat antes de inyectarlo (human-in-the-loop por sprint). En MAW la aprobación se traslada al **diff**: el worker implementa en su worktree y el humano aprueba en la integración (`integrate.md`). Si el usuario quiere conservar la aprobación previa por sprint, `ENGINE: inline` y ejecuta los sprints uno a uno con `plan.md` modo 2.
18
+
19
+ ## Tras integrar
20
+ la integración (`integrate.md`) marca el sprint como `[completado] (merge <sha>)` en el fichero del plan. El worker nunca lo edita.
@@ -0,0 +1,42 @@
1
+ # Adaptador: spec-kit → unidades
2
+
3
+ **Si vienes del hook `before_implement`** (el usuario escribió `/speckit.implement`): ya estás en la sesión del coordinador. No vuelvas a invocar `/speckit.implement` ni lo pidas a los workers. Al terminar, todas las tareas integradas quedan `[x]` y el flujo de implement solo valida. Si decides «secuencial», no toques nada: implement sigue solo.
4
+
5
+ Precondición: existen `spec.md`, `plan.md` y `tasks.md` en `specs/<feature>/`. Si falta `tasks.md`: `BLOCKED: ejecuta /speckit.tasks primero`. Recomendado haber pasado `/speckit.analyze` sin hallazgos CRITICAL.
6
+
7
+ ## Lectura de tasks.md
8
+ Formato de línea: `- [ ] T014 [P] [US2] Descripción con ruta/al/fichero.ts`
9
+ - `T###` → id de tarea (se conserva en `source`).
10
+ - `[P]` → paralelizable **dentro** de su fase. No implica worker propio.
11
+ - `[USn]` → user story. Sin etiqueta = Setup, Foundational o Polish.
12
+ - Rutas en la descripción → candidatas a `write`.
13
+ - Tareas ya marcadas `[x]` se excluyen.
14
+
15
+ ## Mapeo
16
+ | spec-kit | Unidad MAW |
17
+ |---|---|
18
+ | Phase 1 Setup + Phase 2 Foundational | `U0`, `round: 0`, la hace el coordinador (o un único worker si es grande) |
19
+ | Cada `Phase n: User Story k` | Una unidad `Uk`, `size` según nº de tareas y ficheros |
20
+ | Phase final Polish / Cross-cutting | Última unidad, `round` = última + 1, tras integrar las stories |
21
+ | Tareas `[P]` dentro de una story | Se quedan en la misma unidad; el worker puede paralelizarlas con sus subagentes |
22
+
23
+ ## Campos
24
+ - `goal`: el **Goal** de la fase de la story + su prioridad (P1/P2…).
25
+ - `acceptance`: los "Acceptance Scenarios" (Given/When/Then) de esa story en `spec.md`, más el "Independent Test" de la fase.
26
+ - `read`: `spec.md` (solo la sección de esa story), `plan.md`, `data-model.md`, `contracts/*` que cite la story, `.specify/memory/constitution.md`.
27
+ - `notes`: decisiones de `plan.md` y de `research.md` que afecten a la story; principios de la constitución que apliquen (por nombre).
28
+ - `source`: `speckit specs/<feature>/tasks.md#USk (T0xx–T0yy)`.
29
+ - `agent`: por capa dominante de la story según `ORCHESTRATION.md` §Agentes.
30
+
31
+ ## Solapes típicos en spec-kit
32
+ Las stories se escriben "independientes", pero suelen compartir: router/rutas, esquema de BD, tipos de dominio, layout, navegación. Si dos stories escriben el mismo fichero:
33
+ 1. Si es infraestructura común → muévelo a `U0` (proponlo como `ASSUMPTION:` y anótalo para `/speckit.tasks` futuros).
34
+ 2. Si no → serializa por prioridad (P1 antes que P2).
35
+
36
+ ## Reglas para el worker (se copian a `notes` de cada unidad)
37
+ - No editar `tasks.md`, `spec.md`, `plan.md` ni la constitución. El coordinador marca `[x]` al integrar.
38
+ - No ejecutar `/speckit.implement` completo: implementa solo las tareas `T0xx–T0yy` de su unidad, en el orden de `tasks.md` (tests antes si la spec los pide).
39
+ - Si encuentra un hueco en la spec: `ask`/`BLOCKED:` al coordinador, no inventa requisito.
40
+
41
+ ## Tras integrar (lo hace la integración (`integrate.md`))
42
+ Marcar `[x]` las tareas de las unidades integradas en `tasks.md`, en un commit del coordinador: `chore(spec): marcar US2 completada`.
@@ -0,0 +1,30 @@
1
+ # Motor: manual (worktrees + humano)
2
+
3
+ Para cuando no hay Orca ni subagentes, o se mezclan proveedores sin Orca.
4
+
5
+ ## 1. Crear worktrees
6
+ Desde el checkout principal, por cada unidad de la ronda:
7
+ ```bash
8
+ git worktree add ../<repo>-wt/<run>-u2 -b maw/<run>/u2 <sha-base>
9
+ ```
10
+ Después, en cada worktree, el setup de `ORCHESTRATION.md` §Entorno (por ejemplo copiar `.env.local` de desarrollo, `pnpm install` o symlink de `node_modules`).
11
+
12
+ ## 2. Dejar el brief
13
+ Escribe el mensaje de despacho en `<worktree>/.work/BRIEF.md` (dentro del worktree, ignorado por git) y en `.work/runs/<run>/briefs/<unit>.md` del principal.
14
+
15
+ ## 3. Instrucciones al usuario (una sola vez, en bloque)
16
+ ```
17
+ Abre un agente en cada carpeta y pégale: «Ejecuta .work/BRIEF.md con la skill worker-contract.md»
18
+ U1 → ../<repo>-wt/<run>-u1 (Claude Code)
19
+ U2 → ../<repo>-wt/<run>-u2 (Antigravity)
20
+ Cuando terminen, dime «ronda lista».
21
+ ```
22
+
23
+ ## 4. Recoger
24
+ Cada worker escribe su informe en `<worktree>/.work/REPORT.md`. Léelos, cópialos a `.work/runs/<run>/reports/` y pasa a la integración (`integrate.md`).
25
+
26
+ ## 5. Limpieza (tras integrar, con confirmación)
27
+ ```bash
28
+ git worktree remove ../<repo>-wt/<run>-u2
29
+ git branch -d maw/<run>/u2 # -d, no -D: falla si no está mergeada
30
+ ```
@@ -0,0 +1,36 @@
1
+ # Motor: Orca
2
+
3
+ Requisitos: Orca abierto, **Settings → Experimental → Orchestration** activado, skills `orca-cli` y `orchestration` instaladas (`npx skills add https://github.com/stablyai/orca --skill orchestration --global`).
4
+
5
+ ## Regla de oro
6
+ Los flags de Orca cambian con cada versión. **Antes del primer comando de cada sesión** carga la guía de tu binario y úsala por encima de este fichero:
7
+ ```
8
+ orca skills get orchestration
9
+ ```
10
+ (Resolución del ejecutable: `ORCA_CLI_COMMAND` si existe; en Linux fuera de Orca, `orca-ide`; si no, `orca`.) No inventes flags; ante la duda, `--help`.
11
+
12
+ ## Flujo de referencia (validar contra la guía)
13
+ ```bash
14
+ orca status --json # Orca vivo
15
+ orca orchestration run-create --objective "<run-id>: <objetivo>" --json
16
+ # por cada unidad de la ronda:
17
+ orca orchestration task-create --task-title "U2 <título>" --spec "<mensaje de despacho completo>" --json
18
+ orca orchestration worker-start --task <taskId> --worktree new-child --name <run>-u2 \
19
+ --agent <claude|antigravity|codex|...> --setup run --json
20
+ # supervisión:
21
+ orca orchestration check --wait --types worker_done,escalation,question --timeout-ms 900000 --json
22
+ orca orchestration check --ack <deliveryId> ... # procesar cada entrega y confirmar
23
+ # preguntas de workers: responder por el canal que indique la guía
24
+ # al terminar una unidad aceptada:
25
+ orca orchestration worker-release --dispatch <dispatchId> --json
26
+ ```
27
+
28
+ ## Notas
29
+ - `--worktree new-child` crea un worktree hijo del actual: parte del commit base de la ronda.
30
+ - `--setup run` ejecuta los hooks de setup del repo (install, `.worktreeinclude`, `orca.yaml`).
31
+ - Modelo por worker: `--model <id> --effort <nivel>` (solo agentes que lo soportan; ver guía). Úsalo para unidades `L` o de razonamiento duro.
32
+ - Antigravity como worker: solo en local (no por SSH).
33
+ - El informe del worker llega en el `--body` de `worker_done`; `--files-modified` sirve para validar `write`.
34
+ - Checkpoints visibles: pide a los workers `orca worktree set --worktree active --comment "<estado>" --workspace-status in-progress|in-review`.
35
+ - No uses `orca orchestration reset` si hay otro coordinador activo.
36
+ - Fallo de Orca a mitad de run: no relances todo; `task-list` para ver estado y continúa con `manual` para lo pendiente.
@@ -0,0 +1,19 @@
1
+ # Motor: subagentes nativos
2
+
3
+ Un solo proveedor, sin Orca. Más barato de montar; menos visibilidad.
4
+
5
+ ## Claude Code
6
+ - Lanza un subagente por unidad con la herramienta de agentes/tareas del entorno, con **aislamiento en worktree** si está disponible (opción de worktree/isolation). Sin aislamiento, dos subagentes comparten checkout ⇒ solo paralelo si sus `write` son disjuntos **y** no ejecutan instaladores, migraciones ni servidores; en caso contrario, secuencial.
7
+ - Prompt del subagente = mensaje de despacho completo (`SKILL.md` §5).
8
+ - El informe es el mensaje final del subagente: exígelo con el formato de `worker-contract.md`.
9
+ - Agent Teams / modos de varios agentes del producto sirven igual; las reglas de `write` y `shared` no cambian.
10
+
11
+ ## Antigravity
12
+ - Usa el Agent Manager: una conversación/agente por unidad, cada uno en su propio worktree o workspace. Si el entorno no crea worktrees, créalos tú con `engine-manual.md` §1 y abre cada agente sobre su carpeta.
13
+ - Pega el mensaje de despacho como primer mensaje del agente.
14
+ - Recoge el informe del final de cada conversación.
15
+
16
+ ## Común
17
+ - Límite práctico: 3 subagentes simultáneos.
18
+ - Los subagentes no ven tu conversación: todo el contexto va en el despacho.
19
+ - Al terminar, la integración es igual: la integración (`integrate.md`).
@@ -0,0 +1,37 @@
1
+ # Integrar una ronda
2
+
3
+ Entrada: informes en `.work/runs/<run>/reports/` de la ronda actual.
4
+
5
+ ## 1. Revisión por unidad (antes de mergear nada)
6
+ Para cada rama de worker, `git diff <base>...maw/<run>/<unit>` y comprueba:
7
+ 1. **Alcance**: ficheros ⊆ `write`. Extra ⇒ ¿justificado en el informe? Si no, se revierte esa parte o vuelve al worker.
8
+ 2. **Acceptance**: cada criterio verificado de verdad (comando o prueba citada). Marcado sin evidencia ⇒ trátalo como no hecho.
9
+ 3. **Calidad**: criterios de bloqueo de `60-git-workflow.md` §Revisión (corrección, seguridad, pérdida de datos, contrato roto, falta de test). No bloquees por estilo que impone el formateador.
10
+ 4. **Contratos entre unidades**: si dos unidades hablan entre sí (API ↔ UI, tipos), que coincidan.
11
+ Resultado por unidad: `accept` · `rework` (con lista concreta de cambios, de vuelta al mismo worker) · `discard`.
12
+ Opcional: en Orca, el usuario puede revisar con Annotate AI Diff y devolver comentarios al worker.
13
+
14
+ ## 2. Orden de merge
15
+ Prioridad de la unidad (P1 antes que P2) → dependencias → la que menos `shared` toca primero.
16
+
17
+ ## 3. Integrar en la rama de integración
18
+ Con autonomía `semi` o `auto`, la confirmación 1 del run ya autoriza estos commits y merges (solo en ramas de trabajo y en la rama de integración, nunca en la de por defecto). Con `manual`, pide un «sí» por ronda. Si un worker no hizo commits, haz tú un commit atómico en su worktree con los cambios revisados (`feat(<ámbito>): <unidad>`). Luego, por unidad:
19
+ ```bash
20
+ git switch feat/<feature> # rama de integración del run
21
+ git merge --no-ff maw/<run>/<unit>
22
+ ```
23
+ Conflicto ⇒ `95-multi-agent.md` §Conflictos. Nunca `--force`, nunca a la rama por defecto sin que el usuario lo pida.
24
+
25
+ ## 4. Puerta sobre el resultado combinado
26
+ Si la ronda tocó UI y existe `impeccable`: `impeccable audit` sobre las vistas cambiadas (a11y, rendimiento, responsive) antes de los gates.
27
+ `csr-gate` completo tras mergear la ronda. Que cada unidad pasara sola no garantiza que pasen juntas. Fallo ⇒ arregla tú la integración (es trabajo del coordinador) y repite.
28
+
29
+ ## 5. Actualizar estado (el coordinador es el único que escribe aquí)
30
+ - spec-kit: marcar `[x]` las tareas de las unidades integradas en `tasks.md`.
31
+ - plan: `[completado] (merge <sha>)` en el sprint de `planes/*.md`.
32
+ - Orca: `worker-release` de cada dispatch aceptado; comentario del worktree principal con el estado del run.
33
+ - `.work/runs/<run>/run.md`: ronda cerrada, sha resultante.
34
+
35
+ ## 6. Limpieza
36
+ Tras el merge final (confirmación 2): worktrees y ramas de unidades integradas con `git worktree remove` + `git branch -d` (o `worker-release` en Orca). Las ramas de unidades `discard` solo se borran si el usuario lo confirma.
37
+
@@ -0,0 +1,48 @@
1
+ # Planificar por sprints (sustituye a «planificar»)
2
+
3
+ Para peticiones grandes sin plan ni spec. Mantiene los dos modos de `planificar` (plan maestro y sprint con visto bueno) y añade el paralelo.
4
+
5
+ ## MODO 1 — Plan maestro
6
+ Disparador: idea grande, refactor o feature compleja sin plan previo.
7
+ 1. Analiza dependencias, ficheros y lógica afectados (búsqueda dirigida; `STACK.md`, `ORCHESTRATION.md`, `AGENTS.md`).
8
+ 2. Divide en sprints. Cada sprint = incremento verificable por sí solo. Prefiere sprints verticales (una funcionalidad completa) a horizontales (toda la BD, luego toda la API…), salvo un Sprint 0 de base común.
9
+ 3. Escribe `planes/<feature>.md` (o `.plans/` si el proyecto lo indica) con este formato exacto:
10
+ ```markdown
11
+ # Plan: <feature>
12
+ Objetivo: <1–2 líneas> · Creado: AAAA-MM-DD · Estado: en curso
13
+
14
+ ## Sprint 0 — Base común <!-- solo si hace falta -->
15
+ - Objetivo:
16
+ - Archivos: crear [..] · modificar [..]
17
+ - Depende de: —
18
+ - Paralelo: no (lo hace el coordinador)
19
+ - Criterios de aceptación:
20
+ - ...
21
+ - Verificación: <comandos de STACK.md §3>
22
+
23
+ ## Sprint 1 — <título>
24
+ - Objetivo:
25
+ - Archivos: crear [..] · modificar [..]
26
+ - Depende de: Sprint 0
27
+ - Paralelo: sí (con Sprint 2) <!-- sí solo si sus Archivos no se cortan con los del otro -->
28
+ - Agente sugerido: claude | antigravity | cualquiera
29
+ - Criterios de aceptación:
30
+ - ...
31
+ - Verificación:
32
+ ```
33
+ 4. Al usuario: ruta del plan + tabla `sprint | depende | paralelo` (nada más). Pregunta una sola cosa: ¿sprint a sprint con visto bueno (modo 2) o en paralelo con orca (modo 3)?
34
+
35
+ ## MODO 2 — Ejecutar un sprint (secuencial, human-in-the-loop)
36
+ Disparador: "comienza el Sprint N de planes/<feature>.md".
37
+ 1. Lee el plan y el sprint. No toques código todavía.
38
+ 2. Presenta el plan de implementación del sprint: arquitectura, funciones, y los fragmentos de código finales (o el diff propuesto si es largo, por fichero).
39
+ 3. Pregunta: «¿Me das tu visto bueno para aplicar este sprint?». Solo con un sí:
40
+ 4. Aplica, pasa `csr-gate`, y marca el sprint `[completado]` en el plan con fecha.
41
+
42
+ ## MODO 3 — Ejecutar en paralelo
43
+ Disparador: el usuario elige paralelo, o "lanza los sprints N y M". Vuelve a `SKILL.md` §2 con el adaptador `plan-file`. La aprobación pasa del código propuesto al plan de rondas y al merge final. El plan lo actualiza solo el coordinador.
44
+
45
+ ## Reglas
46
+ - Un sprint que toca >10 ficheros o varias capas sin contrato entre ellas: divídelo.
47
+ - `Paralelo: sí` es una promesa: compruébala con los `Archivos` reales antes de escribirla.
48
+ - El plan es documentación viva: si un sprint cambia de alcance al implementarse, actualiza su sección (coordinador) y anótalo.
@@ -0,0 +1,35 @@
1
+ # Modo carrera: varios agentes, un problema
2
+
3
+ Para bugs difíciles de causa desconocida o decisiones con 2–3 enfoques plausibles. Cuesta N veces más: úsalo solo cuando el usuario lo pida o la incertidumbre lo justifique.
4
+
5
+ ## Cuándo no usarla
6
+ Bug con causa visible en un stack trace, cambio mecánico, o unidad `S`. Una carrera multiplica el coste por N.
7
+
8
+ ## 1. Unidad única
9
+ Con el adaptador que toque (`adapters/chat.md` normalmente) genera **una** unidad. Refuerza:
10
+ - `acceptance` con un test de reproducción que hoy falla (si es bug). Si no existe, escríbelo tú primero en la base: sin él, no hay forma objetiva de comparar.
11
+ - `notes`: "Enfoque libre. Explica en el informe por qué elegiste el tuyo."
12
+
13
+ ## 2. Participantes
14
+ 2–3 agentes de **proveedores distintos** (Claude, Antigravity/Gemini, Codex…) o el mismo con modelos distintos. Mismo despacho, palabra por palabra. Motor: `orca` (ideal) o `manual`.
15
+ Variante "enfoques dirigidos": en vez de enfoque libre, asigna un enfoque por participante en `notes` (por ejemplo A: arreglar en el servicio; B: arreglar en la consulta).
16
+
17
+ ## 3. Comparación (tabla fija)
18
+ | criterio | peso | A | B | C |
19
+ |---|---|---|---|---|
20
+ | Test de reproducción pasa | bloqueante | | | |
21
+ | Gates (`csr-gate`) sin FAIL | bloqueante | | | |
22
+ | Causa raíz vs. síntoma | 3 | | | |
23
+ | Tamaño del diff (menor mejor) | 2 | | | |
24
+ | Ficheros fuera de `write` | 2 | | | |
25
+ | Riesgo (seguridad, datos, contrato) | 3 | | | |
26
+ | Legibilidad / encaje con el código existente | 1 | | | |
27
+ Puntúa 0–2 por criterio. Lee los diffs de verdad; no puntúes por el informe.
28
+
29
+ ## 4. Salida
30
+ ```
31
+ race U1 · ganador: B (antigravity) · 11/13
32
+ A: arregla el síntoma (añade retry); B: corrige el orden de await en payment.service.ts:88
33
+ mezcla sugerida: test extra de A (concurrencia) sobre la solución de B
34
+ ```
35
+ Después: integra (`integrate.md`) solo la ganadora (más los añadidos que el usuario apruebe). Las ramas perdedoras se borran con confirmación.
@@ -0,0 +1,26 @@
1
+ # Preparar la orquestación de un repo
2
+
3
+ Genera o actualiza `ORCHESTRATION.md`, `orca.yaml`, `.worktreeinclude` y `.work/` en `.gitignore`.
4
+
5
+ ## Procedimiento
6
+ 1. **Requisito**: `STACK.md` rellena. Si falta o es la plantilla vacía, ejecuta `csr-stack` primero. Normalmente lo hace `kit-init`.
7
+ 2. **Detecta**:
8
+ - Gestor de paquetes y dirs pesados regenerables: `node_modules`, `.next/cache`, `.turbo`, `.venv`, `target/`… → candidatos a `sharedDirectories`.
9
+ - Ficheros de entorno: `.env*` existentes y `.env.example`. Solo los de **desarrollo** van a `.worktreeinclude`.
10
+ - BD local: `docker-compose*.yml`, `supabase/config.toml`, URLs en `.env.example` → estrategia de BD por worktree.
11
+ - Servidores de dev y su puerto por defecto → `PORT_BASE`.
12
+ - Ficheros calientes (`95-multi-agent.md` §Solapes) que existan de verdad en el repo → lista `shared`.
13
+ - Capas/monorepo (`apps/*`, `packages/*`, `frontend/`, `backend/`) → filas de la tabla de agentes.
14
+ - spec-kit (`.specify/`), planes (`planes/`), Orca (`orca.yaml`).
15
+ 3. **Escribe** desde las plantillas de `~/.agents/templates/` (las deja el instalador; si no existen, usa `templates/` del kit `Orca Multiagent Kit`):
16
+ - `ORCHESTRATION.md` (preservando lo escrito a mano si ya existe).
17
+ - `orca.yaml` con `worktree.sharedDirectories` — solo directorios que **existen y están en `.gitignore`** (Orca ignora los demás).
18
+ - `.worktreeinclude` — solo ficheros gitignorados, rutas literales (sin globs).
19
+ - `.gitignore`: añade `.work/` si falta.
20
+ 4. **Pregunta** como máximo 3 cosas, en una tanda: reparto de agentes por capa, nivel de autonomía (`manual` / `semi` / `auto`; propón `semi`) y si los workers pueden hacer commits locales. Límite de workers: 3 salvo que el usuario diga otra cosa.
21
+ 5. **Reporta** en 2 líneas: qué se creó y qué quedó `TODO:`.
22
+
23
+ ## Reglas
24
+ - Nunca pongas en `.worktreeinclude` ficheros con credenciales de producción. Si el único `.env` tiene secretos reales: `RISK:` y propón `.env.development.local` sin secretos de producción.
25
+ - No toques `STACK.md` (es de `csr-stack`).
26
+ - `ORCHESTRATION.md` y `orca.yaml` se commitean (son del proyecto); `.work/` no.
@@ -0,0 +1,44 @@
1
+ # Unidades de trabajo (formato común)
2
+
3
+ Toda entrada acaba en este formato antes de repartirse. Es el contrato entre coordinador y workers: no cambies los nombres de campo.
4
+
5
+ ## Formato de unidad (contrato — no cambiar nombres de campo)
6
+ ```markdown
7
+ ### UNIT: U2 — Endpoint POST /recargas
8
+ - source: speckit specs/003-recargas/tasks.md#US2 (T014–T019)
9
+ - goal: <1–2 frases: qué existe al terminar que antes no existía>
10
+ - write: [server/src/routes/recargas.ts, server/src/services/recarga.service.ts, server/tests/recargas.test.ts]
11
+ - read: [server/src/db/schema.ts, specs/003-recargas/contracts/recargas.yaml]
12
+ - shared: [] # ficheros de la lista shared que necesita tocar (normalmente vacío)
13
+ - depends_on: [U0]
14
+ - round: 1
15
+ - size: M
16
+ - agent: claude | antigravity | any # sugerencia; ORCHESTRATION.md §Agentes manda
17
+ - acceptance:
18
+ - POST /recargas con importe válido devuelve 201 y persiste la recarga
19
+ - importe ≤0 o tarjeta inexistente → 422 con código de error del contrato
20
+ - verify: [pnpm --filter server test recargas, pnpm --filter server typecheck] # de STACK.md §3
21
+ - out_of_scope: [UI de recarga (U3), notificaciones]
22
+ - notes: <decisiones ya tomadas que el worker no debe reabrir>
23
+ ```
24
+ Reglas del formato:
25
+ - `write` con rutas reales o globs estrechos (`src/features/recargas/**`). Nunca `src/**`.
26
+ - `acceptance` observable y comprobable. "Funciona bien" no vale.
27
+ - `verify` sale de `STACK.md` §3. Si un comando no existe: `N/A` + `RISK:`.
28
+ - `notes` lleva el contexto que el worker no puede deducir (decisiones de spec/plan, convenciones no escritas). Es lo que evita que el worker pregunte o reinvente.
29
+
30
+ ## Unidad 0 (coordinador)
31
+ Todo lo que varias unidades necesitan y toca `shared` (esquema de BD, tipos compartidos, rutas centrales, dependencias nuevas) va a `U0`, `round: 0`. La hace el coordinador antes de repartir y hace commit; las rondas parten de ese commit.
32
+
33
+ ## Grafo y rondas
34
+ Calcula `depends_on` explícito + solapes de `write` (`~/.agents/rules/95-multi-agent.md` §Solapes). `round: 0` es lo que hace el coordinador antes de repartir.
35
+
36
+ ## Salida (al usuario)
37
+ ```
38
+ run: 20261107-recargas · entrada: speckit · unidades: 4
39
+ round | unidades | paralelo
40
+ 0 | U0 (setup+found)| coordinador
41
+ 1 | U1, U2 | sí
42
+ 2 | U3 | — (depende de U1: comparte src/app/layout.tsx)
43
+ RISK: U2 sin test de integración en STACK.md §3
44
+ ```
@@ -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 -->