How Synkra AIOS Installation Wizard Manages Existing Configurations in Brownfield Projects

The Synkra AIOS Installation Wizard detects brownfield projects by scanning for 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. This classifier examines the target directory for specific markers that indicate prior development activity.

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

When the scanner discovers a 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. This function produces a detailed detection result that includes confidence scoring and legacy type mapping.

// .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, this logic checks the project type before emitting configuration files.

// 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 receives the projectType parameter and embeds it directly into the generated core-config.yaml.

// 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 implements the brownfield-specific user experience. When the detected mode resolves to InstallationMode.BROWNFIELD, the configureModeSpecific function executes a dedicated code path.

// 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:

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:

// 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, .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 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 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 scans for package.json or .git directories. Second, detectInstallationMode in .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 with project.type set to BROWNFIELD via core-config-template.js, adjusts IDE settings in 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.

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