AGENTS.md PR Draft — claude-code #6235

ISSUE ANALYSIS — WHAT THE COMMUNITY IS ASKING

COMMUNITY REQUEST

The issue has 294 comments and growing. The community wants claude-code to load an AGENTS.md file from the workspace root — similar to how Cursor loads .cursorrules, or how OpenAI's Codex loads system context.

Key themes from the thread:

Agent personality / tone configuration
Project-specific rules and constraints
Tool policy overrides per workspace
Human/user context injection
Memory and continuity across sessions
Skill/plugin loading configuration

EOSE POSITION

        We don't need to speculate. OpenClaw has been running this pattern in production for 2+ months across a 7-silo fleet. Every feature the community is asking for — we have it working.
        
        Our contribution is the reference implementation: proven file structure, proven loading protocol, proven context injection pattern.
        
        We're not proposing a design. We're contributing the design we already built, tested, and run in production daily.

OUR IMPLEMENTATION — AGENTS.MD WORKSPACE STRUCTURE

OPENCLAW WORKSPACE FILE HIERARCHY — ANIMATED · PRODUCTION LAYOUT

AGENTS.MD — ACTUAL PRODUCTION FILE

OPENCLAW WORKSPACE / AGENTS.MD (EXCERPT — CONTRIBUTING THE PATTERN, NOT THE CODE)

# AGENTS.md - Your Workspace
#
# Loaded by OpenClaw on session init. Defines agent config,
# rules, memory protocol, skill loading, and group chat behavior.

## Session Startup

Before doing anything else:

1. Read `SOUL.md`    — this is who you are (personality, tone)
2. Read `USER.md`    — this is who you're helping (human context)
3. Read `memory/YYYY-MM-DD.md` (today + yesterday) for recent context
4. If in MAIN SESSION: Also read `MEMORY.md`

## Memory Protocol
# Daily notes: memory/YYYY-MM-DD.md
# Long-term: MEMORY.md — curated, main session only
# Subagent isolation: MEMORY.md NOT loaded in spawned subagents (security)

## Red Lines
# Tool policy overrides — workspace-specific constraints
# msi01 is production. Never test on msi01.
# Never change model routing without explicit approval.

## Skills
# Skill loading from ~/.openclaw/skills/ or workspace skills/
# Each skill has SKILL.md with instructions + references/
    

PR SCOPE — WHAT CLAUDE-CODE NEEDS TO ADD

COMPONENT	WHAT TO ADD	NOTES	EFFORT
File Loader	Locate AGENTS.md: workspace root → git root → home dir (priority order). Parse markdown sections.	Similar to .gitignore lookup. Fail gracefully if not found.	S
SOUL.md Injection	Load SOUL.md if referenced in AGENTS.md. Inject as personality prefix in system prompt.	Optional file. Skip if absent. Max size limit recommended.	S
USER.md Injection	Load USER.md if referenced. Inject as human context into session context (not system prompt).	Keep separate from system prompt for clarity. Structured metadata.	S
Crew Config	Parse AGENTS.md sections for tool policy (allowlist/denylist), skill loading, red lines.	Tool policy overrides current defaults. Skills = additional SKILL.md files to load.	M
Memory Protocol	Load MEMORY.md in main session. Exclude from subagent spawns. Load memory/YYYY-MM-DD.md for recency.	Security-critical: subagent isolation prevents personal context leaking to group contexts.	M
HEARTBEAT.md	Load on session init as proactive task checklist. Surface in session context.	Optional. Enables scheduled/proactive behavior without hardcoded prompts.	S
Skill Loading	Load SKILL.md files from paths listed in AGENTS.md skills/ section.	Each skill = set of instructions + references. Dynamic capability extension.	M
Hot-reload (optional)	Watch AGENTS.md for changes. Re-apply updated config without session restart.	Nice-to-have. Can be v2. Flag: --watch-agents-md	L

REFERENCE IMPLEMENTATION — OPENCLAW 2+ MONTHS PRODUCTION

PRODUCTION METRICS

Deployment: 7-silo fleet
msi01 · msclo · forge · yone · lilo · pcdev · cloud

Runtime: 2+ months continuous

Sessions per day: 50–200+ across fleet

Files loaded per session:
AGENTS.md + SOUL.md + USER.md + MEMORY.md
+ memory/YYYY-MM-DD.md + TOOLS.md + HEARTBEAT.md

Skill count: 15+ production skills
discord · github · weather · healthcheck · tmux
gh-issues · taskflow · skill-creator · node-connect · ...

Subagent isolation: Working ✅
MEMORY.md excluded from all spawned subagents

WHY OPENCLAW IS THE REFERENCE

The community has been debating the AGENTS.md spec for months. We ended the debate by building it.

Every design decision in our implementation came from production pain:

SOUL.md separate from AGENTS.md — personality should be evolvable without changing rules
USER.md separate — human context is structured differently from agent config
Memory isolation — learned the hard way: personal context in group chats = bad
Skill loading protocol — 15+ skills taught us what works
Daily memory files — session continuity across restarts

We're not guessing. We're contributing the design we proved works.

SAMPLE PR DESCRIPTION (DRAFT)

## AGENTS.md: Agent Workspace Configuration Support

Closes #6235

### Summary
Adds support for AGENTS.md workspace configuration files.
When claude-code starts, it looks for AGENTS.md in:
  1. Current working directory
  2. Git repository root
  3. User home directory (~/.claude/AGENTS.md)

### File Structure Supported
AGENTS.md may reference companion files:
  - SOUL.md: Agent personality and tone (injected into system prompt)
  - USER.md: Human context (name, timezone, preferences)
  - MEMORY.md: Long-term curated memory (main session only)
  - HEARTBEAT.md: Proactive task checklist
  - TOOLS.md: Infrastructure-specific notes
  - skills/: Directory of SKILL.md files for capability extension

### Security
  - MEMORY.md is NOT loaded in subagent spawns (personal context isolation)
  - File size limits enforced per companion file
  - Graceful degradation: all companion files are optional

### Reference Implementation
This pattern has been running in production at EOSE Labs Inc.
for 2+ months across a 7-silo fleet. Contributed under EOSE Labs Inc.
entity. IP review completed. Pattern contributed; implementation retained.

Contribution of Interest (COI) filed: 2026-05-10
CLO: Harvey (cleared) · GC: Amani Joffe (sign-off required before submit)
    

IP NOTE — WHAT WE CONTRIBUTE vs WHAT WE RETAIN

⚖ INTELLECTUAL PROPERTY — CONTRIBUTION BOUNDARY

CONTRIBUTED ✅ SAFE TO FILE — The AGENTS.md file structure specification. The companion file protocol (SOUL.md, USER.md, MEMORY.md pattern). The loading priority order (workspace → git root → home). The subagent isolation rule. The skill loading interface. All of these are patterns, not code.

RETAINED 🔒 NOT IN PR — OpenClaw source code. The memory search system (memory_search, memory_get tools). The heartbeat scheduling implementation. The fleet orchestration layer. The PEMCLAU GraphRAG integration. The skill implementations (discord, github, etc.). All EOSE Labs Inc. proprietary tooling.

STRATEGY We contribute the specification and a minimal example. The implementation in claude-code is theirs to write. Our production system remains proprietary. This is the standard open-source contribution model for reference implementations.

COI FILED COI-2026-05-10-001 · EOSE Labs Inc. · anthropics/claude-code #6235 · Harvey (CLO lead) reviewed 2026-05-10

CLO + GC SIGN-OFF

CLO LEAD

HARVEY

✅ CLEARED

All 5 COI targets reviewed. IP boundary defined. Pattern contribution approved. PR drafting authorized. No OpenClaw code in any filing.

GENERAL COUNSEL

AMANI JOFFE

⏳ W4 SIGN-OFF

GC sign-off required before submit (Week 4). Currently: draft + review phases. Also GC: Scarborough Transit Connect (~$10B SSE subway project).

CONTRIBUTING ENTITY

EOSE LABS INC.

✅ ACTIVE

Incorporated 2026-03-29. Ontario, Canada. All contributions filed under this entity. COI documented per issue before PR submission.