ADR-0030: A producing workflow definition for every awaited blueprint kind¶
Decision
This page records a decision and its status. A Proposed decision is not binding; an Accepted decision is binding on the Factory until amended or superseded.
- Status: Accepted 2026-11-05 by the product owner (decision D78); the placement in decision 4 was amended the same day (D84)
- Date: 2026-11-05
- Deciders: Dmitry Khaymov (product owner)
- Tags: workflows, blueprints, readiness, roles
Context¶
ADR-0027 made every workflow definition strict and added a rule that reports blueprint kinds a readiness bundle awaits but no definition produces. Six kinds were reported: API Gateway, Backend Library, Documentation, Observability, Pipeline and Security. A definition that awaits one of them could start only after a person wrote that blueprint through BlueprintService.
Nine members of eight definitions waited on these kinds. compliance-check and infrastructure-plan require the Security Blueprint, infrastructure-plan requires the Observability Blueprint, gateway-generation requires the API Gateway Blueprint, generate-libraries requires the Backend Library Blueprint, and documentation-sync and guides-generation require the Documentation Blueprint. delivery-run and preview-environment take the Pipeline Blueprint when it exists.
The owner was offered four ways to close the gap: a producing definition for every kind, an explicit decision that the kinds stay written by a person, a mix, or leaving it open. The owner chose a producing definition for every kind.
Decision¶
-
Six producing definitions (D78). Each follows the pattern of
database-blueprint: a readiness bundle of validated inputs, one planning step, one drafting step, then the submit, validate and check loop of ADR-0026 with at most two returns to the draft.Definition Awaits Role Produces security-blueprintService Blueprint Security Architect Security Blueprint api-gateway-blueprintService and Security Blueprints API Designer API Gateway Blueprint backend-library-blueprintService Blueprint and the derived domain model Solution Architect Backend Library Blueprint observability-blueprintService and Module Blueprints Observability Engineer Observability Blueprint pipeline-blueprintModule, Test and Security Blueprints DevOps Engineer Pipeline Blueprint documentation-blueprintService and Module Blueprints Documentation Writer Documentation Blueprint -
Role contracts. A role that authors a blueprint cannot require that blueprint as input. The Documentation Writer's Documentation Blueprint and module code inputs became optional, and the blueprint became a declared output. The DevOps Engineer, the Solution Architect and the Documentation Writer gained the optional inputs their new steps map. The Security Architect and the Observability Engineer, which no definition had cast, are now cast.
- A product that needs none. A product without a shared kernel yields a Backend Library Blueprint that declares no library. Definitions that await the kind are therefore never starved, as with the Database Blueprint of a product without persistence.
- Placement in the build backlog. Each definition is a feature of the Factory assets epic, placed where its first consumer needs it.
security-blueprintandobservability-blueprintare built in the second increment together withinfrastructure-plan, because the preview environment of that increment awaits the Infrastructure Blueprint and the owner decided that no person writes it (D84).pipeline-blueprintis in the fourth increment,documentation-blueprintin the fifth, andapi-gateway-blueprintandbackend-library-blueprintin the sixth. Until a definition is built, a person submits that blueprint through BlueprintService, as before.
Consequences¶
- The model carries 36 workflow definitions, all strict; 32 are readiness-activated and four are submitted by a person. Six coordinators were added, one per definition.
- The validator no longer reports an awaited blueprint kind without a producing definition, and the coverage page names a producer for every awaited kind.
- The order of blueprint production is explicit: the Service Blueprint first; then the Security and Backend Library Blueprints; then the Module Blueprints; then the Test, Observability and Documentation Blueprints; then the API Gateway and Pipeline Blueprints. The definitions wait on each other through readiness, with no manual start.
- More runs start without a person. Each is bounded by its own budget, and every Draft blueprint version it submits is a shared write that the project policy may gate (D64).
- The definitions are Draft, like all others, until an evaluation gate of ADR-0021 publishes them.
Alternatives rejected¶
- The six kinds stay written by a person. Rejected by the owner: a product could not be generated end to end without manual blueprint authoring.
- A mix, with definitions for the delivery-critical kinds only. Rejected by the owner in favour of all six.
- One definition that produces several kinds. Rejected: each kind has its own inputs, role and validation rule set, and a consumer waits for one kind.
- Drafting the blueprint inside the consuming definition. Rejected for the reason given in ADR-0027: a consumer must start from a validated version.
Revisit triggers¶
- A product routinely needs none of a kind: the producing definition may then be guarded by a condition instead of producing an empty blueprint.
- A role is curated with typed inputs: the mappings of its steps become descriptor checks.
- A new blueprint kind is awaited by a definition: the validator reports it until a producer exists.