Skip to content

AIFACTORY-FEAT-156: Agent host template: generated-solution gate and a publishable package

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 Ecosystem component extensions · Increment I0 Readiness · State elaborated · Route backend-developer · Phase before development · Build order 11 of 185 (Templates and libraries)

Before development

Template or library work: every task of this feature changes a template or a shared library the Factory builds on, and it lands before the Factory's own repositories of I0 are developed. The mark travels with every task (tag phase:before-development).

The last alignment pass of the template records a blocking generation defect inherited from the base template (a persistence provider substitution that leaves an unterminated JSON string in the generated configuration), stale symbols in the agent metadata, a submodule behind the base template, and a package publication that stays blocked until the generated cases pass their configuration smoke tests (Docs/AgentTemplate-Alignment-Verification.md of the template). The two Agent Mesh services are scaffolded only from a published package whose generated solution builds and passes. Component: AI Agent host template (extend).

Delivers —
Stubs —
Realizes components: cmp-agent-template
adrs: ADR-0028
Requirements —
Depends on AIFACTORY-FEAT-158 Base template: open consumer findings closed before the first scaffold
Sources model/components.yaml, ConnectSoft.AI.SoftwareFactory.AgentTemplate/Docs/AgentTemplate-Alignment-Verification.md

AIFACTORY-US-148: Agent host template: the base-template submodule carries the substitution fix and the agent metadata holds no stale symbol

enabling · persona asset-maintainer As an asset maintainer, I want the agent template to compose on a base template whose persistence substitution is fixed and on metadata whose symbols are current, so that a generated host no longer carries an unterminated JSON string in its configuration and the authoring solution builds in Release with zero errors.

The alignment verification of the template (Docs/AgentTemplate-Alignment-Verification.md of the template) records a blocking generation defect inherited from the base template: the Dapper, PostgreSQL and MySQL persistence substitutions share a replacement marker and drop its closing quote, so the generated provider becomes an unterminated JSON string in the configuration even for the default NHibernate generation, and the same stale symbols sit in the agent-owned metadata. The verification states that the submodule contents are not patched and the configuration regression tests are not removed to bypass the failure. This PBI waits for the base template findings feature to carry the fix, then points the base-template submodule of the agent template at that base template, reconciles the agent metadata (the extend file, the merge script and the nuspec) so that no stale or duplicated symbol remains, and rebuilds the authoring solution in Release. The vulnerability audit of the authoring solution reports zero findings. A submodule pointer that does not carry the fix is refused by a pipeline check that generates the default case and runs its configuration smoke tests, in the shared template pipeline Docs/Shared-Template-CI.md of the template describes.

Acceptance criteria

AC1 Given the base template findings feature has landed the substitution fix, when the base-template submodule of the agent template is moved to that base template, then the default generated case produces a configuration whose persistence provider is a terminated JSON string and its configuration smoke tests pass (feature component-base-template-findings, ADR-0028 amendment on the Factory templates).
AC2 Given the agent-owned metadata (the extend file, the merge script and the nuspec), when the stale persistence symbols are reconciled, then no symbol of the metadata is absent from the composed template configuration and no symbol is defined twice; the inventory of model/template-parameters/connectsoft-ai-agent.yaml lists each symbol once after the next run.
AC3 Given the reconciled authoring solution, when it builds in Release, then the build reports zero errors and the direct and transitive vulnerability audit reports zero findings; a pipeline check in the shared template pipeline (Docs/Shared-Template-CI.md of the template) refuses a submodule pointer whose default generated case fails the configuration smoke tests, which is the generated-solution gate docs/architecture/ecosystem-composition.md names as a need of this component.
Traces: adrs ADR-0028
Depends on feature:component-base-template-findings
Sources model/components.yaml, model/template-parameters/connectsoft-ai-agent.yaml, docs/architecture/ecosystem-composition.md, docs/architecture/adr/0028-one-repository-and-deployable-per-service.md

Tasks

Task Kind Expected output Repository
AIFACTORY-TASK-840 Base-template submodule moved to the base template with the substitution fix operations The base-template submodule of the agent template points at the base template commit that carries the persistence substitution fix; the default generated case has a terminated provider string in its configuration. ConnectSoft.AI.SoftwareFactory.AgentTemplate
AIFACTORY-TASK-841 Agent metadata reconciled with the composed template configuration implementation The extend file, the merge script and the nuspec of the agent template define no stale persistence symbol and no duplicate symbol; a test composes the template configuration and asserts that every metadata symbol appears exactly once. ConnectSoft.AI.SoftwareFactory.AgentTemplate
AIFACTORY-TASK-842 Submodule check in the template pipeline operations A pipeline step generates the default case from the current submodule and runs its configuration smoke tests; a pointer whose case fails the tests fails the run with the failing case named; the step is documented in Docs/Shared-Template-CI.md of the template. ConnectSoft.AI.SoftwareFactory.AgentTemplate
AIFACTORY-TASK-843 Verify the Release build and the audit of the reconciled authoring solution verification Run dotnet build -c Release and the vulnerability audit on the authoring solution; zero errors and zero findings, and the default generated case passes its configuration smoke tests, which proves AC1 to AC3 of AIFACTORY-US-148. ConnectSoft.AI.SoftwareFactory.AgentTemplate

AIFACTORY-US-149: Agent host template: the pipeline generates the Domain and Compatibility cases, builds and smoke-tests them, audits them and fails the run on any failing case

evidence · persona asset-maintainer As an asset maintainer, I want every change of the agent template to be gated by its generated cases, so that a package that would generate a host that does not build, start or audit clean never reaches the feed.

The alignment verification of the template ran one nested Domain case and three Compatibility cases by hand and recorded that their audits were not reached after the configuration smoke failure, so the earlier clean audit was no evidence for the final candidate. This PBI turns that manual pass into the generated-solution gate of the template pipeline, which docs/architecture/ecosystem-composition.md names as a need of this component and whose mechanism is the shared template pipeline of Docs/Shared-Template-CI.md of the template. On every change of the template, the pipeline packs and installs the template, generates the Domain case and the Compatibility cases together with the identity, access and host-kind cases of the earlier features, restores and builds each case in Release, runs its configuration smoke tests, its unit and architecture tests and the placeholder scan, and runs the direct and transitive vulnerability audit of each generated solution. A case that fails any stage fails the run with the case and the stage named, and no later stage of that case is reported as evidence. The gate runs before the publication stage, which is reached only when every case is green. The run keeps the logs of every case as its artifacts. This is an evidence PBI (D113): a template feature has no scenario to trace, so the gate names what it proves through traces.adrs and its sources: the ADR-0028 amendment on the Factory templates and the generated-solution need that docs/architecture/ecosystem-composition.md records for this component.

Acceptance criteria

AC1 Given a change of the agent template, when the pipeline runs, then it packs and installs the template, generates the Domain case, the Compatibility cases and the cases of the identity, access and host-kind features, and for each case restores, builds in Release, runs the configuration smoke tests, the unit and architecture tests, the placeholder scan and the vulnerability audit (ADR-0028 amendment on the Factory templates; mechanism in Docs/Shared-Template-CI.md and Docs/AgentTemplate-Alignment-Verification.md of the template).
AC2 Given a case fails any stage, when the pipeline evaluates the run, then the run fails with the case and the stage named, no later stage of that case is reported as passed, and the publication stage is not reached; a fixture with a planted failing case proves the refusal (ADR-0028 amendment on the Factory templates: the two agent services are scaffolded only from a package whose generated solution passes).
AC3 Given every case is green, when the pipeline reaches the publication stage, then the stage is enabled with the logs of every case kept as run artifacts, and the gate closes the generated-solution need that docs/architecture/ecosystem-composition.md records for this component.
Traces: adrs ADR-0028
Depends on AIFACTORY-US-148
Sources model/components.yaml, docs/architecture/ecosystem-composition.md, docs/architecture/adr/0028-one-repository-and-deployable-per-service.md

Tasks

Task Kind Expected output Repository
AIFACTORY-TASK-844 Generated-case matrix definition of the template pipeline operations The template pipeline defines the Domain case, the Compatibility cases and the identity, access and host-kind cases with their generation options; each case is a named job that restores, builds, smoke-tests, tests, scans and audits its generated solution; the matrix is documented in Docs/Shared-Template-CI.md of the template. ConnectSoft.AI.SoftwareFactory.AgentTemplate
AIFACTORY-TASK-845 Fail-fast evaluation and publication stage dependency operations A failing stage of any case fails the run with the case and stage named and stops the later stages of that case; the publication stage depends on every case job and is skipped when one failed; the case logs are kept as run artifacts. ConnectSoft.AI.SoftwareFactory.AgentTemplate
AIFACTORY-TASK-846 Planted failing case fixture for the gate fixture A pipeline fixture generates a case with a planted configuration defect and asserts that the run fails at the smoke stage with the case named and that publication is not reached. ConnectSoft.AI.SoftwareFactory.AgentTemplate
AIFACTORY-TASK-847 Verify the generated-solution gate on a green and on a planted run verification One pipeline run with every case green reaches the publication stage and one run with the planted case fails before it; both runs prove AC1 to AC3 of AIFACTORY-US-149 and close the generated-solution gate docs/architecture/ecosystem-composition.md names for this component. ConnectSoft.AI.SoftwareFactory.AgentTemplate

AIFACTORY-US-150: Agent host template: the package is published to the feed with a verified version and the two Agent Mesh hosts generate from it unchanged

evidence · persona asset-maintainer As an asset maintainer, I want the agent template package on the feed with the version the readiness checklist names, so that AgentRuntimeService and WorkflowEngineService are scaffolded from a published package whose generated solution builds and passes.

The alignment verification of the template keeps package publication blocked until the generated cases pass their configuration smoke tests, and lists the remaining release checks: full application suites run twice against the available services, the database concurrency verification repeated, the generated audits rerun after the base template checkpoint, and fresh pipeline timings and publication gates confirmed. This PBI publishes the package once the gate of the earlier PBI is green and those checks are recorded in the readiness checklist of the template. The publication stage pushes the package with the version the checklist names and refuses a version that is already on the feed or that the checklist does not name. A probe installs the published package and generates the attempt-runtime and workflow-engine hosts with the names of the two Agent Mesh services; both build in Release unchanged. The documentation repository re-runs its template inventory so that the parameter snapshot lists every switch of this epic; the inventory reads no package version, so the published version is recorded in the readiness checklist of the template and not in the model. This is an evidence PBI (D113): a template feature has no scenario to trace, so the probe names what it proves through traces.adrs and its sources: the two silo kinds of ADR-0028 decision 4 generate unchanged from the published connectsoft-ai-agent package, and model/template-parameters/connectsoft-ai-agent.yaml lists the switches of the epic.

Acceptance criteria

AC1 Given the generated-solution gate is green and the readiness checklist records the remaining release checks, when the publication stage runs, then the package is pushed to the feed with the version the checklist names, and a version already on the feed or not named by the checklist is refused with the reason (ADR-0028 amendment on the Factory templates; the publication stage of Docs/Shared-Template-CI.md of the template).
AC2 Given the published package, when dotnet new install of that version is followed by a generation of the attempt-runtime host named for AgentRuntimeService and of the workflow-engine host named for WorkflowEngineService, then both generated solutions build in Release unchanged (ADR-0028 amendment on the Factory templates, D94, which scaffolds the two silo kinds of decision 4 from connectsoft-ai-agent; docs/architecture/adr/0028-one-repository-and-deployable-per-service.md).
AC3 Given the published package, when the documentation repository runs its template inventory, then every switch of this epic (agent-host-kind, UseFactoryModelRouter, UseFactoryToolAdapter, the Orleans choice of MessagingModelType, the derived default of agent-class-name and the flipped default of IncludeMcpSamples) appears in model/template-parameters/connectsoft-ai-agent.yaml and in the switches list of model/templates.yaml, and the row of the agent template in docs/architecture/catalogs/templates.md still renders.
Traces: adrs ADR-0028
Depends on AIFACTORY-US-149
Sources model/components.yaml, model/templates.yaml, model/template-parameters/connectsoft-ai-agent.yaml, docs/architecture/catalogs/templates.md, docs/architecture/adr/0028-one-repository-and-deployable-per-service.md

Tasks

Task Kind Expected output Repository
AIFACTORY-TASK-848 Readiness checklist completed with the remaining release checks documentation The readiness checklist of the template records the twice-run application suites, the repeated database concurrency verification, the rerun generated audits and the pipeline timings, and names the version to publish. ConnectSoft.AI.SoftwareFactory.AgentTemplate
AIFACTORY-TASK-849 Publication stage with the version guard operations The publication stage pushes the package to the feed with the version the checklist names; a version already on the feed or not named by the checklist is refused with the reason and the run fails. ConnectSoft.AI.SoftwareFactory.AgentTemplate
AIFACTORY-TASK-850 Published template configuration carries every switch of the epic for the inventory documentation The template configuration of the published package names every switch of this epic with its description and choices, so that python -I tools/docs_model inventory-templates of the documentation repository lists them in the switches of model/templates.yaml and in model/template-parameters/connectsoft-ai-agent.yaml without a hand edit. ConnectSoft.AI.SoftwareFactory.AgentTemplate
AIFACTORY-TASK-851 Verify the published package by generating the two Agent Mesh hosts verification Install the published version, generate the attempt-runtime host as ConnectSoft.AI.SoftwareFactory.AgentRuntimeService and the workflow-engine host as ConnectSoft.AI.SoftwareFactory.WorkflowEngineService, and build both in Release unchanged; this proves AC1 to AC3 of AIFACTORY-US-150 (ADR-0028). ConnectSoft.AI.SoftwareFactory.AgentTemplate

AIFACTORY-US-105: Agent host template: generated-solution gate and a publishable package is delivered and proven on a generated solution

enabling · persona asset-maintainer As an asset maintainer, I want AI Agent host template to carry a generated-solution gate and a publishable package, so that it serves AgentRuntimeService and WorkflowEngineService without later rework.

This is the integration PBI of the feature. With the submodule refreshed and the metadata reconciled, the generated-solution gate in the pipeline and the publication stage of the earlier PBIs, the asset maintainer runs the template pipeline end to end: pack, install, generate every case, restore, build, smoke-test, test, scan, audit, and publish with the verified version. A case that fails any stage fails the run and blocks publication with the case and stage named. The migrated tasks of this PBI are its proofs on the generated solution and on the published package; the implementation lives in the enabling PBI of the submodule and the metadata and in the tasks of the gate and probe evidence PBIs. The feature is done when the authoring solution builds in Release with zero errors, the gate runs on every change of the template and fails the run on any failing case, the package is on the feed with the version the readiness checklist names, and a fresh install of that package generates the two Agent Mesh hosts that build unchanged, which closes the blocked publication of the alignment verification and gives the ADR-0028 amendment on the Factory templates the published template AgentRuntimeService and WorkflowEngineService are scaffolded from.

Acceptance criteria

AC1 Given the template repository ConnectSoft.AI.SoftwareFactory.AgentTemplate with the work of this feature, when the template is packed, installed and instantiated in its pipeline, then the generated solution of every case builds and its tests pass before the package publishes with a verified version (ADR-0028, model/components.yaml).
AC2 Given the work of AIFACTORY-TASK-577 (base template submodule refreshed and agent metadata reconciled) is done, then the base-template submodule points at the base template that carries the substitution fix, the stale symbols of the agent metadata are removed, and the authoring solution builds in Release with zero errors (model/template-parameters/connectsoft-ai-agent.yaml lists each symbol once).
AC3 Given the work of AIFACTORY-TASK-578 (generated-solution gate in the template pipeline) is done, then the pipeline generates the Domain and Compatibility cases, restores, builds, runs the configuration smoke tests and the vulnerability audit, fails the run when any case fails, and the gate runs on every change of the template (ADR-0028 amendment on the Factory templates; mechanism in Docs/Shared-Template-CI.md of the template).
AC4 Given the work of AIFACTORY-TASK-579 (package published to the feed with a verified version) is done, then the template package is published with the version the readiness checklist names, and dotnet new install of the published package followed by a generation of the two Agent Mesh hosts builds unchanged (ADR-0028 amendment on the Factory templates, D94; docs/architecture/catalogs/templates.md).
Traces: adrs ADR-0028
Depends on AIFACTORY-US-148, AIFACTORY-US-149, AIFACTORY-US-150
Sources model/components.yaml, docs/architecture/catalogs/templates.md, docs/architecture/adr/0028-one-repository-and-deployable-per-service.md

Tasks

Task Kind Expected output Repository
AIFACTORY-TASK-577 Base template submodule refreshed and agent metadata reconciled verification The authoring solution and the default generated case prove the outputs of AIFACTORY-TASK-840 to AIFACTORY-TASK-843 (AC2 of AIFACTORY-US-105): the submodule carries the substitution fix, the metadata holds no stale symbol and the Release build reports zero errors. ConnectSoft.AI.SoftwareFactory.AgentTemplate
AIFACTORY-TASK-578 Generated-solution gate in the template pipeline verification The green pipeline run proves the outputs of AIFACTORY-TASK-844 to AIFACTORY-TASK-847 (AC3 of AIFACTORY-US-105): the pipeline generates the Domain and Compatibility cases, restores, builds, runs the configuration smoke tests and the vulnerability audit, and fails the run when any case fails; the gate runs on every change of the template. ConnectSoft.AI.SoftwareFactory.AgentTemplate
AIFACTORY-TASK-579 Package published to the feed with a verified version verification The published package proves the outputs of AIFACTORY-TASK-848 to AIFACTORY-TASK-851 (AC4 of AIFACTORY-US-105): the package is on the feed with the version the readiness checklist names and dotnet new install of it followed by a generation of the two Agent Mesh hosts builds unchanged. ConnectSoft.AI.SoftwareFactory.AgentTemplate
AIFACTORY-TASK-665 Verify agent-template-release-delivered by running the declared command verification Run dotnet build -c Release and dotnet test -c Release --no-build on the authoring solution and on every generated case of the matrix after the published package is installed; they pass and prove AC1 to AC4 of AIFACTORY-US-105. ConnectSoft.AI.SoftwareFactory.AgentTemplate