Directives

Binding rules every agent gets on every turn, written once and kept short.

Since v0.16.0, project directives are short rules. Shared rules live in a platform catalog and are referenced by projects instead of being copied; each project adds only the facts that hold for it alone. Every rule costs context in every request, so keep them few and short.

What directives are

A directive is one imperative sentence that an agent must follow without being asked: a lock, a notice duty, a build quirk, a commit convention. Directives apply to the whole project and to every agent working in it.

What does not belong in directives:

• Shared standards such as language, commit style or em-dashes: use the project settings or a catalog rule.
• Workflows: they are skills.
• Explanations and how-tos: they belong in knowledge base documents.

Sources

The effective directive list of a project is built from four sources:

On a project page, default and optional catalog rules are listed together as Nexus rules.

Rule and description

Each directive has two texts:

The editor shows a live character budget for both fields: amber at 90%, red past the limit, with the overflow highlighted in the rule editor.

Levels

level replaces the old priority field and has two values:

Within a category, rules are ordered by sort_order.

Categories

Categories are a fixed set:

Render budget and preview

Keep a project within 40 rules and about 600 words. The directives panel on the project page counts the enabled rules and their words against this budget and shows a What agents get preview: the exact list that will be rendered into the agent files, grouped by category.

Writing good rules

The directives panel has a slide-over guide ("How to write a good rule"). Its key points:

The rule

One imperative sentence: what to do or not do, and when. Name the concrete trigger; leave out the why.

The description

The description says why the rule exists. A few sentences, plus a link or reference for the background. Agents never see it.

• Good: names who is affected, which systems and environments the rule covers, and why the notice is needed.
• Avoid: a full runbook with commands, verification steps and incident history. Put it in a knowledge base document and link it.

Icon legend

The directives panel and the platform catalog open an icon legend from the right ("Icon legend" in the panel header, or a click on any level seal). It explains:

Level seals

The same seal component is used for the classification levels elsewhere in Nexus.

Source icons

Labels

Row actions

Platform catalog

Platform admins manage the catalog under Platform > Directives. Rule texts are written once there and used by every project that references them.

• Usage: each catalog rule shows how many projects get it.
• Versioning: editing a rule text bumps its version (v2, v3, ...). Projects receive the new text on their next nexus pull; nothing has to be changed per project.
• Kinds: mandatory (platform rules), flag (rendered by a project setting), default and optional.

What agents get

Only enabled rule texts are sent; descriptions, labels and seals stay in the UI. How the list reaches the agent depends on the runtime:

The CLAUDE.md bootstrap of Claude Code projects names the always-loaded rules file (and directives.md as its readable copy) instead of asking the agent to load directives.md, which Claude Code never loads on its own.

If the catalog, the project's rules or its settings cannot be read, Nexus answers with an error instead of exporting an incomplete list: af_export, pd_list, directive_export and the directives REST endpoint return 503 with the missing sources, and the agent files are not regenerated.

MCP tools

The pd_* tools work on the effective list. Since nexus-mcp v0.10.16:

• pd_list returns each entry with its source: mandatory, flag, template or project. Mandatory and flag rules cannot be edited with pd_update.
• title, body and priority are still accepted as deprecated aliases for rule, rationale and level.
• pd_create, pd_update and pd_toggle require a project admin or editor; pd_delete requires a project admin. Update, delete and toggle write audit entries.

{
  "tool": "pd_create",
  "arguments": {
    "rule": "Run database migrations only through the Makefile targets, never with ad hoc SQL.",
    "rationale": "Ad hoc SQL bypasses the migration log and the staging dry run.",
    "level": "must",
    "category": "operations"
  }
}

Migration from old directives

The v0.16.0 migration converted existing directives automatically:

• Texts that were copies of shared standards became project settings or catalog references.
• Remaining project facts were shortened into rules; the old text was kept as the description.
• Directives already covered by the core skills or the capability routing rule were removed.
• Model routing notes and similar background moved to the knowledge base.

This also fixed the alphabetical priority sort, the double inclusion in AGENTS.md and CLAUDE.md, and the always-zero priority in the runtime spec.