# How Synkra AIOS Installation Wizard Manages Existing Configurations in Brownfield Projects

> Learn how Synkra AIOS Installation Wizard seamlessly manages existing configurations in brownfield projects by merging new settings instead of overwriting.

- Repository: [SynkraAI/aios-core](https://github.com/synkraai/aios-core)
- Tags: how-to-guide
- Published: 2026-02-16

---

**The Synkra AIOS Installation Wizard detects brownfield projects by scanning for [`package.json`](https://github.com/SynkraAI/aios-core/blob/main/package.json) or `.git` markers, then merges new configurations with existing files rather than overwriting them.**

The Synkra AIOS Installation Wizard provides intelligent detection and preservation mechanisms when initializing AIOS in existing codebases. When run inside a directory containing prior development artifacts, the wizard automatically classifies the project as **brownfield** and adapts its configuration generation to respect existing standards. This approach ensures that initialization never destroys established `.gitignore` rules, IDE settings, or workflow configurations.

## Brownfield Detection Mechanism

### Project-Type Detection

The installer first executes the `detectProjectType` function located in [`packages/installer/src/detection/detect-project-type.js`](https://github.com/SynkraAI/aios-core/blob/main/packages/installer/src/detection/detect-project-type.js). This classifier examines the target directory for specific markers that indicate prior development activity.

```javascript
// packages/installer/src/detection/detect-project-type.js
if (hasPackageJson || hasGit) {
  return 'BROWNFIELD';
}

```

When the scanner discovers a [`package.json`](https://github.com/SynkraAI/aios-core/blob/main/package.json) file or a `.git` directory, it immediately returns the `BROWNFIELD` classification. This detection occurs at line 65 of the source file and serves as the primary gate for triggering brownfield-specific logic throughout the installation pipeline.

### Mode Detection and Confidence Scoring

Following initial classification, the wizard invokes `detectInstallationMode` from [`.aios-core/infrastructure/scripts/documentation-integrity/mode-detector.js`](https://github.com/SynkraAI/aios-core/blob/main/.aios-core/infrastructure/scripts/documentation-integrity/mode-detector.js). This function produces a detailed detection result that includes confidence scoring and legacy type mapping.

```javascript
// .aios-core/infrastructure/scripts/documentation-integrity/mode-detector.js
if (markers.hasPackageJson || markers.hasGit || …) {
  return {
    mode: InstallationMode.BROWNFIELD,
    legacyType: LegacyProjectType.BROWNFIELD,
    confidence: 90,
    reason: `Existing project detected: ${projectTypes.join(', ') || 'Git repository'}`,
    markers,
  };
}

```

The detection result returned at lines 138-152 includes a 90% confidence score and explicitly sets both the installation mode and legacy type to `BROWNFIELD`. This structured object propagates through the wizard to inform all downstream configuration decisions.

## Configuration Merging Strategy

### Preserving Existing .gitignore Rules

When operating in brownfield mode, the wizard analyzes existing repository artifacts through the `collectMarkers` routine. This routine records the presence of a `.gitignore` file and passes this metadata to the configuration generators. Rather than generating a fresh `.gitignore` that would overwrite user-defined exclusions, the brownfield configuration merges the AIOS template with the existing file, preserving custom rules while adding AIOS-specific entries.

### Adapting IDE Configurations

The IDE configuration generator receives an `isBrownfield` flag that modifies its output behavior. Located in [`packages/installer/src/wizard/ide-config-generator.js`](https://github.com/SynkraAI/aios-core/blob/main/packages/installer/src/wizard/ide-config-generator.js), this logic checks the project type before emitting configuration files.

```javascript
// packages/installer/src/wizard/ide-config-generator.js
const isBrownfield = projectType === 'BROWNFIELD' || projectType === 'EXISTING_AIOS';

```

When `isBrownfield` evaluates to true (lines 77-85), the generator adapts the `ide` section of the output to avoid overwriting existing editor settings, instead proposing additive changes that integrate with established development environments.

### Core Configuration Template Updates

The `generateCoreConfig` template in [`packages/installer/src/config/templates/core-config-template.js`](https://github.com/SynkraAI/aios-core/blob/main/packages/installer/src/config/templates/core-config-template.js) receives the `projectType` parameter and embeds it directly into the generated [`core-config.yaml`](https://github.com/SynkraAI/aios-core/blob/main/core-config.yaml).

```javascript
// packages/installer/src/config/templates/core-config-template.js
const { projectType = 'GREENFIELD', … } = options;
// …
project: { type: projectType, … }

```

For brownfield projects, the caller passes `'BROWNFIELD'` as the `projectType` (lines 15-18 and 36-42), ensuring that the resulting configuration file explicitly declares the project state. This metadata enables other AIOS tools to apply appropriate merging strategies throughout the project lifecycle.

## Wizard Execution Flow

The orchestration logic in [`packages/installer/src/wizard/wizard.js`](https://github.com/SynkraAI/aios-core/blob/main/packages/installer/src/wizard/wizard.js) implements the brownfield-specific user experience. When the detected mode resolves to `InstallationMode.BROWNFIELD`, the `configureModeSpecific` function executes a dedicated code path.

```javascript
// packages/installer/src/wizard/wizard.js
case InstallationMode.BROWNFIELD:
  console.log('📂 Brownfield Mode');
  console.log('   → Will analyze existing source tree');
  console.log('   → Will detect existing coding standards');
  console.log('   → Will merge with existing .gitignore');
  console.log('   → Will analyze existing GitHub workflows\n');
  config.deployment = await elicitDeploymentConfig();
  break;

```

This block (lines 142-149) explicitly communicates the non-destructive nature of the operation to the user, listing the preservation of source trees, coding standards, `.gitignore` rules, and GitHub workflows. Following this notification, the wizard proceeds to `elicitDeploymentConfig()` to gather deployment-specific settings while maintaining the existing development environment intact.

Upon completion, the `runWizard` function returns a comprehensive result object:

```javascript
return {
  projectType: detected.legacyType, // e.g. 'BROWNFIELD'
  installationMode: selectedMode, // 'brownfield'
  targetDir,
  detected,
  modeConfig, // contains generateDocs:true, generateConfig:true, generateGitignore:true, etc.
};

```

This object includes the detected legacy type, the selected installation mode, and a `modeConfig` structure that specifies which generators to execute (documentation, configuration, gitignore) and which to skip (such as `runSetupGithub` when existing workflows are detected).

## Practical Implementation Example

The following example demonstrates programmatic invocation of the brownfield detection and configuration flow:

```javascript
// example-brownfield-wizard.js
const { runWizard } = require('@aios/installer/src/wizard/wizard');

// Assume we are inside an existing Node project (package.json + .git)
runWizard({ targetDir: process.cwd() })
  .then(result => {
    console.log('=== Wizard Result ===');
    console.log(`Mode detected   : ${result.installationMode}`);
    console.log(`Project type    : ${result.projectType}`);
    console.log('Mode‑specific config:', result.modeConfig);
  })
  .catch(err => console.error('Wizard failed:', err));

```

Executing this script within a repository containing existing development artifacts produces output confirming the non-destructive brownfield approach:

```

🚀 Welcome to AIOS Installer

📊 Analyzing project directory...
✅ Detected: brownfield (Existing project detected: Node.js)

📂 Brownfield Mode
   → Will analyze existing source tree
   → Will detect existing coding standards
   → Will merge with existing .gitignore
   → Will analyze existing GitHub workflows

=== Wizard Result ===
Mode detected   : brownfield
Project type    : BROWNFIELD
Mode‑specific config: {
  mode: 'brownfield',
  generateDocs: true,
  generateConfig: true,
  generateGitignore: true,
  runSetupGithub: false,
  deployment: { … }
}

```

## Summary

- **Automatic Detection**: The Synkra AIOS Installation Wizard identifies brownfield projects by detecting [`package.json`](https://github.com/SynkraAI/aios-core/blob/main/package.json), `.git` directories, or other language-specific markers in `detectProjectType` and `detectInstallationMode`.
- **Non-Destructive Merging**: Rather than overwriting existing files, the wizard merges AIOS configurations with existing `.gitignore` rules, IDE settings, and GitHub workflows.
- **Mode-Specific Configuration**: The `configureModeSpecific` function in [`wizard.js`](https://github.com/SynkraAI/aios-core/blob/main/wizard.js) executes brownfield-specific logic that analyzes existing coding standards and source trees while skipping destructive operations like `runSetupGithub`.
- **Explicit Project Typing**: The [`core-config-template.js`](https://github.com/SynkraAI/aios-core/blob/main/core-config-template.js) embeds `project.type: 'BROWNFIELD'` into generated configuration files, enabling downstream tools to apply appropriate merging strategies.
- **Confidence Scoring**: The detection system provides a 90% confidence score and detailed reasoning when classifying projects as brownfield, ensuring transparent decision-making.

## Frequently Asked Questions

### How does the Synkra AIOS Installation Wizard determine if a project is brownfield?

The wizard executes a two-stage detection process. First, `detectProjectType` in [`packages/installer/src/detection/detect-project-type.js`](https://github.com/SynkraAI/aios-core/blob/main/packages/installer/src/detection/detect-project-type.js) scans for [`package.json`](https://github.com/SynkraAI/aios-core/blob/main/package.json) or `.git` directories. Second, `detectInstallationMode` in [`.aios-core/infrastructure/scripts/documentation-integrity/mode-detector.js`](https://github.com/SynkraAI/aios-core/blob/main/.aios-core/infrastructure/scripts/documentation-integrity/mode-detector.js) validates these markers and returns a detection result with 90% confidence and `InstallationMode.BROWNFIELD` when existing project artifacts are confirmed.

### Will the AIOS Installation Wizard overwrite my existing .gitignore file?

No. When operating in brownfield mode, the wizard merges AIOS-specific entries with your existing `.gitignore` rules rather than replacing the file. The `collectMarkers` routine records the presence of existing ignore patterns, and the configuration generators preserve custom exclusions while adding AIOS-required entries. This merging behavior is explicitly communicated to users when the wizard displays "→ Will merge with existing .gitignore" during the brownfield configuration phase.

### What configuration files does the wizard modify in a brownfield project?

The wizard adapts several configuration layers when initializing AIOS in existing projects. It generates [`core-config.yaml`](https://github.com/SynkraAI/aios-core/blob/main/core-config.yaml) with `project.type` set to `BROWNFIELD` via [`core-config-template.js`](https://github.com/SynkraAI/aios-core/blob/main/core-config-template.js), adjusts IDE settings in [`ide-config-generator.js`](https://github.com/SynkraAI/aios-core/blob/main/ide-config-generator.js) to avoid overwriting existing editor configurations, and merges `.gitignore` patterns. Additionally, it analyzes existing GitHub workflows without modifying them directly, setting `runSetupGithub: false` in the mode configuration to prevent destructive changes to established CI/CD pipelines.