orca-multiagent-kit 1.6.0 → 1.7.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 (71) hide show
  1. package/AI_INSTALL.md +4 -3
  2. package/CHANGELOG.md +41 -1
  3. package/GUIA.html +11 -9
  4. package/README.md +22 -23
  5. package/VERSION +1 -1
  6. package/bin/backup.js +44 -0
  7. package/bin/fetch.js +243 -0
  8. package/bin/hooks.js +187 -0
  9. package/bin/omk.js +127 -51
  10. package/bin/run/cleanup.js +402 -0
  11. package/bin/run/git.js +641 -0
  12. package/bin/run/glob.js +193 -0
  13. package/bin/run/ledger.js +243 -0
  14. package/bin/run/plan.js +328 -0
  15. package/bin/run/units.js +101 -0
  16. package/bin/run/util.js +116 -0
  17. package/bin/run.js +224 -0
  18. package/bin/setup.js +81 -8
  19. package/bin/sync.js +222 -0
  20. package/bin/ui.js +8 -4
  21. package/bin/update.js +169 -0
  22. package/core/AGENTS.md +7 -7
  23. package/docs/EJECUTABLE.md +5 -4
  24. package/docs/MANUAL.md +16 -3
  25. package/docs/ORQUESTADOR.md +59 -1
  26. package/docs/PLUGIN-ORCA.md +34 -16
  27. package/hooks/orca-gate.cjs +402 -0
  28. package/install.sh +26 -13
  29. package/orca-plugin/README.md +3 -1
  30. package/orca-plugin/orca-plugin.json +2 -2
  31. package/orca-plugin/src/kit.test.ts +35 -13
  32. package/orca-plugin/src/kit.ts +64 -19
  33. package/orca-plugin/src/panel-state.ts +11 -3
  34. package/orca-plugin/src/panel.check.ts +71 -0
  35. package/orca-plugin/src/panel.test.tsx +69 -4
  36. package/orca-plugin/src/panel.tsx +32 -16
  37. package/orca-plugin/src/protocol.ts +39 -0
  38. package/orca-plugin/src/tabs/autonomy.tsx +3 -1
  39. package/orca-plugin/src/tabs/history.test.tsx +1 -0
  40. package/orca-plugin/src/tabs/history.tsx +1 -0
  41. package/orca-plugin/src/tabs/notices.test.tsx +1 -0
  42. package/orca-plugin/src/tabs/worktrees.test.tsx +1 -0
  43. package/orca-plugin/src/ui/action-card.tsx +112 -0
  44. package/orca-plugin/src/worker/actions.test.ts +288 -0
  45. package/orca-plugin/src/worker/actions.ts +292 -0
  46. package/orca-plugin/src/worker/context.ts +4 -1
  47. package/orca-plugin/src/worker/history.ts +3 -3
  48. package/orca-plugin/src/worker/notices.ts +1 -4
  49. package/orca-plugin/src/worker.test.ts +24 -6
  50. package/orca-plugin/src/worker.ts +79 -83
  51. package/output-styles/csr-minimal.md +1 -0
  52. package/package.json +3 -3
  53. package/rules/50-done-gate.md +1 -1
  54. package/rules/95-multi-agent.md +13 -3
  55. package/skills/kit-init/SKILL.md +16 -4
  56. package/skills/orca/SKILL.md +27 -5
  57. package/skills/orca/references/adapters/artifact.md +2 -0
  58. package/skills/orca/references/adapters/chat.md +2 -0
  59. package/skills/orca/references/adapters/native-plan.md +6 -0
  60. package/skills/orca/references/adapters/plan-file.md +2 -0
  61. package/skills/orca/references/engine-manual.md +7 -5
  62. package/skills/orca/references/engine-subagents.md +4 -4
  63. package/skills/orca/references/integrate.md +14 -2
  64. package/skills/orca/references/ledger.md +1 -1
  65. package/skills/orca/references/olimpo.md +1 -1
  66. package/skills/orca/references/plan.md +2 -1
  67. package/skills/orca/references/units.md +1 -1
  68. package/skills/orca/references/worker-contract.md +2 -2
  69. package/templates/AGENTS.md +2 -2
  70. package/templates/CLAUDE.md +1 -1
  71. package/templates/claude-settings.json +25 -0
@@ -98,8 +98,9 @@ test('el ajuste off desactiva el hook', async () => {
98
98
  test('verificar abre un terminal con el literal omk verify en el workspace activo', async () => {
99
99
  const w = await start()
100
100
  const result = await w.command('kit.verify')
101
+ // `--exit-marker`: omk escribe al salir la línea con la que el plugin sabe que ha terminado.
101
102
  assert.deepEqual(w.host.callsOf('terminal.create'), [
102
- { workspaceId: 'w1', title: 'omk verify', command: 'omk verify' }
103
+ { workspaceId: 'w1', title: 'omk verify', command: 'omk verify --exit-marker' }
103
104
  ])
104
105
  assert.equal(result, 'Ejecutando `omk verify` en un terminal nuevo del workspace activo.')
105
106
  assert.deepEqual(w.refusals, [])
@@ -108,7 +109,7 @@ test('verificar abre un terminal con el literal omk verify en el workspace activ
108
109
  test('actualizar usa omk update', async () => {
109
110
  const w = await start()
110
111
  await w.command('kit.update')
111
- assert.equal((w.host.callsOf('terminal.create')[0] as { command: string }).command, 'omk update')
112
+ assert.equal((w.host.callsOf('terminal.create')[0] as { command: string }).command, 'omk update --exit-marker')
112
113
  })
113
114
 
114
115
  test('sin workspace identificable no ejecuta nada y lo avisa', async () => {
@@ -132,6 +133,20 @@ test('un fallo de Orca al crear el terminal se notifica, no se calla', async ()
132
133
  assert.equal(w.host.callsOf('notifications.show').length, 1)
133
134
  })
134
135
 
136
+ test('desde el panel, un fallo vuelve como error con su código, no como respuesta', async () => {
137
+ const w = await start({ results: { 'workspace.readContext': null } })
138
+ await assert.rejects(
139
+ w.request('kit.run', { action: 'verify' }),
140
+ (error: unknown) => (error as { code?: string }).code === 'unavailable' && /No identifico el workspace activo/.test(String(error))
141
+ )
142
+ const bad = await start({ settings: { initAgent: 'claude; rm -rf ~' } })
143
+ await assert.rejects(
144
+ bad.request('kit.run', { action: 'init' }),
145
+ (error: unknown) => (error as { code?: string }).code === 'invalid_params'
146
+ )
147
+ assert.equal(bad.host.callsOf('agent.launch').length, 0)
148
+ })
149
+
135
150
  test('inicializar lanza el agente configurado con «inicializa el proyecto»', async () => {
136
151
  const w = await start({ settings: { initAgent: 'codex' } })
137
152
  await w.command('kit.init')
@@ -326,18 +341,21 @@ test('aplicar el equipo ejecuta omk team set con el equipo en base64url', async
326
341
  }
327
342
  await w.request('team.apply', { team })
328
343
  assert.deepEqual(w.host.callsOf('terminal.create'), [
329
- { workspaceId: 'w1', title: 'omk team', command: `omk team set --data ${encodeTeam(team)}` }
344
+ { workspaceId: 'w1', title: 'omk team set', command: `omk team set --data ${encodeTeam(team)} --exit-marker` }
330
345
  ])
331
- assert.match((w.host.callsOf('terminal.create')[0] as { command: string }).command, /^omk team set --data [A-Za-z0-9_-]+$/)
346
+ assert.match(
347
+ (w.host.callsOf('terminal.create')[0] as { command: string }).command,
348
+ /^omk team set --data [A-Za-z0-9_-]+ --exit-marker$/
349
+ )
332
350
  await w.request('team.show')
333
- assert.equal((w.host.callsOf('terminal.create')[1] as { command: string }).command, 'omk team')
351
+ assert.equal((w.host.callsOf('terminal.create')[1] as { command: string }).command, 'omk team --exit-marker')
334
352
  })
335
353
 
336
354
  test('la autonomía del proyecto va con una orden literal y nada más', async () => {
337
355
  const w = await start()
338
356
  await w.request('team.autonomy', { autonomy: 'auto' })
339
357
  assert.deepEqual(w.host.callsOf('terminal.create'), [
340
- { workspaceId: 'w1', title: 'omk team', command: 'omk team set --autonomy auto' }
358
+ { workspaceId: 'w1', title: 'omk team set --autonomy auto', command: 'omk team set --autonomy auto --exit-marker' }
341
359
  ])
342
360
  for (const autonomy of ['total', 'auto; rm -rf ~', '', null]) {
343
361
  await assert.rejects(
@@ -1,12 +1,12 @@
1
1
  // Worker del plugin: comandos de paleta del kit, referencia al contrato del worker en los
2
2
  // despachos de orquestación, la skill orca en los prompts de arranque, los agentes con nombre en
3
3
  // la barra de estado y el panel, sus avisos, y las peticiones del panel (acciones, equipo y repartir).
4
- // Las pestañas Avisos, Worktrees e Historial viven en src/worker/: este núcleo oye a Orca una sola
5
- // vez y les reparte los sucesos (src/worker/context.ts).
4
+ // Las pestañas Avisos, Worktrees e Historial y el seguimiento de la acción en curso viven en
5
+ // src/worker/: este núcleo oye a Orca una sola vez y les reparte los sucesos (src/worker/context.ts).
6
6
  // Orca transpila este fichero al cargarlo: no hay paso de build.
7
7
  import type { OrcaWorkerApi } from 'orca/worker'
8
8
  import {
9
- INSTALL_HINT,
9
+ EXIT_MARKER_FLAG,
10
10
  TASK_MAX,
11
11
  blockedNotice,
12
12
  cleanLabel,
@@ -19,13 +19,11 @@ import {
19
19
  indexWorkspaces,
20
20
  isAutonomy,
21
21
  isKitAction,
22
- isMissingCommand,
23
22
  isValidAgentId,
24
23
  orchestratePrompt,
25
24
  parseContractHintMode,
26
25
  parseDispatch,
27
26
  parseTeam,
28
- pollUntil,
29
27
  resolveFocusedWorkspaceId,
30
28
  summarizeAgents,
31
29
  teamCommand,
@@ -41,6 +39,7 @@ import {
41
39
  type WorkspaceIndex
42
40
  } from './kit.ts'
43
41
  import type { AgentsView } from './protocol.ts'
42
+ import { registerActions } from './worker/actions.ts'
44
43
  import { createBus, type KitContext, type TerminalInfo } from './worker/context.ts'
45
44
  import { createNodeSystem, type KitSystem } from './worker/system.ts'
46
45
  import { registerHistory } from './worker/history.ts'
@@ -50,8 +49,6 @@ import { registerWorktrees } from './worker/worktrees.ts'
50
49
  const STATUS_ITEM = 'agents'
51
50
  const INIT_PROMPT = 'inicializa el proyecto'
52
51
  const DEFAULT_INIT_AGENT = 'claude'
53
- // `omk verify` tarda poco; si en ~15 s no hay error de "comando no encontrado", existe.
54
- const MISSING_CHECK = { attempts: 10, delayMs: 1500 }
55
52
  // Terminales de los que se recuerda qué agente y qué unidad llevan; los más antiguos se olvidan.
56
53
  const TERMINALS_MAX = 200
57
54
  const NO_WORKSPACE =
@@ -59,7 +56,7 @@ const NO_WORKSPACE =
59
56
 
60
57
  type OmkSubcommand = 'verify' | 'update'
61
58
 
62
- // Esperas pendientes de las comprobaciones de `omk`: `deactivate` las cancela al parar el worker.
59
+ // Esperas pendientes del seguimiento de acciones: `deactivate` las cancela al parar el worker.
63
60
  const pendingTimers = new Set<ReturnType<typeof setTimeout>>()
64
61
  const sleep = (ms: number) =>
65
62
  new Promise<void>((resolve) => {
@@ -81,11 +78,11 @@ export function deactivate(): void {
81
78
  const describeError = (error: unknown) =>
82
79
  error instanceof Error ? `${(error as { code?: string }).code ?? 'error'}: ${error.message}` : String(error)
83
80
 
84
- // Lo que responde `runOmk` cuando abre el terminal; cualquier otra respuesta es un fallo ya avisado.
85
81
  const running = (command: string) => `Ejecutando \`${command}\` en un terminal nuevo del workspace activo.`
86
82
 
87
83
  // Un `code` de error del host llega tal cual al panel (`plugin.request` lo rechaza con él).
88
- const invalidParams = (message: string) => Object.assign(new Error(message), { code: 'invalid_params' })
84
+ const failure = (code: string, message: string) => Object.assign(new Error(message), { code })
85
+ const invalidParams = (message: string) => failure('invalid_params', message)
89
86
 
90
87
  export default async function activate(orca: OrcaWorkerApi): Promise<void> {
91
88
  const { host } = orca
@@ -121,8 +118,9 @@ export default async function activate(orca: OrcaWorkerApi): Promise<void> {
121
118
  if (notice) bus.emit('runDone', { run, notice, at })
122
119
  }
123
120
 
124
- // Un fallo de Orca en un comando se cuenta al usuario; nunca se queda en silencio.
125
- const guarded = (label: string, run: () => Promise<string>) => async () => {
121
+ // Desde la paleta no hay panel que enseñe el error: un fallo se notifica y es lo que responde
122
+ // el comando; nunca se queda en silencio.
123
+ const fromPalette = (label: string, run: () => Promise<string>) => async () => {
126
124
  try {
127
125
  return await run()
128
126
  } catch (error) {
@@ -133,6 +131,16 @@ export default async function activate(orca: OrcaWorkerApi): Promise<void> {
133
131
  }
134
132
  }
135
133
 
134
+ // Desde el panel el error vuelve a él con su `code` y lo enseña; aquí solo queda en el log.
135
+ const fromPanel = async (label: string, run: () => Promise<string>) => {
136
+ try {
137
+ return { message: await run() }
138
+ } catch (error) {
139
+ orca.log(`${label}: ${describeError(error)}`)
140
+ throw error
141
+ }
142
+ }
143
+
136
144
  const canonical = (workspaceId: string | null) =>
137
145
  workspaceId === null ? null : canonicalWorkspaceId(workspaceId, workspaces)
138
146
 
@@ -246,56 +254,64 @@ export default async function activate(orca: OrcaWorkerApi): Promise<void> {
246
254
  }
247
255
  }
248
256
 
249
- const warnIfOmkMissing = async (terminalId: string) => {
250
- const missing = await pollUntil(
251
- async () => (await host.call('terminal.read', { terminalId, maxLines: 40 })).lines,
252
- (lines) => isMissingCommand(lines),
253
- { ...MISSING_CHECK, sleep }
254
- )
255
- if (missing) notify('omk no está instalado', INSTALL_HINT)
257
+ const ctx: KitContext = {
258
+ host,
259
+ panels: orca.panels,
260
+ storage: orca.storage,
261
+ system: hostSystem.current,
262
+ log: (message) => orca.log(message),
263
+ notify: (title, body) => {
264
+ if (notifyEnabled) notify(title, body)
265
+ },
266
+ agents,
267
+ terminals,
268
+ workspaces: () => workspaces,
269
+ workspaceName,
270
+ refreshWorkspaces,
271
+ ...bus
256
272
  }
273
+ const tracker = registerActions(ctx, sleep)
257
274
 
258
- // `command` es siempre un literal o sale de `teamCommand` (ids validados): nunca se interpola
259
- // texto libre del usuario ni de terceros en el terminal.
260
- const runOmk = (title: string, command: string) =>
261
- guarded(title, async () => {
262
- const workspaceId = await focusedWorkspaceId()
263
- if (!workspaceId) {
264
- notify('Orca Multiagent Kit', NO_WORKSPACE)
265
- return NO_WORKSPACE
266
- }
267
- const { terminalId } = await host.call('terminal.create', { workspaceId, title, command })
268
- void warnIfOmkMissing(terminalId).catch((error: unknown) => {
269
- orca.log(`no pude leer la salida de ${title}: ${describeError(error)}`)
270
- })
271
- return running(command)
275
+ const activeWorkspaceId = async () => {
276
+ const workspaceId = await focusedWorkspaceId()
277
+ if (!workspaceId) throw failure('unavailable', NO_WORKSPACE)
278
+ return workspaceId
279
+ }
280
+
281
+ // Abre un terminal con `command` y lo sigue hasta que acaba (src/worker/actions.ts). `command`
282
+ // es siempre un literal o sale de `teamCommand` (ids validados): nunca se interpola texto libre
283
+ // del usuario ni de terceros en el terminal. Lanza si no hay workspace o si Orca falla.
284
+ const runOmk = async (title: string, command: string) => {
285
+ const workspaceId = await activeWorkspaceId()
286
+ const { terminalId } = await host.call('terminal.create', {
287
+ workspaceId,
288
+ title,
289
+ command: `${command} ${EXIT_MARKER_FLAG}`
272
290
  })
291
+ tracker.omk(terminalId, title)
292
+ return running(command)
293
+ }
273
294
 
274
- const subcommand = (name: OmkSubcommand) => runOmk(`omk ${name}`, `omk ${name}`)
295
+ const subcommand = (name: OmkSubcommand) => () => runOmk(`omk ${name}`, `omk ${name}`)
275
296
 
276
- const launchAgent = (label: string, agent: string, prompt: string, done: string) =>
277
- guarded(label, async () => {
278
- const workspaceId = await focusedWorkspaceId()
279
- if (!workspaceId) {
280
- notify('Orca Multiagent Kit', NO_WORKSPACE)
281
- return NO_WORKSPACE
282
- }
283
- await host.call('agent.launch', { workspaceId, agent, prompt })
284
- return done
285
- })
297
+ // Lanza un agente con `prompt` y lo sigue. Lanza si no hay workspace o si Orca falla.
298
+ const launchAgent = async (title: string, agent: string, prompt: string, done: string) => {
299
+ const workspaceId = await activeWorkspaceId()
300
+ const { terminalId } = await host.call('agent.launch', { workspaceId, agent, prompt })
301
+ tracker.agent(terminalId, title)
302
+ return done
303
+ }
286
304
 
287
305
  const initProject = async () => {
288
306
  if (!isValidAgentId(initAgent)) {
289
- const message = `El ajuste «Agente para inicializar» no es un id de agente válido: ${String(initAgent)}`
290
- notify('Orca Multiagent Kit', message)
291
- return message
307
+ throw invalidParams(`El ajuste «Agente para inicializar» no es un id de agente válido: ${String(initAgent)}`)
292
308
  }
293
309
  return launchAgent(
294
- 'inicializar proyecto',
310
+ `Inicializar proyecto · ${initAgent}`,
295
311
  initAgent,
296
312
  INIT_PROMPT,
297
313
  `Lanzado ${initAgent} con «${INIT_PROMPT}» (skill kit-init) en el workspace activo.`
298
- )()
314
+ )
299
315
  }
300
316
 
301
317
  // Los hooks no deniegan nunca: si no aplican, el prompt o el lanzamiento pasan intactos. Un
@@ -341,16 +357,16 @@ export default async function activate(orca: OrcaWorkerApi): Promise<void> {
341
357
  init: initProject
342
358
  }
343
359
 
344
- orca.commands.register('kit.verify', actions.verify)
345
- orca.commands.register('kit.update', actions.update)
346
- orca.commands.register('kit.init', actions.init)
360
+ orca.commands.register('kit.verify', fromPalette('omk verify', actions.verify))
361
+ orca.commands.register('kit.update', fromPalette('omk update', actions.update))
362
+ orca.commands.register('kit.init', fromPalette('inicializar proyecto', actions.init))
347
363
  orca.commands.register('agents.status', async () => describeAgents(groupAgents(agents, workspaces.byId)))
348
364
 
349
365
  // El panel solo elige entre las acciones fijas de arriba; cualquier otro valor se rechaza.
350
366
  orca.panels.handle('kit.run', async (input) => {
351
367
  const action: unknown = input?.action
352
368
  if (!isKitAction(action)) throw invalidParams(`acción desconocida: ${String(action)}`)
353
- return { message: await actions[action]() }
369
+ return fromPanel(`kit.run ${action}`, actions[action])
354
370
  })
355
371
  orca.panels.handle('agents.summary', () => agentsView())
356
372
 
@@ -369,21 +385,19 @@ export default async function activate(orca: OrcaWorkerApi): Promise<void> {
369
385
  if (command === null) {
370
386
  throw invalidParams('el equipo no cabe en una orden de terminal: quita roles propios o acorta sus textos')
371
387
  }
372
- return { message: await runOmk('omk team', command)() }
388
+ return fromPanel('team.apply', () => runOmk('omk team set', command))
373
389
  })
374
390
 
375
- orca.panels.handle('team.show', async () => ({ message: await runOmk('omk team', 'omk team')() }))
391
+ orca.panels.handle('team.show', () => fromPanel('team.show', () => runOmk('omk team', 'omk team')))
376
392
 
377
393
  // Solo uno de los tres niveles llega a la orden: `autonomyCommand` no interpola nada más.
378
394
  orca.panels.handle('team.autonomy', async (input) => {
379
395
  const level: unknown = input?.autonomy
380
396
  if (!isAutonomy(level)) throw invalidParams(`autonomía desconocida: ${String(level)}`)
381
397
  const command = autonomyCommand(level)
382
- const message = await runOmk('omk team', command)()
383
- if (message === running(command)) {
384
- bus.emit('action', { kind: 'autonomy', title: `Autonomía del proyecto → ${level}`, detail: null, agentKey: null, run: null, at: Date.now() })
385
- }
386
- return { message }
398
+ const result = await fromPanel('team.autonomy', () => runOmk(command, command))
399
+ bus.emit('action', { kind: 'autonomy', title: `Autonomía del proyecto → ${level}`, detail: null, agentKey: null, run: null, at: Date.now() })
400
+ return result
387
401
  })
388
402
 
389
403
  orca.panels.handle('team.orchestrate', async (input) => {
@@ -395,13 +409,11 @@ export default async function activate(orca: OrcaWorkerApi): Promise<void> {
395
409
  throw invalidParams(`falta la tarea, pasa de ${TASK_MAX} caracteres, o la entrada o la autonomía no existen`)
396
410
  }
397
411
  const done = `Lanzado ${agent} con la skill orca en el workspace activo.`
398
- const message = await launchAgent('orquestar', agent, prompt, done)()
399
- if (message === done) {
400
- const task = cleanLabel(typeof input?.task === 'string' ? input.task : '', 120)
401
- const title = isAutonomy(autonomy) ? `Repartir con ${agent} (autonomía ${autonomy})` : `Repartir con ${agent}`
402
- bus.emit('action', { kind: 'orchestrate', title, detail: task, agentKey: null, run: null, at: Date.now() })
403
- }
404
- return { message }
412
+ const result = await fromPanel('team.orchestrate', () => launchAgent(`Repartir · ${agent}`, agent, prompt, done))
413
+ const task = cleanLabel(typeof input?.task === 'string' ? input.task : '', 120)
414
+ const title = isAutonomy(autonomy) ? `Repartir con ${agent} (autonomía ${autonomy})` : `Repartir con ${agent}`
415
+ bus.emit('action', { kind: 'orchestrate', title, detail: task, agentKey: null, run: null, at: Date.now() })
416
+ return result
405
417
  })
406
418
 
407
419
  orca.events.on('agent.status.changed', (event) => {
@@ -450,22 +462,6 @@ export default async function activate(orca: OrcaWorkerApi): Promise<void> {
450
462
  renderStatus()
451
463
  })
452
464
 
453
- const ctx: KitContext = {
454
- host,
455
- panels: orca.panels,
456
- storage: orca.storage,
457
- system: hostSystem.current,
458
- log: (message) => orca.log(message),
459
- notify: (title, body) => {
460
- if (notifyEnabled) notify(title, body)
461
- },
462
- agents,
463
- terminals,
464
- workspaces: () => workspaces,
465
- workspaceName,
466
- refreshWorkspaces,
467
- ...bus
468
- }
469
465
  registerNotices(ctx)
470
466
  registerWorktrees(ctx)
471
467
  registerHistory(ctx)
@@ -8,6 +8,7 @@ Eres un ingeniero senior. Tu razonamiento y tu código son exhaustivos; tu prosa
8
8
  - Primera línea = resultado o estado. Sin preámbulo, sin narrar herramientas, sin cortesía, sin recapitulación.
9
9
  - ≤4 líneas de prosa por turno. Código, diffs, tablas de gates y comandos no cuentan.
10
10
  - El resto del protocolo (prefijos, excepciones, disparadores de detalle) está en `~/.agents/AGENTS.md` §2 y en `~/.agents/rules/10-communication.md`. Aplícalo; no lo repitas.
11
+ - Puerta de reparto (`~/.agents/AGENTS.md` §6): en un trabajo con ≥2 entregables separables, la línea `ORCA: …` de la skill `orca` se escribe en el chat antes de la primera edición, aunque no sea el mensaje final; si reparte, va con el plan de rondas. Esa línea, el plan de rondas y sus confirmaciones no son prosa que recortar ni preguntas que ahorrarse.
11
12
  - El ahorro es solo de salida en prosa. No reduzcas análisis, lectura de código, tests ni auditoría de seguridad.
12
13
  - Antes de declarar algo terminado: `~/.agents/rules/50-done-gate.md` y tabla de gates. Un comando no ejecutado se reporta `SKIPPED (motivo)`, nunca `PASS`.
13
14
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "orca-multiagent-kit",
3
- "version": "1.6.0",
3
+ "version": "1.7.0",
4
4
  "description": "Una sola fuente de reglas y skills (CSR + MAW) para Claude Code, Antigravity, Codex, Copilot y Cursor, con orquestación multiagente.",
5
5
  "license": "MIT",
6
6
  "author": "Fernando Baquero (https://github.com/FernandoBaqueroo)",
@@ -13,14 +13,14 @@
13
13
  "orca-multiagent-kit": "bin/omk.js"
14
14
  },
15
15
  "files": [
16
- "bin/", "speckit-extension/", "core/", "rules/", "skills/", "templates/", "output-styles/", "docs/", "orca-plugin/",
16
+ "bin/", "hooks/", "speckit-extension/", "core/", "rules/", "skills/", "templates/", "output-styles/", "docs/", "orca-plugin/",
17
17
  "install.sh", "VERSION", "GUIA.html", "AI_INSTALL.md", "CHANGELOG.md", "LICENSE", "README.md"
18
18
  ],
19
19
  "engines": { "node": ">=18" },
20
20
  "os": ["darwin", "linux", "win32"],
21
21
  "keywords": ["ai-agents", "claude-code", "antigravity", "gemini", "codex", "copilot", "cursor", "orca", "agent-skills", "multi-agent", "worktrees", "spec-kit", "agents-md"],
22
22
  "scripts": {
23
- "test": "bash scripts/check.sh && bash tests/test_install.sh && bash tests/test_cli.sh && bash tests/test_team.sh && bash tests/test_orca.sh && bash tests/test_speckit.sh",
23
+ "test": "bash scripts/check.sh && bash tests/test_install.sh && bash tests/test_cli.sh && bash tests/test_team.sh && bash tests/test_orca.sh && bash tests/test_update.sh && bash tests/test_gate.sh && bash tests/test_run.sh && bash tests/test_run_plan.sh && bash tests/test_run_git.sh && bash tests/test_run_cleanup.sh && bash tests/test_speckit.sh",
24
24
  "build:exe": "node scripts/build-exe.js"
25
25
  }
26
26
  }
@@ -59,7 +59,7 @@ build | pnpm build | PASS
59
59
  test | pnpm test | PASS 128/128
60
60
  coverage | pnpm test:cov | 86% cambiado
61
61
  sec-scan | semgrep --config=auto| SKIPPED (no instalado: semgrep)
62
- deps | npm audit | SKIPPED (sin red)
62
+ deps-audit | npm audit | SKIPPED (sin red)
63
63
  RISK: <si aplica>
64
64
  DEFERRED: <si aplica>
65
65
  ```
@@ -2,21 +2,31 @@
2
2
 
3
3
  > El núcleo (`~/.agents/AGENTS.md` §6) enuncia las invariantes. Este fichero añade criterio y casos. No las repite.
4
4
 
5
+ ## Puerta de reparto (cuándo se evalúa)
6
+ La evaluación no es opcional ni depende de la vía de entrada: todo trabajo de implementación con ≥2 entregables separables pasa por la skill `orca` antes de la primera edición (núcleo §6) y deja una línea `ORCA: …`. Contar entregables es barato y se hace siempre; los criterios de abajo los aplica la skill, con las unidades delante, no el agente de memoria antes de cargarla.
7
+ | Entrada | Qué la dispara |
8
+ |---|---|
9
+ | spec-kit | Hook `before_implement` de `/speckit.implement` (skill `speckit-orca-implement`) |
10
+ | Prompt de chat, ticket, «implementa `planes/x.md`», artefacto | Núcleo §6; en Claude Code, además, el hook `UserPromptSubmit` del kit lo recuerda en cada mensaje |
11
+ | Plan nativo aprobado | La sección `Reparto` del propio plan (núcleo §6); en Claude Code, además, el hook `PostToolUse` sobre `ExitPlanMode` |
12
+ | Agente arrancado por Orca con una tarea | Plugin del kit en Orca («Repartir siempre») |
13
+ Un entregable solo, una pregunta o un worker con su unidad no pasan por la puerta.
14
+
5
15
  ## Cuándo paralelizar (y cuándo no)
6
16
  Paraleliza solo si **todo** se cumple:
7
17
  - Hay ≥2 unidades sin dependencia entre sí.
8
18
  - Sus conjuntos de ficheros de escritura no se cortan (ver §Solapes).
9
- - Cada unidad tiene ≥ ~15 min de trabajo. Por debajo, el coste de worktree + revisión + merge supera la ganancia.
19
+ - Cada unidad tiene ≥ ~15 min de trabajo. Por debajo, el coste de worktree + revisión + merge supera la ganancia. Mídelo por talla (§Tamaño de unidad), no a ojo: una unidad `M` o `L` cumple; una `S` no.
10
20
  - Puedes verificar cada unidad por separado (tests, build o comprobación visual concreta).
11
21
  Si falla cualquiera: secuencial en un solo agente (motor `inline`). Decláralo: `ORCA: secuencial — <motivo>`.
12
22
 
13
23
  ### Cuenta rápida (cuando dudes)
14
24
  ```
15
25
  ahorro = Σ t(unidades de la ronda) − max t(unidad) # lo que ganas por ronda
16
- coste = 10 min × unidades + 10 min × rondas # brief + revisión + merge + gates del conjunto
26
+ coste = 5 min × unidades + 5 min × rondas # brief + revisión + merge + gates del conjunto
17
27
  compensa si Σ ahorro > coste y ningún ahorro depende de una unidad L sin dividir
18
28
  ```
19
- Estimaciones en minutos de agente, no humanos. Penaliza (+10 min por fichero) cada fichero `shared` que obligue a serializar o a pasarlo a `U0`. Si el resultado es dudoso, secuencial: la orquestación fallida cuesta más que la que no se hizo.
29
+ Estimaciones en minutos de agente, no humanos. Penaliza (+10 min por fichero) cada fichero `shared` que obligue a serializar o a pasarlo a `U0`. Con dos unidades `M` de ficheros disjuntos la cuenta sale a favor (30 + 30 min: ahorro 30, coste 15): se reparten. Secuencial solo si la cuenta sale en contra o si alguna condición de arriba falla; ante un empate, reparte.
20
30
 
21
31
  ## Tamaño de unidad
22
32
  | Talla | Orientación | Presupuesto orientativo | Qué hacer |
@@ -1,11 +1,11 @@
1
1
  ---
2
2
  name: kit-init
3
- description: Inicializa o migra un proyecto al Orca Multiagent Kit con un solo prompt - crea o actualiza AGENTS.md y CLAUDE.md desde las plantillas, detecta el stack (csr-stack), prepara la orquestacion multiagente, activa el hook de spec-kit para que /speckit.implement reparta el trabajo y deja .work/ ignorado. Usar con "inicializa el proyecto", "prepara este repo", "kit-init", al abrir un repo sin AGENTS.md o STACK.md, o con un AGENTS.md/CLAUDE.md con bloques CSR antiguos.
3
+ description: Inicializa o migra un proyecto al Orca Multiagent Kit con un solo prompt - crea o actualiza AGENTS.md y CLAUDE.md desde las plantillas, detecta el stack (csr-stack), prepara la orquestacion multiagente, activa el hook de spec-kit para que /speckit.implement reparta el trabajo, deja en .claude/settings.json los hooks de reparto de Claude Code y deja .work/ ignorado. Usar con "inicializa el proyecto", "prepara este repo", "kit-init", al abrir un repo sin AGENTS.md o STACK.md, o con un AGENTS.md/CLAUDE.md con bloques CSR antiguos.
4
4
  ---
5
5
 
6
6
  # kit-init — Proyecto listo en un prompt
7
7
 
8
- No necesita terminal ni el instalador: copia desde `~/.agents/templates/`. Si esa carpeta no existe: `BLOCKED: Orca Multiagent Kit no está instalado globalmente (./install.sh)`.
8
+ No necesita terminal ni el instalador: copia desde `~/.agents/templates/`. Si esa carpeta no existe: `BLOCKED: Orca Multiagent Kit no está instalado globalmente` (`omk setup`, o `./install.sh` desde la carpeta del kit).
9
9
 
10
10
  ## 1. Diagnóstico (solo lectura)
11
11
  Comprueba y anota en una línea cada uno:
@@ -13,6 +13,7 @@ Comprueba y anota en una línea cada uno:
13
13
  - `CLAUDE.md`: igual. Es correcto si solo contiene el bloque con `@AGENTS.md`.
14
14
  - `STACK.md`: falta | plantilla sin rellenar (campos vacíos, `| | |`) | rellena.
15
15
  - `ORCHESTRATION.md`, `orca.yaml`, `.worktreeinclude`, `.gitignore` con `.work/`.
16
+ - `.claude/settings.json` (solo si el proyecto usa Claude Code: hay `.claude/` o `CLAUDE.md`, o es el agente que ejecuta esto): falta | sin hooks de reparto | con hooks de reparto (algún `command` contiene `[Orca Multiagent Kit]`).
16
17
  - Ficheros de otras herramientas que conviven: `.specify/` (spec-kit), `PRODUCT.md`/`DESIGN.md` (impeccable), `planes/`, `.cursor/rules/`, `.agents/rules/`, `.github/copilot-instructions.md`. No se tocan; se tienen en cuenta.
17
18
 
18
19
  ## 2. Reglas del proyecto
@@ -35,6 +36,8 @@ Activa la implementación orquestada: el hook `before_implement` de la extensió
35
36
  ```yaml
36
37
  installed:
37
38
  - orca
39
+ settings:
40
+ auto_execute_hooks: true
38
41
  hooks:
39
42
  before_implement:
40
43
  - extension: orca
@@ -42,12 +45,20 @@ Activa la implementación orquestada: el hook `before_implement` de la extensió
42
45
  enabled: true
43
46
  optional: false
44
47
  priority: 10
45
- description: "Orquestación multiagente: reparte las user stories si compensa"
48
+ description: "Orquestacion multiagente: reparte las user stories si compensa"
46
49
  ```
47
50
  El comando lo resuelve la skill global `speckit-orca-implement`.
48
51
  3. Comprueba que `/speckit.implement` lo verá: la skill `speckit-implement` del proyecto debe mencionar `hooks.before_implement`. Si es una versión antigua sin hooks: `RISK:` y propón actualizar spec-kit.
49
52
 
50
- ## 6. Cierre
53
+ ## 6. Claude Code: `.claude/settings.json` y hooks de reparto (si el proyecto usa Claude Code)
54
+ Fuera de spec-kit no hay hook `before_implement`: en Claude Code lo suplen dos hooks de `~/.agents/templates/claude-settings.json` (`UserPromptSubmit`, y `PostToolUse` sobre `ExitPlanMode`) que recuerdan la puerta de reparto (`~/.agents/AGENTS.md` §6) en cada mensaje y al aprobar un plan.
55
+ 1. No existe `.claude/settings.json` ⇒ cópialo entero de `~/.agents/templates/claude-settings.json`.
56
+ 2. Existe sin hooks de reparto ⇒ añade a su clave `hooks` las entradas `UserPromptSubmit` y `PostToolUse` de la plantilla, tal cual. Conserva todo lo demás (permisos, otros hooks, otras claves); si ya hay entradas en esos eventos, añade las del kit al final de la lista. No toques `permissions`.
57
+ 3. Ya los tiene ⇒ si el texto difiere del de la plantilla, sustituye solo esas dos entradas (las que contienen `[Orca Multiagent Kit]`).
58
+ 4. Comprueba que el fichero sigue siendo JSON válido. No edites `.claude/settings.local.json` ni la configuración global del usuario (`~/.claude/settings.json`): esa la gestiona el instalador.
59
+ Otros agentes (Antigravity, Codex…): no se les crea ningún hook; les aplica la regla del núcleo.
60
+
61
+ ## 7. Cierre
51
62
  No hagas commit sin permiso. Reporta:
52
63
  ```
53
64
  kit-init · <proyecto>
@@ -58,6 +69,7 @@ ORCHESTR. | proveedores: <activos> · sensibles: <n> · shared: <n> ficheros
58
69
  entorno | copia: <ficheros .env> · install: <cmd> · comprobación: <cmd>
59
70
  modelos | ~/.agents/models.md: creado / ya ok / <proveedor> sin nivel <n>
60
71
  spec-kit | hook before_implement: activo / no aplica
72
+ claude | .claude/settings.json: creado / hooks de reparto añadidos / ya ok / no aplica
61
73
  convive con | spec-kit · impeccable · …
62
74
  commit sugerido: chore: inicializar Orca Multiagent Kit (AGENTS, STACK, ORCHESTRATION)
63
75
  ```
@@ -1,12 +1,22 @@
1
1
  ---
2
2
  name: orca
3
- description: Política de desarrollo orquestado del kit - decide si una tarea compensa repartirla entre varios agentes, la divide en unidades y rondas, lanza un worker por unidad (Orca, subagentes o worktrees), revisa, integra y reanuda runs a medias. Úsala por iniciativa propia cuando una tarea tenga 2 o más partes independientes de más de 15 minutos cada una (varias user stories, sprints, módulos o pantallas), cuando el usuario pida paralelo, varios agentes, worktrees o una carrera, y siempre que la invoque el hook before_implement de spec-kit. Manda sobre el reparto y la integración; para los comandos exactos de Orca carga además la skill orchestration de Orca, que manda sobre la sintaxis. Si el usuario solo quiere delegar una tarea suelta a otro agente sin plan ni integración, usa orchestration u orca-cli directamente.
3
+ description: Política de desarrollo orquestado del kit - decide si una tarea compensa repartirla entre varios agentes, la divide en unidades y rondas, lanza un worker por unidad (Orca, subagentes o worktrees), revisa, integra y reanuda runs a medias. Cárgala SIEMPRE antes de la primera edición al implementar algo con 2 o más entregables separables (user stories, sprints, módulos, pantallas, endpoints, secciones de un plan), venga de un prompt, de un plan aprobado (modo plan de Claude Code, implementation_plan.md de Antigravity), de un plan en fichero, de un artefacto o de un ticket; con «implementa el plan»; si el usuario pide paralelo, varios agentes, worktrees o una carrera; y desde el hook before_implement de spec-kit. Decide en una línea que empieza por ORCA si se reparte o va secuencial, así que no lo decidas sin cargarla. Para los comandos de Orca carga además la skill orchestration, que manda sobre la sintaxis. Para delegar una tarea suelta sin plan ni integración, usa orchestration u orca-cli.
4
4
  ---
5
5
 
6
6
  # orca — Desarrollo orquestado de principio a fin
7
7
 
8
8
  Un solo punto de entrada. El usuario no tiene que conocer fases ni comandos: tú decides si compensa repartir y, si compensa, llevas el ciclo completo. Detalle en `references/` (léelo solo cuando llegues a ese paso).
9
9
 
10
+ **Lo primero que haces al cargar esta skill**: decidir §1 y dejar su veredicto **escrito en el chat**, en una línea que empieza por `ORCA:`. Es texto visible para el usuario, no razonamiento.
11
+ - **Si reparte**: la línea y el plan de rondas (§3) van **antes de llamar a ninguna herramienta de edición**, también antes de la ronda 0: no se toca código hasta que el plan está enseñado (y confirmado, salvo en `auto`). No recortes el reparto porque la sesión vaya justa de presupuesto o de contexto: enseña el plan y dilo en un `RISK:`.
12
+ - **Si es secuencial**: `ORCA: secuencial — <motivo>` también antes de la primera edición; después, hazlo tú.
13
+ - En Claude Code lo impone un hook del kit (`omk gate`): nada más escribir la línea en el chat, **regístrala** ejecutando `echo "ORCA: …"` con la misma línea (el hook la lee de esa orden, porque el chat le llega tarde); sin ese registro, la edición se deniega, y con un reparto sin responder se deniegan también la shell que escribe y lanzar workers. Si te deniega, no busques otro camino: escribe la línea (o termina el turno con el plan) y sigue.
14
+
15
+ **Puerta de reparto** (`~/.agents/AGENTS.md` §6): se llega aquí antes de la primera edición de todo trabajo con ≥2 entregables separables, venga de un prompt, de un plan nativo aprobado, de un plan en fichero, de un artefacto, de un ticket o del hook de spec-kit. La salida mínima es siempre **una línea** `ORCA: …` (§1); sin ella no se edita.
16
+ - **Sin `tasks.md` también se decide**: si la entrada no trae las partes hechas, esboza las unidades (título + ficheros que escribe cada una, buscados en el repo) con el adaptador de §2 y decide §1 con ese esbozo. No des «secuencial» por no tener el reparto hecho.
17
+ - **En modo plan** (sin permiso de edición): haz solo §1 y el esbozo, y escríbelos como sección final `Reparto` del plan (veredicto `ORCA: …` y tabla `unidad | ficheros | depende`). El run (`.work/`, §3 en adelante) empieza cuando el plan se aprueba; aprobar el plan no es la confirmación 1: la tabla de §3 se enseña y se confirma igual.
18
+ - **Eres un worker** (tu mensaje empieza por `UNIT:`): no repartas tu unidad; sigue `references/worker-contract.md`.
19
+
10
20
  ## 0. Configuración y estado
11
21
  Lee `./ORCHESTRATION.md` (si no existe, valores por defecto entre paréntesis):
12
22
  - **Autonomía** (`semi`):
@@ -28,6 +38,16 @@ Lee `./ORCHESTRATION.md` (si no existe, valores por defecto entre paréntesis):
28
38
  Al cerrar el run, ofrece **una vez** guardar lo deducido en `ORCHESTRATION.md`, `orca.yaml` y `.worktreeinclude` (son ficheros del proyecto: no los edites sin ese «sí»). La tabla antigua «Agentes por capa» sigue valiendo como excepciones.
29
39
  - **Run a medias**: si existe `.work/runs/*/run.md` con `status: active` para este mismo trabajo, no planifiques de nuevo: reanuda con `references/ledger.md` §Reanudar.
30
40
  - **Limpieza pendiente**: si algún `run.md` tiene `cleanup: pending`, dilo en una línea antes de seguir (`ORCA: limpieza pendiente del run <run> — <n> worktrees, <m> ramas`) y ofrece hacerla (`references/integrate.md` §6).
41
+ - **Motor `omk run`**: lo mecánico del run (estado, rondas, worktrees, alcance, merge y limpieza) lo hace el CLI del kit, no tu memoria. Ejecútalo desde tu checkout (con Orca, tu workspace), donde vive `.work/runs/<run>/`. Si `omk run help` no responde (kit antiguo o sin `omk` en el `PATH`), sigue los pasos a mano de cada referencia y dilo en el plan (`ficha: sin omk run`).
42
+ | Paso | Orden |
43
+ |---|---|
44
+ | §2 unidades escritas | `omk run new <run> --input "<entrada>" --engine <motor> --autonomy <nivel> --integration <rama>` y `omk run plan <run>` |
45
+ | §3 «sí» | `omk run meta <run> status=active confirm1=<fecha>` |
46
+ | §4 base fresca | `omk run start <run> --parent <padre>` |
47
+ | §5 cada unidad con worktree propio | `omk run worktree <run> <U>`; `omk run set <run> <U> status=dispatching` antes de lanzar y `status=dispatched ref=<id>` después |
48
+ | §7 revisar e integrar | `omk run check <run> <U>`, `omk run set <run> <U> status=accepted` y `omk run merge <run> <U>` |
49
+ | §8 limpieza | `omk run cleanup <run>` (inventario) y, con el «sí», `omk run cleanup <run> --apply` |
50
+ Salida 1 = rechazo con su motivo: arregla la causa, no lo rodees con git a mano. Salida 3 = decisión del usuario (una pregunta). `omk run status` enseña el run y `omk run log <run> <texto>` anota lo demás.
31
51
 
32
52
  ## 1. ¿Compensa? (decídelo en menos de un minuto)
33
53
  Criterio y cuenta rápida en `~/.agents/rules/95-multi-agent.md` §Cuándo paralelizar: ≥2 unidades independientes, `write` disjuntos, ≥15 min cada una, verificables por separado, y el ahorro supera el coste de coordinar.
@@ -42,10 +62,10 @@ Identifica la entrada y lee **solo** su adaptador:
42
62
  |---|---|
43
63
  | spec-kit (`specs/<feature>/tasks.md`, o vienes del hook) | `references/adapters/speckit.md` |
44
64
  | `planes/*.md` / `.plans/*.md` | `references/adapters/plan-file.md` |
45
- | Plan nativo (modo plan de Claude, `implementation_plan.md` de Antigravity) | `references/adapters/native-plan.md` |
65
+ | Plan nativo recién aprobado o con «implementa el plan» (modo plan de Claude, `implementation_plan.md` de Antigravity) | `references/adapters/native-plan.md` |
46
66
  | Prompt de chat o ticket | `references/adapters/chat.md` (si es grande y vago, primero `references/plan.md`) |
47
67
  | Mockup, diseño, documento | `references/adapters/artifact.md` |
48
- Escribe las unidades con el formato de `references/units.md` en `.work/runs/<run>/units.md` (`.work/` en `.gitignore`).
68
+ Escribe las unidades con el formato de `references/units.md` en `.work/runs/<run>/units.md` (`.work/` en `.gitignore`) y pásale `omk run plan <run>`: con errores (globs anchos, ciclos, `write` que pisa `shared`, campos que faltan) corrige `units.md` antes de enseñar nada. Las rondas de la tabla de §3 son las que calcula (con el motivo de cada empuje por solape), y su línea `compensa:` es la cuenta de §1 con datos: si dice `no`, el veredicto pasa a `ORCA: secuencial — <su motivo>`.
49
69
 
50
70
  Después, con `references/olimpo.md`, da a cada unidad su **rol** (de él salen el nivel de modelo y quién la revisa), comprueba los modelos disponibles de cada proveedor activo y elige proveedor. Con `~/.agents/rules/95-multi-agent.md` §Recurso por unidad, elige su **recurso** (coordinador, subagente de solo lectura, subagente con worktree, worker de Orca o manual). Nada de esto se improvisa, y si una unidad va con el modelo por defecto del proveedor, el plan lo dice.
51
71
 
@@ -67,7 +87,7 @@ merge final: feat/003-recargas → main (te lo pediré al terminar; después, la
67
87
  - `<alto>`, `<medio>`: el valor real de `~/.agents/models.md` para ese proveedor, o `por defecto` si ese nivel no tiene modelo ahí.
68
88
  - La línea `modelos:` solo aparece si `references/olimpo.md` §Modelos ha clasificado un modelo nuevo o tiene algo que avisar. Es informativa: el nivel lo decide el coordinador con evidencia, no se le pregunta al usuario.
69
89
  - **Tarjeta del plan** (solo en Orca): crea antes el Run de Orca (`run-create`, `references/engine-orca.md`) y, justo antes de enseñar la tabla, escribe el mismo plan con su id (`orcaRun`) en `.work/runs/<run>/plan.json` (`references/plan-card.md`). El plugin del kit lo enseña en su pestaña Avisos con «Sí» y «Cambiar». La respuesta te llega en tu terminal, o, si corres como chat, como mensaje del buzón del Run con asunto «Respuesta desde el panel: …»: para la **confirmación 1** vale igual que si la escribiera el usuario. Las confirmaciones 2 y 3 (merge final y limpieza) solo valen escritas en el chat. Si no puedes escribir el plan, sigue sin él: la tabla del chat manda.
70
- - El «sí» autoriza los commits y merges **del run** en ramas de trabajo y en la rama de integración, Con el «sí», crea `.work/runs/<run>/run.md` (`references/ledger.md`): desde aquí, cada paso se anota **antes** de hacerlo.
90
+ - El «sí» autoriza los commits y merges **del run** en ramas de trabajo y en la rama de integración. Con el «sí», `run.md` (`references/ledger.md`, creado por `omk run new`) pasa a `status: active`: desde aquí, cada paso se anota **antes** de hacerlo.
71
91
 
72
92
  ## 4. Base fresca y base común (U0)
73
93
  **Antes del plan** (la línea `base:` sale de aquí): nunca partas de una rama local sin contrastarla con su remoto.
@@ -86,6 +106,7 @@ git rev-list --left-right --count origin/<padre>...<padre> # <detrás> <del
86
106
  - Si la rama de integración ya existe (feature empezada), compárala igual con su remoto y con `origin/<padre>`; si `<padre>` ha avanzado, dilo en el plan.
87
107
  - `--no-track` siempre que la rama de integración nazca de una ref remota: sin él, su upstream sería `origin/<padre>` y un push desde ella podría ir a la rama padre.
88
108
  - Anota en `run.md` `base_ref` y su sha. Todo worktree del run sale de la rama de integración; ninguno sale de `<padre>` directamente.
109
+ - Con `omk run`: el `fetch` y la cuenta de arriba (solo lectura) dan la línea `base:` del plan; tras el «sí», `omk run start <run> --parent <padre>` aplica la misma tabla, crea la rama con `--no-track` (o se cambia a ella si existe) y anota `base_ref`. Si sale con 3 (local por delante), usa la respuesta del usuario: `--from remote` o `--from local`.
89
110
 
90
111
  Después haz tú la ronda 0, pasa `csr-gate` y haz commit en la rama de integración. Todas las unidades parten de ese commit.
91
112
 
@@ -94,6 +115,7 @@ Cada unidad usa el recurso que le tocó en el plan. Orca solo si `orca status --
94
115
  Mensaje de despacho (todo dentro del mensaje: el worker no ve tu checkout ni tu conversación):
95
116
  ```
96
117
  UNIT: U2 — <título> RUN: <run> BASE: <sha> PUERTO DEV: <PORT_BASE+n>
118
+ WORKTREE: <sin Orca: ruta absoluta del worktree de la unidad (omk run worktree) y su rama wt/<run>/u2>
97
119
  ROL: Ariadna · código sensible · nivel alto — <guardarraíl de su fila en olimpo.md>
98
120
  <bloque completo de la unidad, tal cual está en units.md>
99
121
  Shared (no tocar salvo los de tu unidad): <lista de ORCHESTRATION.md>
@@ -121,7 +143,7 @@ rama: feat/003-recargas (+1.240/−310, 46 ficheros)
121
143
  BLOCKED/DEFERRED: <si aplica>
122
144
  ¿Mergeo feat/003-recargas en main? (o abre PR)
123
145
  ```
124
- Antes de pedir el merge final repite el `git fetch` de §4: si `<padre>` ha avanzado, trae `origin/<padre>` a la rama de integración (merge, sin reescribir), repite `csr-gate` y enseña la tabla actualizada.
146
+ Antes de pedir el merge final repite el `git fetch` de §4 (o `omk run start <run> --parent <padre>`, que lo avisa): si `<padre>` ha avanzado, trae `origin/<padre>` a la rama de integración (merge, sin reescribir), repite `csr-gate` y enseña la tabla actualizada.
125
147
 
126
148
  **Confirmación 3 — limpieza.** Tras el merge final (o cuando el usuario confirme que el PR está fusionado), enseña el inventario de lo que el run ha dejado (worktrees, ramas, copias de `.env`) y pide permiso para borrarlo: `references/integrate.md` §6. No se borra nada sin ese «sí», y el run no se cierra sin haberlo preguntado: con un «no», `cleanup: pending` en `run.md`. Después, `run.md` a `status: done`.
127
149
  - **Si vienes del hook de spec-kit**: todas las tareas quedan marcadas `[x]`. Di en una línea «Tareas completadas por la orquestación; /speckit.implement solo debe validar y ejecutar sus hooks posteriores» y devuelve el control. Si el run queda a medias (unidades `BLOCKED` o en curso), devuelve `ORCA: pendiente — …` (ver `speckit-orca-implement`): implement no debe hacer las tareas restantes por su cuenta mientras haya intentos abiertos.
@@ -2,6 +2,8 @@
2
2
 
3
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
4
 
5
+ **Cuándo se usa**: «implementa este diseño/documento/artefacto» con ≥2 pantallas, componentes o secciones separables, antes de la primera edición (puerta de reparto, `~/.agents/AGENTS.md` §6). Un plan escrito en un artefacto se trata como plan en fichero (`plan-file.md`).
6
+
5
7
  ## 1. Extrae requisitos verificables
6
8
  - **Estructura**: secciones/componentes, jerarquía, orden.
7
9
  - **Estados**: vacío, cargando, error, éxito, hover/focus, responsive (móvil/escritorio).
@@ -2,6 +2,8 @@
2
2
 
3
3
  Un prompt suelto rara vez trae lo que un worker necesita. Este adaptador lo convierte en un brief bueno antes de repartir.
4
4
 
5
+ **Cuándo se usa**: el mensaje pide implementar y nombra ≥2 entregables separables (puerta de reparto, `~/.agents/AGENTS.md` §6). Para decidir `SKILL.md` §1 basta el esbozo de §3 (título + ficheros de cada parte); el brief completo de §1–§2 se escribe solo si se reparte.
6
+
5
7
  ## 1. Completa los huecos (sin preguntar lo deducible)
6
8
  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
9
  | Hueco | Dónde deducirlo |