Workflow — UX Blueprint

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	ux-blueprint · version 1 · Draft (Draft → InReview → Published → Deprecated, BC-04)
Coordinator	ux-blueprint-coordinator · family Planning, Intent Routing & Product Vision
Owner service	WorkflowEngineService (BC-38) under Run Control (BC-03)
Starts on	readiness bundle ux-input-bundle-v1 → RunAccepted from RunControlService when payload.workflowId == 'ux-blueprint' (event)
Steps	8 · gated 0 · agents 1
Budget per run	600000 tokens · cap 60.0 USD · 240 min
Descriptor	workflow-definition-v1 · schema
Status	target

Final UX pass on the typed, aligned input bundle: journeys and screens bound to the Service Blueprint's operations, the UX Blueprint version validated with a receipt, the coverage matrix against the agreed stories and the Claude Design handoff pack.

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
vision-blueprint	blueprint (Vision)	blueprint-vision-v1	yes	BlueprintService.BlueprintValidated	payload.kind == 'Vision' and payload.passed == true
service-blueprint	blueprint (Service)	blueprint-service-v1	yes	BlueprintService.BlueprintValidated	payload.kind == 'Service' and payload.passed == true
alignment-memo	approval	alignment-memo-v1	yes	RunControlService.ApprovalDecided	payload.state == 'Approved' and payload.proposalKind == 'artifact' and payload.proposalDescriptor == 'alignment-memo-v1'
requirements	artifact	requirements-v1	yes	ArtifactService.ArtifactStored	payload.descriptor == 'requirements-v1'
backlog	artifact	backlog-v1	yes	ArtifactService.ArtifactStored	payload.descriptor == 'backlog-v1'
personas	artifact	personas-v1	yes	ArtifactService.ArtifactStored	payload.descriptor == 'personas-v1'
journey-seeds	artifact	journey-seeds-v1	no	ArtifactService.ArtifactStored	payload.descriptor == 'journey-seeds-v1'
research-insights	artifact	research-insights-v1	no	ArtifactService.ArtifactStored	payload.descriptor == 'research-insights-v1'

• Consistency: alignment-memo.agreedVersions must equal the member references of vision-blueprint, requirements, backlog and personas (id, version, hash); the memo is approved only after discovery produced the personas (D63); a mismatch supersedes the correlation instead of submitting
• Fingerprint: sha256 over the sorted list of slotversion: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 input hash); a new member version yields a new fingerprint and a new correlation, and the Open one is Superseded; a different input under the same key is a 409 and the correlation is Superseded with reason conflict
• Submit: workflow ux-blueprint (release alias latest), model profile reasoning-high, input ux-input-bundle-v1, client reference correlationId.

Definition

flowchart TD
    start(("RunAccepted"))
    map_journeys["Map journeys and screens"]
    draft_ux_blueprint["Draft the UX Blueprint"]
    submit_version[["tool: Submit the Draft version"]]
    validate[["tool: Validate the blueprint"]]
    check_valid{"Validation passed?"}
    coverage_matrix["Coverage matrix"]
    check_coverage{"Coverage complete?"}
    handoff_pack["Handoff pack"]
    start --> map_journeys
    map_journeys --> draft_ux_blueprint
    draft_ux_blueprint --> submit_version
    submit_version --> validate
    validate --> check_valid
    check_valid --> coverage_matrix
    coverage_matrix --> check_coverage
    check_coverage --> handoff_pack
    done(("WorkflowRunCompleted"))
    handoff_pack --> done
    check_valid -. "retry up to 2" .-> draft_ux_blueprint
    check_coverage -. "retry up to 1" .-> map_journeys
    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 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.

Steps

#	Step	Kind	Runs	Gate	Class	Depends on	Retry	Timeout	Compensation	What it does
1	Map journeys and screens map-journeys	agent	ux-designer skill ux-designer-journeys-and-screens-with-states	none	read	—	exponential ×3 (30s)	PT30M	—	Orders journeys as screen steps with decision points and adverse branches from the personas, journey seeds, backlog stories and the Service Blueprint's operations.
2	Draft the UX Blueprint draft-ux-blueprint	agent	ux-designer skill ux-designer-state-families-and-status-palette	none	sandbox	map-journeys	exponential ×3 (30s)	PT45M	—	Writes the UX Blueprint document: personas projection, journeys, screens with read models and commands, state families, design system, accessibility and locales; metadata.dependsOn names the bundle's Vision and Service versions (UX-005).
3	Submit the Draft version submit-version	tool	blueprint-submit-version	none	shared-write	draft-ux-blueprint	fixed ×2 (10s)	PT2M	—	Stores the document as a project-scope Draft BlueprintVersion of its kind (idempotent on document hash); a shared write that the project policy may gate; Draft versions are autonomous by default (D64).
4	Validate the blueprint validate	tool	blueprint-validate	none	sandbox	submit-version	fixed ×2 (10s)	PT5M	—	BlueprintService validates the version against blueprint-ux-v1 and rules UX-001 to UX-005 and its rule set and returns a receipt; BlueprintValidated is emitted with passed true or false.
5	Validation passed? check-valid	condition	engine	none	read	validate	none	PT1M	—	Engine condition over the recorded receipt; findings go back to the draft step up to twice, then the run fails with the report. Condition: steps.validate.validation-receipt.passed == true. On false: back to draft-ux-blueprint up to 2 time(s) with steps.validate.validation-receipt.
6	Coverage matrix coverage-matrix	agent	ux-designer	none	sandbox	check-valid	exponential ×3 (30s)	PT30M	—	Maps every backlog story and requirement of the bundle to the personas, journeys, screens and operations of the validated blueprint; names the gaps.
7	Coverage complete? check-coverage	condition	engine	none	read	coverage-matrix	none	PT1M	—	Engine condition over the recorded coverage matrix: unresolved gaps (gaps minus accepted deferrals naming their authority) must be zero; otherwise the journeys are reworked once more (UX-006). Condition: steps.coverage-matrix.coverage-matrix.summary.unresolvedGaps == 0. On false: back to map-journeys up to 1 time(s) with steps.coverage-matrix.coverage-matrix.
8	Handoff pack handoff-pack	agent	ux-designer skill ux-designer-handoff-pack-master-brief-packs-fixtures-accepta	none	sandbox	check-coverage	exponential ×3 (30s)	PT30M	—	Master brief, per-work-area packs, fixtures and acceptance for Claude Design, bound to the validated blueprint version and its coverage matrix.

Step contracts

Step	Inputs (name ← source)	Outputs (name: descriptor)
map-journeys	vision-blueprint ← input.vision-blueprint service-blueprint ← input.service-blueprint personas ← input.personas requirements ← input.requirements backlog ← input.backlog alignment-memo ← input.alignment-memo journey-seeds ← input.journey-seeds research-insights ← input.research-insights	journeys-draft: artifact-v1
draft-ux-blueprint	vision-blueprint ← input.vision-blueprint service-blueprint ← input.service-blueprint personas ← input.personas requirements ← input.requirements backlog ← input.backlog alignment-memo ← input.alignment-memo journey-seeds ← input.journey-seeds research-insights ← input.research-insights journeys-draft ← steps.map-journeys.journeys-draft	ux-blueprint-draft: blueprint-ux-v1
submit-version	document ← steps.draft-ux-blueprint.ux-blueprint-draft	version-ref: blueprint-version-ref-v1
validate	version-ref ← steps.submit-version.version-ref	validation-receipt: blueprint-validation-receipt-v1
coverage-matrix	vision-blueprint ← input.vision-blueprint service-blueprint ← input.service-blueprint personas ← input.personas requirements ← input.requirements backlog ← input.backlog alignment-memo ← input.alignment-memo journey-seeds ← input.journey-seeds research-insights ← input.research-insights ux-blueprint ← steps.draft-ux-blueprint.ux-blueprint-draft	coverage-matrix: ux-coverage-matrix-v1
handoff-pack	vision-blueprint ← input.vision-blueprint service-blueprint ← input.service-blueprint personas ← input.personas requirements ← input.requirements backlog ← input.backlog alignment-memo ← input.alignment-memo journey-seeds ← input.journey-seeds research-insights ← input.research-insights ux-blueprint ← steps.draft-ux-blueprint.ux-blueprint-draft coverage-matrix ← steps.coverage-matrix.coverage-matrix validation-receipt ← steps.validate.validation-receipt	handoff-pack: ux-handoff-pack-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

• shared-write: creating a Draft blueprint version in project scope is autonomous unless the project policy (BC-20) gates blueprint drafts, in which case an approval bound to the document hash is requested (D64) 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	vision-blueprint	blueprint-vision-v1	yes
in	service-blueprint	blueprint-service-v1	yes
in	alignment-memo	alignment-memo-v1	yes
in	requirements	requirements-v1	yes
in	backlog	backlog-v1	yes
in	personas	personas-v1	yes
in	journey-seeds	journey-seeds-v1	no
in	research-insights	research-insights-v1	no
out	ux-blueprint	blueprint-ux-v1	yes
out	coverage-matrix	ux-coverage-matrix-v1	yes
out	handoff-pack	ux-handoff-pack-v1	yes
out	validation-receipt	blueprint-validation-receipt-v1	yes

Starts on RunAccepted from RunControlService when payload.workflowId == 'ux-blueprint'; emits BlueprintValidated, 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-06 Exact-version approvals · FR-07 Authorized context assembly with provenance · FR-08 Validated artifacts with lineageFUX: FUX-11 Software Factory journey · FUX-12 Documented viewsXL: XL-08 Evaluate before promotionADRs: ADR-0014, ADR-0024, ADR-0026 · ADR index

The final UX pass of the requirements-to-UX handoff (ADR-0026, D59, D60): activated by the Workflow Engine's readiness correlation, never by a raw event; replaces ux-personas together with ux-discovery.

Related

• Workflow definitions · Workflows catalog · Agent Mesh workflows · Durable execution (ADR-0024) · Approvals