How AI-DLC Code Generation Handles Greenfield Codebases: 6 Architectural Differences

AI-DLC code generation treats greenfield codebases by skipping reverse engineering, creating full directory scaffolds from scratch, and validating progress through checkbox-driven milestones rather than modifying existing files.

The AWS Labs aidlc-workflows repository defines distinct execution paths for new versus existing projects. When initializing AI-DLC code generation for greenfield codebases—environments with no prior source code—the workflow engine applies specialized rules that ensure complete project scaffolding before any business logic is written.

1. Workspace Detection and Classification

The workflow begins with Workspace Detection logic defined in aidlc-rules/aws-aidlc-rules/core-workflow.md. The system scans the target directory and classifies the project based on file presence:

• Greenfield: Directory is empty or lacks aidlc-state.md and existing source files (lines 98-106)
• Brownfield: Contains aidlc-state.md or recognizable source artifacts

During the Inception phase, the user confirms this classification through a standardized question format defined in aidlc-rules/aws-aidlc-rule-details/common/question-format-guide.md (lines 66-73), selecting between "new project (greenfield)" or "existing codebase (brownfield)." This binary classification drives all downstream generation logic.

2. Reverse Engineering Phase is Skipped Entirely

For greenfield projects, the Reverse Engineering phase is unconditionally skipped (lines 112-120 in core-workflow.md). This phase normally analyzes existing code to extract patterns, dependencies, and architectural constraints. Since greenfield codebases contain no existing artifacts to analyze, the workflow transitions directly from Inception to Construction, eliminating analysis overhead and potential hallucinations based on non-existent code.

3. Project Structure Setup (Greenfield Only)

The Construction → Code Generation rule file (aidlc-rules/aws-aidlc-rule-details/construction/code-generation.md) injects a mandatory step absent from brownfield workflows: "Project Structure Setup (greenfield only)" (lines 30-34).

Greenfield behavior:

• Creates complete directory hierarchies: src/, tests/, config/, or multi-unit patterns like {unit-name}/src/
• Establishes fresh workspace roots without checking for existing file conflicts

Brownfield behavior:

• Modifies files in-place within existing directory structures (e.g., src/main/java/, lib/)
• Never generates new top-level scaffolding that might duplicate existing architecture

4. Strict File Location and Generation Rules

During the Generation phase, the runner enforces location rules that fundamentally differ by project type (lines 74-89 in code-generation.md):

Greenfield code generation writes application code to a fresh workspace root (e.g., src/services/user-service.ts), following single-unit or multi-unit layout patterns (lines 79-84).

Brownfield code generation modifies existing directories only, strictly avoiding duplicate file creation or structural changes that would disrupt the incumbent architecture (lines 85-89).

5. Checklist-Driven Progress Tracking

Every greenfield generation step is expressed as a markdown checkbox (e.g., - [ ] Project Structure Setup (greenfield only)). The runtime logic—implemented in scripts/aidlc-evaluator/packages/execution/src/aidlc_runner/agents/executor.py—marks each box [x] immediately after completion (lines 90-98 in code-generation.md).

This ensures scaffolding validation occurs before business logic generation:

- [x] Project Structure Setup (greenfield only)
- [ ] Business Logic Generation
- [ ] Business Logic Unit Testing
- [ ] API Layer Generation

The checkbox mechanism guarantees that the full directory structure exists before any service, controller, or repository code is generated.

6. Result Summary Format Differences

Upon completion, the AI-DLC presenter formats output differently based on project classification (lines 35-38 in code-generation.md).

Greenfield reports display only created files:

# 💻 Code Generation Complete - user-service

• Created: src/services/user-service.ts
• Created: src/controllers/auth-controller.ts
• Created: tests/user-service.test.ts

Brownfield reports distinguish between modified and created files, reflecting the incremental nature of existing codebase updates.

Implementation Details and Code Examples

Workspace Detection Logic

The classification heuristic implemented in the execution agent evaluates directory contents:

def detect_workspace(root):
    if not any(Path(root).glob("*")):          # empty directory → greenfield

        return "greenfield"
    elif (Path(root) / "aidlc-state.md").exists():
        return "brownfield"
    else:
        # fallback heuristic (e.g., presence of source files)

        return "brownfield" if any(Path(root).rglob("*.py")) else "greenfield"

Source: Classification logic derived from core-workflow.md (lines 98-106) and implemented in scripts/aidlc-evaluator/packages/execution/src/aidlc_runner/agents/executor.py.

Prompt Template Context

The prompt template system (scripts/aidlc-evaluator/packages/cli-harness/src/cli_harness/prompt_template.py) injects greenfield detection status into the model context, ensuring the code generator receives explicit instructions to create rather than modify.

Summary

• Early detection: Empty workspaces lacking aidlc-state.md trigger greenfield classification in core-workflow.md
• Phase elimination: Greenfield projects skip Reverse Engineering entirely (lines 112-120)
• Scaffolding mandate: A dedicated "Project Structure Setup" step runs only for greenfield projects (lines 30-34)
• Location rules: Greenfield writes to fresh roots; brownfield modifies in-place (lines 74-89)
• Validation mechanism: Checkbox-driven progress tracking ensures complete scaffolding before logic generation (lines 90-98)
• Output format: Greenfield results list only "Created" files, omitting "Modified" entries (lines 35-38)

Frequently Asked Questions

How does AI-DLC detect a greenfield codebase?

The system scans the workspace root for the presence of aidlc-state.md or existing source files as defined in aidlc-rules/aws-aidlc-rules/core-workflow.md (lines 98-106). If the directory is empty or lacks these markers, the project is classified as greenfield, triggering the specialized generation workflow.

What happens to the Reverse Engineering phase in greenfield projects?

The Reverse Engineering phase is completely skipped for greenfield codebases (lines 112-120 in core-workflow.md). Since there is no existing code to analyze or pattern-match against, the workflow proceeds directly from the Inception phase to Construction, optimizing execution time and eliminating analysis errors.

How does AI-DLC code generation output differ between greenfield and brownfield?

Greenfield generation creates files in a fresh workspace with new directory structures (src/, tests/, config/) and reports only "Created" files in the result summary. Brownfield generation modifies existing files in-place, preserves incumbent directory layouts, and distinguishes between "Modified" and "Created" files in completion reports (lines 35-38 and 74-89 in code-generation.md).

Can AI-DLC switch from greenfield to brownfield mode mid-project?

Once a project initializes with a greenfield classification and generates its initial scaffold, subsequent workflow invocations detect the created aidlc-state.md and source files, automatically reclassifying the project as brownfield. This transition occurs naturally through the Workspace Detection logic without manual intervention.

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