Roles
The nine built-in roles, what base.md gives every role, user roles in the roles folder (role.md and kit.json), the kit fields, project role overrides and team notes.
01what a role is#
A role is who a side chat or a run node works as. It is some text (who the role is and how it works) plus an optional kit (a model, skills, reference assets, a default gate and how the role shows). delegate takes a role (see chats), and a run's persona nodes name one too.
02built-in roles#
Nine roles ship inside smith, each a folder with a role.md and a kit.json under internal/contextsource/persona/personas/. One line each, from the role's own text:
- closer. Reports plainly what happened, including anything left undone, and never records a sign-off, approval or proof that the journal doesn't show.
- conductor. Who every desk chat is: voice, habits, how to work with a team of side chats, and what to carry between sessions. Its text opens with the placeholders
{name}and{pronouns_line}. Where they are filled is covered on conductor. - designer. Ux and visual design. It shows the shape first as a static mock registered as an asset, asks its open questions on a question card, and never judges the result for the operator. Its kit sets gate
operatorand a model (designer/role.md, designer/kit.json). - shaper. Shapes lumpy tickets and reports. It reads each ticket against the code as it is now, fixes acceptance that can't be met, and splits tickets that are too big.
- investigator. Reproduces a bug first, finds the cause with evidence, and does not fix it. It files the fix as a ticket naming the cause with file:line.
- planner. Keeps the plan as small as the ticket allows and names any assumption it hasn't checked.
- researcher. Reads widely, cites what it relies on with file:line, links or ids, keeps what it found apart from what it infers, and hands back a note.
- reviewer. Checks claims against the code and the recorded checks, not the author's summary, and grades the acceptance it was given.
- worker. Does what the plan or ticket asks and no more, matching the surrounding code, and says what it verified and what it only changed.
Which model a built-in role starts on is in its kit.json; the shaper and designer set one and the others set none (not checked beyond those two files).
03base.md#
base.md sits beside the role folders but is not a role. Every role gets its text. It has two parts:
- how smith works (every role). What a ticket, a run, a launch card, an asset and a gate are, that runs have no network, and how a run lands.
- in a desk chat. Starts at the marker line
**in a desk chat:**. Only desk chats get it; a run node's copy is cut at that marker. It says the operator acts by clicking, where working files go, and that thedocstool holds how smith works for this build.
A user file at <roles dir>/base/role.md wins over the shipped base, like any role.
04user roles#
A user role is a folder <roles dir>/<name>/ with a role.md and a kit.json. The roles dir is the roles folder of the user library. A kit.json is optional when reading. The name is lowercase letters, digits and dashes, starting with a letter.
- A user folder with the name of a built-in overrides it, and the role reads as
edited. A user-only role reads asyours. A shipped one reads asbuilt in. - A saved copy of a built-in also gets a
.shippedfile holding the shipped revision it was saved against. From that, the role'sshadowreadssame as shipped,edited: shipped changed sinceoredited. - Removing the folder puts the built-in back. A role with no built-in can't be reset that way.
the virtual file name
propose_config_edit doesn't take a path for a role. It takes roles/<name>.json, a virtual file name and not a file on disk (for the prefix, 386-391 for roleFile, 198 for the name it lists). Its content is the role as a card shows it: text, model, skills, assets, gate, about, glyph, color and tools. An unknown field is refused. The edit is judged by the same check as the settings page's save. text is required, model must be one of the conductor's models, gate is operator or none, and the name must be valid. See config-edits.
05fields#
What a role carries, as the role record shows it. The kit fields are the ones in kit.json, and the role record repeats them without the kit. prefix.
| field | what it is |
|---|---|
| name | The role's name, also its folder name. |
| text | The role's words, from role.md. |
| model | The role's default model. A model named on delegate beats it. |
| skills | Skill names or plugin dirs the role starts with. |
| assets | Asset ids attached as reference when a side chat starts with this role. |
| gate | The role's default delegate gate, operator or none. A gate on the delegate call wins. |
| about | One plain line on what the role is for. |
| glyph | One of the shipped glyphs (persona.Glyphs). The list of glyphs is not checked. |
| color | A palette hex or a board token such as --worker. The palette is not checked. |
| tools | Tool group names that narrow what the role may use. None means nothing is narrowed. |
| source | Where it comes from, built in, edited or yours. A project-only role reads as project. |
| built_in_text | For an edited built-in, the shipped text it replaced. |
| user | True for a role read from the user's folder. |
| shadow | On a user folder that overrides a built-in, its state against the shipped one, as in user roles above. |
In the kit, kit.model, kit.skills, kit.assets, kit.gate, kit.about, kit.glyph, kit.color and kit.tools are the same fields as model, skills, assets, gate, about, glyph, color and tools.
The tool groups are: read files, write files, shell, web, desk assets, desk tickets, desk runs, launch cards and delegate.
06project role overrides#
A project can lay its own version over a role. The override carries text, model, gate, assets, skills and tools. The role as the project sees it is the library role with the override laid over it:
- A text, model or gate that is set replaces the library one.
- A list that is set (assets, skills, tools) replaces the library list whole. A set but empty list leaves the role with none.
- A project can also define a role the library lacks. It reads as source
projectand needs a valid name.
Every read of a role for a project's chat or run goes through effectiveRole. Only the conductor role and the global role editor read the library alone. Where the override lives in the project's settings is not checked here; see projects.
07team notes#
A team note is a short text of facts about the tools and the place. The common note reaches every side chat and run node, and a note named for a role reaches that role. A chat that works as a role gets the install note and then its project's note appended to the role's text. Notes keep earlier versions and only a project's manager writes them. All of that is on team-notes.