Objective: You are to format and maintain .claude directories within this repository. These directories act as the authoritative, agent-readable context layer. Regardless of whether a .claude directory sits at the repository root or deep within a subdirectory, it must strictly adhere to the following structural and conceptual guidelines. 1. The Standardized Directory Tree Every .claude directory must follow this exact structure to ensure predictable crawling: Plaintext .claude/ ├── CLAUDE.md # The primary landing page and index ├── concepts/ # Complex logic, state flows, and historical context └── skills/ # Executable agent tasks, scripts, and workflows 2. The Entry Point: CLAUDE.md This is the root node for the agent's context in this directory. It must contain: Purpose: A one-sentence declaration of what the parent directory does. Subdirectory Architecture (Diagram): A high-level Mermaid.js diagram mapping all subdirectories and their intents. Context Pointers: Explicit links to the skills/ and concepts/ relevant to this directory. Your overarching goal is to structure this document in a way where a future developer can read this document, and immediately know where to find and, crucially, how to contribute structured code that matches our intended patterns, anywhere in this directory. This should be the ultimate 0->1. 3. Bidirectional Referencing .claude directories are not isolated silos; they are nodes in a graph. Upward/Downward Linking: A subdirectory's CLAUDE.md must link back to its parent's .claude/CLAUDE.md. Lateral Linking: If a backend service relies on a shared library, the backend's .claude must explicitly link to the shared library's .claude. Format: Always use relative markdown links (e.g., For database schemas, see [Root DB Context](../../.claude/CLAUDE.md)). 4. Structuring Skills (/skills/) The skills/ directory holds operational instructions. These are the "how-tos" for the agent. Each markdown file here should represent a discrete workflow and contain: Trigger: When should the agent use this skill? (e.g., "Run this when updating the Lane Processing pipeline.") Prerequisites: What context or files must be read first? Execution Steps: Numbered, concrete commands or code modification patterns. Verification: How the agent can test that the skill was executed successfully. 5. Storing Conceptual Flows (/concepts/) The concepts/ directory is the memory bank for "why" the system works the way it does. It is the mandatory home for complex state machines, race conditions, edge cases, and architectural invariants. Rule for Conceptual Flows: When documenting a complex flow, always include: The Goal/Invariant: What must remain true. The Anti-Pattern/Trap: Historical bugs or naive implementations that break the invariant. Visual Trace: A diagram mapping the entities. Chronological Trace: A step-by-step text breakdown of the state transitions.