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

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, located at .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, .git, 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.

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. 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) tailored to full-stack development

The wizard, implemented in packages/installer/src/wizard/wizard.js, invokes the greenfield template 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 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, 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) to merge AIOX configuration with existing project files. The system uses 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 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, .git, etc.)
Initial Step	Project naming and platform selection	Documentation analysis (@analyst *document-project)
Configuration	Clean template (core-config-greenfield.tmpl.yaml)	Merged via brownfield-upgrader (core-config-brownfield.tmpl.yaml)
Workflow File	greenfield-fullstack.yaml	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:

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:

# 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 and core-config-greenfield.tmpl.yaml, presenting low integration risk.
• Brownfield workflows detect existing project markers and integrate AIOX via 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) 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. If the directory is empty (isEmpty: true), it selects greenfield mode. If it detects existing project files like package.json, .git, or 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 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 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, 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.

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