Workflow — Application design¶
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 | application-design · version 1 · Draft (Draft → InReview → Published → Deprecated, BC-04) |
| Coordinator | application-design-coordinator · family Blueprint & Microservice Assembly |
| Owner service | WorkflowEngineService (BC-38) under Run Control (BC-03) |
| Starts on | readiness bundle readiness-bundle-v1 → RunAccepted from RunControlService when payload.workflowId == 'application-design' (event) |
| Steps | 4 · gated 0 · agents 1 |
| Budget per run | 600000 tokens · cap 60.0 USD · 240 min |
| Descriptor | workflow-definition-v1 · schema |
| Status | target |
Produces the application design of every module from its validated Module Blueprint: use cases and handlers, input and output ports, adapters and the telemetry span plan, stored as a typed artifact the generation recipe pins.
Authored design, Draft (D54, D57)
These definitions were authored 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.
Activation (readiness bundle)¶
The Workflow Engine's readiness correlation (BC-38, ADR-0026) joins the signals below per project and bundle fingerprint and submits one run through Run Control's SubmitRun; the run then starts on RunAccepted like every other definition. Nothing starts on a raw event.
| Slot | Kind | Descriptor | Required | Satisfied by | Predicate |
|---|---|---|---|---|---|
module-blueprints |
blueprint (Module) | blueprint-module-v1 |
yes | BlueprintService.BlueprintValidated |
payload.kind == 'Module' and payload.passed == true |
- Consistency: members are satisfied only within the trusted tenant and project of the signal; a newer version of any member opens a new correlation and supersedes the open one
- Fingerprint: sha256 over the sorted list of slot
version:hash of every satisfied required and optional member
- Idempotency key:
{scope}:{operation}:{workflowReleaseId}:{bundleFingerprint} - Deduplication: the same key returns the existing run (SubmitRun: same Idempotency-Key, same canonical body); a new member version yields a new fingerprint and a new correlation, and the Open one is Superseded; a different body under the same key is a 409 and the correlation is Superseded with reason conflict
- Submit: workflow
application-design(release aliaslatest), model profilereasoning, inputreadiness-bundle-v1, client referencecorrelationId.
Definition¶
flowchart TD
start(("RunAccepted"))
discover_use_cases["Discover the use cases"]
design_ports["Design the ports and adapters"]
plan_telemetry["Plan the telemetry spans"]
assemble_design["Assemble and store the design"]
start --> discover_use_cases
discover_use_cases --> design_ports
design_ports --> plan_telemetry
plan_telemetry --> assemble_design
done(("WorkflowRunCompleted"))
assemble_design --> done
classDef gated stroke:#B45309,stroke-width:2px
Shapes: rectangle = agent attempt · double rectangle = tool call · stadium = human decision · diamond = condition evaluated by the engine over recorded outputs · parallelogram = fan-out or join · circle = timer · cylinder = sub-workflow · flag = compensation. A thick amber border marks a gated step; a dashed edge is a bounded on_false loop. A step with a when guard runs only when its predicate over recorded outputs holds; otherwise the engine records it Skipped and its dependants treat it as satisfied (ADR-0027).
Steps¶
| # | Step | Kind | Runs | Gate | Class | Depends on | Retry | Timeout | Compensation | What it does |
|---|---|---|---|---|---|---|---|---|---|---|
| 1 | Discover the use casesdiscover-use-cases |
agent | application-architectskill application-architect-use-case-discovery |
none | read | — | exponential ×3 (30s) | PT30M | — | Commands, queries, event handlers and scheduled work per aggregate of the module, with their authorization and tenant scope. |
| 2 | Design the ports and adaptersdesign-ports |
agent | application-architectskill application-architect-output-port-designer |
none | read | discover-use-cases | exponential ×3 (30s) | PT30M | — | Input and output ports per use case and the adapters that implement them on the template switches of the module. |
| 3 | Plan the telemetry spansplan-telemetry |
agent | application-architectskill application-architect-telemetry-span-planner |
none | read | design-ports | exponential ×3 (30s) | PT30M | — | One span per use case with the attributes the observability conventions require. |
| 4 | Assemble and store the designassemble-design |
agent | application-architectskill application-architect-assemble-design |
none | sandbox | plan-telemetry | exponential ×3 (30s) | PT30M | — | Writes the application-design-v1 body bound to the exact Module Blueprint version and stores it as an artifact; ArtifactStored carries the descriptor. |
Step contracts¶
| Step | Inputs (name ← source) | Outputs (name: descriptor) |
|---|---|---|
discover-use-cases |
module-blueprint ← input.module-blueprints |
use-cases: artifact-v1 |
design-ports |
module-blueprint ← input.module-blueprintsuse-cases ← steps.discover-use-cases.use-cases |
ports: artifact-v1 |
plan-telemetry |
module-blueprint ← input.module-blueprintsuse-cases ← steps.discover-use-cases.use-casesports ← steps.design-ports.ports |
span-plan: artifact-v1 |
assemble-design |
module-blueprint ← input.module-blueprintsuse-cases ← steps.discover-use-cases.use-casesports ← steps.design-ports.portsspan-plan ← steps.plan-telemetry.span-plan |
application-design: application-design-v1 |
Every mapping names its source (input.* a workflow input, steps.* an ancestor's recorded output, bundle.* a readiness member) and the validator checks that every required input of the step's agent is mapped and that descriptors agree. |
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 | Required |
|---|---|---|---|
| in | module-blueprints | blueprint-module-v1 |
yes |
| out | application-design | application-design-v1 |
yes |
Starts on RunAccepted from RunControlService when payload.workflowId == 'application-design'; emits ArtifactStored, 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-11 Compatible templates and libraries through release gates
- XL: XL-09 Generation yields a usable consumer
- ADRs: ADR-0014, ADR-0024, ADR-0026, ADR-0027 · ADR index
Definition authored 2026-11-05 to close the generation input gap (ADR-0027, D66); Draft until an evaluation gate (ADR-0021) and a review publish it as a BC-04 asset release.