boocode/openspec/changes/orchestrator/artifacts/design-context.md

# Orchestrator (Phase 2) — settled design (source spec)

This is the behavioral specification for the BooCode Orchestrator, settled via a
`grill-me` interview. It is the ground truth for *what*; the implementation plan
covers *how*. Phase 1 (the standalone code conductor at `/opt/boocode/conductor/`)
is done; this is the in-app integration.

## Outcome

Bring the deterministic multi-agent conductor into the BooCode app: a user can
launch any Han flow from BooChat or BooCoder, watch each agent's progress live
(Paseo-style), and get an evidence-disciplined report — all on local Qwen, free.

## Settled decisions (immutable for this plan)

1. **One engine.** The conductor is the only engine. Every read-only Han skill IS
   a conductor flow. No single-agent degraded path.
2. **Two doors, full parity.** A slash command and an "Orchestrator" button, both
   on the shared `ChatInput` composer — so both appear in BooChat (ChatPane) and
   BooCoder (CoderPane), desktop and mobile (mobile = icon only). Launching from
   either opens the same run view.
3. **Run view = new pane kind.** A fourth pane kind, `orchestrator`, alongside
   `chat | terminal | coder`, opened as a new pane in the current session. It
   renders: flow + band at top, a list of agents with live status, each
   expandable to watch its stream; the final report at the top when done. Shape
   is parent-with-nested-children (Paseo's parent/subagents), not one-agent.
4. **Execution through BooCoder backends.** Each flow agent is a real BooCoder
   agent session dispatched through the existing `AgentBackend`s → live streaming
   via the existing AgentEvent→WS-frame pipeline, persisted to Postgres,
   resumable. New `flow_runs` + `flow_steps` tables in the coder schema; the
   conductor's scheduler fires each step's task as its deps complete.
5. **Read-only, no worktree.** Flows never write to the repo. Agents read the
   project's working directory directly; no git worktree is created. Read-only is
   enforced at dispatch (agents get no edit/write tools). The report is the only
   output.
6. **Qwen-only.** Default the loaded 35B (`llama-swap/qwen3.6-35b-a3b-mxfp4`),
   held as a single config value so additional local models slot in later with
   near-zero rework. No Claude path — Claude Code remains the Claude lane.
7. **Naming.** "Orchestrator." The existing Arena (same-task-on-N-models,
   `apps/coder/src/routes/arena.ts`) stays a separate feature.
8. **Skill placement.** The slash menu surfaces the read-only analysis/review set
   (research, investigate, code-review, architectural-analysis, security-review,
   gap-analysis, data-review, devops-review, issue-triage, project-discovery,
   test-planning). The Orchestrator button exposes the FULL catalog (22 flows),
   including the planning/authoring draft flows.
9. **Launch UX.** Slash launches instantly with defaults (band = small, target =
   the current pane's project, text after the command = the question/focus),
   opening an Orchestrator pane. The button opens a launcher first (pick flow,
   size, target/focus) then launches. Same run view either way.
10. **Report output.** Stored with the run in Postgres, shown at the top of the
    Orchestrator pane. Runs persist and are reopenable from a runs history.
    Export on demand: copy / save-to-file / send-to-chat. Nothing auto-written to
    the repo.
11. **Concurrency.** Multiple runs allowed; each its own pane. They share the one
    local model, so workers queue at llama-swap — panes show `queued` honestly.
12. **Sizing modes.** Han's bands (small/medium/large) select roster breadth per
    flow; a fast mode caps each worker's depth. Both carry over from Phase 1.

## Evidence & rule alignment (carried from Phase 1)

Flows apply Han's `evidence-rule` (trust classes, web corroboration gate,
no-evidence labeling) and `yagni-rule` (producing flows only), injected as
contracts. The adversarial-validator gate runs the review checklists and emits a
plain-language Summary + Confidence. This is already built in the conductor
(`conductor/src/contracts.ts`); Phase 2 must preserve it when porting dispatch
from `opencode run` subprocess to the BooCoder backends.

## Out of scope (Phase 2)

- The exact pixel-faithful per-skill Han report templates (spine-level only, by
  prior decision).
- A Claude execution path (Claude Code covers it).
- Folding the existing Arena into the Orchestrator (stays separate).
- Per-agent model tiering (single model per run for now; revisit when more local
  models exist).

## Open items the plan must resolve (the HOW)

- How the conductor's flow/spine definitions (Phase 1, `conductor/src/`) are
  reused vs. re-homed inside `apps/coder` when dispatch moves to the backends.
- The `flow_runs`/`flow_steps` schema shape, status lifecycle, and how a step maps
  to a `tasks`/`agent_sessions` row.
- How the scheduler resumes a run after a coder-service restart (mid-flight steps).
- The new `orchestrator` WS frame(s) and how the pane subscribes to per-agent
  streams (reusing the existing broker/AgentEvent pipeline).
- The Orchestrator pane component structure and how it nests N live agent streams
  without the crowding the grill rejected.