Skip to content

AIFACTORY-FEAT-115: Workflow definition: Preview environment

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.

A design artefact, not a tracker

This backlog is generated from model/backlog/ and validated against the architecture model. No work item exists in any tracker, and no item carries a date, an estimate or an assignee (ADR-0029).

Epic Factory assets: workflow definitions, agents and skills · Increment I2 Deliver it · State elaborated · Route solution-architect · Build order 104 of 185 (Factory code)

The workflow definition preview-environment as a published asset: Creates a per-developer preview environment from a change proposal, keeps it for its time to live and tears it down; a later capability of Runtime Cloud exposed as a workflow. It has 5 steps, names the agents devops-engineer, environment-manager and the tools none, and is executed by WorkflowEngineService under Run Control.

Delivers —
Stubs —
Realizes workflows: preview-environment
adrs: ADR-0014, ADR-0017, ADR-0027
Requirements FR-09, XL-12
Depends on AIFACTORY-FEAT-189 AgentRegistryService: the publication path of releases from I2
Sources model/workflows/preview-environment.yaml

Scenarios to trace (5, catalog): SCN-preview-environment-001 ✓, SCN-preview-environment-002 ✓, SCN-preview-environment-003 ✓, SCN-preview-environment-004 ✓, SCN-preview-environment-005 ✓

AIFACTORY-US-027: A change proposal gets a preview environment that tears itself down

behavior · persona requester As a requester, I want a preview environment with my proposed change deployed, kept for a limited time, so that I can try the generated service before it is merged, without leaving infrastructure behind.

The integration PBI of the definition preview-environment. When PipelineExecutionService publishes ChangeProposalOpened for a project and BlueprintService has published BlueprintValidated for a passed Infrastructure Blueprint of the same project, WorkflowEngineService satisfies the two required readiness members change-proposal (pull-request-proposal-v1, hashed on the pull request reference) and infrastructure-blueprint (blueprint-infrastructure-v1), and the optional pipeline-blueprint when a validated Pipeline Blueprint exists. It submits the run itself through SubmitRun of RunControlService with a service token that names the project and the bundle idempotency key (D131): the same proposal version returns the existing run and a new version of a member supersedes the open correlation. Run Control accepts the run and publishes RunAccepted; the engine loads the Published release the run pinned through AgentRegistryService and marks the five steps ready in the declared order: resolve-change, approve-preview, request-preview, time-to-live and teardown, with the agents environment-manager and devops-engineer on their pinned releases. Every step records exactly one outcome, the run reports exactly one outcome to Run Control (ADR-0014) and stays within the declared budget. Before any run, the definition release and the agent releases of its two agents, with any skill, tool or model profile release they need that is not yet Published, are submitted through SubmitRelease and published through PublishRelease of AgentRegistryService (feature agent-registry-service-publication); each publication is approved by a Reviewer who is not the submitter, a Platform admin for a model profile release, no evaluation verdict is required before I4, and the runs pin the Published release, never a Draft one (D140). The step behaviour is specified in AIFACTORY-US-1187 to AIFACTORY-US-1189; this PBI proves the chain on the recorded fixture.

Acceptance criteria

AC1 Given PipelineExecutionService/ChangeProposalOpened for a project and a BlueprintService/BlueprintValidated with kind Infrastructure and passed true for the same project and tenant, when both required members are satisfied, then WorkflowEngineService/ReadinessRunSubmitted is emitted once and the run is submitted through RunControlService/SubmitRun with a service token naming the project (D131); a repeated event for the same proposal version returns the existing run.
AC2 Given a newer version of the proposal or of the Infrastructure Blueprint is announced while a correlation is open, when the readiness bundle is recomputed, then WorkflowEngineService/ReadinessSuperseded is emitted for the open correlation and a new correlation opens with the new fingerprint.
AC3 Given the Published release of preview-environment, authored exactly as in model/workflows/preview-environment.yaml, submitted through AgentRegistryService/SubmitRelease and published through AgentRegistryService/PublishRelease after an approval by a Reviewer who is not the submitter (D140), when RunControlService/RunAccepted arrives for a run that pinned it, then WorkflowEngineService/WorkflowRunStarted is emitted and preview-environment/resolve-change, preview-environment/approve-preview, preview-environment/request-preview, preview-environment/time-to-live and preview-environment/teardown become ready in that order, each agent step on the pinned Published release of its agent, and no Draft release is loaded.
AC4 Given every step succeeds, when the teardown completes, then preview-environment (artifact-v1) is the run output, WorkflowEngineService/WorkflowRunCompleted is emitted once and RunControlService/RunCompleted follows exactly once (ADR-0014).
AC5 Given the recorded fixture inputs of model/workflows/preview-environment.yaml, when the fixture run executes in the pipeline, then its outputs match the recorded ones field by field and the run stays within the declared budget (ADR-0024).
Traces: workflows preview-environment
Traces: steps preview-environment/resolve-change, preview-environment/approve-preview, preview-environment/request-preview, preview-environment/time-to-live, preview-environment/teardown
Traces: agents environment-manager, devops-engineer
Traces: services WorkflowEngineService, RunControlService, PipelineExecutionService, BlueprintService, AgentRegistryService
Traces: apis RunControlService/SubmitRun, AgentRegistryService/SubmitRelease, AgentRegistryService/PublishRelease
Traces: events AgentRegistryService/AssetReleasePublished, PipelineExecutionService/ChangeProposalOpened, BlueprintService/BlueprintValidated, WorkflowEngineService/ReadinessRunSubmitted, WorkflowEngineService/ReadinessSuperseded, WorkflowEngineService/WorkflowRunStarted, WorkflowEngineService/WorkflowRunCompleted, RunControlService/RunAccepted, RunControlService/RunCompleted
Traces: descriptors workflow-definition-v1, readiness-bundle-v1, pull-request-proposal-v1, blueprint-infrastructure-v1, blueprint-pipeline-v1
Traces: adrs ADR-0014, ADR-0017, ADR-0024, ADR-0027
Traces: requirements FR-09, XL-12
Depends on AIFACTORY-US-1187, AIFACTORY-US-1188, AIFACTORY-US-1189, feature:pipeline-execution-service-thin, feature:blueprint-service, feature:workflow-engine-service, feature:run-control-service, feature:agent-registry-service-thin, feature:agent-registry-service-publication
Sources model/workflows/preview-environment.yaml, docs/planes/agent-runtime/workflow-definitions/preview-environment.md

Tasks

Task Kind Expected output Repository
AIFACTORY-TASK-333 Readiness start on an open change proposal and a validated Infrastructure Blueprint implementation The preview run starts once per proposal version when both required members are satisfied, through SubmitRun with a service token naming the project, and a newer member version supersedes the open correlation (AC1 and AC2 of AIFACTORY-US-027). ConnectSoft.AI.SoftwareFactory.WorkflowEngineService
AIFACTORY-TASK-275 Author, submit and publish the release of the workflow definition preview-environment with its agent releases implementation The release of preview-environment (workflow-definition-v1) authored with its 5 steps, input mappings, retry policies, timeouts, the failure policy of each agent and human step, the compensation of request-preview and the timer and compensation steps exactly as in model/workflows/preview-environment.yaml and accepted by ValidateWorkflowDefinition; it is submitted through SubmitRelease of AgentRegistryService together with the agent releases devops-engineer and environment-manager of AIFACTORY-TASK-276 and any skill, tool or model profile release of their closure that is not yet Published, each publication is approved, through the approval that RunControlService opens with the subject kind asset-release, by a Reviewer who is not the submitter (a Platform admin for a model profile release), and each release is published through PublishRelease with the alias latest moved to it (feature agent-registry-service-publication, D140); no evaluation verdict is required before I4, and the Published release ids are recorded for the fixture run, which pins them. ConnectSoft.AI.SoftwareFactory.WorkflowEngineService
AIFACTORY-TASK-276 Author the agent releases devops-engineer, environment-manager with their prompts and skills implementation Draft releases of devops-engineer and environment-manager with their instructions, the skills environment-manager-resolve-change and devops-engineer-request-preview among their bound skills, tool bindings and model profiles of model/agents/devops-delivery/; each release passes a smoke run on a fixture input in the template tests and is submitted for publication by AIFACTORY-TASK-275, and no evaluation verdict of the suite devops-delivery-core-v1 is required for its publication before I4 (D140). ConnectSoft.AI.SoftwareFactory.AgentTemplate
AIFACTORY-TASK-277 Fixture run of preview-environment against recorded inputs verification The definition runs end to end on a fixture proposal and Infrastructure Blueprint in the acceptance environment from the readiness start to RunCompleted on the Published releases of AIFACTORY-TASK-275; every step output validates against its descriptor (AC3 to AC5 of AIFACTORY-US-027). ConnectSoft.AI.SoftwareFactory.WorkflowEngineService
AIFACTORY-TASK-734 Verify preview-environment-lifecycle by running the declared command verification Run dotnet test -c Release --filter Category=WorkflowFixture; it passes and proves AC1 to AC5 of AIFACTORY-US-027; the output names the Published release ids of preview-environment, devops-engineer and environment-manager that the run pinned, as AgentRegistryService/GetRelease reports them with their approval by a Reviewer who is not the submitter (D140). ConnectSoft.AI.SoftwareFactory.WorkflowEngineService

AIFACTORY-US-1187: The Environment Manager resolves the proposal to a buildable change set and a reviewer approves the preview

behavior · persona reviewer As a reviewer of the project, I want the change behind a proposal resolved to the modules it touches, and to decide on that exact deployment before a preview environment is created, so that no non-production environment is created from a change nobody has looked at.

The first agent step and the human step of preview-environment. When the engine marks resolve-change ready it resolves infrastructure-blueprint from input.infrastructure-blueprint (blueprint-infrastructure-v1) and change-proposal from input.change-proposal (pull-request-proposal-v1); the environment-manager release runs the skill environment-manager-resolve-change in read class with knowledge-search and read-range and writes change-set (artifact-v1): the buildable change set of the proposal and the modules of the Infrastructure Blueprint it touches. The step declares failure_policy Retry: a Failed attempt of failure class transient is retried under the exponential budget of 3 attempts with backoff 30s, any other failure class is not retried, and a step that exceeds its timeout PT30M or spends its budget fails the run with nothing created. When approve-preview becomes ready the engine emits StepReady for a Human step and Run Control opens an approval request whose subject is the run and the step, of action class shared-write and proposal kind deployment-manifest, with the hash of steps.resolve-change.change-set as proposal hash and the approver rule role Reviewer in project scope, where the requester of the run never decides (ADR-0015, D129). The definition gates this approval on the project policy, but the step carries no guard and policy-decision-v1 has no action kind for non-production environment creation; this is reported as an open question (D127, D129), and whether a run without such a policy skips the request is not asserted here. An approving decision bound to that hash completes the step; on a rejection, an expiry the on-expiry rule does not re-request, or the timeout P2D, Run Control fails the run (ApprovalRejectedOrExpired) and publishes RunFailed exactly once, and the engine closes its projection on RunFailed without WorkflowRunFailed; no environment is created. A regenerated change set makes the pending request Stale.

Acceptance criteria

AC1 Given a run accepted with change-proposal and infrastructure-blueprint, when environment-manager executes preview-environment/resolve-change, then change-set (artifact-v1) is recorded once under the run envelope with the buildable change set and the touched modules of the Infrastructure Blueprint (SCN-preview-environment-001).
AC2 Given an attempt of preview-environment/resolve-change spends the exponential budget of 3 attempts, settles Failed with a non-transient failure class or exceeds PT30M, when Run Control settles the step, then WorkflowEngineService/WorkflowRunFailed names the step and no environment is requested (SCN-preview-environment-001, ADR-0014).
AC3 Given steps.resolve-change.change-set is recorded, when preview-environment/approve-preview becomes ready, then RunControlService/ApprovalRequested is published for the run and the step with action class shared-write, proposal kind deployment-manifest, the change-set hash and the approver rule role Reviewer that excludes the requester, and the run waits WaitingForApproval (SCN-preview-environment-002, ADR-0015).
AC4 Given the pending request, when RunControlService/ApprovalDecided approves it for that hash, then preview-environment/request-preview becomes ready; when it rejects it, the request expires with no re-request left or the step reaches P2D without a decision, then Run Control fails the run (ApprovalRejectedOrExpired) and publishes RunControlService/RunFailed exactly once; the engine closes its projection on RunFailed without WorkflowEngineService/WorkflowRunFailed; no environment is created (SCN-preview-environment-002, D119, D121).
Traces: workflows preview-environment
Traces: steps preview-environment/resolve-change, preview-environment/approve-preview
Traces: agents environment-manager
Traces: services WorkflowEngineService, RunControlService
Traces: aggregates RunControlService/ApprovalRequest
Traces: events WorkflowEngineService/StepReady, WorkflowEngineService/WorkflowRunFailed, RunControlService/ApprovalRequested, RunControlService/ApprovalDecided, RunControlService/RunFailed
Traces: descriptors blueprint-infrastructure-v1, pull-request-proposal-v1, artifact-v1, approval-request-v1
Traces: scenarios SCN-preview-environment-001, SCN-preview-environment-002
Traces: adrs ADR-0014, ADR-0015
Traces: requirements FR-09
Depends on feature:workflow-engine-service, feature:run-control-service
Sources model/workflows/preview-environment.yaml, model/skills/devops-delivery/environment-manager-resolve-change.yaml, model/scenarios/preview-environment.yaml

Tasks

Task Kind Expected output Repository
AIFACTORY-TASK-4737 Bind the resolve-change skill and the approval block of approve-preview implementation The step resolve-change of the Draft release runs environment-manager-resolve-change with infrastructure-blueprint and change-proposal mapped as in model/workflows/preview-environment.yaml, and approve-preview carries action class shared-write, proposal kind deployment-manifest, proposal from steps.resolve-change.change-set, the approver rule and the stale rule. ConnectSoft.AI.SoftwareFactory.WorkflowEngineService
AIFACTORY-TASK-4738 Fixture proposal with its expected change set and approval request fixture A recorded proposal and Infrastructure Blueprint with the expected change set and touched modules, and the expected ApprovalRequested bound to the change-set hash, as the oracle of SCN-preview-environment-001 and SCN-preview-environment-002. ConnectSoft.AI.SoftwareFactory.AgentTemplate
AIFACTORY-TASK-4739 Prove the resolve step and the preview approval on the fixture verification A fixture run proves SCN-preview-environment-001 and SCN-preview-environment-002 (AC1 to AC4 of AIFACTORY-US-1187), with the approve and stale paths, the reject and expire paths ending in RunFailed without WorkflowRunFailed, and the requester refused as decider. ConnectSoft.AI.SoftwareFactory.WorkflowEngineService

AIFACTORY-US-1188: The DevOps Engineer requests the preview environment and a failed request is compensated by a teardown

behavior · persona requester As a requester, I want the approved change set deployed into a preview environment whose address I receive as an artifact, so that I can try my change, and a failed request never leaves a half-created environment behind.

The request step of preview-environment. When approve-preview held, the engine marks request-preview ready and resolves change-set from steps.resolve-change.change-set and pipeline-blueprint from input.pipeline-blueprint (blueprint-pipeline-v1, optional). The devops-engineer release runs the skill devops-engineer-request-preview in shared-write class with its bound tools list-files, search-text, search-symbols, find-references, read-range, get-dependencies, get-git-diff, knowledge-search, write-file, propose-change-set, mcp-azure-devops and mcp-github, and returns preview-environment (artifact-v1): the identity and address of the preview environment with the change set deployed, which is also the run output. The definition names RuntimeEnvironmentService as the service that creates the preview, but that service models no operation that creates an environment, so this PBI delivers the step contract, its output and its compensation and traces no service operation for the creation. The step declares failure_policy Compensate with the compensation request the teardown and no idempotency key, so a Failed attempt is never retried although the definition declares an exponential budget of 3 attempts: the step fails, the engine starts the compensation, the teardown is requested and the run ends Failed with the evidence. An Uncertain attempt is never retried automatically and goes to an operator decision of the project (D119). The step requests no approval of its own; the approval of approve-preview covers it.

Acceptance criteria

AC1 Given preview-environment/approve-preview held, when devops-engineer executes preview-environment/request-preview with change-set and the optional pipeline-blueprint, then preview-environment (artifact-v1) with the environment identity and address is recorded once under the run envelope and preview-environment/time-to-live becomes ready (SCN-preview-environment-003).
AC2 Given an attempt of preview-environment/request-preview settles Failed or exceeds PT30M, when Run Control settles the step through RunControlService/StepSettled, then it is not retried because the shared-write step declares no idempotency key, WorkflowEngineService/CompensationStarted is emitted, the compensation requests the teardown and the run ends Failed with the evidence (SCN-preview-environment-003, ADR-0014).
AC3 Given an attempt of preview-environment/request-preview settles Uncertain, when Run Control records it, then it is not retried and RunControlService/ApprovalRequested of kind operator-decision is opened for the Operator of the project; the run continues or compensates only on that decision (SCN-preview-environment-003).
Traces: workflows preview-environment
Traces: steps preview-environment/request-preview
Traces: agents devops-engineer
Traces: services WorkflowEngineService, RunControlService
Traces: events WorkflowEngineService/CompensationStarted, RunControlService/StepSettled, RunControlService/ApprovalRequested
Traces: descriptors artifact-v1, blueprint-pipeline-v1
Traces: scenarios SCN-preview-environment-003
Traces: adrs ADR-0014, ADR-0017
Traces: requirements FR-09, XL-12
Depends on AIFACTORY-US-1187, feature:workflow-engine-service, feature:run-control-service
Sources model/workflows/preview-environment.yaml, model/skills/devops-delivery/devops-engineer-request-preview.yaml, model/scenarios/preview-environment.yaml

Tasks

Task Kind Expected output Repository
AIFACTORY-TASK-4740 Bind the request-preview skill and its compensation in the Draft release implementation The step request-preview of the Draft release runs devops-engineer-request-preview with change-set and pipeline-blueprint mapped as in model/workflows/preview-environment.yaml, declares failure policy Compensate with the compensation request the teardown, and sets preview-environment as the run output. ConnectSoft.AI.SoftwareFactory.WorkflowEngineService
AIFACTORY-TASK-4741 Fixture expected preview environment artifact fixture The expected preview-environment artifact of the fixture run with the environment identity and address, and a recorded failed and an Uncertain attempt with their expected compensation and operator decision, as the oracle of SCN-preview-environment-003. ConnectSoft.AI.SoftwareFactory.AgentTemplate
AIFACTORY-TASK-4742 Prove the preview request and its compensation on the fixture verification A fixture run proves SCN-preview-environment-003 (AC1 to AC3 of AIFACTORY-US-1188); the artifact recorded once, a Failed attempt not retried that starts the compensation, and an Uncertain attempt that waits for an operator decision. ConnectSoft.AI.SoftwareFactory.WorkflowEngineService

AIFACTORY-US-1189: The preview environment is kept for its time to live and then torn down with its lifetime and cost recorded

behavior · persona requester As a requester, I want my preview environment kept for its time to live and torn down afterwards with its lifetime and cost recorded, so that previews never outlive their use and their cost is visible.

The timer and the teardown of preview-environment. When request-preview succeeded the engine marks time-to-live ready: it is an engine timer with no agent, no tool and no attempt; the engine stores a durable timer entry for the configured time to live, at most P3D, moves its projection of the run to WaitingForTimer and returns it to Running when the timer fires and TimerFired is emitted. A timer that fires after its step already advanced is a no-op. The definition says the time to live is extended by use, but the model carries no signal that extends a timer, so this PBI delivers the fixed time to live only and the extension by use is reported as an open question. When the timer fired the engine marks teardown ready: a step of kind compensation in sandbox class, for which the engine stores a task contract in ArtifactService before it announces the step (D125), so Run Control dispatches its attempt like any other. The teardown requests the removal of the preview environment and records its lifetime and cost as the output of its attempt, an artifact-v1 under the run envelope stored through Artifacts.Store; the definition declares no output for the step, and where the cost figure comes from is reported as an open question. A Failed attempt of failure class transient is retried under the fixed budget of 3 attempts with backoff 10s, and a teardown that exceeds PT30M or spends its budget ends the run Failed with an operator follow-up, never silently. A run that Run Control cancels or fails while it waits for the timer closes the engine projection Cancelled or Failed; on RunCancelled the engine skips its pending timers and has no path to compensation, and on RunFailed it only closes the projection and cancels open step runs (D121), so no teardown runs and the environment is left for an operator follow-up. The model has no early-end path that tears the environment down, which is reported as an open question. When the teardown succeeds the run completes with preview-environment as its output.

Acceptance criteria

AC1 Given preview-environment/request-preview succeeded, when the engine reaches preview-environment/time-to-live, then a durable timer entry for the configured time to live of at most P3D is stored, the run projection is WaitingForTimer and no attempt is dispatched (SCN-preview-environment-004).
AC2 Given the timer is due, when it fires, then WorkflowEngineService/TimerFired is emitted once, the projection returns to Running and preview-environment/teardown becomes ready; a second firing for the same step is a no-op (SCN-preview-environment-004).
AC3 Given preview-environment/teardown becomes ready, when the engine announces it with WorkflowEngineService/StepReady carrying the reference and hash of its stored task contract (agent-task-contract-v1), then its attempt requests the teardown, the lifetime and cost of the environment are recorded as an artifact-v1 under the run envelope through ArtifactService/Artifacts.Store, and the run completes with WorkflowEngineService/WorkflowRunCompleted once (SCN-preview-environment-005, ADR-0014).
AC4 Given a teardown attempt settles Failed with failure class transient until the fixed budget of 3 attempts is spent, or exceeds PT30M, when Run Control settles the step, then the run ends Failed with WorkflowEngineService/WorkflowRunFailed naming teardown and an operator follow-up, never silently (SCN-preview-environment-005).
AC5 Given the run is cancelled or failed by Run Control while it waits in preview-environment/time-to-live, when the engine hears RunControlService/RunCancelled or RunControlService/RunFailed, then the projection ends Cancelled or Failed, no teardown step runs and the environment is left for an operator follow-up (SCN-preview-environment-004, D121).
Traces: workflows preview-environment
Traces: steps preview-environment/time-to-live, preview-environment/teardown
Traces: services WorkflowEngineService, RunControlService, ArtifactService
Traces: apis ArtifactService/Artifacts.Store
Traces: events WorkflowEngineService/TimerFired, WorkflowEngineService/StepReady, WorkflowEngineService/WorkflowRunCompleted, WorkflowEngineService/WorkflowRunFailed, RunControlService/RunCancelled, RunControlService/RunFailed
Traces: descriptors agent-task-contract-v1, artifact-v1
Traces: scenarios SCN-preview-environment-004, SCN-preview-environment-005
Traces: adrs ADR-0014
Traces: requirements FR-09, XL-12
Depends on AIFACTORY-US-1188, feature:workflow-engine-service, feature:run-control-service, feature:artifact-service
Sources model/workflows/preview-environment.yaml, model/services/agent-mesh/WorkflowEngineService.yaml, model/scenarios/preview-environment.yaml

Tasks

Task Kind Expected output Repository
AIFACTORY-TASK-334 Preview time to live and teardown implementation The timer step time-to-live waits the configured time to live of at most P3D on a durable timer entry, and the compensation step teardown is announced with its stored task contract, requests the teardown and records the lifetime and cost of the environment (SCN-preview-environment-004, SCN-preview-environment-005). ConnectSoft.AI.SoftwareFactory.WorkflowEngineService
AIFACTORY-TASK-335 Preview commands in the command-line client implementation The client shows the preview run of a proposal with the preview-environment artifact, its address and the remaining time to live; it offers no early end, because the model has no act that tears the environment down before the timer fires. ConnectSoft.AI.SoftwareFactory.Cli
AIFACTORY-TASK-4743 Prove the timer and the teardown on the fixture verification A fixture run with a shortened time to live proves SCN-preview-environment-004 and SCN-preview-environment-005 (AC1 to AC5 of AIFACTORY-US-1189); one TimerFired, a no-op second firing, the teardown with lifetime and cost recorded as an artifact, a run cancelled while waiting that runs no teardown and leaves the environment for an operator follow-up, and a teardown that spends its budget ending the run Failed with an operator follow-up. ConnectSoft.AI.SoftwareFactory.WorkflowEngineService