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

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 at line 60:

{
  "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. 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 (line 19): Validator usage guide
• docs/getting-started.md (lines 247 and 298): Onboarding instructions
• AGENTS.md (line 42): Agent workflow cheat-sheet

Step-by-Step Configuration Guide

Local Development Setup

Install dependencies and verify your environment:

# 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 at line 303:

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

#!/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

# From repository root

npm run validate:parity

CI Workflow Integration

# .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

// 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 (line 60) and executes .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 (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 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.

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