# Greenfield vs. Brownfield Development Workflows in AIOX: Detection, Configuration, and Implementation

> Understand greenfield vs brownfield development in AIOX. Greenfield creates new project scaffolding, while brownfield integrates with existing codebases. Learn detection, configuration, and implementation.

- Repository: [SynkraAI/aiox-core](https://github.com/synkraai/aiox-core)
- Tags: deep-dive
- Published: 2026-03-15

---

**Greenfield workflows in AIOX generate full scaffolding for new projects, while brownfield workflows integrate with existing codebases through configuration merging and documentation-first analysis.**

AIOX (AI Orchestration & Execution) distinguishes between **greenfield and brownfield development workflows** to provide context-aware scaffolding. Whether you are initializing a brand-new application or augmenting a legacy codebase, the framework's mode detection system in SynkraAI/aiox-core automatically selects the appropriate orchestration path. This article examines the technical implementation of these workflows, analyzing how the system detects project states and generates corresponding configuration artifacts.

## How AIOX Detects Greenfield vs. Brownfield Modes

The framework determines which workflow to execute through an automated detection system that analyzes the target directory's existing structure.

### The Mode Detector Logic

At the heart of this system lies [`mode-detector.js`](https://github.com/SynkraAI/aiox-core/blob/main/mode-detector.js), located at [`.aiox-core/infrastructure/scripts/documentation-integrity/mode-detector.js`](https://github.com/SynkraAI/aiox-core/blob/main/.aiox-core/infrastructure/scripts/documentation-integrity/mode-detector.js). This module exports the `detectInstallationMode` function, which returns a structured `DetectionResult` containing the installation mode, confidence level, and human-readable reasoning.

The detector evaluates three primary states:

- **Greenfield**: Triggered when `isEmpty: true` — the target directory contains no files
- **Brownfield**: Triggered when the directory contains project markers such as [`package.json`](https://github.com/SynkraAI/aiox-core/blob/main/package.json), `.git`, [`requirements.txt`](https://github.com/SynkraAI/aiox-core/blob/main/requirements.txt), or similar existing configuration files
- **Framework-dev**: Triggered when an `.aiox-core` folder already exists (indicating the project is the framework itself)

When the detector identifies existing project markers, it returns `InstallationMode.BROWNFIELD`. For empty directories, it returns `InstallationMode.GREENFIELD`.

### Detection Results and Confidence Scoring

The detection system provides granular feedback beyond a simple binary classification. The `DetectionResult` object includes confidence metrics that help the wizard determine whether to proceed automatically or prompt for manual selection.

```js
const { detectInstallationMode } = require('./.aiox-core/infrastructure/scripts/documentation-integrity/mode-detector');

console.log(detectInstallationMode('/path/to/project'));
// → { mode: 'greenfield', confidence: 1.0, reason: 'Directory is empty' }
// → { mode: 'brownfield', confidence: 0.95, reason: 'Found package.json and .git' }

```

## Greenfield Workflow: Starting from Scratch

The greenfield path represents AIOX's "blank canvas" approach, generating complete project infrastructure without constraints imposed by existing code.

### Generated Artifacts and Templates

When operating in greenfield mode, AIOX produces comprehensive scaffolding through the workflow defined in [`.aiox-core/development/workflows/greenfield-fullstack.yaml`](https://github.com/SynkraAI/aiox-core/blob/main/.aiox-core/development/workflows/greenfield-fullstack.yaml). This workflow orchestrates the creation of:

- Complete documentation structure
- Deployment configuration wizard
- Starter `.aiox-core` directory with framework-specific settings
- A brand-new workflow file ([`greenfield-fullstack.yaml`](https://github.com/SynkraAI/aiox-core/blob/main/greenfield-fullstack.yaml)) tailored to full-stack development

The wizard, implemented in [`packages/installer/src/wizard/wizard.js`](https://github.com/SynkraAI/aiox-core/blob/main/packages/installer/src/wizard/wizard.js), invokes the greenfield template [`core-config-greenfield.tmpl.yaml`](https://github.com/SynkraAI/aiox-core/blob/main/core-config-greenfield.tmpl.yaml) to generate configuration files. This template assumes no prior conventions and establishes AIOX's preferred directory structure and tooling defaults.

### Risk Profile and Scaffolding

Greenfield development carries a **low integration risk** because no existing code requires migration or compatibility testing. The wizard asks for project name and target platform, then creates all files from scratch according to AIOX's current best practices without needing to reconcile conflicting configurations.

## Brownfield Workflow: Integrating with Existing Code

The brownfield path addresses the complexity of introducing AIOX into established codebases, such as legacy services, monorepos, or projects with existing [`package.json`](https://github.com/SynkraAI/aiox-core/blob/main/package.json) configurations.

### Documentation-First Analysis

Unlike the greenfield approach, the brownfield workflow begins with a **documentation phase** rather than immediate file generation. The wizard executes `@analyst *document-project` to capture the current state of the existing codebase before making any modifications.

This analysis step, detailed in [`.aiox-core/working-in-the-brownfield.md`](https://github.com/SynkraAI/aiox-core/blob/main/.aiox-core/working-in-the-brownfield.md), ensures AIOX understands existing architectural patterns before proceeding to Product Requirements Document (PRD) creation and integration planning. The framework respects existing conventions and avoids destructive changes to working systems.

### Configuration Merging Strategy

Rather than overwriting existing files, the brownfield workflow utilizes the **brownfield-upgrader** ([`brownfield-upgrader.js`](https://github.com/SynkraAI/aiox-core/blob/main/brownfield-upgrader.js)) to merge AIOX configuration with existing project files. The system uses [`core-config-brownfield.tmpl.yaml`](https://github.com/SynkraAI/aiox-core/blob/main/core-config-brownfield.tmpl.yaml) as a base template but applies intelligent merging logic to preserve existing settings while adding AIOX-specific orchestration capabilities.

The workflow file [`.aiox-core/development/workflows/brownfield-fullstack.yaml`](https://github.com/SynkraAI/aiox-core/blob/main/.aiox-core/development/workflows/brownfield-fullstack.yaml) drives this integration process, handling the story-development-cycle and agent orchestration in a way that accommodates existing CI/CD pipelines and project structures.

### Risk Management in Legacy Environments

Brownfield integration carries a **higher risk profile** because AIOX must avoid breaking changes while adding new capabilities. The framework implements incremental migration strategies and safety checks to ensure existing functionality remains intact throughout the integration process.

## Comparing Workflow Orchestration

The distinction between these workflows extends beyond initial setup into the ongoing development lifecycle:

| Aspect | Greenfield Workflow | Brownfield Workflow |
|--------|--------------------|----------------------|
| **Entry Point** | Empty directory detection (`isEmpty: true`) | Existing markers ([`package.json`](https://github.com/SynkraAI/aiox-core/blob/main/package.json), `.git`, etc.) |
| **Initial Step** | Project naming and platform selection | Documentation analysis (`@analyst *document-project`) |
| **Configuration** | Clean template ([`core-config-greenfield.tmpl.yaml`](https://github.com/SynkraAI/aiox-core/blob/main/core-config-greenfield.tmpl.yaml)) | Merged via brownfield-upgrader ([`core-config-brownfield.tmpl.yaml`](https://github.com/SynkraAI/aiox-core/blob/main/core-config-brownfield.tmpl.yaml)) |
| **Workflow File** | [`greenfield-fullstack.yaml`](https://github.com/SynkraAI/aiox-core/blob/main/greenfield-fullstack.yaml) | [`brownfield-fullstack.yaml`](https://github.com/SynkraAI/aiox-core/blob/main/brownfield-fullstack.yaml) |
| **Scaffolding** | Full generation (docs, deployment, `.aiox-core` directory) | Selective integration respecting existing structure |
| **Risk Level** | Low (no conflicts) | Higher (requires migration planning) |

## Implementing Mode Detection in Practice

You can leverage the mode detection system programmatically or through the CLI to build custom tooling around AIOX workflows.

### Programmatic Mode Detection

Use the detection API to conditionally execute workflow-specific logic:

```js
const { detectInstallationMode } = require('./.aiox-core/infrastructure/scripts/documentation-integrity/mode-detector');

function chooseWorkflow(targetDir) {
  const { mode, confidence } = detectInstallationMode(targetDir);
  
  if (mode === 'greenfield' && confidence > 0.9) {
    console.log('Launching greenfield-fullstack workflow...');
    // spawn('aiox', ['workflow', 'greenfield-fullstack']);
  } else if (mode === 'brownfield' && confidence > 0.9) {
    console.log('Launching brownfield-fullstack workflow...');
    // spawn('aiox', ['workflow', 'brownfield-fullstack']);
  } else {
    console.error('Unable to determine project type with sufficient confidence – please select manually.');
  }
}

chooseWorkflow(process.cwd());

```

### CLI Invocation

Explicitly specify the workflow mode when starting the wizard:

```bash

# For a new, empty project directory

aiox wizard start --mode greenfield

# For an existing codebase with established files

aiox wizard start --mode brownfield

```

## Summary

- **Greenfield workflows** in AIOX target empty directories and generate complete scaffolding using [`greenfield-fullstack.yaml`](https://github.com/SynkraAI/aiox-core/blob/main/greenfield-fullstack.yaml) and [`core-config-greenfield.tmpl.yaml`](https://github.com/SynkraAI/aiox-core/blob/main/core-config-greenfield.tmpl.yaml), presenting low integration risk.
- **Brownfield workflows** detect existing project markers and integrate AIOX via [`brownfield-fullstack.yaml`](https://github.com/SynkraAI/aiox-core/blob/main/brownfield-fullstack.yaml), employing the brownfield-upgrader to merge configurations and prioritizing documentation-first analysis.
- The **mode detector** ([`.aiox-core/infrastructure/scripts/documentation-integrity/mode-detector.js`](https://github.com/SynkraAI/aiox-core/blob/main/.aiox-core/infrastructure/scripts/documentation-integrity/mode-detector.js)) automates selection through the `detectInstallationMode` function, returning structured results with confidence scoring.
- **Risk profiles differ significantly**: greenfield development proceeds without conflicts, while brownfield integration requires careful management of existing conventions and incremental migration strategies.

## Frequently Asked Questions

### How does AIOX determine whether to use greenfield or brownfield mode?

AIOX evaluates the target directory through the `detectInstallationMode` function in [`mode-detector.js`](https://github.com/SynkraAI/aiox-core/blob/main/mode-detector.js). If the directory is empty (`isEmpty: true`), it selects greenfield mode. If it detects existing project files like [`package.json`](https://github.com/SynkraAI/aiox-core/blob/main/package.json), `.git`, or [`requirements.txt`](https://github.com/SynkraAI/aiox-core/blob/main/requirements.txt), it selects brownfield mode. The system returns a `DetectionResult` object containing the mode, confidence level, and reasoning.

### Can I force AIOX to use a specific workflow mode?

Yes. While the wizard automatically detects the appropriate mode, you can explicitly specify either `greenfield` or `brownfield` using the CLI flag `--mode`. For example: `aiox wizard start --mode brownfield`. This overrides automatic detection when working with edge-case directory structures that might confuse the heuristic detector.

### What configuration files does AIOX generate for brownfield projects?

For brownfield integration, AIOX uses [`core-config-brownfield.tmpl.yaml`](https://github.com/SynkraAI/aiox-core/blob/main/core-config-brownfield.tmpl.yaml) as the base template but merges settings with existing configuration files rather than overwriting them. The brownfield-upgrader handles this merging process, ensuring that existing [`package.json`](https://github.com/SynkraAI/aiox-core/blob/main/package.json) scripts, CI/CD configurations, and environment files remain functional while adding AIOX-specific orchestration capabilities.

### Is the brownfield workflow safe for production legacy systems?

The brownfield workflow is designed with safety mechanisms including the documentation-first `@analyst *document-project` step and configuration merging rather than replacement. However, as noted in [`.aiox-core/working-in-the-brownfield.md`](https://github.com/SynkraAI/aiox-core/blob/main/.aiox-core/working-in-the-brownfield.md), it carries a higher risk profile than greenfield development because it must respect existing conventions. Always review the generated integration plan and test in non-production environments before applying AIOX orchestration to critical legacy systems.