boocode/openspec/changes/orchestrator/tasks.md

Orchestrator (Phase 2) — tasks

Decomposition in dependency order, grouped by subsystem. Each group notes its deploy surface. Decisions referenced are in artifacts/implementation-decision-log.md; the HOW is in design.md.

Deploy surfaces:

• coder = sudo systemctl restart boocoder
• web/contracts = pnpm -C packages/contracts build && docker compose up --build -d boocode

---

1. Re-home conductor defs + DispatchFn seam + model param (coder) — [D-1]

• Copy spine.ts, flows/*, contracts.ts, types.ts, render.ts into apps/coder/src/conductor/. Do NOT copy flow.ts or dispatch.ts.
• Copy the 23 personas (conductor/agents/*.md) into the coder tree.
• Add a DispatchFn field to StepContext (types.ts); replace flows/code-review.ts:10 (import { dispatchAgent } from '../dispatch.js') and its call site (:62) with a call through ctx.dispatch.
• Parameterize spine.ts:122 process.env.CONDUCTOR_MODEL → the run's model (threaded through the spine factory / step context).
• Confirm the Phase-1 CLI (conductor/) still builds + runs unchanged (regression oracle).
• Coder build passes (pnpm -C apps/coder build).

2. Schema: flow_runs / flow_steps (coder) — [D-5], [D-10]

• Add flow_runs to apps/coder/src/schema.sql (project_id no FK; band CHECK small|medium|large; status CHECK-named running|completed|failed; input JSONB CHECK input ? 'question'; report TEXT nullable; timestamps via clock_timestamp()).
• Add flow_steps (run_id FK→flow_runs CASCADE; step_id; kind CHECK agent|code; status CHECK-named pending|running|completed|failed|skipped — NO queued; task_id→tasks SET NULL nullable; chat_id→chats SET NULL; output TEXT FULL; UNIQUE(run_id, step_id)).
• Indexes flow_steps(run_id, status), flow_runs(project_id, created_at DESC).
• Explicit CHECK names + DROP-IF-EXISTS → guarded-ADD migration discipline.
• Verify idempotent re-apply (schema applies clean twice).

3. WS frames in all three registries (contracts + server + web) — [D-6]

• Add flow_run_started (run_id, flow_name, band, steps[{step_id, agent, kind, chat_id, label}]) + flow_run_step_updated (run_id, step_id, status, run_status?, report?) to packages/contracts/src/ws-frames.ts WsFrameSchema; rebuild (pnpm -C packages/contracts build).
• Add both to the server loose InferenceFrame union (apps/server/src/services/inference/turn.ts).
• Add both to the web strict WsFrame union (apps/web/src/api/types.ts) — the wire-format gate.
• Confirm the per-agent stream reuses existing delta/tool_call/ message_complete by chat_id (no new stream frames).

4. Flow-runner + onTaskTerminal hook + plan mode + per-step chats (coder) — [D-2], [D-3], [D-4]

• Add onTaskTerminal(taskId, state) callback to createDispatcher, invoked at the external terminal transitions (dispatcher.ts:642-646, :659-661). No change to internal run functions.
• Create apps/coder/src/services/flow-runner.ts: load flow def, derive ready wave, INSERT flow_runs/flow_steps, build prompts via step.run(ctx) in-process (contracts injected), INSERT a synthetic chats row per agent step, INSERT each ready agent step as a tasks row with state='pending', mode_id='plan' (hardcoded, never user-overridable), chat_id=<synthetic>.
• Run code steps inline (flow_steps.task_id NULL).
• On onTaskTerminal: read FULL task output → flow_steps.output, mark step, derive + INSERT next wave; on last wave render report → flow_runs.report, status='completed'.
• Publish flow_run_started on launch and flow_run_step_updated on each step transition (report on completion).

5. Resume on startup (coder) — [D-9]

• Add initResume (coder startup) over flow_runs WHERE status='running': task completed → mark step done + advance; task lost/failed → re-dispatch (fresh task, mode_id='plan'); keep completed steps.
• Verify a coder restart mid-run reconciles and advances (manual smoke).

6. Routes: create / list / reopen (coder) — [D-2], [D-7]

• POST /api/runs {project_id, flow_name, band, input:{question}, model?} → create run, start flow-runner, return run_id.
• GET /api/runs?project_id= → runs history.
• GET /api/runs/:id → run + steps + report (reopen).

7. orchestrator pane kind + OrchestratorPane (web) — [D-7]

• Add orchestrator to WorkspacePaneKind (api/types.ts); thread through useWorkspacePanes, Workspace, NewPaneMenu, ChatTabBar, PaneHeaderActions (follow the markdown_artifact/html_artifact precedent).
• OrchestratorPane.tsx: run header, report-at-top on completion, collapsed roster reusing AgentStatusDot (AgentComposerBar.tsx:204), expand-one-at-a-time well reusing CoderPane stream rendering keyed by step chat_id, mobile single-column inline expand, auto-expand-follows-active.
• Subscribe to flow_run_started (build roster) + flow_run_step_updated (status/report) + reused stream frames by chat_id; handlers idempotent (event-dedup discipline).

8. Workflow toolbar button + slash launch wiring, parity (web) — [D-8]

• Add the Workflow (lucide) button to ChatInput's controls row between SquareSlash and Globe (ChatInput.tsx:648-732); "Flows" desktop, icon-only mobile. Confirm the row stays one line (no scroll/wrap) on mobile.
• Slash (/flow <focus>): launch instantly with defaults (band small, current pane's project, text-after = focus), open an Orchestrator pane.
• Verify parity: the button + slash both appear in BooChat (ChatPane) AND BooCoder (CoderPane) since ChatInput is shared.

9. FlowLauncherDialog (web) — [D-8]

• FlowLauncherDialog.tsx: 5 category tabs (Analysis/Discovery/Planning/ Authoring/Review) filtering the flow list (flows/index.ts), + size + focus + fast toggle; defaults Analysis/Small/off. On launch → POST /api/runs, open the Orchestrator pane.

10. Runs history + export (web) — [D-7]

• Runs history entry point in NewPaneMenu (backed by GET /api/runs); reopening opens an Orchestrator pane via GET /api/runs/:id.
• Export in the pane header …: copy / save-to-file / send-to-chat (existing sendToChat, lib/events.ts), conditional on a completed report.

11. Tests — [D-2], [D-9]

• Coder vitest for the scheduler: ready-wave derivation from a flow def, onTaskTerminal advancement, last-wave report render. Extract a pure helper (e.g. flow-runner-decisions.ts) for the wave/advance logic (repo pattern: turn-guard.ts/lifecycle-decisions.ts).
• Coder vitest for resume: completed step kept, lost/failed step re-dispatched (pure reconcile helper).
• Parity check: assert the Workflow button + slash are wired through the shared ChatInput (so both panes get them) — code-level assertion, no web test harness exists.

---

Sequencing notes

• Groups 1–6 are coder-only (one systemctl restart boocoder after 1–6 land together, or incrementally).
• Group 3 (contracts) must build before groups 7–10 consume the frame types (pnpm -C packages/contracts build first).
• Groups 7–10 are web; ship with docker compose up --build -d boocode.
• Group 11 lands alongside the code it tests (coder tests after group 4/5).