🛡️ Open Engineering Standards (OES)

OES is a lightweight, zero-dependency CLI tool to define, check, and align AI coding assistants (like Cursor, Windsurf, and Antigravity) with your project's custom engineering standards.

Instead of writing agent prompt files from scratch, OES compiles your custom standards into configurations that IDE agents read automatically on startup.

🎯 Purpose & Audience

Why use OES?

AI agents are fast, but they can generate "code slop" (hardcoded colors, raw HTML tags, duplicate API logic, and insecure forms). OES ensures AI agents paired with you write clean, secure, and production-ready code that matches your style guides.

Who is this for?

• Developers paired with AI assistants: Keeps your assistant aligned with your guidelines.
• Team Leads: Standardizes AI developer patterns across multiple repositories.

🚀 Installation & Setup

Choose the installation method that fits your project type:

Option A: Local Installation (Best for Node.js / JS / TS projects)

Install OES as a development dependency inside your project:

npm install --save-dev open-engineering-standard

Run commands using npx:

npx oes init
npx oes check

(Make sure node_modules/ is in your .gitignore so library files aren't tracked by Git!)

Option B: Zero-Install (Best for quick runs & non-Node projects)

Run OES directly without installing it or adding any files/dependencies to your workspace:

npx open-engineering-standard init
npx open-engineering-standard check

Option C: Global Installation (Best for Flutter, Python, Go, and desktop apps)

Install OES globally on your machine:

npm install -g open-engineering-standard

Run commands directly in any directory:

oes init
oes check

🛠️ CLI Usage

Navigate to your project root and run one of the following commands:

1. Initialize Rules (oes init)

Analyzes your codebase to automatically detect the project type (Website Project/Web vs. Mobile App Project/Flutter) and launches an interactive wizard to choose:

• AI Platform Targets: Choose which AI assistant rules to generate (Antigravity, Cursor, Windsurf, or All).
• Rules Selection: Toggle specific engineering standards to enforce.

oes init

Generates configuration and rule files tailored to your selections:

• .oes.config.json (OES settings)
• .agents/skills/oes/SKILL.md (For Antigravity workspace skills)
• .skills/oes.md (Fallback/backward-compatible skill rules)
• .cursorrules (For Cursor IDE)
• .windsurfrules (For Windsurf IDE)

2. Audit Codebase (oes check)

Scans your workspace for styling, naming, and architectural violations, returning a status and an aesthetic HTML report.

oes check

Creates a visual oes-report.html report in your root.

3. Import Remote Rules (oes add <owner/repo>)

Imports OES standards directly from a public GitHub repository.

oes add Vikashuvi/OpenEngineeringStandard

🛡️ Standard Rules Audited

OES checks for and aligns your assistant on:

1. Folder Layouts: Directs code into /components, /services, /utils, /hooks.
2. Naming Conventions: Enforces PascalCase components, camelCase utilities/hooks, and UPPER_SNAKE_CASE constants.
3. API Isolation: Bans raw network requests (fetch/axios) inside UI components.
4. Form CAPTCHA: Enforces bot protection on public forms.
5. Theme Styling: Prevents hardcoded hex/rgb colors in favor of CSS variables.
6. Optimized Assets: Demands modern WebP/AVIF image formats.
7. Secrets Security: Scans for and prevents committed passwords/API keys.
8. Component Reusability: Limits component lines and inline styles.

📄 License

MIT License.