Agent Workflow Orchestration

Why declare rather than prompt

An agent defined by a prompt inside a function is invisible to review. You cannot diff it meaningfully, you cannot tell what tools it can reach, and you certainly cannot tell what it is allowed to change.

So the unit here is a file. Each workflow declares:

• the capability it serves — the thing being done, from a registry
• its steps, each naming one tool, with depends_on for ordering and a parallel group for steps that can run together
• its autonomy mode — observe, assist or autofix
• the tools it may use, each marked primary or supporting
• the evidence a run must produce to be considered complete

That is reviewable. Someone can look at a pull request and say "this workflow should not be in autofix" before it ever runs.

Scale of the catalog

Declared	Count
Workflow definitions	38
Capabilities	41
Tools	15
Cron schedules, each with its own budget	36
Event trigger rules	6
Predefined chains	2

The 38 group into diagnostics and incident response, single-tool utilities, infrastructure monitoring, orchestration control loops, research and learning, governance and executive planning, and offer intelligence. Exactly one is declared in autofix mode; the rest observe or assist.

The workflow

1. Automated software

   Trigger

   Decision point: One of three: a cron schedule, an event on the trigger stream, or a manual run. There is no fourth.

2. Approval gate

   Event rules with dedup windows

   Decision point: Six rules map an event to a workflow and a mode — a dead-lettered job, an exhausted offer cap, a score drop, an earnings drop, a bounce spike, a placement drop. Each carries its own dedup window so a flapping signal cannot storm the queue.

3. Automated software

   Resolve the definition

   Load the workflow by key: its capability, steps, required evidence and declared tools.

4. Approval gate

   Governance gate

   Decision point: Seven sequential checks before execution. Documented separately — nothing runs without passing all of them.

5. Data store

   Retrieve grounded context

   Hybrid search over curated documentation, so the agent reasons from written architecture rather than inferring it.

6. AI / LLM

   Execute steps under budget

   Ordered by depends_on, with parallel groups running together. Bounded by the schedule's token, tool-call and runtime ceilings.

7. Approval gate

   Approval gate for autofix

   Decision point: Requiring approval for autofix defaults to on. The run parks in an awaiting-approval state and resumes only after a human approves — and resumption re-verifies both the approval and the run state rather than trusting the first check.

8. Data store

   Record the run

   Per-step timings, tool calls, artifacts and required evidence, so the run is auditable rather than reconstructed from logs.

9. Monitoring / feedback

   Chain continuation

   Decision point: Two chains exist — one for offer optimization in observe mode, one for campaign optimization in assist. A chain passes the prior run forward, stops on error outside observe mode, and halts at an approval gate rather than stepping over it.

Legend

• Automated software
• AI / LLM
• Data store
• Approval gate
• Monitoring / feedback

Decision points

• Which capability does this task want? Free-text intent is routed to a capability by weighted pattern matching before a workflow is chosen.
• Has an equivalent event fired inside the dedup window? If so, drop it.
• Which mode is this capability permitted to run in? Resolved by the governance gate, not by the definition's own wish.
• Does this run need approval? Autofix does, by default.
• Continue the chain? Only outside error states, and never past an approval gate.

Responsibilities

Human approval points

1. Adding or changing a definition — it is a file, so this is a code review.
2. Any autofix run, which parks awaiting approval by default.
3. Escalating a capability's permitted mode.

Failure handling

Failure	Response
Budget exhausted mid-run	The run ends and is recorded as exhausted. Repeated exhaustion means the task is mis-scoped, not that the ceiling is wrong.
A step's tool fails	Recorded against the step. Non-observe chains stop rather than continuing on a broken prior result.
Event storm	Per-rule dedup windows collapse it.
Workflow disabled by risk score	The orchestrator refuses it up front rather than starting and aborting.
Approval never given	The run stays parked. It does not time out into execution.
Definition references an unknown tool	Caught at seed time — which is also how I know one declared tool is referenced by no workflow.

Monitoring

Runs and steps per agent, budget exhaustion rate, dedup collapse ratio, approval queue depth and age, chain completion rate, and — the one that matters most for this workflow — how many runs carry a workflow key versus none.