Instruction Sources & Priority Hierarchy

System Instruction Assembly Order

When a session is configured, system instructions are assembled in a fixed order from first to last in the final prompt. Each layer adds context that shapes the model's behavior:

Base Instructions — Multi-Tier Folder Hierarchy

The Base Instructions layer (Layer 1 above) is loaded by JaatoRuntime._load_base_system_instructions() from a multi-tier .jaato/instructions/ folder hierarchy. The single legacy file .jaato/system_instructions.md is a fallback only, used when no folder exists in any tier.

Tiers are searched in the following precedence order; the first tier that provides a non-empty folder wins for the workspace/user layer:

Within each folder, all *.md files are sorted lexicographically by filename and concatenated with double-newline separators. Numeric prefixes (e.g. 00-, 10-, 15-) control ordering. README.md (matched exactly, case-insensitive) is skipped — it documents the folder layout and is not injected as instructions.

The combined base instructions form the BASE tier of the instruction budget, classified as LOCKED (instruction_budget.py:65): they appear first in every assembled prompt and are never garbage-collected, regardless of context pressure.

Suppressing or Overriding Base Instructions

A profile can opt out of the base instructions layer via the suppress_base_instructions field (config.py:949–960). When set to true, the .jaato/instructions/ base layer and the framework's always-on baseline are omitted from that session's prompt; plugin and persona instructions still apply.

Typical savings are 3–5 k tokens per turn — which can be the difference between fitting a small model's context window and triggering aggressive GC. It is intended for narrow, body-wired agents (echo specialists, single-purpose narrators) that derive no benefit from general-purpose guidance.

Inheritance uses OR semantics (config.py:1645–1657): once any ancestor in the profile inheritance chain sets suppress_base_instructions: true, it stays suppressed — a child profile cannot silently re-enable a parent's suppression. This is a security primitive: a minimalist base profile cannot be silently upgraded by an inheritor. A child that genuinely needs base instructions should not inherit from a minimalist parent.

The field also enables an override pattern: set suppress_base_instructions: true and supply an agent persona (.jaato/agents/<name>.md) that provides the complete replacement system instructions. This gives the persona full control over the prompt with no shared project-level baseline layered beneath it.

Agent Identity: Personas vs. system_instructions

The profile field system_instructions is deprecated (config.py:889) and emits a DeprecationWarning at runtime. Agent identity and role-specific instructions belong in a persona file under .jaato/agents/<name>.md, not in the profile.

The design separates concerns deliberately: the Profile (.jaato/profiles/<name>.yaml) holds runtime configuration only — model, provider, plugins, GC strategy, schemas. The Persona (.jaato/agents/<name>.md) holds agent identity: role, voice, domain knowledge, and lifecycle behaviour. When a session names an agent via --agent, the framework renders the persona Markdown and applies it as the session's system instructions, layered on top of the base-instruction folder.

Migrate any existing system_instructions: profile field content to a .jaato/agents/ persona file.

Token Budget Overview

The total instruction overhead depends on which plugins are enabled:

With JAATO_DEFERRED_TOOLS=true (the default), initial context is smaller because only core tools are loaded upfront. The model discovers other tools via introspection as needed.

Plugin Token Breakdown

Prompt Enrichment Pipeline

User prompts are processed through an enrichment pipeline before being sent to the model. Plugins subscribe to this pipeline and are called in priority order (lower numbers run first):

User Prompt → references(20) → template(40) → multimodal(60) → memory(80) → session(90) → Enriched Prompt

Each plugin receives the output of the previous plugin, enabling chained transformations. For example, the references plugin injects @file content, then the template plugin extracts embedded templates from that injected content.

Runtime Message Priority

During agent execution, messages between agents are queued with priority-based processing. High-priority messages (from PARENT, USER, SYSTEM) can interrupt the model mid-turn, while low-priority messages (from CHILD agents) are queued and processed when the agent becomes idle.