Skip to content

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

  1. 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-blueprint Service Blueprint Security Architect Security Blueprint
    api-gateway-blueprint Service and Security Blueprints API Designer API Gateway Blueprint
    backend-library-blueprint Service Blueprint and the derived domain model Solution Architect Backend Library Blueprint
    observability-blueprint Service and Module Blueprints Observability Engineer Observability Blueprint
    pipeline-blueprint Module, Test and Security Blueprints DevOps Engineer Pipeline Blueprint
    documentation-blueprint Service and Module Blueprints Documentation Writer Documentation Blueprint
  2. 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.

  3. 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.
  4. Placement in the build backlog. Each definition is a feature of the Factory assets epic, placed where its first consumer needs it. security-blueprint and observability-blueprint are built in the second increment together with infrastructure-plan, because the preview environment of that increment awaits the Infrastructure Blueprint and the owner decided that no person writes it (D84). pipeline-blueprint is in the fourth increment, documentation-blueprint in the fifth, and api-gateway-blueprint and backend-library-blueprint in 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.