Core File Architecture
The canonical workspace files — AGENTS.md, SOUL.md, TOOLS.md, IDENTITY.md, USER.md — are the agent's operating system. How you structure them determines what the model actually pays attention to, what gets truncated away, and whether rules are followed or ignored.
This section covers file architecture patterns: what belongs where, how to write instructions the model reliably follows, and when to use prose vs. structured data vs. tables.
Key Problems
Unclear ownership between files
SOUL.md has "Lessons Learned" that overlap with AGENTS.md's standing orders. IDENTITY.md has context that could live in USER.md. When ownership is unclear, rules accumulate in multiple places and diverge over time.
Instruction compliance varies by format
Not all instruction formats are equal. The model's attention to a rule depends on where it appears in the file (primacy/recency bias), how it's formatted (headers vs. inline), and whether it's stated as a positive instruction or a negative constraint.
Personality vs. operations tension
SOUL.md defines voice and personality. AGENTS.md defines operational rules. But personality is operational — "be concise in Telegram" is both a behavioral preference and an operational rule. The boundary between the two files is inherently fuzzy.
Template bloat
Daily note templates, post-mortem templates, WIP checkpoint formats — all injected on every call even though they're only used occasionally. Templates are reference material, not always-needed context.
Key Findings
- Instruction ordering matters — primacy and recency bias means the top and bottom of files get more attention than the middle
- Truncation is worse than attention decay — content in the attention trough gets less weight, but truncated content is literally invisible
- Deduplication across files prevents drift where three versions of the same rule diverge over time
Tracks
- File architecture patterns — what belongs in each file, ownership boundaries
- Instruction format experiments — prose vs. lists vs. tables vs. structured data
- Compliance measurement — which rules get followed, which get ignored, and why
Status
Overlap identified, restructure needed. Auditing bootstrap files typically reveals specific redundancies and ownership conflicts. Restructuring requires careful sequencing — changes affect every session.