Skip to content

Agent Execution Flow

This document describes the detailed execution flow for the ConnectSoft AI Software Factory. It is written for architects and engineers understanding the workflow from prompt to production-ready code, including error handling and retry mechanisms.

The Factory orchestrates agents through a structured workflow: input → vision → architecture → engineering → QA → DevOps → deployment. Each stage involves specialized agents collaborating to produce artifacts, with built-in error handling and quality gates.

Tip

The execution flow is event-driven and traceable. Every agent action is logged with correlation IDs, enabling full observability and debugging of the generation process.

High-Level Flow

The Factory execution flow follows these main stages:

flowchart TD
    INPUT[Project Definition<br/>High-Level Requirements] --> VISION[Vision & Planning]
    VISION -->|Product Plan| ARCH[Architecture]
    ARCH -->|Blueprints & ADRs| ENG[Engineering]
    ENG -->|Code & Tests| QA[QA & Validation]
    QA -->|Quality Report| DEVOPS[DevOps]
    DEVOPS -->|CI/CD & Infrastructure| FINAL[Finalization]
    FINAL -->|Commit| ADO[Azure DevOps<br/>Generated Artifacts]

    QA -->|Issues Found| ENG
    ENG -->|Fixes| QA

    FINAL -->|Deploy| PROD[Production<br/>Running Services]

    style VISION fill:#2563EB,color:#fff
    style ARCH fill:#4F46E5,color:#fff
    style ENG fill:#10B981,color:#fff
    style QA fill:#EAB308,color:#fff
    style DEVOPS fill:#EF4444,color:#fff
    style ADO fill:#06B6D4,color:#fff
Hold "Alt" / "Option" to enable pan & zoom

Flow Overview:

  1. Input - Project definition or high-level requirements received
  2. Vision & Planning - Requirements refined, scope broken into epics/features
  3. Architecture - Bounded contexts designed, APIs and events defined
  4. Engineering - Code generated, microservices scaffolded, tests written
  5. QA & Validation - Quality verified, tests run, issues identified
  6. DevOps - CI/CD pipelines created, infrastructure generated
  7. Finalization - Artifacts committed to Azure DevOps, work items updated
  8. Deployment - Services deployed to target environment

Detailed Step-by-Step Flow

Stage 1: Vision & Planning

Trigger: Project definition or high-level requirements received

Agents Involved: - Vision & Planning Agents

Process: 1. Analyze input requirements and business context 2. Query knowledge system for similar projects 3. Refine vague requirements into specific features 4. Break down features into epics and user stories 5. Prioritize work based on business value 6. Create product plan document

Artifacts Produced: - Product plan with scope and goals - User stories and epics - Feature breakdown - Product roadmap (if applicable)

Output: Product plan passed to Architecture stage

Stage 2: Architecture

Trigger: Product plan received from Vision & Planning

Agents Involved: - Architect Agents

Process: 1. Analyze product plan and requirements 2. Query knowledge system for architectural patterns 3. Design bounded contexts following DDD principles 4. Define aggregates, entities, and value objects 5. Design APIs (REST/gRPC) and create OpenAPI specs 6. Design event schemas and integration contracts 7. Create context maps and system diagrams 8. Document architectural decisions in ADRs

Artifacts Produced: - Architecture blueprint - Bounded context designs - API specifications (OpenAPI/Swagger) - Event schemas - ADRs - Context maps

Output: Architecture blueprint passed to Engineering stage

Stage 3: Engineering

Trigger: Architecture blueprint received from Architecture

Agents Involved: - Engineering Agents (multiple agents can work in parallel)

Process: 1. Analyze architecture blueprint and ADRs 2. Query knowledge system for code patterns 3. For each microservice: - Generate Domain layer (entities, value objects, domain services) - Generate Application layer (use cases, workflows, DTOs) - Generate Infrastructure layer (repositories, external services, messaging) - Generate API layer (controllers, request/response models) - Generate unit tests for domain logic - Generate integration tests for APIs 4. Apply microservice template structure 5. Reference ConnectSoft.Extensions.* libraries 6. Generate code documentation

Artifacts Produced: - Complete microservice code (all layers) - Unit tests - Integration tests - Code documentation - Configuration files

Output: Generated code passed to QA stage

Stage 4: QA & Validation

Trigger: Generated code received from Engineering

Agents Involved: - QA & Validation Agents

Process: 1. Analyze generated code and architecture blueprint 2. Generate comprehensive test suites: - Unit tests for domain logic - Integration tests for APIs - Acceptance tests for user stories 3. Run static analysis and linting 4. Validate architectural compliance (Clean Architecture, DDD) 5. Check code quality metrics (coverage, complexity) 6. Validate security best practices 7. Generate quality report

Artifacts Produced: - Test suites (unit, integration, acceptance) - BDD specifications - Quality report - Test coverage metrics - Bug reports and fix suggestions

Output: Quality report passed to DevOps stage (or back to Engineering if issues found)

Stage 5: DevOps

Trigger: Quality report received from QA (with passing status)

Agents Involved: - DevOps Agents

Process: 1. Analyze generated microservices and requirements 2. Create CI/CD pipelines (Azure DevOps YAML): - Build stages - Test stages - Deploy stages (dev, staging, production) 3. Generate Infrastructure-as-Code (Bicep templates): - Azure resources (AKS, Service Bus, Cosmos DB, Key Vault, etc.) - Kubernetes manifests - Configuration secrets 4. Configure observability: - Logging setup - Distributed tracing - Metrics collection - Alerting rules 5. Create runbooks and operational documentation

Artifacts Produced: - CI/CD pipelines (YAML) - Infrastructure-as-Code (Bicep) - Kubernetes manifests - Deployment configurations - Runbooks - Monitoring dashboards

Output: Infrastructure code passed to Finalization stage

Stage 6: Finalization

Trigger: All artifacts received from previous stages

Agents Involved: - Factory Orchestrator (coordinates finalization)

Process: 1. Validate all artifacts are complete 2. Create repositories in customer's Azure DevOps 3. Commit code, tests, pipelines, documentation 4. Create work items (epics, user stories, tasks) 5. Link work items to code commits 6. Update project documentation 7. Generate project summary report

Artifacts Produced: - Azure DevOps repositories - Committed code and artifacts - Work items - Project documentation - Summary report

Output: Complete solution in customer's Azure DevOps

Error Handling and Retries

The Factory includes robust error handling and retry mechanisms:

Error Detection

Errors are detected at multiple levels: - Agent-level - Agents validate their own outputs - QA-level - QA agents catch quality issues - Orchestrator-level - Orchestrator detects workflow failures - Infrastructure-level - Deployment failures caught during DevOps stage

Error Types and Handling

Code Generation Failures: - Symptom: Engineering agent fails to generate valid code - Handling: Agent retries with adjusted parameters, queries knowledge system for similar solutions - Escalation: After 3 retries, escalates to human review

Quality Gate Failures: - Symptom: QA agent finds critical issues (security, architecture violations) - Handling: Code sent back to Engineering agent with detailed fix suggestions - Loop: Engineering → QA loop continues until quality gates pass - Escalation: After 5 iterations, escalates to architect review

Pipeline Failures: - Symptom: CI/CD pipeline fails to build or deploy - Handling: DevOps agent analyzes failure, fixes pipeline or infrastructure code - Retry: Pipeline retried automatically - Escalation: After 3 retries, escalates to human DevOps engineer

Invalid Configurations: - Symptom: Invalid configuration detected (missing required parameters, invalid values) - Handling: Agent validates configuration before execution, requests clarification - Escalation: Configuration errors escalate immediately (blocking issue)

Retry Strategy

The Factory uses exponential backoff for retries: - First retry: Immediate - Second retry: 5 seconds delay - Third retry: 15 seconds delay - Fourth retry: 60 seconds delay - After 4 retries: Escalate to human review

Compensation and Rollback

For partial failures: - Compensation: Orchestrator tracks completed work, can rollback partial changes - Rollback: Failed stages trigger rollback of previous stages if needed - Cleanup: Failed artifacts cleaned up automatically

Warning

Critical failures (security violations, data corruption risks) immediately stop the workflow and escalate to human review. Never auto-retry critical failures.

Example Scenarios

Scenario 1: New Microservice Generation

Input: "Create a new Audit Trail microservice for logging user actions"

Flow: 1. Vision & Planning: Refines into features (log events, query audit trail, export logs) 2. Architecture: Designs Audit bounded context with Event aggregate, defines APIs 3. Engineering: Generates Audit microservice with event storage and query APIs 4. QA: Generates tests, validates quality 5. DevOps: Creates CI/CD pipeline and infrastructure (Cosmos DB for events) 6. Finalization: Commits to Azure DevOps

Duration: ~30-60 minutes for complete microservice

Scenario 2: Existing Service Update

Input: "Add tenant filtering to the existing Invoice microservice"

Flow: 1. Vision & Planning: Analyzes existing service, creates update plan 2. Architecture: Reviews existing architecture, designs tenant filtering changes 3. Engineering: Updates Invoice microservice code (adds tenant context) 4. QA: Generates tests for tenant filtering, validates existing tests still pass 5. DevOps: Updates infrastructure if needed (no changes in this case) 6. Finalization: Creates pull request with changes

Duration: ~15-30 minutes for service update

Scenario 3: Cross-Cutting Change

Input: "Add OpenTelemetry tracing to all microservices"

Flow: 1. Vision & Planning: Identifies all affected microservices 2. Architecture: Designs tracing integration pattern 3. Engineering: Updates all microservices in parallel (adds tracing) 4. QA: Validates tracing works across all services 5. DevOps: Updates infrastructure (adds tracing collector) 6. Finalization: Commits changes to all repositories

Duration: ~45-90 minutes for cross-cutting change