[Maintenance after D1 front door] Shrink AGENTS.md to surviving invariants

Summary

Refactor the repository's agent-facing guidance so the root AGENTS.md contains only stable, globally applicable instructions, while subsystem-specific rules live close to the code they govern and the detailed module inventory becomes a generated or ordinary reference document loaded only when needed.

The current root guide is valuable and unusually explicit, but it also contains a large, frequently changing module map with issue-specific implementation notes. Because root guidance is global, agents may load substantial subsystem detail for tasks that touch only a small area. The same centralization also increases documentation drift: every module addition, extraction, or responsibility change requires editing an always-authoritative file.

Goal

Create a layered instruction model that improves both human discoverability and agent context efficiency without weakening repository invariants.

Suggested structure:

Root AGENTS.md

Keep only stable global material:

• project purpose, product boundary, and non-goals;
• authority order and instruction-resolution rules;
• package-wide architectural invariants;
• canonical bootstrap and validation commands;
• public API/change-management rules;
• security, compatibility, and write/approval policies;
• a concise map pointing to subsystem instructions and reference documentation.

Path-scoped guidance

Place subsystem-specific rules near the governed paths, using nested AGENTS.md or the repository's chosen path-scoped instruction mechanism, for example:

• src/contextweaver/context/;
• src/contextweaver/routing/;
• src/contextweaver/store/;
• src/contextweaver/adapters/;
• gateway/MCP surfaces;
• tests and documentation where distinct conventions genuinely apply.

Only create a scoped instruction file where there are durable local invariants; do not mirror the full root guide into every directory.

Module inventory

Move the detailed file-by-file responsibility map into a non-authoritative reference such as docs/agent-context/module-map.md or a generated structured artifact. Prefer generating stable facts from the repository where practical, with a drift check, while keeping architectural intent human-authored.

Design requirements

• The nearest applicable scoped instruction may refine global rules but must not silently contradict protected root invariants.
• Instruction authority and precedence must be documented for humans and supported agent surfaces.
• Volatile issue numbers, delivery status, and implementation history should not remain in always-loaded global guidance unless they encode a durable invariant.
• The restructuring must reduce global context without hiding critical commands or boundaries.
• A task touching multiple subsystems must have a deterministic way to discover all applicable guidance.

Proposed scope

1. Inventory the current root guide into:
   • stable global rule;
   • subsystem-local rule;
   • generated fact/module metadata;
   • volatile implementation history that belongs in normal docs/changelog.
2. Propose the target instruction hierarchy and precedence model.
3. Implement the smallest useful set of scoped files rather than one per directory.
4. Move or generate the detailed module map.
5. Add validation for broken references, missing required global sections, and generated-map drift where applicable.
6. Update contributor documentation and tool-specific wrappers so they still defer to the correct source of truth.

Non-goals

• Rewriting the architecture or changing runtime behavior.
• Removing useful agent guidance merely to reduce line count.
• Creating dozens of tiny instruction files.
• Treating token reduction as more important than correctness or discoverability.
• Resolving the module-size policy; coordinate with #753 but keep that decision separate.

Acceptance criteria

• Root AGENTS.md contains only stable global rules and a concise navigation map.
• Durable subsystem-specific rules are path-scoped and colocated with the relevant code areas.
• The detailed module inventory is no longer maintained as volatile always-loaded root instruction text.
• The chosen instruction precedence and multi-path resolution behavior are documented.
• Tool-specific guidance (CLAUDE.md, Copilot instructions, or equivalents) continues to defer consistently without duplicating canonical rules.
• Canonical validation/bootstrap commands and protected invariants remain immediately discoverable from the root.
• Tests or validation detect broken instruction links and stale generated module-map content where applicable.
• A small-task walkthrough demonstrates that only relevant scoped guidance is needed; a cross-cutting walkthrough demonstrates that all applicable guidance can still be found.
• No runtime behavior changes.

Risks and trade-offs

• Too many scoped files can increase navigation and create contradictory rules; use only durable subsystem boundaries.
• Generated maps can preserve factual freshness but cannot replace human architectural explanations.
• Some agent surfaces may resolve nested instructions differently; document and test the supported behavior before relying on it.

Related

• #753 — revisit the module-size ceiling and mechanical splits
• AGENTS.md
• docs/agent-context/invariants.md
• docs/agent-context/workflows.md
• .claude/CLAUDE.md
• .github/copilot-instructions.md

---

The objective is dual operability: less irrelevant global context for agents, while preserving clear human ownership, architectural intent, and deterministic validation.

Start by reading AGENTS.md, docs/agent-context/invariants.md, docs/agent-context/workflows.md, .claude/CLAUDE.md, and .github/copilot-instructions.md, then inventory their rules by scope and volatility. Define the precedence and path-scoped structure before moving durable guidance and the module map. Done means the acceptance criteria pass, including broken-link or drift validation, preserved commands and invariants, and the small-task and cross-cutting walkthroughs.