| 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/<your-role>/) 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/<slug>.md, indexed in MEMORY.md) — single durable
facts.
- Skills (
.agents/skills/<name>/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.
