vigiles

vigiles

Quis custodiet ipsos custodes? — Who watches the watchmen?

---

You wouldn't ship code without a linter. Why ship agent instructions without one?

Your CLAUDE.md is a plain text file. Anyone can edit it. Nobody verifies it. The lint rule it references was disabled three months ago. The file path it mentions was renamed. The npm script it suggests was deleted. Your agent reads this, trusts it, and produces code based on lies.

Markdown can't be validated. TypeScript can.

npx vigiles init

vigiles compiles typed TypeScript specs to instruction files (CLAUDE.md, AGENTS.md). Every linter reference is verified against your actual config — not just that it exists, but that it's enabled. Every file path is checked against the filesystem. Every command is validated against package.json. If something is stale, broken, or disabled — you find out at compile time, not when the agent silently ignores your instructions.

After setup, the agent edits the spec instead of the markdown. Hooks auto-compile. Types catch typos in the editor. CI catches drift. It's self-maintaining.

Not using vigiles with AI agents is like not using ESLint with JavaScript. You can do it. You can't afford to.

Companion repo for Feedback Loop Is All You Need.

The Problem

Hand-written CLAUDE.md files rot silently. Here's what they actually look like:

## Code Style

Never use `any` — the `@typescript-eslint/no-explicit-any` rule
catches this. Always use `unknown` and narrow with type guards.
See `src/utils/type-helpers.ts` for project utilities.

## Testing

Run `npm run typecheck` before submitting. Every service in
src/services/ should have a corresponding test file.

Reads fine. Four things are wrong:

1. @typescript-eslint/no-explicit-any — disabled to unblock a deadline, never re-enabled
2. src/utils/type-helpers.ts — renamed to src/utils/narrowing.ts last quarter
3. npm run typecheck — script removed from package.json
4. Service/test pairing — no automated check, just a hope

The agent reads this, trusts it, and writes code based on stale claims nobody verified.

What Changes With vigiles

Claude Code

	Without vigiles	With vigiles
Instructions	Hand-written CLAUDE.md	Compiled from .spec.ts (build artifact)
Linter rule references	Trust-based (nobody checks)	Verified at compile time against real config
File paths	Rot silently when renamed	file() references checked against filesystem
Commands	Stale scripts go unnoticed	cmd() references checked against package.json
Direct edits to CLAUDE.md	Anyone can, nobody knows	PreToolUse hook blocks edits, redirects to spec
Spec edits	N/A	PostToolUse hook auto-compiles to markdown
Linter config changes	CLAUDE.md drifts out of sync	PostToolUse hook auto-regenerates types
guidance → enforce upgrades	Manual guesswork	/strengthen reads per-linter docs, suggests upgrades
New lint rules from PR feedback	Copy-paste from review	/pr-to-lint-rule generates rule + tests + spec entry
CI	Nothing to verify	vigiles audit catches hand-edits, disabled rules, stale refs

Codex (same compile-time checks, no hooks)