prime-silo: Instructions file for Codex

AGENTS

Documentation First

Documentation is the most important part of this project.

Treat every AGENTS.md file as part of the runtime contract, not as optional notes. Poor documentation causes agent behavior drift, architecture drift, and bad changes in the wrong layer.

This repository now uses a documentation hierarchy:

• /AGENTS.md owns repo-wide rules, documentation policy, and top-level architecture
• the five core docs are /AGENTS.md, /app/AGENTS.md, /server/AGENTS.md, /commands/AGENTS.md, and /packaging/AGENTS.md
• deeper AGENTS.md files inside app/ and server/ own the concrete implementation contracts for the module or subsystem in their subtree
• the closer the doc is to the code, the more technical and specific it should be
• the higher the doc is in the tree, the more it should focus on principles, ownership, stable contracts, and architecture

Always update the relevant docs in the same session as the code change:

• update the closest owning AGENTS.md for the files you changed
• reflect stable architecture, workflow, and agent-facing behavior changes into the supplemental docs under app/L0/_all/mod/_core/documentation/docs/
• update parent docs too when the higher-level contract, ownership boundary, architecture, or workflow changed
• keep higher-level docs abstract where appropriate and push implementation detail down into local docs
• keep lower-level docs concrete, explicit, and practical
• remove stale or contradictory documentation immediately
• keep README.md as the public product source of truth for the project pitch, quick starts, community links, release links, and the high-level documentation map
• do not let README.md become a competing implementation contract; durable architecture and workflow contracts belong in AGENTS.md, while broader agent-facing narrative docs belong in app/L0/_all/mod/_core/documentation/docs/

Documentation depth model:

• level 0 repo doc: mission, top-level architecture, cross-cutting rules, and the documentation policy for the whole tree
• level 1 core domain docs: app/, server/, commands/, and packaging/ architecture, plus the template for their immediate child docs
• level 2 subsystem or module docs: one major area, its owned files, its stable contracts, and the template for any deeper docs in that subtree
• level 3 leaf docs: one concrete surface, feature, view, or service contract with exact implementation guidance
• if a level 2 or level 3 doc later gains children, it stops being a leaf and must add its own Documentation Hierarchy section before those child docs land