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

# 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?

Start with the existing `buzz workflows` engine and its workflow YAML, especially the current linear actions such as `request_approval` and `call_webhook`. Review the proposed M1–M4 milestones and open design questions before identifying implementation boundaries. Done requires an agreed design for agent invocation, run state, branching, human gates, and templates.

Written by the indexing model from the issue text.