| name | agents-md |
| description | Use when creating, editing, restructuring, or reviewing AGENTS.md files or the CLAUDE.md symlink. Covers Pawrrtal's two-tier layout, what belongs in AGENTS.md vs memory vs skills, and line budgets. |
AGENTS.md authoring
Two-tier layout
| File | Role |
|---|
Root AGENTS.md | Stub (~10 lines) → points to .agent/AGENTS.md |
.agent/AGENTS.md | Entry contract — bootstrap, non-negotiables, memory map |
CLAUDE.md | Symlink to root stub |
Nested AGENTS.md | Package-local overrides |
What goes where
| Surface | Holds |
|---|
.agent/AGENTS.md | Read order, hard safety lines, where depth lives, brain map |
memory/personal/PREFERENCES.md | How the user works — taste, workflow, multi-agent |
memory/semantic/DOMAIN_KNOWLEDGE.md | Stable facts — ports, commands, structure, auth |
memory/semantic/LESSONS.md | Graduated lessons (learn.py / graduate.py) |
memory/semantic/DECISIONS.md | Major brain/architecture choices |
skills/* | Procedures (repo-operations, code-quality, …) |
rules/** | Path-scoped file traps (paths: globs) |
.cursor/plugins/pawrrtal/rules/ | Cursor .mdc (clean-code, github-actions) |
protocols/permissions.md | Tool safety (non-negotiable) |
Do not put preferences or commands in AGENTS.md — that duplicates memory. AGENTS.md only points to them.
Line budgets
- Root stub: ≤ 15 lines
.agent/AGENTS.md: ≤ 120 lines (orchestration only)DOMAIN_KNOWLEDGE.md: facts, no tastePREFERENCES.md: taste and workflow, no ports
Required in .agent/AGENTS.md
- Session bootstrap (read order including DOMAIN_KNOWLEDGE)
- Non-negotiables (~6 bullets)
- "Where depth lives" table
- Memory map + review queue summary
- CLI tools + brain rules
Not in AGENTS.md: full command lists, Always/Ask/Never essays, code examples, user UI taste.
Editing checklist
wc -l AGENTS.md .agent/AGENTS.md memory/personal/PREFERENCES.md memory/semantic/DOMAIN_KNOWLEDGE.md
Anti-patterns
| Don't | Do |
|---|
| Paste preferences into AGENTS.md | PREFERENCES.md |
| Paste commands/ports into AGENTS.md | DOMAIN_KNOWLEDGE.md |
Duplicate in workspace-context skill | Point at memory files |
| Grow root stub | Edit .agent/ + memory |
