Instruction Files

Auto-generated, structured documentation that agents actually read.

Every package in your repo has implicit rules — the conventions you follow, the patterns you've rejected, the gotchas a new contributor would step on. Most of that lives in your head, some lives in scattered README files, and almost none of it makes it into an agent's context window when it matters.

Instruction Files solve this at the package level. The local runtime scans each package in your mounted repos, parses the AST, identifies entry points and public interfaces, and generates a structured markdown file that describes what the package does, how it's organized, and the conventions it follows. These files live alongside your code, version with your code, and get fed to every agent that touches that package.

The format is deliberately boring — headings, bullets, code references. It's designed to be read by both humans and language models, edited by both, and useful in both contexts. When the agent needs to refactor auth/session.py, it reads auth/INSTRUCTIONS.md first. When you onboard a contributor, they read the same file.

Generation is incremental. Add a new module, the instruction file updates. Rename a function, the references update. Reject a generated suggestion, the file learns to flag that pattern next time. This is the layer that turns one-shot AI suggestions into something that respects what you've already built.

You can edit instruction files directly. Anything you write by hand is preserved across regenerations. The runtime treats your edits as ground truth and refits the generated sections around them.

This is the upstream input for the RAG Index, the Memory Engine, and every agent you run. Get the instruction files right and everything downstream improves.