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 |