LLM Instructions

These apply in every session, with no exceptions:

• UNIX line endings — all new files use LF, never CRLF.
• New org docs via compass only — never write .org frontmatter by hand. Always use ./projects/ores.compass/compass.sh add <type>. See How do I create a new doc?.
• Check recipes first — before searching for how to do anything, open Recipes and find the matching topic.
• Every new .org file is scaffolded via compass add — this ensures correct frontmatter (:ID:, #+type:, #+description:, etc.).
• Pull requests via compass only — never open one unless the user asks in that turn. Raise, merge, check and record it with compass pr create, compass pr merge, compass pr checks and compass pr record, never with gh pr. gh may only read what compass does not cover. The raw verbs skip the title check, the fixed body, the Traceability table and the guard rails. See How do I create a PR?.

Read these first on a new contact:

• Compass — top-level map of doc/; the entry point.
• Orientation — navigation guide by reader intent.
• Glossary — definitions for task, story, sprint, version, function, recipe.
• Agile — current version and sprint at a glance.

• CMake setup — preset names, output layout, build types.
• How do I set up a development environment? — fresh-install bootstrap.
• How do I configure the project? — cmake --preset step.
• How do I build the system? — day-to-day build command.
• How do I run the tests? — cmake --build ... --target rat.

• Code review checklist — naming (snake_case, include order), include order, comment quality, platform isolation, and all review categories.

• System model — four-layer architecture and component inventory.
• Codegen patterns: choosing a model shape — read this before authoring or changing any model, and pick one pattern from the library.
• Knowledge — cross-cutting reference: entity patterns, SQL schema, presentation patterns, CLI/shell patterns, unit-test conventions.

• Document types — frontmatter contract.
• How do I validate component documentation before committing? — validate_docs.sh before every push that touches modeling/.

• ores.sql — component overview; the strict service-table isolation invariant lives under "Service Table Isolation" in this doc.
• Rule: each service user holds DML only on its own ores_<service>_* tables. Do not add cross-service grants without documented justification. Trigger functions that SELECT across services must be SECURITY DEFINER SET search_path = public, pg_temp.

• Unit Test Writer Skill — Catch2 conventions, file structure, naming, table-driven patterns.
• How do I run the tests? — test command.

• How do I create a PR? — title format ([COMPONENT] Description), body structure, and the no-test-plan rule.
• How do I generate a PR summary? — assemble the body before compass pr create.

• Claude Code Settings — the literate source for .claude/settings.json. Lists every permission entry with its security rationale and the concrete command variations it covers. Edit this file (not the JSON) to add or remove permissions; regenerate with How do I deploy the settings?.
• How do I deploy all org-mode artefacts? — the deploy_org (dorg) target rebuilds site, skills, settings, and diagrams in one shot.

• Project memory — catalogue of session-feedback memories; read and write here to persist durable facts across conversations.
• compass-doc-add-memory skill — LLM-side procedure for adding memories.

Non-negotiable: all memories go in doc/llm/memory/ via compass add memory. Never write to the Claude Code harness memory system (~/.claude/projects/*/memory/) — it is disabled via autoMemoryEnabled: false in .claude/settings.json and its files are not version-controlled or reviewed.

• Execution model — how LLMs and agents operate within the cybernetic information architecture during a sprint.
• Recipes — full index of operational how-tos by topic.