How AI‑DLC Detects Brownfield Projects During Workspace Detection

AI‑DLC detects brownfield projects by recursively scanning the workspace for existing source files and build artifacts, then setting a brownfield flag to true if any code is found outside the aidlc-docs/ directory.

The awslabs/aidlc-workflows repository defines the AI‑Driven Development Life‑Cycle (AI‑DLC) methodology, which classifies projects as either greenfield or brownfield during the Inception stage. This classification determines whether the workflow proceeds to reverse engineering or starts with a blank architectural vision.

The Workspace Detection Phase

According to the source specification in [aidlc-rules/aws-aidlc-rule-details/inception/workspace-detection.md](https://github.com/awslabs/aidlc-workflows/blob/main/aidlc-rules/aws-aidlc-rule-details/inception/workspace-detection.md), the detection occurs in the Workspace Detection phase. This phase inspects the file system to determine if an existing code base exists before the AI generates any new artefacts.

The logic relies entirely on declarative file‑system inspection rather than runtime analysis, ensuring that existing production code is never accidentally overwritten.

Step‑by‑Step Brownfield Detection Logic

1. State‑File Check (Resume vs. Fresh Start)

First, AI‑DLC looks for aidlc-docs/aidlc-state.md in the workspace root. If this file exists, the workflow resumes from the previously saved phase rather than performing a fresh detection scan.

aidlc-docs/aidlc-state.md

2. Source‑Code Scan (Identifying Existing Code)

If no state file exists, the system recursively scans the workspace—specifically excluding the aidlc-docs/ folder—to find common source‑code extensions and build‑file signatures.

Scanned patterns include:

• Source files: .java, .py, .js, .ts, .jsx, .tsx, .kt, .kts, .scala, .groovy, .go, .rs, .rb, .php, .c, .h, .cpp, .hpp, .cc, .cs, .fs
• Build files: pom.xml, package.json, build.gradle, Cargo.toml, go.mod, etc.

This scan identifies whether the workspace contains an existing implementation that requires reverse engineering.

3. Brownfield Flag Assignment

Based on the scan results:

• No source files found → brownfield = false (classified as greenfield)
• Any source files found → brownfield = true (classified as brownfield)

The boolean flag is stored in the state file and drives the subsequent phase selection.

4. Reverse‑Engineering Artefact Validation

For projects flagged as brownfield, AI‑DLC checks aidlc-docs/inception/reverse-engineering/ for previously generated reverse‑engineering artefacts. If up‑to‑date artefacts exist, the workflow can skip the reverse‑engineering step; otherwise, it proceeds to that phase.

5. State File Creation

The detection results—including project type, existing code evidence, workspace root, and reverse‑engineering requirements—are written to aidlc-docs/aidlc-state.md. This markdown file becomes the single source of truth for all subsequent AI‑DLC phases.

6. User‑Visible Summary

Finally, AI‑DLC presents a completion message that explicitly states:

Project Type: Brownfield
Next Phase: Reverse Engineering

Detection Implementation Details

The detection algorithm is implemented as a deterministic file‑system walker. By excluding the aidlc-docs/ directory from the scan, the system avoids false positives from its own generated documentation or previous AI‑DLC outputs.

The methodology defines brownfield as any project containing existing implementation code that must be understood before modification, while greenfield represents a clean slate with no existing source files.

Example Detection Script

The following Python illustration mimics the internal AI‑DLC CLI logic for detecting brownfield projects:

import pathlib
import json

def is_brownfield(workspace: pathlib.Path) -> bool:
    """Return True if source files are found in the workspace."""
    src_patterns = [
        "*/*.java", "*/*.py", "*/*.js", "*/*.ts", "*/*.jsx", "*/*.tsx",
        "*/*.kt", "*/*.kts", "*/*.scala", "*/*.groovy", "*/*.go",
        "*/*.rs", "*/*.rb", "*/*.php", "*/*.c", "*/*.h",
        "*/*.cpp", "*/*.hpp", "*/*.cc", "*/*.cs", "*/*.fs"
    ]
    for pattern in src_patterns:
        if any(workspace.glob(pattern)):
            return True
    return False

def detect_project_type(root: str = "."):
    root_path = pathlib.Path(root)
    state_file = root_path / "aidlc-docs" / "aidlc-state.md"
    if state_file.exists():
        print("Resuming existing AI‑DLC session.")
        return

    brownfield = is_brownfield(root_path)
    project_type = "Brownfield" if brownfield else "Greenfield"
    print(f"Detected project type: {project_type}")

    # Write minimal state file (real AI‑DLC writes a richer markdown document)

    state_file.parent.mkdir(parents=True, exist_ok=True)
    state_file.write_text(
        f"# AI‑DLC State Tracking\n"

        f"- Project Type: {project_type}\n"
        f"- Detected at: {root_path.resolve()}\n"
    )

if __name__ == "__main__":
    detect_project_type()

Running this in a repository containing Java or Python files outputs:

Detected project type: Brownfield

Summary

• AI‑DLC performs detection during the Workspace Detection phase of the Inception stage.
• The system scans for source files (.java, .py, .js, etc.) and build files (pom.xml, package.json, etc.) while excluding the aidlc-docs/ directory.
• Finding any existing source code sets brownfield = true; finding none sets it to false (greenfield).
• Results are persisted to aidlc-docs/aidlc-state.md, which serves as the single source of truth for subsequent workflow phases.
• Brownfield projects trigger a check for existing reverse‑engineering artefacts before proceeding.

Frequently Asked Questions

What file types does AI‑DLC scan to detect brownfield projects?

AI‑DLC scans for common programming languages including Java, Python, JavaScript, TypeScript, Kotlin, Scala, Go, Rust, Ruby, PHP, C/C++, C#, and F#. It also looks for build configuration files such as pom.xml, package.json, build.gradle, Cargo.toml, and go.mod to identify project structure.

Where does AI‑DLC store the brownfield detection results?

Detection results are stored in aidlc-docs/aidlc-state.md at the workspace root. This markdown file tracks the project type (brownfield or greenfield), detection timestamp, workspace path, and the state of reverse‑engineering artefacts for subsequent AI‑DLC phases.

Can AI‑DLC resume a previous detection session?

Yes. If aidlc-docs/aidlc-state.md exists when the workflow starts, AI‑DLC resumes from the saved phase recorded in that file rather than re‑scanning the workspace. This allows teams to pause and resume the AI‑DLC process without losing context.

How does AI‑DLC handle reverse engineering for brownfield projects?

After flagging a project as brownfield, AI‑DLC checks aidlc-docs/inception/reverse-engineering/ for existing documentation of the current system. If up‑to‑date artefacts are found, the workflow skips reverse engineering; otherwise, it proceeds to generate architectural models from the existing code base.

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