How AI‑DLC Determines Phase Execution in Workflows: Core Logic and Decision Gates

AI‑DLC determines phase execution by evaluating rule‑file annotations, runtime context checks, extension opt‑ins, and explicit user approvals to decide which stages across Inception, Construction, and Operations should run for each specific request.

The AI‑DLC (AI‑Digital Lifecycle Companion) engine in the awslabs/aidlc-workflows repository orchestrates software development through a deterministic yet adaptive workflow defined in the core‑workflow.md rule file. At the start of every request, the system loads common rule files such as common/process‑overview.md and the rule‑detail directory matching the IDE, then applies a multi‑factor decision matrix to selectively execute only the necessary phases while maintaining full auditability.

Core Mechanisms Driving Phase Selection

The execution logic relies on five primary mechanisms encoded in the rule files and engine implementation.

Mandatory and Conditional Execution Flags

Every stage in the workflow is annotated with execution directives read directly from the rule files. In core‑workflow.md, lines 81‑94 define the Inception phase stages, while lines 91‑105 define the Construction phase stages. Each stage carries one of three flags:

• "ALWAYS EXECUTE" – The stage runs unconditionally regardless of context.
• "CONDITIONAL" – The stage runs only when specific prerequisite predicates evaluate to true.
• "CONDITIONAL – Brownfield only" – The stage runs exclusively for brownfield projects meeting additional criteria.

Context‑Aware Workspace Detection

Before any conditional logic executes, Workspace Detection runs unconditionally (line 98 in core‑workflow.md) to determine whether the project is brownfield or greenfield. This detection informs subsequent branching:

• If the workspace is brownfield and lacks reverse engineering artifacts, the engine triggers Reverse Engineering (lines 12‑18).
• If greenfield or artifacts exist, the workflow jumps directly to Requirements Analysis (line 7).

This runtime check ensures that expensive analysis phases only execute when the workspace state demands them.

Extension Opt‑In and Deferred Rule Loading

Extensions are scanned at startup, but only their *.opt‑in.md prompts are loaded initially. When a user opts into an extension, the full rule file is consulted to determine whether the related phase should run (see "Deferred Rule Loading" in lines 37‑40). This prevents unnecessary phases from loading into memory or appearing in the execution path until explicitly requested.

Adaptive Depth and Complexity Scoring

Phases such as Requirements Analysis dynamically adjust their depth—minimal, standard, or comprehensive—based on request complexity (lines 41‑45). This scoring influences how many subsequent stages are instantiated. A simple bug fix might trigger minimal analysis, while a new feature request could cascade into comprehensive requirements gathering and additional construction stages.

Explicit User Approval Gates

After each stage completion, the model presents a binary approval prompt and waits for explicit confirmation before proceeding. For example, construction/code-generation.md defines the completion prompt as:

**[Answer]**: Choose one
A. Request Changes
B. Continue to Next Stage

The engine will not proceed until the user selects option B, creating a hard gate that prevents accidental phase execution.

Execution Flow Implementation

The decision logic is implemented through a rules engine that evaluates stages sequentially. The following Python‑style pseudocode illustrates how the AI‑DLC engine evaluates execution predicates:

def should_execute(stage, context):
    """Evaluate if a stage should run based on rule file flags and context."""
    if stage.always:
        return True
    if stage.conditional:
        return stage.check(context)  # Custom predicate defined in rule file

    return False

def run_workflow(context):
    """Main workflow executor demonstrating phase determination logic."""
    load_common_rules()
    
    # Always execute workspace detection first

    if should_execute(Stage('Workspace Detection'), context):
        run_workspace_detection(context)
    
    # Conditional execution based on brownfield detection

    if context.is_brownfield and not context.has_rev_artifacts:
        run_reverse_engineering(context)
    
    # Core inception phases

    run_requirements_analysis(context)
    if should_execute(Stage('User Stories'), context):
        run_user_stories(context)
    
    # Planning and construction

    plan_workflow()
    if new_components_needed():
        execute_application_design()
    
    # Unit-level construction loops

    for unit in context.units:
        if functional_design_needed():
            execute_functional_design(unit)
        if nfr_requirements_needed():
            execute_nfr_requirements(unit)
        execute_code_generation(unit)
        # Approval gate enforced here before next iteration

    
    execute_build_and_test()
    execute_operations_placeholder()

This implementation demonstrates how the engine combines static rule flags with dynamic context evaluation to build an execution graph unique to each request.

State Tracking and Auditability

All phase execution decisions are persisted for transparency and reproducibility. The system maintains two critical audit files:

• aidlc-docs/aidlc-state.md – Tracks which phases have been executed, skipped, or are currently pending, allowing the engine to resume workflows or skip redundant stages across sessions.
• aidlc-docs/audit.md – Logs every decision, user input, approval response, and context evaluation, creating a complete trail of why specific phases ran or were bypassed.

These files ensure that AI‑DLC phase execution remains deterministic and auditable, satisfying compliance requirements for automated software development workflows.

Summary

• AI‑DLC phase execution relies on rule‑file annotations ("ALWAYS EXECUTE", "CONDITIONAL", "CONDITIONAL – Brownfield only") defined in core‑workflow.md to determine stage eligibility.
• Context‑aware checks such as Workspace Detection (line 98) and brownfield artifact validation trigger conditional phases like Reverse Engineering (lines 12‑18) only when necessary.
• Extension opt‑ins use deferred loading (lines 37‑40) to prevent phases from entering the execution path until explicitly enabled.
• Adaptive depth logic (lines 41‑45) scales phase complexity based on request analysis, skipping unnecessary substages.
• Explicit approval gates after each stage require user confirmation before the engine continues, preventing automated progression through critical checkpoints.
• Audit trails in aidlc-docs/audit.md and state tracking in aidlc-docs/aidlc-state.md ensure every phase execution decision is logged and reproducible.

Frequently Asked Questions

What are the three main phases in AI‑DLC workflows?

AI‑DLC structures software development into three high‑level phases: Inception (discovery and requirements), Construction (design and code generation), and Operations (deployment and maintenance). Each phase contains multiple stages governed by the execution flags and context checks described in core‑workflow.md.

How does AI‑DLC decide whether to run Reverse Engineering?

The engine runs Reverse Engineering only when Workspace Detection (which always executes at line 98) identifies a brownfield project that lacks existing reverse engineering artifacts. This conditional logic appears in lines 12‑18 of the core workflow, ensuring the phase runs exclusively for legacy codebases requiring analysis before new development begins.

Where does AI‑DLC store the execution state of each phase?

Current execution state is persisted in aidlc-docs/aidlc-state.md, which tracks completed, skipped, and pending phases. This file enables session resumption and prevents redundant phase execution across multiple interactions with the AI‑DLC engine.

Can AI‑DLC skip phases based on request complexity?

Yes. During Requirements Analysis, the engine evaluates request complexity (lines 41‑45) and adjusts the analysis depth to minimal, standard, or comprehensive. This adaptive scoring determines whether subsequent stages such as User Stories or Application Design execute at full scope, reduced scope, or are skipped entirely.

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