# How to Configure Multi-IDE Parity Validation Using npm run validate:parity in aios-core

> Configure multi IDE parity validation with npm run validate:parity in aios core. Ensure Claude, Codex, and Gemini IDE rule sets stay synchronized across the codebase. Learn how today.

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

---

**Run `npm run validate:parity` from the repository root to verify that Claude, Codex, and Gemini IDE rule sets remain synchronized across the aios-core codebase.**

The SynkraAI/aios-core repository maintains specialized rule sets for multiple AI IDEs to ensure consistent behavior across Claude, Codex, and Gemini. Multi-IDE parity validation prevents configuration drift by automatically comparing these rule sets and blocking changes that would create inconsistencies between supported development environments.

## What Is Multi-IDE Parity Validation?

Multi-IDE parity validation ensures that rule sets, skill definitions, and agent configurations remain identical across Claude, Codex, and Gemini implementations. The `npm run validate:parity` command executes a Node.js script that normalizes and compares IDE-specific artefacts stored in `.aios-core/product/templates/ide-rules/`.

When drift is detected—such as missing rules in one IDE or mismatched agent shortcuts—the validator reports specific file differences and exits with a non-zero status. This mechanism guarantees that updates to one IDE's configuration propagate correctly to all others.

## Architecture and Key Files

Understanding the validator's architecture helps you troubleshoot failures and extend the system for additional IDEs.

### npm Script Configuration

The command entry point is defined in [`package.json`](https://github.com/SynkraAI/aios-core/blob/main/package.json) at line 60:

```json
{
  "scripts": {
    "validate:parity": "node .aios-core/infrastructure/scripts/validate-parity.js"
  }
}

```

This abstraction allows the underlying implementation to change without affecting developer workflows or CI pipelines.

### Core Validator Implementation

The validation logic resides in [`.aios-core/infrastructure/scripts/validate-parity.js`](https://github.com/SynkraAI/aios-core/blob/main/.aios-core/infrastructure/scripts/validate-parity.js). This framework-agnostic Node.js script performs the following operations:

1. **Loads rule sets** from `.aios-core/product/templates/ide-rules/` subdirectories for Claude, Codex, and Gemini
2. **Normalizes** each rule by stripping comments and ordering keys deterministically
3. **Compares** normalized representations across all three IDEs to detect missing rules or definition mismatches
4. **Verifies** that agent-specific shortcuts (`@agent`, `/agent`) remain identical across implementations
5. **Reports** drift with file-specific diffs and exits with code `0` (success) or non-zero (failure)

### Documentation References

Multiple documentation files reference this workflow:

- [`docs/ide-integration.md`](https://github.com/SynkraAI/aios-core/blob/main/docs/ide-integration.md) (line 19): Validator usage guide
- [`docs/getting-started.md`](https://github.com/SynkraAI/aios-core/blob/main/docs/getting-started.md) (lines 247 and 298): Onboarding instructions
- [`AGENTS.md`](https://github.com/SynkraAI/aios-core/blob/main/AGENTS.md) (line 42): Agent workflow cheat-sheet

## Step-by-Step Configuration Guide

### Local Development Setup

Install dependencies and verify your environment:

```bash

# Install all dependencies (run once)

npm ci

# Execute parity validation

npm run validate:parity

```

Successful execution produces a brief confirmation message. If drift exists, the output identifies specific files and line differences requiring reconciliation.

### Fixing Parity Drift

When the validator reports inconsistencies:

1. Examine the diff output to identify which IDE configuration diverges
2. Edit files in `.aios-core/product/templates/ide-rules/` to synchronize content across Claude, Codex, and Gemini directories
3. Re-run `npm run validate:parity` until exit code is `0`

### CI Pipeline Integration

The repository already enforces parity validation in [`.github/workflows/ci.yml`](https://github.com/SynkraAI/aios-core/blob/main/.github/workflows/ci.yml) at line 303:

```yaml
- name: Validate IDE parity
  run: npm run validate:parity

```

This step blocks pull requests that introduce IDE configuration drift, ensuring that only synchronized changes reach the main branch.

### Pre-Commit Hook Setup (Optional)

For local guardrails, add the validator to `.husky/pre-commit`:

```bash
#!/bin/sh
. "$(dirname "$0")/_/husky.sh"

# Block commits that break multi-IDE parity

npm run validate:parity

```

This configuration prevents developers from committing changes that would fail CI validation, reducing feedback loop time.

## Code Examples

### Basic Validation Execution

```bash

# From repository root

npm run validate:parity

```

### CI Workflow Integration

```yaml

# .github/workflows/ci.yml

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with:
          node-version: '20'
      - run: npm ci
      - name: Validate IDE parity
        run: npm run validate:parity

```

### Programmatic Invocation

```javascript
// example.js
const { execSync } = require('child_process');

try {
  execSync('npm run validate:parity', { stdio: 'inherit' });
  console.log('✅ Multi-IDE parity validated successfully');
} catch (err) {
  console.error('❌ IDE parity validation failed');
  process.exit(1);
}

```

## Summary

- **`npm run validate:parity`** is the canonical command for ensuring synchronized rule sets across Claude, Codex, and Gemini IDEs in aios-core.
- The validator is defined in [`package.json`](https://github.com/SynkraAI/aios-core/blob/main/package.json) (line 60) and executes [`.aios-core/infrastructure/scripts/validate-parity.js`](https://github.com/SynkraAI/aios-core/blob/main/.aios-core/infrastructure/scripts/validate-parity.js).
- It normalizes and compares IDE-specific artefacts in `.aios-core/product/templates/ide-rules/` to detect drift.
- CI enforcement occurs automatically via [`.github/workflows/ci.yml`](https://github.com/SynkraAI/aios-core/blob/main/.github/workflows/ci.yml) (line 303), blocking PRs with parity violations.
- Optional local enforcement is available through `.husky/pre-commit` hooks or direct script invocation.

## Frequently Asked Questions

### What does the multi-IDE parity validator check?

The validator compares rule sets, skill definitions, and agent configurations across Claude, Codex, and Gemini implementations. It normalizes each file by stripping comments and ordering keys, then verifies that definitions remain identical across all three IDE directories in `.aios-core/product/templates/ide-rules/`.

### Where is the validate:parity script defined?

The npm script is declared in [`package.json`](https://github.com/SynkraAI/aios-core/blob/main/package.json) at line 60, mapping `validate:parity` to `node .aios-core/infrastructure/scripts/validate-parity.js`. This abstraction allows the underlying implementation to evolve without changing developer-facing commands or CI configurations.

### How do I fix validation failures when adding new IDE rules?

When the validator reports drift, examine the console output to identify which specific files differ between Claude, Codex, and Gemini directories. Synchronize the content across all three IDE rule directories in `.aios-core/product/templates/ide-rules/`, then re-run `npm run validate:parity` until it exits with code 0.

### Can I run parity validation outside of CI?

Yes. You can execute `npm run validate:parity` locally anytime after running `npm ci` to install dependencies. For automated local enforcement, add the command to `.husky/pre-commit` to block commits that would introduce parity violations, or invoke it programmatically from other Node.js scripts using `child_process.execSync`.