CDX-301a · Module 1

Package-Level Overrides

3 min read

Package-level overrides let individual workspaces diverge from root conventions without polluting the shared config. The override mechanism uses AGENTS.override.md at the workspace directory level, which takes precedence over both the workspace AGENTS.md and the root AGENTS.md for that scope. This is the right tool for experimental packages, legacy code that cannot follow new conventions, or packages with unique compliance requirements.

A common anti-pattern is overriding at the root level to accommodate one package. If your payment processing package needs stricter rules, put those rules in packages/payments/AGENTS.md — not in the root where they burden every other workspace. The cascade should flow from general to specific, never the reverse.

Override files also solve the "legacy package" problem. When a package uses an older framework version or deprecated patterns that conflict with root rules, a workspace-level AGENTS.md can declare those deviations explicitly. This is better than removing the root rule, which would relax constraints for the entire monorepo.

# Legacy Auth Package

## Context
This package uses Express 4 (not 5) and Passport.js.
Do NOT suggest migrating to Express 5 — it is scheduled for Q3.

## Overrides from root
- Use CommonJS require(), not ES module imports
- Tests use Mocha + Chai, not Vitest
- Run tests: `npm test` (not `pnpm test`)

## Rules
- Never modify the session serialization logic without Greg's approval
- All auth routes must have rate limiting middleware

Do This

  • Scope overrides to the narrowest directory that needs them
  • Document the reason for every deviation from root rules
  • Set expiration dates on temporary overrides ("remove after Q3 migration")
  • Review override files during quarterly config audits

Avoid This

  • Override root rules because one package is non-compliant — fix the package
  • Create deep override chains (3+ levels) — they become impossible to debug
  • Let override files grow stale — outdated overrides cause more confusion than no overrides
  • Use overrides to suppress warnings instead of fixing the underlying issue