Overview

Add support for .hermes.md (or HERMES.md) project configuration files that define per-repository rules, conventions, and context for the agent — similar to CLAUDE.md in Claude Code, .cursorrules in Cursor, and .windsurfrules in Windsurf.

When the agent starts a session in a project directory, it discovers and loads these files, injecting their contents into the system prompt as "Project Context." This eliminates the need to re-explain project conventions every session and makes the agent immediately project-aware.

This was the #1 most universal UX pattern across 30+ AI agent interfaces studied. Every major competitor has it. Hermes currently has NO per-project configuration.

Split from #502 for atomicity. The companion feature (@ context references) is tracked in #506.

Research Findings

How Competitors Do It

Claude Code (CLAUDE.md) — The gold standard:

• CLAUDE.md at repo root acts as a "constitution" for the agent
• Can contain: code style rules, testing conventions, deployment procedures, file organization docs
• Nested CLAUDE.md files in subdirectories for scoped rules
• Automatically loaded when agent opens a project
• Can reference other files

Cursor (.cursorrules) — Similar concept:

• JSON or markdown file with project-specific instructions
• Prepended to system prompt
• Community-maintained collections of rules for different frameworks (cursor.directory)

Windsurf (.windsurfrules) — Same pattern, different name.

Key insight: Project config files are "persistent context that lives with the code." They're shared across team members via version control and survive across sessions automatically.

Current State in Hermes Agent

What we already have (close but not quite):

• prompt_builder.py build_context_files_prompt() (line 288) already auto-discovers SOUL.md, AGENTS.md, and .cursorrules at startup and injects them into the system prompt
• Global ~/.hermes/config.yaml for agent-wide configuration
• MEMORY.md / USER.md for persistent context (global, not project-scoped)
• Skills with reference files for per-skill context

The gap: No .hermes.md discovery, no nested config merging, no project-scoped rules. The existing build_context_files_prompt() is the natural extension point.

Implementation Plan

Skill vs. Tool Classification

This should be a core codebase change — a modification to prompt_builder.py and potentially cli.py/gateway/run.py for the /project command. It requires deterministic config file discovery and system prompt injection, which must happen reliably every session.

What We'd Need

1. Config file discovery logic (scan CWD → git root for .hermes.md / HERMES.md)
2. System prompt injection (extend build_context_files_prompt())
3. Optional YAML frontmatter parser for structured config
4. /project slash command to view/reload active project config
5. .hermesignore support for files/dirs the agent should never touch

Detailed Specification

Discovery order (first found wins, or merge all):

1. .hermes.md in CWD
2. HERMES.md in CWD
3. Walk parent directories up to git root (or filesystem root)
4. Nested: subdirectory configs extend/override parent configs

File format:

---
# Optional YAML frontmatter for structured config
model: claude-sonnet-4-20250514
personality: technical
tools:
  disabled: [image_generate, text_to_speech]
---

# Project: MyApp

## Code Style
- Use TypeScript with strict mode
- Prefer functional components with hooks
- All API calls go through the `api/` module

## Testing
- Run tests with `npm test`
- Integration tests require `docker compose up -d` first
- Minimum 80% coverage for new code

## Architecture
- Frontend: React + Next.js in `web/`
- Backend: FastAPI in `api/`  
- Database: PostgreSQL with Alembic migrations in `db/`

## Deployment
- Staging: `make deploy-staging`
- Production requires PR approval from @tech-lead

Injection into system prompt:

══════════════════════════════════════════════
PROJECT CONTEXT (from .hermes.md)
══════════════════════════════════════════════
[contents of .hermes.md, frontmatter parsed and applied]

.hermesignore (same syntax as .gitignore):

# Files the agent should never read or modify
.env
secrets/
*.key
node_modules/

Deliverables

• .hermes.md / HERMES.md file discovery in prompt_builder.py
• System prompt injection with clear section header
• YAML frontmatter parsing for structured config (model, personality, tools)
• Parent directory walking up to git root
• /project command: show active config, reload on demand
• .hermesignore file parsing and integration with file tools
• Documentation: what goes in .hermes.md, example configs
• Tests for discovery, parsing, injection, edge cases

Pros & Cons

Pros

• Highest impact-to-effort ratio of any proposed UX improvement
• Eliminates repetitive re-explanation of project conventions
• Lives in version control — shared across team members automatically
• Builds on existing build_context_files_prompt() infrastructure
• Community can share configs (like cursor.directory)
• Small, focused, shippable in days

Cons / Risks

• Config could contain sensitive info (API keys) — need to warn about committing secrets
• Frontmatter parsing adds complexity (model/tool overrides need validation)
• Token cost: large .hermes.md files consume context window space
• Need to handle conflicts between .hermes.md settings and user's global config
• Discovery walking could be slow in deep directory trees (mitigate: stop at git root)

Open Questions

• Should frontmatter config (model, tools, personality) override or merge with global config.yaml?
• Should we support a .hermes/ directory with multiple config files, or keep it to a single .hermes.md?
• Maximum file size before warning? (Suggest: warn at >2KB, refuse at >10KB)
• Should the agent auto-generate a starter .hermes.md when it detects an unconfigured project?

References

• CLAUDE.md docs — Anthropic's project config spec
• cursor.directory — Community-maintained .cursorrules collection
• Existing code: prompt_builder.py:288 build_context_files_prompt() — the extension point
• Existing code: prompt_builder.py auto-discovers SOUL.md, AGENTS.md, .cursorrules
• Supersedes Phase 1 of closed Feature: Project Context System — @ References, .hermes.md Config Files & Workspace Awareness #502
• Related: Feature: PAHF Personalization Loop — Pre-Action Clarification, Preference Grounding & Post-Action Feedback Integration #362 (PAHF Personalization — user-level rules), Feature: Agent Mode System — Persona + Tool Scoping + Behavioral Constraints (inspired by Kilocode) #476/Feature: Switchable Agent Modes — Named Profiles with Tool Restrictions, Personas & Per-Project Config (inspired by Roo Code) #482 (Agent Modes — .hermes.md could set default mode)