Skip to content

Workflow — Plan a run

Generated from the architecture model

This page is rendered from model/**/*.yaml by tools/docs_model during mkdocs build. Edit the YAML, not this page; hand-written design lives on the linked service, platform and plane pages.
Workflow id plan-run · version 1 · Draft (Draft → InReview → Published → Deprecated, BC-04)
Coordinator ai-planner-coordinator · family Planning, Intent Routing & Product Vision
Owner service WorkflowEngineService (BC-38) under Run Control (BC-03)
Starts on RunAccepted from RunControlService (event)
Steps 5 · gated 0 · agents 1
Budget per run 600000 tokens · cap 60.0 USD · 240 min
Descriptor workflow-definition-v1 · schema
Status target

Turns an accepted run submission into a workflow-definition instance: classifies the intent, selects a Published definition or composes a plan validated against the DSL, and hands the first steps to the engine.

Authored design, Draft (D54, D57)

These definitions were authored on 2026-10-14 from the coordinator cards as design assumptions. None is published, evaluated or has run; agents are named by id as design bindings, not as tested integrations.

Definition

flowchart TD
    start(("RunAccepted"))
    classify_intent["Classify the intent"]
    select_definition{"Published definition available?"}
    compose_plan["Compose a plan"]
    validate_plan{"Validate against the DSL"}
    start_steps[["tool: Start the first steps"]]
    start --> classify_intent
    classify_intent --> select_definition
    select_definition --> compose_plan
    compose_plan --> validate_plan
    validate_plan --> start_steps
    done(("WorkflowRunCompleted"))
    start_steps --> done
    classDef gated stroke:#B45309,stroke-width:2px
Hold "Alt" / "Option" to enable pan & zoom

Shapes: rectangle = agent attempt · double rectangle = tool call · stadium = human decision · diamond = condition evaluated by the engine · parallelogram = fan-out or join · circle = timer · cylinder = sub-workflow · flag = compensation. A thick amber border marks a gated step.

Steps

# Step Kind Runs Gate Class Depends on Retry Timeout Compensation What it does
1 Classify the intent
classify-intent		 agent factory-workflow-orchestrator none read — exponential ×2 PT30M — Reads the submission and names the intent class and candidate definitions with the reasoning profile; no tool with side effects.
2 Published definition available?
select-definition		 condition engine none sandbox classify-intent none PT1M — True when a Published definition matches the intent class and the scope; the run then instantiates it unchanged. Condition: intent.matchedDefinition != null.
3 Compose a plan
compose-plan		 agent factory-workflow-orchestrator none read select-definition exponential ×2 PT30M — Composes a plan as a workflow-definition instance from the intent, the blueprint and the agent catalog; every step names a Published agent release. Condition: not intent.matchedDefinition.
4 Validate against the DSL
validate-plan		 condition engine none sandbox compose-plan none PT1M — The engine validates the instance against workflow-definition-v1, the agent release states and the budget; an invalid plan fails the run with the validation report. Condition: plan.valid.
5 Start the first steps
start-steps		 tool knowledge-search none read validate-plan none PT1M — The engine records the plan, emits StepReady for the steps without dependencies and Run Control dispatches them.

Gates and approvals

No approval is required: every step runs in the read or sandbox class; the agents' own tool calls still carry their classes (D21). Compensation steps run in reverse order of the succeeded steps on failure after the last checkpoint; a step without a compensation leaves its sandbox output in place and the run ends Failed with the evidence (ADR-0014, recovery not replay).

Inputs, outputs and events

Direction Name Descriptor
in run-submission run-submission-v1
in vision-blueprint blueprint-vision-v1
out plan workflow-definition-v1

Starts on RunAccepted; emits WorkflowRunStarted, StepReady, plus the engine's WorkflowRunStarted, StepReady, StepRunStateChanged and WorkflowRunCompleted / WorkflowRunFailed and Run Control's run and attempt events (ADR-0014).

Decisions and traceability

FR: FR-02 Immutable asset releases · FR-03 Idempotent work requests and persisted run stateXL: XL-03 Read-only assessmentFUX: FUX-03 Task-first submissionADRs: ADR-0014, ADR-0024 · ADR index

The start-steps step is an engine action; it is modelled as a read-class tool step so the DAG shows where the engine takes over (D54). Semantic Kernel planners are excluded; the composition runs on the Agent Framework (ADR-0024).