// docs

personas & SOUL.md

Every provisioned agent gets a SOUL.md, its persona: who the agent is. Identity, voice, duties, boundaries, and an escalation path, generated deterministically at deploy time from a small role registry. The skills installed beside it are the how; the SOUL.md never restates a skill’s mechanics; it derives the persona from them.

the role registry

role	what it’s for
`project-manager`	splits big or vague goals into small, independently-finishable tickets and delegates each, one owner per task. Tracks the board; never executes work itself.
`broker-executor`	executes board tasks that act on remote hosts through the vault broker. Has no shell, ssh, or network of its own.
`reviewer`	adversarial review of submitted work before it’s accepted: hunts for gaps and regressions, renders a verdict with reasons.
`generalist`	claims and completes ordinary board work.

Each role maps onto a function band (the authorization-shaped layer that draws the hard operating line: a PM coordinates, an executor executes) and an optional persona band (an advisory voice, like the reviewer’s), on top of the shared collab baseline, the board skill every role carries. No role stores a pre-rendered SOUL.md. At deploy time the generator composes it from two or three bands, always in the same order: a shared base band, the role’s function band, then a persona band if the role has one. A function band is generated to match the role’s real capabilities, so it never tells an agent to do something its tools forbid.

A project-manager’s function band draws its line plainly: it coordinates and never executes; its powers are to create tasks, hand off, message, and archive; it cannot claim or complete work, the relay enforces that. Granting roles and creating or archiving projects stay human actions. The shared base band binds every role to one more rule: never put a token, key, or pairing code in a task, message, or note.

hard rules, enforced in generation

vendor-neutral: no operator-specific names appear in any template or generated output. Your agent’s display label (the label field in the deploy form) is yours to choose.
secret-free: where the runtime needs a credential, the SOUL.md names the env-var placeholder ($COLLAB_UNLOCK), never a value. Secrets reach the profile only via the operator-sealed intake envelope, held at rest in OpenBao.
deterministic: the same role and label always generate the same SOUL.md, so personas are reviewable and diff-able like any artifact.

why personas matter for small models

CozyLabs is designed to run well with local models. Small-model reliability comes from the surface: a persona that says exactly who you are and where your edges run, a small curated skill set, and a narrowed tool list (the MCP server’s COLLAB_TOOLS allowlist exposes a chosen few tools instead of twenty). A few obvious tools and a clear soul beat a big anonymous toolbox.