boocode/openspec/changes/orchestrator-flow-advanced/proposal.md

Orchestrator — Advanced Flow Patterns

Status: Proposed Epic: orchestrator-flow-advanced Depends on: v2.7.17-orchestrator (flow-runner already shipped)

Why

The orchestrator (shipped v2.7.17) runs sequential research/analysis flows on local Qwen. Each step is a linear dependency chain: A → B → C. This works for analysis flows (code-review, investigate) but limits three high-value scenarios:

1. Parallel research — "Analyze this from 3 angles" currently requires 3 separate runs. A single flow with parallel branches would halve the wall-clock time.
2. Adaptive depth — "Investigate bug, and if it's a security issue, escalate to security review" requires conditional branching. Currently all steps run unconditionally.
3. Human-in-the-loop — "Review the diff and approve before applying" requires the orchestrator to pause and wait for user input before proceeding.

The patterns from the Ion hybrid workflow engine (trigger rules, event sourcing, approval gates, variable substitution) provide a proven vocabulary for these scenarios — we adapt the patterns without adopting the project.

What Changes

Trigger rules on step deps

Add trigger_rule?: 'all_success' | 'one_success' | 'all_done' to the Step type. Default all_success preserves existing behavior.

• all_success — step runs when ALL dependencies complete successfully (current behavior)
• one_success — step runs when ANY dependency completes (parallel research: whichever finishes first seeds the synthesis)
• all_done — step runs when all deps finish regardless of status (cleanup/reporting steps)

Variable substitution in step prompts

Add $stepId.output and $stepId.output.field syntax in step prompts. The flow-runner resolves these before dispatching.

• $research.output — the full text output of step with id "research"
• $classify.output.severity — the "severity" field from step output parsed as YAML/JSON frontmatter

Human approval gate

New kind: 'approval' step type that pauses the flow and publishes a permission frame to the user channel. Flow resumes when the user approves or rejects.

Event-sourced step log

Append-only event log for each step execution (start, complete, fail, skip, pause, resume). Enables deterministic resume after coder restart without polling.

Non-Goals

• No YAML DAG format (stay with TypeScript flow definitions)
• No CLI tool (orchestrator stays in-app)
• No replacement of the existing flow definitions — additive changes only
• No VM sandbox or WASM