AI-DLC generates nine conditional documentation artifacts under aidlc-docs/inception/reverse-engineering/ when it detects an existing codebase, covering architecture, API documentation, code structure, and quality metrics.

When you run the awslabs/aidlc-workflows engine against a repository containing existing application code, it triggers a Reverse Engineering stage that produces machine-readable documentation artifacts. These brownfield artifacts capture the current state of your codebase and serve as the foundation for all subsequent AI-driven development phases, including Requirements Analysis and Application Design.

How AI-DLC Detects Brownfield Projects

AI-DLC performs Workspace Detection at startup to determine if your repository contains existing code. When existing source files are detected, the workflow automatically triggers the Reverse Engineering stage defined in aidlc-rules/aws-aidlc-rules/core-workflow.md (lines 12-14). This conditional block executes only when the brownfield flag evaluates to true, ensuring documentation generation occurs exclusively for existing codebases.

The 9 Conditional Reverse-Engineering Artifacts

All brownfield-specific artifacts reside in aidlc-docs/inception/reverse-engineering/. These files are created only when analyzing existing projects, as specified in docs/GENERATED_DOCS_REFERENCE.md.

business-overview.md – Captures high-level business domain descriptions, key transactions, and domain terminology used throughout the application.

architecture.md – Contains system-level architecture diagrams, component boundaries, and data-flow narratives describing how services interact.

code-structure.md – Inventories the build system, main packages or modules, design patterns employed, and overall file layout of the repository.

api-documentation.md – Catalogs public and internal APIs including request/response schemas, data models, and endpoint specifications.

component-inventory.md – Lists all software components (application, infrastructure, shared libraries, and test suites) with their brief responsibilities.

technology-stack.md – Documents languages, frameworks, CI/CD tools, cloud services, and testing utilities currently in use.

dependencies.md – Maps internal and external library dependencies, version ranges, and relationship graphs between components.

code-quality-assessment.md – Records metrics including test coverage percentages, static analysis warnings, technical debt indicators, and coding style adherence.

reverse-engineering-timestamp.md – Stores metadata including who ran the analysis, when it occurred, and how it was performed for auditability purposes.

Global Artifacts Created for All Projects

In addition to the conditional reverse-engineering files, AI-DLC always creates these artifacts regardless of project type:

• aidlc-docs/aidlc-state.md – Tracks workflow progress and stage completion status
• aidlc-docs/audit.md – Immutable, timestamped log of every user input and AI response

Example Artifact Content

Below is a representative excerpt showing the format and depth of generated documentation:

# Architecture Overview

## System Context

- The system processes incoming **Order** events from an external SaaS platform.
- Core services:
  - `order-service` (Java Spring Boot) – business logic
  - `payment-service` (Node.js) – payment gateway integration
  - `notification-service` (Python) – email/SMS alerts

## Component Diagram

```mermaid
graph LR
    Client --> OrderService
    OrderService --> PaymentService
    OrderService --> NotificationService
    PaymentService --> BankAPI

POST /orders

{
  "orderId": "string",
  "customerId": "string",
  "items": [{ "sku": "string", "qty": 1 }]
}

Response: 201 Created with location header.

Technology Stack

• Language: Java 17, Node 20, Python 3.11
• Frameworks: Spring Boot, Express, FastAPI
• CI: GitHub Actions, Maven, npm, Poetry

## Summary

- AI-DLC generates **nine conditional artifacts** under `aidlc-docs/inception/reverse-engineering/` specifically for brownfield codebases
- These files cover business context, architecture, APIs, components, technology stack, dependencies, code quality, and audit metadata
- The **Reverse Engineering** stage triggers automatically when **Workspace Detection** finds existing code, implemented in [`core-workflow.md`](https://github.com/awslabs/aidlc-workflows/blob/main/core-workflow.md)
- **Global artifacts** ([`aidlc-state.md`](https://github.com/awslabs/aidlc-workflows/blob/main/aidlc-state.md) and [`audit.md`](https://github.com/awslabs/aidlc-workflows/blob/main/audit.md)) are created for both greenfield and brownfield projects
- All artifacts serve as the machine-readable foundation for subsequent AI-DLC phases

## Frequently Asked Questions

### Where does AI-DLC store brownfield documentation artifacts?

AI-DLC stores brownfield-specific documentation in the `aidlc-docs/inception/reverse-engineering/` directory. This path is created automatically when the **Workspace Detection** step identifies an existing codebase and triggers the **Reverse Engineering** stage.

### What triggers the generation of reverse-engineering artifacts?

The **Workspace Detection** step triggers artifact generation when it discovers existing application code in your repository. This conditional logic is defined 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) at lines 12-14, which checks if the `brownfield` flag is true before executing the Reverse Engineering stage.

### Are these artifacts generated for greenfield projects?

No. The nine reverse-engineering artifacts are **conditional** and appear only for brownfield projects. However, global files including [`aidlc-state.md`](https://github.com/awslabs/aidlc-workflows/blob/main/aidlc-state.md) and [`audit.md`](https://github.com/awslabs/aidlc-workflows/blob/main/audit.md) are generated for both greenfield and brownfield repositories.

### How can I verify what artifacts were generated for my project?

Check the `aidlc-docs/inception/` directory. If you see a `reverse-engineering/` subdirectory containing files like [`architecture.md`](https://github.com/awslabs/aidlc-workflows/blob/main/architecture.md) and [`code-quality-assessment.md`](https://github.com/awslabs/aidlc-workflows/blob/main/code-quality-assessment.md), your project was processed as a brownfield codebase. The complete artifact specification is documented in [`docs/GENERATED_DOCS_REFERENCE.md`](https://github.com/awslabs/aidlc-workflows/blob/main/docs/GENERATED_DOCS_REFERENCE.md).

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