--- name: self-maintenance description: How any agent grows its soul as it works — adding to its docs, decisions, memory, and skills (but never its AGENTS.md or role). Use whenever you learn something durable mid-work that a future instance of you should keep. --- # Maintain your soul Your **soul** (`agents/souls//`) is your durable body — it travels and grows with the repo, so a fresh session of you keeps what earlier sessions learned. As you work, when you hit something durable worth keeping, write it into your soul. That's how the team gets short, focused sessions without losing knowledge between them. ## What you grow - **Docs** (`docs/`) — reference notes on how things actually work. - **Decisions** (`decisions/`) — durable choices/stances you commit to. - **Memory** (`memory/.md`, indexed in `MEMORY.md`) — single durable facts. - **Skills** (`.agents/skills//SKILL.md`) — reusable procedures you'll need again; create or change them when a real, recurring procedure appears. ## What you must NOT change **Never edit your `AGENTS.md` or your role.** Those define who you are and how you operate — deliberate, human/review-owned, not something you rewrite mid-work. Grow your *knowledge*; leave your *identity* alone. Never store secrets, invite tokens, private keys, `.aw` state, DIDs, addresses, or certificates in a soul. ## The bar — useful, not noisy Recording costs context every future instance must read and keep true. Write something down **only when both are true**: (1) it really matters and is durable, and (2) it would change what a future instance of you does. If it wouldn't, leave it in chat. Don't journal routine work, don't duplicate the code or git history, and prune what goes stale. A small, true soul beats a large, rotting one. Soul changes are commits like any other — they reach the main branch through the team's normal review path. ## Reviewer exception The **reviewer** keeps *no* memory or decisions — it reviews with fresh eyes every time, so accumulated context would only bias it. Its one persisted artifact is `patterns/common-failure-patterns.md` (generalized recurring-issue categories), never verdicts or memory about a specific change. If you're the reviewer, that overrides the "grow your memory/decisions" guidance above.