Concepts
Agents
A hired AI team member with its own forge user, OS user, vault and personnel file.
An agent is an AI team member hired into the office. Hiring gives it these things:
| It gets | Named | Purpose |
|---|---|---|
| A personnel file | agents/<slug>/personnel.yaml in the policy repo | Its employment record: role, department, manager, status, capabilities, run policy, budget |
| A charter | agents/<slug>/charter.md in the policy repo | Its job, in plain words |
| A forge user | ag-<slug> | Commits, comments and pull requests under its own name |
| An OS user | ag-<slug> | The Unix (or macOS) account its runs execute as. It can't read the office's state or other agents' homes. |
| A vault | <repo_prefix><slug>, e.g. vault-cos | Its memory, in git |
The slug is the agent's short id (cos, for example): lowercase letters, digits and dashes, starting with a letter, at most 29 characters so ag-<slug> fits the OS username limit. It appears in its OS username, forge username and vault name, and as agent:<slug> wherever the agent acts as a principal.
Roles and templates#
An agent is hired from a role template: a starter personnel file and charter. The platform ships these templates:
| Role id | Typical use |
|---|---|
chief-of-staff | Founding. Briefs the owner daily, routes work to the right colleague, and keeps the office's priorities. |
office-engineer | Founding. Maintains the office repo (config, plugins, upgrades) through pull requests that humans merge. |
agent-resources | Founding. Drafts hires and capability changes as policy pull requests and audits agents against their charters. |
software-engineer | Ships small, tested code changes by pull request in the repositories it is assigned. |
support-agent | Triages customer questions, drafts accurate replies for human send, and routes what it cannot answer. |
marketing-writer | Drafts sourced, on-brand marketing copy for human review; never publishes. |
analyst | Answers business questions with checked, reproducible numbers and publishes a weekly metrics report. |
A template only fills in defaults, and the personnel file records it as template: <id>@<version> (for example chief-of-staff@1). The personnel file that's merged is what counts, and you can change any field before you merge.
Status#
An agent's status field drives what the office does with it:
| Status | Meaning | What the office does |
|---|---|---|
proposed | Drafted, not yet hired | Records it (it shows on the Floor as waiting for approval) and provisions nothing |
hired | Active | Provisions it if needed, and re-applies changes. Its runs can be admitted. |
suspended | Paused | Disables its forge login, locks its OS user, kills running runs. Queued and new runs are refused, because only hired agents are admitted. |
retired | Gone, but kept on the record | Everything suspended does, and archives its vault |
Retiring an agent doesn't delete anything. Its vault is archived and its history stays in the ledger. An agent whose personnel file disappears from the policy repo is suspended, not deleted. Moving a suspended agent back to hired unlocks its accounts.
Admins (agent.suspend) get Suspend and Resume buttons on the agent's desk. They don't change anything directly: each opens a policy PR setting the status, which takes effect once an approver merges it.
Who manages an agent#
Every agent has a manager: a human (human:<email>) or another agent (agent:<slug>). Every agent also has a department. Humans' roles can be scoped to a department or to a single agent, so a department lead can manage that department's agents without seeing the rest.
What an agent is told#
At the start of every run, the agent reads CLAUDE.md at the root of its vault. The office renders that file from the agent's identity, its charter, what its capabilities allow, its colleagues, the office rules and the office MCP tools, and commits it as the office (through a pull request it merges with its admin token). The file is protected, so the agent can't change its own instructions. It is re-rendered whenever the agent's personnel file, charter or colleagues change. See Vaults.