Skip to content

AIFACTORY-FEAT-110: Workflow definition: Application design

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 I1 Generate a microservice · State elaborated · Route solution-architect · Build order 88 of 185 (Factory code)

The workflow definition application-design as a published asset: Produces the application design of every module from its validated Module Blueprint: use cases and handlers, input and output ports, adapters and the telemetry span plan, stored as a typed artifact the generation recipe pins. It has 4 steps, names the agents application-architect and the tools none, and is executed by WorkflowEngineService under Run Control.

Delivers —
Stubs —
Realizes workflows: application-design
adrs: ADR-0014, ADR-0024, ADR-0026, ADR-0027
Requirements FR-11, XL-09
Depends on —
Sources model/workflows/application-design.yaml

Scenarios to trace (4, catalog): SCN-application-design-001 ✓, SCN-application-design-002 ✓, SCN-application-design-003 ✓, SCN-application-design-004 ✓

AIFACTORY-US-011: An application design for every module

behavior · persona requester As a requester, I want use cases, ports, adapters and telemetry spans designed for each module from its blueprint, so that the backend developer role fills code against a precise design.

The integration PBI of the definition application-design. The run is activated, not submitted by a person: the definition has one required readiness member, module-blueprints, satisfied by BlueprintValidated of kind Module with passed true, so every validated Module Blueprint version satisfies its own correlation and the readiness correlation of WorkflowEngineService submits one run for it through SubmitRun of RunControlService with a service token that names the project; a newer version of the same Module Blueprint supersedes an open correlation. After RunAccepted the engine loads the Draft release through AgentRegistryService and runs four agent steps in order on the application-architect release: discover-use-cases, design-ports, plan-telemetry and assemble-design. Every step declares failure_policy Retry with the exponential budget of 3 attempts; the definition has no tool step, no condition and no approval, because no step writes to a shared system: the design is an artifact of the run. The last step stores the application-design-v1 body bound to the exact Module Blueprint version and hash through ArtifactService, whose ArtifactStored carries the descriptor, so that GenerationRecipeService can offer the design for a backend module entry of a recipe (ADR-0027, D66). The run reports exactly one outcome within the declared budget. The step behaviour is specified in AIFACTORY-US-1149 to AIFACTORY-US-1151; this PBI proves the chain on the recorded fixture. The tasks AIFACTORY-TASK-211 and AIFACTORY-TASK-212 of this PBI moved to AIFACTORY-US-1149 and AIFACTORY-US-1151, the PBIs whose behaviour they prove; AIFACTORY-TASK-212 also moved from an ArtifactService contract task to an AgentRuntimeService implementation task, because ArtifactService delivers the storage with descriptor and lineage itself and the step only needs the runtime path that records its output.

Acceptance criteria

AC1 Given the Draft release of application-design (workflow-definition-v1) with its readiness activation, 4 steps, mappings, retry policies and timeouts exactly as in model/workflows/application-design.yaml, when BlueprintService/BlueprintValidated of kind Module with passed true arrives, then the WorkflowEngineService/ReadinessCorrelation submits one run for that Module Blueprint version through RunControlService/SubmitRun with a service token naming the project and WorkflowEngineService/ReadinessRunSubmitted is published.
AC2 Given RunControlService/RunAccepted with input module-blueprints, when the run executes, then WorkflowEngineService/WorkflowRunStarted is emitted and application-design/discover-use-cases, application-design/design-ports, application-design/plan-telemetry and application-design/assemble-design become ready in that order on the pinned release of application-architect.
AC3 Given every step succeeds, when the run completes, then application-design (application-design-v1) names the exact Module Blueprint version and hash, ArtifactService/ArtifactStored carries the descriptor, WorkflowEngineService/WorkflowRunCompleted is emitted once and RunControlService/RunCompleted follows exactly once (ADR-0014, ADR-0027).
AC4 Given a step settles Failed with a non-transient failure class or exhausts its retry budget, when the engine applies the compensation policy of model/workflows/application-design.yaml, then WorkflowEngineService/WorkflowRunFailed names the step, the outputs recorded so far stay as evidence, no design is offered for a recipe unless it was stored before the failure, and RunControlService/RunFailed is published exactly once.
AC5 Given the recorded fixture inputs of model/workflows/application-design.yaml, when the fixture run executes in the pipeline, then its outputs match the recorded ones field by field, every step output validates against its descriptor and the run stays within the declared budget (ADR-0024).
Traces: workflows application-design
Traces: steps application-design/discover-use-cases, application-design/design-ports, application-design/plan-telemetry, application-design/assemble-design
Traces: agents application-architect
Traces: services WorkflowEngineService, RunControlService, AgentRegistryService, ArtifactService
Traces: aggregates WorkflowEngineService/ReadinessCorrelation
Traces: apis RunControlService/SubmitRun
Traces: events BlueprintService/BlueprintValidated, ArtifactService/ArtifactStored, WorkflowEngineService/ReadinessRunSubmitted, WorkflowEngineService/WorkflowRunStarted, WorkflowEngineService/WorkflowRunCompleted, WorkflowEngineService/WorkflowRunFailed, RunControlService/RunAccepted, RunControlService/RunCompleted, RunControlService/RunFailed
Traces: descriptors workflow-definition-v1, readiness-bundle-v1, blueprint-module-v1, application-design-v1
Traces: adrs ADR-0014, ADR-0024, ADR-0026, ADR-0027
Traces: requirements FR-11, XL-09
Depends on AIFACTORY-US-1149, AIFACTORY-US-1150, AIFACTORY-US-1151, feature:workflow-engine-service, feature:run-control-service, feature:agent-registry-service-thin, feature:blueprint-service, feature:artifact-service, feature:wf-module-blueprints
Sources model/workflows/application-design.yaml, model/agents/architecture/application-architect.yaml, docs/planes/agent-runtime/workflow-definitions/application-design.md

Tasks

Task Kind Expected output Repository
AIFACTORY-TASK-175 Author the release of the workflow definition application-design from the model implementation A Draft release of application-design (workflow-definition-v1) with its readiness activation on BlueprintValidated of kind Module, its 4 agent steps, input mappings, retry policies, timeouts, the compensation policy and the budget as in model/workflows/application-design.yaml, with the failure_policy Retry of every step copied as it stands; loadable by AgentRegistryService and accepted by ValidateWorkflowDefinition of WorkflowEngineService. ConnectSoft.AI.SoftwareFactory.WorkflowEngineService
AIFACTORY-TASK-176 Author the agent releases application-architect with their prompts and skills implementation A Draft release of application-architect with its instructions, the skills application-architect-use-case-discovery, application-architect-output-port-designer, application-architect-telemetry-span-planner and application-architect-assemble-design among its bound skills, the tool bindings and the model profile reasoning; the release passes a smoke evaluation of the suite architecture-core-v1 on a fixture Module Blueprint. ConnectSoft.AI.SoftwareFactory.AgentTemplate
AIFACTORY-TASK-177 Fixture run of application-design against recorded inputs verification The definition runs end to end on a fixture project from a BlueprintValidated of kind Module to RunCompleted; every step output validates against its descriptor and the stored application design matches the recorded one field by field (AC1 to AC3 and AC5 of AIFACTORY-US-011). ConnectSoft.AI.SoftwareFactory.WorkflowEngineService
AIFACTORY-TASK-720 Verify application-design-per-module by running the declared command verification Run dotnet test -c Release --filter Category=WorkflowFixture; it passes and proves AC1 to AC5 of AIFACTORY-US-011, including the failure path of AC4 with WorkflowRunFailed and RunFailed exactly once. ConnectSoft.AI.SoftwareFactory.WorkflowEngineService

AIFACTORY-US-1149: The Application Architect discovers the use cases of a module and designs their ports and adapters

behavior · persona requester As a requester, I want the commands, queries, event handlers and scheduled work of each module listed with their authorization, and a port and adapter for each, so that the backend code is generated against an explicit list of use cases rather than invented ones.

The two read-class agent steps that open application-design, both on the application-architect release. When discover-use-cases becomes ready the engine resolves module-blueprint from input.module-blueprints, the validated Module Blueprint the readiness bundle carried; the skill application-architect-use-case-discovery reads the module's aggregates and returns use-cases (artifact-v1): per aggregate the commands, queries, event handlers and scheduled work, each with its authorization and whether it is tenant scoped. When design-ports becomes ready it receives the same blueprint and use-cases from steps.discover-use-cases.use-cases; the skill application-architect-output-port-designer returns ports (artifact-v1): the input port of every use case, its output ports, each with a direction and a contract, and the adapter that implements each port on the template switches the Module Blueprint declares, so a port is never designed for a switch the module does not use. Both steps use only the read-class tools of their skills (knowledge-search, graph-query, list-files, read-range), write nothing outside the run envelope and need no approval. Each declares failure_policy Retry: a Failed attempt of failure class transient is retried under the exponential budget of 3 attempts with backoff 30s, another failure class is not retried, and a step that exceeds PT30M or exhausts the budget fails the run with evidence.

Acceptance criteria

AC1 Given a run accepted with input module-blueprints (blueprint-module-v1), when application-architect executes application-design/discover-use-cases, then use-cases (artifact-v1) lists per aggregate of the module its commands, queries, event handlers and scheduled work with authorization and tenant scope, is recorded once under the run envelope and application-design/design-ports becomes ready (SCN-application-design-001).
AC2 Given steps.discover-use-cases.use-cases is recorded, when application-design/design-ports runs, then ports (artifact-v1) gives every use case an input port, every port a direction and a contract, and every port an adapter on a switch the Module Blueprint declares, and is recorded once under the run envelope (SCN-application-design-002).
AC3 Given an attempt of either step exceeds PT30M, settles Failed with a non-transient failure class or exhausts the exponential budget of 3 attempts, when the engine applies the policy of model/workflows/application-design.yaml, then the attempt fails with evidence, WorkflowEngineService/WorkflowRunFailed names the step and no shared system is changed (SCN-application-design-001, SCN-application-design-002, ADR-0014).
Traces: workflows application-design
Traces: steps application-design/discover-use-cases, application-design/design-ports
Traces: agents application-architect
Traces: services WorkflowEngineService
Traces: events WorkflowEngineService/StepReady, WorkflowEngineService/WorkflowRunFailed
Traces: descriptors blueprint-module-v1, artifact-v1
Traces: scenarios SCN-application-design-001, SCN-application-design-002
Traces: adrs ADR-0014, ADR-0027
Traces: requirements FR-11
Depends on feature:workflow-engine-service, feature:run-control-service
Sources model/workflows/application-design.yaml, model/skills/architecture/application-architect-use-case-discovery.yaml, model/skills/architecture/application-architect-output-port-designer.yaml, model/scenarios/application-design.yaml

Tasks

Task Kind Expected output Repository
AIFACTORY-TASK-211 Application architect release implementation The steps discover-use-cases and design-ports of the release authored by AIFACTORY-TASK-175 run application-architect-use-case-discovery and application-architect-output-port-designer with module-blueprint and use-cases mapped as in model/workflows/application-design.yaml and only the read-class tools of their skills. ConnectSoft.AI.SoftwareFactory.AgentTemplate
AIFACTORY-TASK-4580 Fixture use cases and ports for a Module Blueprint with persistence and messaging fixture A fixture Module Blueprint with two aggregates and the persistence and messaging switches, with the expected use-cases and ports artifacts (artifact-v1), as the oracle of SCN-application-design-001 and SCN-application-design-002. ConnectSoft.AI.SoftwareFactory.AgentTemplate
AIFACTORY-TASK-4581 Prove the use-case and port steps on the fixture verification A fixture run proves SCN-application-design-001 and SCN-application-design-002 (AC1 to AC3 of AIFACTORY-US-1149); every use case has authorization and tenant scope, every port a direction, a contract and an adapter on a declared switch, and the timeout path ends in WorkflowRunFailed naming the step. ConnectSoft.AI.SoftwareFactory.WorkflowEngineService

AIFACTORY-US-1150: The Application Architect plans one telemetry span per use case with the required attributes

behavior · persona requester As a requester, I want one span planned for every use case of a module with the attributes the observability conventions require, so that every generated handler is traced the same way from its first build.

The read-class agent step plan-telemetry of application-design. When the engine marks it ready it resolves module-blueprint from input.module-blueprints, use-cases from steps.discover-use-cases.use-cases and ports from steps.design-ports.ports; the application-architect release runs the skill application-architect-telemetry-span-planner and returns span-plan (artifact-v1): exactly one span per use case, named after the use case, with the attributes the observability conventions require, among them the tenant of a tenant-scoped use case, and the output ports the span covers. A use case without a span or a span without a use case is an error of the step output, not something a later step repairs. The step uses only the read-class tools of its skill, writes nothing outside the run envelope and needs no approval. It declares failure_policy Retry: a Failed attempt of failure class transient is retried under the exponential budget of 3 attempts with backoff 30s, another failure class is not retried, and an attempt that exceeds PT30M or exhausts the budget fails the run with evidence, the use cases and ports recorded before it staying in place (ADR-0014, recovery not replay).

Acceptance criteria

AC1 Given use-cases and ports are recorded, when application-architect executes application-design/plan-telemetry, then span-plan (artifact-v1) holds exactly one span per use case with the required attributes and the output ports it covers, and is recorded once under the run envelope (SCN-application-design-003).
AC2 Given a tenant-scoped use case, when its span is planned, then the span carries the tenant attribute, and given a use case that is not tenant scoped, then the span does not invent one (SCN-application-design-003).
AC3 Given an attempt exceeds PT30M, settles Failed with a non-transient failure class or exhausts the exponential budget of 3 attempts, when the engine applies the policy of model/workflows/application-design.yaml, then the attempt fails with evidence, WorkflowEngineService/WorkflowRunFailed names the step and the recorded use cases and ports stay in place (SCN-application-design-003, ADR-0014).
Traces: workflows application-design
Traces: steps application-design/plan-telemetry
Traces: agents application-architect
Traces: services WorkflowEngineService
Traces: events WorkflowEngineService/WorkflowRunFailed
Traces: descriptors artifact-v1
Traces: scenarios SCN-application-design-003
Traces: adrs ADR-0014
Traces: requirements FR-11
Depends on AIFACTORY-US-1149, feature:workflow-engine-service, feature:run-control-service
Sources model/workflows/application-design.yaml, model/skills/architecture/application-architect-telemetry-span-planner.yaml, model/scenarios/application-design.yaml

Tasks

Task Kind Expected output Repository
AIFACTORY-TASK-4582 Fixture span plan for the fixture use cases fixture The expected span-plan (artifact-v1) for the fixture use cases and ports, one span per use case with the tenant attribute on the tenant-scoped ones, as the oracle of SCN-application-design-003. ConnectSoft.AI.SoftwareFactory.AgentTemplate
AIFACTORY-TASK-4583 Prove the telemetry planning step on the fixture verification A fixture run proves SCN-application-design-003 (AC1 to AC3 of AIFACTORY-US-1150); one span per use case, the tenant attribute exactly on tenant-scoped use cases, and the timeout path failing the run with the earlier outputs kept. ConnectSoft.AI.SoftwareFactory.WorkflowEngineService

AIFACTORY-US-1151: The application design is assembled against its schema and stored as a typed artifact bound to the Module Blueprint version

behavior · persona requester As a requester, I want the use cases, ports and span plan of a module assembled into one application design stored with its descriptor, so that a generation recipe can pin exactly that design for the backend module.

The last agent step of application-design. When plan-telemetry succeeded the engine marks assemble-design ready and resolves module-blueprint, use-cases, ports and span-plan from the mappings of the definition. The application-architect release runs the skill application-architect-assemble-design in sandbox class: it writes the application-design-v1 body with write-file in the isolated workspace, with moduleBlueprintRef naming the exact Module Blueprint id, version and hash, every use case with its handler and every port with its direction and contract, so that the body validates against docs/reference/schemas/application-design.schema.json, and returns it as the step output application-design. The skill calls no gRPC method; AgentRuntimeService records the output under the run envelope through Artifacts.Store of ArtifactService, the one writer of artifacts, with the producer run, attempt and agent and the lineage the skill declared: the Module Blueprint as the run input and the use cases, ports and span plan as artifacts it derives from. Exactly one new ArtifactStored results and it carries the descriptor application-design-v1, which GenerationRecipeService hears to offer the design for a backend module entry; the intermediate artifacts are not stored again. The step requests no approval. It declares failure_policy Retry with the exponential budget of 3 attempts; an attempt that exceeds PT30M, fails with another failure class or exhausts the budget fails the run with evidence, and a design already stored is not written twice on recovery because Artifacts.Store is idempotent on tenant and hash (ADR-0014).

Acceptance criteria

AC1 Given use-cases, ports and span-plan are recorded, when application-architect executes application-design/assemble-design, then the output application-design validates against application-design-v1, names the exact Module Blueprint version and hash in moduleBlueprintRef, gives every use case a handler and every port a direction and a contract (SCN-application-design-004, ADR-0027).
AC2 Given the output is returned, when AgentRuntimeService records it through ArtifactService/Artifacts.Store, then exactly one new ArtifactService/ArtifactStored is emitted with the descriptor application-design-v1, the producer run and the content hash, and the lineage of the ArtifactService/Artifact links the Module Blueprint and the use cases, ports and span plan artifacts, which are not stored again (SCN-application-design-004).
AC3 Given an attempt exceeds PT30M, settles Failed with a non-transient failure class or exhausts the exponential budget of 3 attempts, when the engine applies the compensation policy of model/workflows/application-design.yaml, then the attempt fails with evidence, WorkflowEngineService/WorkflowRunFailed names the step and no artifact is written twice on recovery (SCN-application-design-004, ADR-0014).
Traces: workflows application-design
Traces: steps application-design/assemble-design
Traces: agents application-architect
Traces: services WorkflowEngineService, AgentRuntimeService, ArtifactService
Traces: aggregates ArtifactService/Artifact
Traces: apis ArtifactService/Artifacts.Store
Traces: events ArtifactService/ArtifactStored, WorkflowEngineService/WorkflowRunFailed
Traces: descriptors application-design-v1, blueprint-module-v1, artifact-v1
Traces: scenarios SCN-application-design-004
Traces: adrs ADR-0014, ADR-0027
Traces: requirements FR-11, XL-09
Depends on AIFACTORY-US-1150, feature:artifact-service, feature:agent-runtime-service, feature:workflow-engine-service, feature:run-control-service
Sources model/workflows/application-design.yaml, model/skills/architecture/application-architect-assemble-design.yaml, model/services/knowledge/ArtifactService.yaml, docs/reference/schemas/application-design.schema.json, model/scenarios/application-design.yaml

Tasks

Task Kind Expected output Repository
AIFACTORY-TASK-212 Record the assembled design through Artifacts.Store with its descriptor and lineage implementation The existing runtime path that records step outputs under the run envelope is reused and verified for assemble-design; the application-design output is stored through Artifacts.Store with producer run, attempt and agent, the descriptor application-design-v1 and the lineage the skill declared, yielding exactly one new ArtifactStored that carries the descriptor and no second store of the use-cases, ports and span-plan artifacts. ConnectSoft.AI.SoftwareFactory.AgentRuntimeService
AIFACTORY-TASK-4584 Fixture expected application design with its lineage fixture The expected application-design-v1 body of the fixture run with its moduleBlueprintRef, use cases with handlers and ports with direction and contract, its content hash and lineage, and the expectation of exactly one new ArtifactStored, as the oracle of SCN-application-design-004. ConnectSoft.AI.SoftwareFactory.AgentTemplate
AIFACTORY-TASK-4585 Prove the assemble and store step on the fixture verification A fixture run proves SCN-application-design-004 (AC1 to AC3 of AIFACTORY-US-1151); the design validates against docs/reference/schemas/application-design.schema.json, exactly one ArtifactStored carries the descriptor application-design-v1, and the recovery path writes nothing twice. ConnectSoft.AI.SoftwareFactory.WorkflowEngineService