DEV Community

koki kanda
koki kanda

Posted on

I built a preflight linter for repositories used by multiple AI coding agents

#ai #python #opensource #showdev

When a repository is used with multiple AI coding agents, the instructions can slowly drift apart.

You may end up with:

  • AGENTS.md telling Codex to use one command
  • Copilot instructions using another
  • Cursor rules targeting a different part of the repository
  • package scripts that were renamed but are still referenced by AI instructions

I built codex-workspace-bootstrap (cwb) to catch those problems before an AI coding agent starts changing code.

What it checks

cwb can detect:

  • repository readiness issues
  • package-manager mismatches
  • missing package.json scripts
  • conflicting validation commands
  • nested AGENTS.md / AGENTS.override.md
  • nested Cursor rules
  • Copilot path-specific instructions
  • risky filenames tracked by Git

It currently understands instruction/config files used by:

  • Codex
  • GitHub Copilot
  • Cursor
  • Cline
  • Continue
  • Claude Code
  • Gemini CLI

Usage

Install:

pip install codex-workspace-bootstrap
Enter fullscreen mode Exit fullscreen mode

Then run:

cwb preflight .
Enter fullscreen mode Exit fullscreen mode

The result is one of:

  • READY
  • NEEDS ATTENTION
  • BLOCKED

For CI:

cwb preflight . --fail-on-integrity
Enter fullscreen mode Exit fullscreen mode

There is also a safe fix preview:

cwb fix .
Enter fullscreen mode Exit fullscreen mode

Existing conflicting instruction files are never automatically rewritten.

Why I made it

AI coding tools are getting better at editing code, but the repository around them still needs to stay consistent.

My goal with cwb is not to replace Codex, Copilot, Cursor, Gitleaks, Trivy, or similar tools.

It is a preflight layer that runs before them.

The checks are local and deterministic. Commands found in AI instruction files are analyzed but not executed.

GitHub:

https://github.com/kohli217/codex-workspace-bootstrap

I’m especially interested in false positives, unusual monorepos, and real-world instruction layouts.

Top comments (1)

Collapse
 
ricart_juncadella_d62f385 profile image
Ricart Juncadella •

How does cwb distinguish conflicting validation commands from intentional differences in nested or path-specific instructions? If root instructions call for the full test suite but package-scoped instructions only require that package’s tests, flagging the difference would be a false positive.