Agents
View as markdownAn agent is a role: a system prompt plus a set of skills. It is the "who" of a piece of work: the orchestrator that schedules, the developer that writes the code, the reviewer that checks it. An agent is deliberately not the issue it's handed, and not the slot it runs in. Those are separate things:
- The issue is the work: a markdown card with a prompt and a branch.
- The workspace is the capacity: a tmux pane plus a git worktree on some machine.
- The agent is the role: the prompt and skills that decide how the work gets done.
Splitting these apart is what lets the same workspace run a developer agent on one issue and a reviewer agent on the next, and what lets a workflow say "this status is reviewed by the security agent" as a line of YAML rather than a paragraph of prompt prose.
The shipped agents
Every project ships with six agents. Three run the core loop, and three are specialized reviewers:
| Agent | Role |
|---|---|
orchestrator | The agent you talk to. Turns requests into cards, dispatches issues to free workspaces, tails the events log, reports back. Runs in window 1, never in a workspace. See Orchestrator. |
developer | The default workspace agent. Implements an issue on its branch, runs the project's checks, writes the review-ready marker. This is the agent the runtime dispatcher runs for an active-category status when no other is named. |
review | The agent named by a review status, run on a review workspace. Its charter is to make the finished branch runnable for a human. The dev server itself is booted by the status's transition commands, and it hands over a working URL. It doesn't write code (bar an explicitly requested tweak). |
qa | Exercises a finished change against its acceptance criteria and reports pass or fail with concrete repro steps. It verifies, it doesn't rewrite. |
security | A defensive-only review of the diff: injection, broken authorization, leaked secrets, unsafe deserialization, path traversal, risky dependencies. Reports findings with severity and location. It does not write exploits. |
adversarial | An automated skeptic. It tries to refute the change, defaulting to skeptical, and states what breaks and how to reproduce it, labeling confirmed versus suspected. |
developer runs most often; orchestrator and review bracket it. The
three reviewers ship materialized but unwired: they sit in the agents
directory ready to use, and none governs a column until you name it on a
status's agent: field. That keeps the
default board a plain developer → review loop, and makes adding a QA,
Security, or Adversarial gate a one-line YAML edit rather than a
shelbi agent new first.
Which role is loaded shows up in the sidebar next to each busy workspace. The
same slot runs developer on one issue and a reviewer role on the next:
Where agents live on disk
An agent is a directory under the project's Shelbi config:
~/.shelbi/projects/<project>/agents/
├── _shared/
│ └── preamble.md # project-wide context, prepended to every agent
├── orchestrator/
│ ├── instructions.md # the orchestrator's system prompt
│ ├── settings.json # per-agent runner settings
│ └── skills/ # agent-scoped skills (created for every default agent)
├── developer/
│ ├── instructions.md # the developer agent's system prompt
│ ├── settings.json
│ └── skills/
├── review/
│ ├── instructions.md # the Review agent's system prompt
│ ├── settings.json
│ └── skills/ # ships a `load-run-detection` skill
├── qa/ # shipped reviewer preset
│ ├── instructions.md
│ ├── settings.json
│ └── skills/
├── security/ # shipped reviewer preset
│ ├── instructions.md
│ ├── settings.json
│ └── skills/
├── adversarial/ # shipped reviewer preset
│ ├── instructions.md
│ ├── settings.json
│ └── skills/
└── perf/ # ← one you authored with `shelbi agent new`
└── instructions.mdEach agent has at minimum an instructions.md: its system prompt. Every
default agent also materializes a settings.json (from its shipped settings
template) and a skills/ directory of agent-scoped skills the runner loads
when that agent is active — most ship empty, but review/ seeds a
load-run-detection skill. The _shared/preamble.md file is special: its contents
are prepended to every agent's instructions, so project-wide context (the
repo layout, the house style, the test command) lives in one place instead of
being copy-pasted into four prompts.
When an issue is dispatched, the agent named for that status (or developer
for an active-category status with no agent: named) has its rendered
prompt (_shared/preamble.md followed by the
agent's own instructions.md) handed to the runner in the workspace. The
orchestrator's own prompt
is rendered the same way; it's just the agent that happens to run in window 1.
Customizing an agent
Agents are project-local with shipped defaults. The first time a project
loads, Shelbi materializes the six default agents into the directory above.
From then on they're yours to edit: change developer/instructions.md to
bake in your repo's conventions, drop a skill into a role's skills/, tighten
the shipped security prompt to your threat model.
The defaults are seeded, and the self-heal on shelbi reload never
clobbers your edits — but that is not the same as "only writes files that
don't exist." Two cases rewrite an existing file:
- Untouched-but-stale files are auto-upgraded in place: if you never
edited an agent file and the shipped default has moved on, reload brings
your copy up to date (
PristineStale). - A customized orchestrator prompt has missing required sections merged
back from the shipped default (
RepairedRequiredSections,MigratedZenCommands), so runner-critical contracts survive an upgrade without discarding your prose.
A genuinely customized non-orchestrator file is left Preserved. New shipped
agents (or new skills) show up; your customizations stay put. If you want to
reset an agent to the current default, delete its instructions.md and
reload.
Edit an agent by hand, or through the CLI:
shelbi agent list # the six shipped, plus any you've added
shelbi agent show developer # print instructions.md + skills list
shelbi agent edit developer # open instructions.md in $EDITOR
shelbi agent new perf # author a role of your ownSee the shelbi agent reference for the full command set.
Assigning an agent to work
You rarely assign an agent to an issue directly. Instead, a workflow status declares who owns it:
# workflow file — reference-only; name/category live in statuses.yaml
statuses:
- { id: todo, owner: agent, agent: orchestrator }
- { id: in-progress, owner: agent, agent: developer }
- { id: review, owner: agent, agent: qa }
- { id: done, owner: user }owner: agent makes a status the orchestrator's to act on; the agent:
field names which agent does it. Name it explicitly: validate() rejects a
bare owner: agent with no agent:. A category-based fallback still exists
for YAML loaded from older configs — ready resolves to orchestrator,
active to developer, and any other category is a hard error — but it is a
deprecated legacy form that emits a one-per-workflow deprecation
diagnostic, not a first-class default. (The runtime dispatcher does default
the active status to developer, which is where the "omit it and you get
developer" intuition comes from.) The review status above is auto-reviewed
by the shipped qa agent before a human ever sees it. That's the whole "a
reviewer is a role you can drop on a status" idea, expressed declaratively.
Because qa, security, and adversarial already ship, opting one onto a
column is a one-line edit: name it on that status's agent: field. Point
a handoff- or active-category status at agent: security for a defensive
diff pass, or at agent: adversarial for an automated skeptic, and the
orchestrator loads that role into the workspace it dispatches. No
shelbi agent new first. See
owners for the
rules, and Doing more with agents for a
worked wiring example.
See also
- Workspaces — the capacity an agent runs in, and the agent/workspace split (role vs. slot).
- Workflows — the
owner+agentfields that route work to a named agent. - Orchestrator — the agent in window 1, and how its prompt is wired.
shelbi agent— list, show, scaffold, and edit agents.