How AI-DLC Creates Workflow Visualizations: Mermaid Diagram Generation Explained

AI-DLC generates workflow visualizations during the Inception phase by analyzing project context, determining phase execution status, and rendering validated Mermaid flowcharts that reflect the adaptive workflow state.

The awslabs/aidlc-workflows repository implements a structured approach to software development lifecycle management, where workflow visualizations serve as critical communication artifacts. Understanding how AI-DLC creates these diagrams reveals the system's adaptive decision-making capabilities and its integration with Mermaid syntax standards.

The Workflow Visualization Pipeline

AI-DLC constructs workflow visualizations through a six-step pipeline defined in the core rule files. This process ensures that every diagram accurately represents the current state of the adaptive workflow.

Trigger Point in Core Workflow

The visualization process initiates at a specific checkpoint in aidlc-rules/aws-aidlc-rules/core-workflow.md. Line 243-244 define the trigger: "Generate workflow visualization (VALIDATE Mermaid syntax before writing)"【/cache/repos/github.com/awslabs/aidlc-workflows/main/aidlc-rules/aws-aidlc-rules/core-workflow.md†L243-L244】. This requirement ensures that no invalid diagrams are persisted to the documentation.

Context Collection

Before rendering, the system gathers comprehensive project context. According to aidlc-rules/aws-aidlc-rule-details/inception/workflow-planning.md lines 7-22, the planner loads all prior artifacts including reverse-engineering documentation, requirements specifications, and user stories【/cache/repos/github.com/awslabs/aidlc-workflows/main/aidlc-rules/aws-aidlc-rule-details/inception/workflow-planning.md†L7-L22】. This collection phase provides the data necessary to determine which workflow phases apply to the current request.

Phase Decision Analysis

The system analyzes scope, impact, risk, and conditional-execution decisions for every phase. Lines 23-44 of inception/workflow-planning.md detail this analysis, evaluating whether each phase should be executed, skipped, or conditionally processed【/cache/repos/github.com/awslabs/aidlc-workflows/main/aidlc-rules/aws-aidlc-rule-details/inception/workflow-planning.md†L23-L44】. These decisions directly translate to the status markers in the final visualization.

Mermaid Rendering

Once decisions are finalized, AI-DLC assembles a Mermaid flowchart. Lines 96-122 of inception/workflow-planning.md contain the rendering logic that creates a flowchart listing all phases and marking each with COMPLETED, SKIP, or EXECUTE status【/cache/repos/github.com/awslabs/aidlc-workflows/main/aidlc-rules/aws-aidlc-rule-details/inception/workflow-planning.md†L96-L122】. The diagram organizes phases into subgraphs representing the three lifecycle stages.

Syntax Validation

Before persisting, the diagram undergoes strict validation. The common/content-validation.md rules, referenced in core-workflow.md lines 52-55, require correct Mermaid syntax verification【/cache/repos/github.com/awslabs/aidlc-workflows/main/aidlc-rules/aws-aidlc-rules/core-workflow.md†L52-L55】. This validation step prevents rendering errors in downstream documentation viewers.

Persistence and Reference

The final validated diagram is written to aidlc-docs/inception/plans/execution-plan.md as specified in lines 51-55 of the workflow planning rules【/cache/repos/github.com/awslabs/aidlc-workflows/main/aidlc-rules/aws-aidlc-rule-details/inception/workflow-planning.md†L51-L55】. This file serves as the canonical reference displayed to users for approval before proceeding to subsequent phases.

Visual Styling and Color Coding

The visualization system implements a strict color protocol defined in aidlc-rules/aws-aidlc-rule-details/common/process-overview.md lines 33-60【/cache/repos/github.com/awslabs/aidlc-workflows/main/aidlc-rules/aws-aidlc-rule-details/common/process-overview.md†L33-L60】:

• Green (#4CAF50): Indicates phases that are COMPLETED or always executed
• Orange (#FFA726): Marks conditional-execute phases (EXECUTE)
• Gray: Represents skipped phases (SKIP)
• Blue containers: Inception phase grouping
• Green containers: Construction phase grouping
• Yellow containers: Operations phase grouping

Implementation Examples

The following examples demonstrate the actual structure used by AI-DLC when generating these visualizations.

Mermaid Diagram Structure

This template illustrates the flowchart generated during workflow planning:

flowchart TD
    Start(["User Request"])

    subgraph INCEPTION["🔵 INCEPTION PHASE"]
        WD["Workspace Detection<br/><b>COMPLETED</b>"]
        RE["Reverse Engineering<br/><b>SKIP</b>"]
        RA["Requirements Analysis<br/><b>COMPLETED</b>"]
        US["User Stories<br/><b>COMPLETED</b>"]
        WP["Workflow Planning<br/><b>EXECUTE</b>"]
        AD["Application Design<br/><b>EXECUTE</b>"]
        UG["Units Generation<br/><b>EXECUTE</b>"]
    end

    subgraph CONSTRUCTION["🟢 CONSTRUCTION PHASE"]
        FD["Functional Design<br/><b>STATUS</b>"]
        NFRA["NFR Requirements<br/><b>STATUS</b>"]
        NFRD["NFR Design<br/><b>STATUS</b>"]
        ID["Infrastructure Design<br/><b>STATUS</b>"]
        CG["Code Generation<br/><b>EXECUTE</b>"]
        BT["Build and Test<br/><b>EXECUTE</b>"]
    end

    subgraph OPERATIONS["🟡 OPERATIONS PHASE"]
        OPS["Operations<br/><b>PLACEHOLDER</b>"]
    end

    Start --> WD
    WD --> RA
    RA --> WP
    WP --> CG
    CG --> BT
    BT --> End(["Complete"])

    style WD fill:#4CAF50,stroke:#1B5E20,stroke-width:3px,color:#fff
    style RE fill:#9E9E9E,stroke:#424242,stroke-width:3px,color:#fff
    style CG fill:#4CAF50,stroke:#1B5E20,stroke-width:3px,color:#fff
    style WP fill:#FFA726,stroke:#E65100,stroke-width:3px,stroke-dasharray:5 5,color:#000

Validation Logic

The validation step referenced in the core workflow follows this pattern:

def validate_mermaid(diagram: str) -> bool:
    """Run Mermaid-Lint to ensure the diagram
    conforms to syntax rules defined in common/content-validation.md"""
    # Parse diagram structure

    # Verify node declarations

    # Check style syntax validity

    return is_valid

Document Integration

The final diagram is inserted into the execution plan document following this structure:

## Workflow Visualization

```mermaid
flowchart TD
    [Generated diagram content]

## Summary

- AI-DLC creates workflow visualizations during the **Workflow Planning** step of the Inception phase according to [`core-workflow.md`](https://github.com/awslabs/aidlc-workflows/blob/main/core-workflow.md) line 243-244.
- The system analyzes scope, risk, and impact to determine whether each phase receives **COMPLETED**, **SKIP**, or **EXECUTE** status.
- **Mermaid syntax validation** is mandatory before writing any diagram, as required by [`content-validation.md`](https://github.com/awslabs/aidlc-workflows/blob/main/content-validation.md) rules.
- Color coding follows strict conventions: green for completed/executed, orange for conditional, gray for skipped.
- Output is persisted to [`aidlc-docs/inception/plans/execution-plan.md`](https://github.com/awslabs/aidlc-workflows/blob/main/aidlc-docs/inception/plans/execution-plan.md) for user approval.

## Frequently Asked Questions

### What triggers the generation of a workflow visualization in AI-DLC?

The generation triggers during the Inception phase when the core workflow reaches the specific step declared in [`aidlc-rules/aws-aidlc-rules/core-workflow.md`](https://github.com/awslabs/aidlc-workflows/blob/main/aidlc-rules/aws-aidlc-rules/core-workflow.md) line 243-244. This step explicitly requires the system to "Generate workflow visualization" with mandatory Mermaid syntax validation before writing.

### How does AI-DLC determine the status of each workflow phase?

The system analyzes scope, impact, risk, and conditional-execution decisions for every phase according to the algorithm in [`aidlc-rules/aws-aidlc-rule-details/inception/workflow-planning.md`](https://github.com/awslabs/aidlc-workflows/blob/main/aidlc-rules/aws-aidlc-rule-details/inception/workflow-planning.md) lines 23-44. Based on this analysis, it assigns one of three statuses: **COMPLETED** for finished phases, **SKIP** for unnecessary phases, or **EXECUTE** for phases requiring work.

### Why does AI-DLC use Mermaid for workflow visualizations?

Mermaid provides a text-based diagram syntax that integrates naturally with Markdown documentation, enables version control tracking, and supports the color-coded styling requirements defined in [`aidlc-rules/aws-aidlc-rule-details/common/process-overview.md`](https://github.com/awslabs/aidlc-workflows/blob/main/aidlc-rules/aws-aidlc-rule-details/common/process-overview.md). The syntax validation requirement ensures all diagrams render correctly in standard Markdown viewers.

### Where are the generated workflow visualizations stored?

The final validated diagrams are written to [`aidlc-docs/inception/plans/execution-plan.md`](https://github.com/awslabs/aidlc-workflows/blob/main/aidlc-docs/inception/plans/execution-plan.md) as specified in [`aidlc-rules/aws-aidlc-rule-details/inception/workflow-planning.md`](https://github.com/awslabs/aidlc-workflows/blob/main/aidlc-rules/aws-aidlc-rule-details/inception/workflow-planning.md) lines 51-55. This file serves as the primary artifact for user review and approval before proceeding to the Construction phase.

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