Configurable orchestration workflows (user-defined; agent + human-in-the-loop; progress + artifacts)

[dilipgv]

Configurable Orchestration Workflows

Problem

Today buzz workflows runs a linear step list with a fixed action set
(send_message | send_dm | set_channel_topic | add_reaction | call_webhook | request_approval | delay).
There is no step that invokes an agent, no branching, no loops, and no first-class
run state for artifacts/progress. Multi-pass processes (e.g. the IMPL workflow: Architect →
Plan Critic → Builder → Inspector → CI → merge) therefore can't be expressed natively — they
require a bespoke controller agent per process. Every new process = new custom code.

Goal

A user-defined, configurable orchestration engine where a workflow is a declarative graph of
steps, each step assigned to a dedicated agent or a human, with the engine tracking run
progress, chat, and artifacts across steps — reusable across many process types
(IMPL, bug triage, review-only, "scan Slack/email → summarize → act").

In scope

• Step assignees: a step targets a specific agent (by pubkey/role) OR a human (approval/input).
• Agent-invocation step: a real step type that dispatches a prompt to an assignee and
  waits for a structured result (not fire-and-forget send_message).
• Control flow: conditional branching + bounded loops (revise/rebuild) with a max-iteration cap.
• Run state & artifacts: each run tracks status per step, inputs/outputs, and attached
  artifacts (plans, diffs, PR ids, summaries) that later steps can read.
• Human-in-the-loop: approval/input gates that pause a run and resume on human action
  (extends today's request_approval).
• Progress & chat surface: a run is observable — current step, history, per-step
  responses/artifacts — visible in-channel.
• Templates: named, versioned workflow definitions users author and instantiate.

Out of scope (for v1)

• Arbitrary code execution inside steps (keep steps declarative; escape hatch = call_webhook).
• Cross-channel orchestration.
• A visual builder (YAML/JSON first; UI later).

Proposed shape (for design, not final)

• Definition: extend the workflow YAML with assignee (agent/human/role), a new
  invoke_agent action (prompt + expected structured output schema/verdict grammar), and
  on/when edges for branching + a loop construct with max_iterations.
• Run model: persistent run object keyed by run id — steps[] with
  status, assignee, input, output, artifacts[], attempts. Verdicts are structured
  tokens (e.g. APPROVED/REVISE/CLEAN) the engine branches on.
• Artifacts: typed references (PR event id, plan doc, message id, external URL) so steps
  hand real objects forward, not prose.
• Assignment/dispatch: engine posts the step to its assignee and blocks the run on that
  step until a structured result or human action arrives; bounded loops re-dispatch.

Example workflows this must support

1. IMPL — Architect(plan) → Plan Critic(loop) → Builder(draft PR) → Inspector(loop) → CI → captain approval+merge. (See thread root for full spec + WORKFLOW STAMP.)
2. Bug triage — intake → classify(agent) → severity gate(human) → assign → track.
3. Review-only — diff_posted → reviewer agent(s) → verdict → human sign-off.
4. Scan → summarize → act — schedule → Slack/email scan(agent) → summarize(agent) →
   proposed actions → human approval → execute.

Key risks / decisions to settle in design

• Loops & branching are the hard part — the current engine is linear. Adding an
  invoke_agent step that blocks on a structured result is the enabling primitive; loops
  and branches build on it. Needs a bounded-iteration cap to avoid silent stalls.
• Where run state lives (relay events vs a store) and how artifacts are referenced durably.
• Assignee resolution: agent-by-role vs by-pubkey; what happens when an assignee is offline.
• Authorization: today call_webhook needs owner/admin — decide the permission model for
  agent-invocation and human-gate steps.
• Backward compatibility with existing linear workflows.

Suggested milestones

• M1: invoke_agent step + structured-result wait + run/artifact state (unlocks single-pass
  agent workflows: review-only, scan→summarize).
• M2: branching + bounded loops + max_iterations (unlocks IMPL, bug triage).
• M3: human-in-the-loop input steps beyond approval; progress/chat surfacing in-app.
• M4: templates (author/version/instantiate) + assignee-by-role.

Open questions for the team

• Definition format: keep YAML, or move to a richer schema?
• Do we build this into the existing buzz workflows engine, or a new orchestration service
  that emits/consumes workflow events?
• Priority order of the four example workflows — which lands first as the proving ground?

[RegardV]

Strong +1 on step assignees specifically. One piece of evidence for that bullet that isn't in the issue yet: it's worth looking at how a workflow reaches an agent today, because the current mechanism is string matching on display names.

resolve_mention_pubkeys in crates/buzz-relay/src/workflow_sink.rs reverse-parses @Name out of workflow message text into the p tags that ACP agent-wake (event_mentions_agent) is gated on. Its own doc comment is explicit that this is load-bearing:

The client resolves mentions to p tags at compose time from an interactive autocomplete pick; the workflow path has only free text, so this reverse-parse defines the matching contract.

And it documents the constraints that follow:

• Members only. Candidates are the destination channel's members; global users are never matched.
• Exact display name. No substring, prefix, or fuzzy matching.
• Ambiguous names wake no one. If two or more members share the matched display name, no p tag is emitted for it — arbitrary selection would silently misroute and tagging all of them is a false-wake firehose.

The code is careful and the conservatism is clearly deliberate — but it means dispatch today has properties a workflow author can't see:

• renaming an agent silently breaks every workflow that targeted it;
• two agents sharing a display name means the step wakes nobody, with no error;
• an agent that isn't a member of the destination channel is never a candidate, so dispatch silently stops;
• an agent with no display_name can't be woken at all — the candidate list is built with filter_map(|u| { let name = u.display_name?; ... }), so it's dropped before matching runs;
• none of it is checkable when the workflow is authored — only at run time, by nothing happening.

In each case the kind:9 is still emitted; only the p tag is missing. So the run looks successful and the agent simply never wakes, which is the hardest shape of failure to debug from the outside.

A structured assignee (pubkey or role, as proposed) turns all four into authoring-time validation errors instead of silent runtime no-ops. That seems worth calling out as motivation independent of the orchestration engine itself — it's a correctness argument, not just an ergonomics one.