DEV Community

koki kanda
koki kanda

Posted on

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

#showdev #ai #opensource #python

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 (2)

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.

Collapse
 
kohli217 profile image
koki kanda •

Great question — that exact case is one of the false positives CWB tries to avoid.
CWB groups validation commands by instruction scope before comparing them. A root AGENTS.md is typically scope ., while something like packages/foo/AGENTS.md is scope packages/foo, so a root “run the full suite” command is not compared against a package-scoped “run only this package’s tests” command as if they were peers.
Path-specific or conditional rules (for example Copilot applyTo, Cursor globs, or Windsurf glob/model-decision rules) are even more conservative: CWB validates their commands against repository evidence individually, but excludes them from cross-file validation-drift comparison. That’s because reducing complex selectors to a coarse directory prefix could otherwise create exactly the false positive you described.
Cross-file validation-command-drift is currently reported only between repository-wide/override instructions in the same scope, and only when they both define the same validation family (test, lint, typecheck, etc.) but have no normalized command in common.
The trade-off is intentional: CWB would rather miss a conflict between two complicated overlapping path-specific selectors than flag intentional scoped differences as drift.
This is a really useful question — I should probably make that scope behavior more explicit in the docs.