# How AI‑DLC Detects Brownfield Projects During Workspace Detection

> Learn how AI‑DLC detects brownfield projects by scanning for existing code and build artifacts outside the aidlc-docs directory. Find out more about this essential feature.

- Repository: [Amazon Web Services - Labs/aidlc-workflows](https://github.com/awslabs/aidlc-workflows)
- Tags: how-to-guide
- Published: 2026-05-09

---

**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](https://github.com/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)](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`](https://github.com/awslabs/aidlc-workflows/blob/main/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.

```markdown
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`](https://github.com/awslabs/aidlc-workflows/blob/main/pom.xml), [`package.json`](https://github.com/awslabs/aidlc-workflows/blob/main/package.json), `build.gradle`, [`Cargo.toml`](https://github.com/awslabs/aidlc-workflows/blob/main/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`](https://github.com/awslabs/aidlc-workflows/blob/main/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:

```text
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:

```python
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:

```text
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`](https://github.com/awslabs/aidlc-workflows/blob/main/pom.xml), [`package.json`](https://github.com/awslabs/aidlc-workflows/blob/main/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`](https://github.com/awslabs/aidlc-workflows/blob/main/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`](https://github.com/awslabs/aidlc-workflows/blob/main/pom.xml), [`package.json`](https://github.com/awslabs/aidlc-workflows/blob/main/package.json), `build.gradle`, [`Cargo.toml`](https://github.com/awslabs/aidlc-workflows/blob/main/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`](https://github.com/awslabs/aidlc-workflows/blob/main/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`](https://github.com/awslabs/aidlc-workflows/blob/main/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.