Agent Instructions Plugin

The Agent Instructions plugin folds two kinds of extra prose into the agent's
prompt:

1. Operator custom_instructions — global directives set via prompt.custom_instructions. Always injected when set.
2. Repo-local instruction files — AGENTS.md, CLAUDE.md, .clinerules, .cursorrules, .cursor/rules, .github/copilot-instructions.md, and anything else you list — discovered in the repositories under analysis. Opt-in; off by default.

It is a builtin, not a config-listed plugin. Do not add it to
plugins:. Override behaviour with a top-level agent_instructions:
section. Listing it under plugins: would skip custom_instructions on
any deployment that forgot the entry.

Repo-local discovery is off by default so existing deployments keep their
current prompt: custom_instructions still apply, and a repository's own
CLAUDE.md is not mixed in until you enable it.

Which files are scanned

When repo_local_enabled: true, files are collected in this order (later
entries sit closer to the user message and take higher authority):

1. Global (if include_global) — ~/.codumentor/<file> and <config_file_dir>/<file>.
2. Project — <repo_root>/<file>. Each name may be a file or a directory of files (for example .clinerules/ or .cursor/rules/); directory contents are concatenated in name order.
3. Nested (if recursive) — <repo_root>/**/<file>, bounded by max_depth and max_nested_files. Skips .git, node_modules, .venv / venv, __pycache__, dist, build, VCS metadata, and hidden directories.

Binary-looking files (NUL bytes) are skipped. Each file is truncated to
per_file_max_bytes. A total_max_bytes ceiling caps the aggregate; leftover
files are dropped with a visible
[N more instruction file(s) omitted — total budget of … bytes reached]
notice — never a silent truncation.

Repo-provided guidance is labeled as subordinate to the agent's core
operating instructions when the two conflict.

@path imports (Claude Code CLAUDE.md style) are off by default
(resolve_imports). When on, imports that leave the repo, form a cycle, or
exceed max_import_depth are replaced with a visible [import skipped: …]
notice.

Configuration

Override under a top-level agent_instructions: section (builtin — do not
add it to plugins:). Set the prose itself under prompt.custom_instructions:

prompt:
  custom_instructions:
    - "Always answer in the user's language."

agent_instructions:
  enabled: true              # master switch (custom_instructions + repo-local)
  repo_local_enabled: false  # scan repos for CLAUDE.md / AGENTS.md / … (default off)
  filenames:
    - AGENTS.md
    - CLAUDE.md
    - .clinerules
    - .cursorrules
    - .cursor/rules
    - .github/copilot-instructions.md
  include_global: false      # also ~/.codumentor/<file> + config_file_dir/<file>
  recursive: false           # scan <repo>/**/<file>
  max_depth: 3
  max_nested_files: 20
  per_file_max_bytes: 32000
  total_max_bytes: 96000
  reread: mtime              # mtime | always | once
  resolve_imports: false     # @path includes
  max_import_depth: 5
  target_agents: all         # main | subagent | all

Parameters

• enabled (optional): Master switch. When false, nothing is injected — neither custom_instructions nor repo-local files (default: true)
• repo_local_enabled (optional): Discover and inject repo-local instruction files. custom_instructions is unaffected (default: false)
• filenames (optional): File or directory names to look for at each repo root, in injection order (lower authority first). Defaults to the list above.
• include_global (optional): Also look in ~/.codumentor/<file> and <config_file_dir>/<file> (default: false)
• recursive (optional): Scan <repo>/**/<file> for nested instruction files (default: false)
• max_depth (optional): Max directory depth for the recursive scan (default: 3)
• max_nested_files (optional): Max nested files collected per repo (default: 20)
• per_file_max_bytes (optional): Per-file truncation budget (default: 32000)
• total_max_bytes (optional): Hard ceiling across all files per turn; overflow is dropped with a visible notice (default: 96000)
• reread (optional): When to re-read files from disk — "mtime" (when the file changes), "always" (every turn), or "once" (once per process) (default: "mtime")
• resolve_imports (optional): Resolve @path imports (default: false)
• max_import_depth (optional): Max import recursion depth (default: 5)
• target_agents (optional): Which agents receive the instructions — "main", "subagent", or "all" (default: "all", matching historical custom_instructions behaviour)

Notes

• Prompt assembly never fails because of this plugin: on error it injects nothing and the turn continues.
• If a deployment ships a custom prompt template that still embeds <additional-instructions> itself, custom_instructions would appear twice.
• Repo-local discovery reads repository content into the prompt, so it is off by default and left to the operator to enable per deployment.