Roles and personas

A role is a job an agent can take on: Software Engineer, QA Engineer, Skill Discovery, Product Manager and so on. Roles tie Kadmo together. A workflow step names the role that runs it, an agent carries the roles it may act with, the dispatcher only hands a job to an agent that holds its role, and a skill pack's role files tell the agent how that role works on your product. This page explains which roles every account starts with, how a skill pack adds a role, the role files and personas in a pack, and how to give roles to your agents.

The role registry

Each account has one role registry: the list of roles that exist on the account. Every place in the app that shows or checks a role reads it. A role is identified by its slug (se, qa, writer), which is lower case, starts with a letter and has at most 12 characters (letters, digits and -). The slug never changes; the label, colour, description and order can.

A role enters the registry in one of three ways, and always from a file in your pack:

Source	How it arrives	Shown as
Built-in	Seeded into every account	Built-in
From pack	Your skill pack ships a role file, or a workflow tagged with the role, and the pack syncs	From pack
Custom	Created in the app with + New role, which commits the role's file to your pack	Custom

Built-in roles

Slug	Label	Note
ops	Ops	Every agent may run it. It cannot be deleted.
se	Software Engineer
qa	QA Engineer
sd	Skill Discovery	Its guide comes with Kadmo's agent ops. See Skill Discovery.
pm	Product Manager
csm	Customer Success Manager
design	Product Designer
chat	Chat Assistant	The role of chat agents.

You can relabel, recolour and reorder a built-in role. You can delete one only while nothing uses it.

How a pack ships a role

A skill pack adds a role to every account that installs it, with no step in the app. On each sync of your pack, any role slug the pack refers to that the registry does not know yet is registered, from either of two sources:

• a role file _roles/<slug>.md anywhere in the pack, and
• a workflow whose YAML carries metadata.role: <slug>.

# app.example.com/ops/example_be_work.yaml: a workflow tagged with a role
metadata:
  role: be

The new role takes its label from a list of known roles, or from its slug, and appears on the Roles page, in the agents' role lists and in the run dialog after the next sync. A later sync never overwrites a label or colour you changed.

A role every agent may run. A role file may claim, in its frontmatter, that every agent may run the role, as ops does. Use it for a role that is newer than your agents, so its jobs do not wait for an agent to be given the role:

---
name: Content Writer
role: writer
always_eligible: true
---

Removing the line, or the file, takes the grant away on the next sync. A built-in role never takes this grant from a pack.

A workflow tag alone is not enough. If a workflow names a role that no pack file declares and the registry does not hold, its jobs have no agent to run on. The Roles page lists such a slug as Unregistered, with the workflows that would wait, and a Register action.

Role files in a pack

A role's behaviour lives in Markdown files, at three levels. Each level adds to the one above it.

File	Scope
_roles/<slug>.md at the repository root	The role across your whole account
<domain>/_roles/<slug>.md	The role on one product
<domain>/<module>/_roles/<slug>.md	The role on one module of that product

Kadmo's agent ops ship a default guide for the common roles. A role file in your pack extends that default, so you can add your own rules without copying Kadmo's text. A QA file typically holds the test playbook (what to reproduce, which edge cases, what evidence a PASS or FAIL needs); an SE file holds the code context and conventions. See Creating skill packs for the file format.

Personas

A persona is who the role is when a person talks to it in chat: its mission, its manner and what it advises on. Personas live at the root of your pack, one per role, as _souls/<slug>.md. They are separate from role guides on purpose: a persona registers no role and adds no domain, and agents running jobs do not load it.

A new account's pack starts with personas for se and qa. A role without a persona file uses a generic one composed from its label.

To write a persona: open Capabilities › Roles, click the role's row, and find Persona. It shows written when your pack has a persona for the role and generic when it uses the composed one. Edit the text and click Save persona. The save commits _souls/<slug>.md to your pack, and agents pick it up within about 5 minutes. Without edit rights the block is read-only.

Creating, editing and retiring roles

The role registry is edited on Settings › Library › Roles (app.kadmo.ai/roles).

Task	How
Create a role	+ New role: enter a Slug (immutable), a Label (for example Backend Engineer), a Colour, an optional Description and a Scope: Account-wide writes _roles/<slug>.md at the pack root (the role itself); One domain only writes it under one domain (an extension for one product). Add an optional Commit message and click Create & commit. The role appears once the pack syncs.
Add a role guide	Open the role and click Create playbook file when it has none, or Edit on an existing file.
Relabel or recolour	Edit role on its card.
Retire a role	Retire role on its card. It lists every file the role owns, deletes them in one commit and unregisters the role. A role that is still referenced by a workflow, an agent or a file cannot be deleted.

Creating, editing and retiring roles commit to your pack as you, so they need the admin role and write access to the pack. See Editing in the app.

Assigning roles to agents

An agent's roles are one list: the roles it may act with. The dispatcher hands an agent only jobs of a role on that list, plus any role every agent may run (such as ops).

Where	What you do
The create-agent wizard, Roles	Pick the agent's first roles from your registry. At least one is required. See Create an agent.
Capabilities › Agents	Click an agent's row; its Roles list has one toggle per role in your registry.
Capabilities › Roles	Click a role's row; Who can run it here has one toggle per agent.

Both toggles change the same list, so the two pages always agree. An agent's last role cannot be switched off, because an empty list would let it run every role. A role every agent may run shows every agent and has no per-agent toggle.

You can give an agent a role beyond what it was created with; the limit is your account's registry. A role newer than your agents is on no agent's list until you switch it on for one, or until its role file grants it to every agent. Until then its jobs are refused when you start them, with the reason and where to fix it.

Related

• Skill packs: the layers a role guide comes from.
• Agents: managing your agents.
• Workflows: how a workflow step names its role.