P1.LOC.002 — Declared vertical-slice directories carry their own AGENTS.md

Field	Value
Principle	P1 (Locality)
Severity	warn
Evidence	strong
Stability	experimental

What it checks

If the repository root contains any of the well-known slice-container directories, every immediate child that holds source files must carry an AGENTS.md or CLAUDE.md.

Recognized containers: - packs/, services/, modules/ - packages/, apps/, libs/ (monorepo conventions: Lerna, Turborepo, NX, Yarn workspaces) - plugins/, engines/, components/ (plugin/extension architectures: Rails engines, WordPress, etc.) - domains/, features/ (domain-driven design)

The rule is conditional: repos that don't use any of those layouts are unaffected. It does not impose a structure, only asks that declared slices label themselves.

Why it matters

When code is already organized into slices, each slice should be independently understandable. A per-slice AGENTS.md bounds the context an agent must hold in its head while editing a slice. Without it, a small change in packs/auth/ can require loading conventions from packs/billing/, the engine internals, and the top-level CLAUDE.md — the antithesis of locality.

When to care

• Care always once your repo uses a packs/, services/, packages/, apps/, or similar layout with more than one sibling slice.
• Care less for auto-generated slices or for a trivial slice whose entire surface is a single, short file. Suppress with a reason and an expires.

How to fix

Create an AGENTS.md at the slice root. Minimum contents:

• One sentence on what the slice is.
• The invariants a change must not break.
• The fast verification command for just this slice.
• Pointers (not duplication) to repo-level context.

Suppressing this rule

ignore:
  - rule: P1.LOC.002
    paths: ["packs/legacy-*"]
    reason: "Legacy slices on a documented deletion path"
    expires: 2026-12-31

(Path-scoped ignore arrives in Phase 2; Phase 1 supports rule-wide ignore only.)

History

• 0.1.0 — introduced at stability: experimental.