🤖 AGENTS.md

AGENTS.md is the repo-scoped contract an agent reads before touching code. Where a SKILL.md teaches a method, an AGENTS.md describes this repository — its systems, commands, conventions, and the files that matter. Deeper AGENTS.md files override higher ones.

1. 🧬 Anatomy

A good AGENTS.md answers four questions in order, so the agent never has to guess or grep blindly:

Section	Question answered	Why it matters
Overview + Architecture	What is this and how does data flow?	Orients the agent before it reads a single source file.
Key directories + Important files	Where do I look / edit?	Replaces wasteful exploration with exact paths.
Commands	How do I build, run, and test?	Stops the agent inventing commands that don’t exist.
Conventions + Testing	What style and gates must I honor?	Keeps changes consistent and verifiable.

2. 📐 Scope & dir-context

AGENTS.md is hierarchical. The root file covers the whole workspace; nested files refine rules for their subtree and take precedence on conflict.

/AGENTS.md                       # workspace-wide systems, commands, conventions
  pi-persistent-intelligence/AGENTS.md   # overrides for the memory engine subtree
  dev/vibesdk/tools/viban/AGENTS.md      # overrides for that tool

• 🧭 Place a nested file wherever a subtree has its own runtime, package manager, or test framework.
• ⚖️ A deeper rule wins; never restate parent rules — only the deltas.

3. 🧱 Skeleton

Annotated template — strip the # comments when authoring.

# Repository Guidelines
 
## Project Overview
 
# 1-paragraph map of the systems this repo integrates, numbered.
 
## Architecture & Data Flow
 
# Per-system bullets + a `text` flow diagram of the critical lifecycle.
 
## Key Directories
 
- `path/`: what lives here and which file is the entrypoint.
 
## Development Commands
 
| Project | Action             | Command         |
| :------ | :----------------- | :-------------- |
| ...     | Build / Test / Run | `exact command` |
 
## Code Conventions & Common Patterns
 
# Naming, async/resource rules, framework idioms — with short code examples.
 
## Important Files
 
- `path/to/entrypoint`: one-line role.
 
## Runtime / Tooling Preferences
 
# Pinned engines (Node >= 22, Bun, Python 3.11+) and package managers.
 
## Testing & QA
 
# Frameworks, test layout, and the pre-publish gate to run before shipping.

4. 🔧 Conventions

• 🎯 Exact paths, not prose. /home/dv/.omp/plugins/ompycord/bot.py: entrypoint beats “the bot file”.
• 🧮 Commands in a table. Project × Action × Command — the agent copies, never guesses.
• 🧵 Show the lifecycle. A text diagram of the request/event flow conveys more than paragraphs (see the event-lifecycle blocks in the root file).
• 🧪 State the gate. Name the exact pre-publish check (bun run typecheck && bun test, npm run check) so the agent self-verifies.
• 🪪 Examples over rules. A 6-line idiomatic snippet pins a convention harder than a sentence describing it.
• 🚫 No secrets. List env variable names and roles, never values.

5. 🔗 Related

• 📦 SKILL.md anatomy — method-teaching agent skills.
• 🔤 Ecosystem lingo — Rule, Profile, Domain Rule defined.
• 📄 llms.txt — LLM-readable site export.