@devravik/engineering-intelligence

v0.1.3

Published

8 days ago

Engineering quality control for AI coding agents: detect, attribute, prioritize, repair, verify.

0High
0Medium
0Low

devravik

ai-agent coding-agent antigravity agy claude-code codex cursor opencode code-quality code-review anti-slop

Engineering Intelligence

Engineering quality control for AI coding agents.

Detect problems. Understand impact. Simplify changes. Verify the result.

1 canonical skill · 18 commands · 81 deterministic detectors · live browser verification · dynamic baseline attribution

Quick start: From your project root, run npx @devravik/engineering-intelligence install, then run ei init (or /ei init) inside your AI coding tool. Full docs: GitHub.

Why Engineering Intelligence?

Modern AI coding agents generate an immense volume of code very quickly. That introduces a critical failure mode:

AI can produce technically valid software that is still bad software. It looks correct.

Large Language Models will cheerfully generate:

4-layer class indirection for a single database query (ARCH-001).
Circular dependency cycles between domain services (ARCH-003).
Pass-through Abstract Factories for singletons (SLOP-001).
Tautological echo comments that verbatim restate the code (SLOP-002).
Destructive migrations that lock production tables (DB-003).
Mutating API endpoints with missing authorization guards (API-001).
N+1 query loops inside serialization maps (DB-002).
AI purple/blue gradients and card-in-card visual slop (UI-COLOR-001, UI-SLOP-003).

Prompts alone cannot prevent this. Engineering Intelligence adds:

One setup flow. ei init records durable project truth in .ei/ (PROJECT.md, ARCHITECTURE.md, CONVENTIONS.md, DESIGN.md, constraints.md), so agents understand architecture without hallucinating boundaries.
18 commands. A shared engineering vocabulary with your AI: detect, review, simplify, impact, ship, doctor, ui critique, ui audit, ui distill, and more.
81 deterministic detector rules (32 code + 49 UI). Runs locally with zero LLM API costs and zero token latency.
Dynamic Git merge-base attribution. Distinguishes legacy debt from regressions in new changes (BASELINE vs NEW).
Staff-level release verification. Mechanical dispositions (BLOCK, FIX, REVIEW, SHIP) enforcing UNKNOWN != PASS.

What's Included

The Skill: engineering-intelligence

The skill installs as a native command across supported AI coding tools:

/ei <command> <target>
# or in terminal:
ei <command> <target>

Start every new project with:

ei init
# or `/ei init` in your agent chat

init inspects the project, discovers the active tech stack, and initializes the durable .ei/ context suite:

.ei/
├── PROJECT.md          # Mission, core domains, and detected stack baseline
├── ARCHITECTURE.md     # Layering rules, dependency boundaries, invariants
├── CONVENTIONS.md      # Coding style, error handling, validation idioms
├── DESIGN.md           # Visual design system tokens, typography, surfaces
├── DECISIONS.md        # Architecture Decision Records (ADRs)
├── constraints.md      # Invariants, performance budgets, forbidden deps
├── ignores.json        # Scoped waivers with mandatory justification
└── state/
    ├── baseline.json   # Known legacy baseline snapshot
    └── sessions/       # Ephemeral session inspection runs

Commands

All commands are accessible directly via the CLI or through your agent's native /ei slash interface:

Usage Examples

ei detect --changed           # Check changed files in active Git branch
ei review                     # Review changes with machine-derived disposition
ei simplify src/services/     # Strip pass-through wrappers and singletons
ei impact UserModel           # Check blast radius before refactoring
ei ship                       # Run release gate verification before merging
ei ui critique src/components # Run 5-pass UI & accessibility critique

Anti-Patterns & Slop Doctrine

Engineering Intelligence enforces explicit constraints against common AI-generated antipatterns:

No speculative indirection: Don't create single-implementation interfaces or factories (ARCH-001, SLOP-001).
No echo comments: Don't write comments that simply restate the line of code (SLOP-002).
No unhandled exceptions: Don't swallow errors in empty catch blocks or destroy stack traces (API-002).
No N+1 queries: Don't execute database queries inside map/filter/loops (DB-002).
No unindexed foreign keys: Don't define relational keys without index backing (DB-001).
No unconstrained HTTP: Don't make external network calls without timeouts or AbortSignals (API-005).
No generic AI aesthetics: Don't use purple-to-blue gradients, card-in-card nesting, or low-contrast text (UI-COLOR-001, UI-SLOP-003).

Installation

The skill needs no runtime of its own. It provisions native skills, instructions, rules, and hooks into your agent harness, while the deterministic engine runs via npm or local CLI.

Option 1: CLI installer (Recommended)

From the root of your project, run:

npx @devravik/engineering-intelligence install

This auto-detects active harness directories and installed CLIs (such as Antigravity, Claude Code, Codex, Cursor, OpenCode, Cline), lets you confirm or customize providers, and installs project-local or global skills.

Non-interactive / Scripted:

# Install for specific providers
npx @devravik/engineering-intelligence install --providers=agy,claude,cursor --scope=project
  
# Install globally across user config directories (~/.gemini, ~/.claude, etc.)
npx @devravik/engineering-intelligence install --scope=global

Update Existing Installations:

npx @devravik/engineering-intelligence update

System Health Check (doctor):

npx @devravik/engineering-intelligence doctor

Option 2: skills.sh Ecosystem (`npx skills add`)

Engineering Intelligence is automatically discoverable through skills.sh — no separate submission required. The skills.sh catalogue is seeded by installation telemetry: once the repo is public with a valid SKILL.md, the first npx skills add invocation registers it.

# Install from GitHub source (canonical)
npx skills add https://github.com/devravik/engineering-intelligence --skill engineering-intelligence

# Or via GitHub shorthand:
npx skills add devravik/engineering-intelligence

This installs Engineering Intelligence into any skills.sh-compatible agent (Claude Code, Cursor, Windsurf, and others). The canonical skill resides in skills/engineering-intelligence/SKILL.md with self-contained detector references, commands, anti-slop doctrine, and verification scripts.

Distribution pipeline: GitHub repo → skills.sh catalogue (auto-discovered via install telemetry) → npx skills add → agent harness. No portal submission or approval step needed.

Option 3: Claude Code Marketplace Plugin

Install the native Claude Code plugin with bundled skills and slash commands:

/plugin marketplace add devravik/engineering-intelligence

Claude Code only. Provides native /detect, /review, /simplify, /impact, /ship, and /ui commands with automated manifest version-lock parity.

Option 4: Google Antigravity (AGY)

Antigravity is supported as a first-class P0 environment with dual-directory compatibility:

Project-Local: Provisions .agents/skills/engineering-intelligence/SKILL.md and .agent/skills/engineering-intelligence/SKILL.md.
Global: Provisions ~/.gemini/config/skills/engineering-intelligence/SKILL.md.
Hooks: Configures edit-time verification and pre-stop check hooks in .agents/hooks.json.
Zero Runtime Dependency: AGY loads the skill's instructions directly; the EI engine is only invoked when deterministic checks or browser testing are requested.

Option 5: Manual Copy & Direct Git

Cursor:

cp -r providers/cursor/.cursor your-project/
# Or copy rule: cp providers/cursor/.cursor/rules/engineering-intelligence.mdc your-project/.cursor/rules/

OpenAI Codex & Copilot:

cp providers/codex/codex.json your-project/
cp providers/copilot/.github/copilot-instructions.md your-project/.github/

OpenCode:

cp -r providers/opencode/.opencode your-project/

Direct Git & Offline Environments:

git clone https://github.com/devravik/engineering-intelligence.git
cd engineering-intelligence
npm install
npm link

Diagnostic Verification (`ei doctor`)

Run ei doctor (or npx @devravik/engineering-intelligence doctor) to verify your environment, harnesses, detectors, hooks, and project context:

================================================================
                 ENGINEERING INTELLIGENCE DOCTOR
================================================================

──── Installed & Detected Harnesses ────
  ✓ Antigravity CLI (AGY)    [P0] (.agents/skills/engineering-intelligence/SKILL.md)
  ✓ Claude Code              [P0] (.claude/skills/engineering-intelligence/SKILL.md)
  ✓ OpenAI Codex CLI         [P0] (.github/copilot-instructions.md)
  ✓ Cursor                   [P1] (.cursor/rules/engineering-intelligence.mdc)
  ✓ GitHub Copilot           [P2] (.github/copilot-instructions.md)

──── Capabilities & Engines ────
  ✓ 32 Engineering Detectors (Architecture, DB, Security, API, Slop)
  ✓ 49 UI Detectors (Typography, Color, Spatial, Slop, A11y, Responsive)
  ℹ Browser Engine: Static DOM & CSS analysis active (install Playwright for live captures)
  ✓ 5-Pass Visual Reasoning Engine (Questions, Distill, Layout, Typeset, Harden, Polish)
  ✓ Agent Client Protocol (ACP) & stdio MCP Server

──── Lifecycle Hooks ────
  ✓ Antigravity (AGY)   : Active edit-time and stop verification hooks in .agents/hooks.json
  ℹ Claude Code         : Supported via native skill discovery in .claude/skills/ and plugin marketplace
  ! Codex / Copilot     : Directives in .github/copilot-instructions.md require user approval per prompt

──── Project Context Suite ────
  ✓ .ei/PROJECT.md        Found
  ✓ .ei/ARCHITECTURE.md   Found
  ✓ .ei/DESIGN.md         Found
  ✓ Baseline Snapshot     Snapshot active (4 legacy issues tracked)

──── Claude Marketplace & Version Parity ────
  Package Version:        0.1.0
  ✓ .claude-plugin/plugin.json      (0.1.0)
  ✓ .claude-plugin/marketplace.json (0.1.0)
  ✓ Version Alignment:           100% aligned
================================================================

The Quality Pipeline & Frozen Core

The core mental model and intellectual property of Engineering Intelligence is the deterministic evidence ➔ attribution ➔ reasoning ➔ verification pipeline:

DETECTION ENGINE                     CONTEXT ENGINE
(32 code + 49 UI rules)               (Project Memory: .ei/)
       │                                       │
       └───────────────────┬───────────────────┘
                           ▼
                  FINDING NORMALIZER
                  (EIFinding Contract)
                           │
                           ▼
                  BASELINE ATTRIBUTION
              (Git Merge-Base Reconciliation)
                           │
                           ▼
                  STAFF-LEVEL REASONING
               (Anti-Slop & Restraint Doctrine)
                           │
                           ▼
                     REVIEW MATRIX
                 (Disposition Derivation)
                           │
                           ▼
                     RELEASE GATE
                 (ei ship: UNKNOWN != PASS)

The Canonical Internal Finding Contract (`EIFinding`)

The Finding Normalizer acts as the stable interface boundary between raw deterministic analysis and reasoning layers:

type EIFinding = {
  ruleId: string
  category: Category
  severity: Severity

  evidence: {
    file: string
    line: number
    snippet: string
    hash: string
  }

  attribution:
    | "BASELINE"    // Pre-existing legacy debt
    | "NEW"         // Introduced in current changeset
    | "MODIFIED"    // Changed in current changeset
    | "RESOLVED"    // Fixed by current changeset
    | "UNKNOWN"     // Unverifiable without human review

  confidence: Confidence
  impact: Impact
  disposition: Disposition // BLOCK | FIX | REVIEW | IGNORE | SHIP
}

Conservative Completeness (Evidence vs. Proof)

Deterministic detectors execute locally via fast AST and text matching without LLM token overhead:

A finding means EI found concrete evidence matching a rule.
It does not mean EI proved that no other instance exists.

Detection is grounded in physical code evidence; it does not claim formal mathematical absence in ambiguous or unanalyzed paths.

Dynamic Git Merge-Base Attribution

EI distinguishes pre-existing legacy technical debt from newly introduced debt using dynamic Git merge-base reconciliation (git merge-base origin/main HEAD) against .ei/state/baseline.json:

BASELINE: 84 existing | THIS CHANGE: 2 new | 1 modified | 1 resolved

Legacy debt is tracked, not blamed on current pull requests.

Universal Provider Protocol: 16 Coding Agents Across 3 Surfaces

Rather than building 16 divergent, hard-coded adapters, Engineering Intelligence is structured around a Standard Engineering Intelligence Protocol. The core produces a unified quality control engine, which translates through 5 standard archetype drivers:

                     Engineering Intelligence Core
                                │
                     ┌──────────┴──────────┐
                     │   EI Core Engine    │
                     └──────────┬──────────┘
                                │ Standard EI Interface (Protocol)
        ┌───────────┬───────────┼───────────┬───────────┐
        ▼           ▼           ▼           ▼           ▼
       CLI        Skills      Hooks      ACP/MCP     IDE Rules
        │           │           │           │           │
      Codex        AGY        Claude       Zed        Cursor
      Aider       Cline      OpenCode     Kilo        Copilot
      Gemini      Kilo                  OpenHands    Windsurf
                                          Devin       Augment
                                                       Junie

The 2026 Agent Ecosystem Matrix

Model Context Protocol (MCP) & Agent Client Protocol (ACP)

Engineering Intelligence includes a built-in stdio JSON-RPC server (ei mcp):

{
  "context_servers": {
    "engineering-intelligence": {
      "command": "ei",
      "args": ["mcp"]
    }
  }
}

Exposed Tools: ei_detect, ei_review, ei_simplify, ei_impact, ei_ship, and ei_ui.

Deterministic Detector Catalog

Automated Test Suite

All 32 code detectors, 49 UI detectors, attribution logic, waiver policies, and provider adapters are verified by 119 automated regression tests:

npm test

Community & License

Engineering Intelligence is open source under the MIT License.

Repository: github.com/devravik/engineering-intelligence
Author: Ravi Krishnan Gupta ([email protected])
Contributions: See CONTRIBUTING.md to add detectors or failure fixtures.