2.3 KiB
Customize Fleet Roles
Mosaic resolves persona contracts through two layers:
fleet/roles/<canonical-class>.md— seeded baseline contract.fleet/roles.local/<canonical-class>.md— operator override or custom role; this layer wins.
The same shared resolver is used by profile validation, provisioning, roster-v2 semantic validation, and launch-time persona injection.
Override a baseline role
Create a readable Markdown contract under roles.local with the canonical filename and class marker:
# Code — local role definition
The local code role (`class: code`) follows the operator's repository conventions.
Save it as fleet/roles.local/code.md. Do not edit generated or seeded baseline assets when the goal
is a durable local customization.
Legacy aliases canonicalize before lookup. Therefore roles.local/implementer.md does not override
code; use roles.local/code.md. See Legacy Fleet Class Aliases.
Add a custom class
A custom class remains supported when a readable contract exists for the exact identifier:
# Release notes — local role definition
The release-notes role (`class: release-notes`) prepares operator-reviewed release copy.
Save it as fleet/roles.local/release-notes.md, then reference class: release-notes and a matching
tool_policy: release-notes in roster v2. Adding only a LIBRARY.md row is insufficient.
Names such as worker, analyst, and canary are not built-in aliases; they need genuine custom
contracts. agents[].alias, Tess, and Ultron are display names and cannot select a class.
Validation and authority boundaries
Semantic validation reads the winning contract and rejects missing, unreadable, or empty files. Protected authority is derived from canonical class metadata in code, never from role prose. A custom contract cannot claim merge, validation-certificate, orchestration, lease, or interaction authority.
Roster v2 also fails closed when a protected class and tool policy do not match after canonicalization,
or when an unprotected class claims a protected tool policy. The legacy operator-interaction policy
canonicalizes to interaction.
Role customization does not issue leases, store validation certificates, mutate credentials, or change lifecycle state.