AI Target State Alignment Engine

A comprehensive plan for implementing a safe, traceable, and autonomous AI-driven software modernization pipeline.

High-Level Architecture

Design Philosophy

The pipeline's design adheres to four core principles: Safety First, Iterative Progress, Full Traceability, and Autonomy. It operates within GitLab CI/CD, orchestrated by a central "AI Refinement Agent."

Decoupled Validation Strategy

To ensure maximum safety, the system uses **Dynamic Pipeline Triggering**. The AI Agent commits changes to a feature branch and then triggers the project's standard CI/CD pipeline to validate them in the actual project environment before proceeding.

graph TD
    subgraph "AI Modernization Pipeline (Scheduled Run)" 
        A[Scheduled Trigger] --> B{Check .ai Directory};
        B -- Missing --> C(Workflow 1: Initialization);
        B -- Exists --> D(Workflow 2: Iterative Refinement);
        D -- Pushes Code --> E(Git Feature Branch);
        D -- Triggers & Monitors via API --> F(Validation Status);
        F -- Success --> G(Create Merge Request);
        F -- Failure --> H(Workflow 3: Failure Analysis);
        E -- Input --> I(Project's Standard CI/CD Pipeline - Validation);
        I -- Output Status --> F;
    end

    

    subgraph "Core Components"
        J(AI Agent - Python/LLM) -- Manages State --> K[(.ai Directory)];
    end

    C -- Executed by --> J;
    D -- Executed by --> J;
    H -- Executed by --> J;

Technology Stack

VCS & CI/CD

GitLab

Infrastructure

AWS (EC2)

IaC

Terraform/OpenTofu

AI Agent

Python

LLM

GPT-4o / Claude 3

The AI Agent

The AI Agent is the "brain" of the operation, a Python application with several core modules responsible for orchestration, state management, Git operations, and LLM communication.

State Management: The `.ai` Directory

modernization_plan.yml


plan:
  - id: 1
    name: "Add unit tests for UserService"
    priority: 10
    status: pending
  - id: 2
    name: "Upgrade Spring Boot from 2.5 to 2.7"
    priority: 5
    status: pending

refinement_history.log (JSONL)


{"timestamp": "...", "task_id": 1, "action": "start_task"}
{"timestamp": "...", "task_id": 1, "action": "validation_triggered"}
{"timestamp": "...", "task_id": 1, "action": "success_mr_created"}

GitLab CI/CD Integration

The pipeline runs on a controlled cadence (e.g., nightly) against the default branch. A `resource_group` is used to prevent concurrent modernization runs on the same project, ensuring stability.


stages:
  - ai_modernization

ai_refinement_workflow:
  stage: ai_modernization
  image: $AI_AGENT_IMAGE
  resource_group: ai_modernization_${CI_PROJECT_ID}
  script:
    - agent-cli execute-workflow
  rules:
    - if: '$CI_PIPELINE_SOURCE == "schedule"'
      when: always
    - if: '$CI_COMMIT_BRANCH =~ /^ai-refactor\//'
      when: never

Detailed Workflows

Workflow 1: Initialization

On its first run, the agent scans the repository, synthesizes the current state, ingests the Target State Architecture (TSA), creates a modernization plan, and commits the `.ai` directory.

Workflow 2: Iterative Refinement

The agent picks the next pending task, creates a feature branch, uses the LLM to generate code changes, pushes them, and triggers the validation pipeline. On success, it creates a Merge Request.

Workflow 3: Failure Analysis

If validation fails, the agent retrieves the pipeline logs, uses the LLM to analyze the root cause, documents the failure in `.ai/last_run_failure.md`, and cleans up the failed branch. This informs the next attempt.

Phased Implementation Plan

A phased approach is essential to manage complexity and ensure safety. The project is broken down into four distinct phases, each with a clear goal and deliverables.