Skip to content

Workflow — Requirements alignment

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

Elicits requirements, refines the backlog and records the stakeholder alignment memo that names the exact agreed versions; a Reviewer approves the memo by hash (publication class) before any final UX run can use it.

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
personas artifact personas-v1 yes ArtifactService.ArtifactStored payload.descriptor == 'personas-v1'
research-insights artifact research-insights-v1 no ArtifactService.ArtifactStored payload.descriptor == 'research-insights-v1'
  • 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 requirements-alignment (release alias latest), model profile reasoning, input readiness-bundle-v1, client reference correlationId.

Definition

flowchart TD
    start(("RunAccepted"))
    elicit_requirements["Elicit requirements"]
    refine_backlog["Refine the backlog"]
    draft_alignment_memo["Draft the alignment memo"]
    approve_memo(["Approve the alignment memo"])
    start --> elicit_requirements
    elicit_requirements --> refine_backlog
    refine_backlog --> draft_alignment_memo
    draft_alignment_memo --> approve_memo
    done(("WorkflowRunCompleted"))
    approve_memo --> done
    class approve_memo gated
    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 Elicit requirements
elicit-requirements		 agent business-analyst
skill business-analyst-use-cases-and-acceptance-criteria		 none read — exponential ×3 (30s) PT30M — Requirements, processes and business rules with acceptance criteria, priorities and scope classes, each traced to its sources and personas.
2 Refine the backlog
refine-backlog		 agent product-owner
skill product-owner-prioritise-and-refine-the-backlog		 none sandbox elicit-requirements exponential ×3 (30s) PT30M — Epics and stories with acceptance criteria, persona and requirement links and rank, within the product owner's delegated authority.
3 Draft the alignment memo
draft-alignment-memo		 agent stakeholder-alignment
skill stakeholder-alignment-decision-memos-with-options		 none sandbox refine-backlog exponential ×3 (30s) PT30M — Records the decisions with options and consequences, the stakeholder positions, the scope classes and the open items, and names the exact ids, versions and hashes of the Vision Blueprint, requirements, backlog and personas it agrees on (research when present); alignment therefore waits for discovery (D63).
4 Approve the alignment memo
approve-memo		 human engine approval publication draft-alignment-memo none P7D — A Reviewer approves the exact memo version by its artifact hash; the requester and the memo's author are never eligible; a regenerated memo makes the pending request stale.

Step contracts

Step Inputs (name ← source) Outputs (name: descriptor)
elicit-requirements stakeholder-input ← input.stakeholder-input
vision-blueprint ← input.vision-blueprint		 requirements: requirements-v1
business-rules: artifact-v1
refine-backlog product-plan ← input.product-plan
feedback ← input.stakeholder-input
requirements ← steps.elicit-requirements.requirements		 backlog: backlog-v1
draft-alignment-memo vision-blueprint ← input.vision-blueprint
requirements ← steps.elicit-requirements.requirements
backlog ← steps.refine-backlog.backlog
personas ← input.personas
research-insights ← input.research-insights		 alignment-memo: alignment-memo-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

  • publication: the alignment memo bound to its exact artifact hash (D21, D58); the decider holds the Reviewer role and is never the requester or the author
  • Step approve-memo: publication-class decision on a artifact proposal taken from steps.draft-alignment-memo.alignment-memo; eligibility role:Reviewer; scope:project; separation of duties: the requester and the memo author are excluded (ADR-0015, D18); stale when a regenerated memo (new hash) makes the pending request Stale. 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 product-plan artifact-v1 no
in personas personas-v1 yes
in research-insights research-insights-v1 no
in stakeholder-input artifact-v1 no
out requirements requirements-v1 yes
out backlog backlog-v1 yes
out alignment-memo alignment-memo-v1 yes

Starts on RunAccepted from RunControlService when payload.workflowId == 'requirements-alignment'; emits ArtifactStored, ApprovalRequested, ApprovalDecided, 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-01 Trusted scope at every entry point · FR-06 Exact-version approvals · FR-08 Validated artifacts with lineageFUX: FUX-02 Inspectable assets and release readiness · FUX-05 Exact-version human decisionsADRs: ADR-0014, ADR-0015, ADR-0024, ADR-0026 · ADR index

Authored for the requirements-to-UX handoff (ADR-0026, D58); readiness-activated by the validated Vision Blueprint and the discovery personas (D63): the memo's approval is what the readiness correlation of ux-blueprint waits for, and a new personas version means a new memo and a new decision.