How the AI-DLC Per-Unit Loop Sequences Design Stages in awslabs/aidlc-workflows

The AI-DLC per-unit loop iterates over every unit of work generated during the Units Generation step, executing a fixed sequence of up to five conditional design stages followed by mandatory Code Generation, before finally running a unified Build & Test across the entire codebase.

AI-DLC (AI-Driven Development Life Cycle) structures its Construction Phase around this granular per-unit loop to ensure each unit of work is fully architected and implemented before proceeding to the next. According to the rule definitions in awslabs/aidlc-workflows, the workflow deterministically sequences design stages while maintaining strict audit trails via audit.md and state management through aidlc-state.md.

The Five Design Stages in the Per-Unit Loop

For each unit, the loop evaluates conditional triggers defined in core-workflow.md to determine which design stages execute before the mandatory code generation.

1. Functional Design (Conditional)

This stage runs only when the unit introduces new data models, complex business logic, or new business rules.

As defined in core-workflow.md at lines 297-306, the workflow loads construction/functional-design.md and requires:

• Mandatory logging of all user input to audit.md
• Presentation of a two-option completion prompt (Request Changes or Continue)
• Production of a technology-agnostic business-logic model

2. NFR Requirements (Conditional)

Executes when performance, security, scalability, or tech-stack decisions are required for the specific unit.

Referencing core-workflow.md at lines 333-340, this stage loads construction/nfr-requirements.md to identify non-functional requirements. The stage follows the same logging pattern as Functional Design, ensuring every decision is captured before proceeding.

3. NFR Design (Conditional)

This stage executes only if NFR Requirements ran successfully.

According to core-workflow.md at lines 353-360, the workflow loads construction/nfr-design.md to translate abstract NFRs into concrete design patterns such as caching strategies or rate-limiting implementations. The conditional dependency ensures resources are not wasted designing patterns for units without NFR constraints.

4. Infrastructure Design (Conditional)

Runs when the unit requires mapping to cloud services or deployment architecture.

Defined in core-workflow.md at lines 371-378, this stage loads construction/infrastructure-design.md to map services to AWS resources, IAM roles, and networking configurations. Like the preceding conditional stages, it logs interactions and requires user approval via the two-option prompt.

5. Code Generation (Always)

Unlike the preceding stages, Code Generation always executes for every unit.

As specified in core-workflow.md at lines 390-397, this stage operates in two distinct phases:

• Planning: Creates a detailed generation plan specifying files, dependencies, and test coverage
• Generation: Produces source files under aidlc-docs/construction/{unit-name}

The stage loads construction/code-generation.md and generates implementation code, unit tests, and supporting documentation.

Execution Mechanics and Workflow Logic

The per-unit loop follows a deterministic execution pattern where each stage's run_stage function loads the specified markdown rule file, logs user interactions, presents the completion prompt, and updates both audit.md and aidlc-state.md.

# Simplified execution model based on awslabs/aidlc-workflows rules

for unit in units:
    # Conditional: Functional Design

    if unit.needs_functional_design():
        run_stage('construction/functional-design.md', unit)
    
    # Conditional: NFR Requirements

    if unit.needs_nfr_requirements():
        run_stage('construction/nfr-requirements.md', unit)
    
    # Conditional: NFR Design (depends on previous NFR stage)

    if unit.nfr_requirements_executed():
        run_stage('construction/nfr-design.md', unit)
    
    # Conditional: Infrastructure Design

    if unit.needs_infra_design():
        run_stage('construction/infrastructure-design.md', unit)
    
    # Mandatory: Code Generation

    run_stage('construction/code-generation.md', unit)

# Final stage after all units complete

run_stage('construction/build-and-test.md')

Each conditional check evaluates the unit's metadata against rules defined in the core workflow, ensuring stages run only when architecturally necessary.

Why the Per-Unit Loop Architecture Matters

The granular loop structure provides three critical advantages for enterprise AI-driven development:

• Granular Control: Processing units individually prevents cross-unit bleed-through and ensures NFRs are scoped correctly to specific services
• Adaptive Depth: Conditional stages eliminate unnecessary processing—simple units without new business rules skip Functional Design, while stateless services may bypass Infrastructure Design
• Traceability: Mandatory logging to audit.md creates a complete audit trail for compliance, enabling reproducible builds and forensic analysis of architectural decisions

Summary

• The AI-DLC per-unit loop processes each work unit individually during the Construction Phase
• Four conditional stages (Functional Design, NFR Requirements, NFR Design, Infrastructure Design) execute only when specific architectural triggers are met, as defined in core-workflow.md lines 297-378
• Code Generation is the only mandatory per-unit stage, running a Planning and Generation workflow for every unit
• Build & Test runs once after all units complete, compiling the entire codebase
• Every stage requires interaction logging to audit.md and user approval through a standardized two-option prompt

Frequently Asked Questions

What triggers the Functional Design stage to run for a specific unit?

According to core-workflow.md lines 297-306, Functional Design executes conditionally when a unit introduces new data models, complex business logic, or new business rules. Simple units that reuse existing patterns skip this stage to avoid unnecessary architectural overhead.

Is Code Generation the only mandatory stage in the per-unit loop?

Yes. While Functional Design, NFR Requirements, NFR Design, and Infrastructure Design are all conditional based on the unit's characteristics, Code Generation runs unconditionally for every unit as specified in core-workflow.md lines 390-397. This ensures every unit produces implementation artifacts regardless of whether it required design-stage processing.

How does the workflow maintain accountability across conditional stages?

Every stage in the per-unit loop, whether conditional or mandatory, must log user interactions to audit.md and present a two-option completion prompt (Request Changes or Continue). Additionally, the workflow maintains state in aidlc-state.md, creating a deterministic and traceable record of which stages executed and what decisions were made for each unit.

Where are the generated code artifacts stored during the per-unit loop?

During the Code Generation stage, artifacts are produced under the aidlc-docs/construction/{unit-name} directory structure. This location is specified in construction/code-generation.md and ensures generated code remains organized by unit while awaiting the final Build & Test stage that compiles the entire codebase.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}