Repository instructions

Repository instructions

Holaryn resolves repository guidance for the file or directory a coding tool will touch. Guidance is
untrusted project data: it can specify conventions and validation, but it cannot change system
safety, approval policy, sandbox roots, or execute hooks.

Compatible files and nested scope

Holaryn reads these files, in order, from the workspace root through the target's parent directory:

1. .holaryn/instructions.md
2. AGENTS.md
3. CLAUDE.md

Root files remain fully compatible. A nested file applies only below its own directory; sibling
instructions are excluded. Multiple targets share each source once, with the applicable targets
listed in its evidence.

Optional frontmatter

Instruction files may start with a small, data-only YAML-compatible block:

---
applies_to: ["src/*.py", "tests/*.py"]
excludes:
  - src/generated/*
priority: 20
mode: append
required_validation:
  - uv run pytest
---
Use full type hints.

applies_to and excludes match paths relative to that instruction file's directory. priority
runs from -1000 through 1000; higher values have later precedence. mode is append (default) or
replace; replace supersedes earlier files at the same directory only. required_validation is
shown to the model and operator but never executed as a hook. Values may be a string, JSON string
array, or dash list. Unknown keys are diagnosed and ignored; malformed frontmatter stays ordinary
instruction content for compatibility.

Precedence, refresh, and containment

Order is operator-global before workspace, shallow before deep, low priority before high priority,
then the compatible filename order. Conflicting replacements use this deterministic order and are
flagged.

Every resolution reads the current filesystem and hashes its sources. Edits, renames, branch or
worktree changes, moved targets, and changed target sets therefore create a new snapshot. Combined
model context is bounded to 24,000 characters and reports truncation.

Canonical target resolution never crosses the workspace root. Targets outside it are rejected, and
instruction symlinks that resolve outside it are ignored with a diagnostic. Instructions from a
different root cannot leak into the session.

When the agent sees guidance

Root guidance enters the coding session preamble. Immediately before file/directory reads, writes,
edits, searches, or shell commands, Holaryn resolves the call's target again. Newly applicable
guidance prefixes the first read result. Before the first consequential call for a new snapshot,
Holaryn takes no action: it returns the guidance to the model, which may retry the exact call. Approval
and sandbox gates remain unchanged.

Inspect the exact result

In the Code tab, choose Files. The Repository instructions disclosure follows the open file,
or the workspace root if no file is open. It shows sources, scope, hashes, precedence, validation,
truncation, conflicts, diagnostics, and exact content.

The local read-only CLI provides the same evidence:

holaryn instructions D:\projects\example src\app.py
holaryn instructions D:\projects\example src\app.py --json