feat(context): add GUIDELINES.md global prompt layer

[ryderstorm]

Load GUIDELINES.md from HERMES_HOME as a distinct global operating-guidelines
layer and inject it into system prompt assembly after the explicit system
message.

Add prompt-builder and run_agent coverage for loading, ordering, injection
blocking, truncation, and skip_context_files behavior.

Co-Authored-By: Hermes Agent no-reply@example.com

[teknium1]

Thanks for adding a scoped global-context layer and coverage.

Problems

• The active prompt assembly has moved: run_agent.py:3667-3670 now forwards to agent/system_prompt.py, and its context tier is assembled at agent/system_prompt.py:443-455. The PR’s run_agent.py integration therefore needs to be relocated during salvage.
• Proposed agent/prompt_builder.py:719 truncates without read_path. The helper falls back to the filename (agent/prompt_builder.py:1797), which would tell read_file to open a relative GUIDELINES.md, not the file under HERMES_HOME.

Suggested changes

• Wire the loader through agent/system_prompt.py, preserving the current run_agent patch seam.
• Pass read_path=str(guidelines_path) and cover the current system-prompt builder.
• Update website/docs/user-guide/features/context-files.md and consider hermes_cli/profiles.py:236-244 for profile export parity.

Automated hermes-sweeper review.

[teknium1]

Please pass read_path=str(guidelines_path) here. _truncate_content otherwise uses the filename as its recovery target, so a truncated global file would instruct read_file to open a relative GUIDELINES.md in the workspace rather than the HERMES_HOME file.

[ryderstorm]

Thanks for the review, @teknium1. You're right about both implementation issues. Prompt assembly moved to agent/system_prompt.py, and truncation needs the source's absolute read_path.

I have an alternate approach that addresses those points and updates the context-file docs. Before I port it onto current main and replace this draft, though, I want to check whether the narrower problem and design are a fit for Hermes.

I also read your decision on #1812. From that, I understand the current product model:

• SOUL.md is the Hermes-specific global surface for personality, environment, and persistent instructions.
• project AGENTS.md is working-directory context and should remain project-scoped.
• adding an implicit HERMES_HOME/AGENTS.md would blur that boundary and create two competing answers for global Hermes instructions.

I am not trying to reopen that implicit design or change project-context precedence.

The interoperability problem

On my machine, Hermes is my daily driver, but the additional coding harnesses I use—Codex, Claude, and others—consume the same user-level AGENTS.md. That file contains technical operating policy I want to apply across coding agents: tooling conventions, testing expectations, change-safety rules, validation behavior, and similar instructions.

Hermes does not consume that cross-harness file. To get the same technical policy into Hermes today, I have to copy it into SOUL.md and then maintain the same instructions in two places.

I treat the two authored sources differently:

• User-level AGENTS.md — shared technical operating policy for coding agents.
• Hermes SOUL.md — Hermes-specific identity, personality, communication stance, and personalization.

What I want to avoid is making SOUL.md the second copy of instructions whose source of truth is the cross-harness file.

Narrow proposal

The revised implementation uses one explicit, opt-in configuration value:

context:
  user_agents_path: ~/.config/agents/AGENTS.md

Its intended contract is deliberately small:

• no implicit HERMES_HOME/AGENTS.md convention;
• one configured file, not a generic list or include hierarchy;
• profile-scoped configuration, so profiles remain isolated;
• loaded under a distinct # User Context section after caller guidance and before project context;
• missing, blank, unreadable, or unset sources are a no-op;
• existing prompt-injection scanning and truncation are reused;
• project AGENTS.md discovery, first-match precedence, and progressive discovery are unchanged;
• SOUL.md remains the Hermes identity/personality source;
• no delegate inheritance, per-user gateway routing, UI editor, or automatic XDG discovery.

The default experience therefore keeps the existing single answer: global Hermes instructions go in SOUL.md. The additional path exists only for users who explicitly need to import a separately owned, cross-harness instruction source.

Related work and what it tells us

Related work	Approach	Outcome or critique	Relationship to this proposal
#1812 — global HERMES_HOME/AGENTS.md	Implicitly load a second global Hermes file before project context.	You closed this one with a clear product decision: SOUL.md already owns global personality, environment, and instructions, while AGENTS.md should remain project-scoped.	This is the blocking product precedent. The revised proposal avoids an implicit Hermes-home convention and frames the feature as an explicit interoperability import rather than a second canonical Hermes location.
#51490 — global RULES.md and #33143	Split global operational rules from identity using another fixed file.	Both closed; PR unmerged. The #51490 closure and the #33143 closure say the use case is already implemented through SOUL.md and that another loader duplicates the global path.	This confirms that merely renaming the second Hermes-owned file does not address the product objection. The proposed source is externally owned and shared with other harnesses.
#32395 — user instructions from ~/.agents/AGENTS.md	Request a vendor-neutral global AGENTS.md shared across agent harnesses.	Open feature request. It hard-codes one proposed location and has no accepted implementation.	This is the closest statement of the interoperability problem. Configuration avoids standardizing one filesystem convention for every user.
#23331 — additive HERMES_HOME/AGENTS.md	Load profile-home AGENTS.md independently alongside project context.	Open, labeled needs-decision. Automated review found duplicate injection when cwd equals HERMES_HOME and inaccurate delegate/cron claims; the branch later addressed both and received production-gateway confirmation.	It shows real demand and a viable additive layer, but still uses implicit file presence. Its open state is not evidence that maintainers have reversed the #1812 policy.
#11885 / #11763	Make gateway/project AGENTS.md resolve through HERMES_HOME.	Open; automated review kept it with low salvageability. The critique is that HERMES_HOME-first lookup suppresses the cwd project's AGENTS.md; it recommends a distinct global operational layer instead.	The revised proposal follows that separation while intentionally not claiming to fix gateway project-cwd discovery.
#66155	Fall back from cwd to profile AGENTS.md.	Open, labeled needs-decision. Automated review found that fallback still participates in the first-match project chain and recommended an additive global operational layer.	Supports separating user policy from project lookup, but does not settle whether another global surface is acceptable.
#65800 and #52580	Gateway/profile fallback or profile-first project lookup.	Open. Reviews found unintended desktop/cron scope, suppression of workspace instructions and missing precedence coverage, and an unresolved maintainer decision about the profile-wide instruction surface.	The revised proposal avoids platform gating and never changes the project loader's precedence.
#48809 — context.external_files	Configure an ordered list of external project-context files with deduplication and discovery controls.	Open; automated sweeper kept it salvageable. Review found a threat-scanner regression, incomplete .cursorrules/.mdc deduplication, and stale config-schema integration.	Closest config mechanism, but materially broader: multiple project files, labels, ignore_hermes_md, and generic composition. This proposal is one profile-scoped user-policy source in a separate section.
#53766 — global context files	A broad external-context system with config, setup/dashboard UI, manifests, restore behavior, and documentation.	Open; automated review requested consolidation with #48809 and one documented contract. The author later unified on context.external_files, but there is no subsequent maintainer acceptance.	Useful evidence that generic external context is a larger product area. The revised proposal intentionally does not import its UI, manifests, or multi-file abstraction.
#12255 — global HERMES/AGENTS/CLAUDE files	Unconditionally load three file types from HERMES_HOME.	Open; maintainer design decision unresolved. Review found duplicate loading when cwd equals home and no explicit precedence contract; cross-PR triage said #1812's rejection remains controlling absent a policy change.	Demonstrates why implicit multi-file loading is not the proposal here.
#72105 — document SOUL/profile scope	Clarify that automatic project AGENTS.md is cwd-scoped while SOUL.md follows the active profile.	Open docs PR. It reflects the current two-surface product model.	The revised docs would preserve that model and describe configured User Context as a third, explicitly opted-in import—not redefine automatic project AGENTS.md.

The automated reviews on #11885 and #66155 suggest that an additive layer is technically safer than changing project lookup. I also recognize that those are automated salvage recommendations, not a human reversal of your product decision on #1812.

Product-fit question

Would you consider this exact, explicit cross-harness import acceptable despite the decision on #1812?

Put differently: can Hermes support an advanced opt-in bridge to a user-owned instruction file without treating that file as another canonical Hermes global location?

If you think this fits the product, I will close this draft, port the implementation onto current main, and open a new PR with the updated approach. If this explicit bridge still conflicts with the intended role of SOUL.md, I will keep it as a local customization rather than spend your review time on the port.

Edit: If you agrees with the product direction, I would suggest that this closes #32395 with a scope note that:

• the path is explicitly configured rather than automatically discovered;
• project context is unchanged;
• Hermes delegate inheritance is not included.

[ryderstorm]

Also - thank you so much for Hermes! It would be an understatement to say that it has revolutionized the way I work with AI.