Date: 2026-09-11 Date: 2026-09-10

​
NOVA.md and project rules

Use this lesson to build a practical, evidence-based Nova workflow for this topic.

​
Purpose

NOVA.md gives Nova durable instructions about how to work in a project. It is the right place for conventions that should apply across sessions: required verification commands, architecture boundaries, language standards, generated-file policies, security constraints, and release rules. It should describe how the repository is meant to be worked on, not duplicate information Nova can discover cheaply from package manifests or repository inspection.

​
Instruction discovery order

Kore-CLI loads project instructions in this order, highest priority first:
  1. <projectRoot>/NOVA.local.md
  2. <projectRoot>/.compass/rules/*.md, sorted alphabetically
  3. <projectRoot>/NOVA.md
  4. <projectRoot>/.compass/NOVA.md
  5. ~/.compass/NOVA.md
All non-empty files found are concatenated into the instruction context. Higher-authority system and organisation policy still takes precedence over every project file.

​
Choosing a location

Use each location deliberately:
  • NOVA.md — team-shared repository instructions, normally committed to version control.
  • NOVA.local.md — developer-specific project instructions, normally excluded from version control.
  • .compass/rules/*.md — modular project rules split by concern, such as testing, frontend, database, or security.
  • .compass/NOVA.md — project instructions kept with other Compass configuration.
  • ~/.compass/NOVA.md — personal defaults that apply across projects.
Keep a single rule in the narrowest sensible scope. Do not repeat it in every layer.

​
What belongs in project instructions

Useful examples include:
  • The supported operating systems and shell syntax.
  • The package manager and commands for install, lint, type checking, tests, and builds.
  • Which generated files must never be edited manually.
  • Architectural boundaries and dependency direction.
  • Error-handling, validation, accessibility, and security requirements.
  • Commit or branch conventions specific to the team.
  • Deployment targets and approval requirements, without credentials.
  • Instructions for protecting uncommitted user work.
Write observable rules:
This is stronger than “test your work” because it names the expected evidence.

​
What does not belong

Avoid:
  • API keys, passwords, tokens, private certificates, or connection strings.
  • Long implementation explanations that will drift out of date.
  • Temporary task status or one-off debugging notes.
  • Raw logs and command output.
  • Rules that conflict with organisation policy.
  • Vague preferences such as “write clean code”.
  • A catalogue of every file in the repository.
Use session notes, issue trackers, plans, or explicit memory for information that is not an enduring work rule.

​
Write concise, testable instructions

A good instruction states the condition and required action:
If exceptions exist, document them. Contradictory rules force the model to guess which convention the team intended.

​
Modular rules

Use .compass/rules when one root file becomes difficult to scan:
Files are sorted alphabetically, so numeric prefixes can make the loading order explicit. Modularisation should reduce cognitive load, not duplicate the same requirements across several files.

​
Local overrides

NOVA.local.md has the highest project-file priority and is suitable for local paths, machine-specific commands, or personal workflow details. Keep it out of Git if it contains environment-specific information. It still must not contain secrets.

​
Maintaining the file

Review instructions when tooling, architecture, or team policy changes. Remove rules that are obsolete or already enforced automatically. A short, accurate NOVA.md is more effective than a large historical document with conflicting guidance. After editing instructions, start a fresh session or ensure Nova reloads the changed context before relying on the new rule.

​
What you learned

You can now apply the core practices in this lesson during a Nova session.

​
Try it yourself

Use this lesson’s guidance in a small, non-destructive task in a local project, then review the result before continuing.

​
Continue the course