How AI-DLC's Adaptive Execution Engine Determines Which Stages to Run Per Request

AI-DLC's adaptive execution engine evaluates runtime project context against conditional predicates defined in AIDLC rule files to dynamically include or exclude specific stages while maintaining a deterministic workflow order.

The awslabs/aidlc-workflows repository implements an intelligent execution system that tailors the AI-Driven Development Lifecycle (AI-DLC) to individual project requirements. Instead of executing a rigid, predefined pipeline, the engine analyzes workspace characteristics and complexity metrics at runtime to optimize computational resources and skip irrelevant stages.

Workspace Detection and Project Classification

The adaptive execution engine begins every request by loading inception/workspace-detection.md via the executor agent in scripts/aidlc-evaluator/packages/execution/src/aidlc_runner/agents/executor.py. This initial stage inspects the workspace/ directory to classify the project as greenfield (new development) or brownfield (existing codebase).

This classification persists in the execution state and serves as the primary predicate for downstream conditional logic. According to the source code, the engine stores this classification early to ensure subsequent stages can reference it without re-scanning the workspace.

Conditional Stage Flags and Predicate Evaluation

In executor.py, each stage in the system prompt is explicitly annotated with either (ALWAYS) or (CONDITIONAL) flags. The engine evaluates runtime predicates to determine whether conditional stages execute, allowing the workflow to adapt to project-specific requirements.

Reverse Engineering for Brownfield Projects

The Reverse Engineering stage executes exclusively for brownfield projects. As implemented in lines 40-44 of executor.py, this stage runs only when the workspace detection identifies an existing codebase, preventing unnecessary analysis on greenfield initiatives.

Complexity-Driven Construction Stages

Multiple construction stages execute conditionally based on project complexity thresholds gathered during inception phases. According to lines 51-79 of executor.py, the following stages run only when complexity warrants them:

• User Stories
• Application Design
• Units Generation
• Functional Design
• NFR Requirements
• NFR Design
• Infrastructure Design

The engine references complexity metrics stored in the execution state to gate these stages, ensuring simple projects bypass elaborate design phases while complex undertakings retain comprehensive lifecycle coverage.

Workflow Planning and Dynamic Rule Loading

After completing mandatory inception steps, the Workflow Planning stage (inception/workflow-planning.md) generates an explicit execution plan that explicitly lists which construction stages will run. This plan synthesizes answers gathered from the simulator (human-in-the-loop) and the project scope determined in prior stages.

Before executing any stage, the engine calls load_rule('…') to load the corresponding rule file from the aidlc-rules/aws-aidlc-rule-details/ directory. As shown in lines 30-34 of executor.py, this architecture ensures that rule modifications instantaneously influence stage selection without requiring code changes or redeployment. The rule files contain the detailed instructions and conditional checks for each stage.

# Pseudocode illustrating stage selection logic

state = load_state()                     # contains project type, scope, etc.

if state.project_type == "brownfield":
    run_stage("reverse-engineering")     # CONDITIONAL stage

if state.complexity > THRESHOLD:
    run_stage("user-stories")            # CONDITIONAL stage

    run_stage("application-design")      # CONDITIONAL stage

# Workflow‑Planning creates the final plan

plan = generate_execution_plan(state)
for stage in plan.construction_stages:
    run_stage(stage)                     # Only stages listed in the plan run

Runtime Resilience and Simulator Integration

The adaptive execution engine configures the underlying Bedrock model client with retries={"max_attempts": 10, "mode": "adaptive"} (lines 18-22 of executor.py). This configuration ensures resilient LLM querying for transient failures, though it does not influence stage selection logic.

When stages require clarification or approval, the executor writes question files to aidlc-docs/ and hands the request off to the simulator agent (lines 101-112). After receiving simulator input, the engine always proceeds to the next stage, maintaining deterministic workflow continuity while incorporating human feedback into the execution state.

# Inside the executor’s system prompt (excerpt)

"""Execute these stages in order...
1. Workspace Detection (ALWAYS) — load_rule('inception/workspace-detection.md')
2. Reverse Engineering (CONDITIONAL: brownfield only) — load_rule('inception/reverse-engineering.md')
...
6. Application Design (CONDITIONAL) — load_rule('inception/application-design.md')
...
12. Code Generation (ALWAYS) — load_rule('construction/code-generation.md')
13. Build and Test (ALWAYS) — load_rule('construction/build-and-test.md')
"""

Summary

• Workspace Detection classifies projects as greenfield or brownfield in inception/workspace-detection.md, storing this classification for downstream conditional logic.
• Conditional Flags annotate stages as (ALWAYS) or (CONDITIONAL) in executor.py, with brownfield-specific and complexity-driven stages gated by runtime predicates.
• Workflow Planning generates an explicit execution plan that determines which construction stages run based on project scope and simulator input.
• Dynamic Rule Loading via load_rule() ensures the engine consults current rule files before each stage, making the system responsive to rule changes without code modification.
• Deterministic Progression guarantees that once conditions are met, the engine proceeds through the full lifecycle while skipping only those stages whose predicates evaluate to false.

Frequently Asked Questions

What causes the adaptive execution engine to skip a conditional stage?

The engine skips a conditional stage when its runtime predicate evaluates to false. For example, Reverse Engineering skips on greenfield projects, while complexity-dependent stages such as Application Design skip when the project scope falls below defined thresholds. These predicates are evaluated against the execution state maintained in executor.py.

How does the engine handle updates to AIDLC rule files during execution?

Because the engine calls load_rule('…') immediately before executing each stage (lines 30-34 of executor.py), any modifications to the rule files in aidlc-rules/aws-aidlc-rule-details/ take effect for the next stage. This design decouples stage logic from the executor code, allowing runtime updates to conditional checks and instructions without restarting the workflow.

What is the difference between ALWAYS and CONDITIONAL stage annotations?

ALWAYS stages execute regardless of project context, ensuring critical lifecycle steps such as Workspace Detection, Code Generation, and Build and Test run for every request. CONDITIONAL stages execute only when specific predicates—such as brownfield classification or complexity thresholds—evaluate to true, allowing the engine to tailor the workflow to project requirements.

How does workspace detection influence the overall workflow?

The greenfield versus brownfield classification determined by inception/workspace-detection.md drives the execution of the Reverse Engineering stage and influences the complexity assessment in subsequent phases. This classification persists in the execution state referenced throughout executor.py, ensuring the workflow adapts to existing codebases by including reverse engineering while omitting it for new development.

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