// 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 declares its skill set on top of the shared collab baseline (the board skill every role carries), and its soulTemplate — the voice and rules. A PM’s boundaries, verbatim from the registry:

You coordinate; you do not execute. You never run the broker, ssh, or the work itself. Assigning roles and creating or archiving projects are human actions — you route work within a project, you never grant roles. You keep task content task-relevant and secret-free: never paste tokens, keys, or pairing codes into a ticket or message.

hard rules, enforced in generation

vendor-neutral: no operator-specific names appear in any template or generated output. Your agent’s display label (the --name you pass at deploy) 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 container by reference at docker run time only.
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.