orca-multiagent-kit 1.4.0 → 1.5.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.
@@ -0,0 +1,100 @@
1
+ // El panel tal como lo dibuja Orca, con el worker sustituido por respuestas fijas.
2
+ import { afterEach, assert, hostError, mockHost, mount, test, type TestPanel } from 'orca/testing'
3
+ import type { AgentsView } from './protocol.ts'
4
+ import * as panel from './panel.tsx'
5
+
6
+ const NO_AGENTS: AgentsView = { text: 'MAW', tone: 'neutral', tooltip: 'ninguno', agents: [] }
7
+ const TWO_AGENTS: AgentsView = {
8
+ text: 'MAW · 1 trabajando · 1 bloqueado',
9
+ tone: 'warning',
10
+ tooltip: 'dos',
11
+ agents: [
12
+ { title: 'U1 login', state: 'trabajando' },
13
+ { title: 'U2 pagos', state: 'bloqueado' }
14
+ ]
15
+ }
16
+
17
+ type Requests = Record<string, (input: never) => unknown>
18
+
19
+ let view: TestPanel | undefined
20
+ afterEach(async () => {
21
+ await view?.unmount()
22
+ view = undefined
23
+ })
24
+
25
+ const open = async (options: { settings?: Record<string, string | boolean>; requests?: Requests } = {}) => {
26
+ const runs: unknown[] = []
27
+ const host = mockHost({
28
+ settings: options.settings ?? {},
29
+ requests: {
30
+ 'agents.summary': () => NO_AGENTS,
31
+ 'kit.run': (input: { action: string }) => {
32
+ runs.push(input)
33
+ return { message: `hecho: ${input.action}` }
34
+ },
35
+ ...options.requests
36
+ }
37
+ })
38
+ view = await mount(panel, { host })
39
+ return { view, host, runs }
40
+ }
41
+
42
+ test('muestra los ajustes guardados y los agentes del worker', async () => {
43
+ const { view } = await open({
44
+ settings: { contractHint: 'all', statusBar: false, initAgent: 'codex' },
45
+ requests: { 'agents.summary': () => TWO_AGENTS }
46
+ })
47
+ assert.equal(view.valueOf({ label: 'Contrato del worker en los despachos' }), 'all')
48
+ assert.equal(view.valueOf({ label: 'Agentes en la barra de estado' }), false)
49
+ assert.equal(view.valueOf({ label: 'Agente para inicializar' }), 'codex')
50
+ assert.ok(view.find({ label: 'U2 pagos' }))
51
+ assert.deepEqual(view.errors, [])
52
+ assert.deepEqual(view.refusals, [])
53
+ })
54
+
55
+ test('sin agentes activos lo dice', async () => {
56
+ const { view } = await open()
57
+ assert.match(view.summary().join(' '), /Ningún agente activo/)
58
+ })
59
+
60
+ test('cada botón pide su acción al worker y enseña la respuesta', async () => {
61
+ const { view, runs } = await open()
62
+ await view.press({ text: 'Verificar instalación' })
63
+ await view.press({ text: 'Inicializar proyecto' })
64
+ await view.press({ text: 'Actualizar kit' })
65
+ assert.deepEqual(runs, [{ action: 'verify' }, { action: 'init' }, { action: 'update' }])
66
+ assert.ok(view.find({ text: 'hecho: update' }))
67
+ })
68
+
69
+ test('un fallo del worker se enseña, no se calla', async () => {
70
+ const { view } = await open({
71
+ requests: {
72
+ 'kit.run': () => {
73
+ throw hostError('action_failed', 'sin workspace')
74
+ }
75
+ }
76
+ })
77
+ await view.press({ text: 'Verificar instalación' })
78
+ assert.match(view.summary().join(' '), /sin workspace/)
79
+ })
80
+
81
+ test('los controles guardan en los ajustes del plugin', async () => {
82
+ const { view, host } = await open()
83
+ await view.toggle({ label: 'Agentes en la barra de estado' })
84
+ await view.select({ label: 'Contrato del worker en los despachos' }, 'off')
85
+ await view.type({ label: 'Agente para inicializar' }, 'codex', { replace: true, submit: true })
86
+ assert.deepEqual(host.data().settings, { statusBar: false, contractHint: 'off', initAgent: 'codex' })
87
+ })
88
+
89
+ test('no guarda un id de agente no válido', async () => {
90
+ const { view, host } = await open()
91
+ await view.type({ label: 'Agente para inicializar' }, 'rm -rf /', { replace: true, submit: true })
92
+ assert.equal(host.data().settings.initAgent, undefined)
93
+ assert.match(view.summary().join(' '), /no es un id de agente válido/)
94
+ })
95
+
96
+ test('se actualiza cuando el worker envía otros agentes', async () => {
97
+ const { view } = await open()
98
+ await view.post('agents.changed', TWO_AGENTS)
99
+ assert.ok(view.find({ label: 'U1 login' }))
100
+ })
@@ -0,0 +1,205 @@
1
+ // Panel lateral del kit: las acciones de la paleta, los ajustes del plugin y los agentes activos.
2
+ // Los ajustes son los mismos de Settings → Plugins → Orca Multiagent Kit: cambiarlos aquí o allí
3
+ // es lo mismo, y el worker se entera por `settings.onDidChange`.
4
+ // Orca transpila este fichero al cargarlo: no hay paso de build.
5
+ import {
6
+ atom,
7
+ Button,
8
+ Callout,
9
+ Card,
10
+ Code,
11
+ EmptyState,
12
+ Heading,
13
+ Input,
14
+ List,
15
+ ListItem,
16
+ plugin,
17
+ read,
18
+ Row,
19
+ Select,
20
+ set,
21
+ settings,
22
+ Stack,
23
+ Switch,
24
+ Text,
25
+ type PanelContext
26
+ } from 'orca'
27
+ import { isValidAgentId, parseContractHintMode, type ContractHintMode, type KitAction } from './kit.ts'
28
+ import type { AgentsView } from './protocol.ts'
29
+
30
+ type Preferences = { contractHint: ContractHintMode; statusBar: boolean; initAgent: string }
31
+ type Outcome = { tone: 'success' | 'danger'; text: string }
32
+
33
+ const DEFAULTS: Preferences = { contractHint: 'kit', statusBar: true, initAgent: 'claude' }
34
+
35
+ const CONTRACT_OPTIONS: readonly { value: ContractHintMode; label: string }[] = [
36
+ { value: 'kit', label: 'Solo despachos del kit' },
37
+ { value: 'all', label: 'Todos los despachos' },
38
+ { value: 'off', label: 'Desactivado' }
39
+ ]
40
+
41
+ const ACTIONS: readonly { action: KitAction; label: string; hint: string }[] = [
42
+ { action: 'verify', label: 'Verificar instalación', hint: 'omk verify en un terminal nuevo' },
43
+ { action: 'init', label: 'Inicializar proyecto', hint: 'el agente de inicializar con «inicializa el proyecto»' },
44
+ { action: 'update', label: 'Actualizar kit', hint: 'omk update en un terminal nuevo' }
45
+ ]
46
+
47
+ const preferences = atom<Preferences>(DEFAULTS)
48
+ const agentDraft = atom(DEFAULTS.initAgent)
49
+ const agents = atom<AgentsView | null>(null)
50
+ const running = atom<KitAction | null>(null)
51
+ const outcome = atom<Outcome | null>(null)
52
+
53
+ // Los errores del host llevan `code` (host-api §Errors); el tipo de `catch` no lo sabe.
54
+ const describeError = (error: unknown) =>
55
+ error instanceof Error ? `${(error as { code?: string }).code ?? 'error'}: ${error.message}` : String(error)
56
+
57
+ function fromSettings(values: Record<string, unknown>): Preferences {
58
+ return {
59
+ contractHint: parseContractHintMode(values.contractHint),
60
+ statusBar: values.statusBar !== false,
61
+ initAgent: typeof values.initAgent === 'string' ? values.initAgent : DEFAULTS.initAgent
62
+ }
63
+ }
64
+
65
+ async function loadPreferences(): Promise<void> {
66
+ try {
67
+ const next = fromSettings(await settings.get())
68
+ set(preferences, next)
69
+ set(agentDraft, next.initAgent)
70
+ } catch (error) {
71
+ set(outcome, { tone: 'danger', text: `No pude leer los ajustes: ${describeError(error)}` })
72
+ }
73
+ }
74
+
75
+ async function save(key: keyof Preferences, value: string | boolean): Promise<void> {
76
+ try {
77
+ await settings.set(key, value)
78
+ set(preferences, { ...read(preferences), [key]: value })
79
+ set(outcome, { tone: 'success', text: 'Ajuste guardado.' })
80
+ } catch (error) {
81
+ set(outcome, { tone: 'danger', text: `No se guardó el ajuste: ${describeError(error)}` })
82
+ }
83
+ }
84
+
85
+ async function saveInitAgent(): Promise<void> {
86
+ const value = read(agentDraft).trim()
87
+ if (!isValidAgentId(value)) {
88
+ set(outcome, { tone: 'danger', text: `«${value}» no es un id de agente válido (minúsculas, números y guiones).` })
89
+ return
90
+ }
91
+ await save('initAgent', value)
92
+ }
93
+
94
+ async function run(action: KitAction): Promise<void> {
95
+ set(running, action)
96
+ try {
97
+ const { message } = await plugin.request('kit.run', { action })
98
+ set(outcome, { tone: 'success', text: message })
99
+ } catch (error) {
100
+ set(outcome, { tone: 'danger', text: describeError(error) })
101
+ } finally {
102
+ set(running, null)
103
+ }
104
+ }
105
+
106
+ export function setup(ctx: PanelContext): void {
107
+ ctx.subscriptions.push(plugin.on('agents.changed', (view) => set(agents, view)))
108
+ ctx.subscriptions.push(settings.onDidChange(() => void loadPreferences()))
109
+ void loadPreferences()
110
+ void plugin
111
+ .request('agents.summary')
112
+ .then((view) => set(agents, view))
113
+ .catch((error: unknown) => set(outcome, { tone: 'danger', text: `Agentes no leídos: ${describeError(error)}` }))
114
+ }
115
+
116
+ function Actions() {
117
+ const busy = read(running)
118
+ return (
119
+ <Card title="Acciones" description="Se ejecutan en el workspace activo.">
120
+ <Stack gap="sm">
121
+ {ACTIONS.map(({ action, label, hint }) => (
122
+ <Button
123
+ icon={action === 'verify' ? 'check' : action === 'init' ? 'play' : 'refresh'}
124
+ tooltip={hint}
125
+ disabled={busy !== null}
126
+ onPress={() => run(action)}
127
+ >
128
+ {busy === action ? `${label}…` : label}
129
+ </Button>
130
+ ))}
131
+ </Stack>
132
+ </Card>
133
+ )
134
+ }
135
+
136
+ function Settings() {
137
+ const prefs = read(preferences)
138
+ const draft = read(agentDraft)
139
+ return (
140
+ <Card title="Ajustes" description="Los mismos que Settings → Plugins → Orca Multiagent Kit.">
141
+ <Stack gap="md">
142
+ <Select
143
+ label="Contrato del worker en los despachos"
144
+ value={prefs.contractHint}
145
+ options={CONTRACT_OPTIONS}
146
+ onChange={(value) => save('contractHint', parseContractHintMode(value))}
147
+ />
148
+ <Switch label="Agentes en la barra de estado" checked={prefs.statusBar} onChange={(on) => save('statusBar', on)} />
149
+ <Row gap="xs" align="end">
150
+ <Input
151
+ label="Agente para inicializar"
152
+ value={draft}
153
+ maxLength={40}
154
+ placeholder={DEFAULTS.initAgent}
155
+ invalid={!isValidAgentId(draft.trim())}
156
+ onChange={(value) => set(agentDraft, value)}
157
+ onSubmit={() => saveInitAgent()}
158
+ />
159
+ <Button variant="outline" disabled={draft.trim() === prefs.initAgent} onPress={saveInitAgent}>
160
+ Guardar
161
+ </Button>
162
+ </Row>
163
+ </Stack>
164
+ </Card>
165
+ )
166
+ }
167
+
168
+ function Agents() {
169
+ const view = read(agents)
170
+ return (
171
+ <Card title="Agentes" description="En todos los workspaces.">
172
+ {view === null ? (
173
+ <Text muted>Cargando…</Text>
174
+ ) : view.agents.length === 0 ? (
175
+ <EmptyState icon="agent" title="Ningún agente activo" />
176
+ ) : (
177
+ <List label="Agentes activos">
178
+ {view.agents.map(({ title, state }) => (
179
+ <ListItem icon="agent" title={title} description={state} />
180
+ ))}
181
+ </List>
182
+ )}
183
+ </Card>
184
+ )
185
+ }
186
+
187
+ export default function Panel() {
188
+ const last = read(outcome)
189
+ return (
190
+ <Stack gap="md">
191
+ <Heading>Orca Multiagent Kit</Heading>
192
+ {last ? (
193
+ <Callout tone={last.tone} icon={last.tone === 'success' ? 'check' : 'error'}>
194
+ <Text>{last.text}</Text>
195
+ </Callout>
196
+ ) : null}
197
+ <Actions />
198
+ <Settings />
199
+ <Agents />
200
+ <Text muted size="xs">
201
+ Desde un terminal: <Code>omk setup</Code> prepara todo el entorno y <Code>omk plugin status</Code> muestra el plugin.
202
+ </Text>
203
+ </Stack>
204
+ )
205
+ }
@@ -0,0 +1,18 @@
1
+ // Contrato entre el panel (src/panel.tsx) y el worker (src/worker.ts), declarado una sola vez.
2
+ import type { AgentLine, AgentSummary, KitAction } from './kit.ts'
3
+
4
+ /** Lo que el panel muestra de los agentes: el resumen de la barra y cada agente activo. */
5
+ export type AgentsView = AgentSummary & { agents: AgentLine[] }
6
+
7
+ declare module 'orca' {
8
+ interface PluginRequests {
9
+ /** Ejecuta una acción del kit en el workspace activo y responde qué ha hecho. */
10
+ 'kit.run': { input: { action: KitAction }; output: { message: string } }
11
+ /** Los agentes activos, como los cuenta la barra de estado. */
12
+ 'agents.summary': { output: AgentsView }
13
+ }
14
+ interface PluginPanelEvents {
15
+ /** Se envía a los paneles abiertos cuando cambia lo que cuentan los agentes. */
16
+ 'agents.changed': AgentsView
17
+ }
18
+ }
@@ -153,3 +153,42 @@ test('la barra parte de los agentes que ya existen y se oculta si se desactiva',
153
153
  const hidden = await start({ settings: { statusBar: false } })
154
154
  assert.deepEqual(hidden.host.callsOf('statusBar.update').at(-1), { id: 'agents', visible: false })
155
155
  })
156
+
157
+ test('el panel ejecuta las mismas acciones que la paleta', async () => {
158
+ const w = await start()
159
+ assert.deepEqual(await w.request('kit.run', { action: 'verify' }), {
160
+ message: 'Ejecutando `omk verify` en un terminal nuevo del workspace activo.'
161
+ })
162
+ await w.request('kit.run', { action: 'init' })
163
+ assert.equal(w.host.callsOf('terminal.create').length, 1)
164
+ assert.equal(w.host.callsOf('agent.launch').length, 1)
165
+ })
166
+
167
+ test('el panel no puede pedir una acción fuera de la lista', async () => {
168
+ const w = await start()
169
+ for (const action of ['rm -rf ~', 'verify; omk update', undefined]) {
170
+ await assert.rejects(
171
+ // Simula lo que un panel podría enviar sin respetar el tipo declarado.
172
+ w.request('kit.run', { action } as unknown as { action: 'verify' }),
173
+ (error: unknown) => (error as { code?: string }).code === 'invalid_params'
174
+ )
175
+ }
176
+ assert.equal(w.host.callsOf('terminal.create').length, 0)
177
+ assert.equal(w.host.callsOf('agent.launch').length, 0)
178
+ })
179
+
180
+ test('el panel recibe los agentes y solo los cambios', async () => {
181
+ const w = await start()
182
+ assert.deepEqual(await w.request('agents.summary'), {
183
+ text: 'MAW', tone: 'neutral', tooltip: 'Orca Multiagent Kit: ningún agente activo', agents: []
184
+ })
185
+ const working = {
186
+ workspaceId: 'w1', paneKey: 'p1', terminalId: 't1', title: 'U1 login', state: 'working', receivedAt: 1
187
+ } as const
188
+ await w.emit('agent.status.changed', working)
189
+ await w.emit('agent.status.changed', { ...working, receivedAt: 2 })
190
+ const changes = w.posts.filter((p) => p.event === 'agents.changed')
191
+ // El arranque envía el estado vacío; el segundo evento no cambia nada y no se reenvía.
192
+ assert.equal(changes.length, 2)
193
+ assert.deepEqual((changes.at(-1)?.payload as { agents: unknown }).agents, [{ title: 'U1 login', state: 'trabajando' }])
194
+ })
@@ -1,10 +1,12 @@
1
1
  // Worker del plugin: comandos de paleta del kit, referencia al contrato del worker en los
2
- // despachos de orquestación y un resumen de agentes en la barra de estado.
2
+ // despachos de orquestación, un resumen de agentes en la barra de estado y las peticiones del panel.
3
3
  // Orca transpila este fichero al cargarlo: no hay paso de build.
4
4
  import type { OrcaWorkerApi } from 'orca/worker'
5
5
  import {
6
6
  INSTALL_HINT,
7
+ agentLines,
7
8
  describeAgents,
9
+ isKitAction,
8
10
  isMissingCommand,
9
11
  isValidAgentId,
10
12
  parseContractHintMode,
@@ -13,8 +15,10 @@ import {
13
15
  summarizeAgents,
14
16
  withContractHint,
15
17
  type ContractHintMode,
18
+ type KitAction,
16
19
  type TrackedAgent
17
20
  } from './kit.ts'
21
+ import type { AgentsView } from './protocol.ts'
18
22
 
19
23
  const STATUS_ITEM = 'agents'
20
24
  const INIT_PROMPT = 'inicializa el proyecto'
@@ -45,12 +49,16 @@ export function deactivate(): void {
45
49
  const describeError = (error: unknown) =>
46
50
  error instanceof Error ? `${(error as { code?: string }).code ?? 'error'}: ${error.message}` : String(error)
47
51
 
52
+ // Un `code` de error del host llega tal cual al panel (`plugin.request` lo rechaza con él).
53
+ const invalidParams = (message: string) => Object.assign(new Error(message), { code: 'invalid_params' })
54
+
48
55
  export default async function activate(orca: OrcaWorkerApi): Promise<void> {
49
56
  const { host } = orca
50
57
  let contractHint: ContractHintMode = 'kit'
51
58
  let statusBarEnabled = true
52
59
  let initAgent: unknown = DEFAULT_INIT_AGENT
53
60
  const agents = new Map<string, TrackedAgent>()
61
+ let postedView = ''
54
62
 
55
63
  const notify = (title: string, body: string) => {
56
64
  void host.call('notifications.show', { title, body }).catch((error: unknown) => {
@@ -78,10 +86,25 @@ export default async function activate(orca: OrcaWorkerApi): Promise<void> {
78
86
  return resolveFocusedWorkspaceId(focused, list.workspaces)
79
87
  }
80
88
 
89
+ const agentsView = (): AgentsView => ({
90
+ ...summarizeAgents(agents.values()),
91
+ agents: agentLines(agents.values())
92
+ })
93
+
94
+ // Los paneles abiertos reciben el resumen solo cuando cambia: los eventos de estado llegan a
95
+ // ráfagas y Orca limita los envíos (200 cada 10 s).
96
+ const postAgents = (view: AgentsView) => {
97
+ const serialized = JSON.stringify(view)
98
+ if (serialized === postedView) return
99
+ postedView = serialized
100
+ orca.panels.post('agents.changed', view)
101
+ }
102
+
81
103
  const renderStatus = () => {
82
- const summary = summarizeAgents(agents.values())
104
+ const view = agentsView()
105
+ postAgents(view)
83
106
  const update = statusBarEnabled
84
- ? { id: STATUS_ITEM, visible: true, text: summary.text, tone: summary.tone, tooltip: summary.tooltip }
107
+ ? { id: STATUS_ITEM, visible: true, text: view.text, tone: view.tone, tooltip: view.tooltip }
85
108
  : { id: STATUS_ITEM, visible: false }
86
109
  void host.call('statusBar.update', update).catch((error: unknown) => {
87
110
  orca.log(`barra de estado sin actualizar: ${describeError(error)}`)
@@ -146,11 +169,25 @@ export default async function activate(orca: OrcaWorkerApi): Promise<void> {
146
169
  return prompt === null ? undefined : next({ ...event, prompt })
147
170
  })
148
171
 
149
- orca.commands.register('kit.verify', runOmk('verify'))
150
- orca.commands.register('kit.update', runOmk('update'))
151
- orca.commands.register('kit.init', initProject)
172
+ const actions: Record<KitAction, () => Promise<string>> = {
173
+ verify: runOmk('verify'),
174
+ update: runOmk('update'),
175
+ init: initProject
176
+ }
177
+
178
+ orca.commands.register('kit.verify', actions.verify)
179
+ orca.commands.register('kit.update', actions.update)
180
+ orca.commands.register('kit.init', actions.init)
152
181
  orca.commands.register('agents.status', async () => describeAgents(agents.values()))
153
182
 
183
+ // El panel solo elige entre las acciones fijas de arriba; cualquier otro valor se rechaza.
184
+ orca.panels.handle('kit.run', async (input) => {
185
+ const action: unknown = input?.action
186
+ if (!isKitAction(action)) throw invalidParams(`acción desconocida: ${String(action)}`)
187
+ return { message: await actions[action]() }
188
+ })
189
+ orca.panels.handle('agents.summary', () => agentsView())
190
+
154
191
  orca.events.on('agent.status.changed', (event) => {
155
192
  const key = event.terminalId ? `t:${event.terminalId}` : `p:${event.paneKey}`
156
193
  if (event.state === 'done') agents.delete(key)
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "orca-multiagent-kit",
3
- "version": "1.4.0",
3
+ "version": "1.5.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)",
@@ -20,6 +20,7 @@
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_speckit.sh"
23
+ "test": "bash scripts/check.sh && bash tests/test_install.sh && bash tests/test_cli.sh && bash tests/test_orca.sh && bash tests/test_speckit.sh",
24
+ "build:exe": "node scripts/build-exe.js"
24
25
  }
25
26
  }
@@ -17,6 +17,15 @@ Lee `./ORCHESTRATION.md` (si no existe, valores por defecto entre paréntesis):
17
17
  | `auto` | **2)** y **3)**; el plan se muestra pero no espera respuesta |
18
18
  En ningún nivel se mergea a la rama por defecto, se hace push ni se borran worktrees o ramas sin confirmación. Las decisiones de producto que surjan siempre se preguntan.
19
19
  - **Proveedores activos**, **dominios sensibles**, **excepciones de reparto**, **ficheros `shared`**, **máximo de workers** (3), **revisión cruzada**, **reintentos** (1), **entorno de worktree**.
20
+ - **Ficha antigua o incompleta** (proyecto inicializado con una versión anterior, o sin `ORCHESTRATION.md`): no pidas al usuario que reinicialice. Deduce tú lo que falte, úsalo en este run y dilo en una línea del plan (`ficha: deducido <qué>`):
21
+ | Falta | Cómo se deduce |
22
+ |---|---|
23
+ | Proveedores activos | CLIs de agente instalados y, con Orca, los agentes que acepta `worker-start`; como mínimo, el proveedor del coordinador |
24
+ | Dominios sensibles | Los de `references/olimpo.md` más las rutas de auth, permisos, pagos, dinero, fiscal o tenancy que existan en el repo |
25
+ | Setup de worktree (o sigue en `TODO:`) | Comando `install` de `STACK.md` §3 (o del manifiesto) y los `.env*` gitignorados de desarrollo que existan en el checkout |
26
+ | `.env` que la app necesita y no está en `.worktreeinclude` | Se copia igualmente con el bloque `SETUP` del despacho, tras comprobar que es de desarrollo |
27
+ | Rama padre | La rama por defecto de `origin` |
28
+ 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.
20
29
  - **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.
21
30
  - **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).
22
31
 
@@ -33,7 +33,7 @@ orca orchestration worker-start --task <taskId> --worktree new-child --base-bran
33
33
  ```
34
34
  - Antes de cada `worker-start`: la unidad en `dispatching` en `run.md`; después, `dispatched` con el `dispatchId` del recibo.
35
35
  - `--worktree new-child` crea un worktree hijo del tuyo; `--base-branch` lo fija al commit base de la ronda (la rama de integración tras el último merge). **Siempre la rama de integración**, que ya nació de una base fresca (`SKILL.md` §4); nunca `main`/`develop` locales. La rama la nombra Orca: léela del recibo o de `orca worktree show`, no supongas `maw/<run>/<unit>`.
36
- - `--setup run` **siempre**: ejecuta el setup del repo (`orca.yaml`: `scripts.setup` y `sharedDirectories`; `.worktreeinclude`: copia de los `.env` de desarrollo). Sin él, el worker arranca sin dependencias ni entorno. Si el recibo avisa de ficheros de `.worktreeinclude` no copiados, díselo al usuario.
36
+ - `--setup run` **siempre**: ejecuta el setup del repo (`orca.yaml`: `scripts.setup` y `sharedDirectories`; `.worktreeinclude`: copia de los `.env` de desarrollo). Sin él, el worker arranca sin dependencias ni entorno. Si el recibo avisa de ficheros de `.worktreeinclude` no copiados, díselo al usuario. Si el proyecto no tiene `orca.yaml` o `.worktreeinclude` al día (`SKILL.md` §0, ficha antigua), añade al despacho el bloque `SETUP` como en los motores sin Orca: el worker copia los `.env` de desarrollo e instala en su arranque.
37
37
  - `--agent <proveedor> --model <modelo> [--effort <esfuerzo>]`: el proveedor y el modelo que le tocaron a la unidad en el plan (`olimpo.md` §Modelos). Sin modelo para ese nivel en ese proveedor, omite `--model` y `--effort` (el plan ya lo dijo). `--effort` exige `--model`.
38
38
  - Unidad de solo lectura en Orca (revisión `cross` por otro proveedor): `--worktree <selector del worktree de la unidad revisada>` en vez de `new-child`; no necesita worktree propio.
39
39
  - Si `worker-start` falla, **no** lo repitas: lee `failedStage` en el JSON y sigue la recuperación de la guía de Orca.