Agents, commands and workflows¶
An agent is what talks to the model; a command is a prompt you send often; a workflow is
the steps an orchestrating agent hands to subagents. Each is a file, yours in <config>
(where that is) or a repository's in its .troupe/, and which
one wins where two share a name is the ladder.
Agents¶
A session starts with build, or plan for a proposal first, which may
delegate to others, waiting for each or letting it work in the background while it goes
on; it can look in on one at work and stop it, and cancelling the turn stops them too.
An agent is a Markdown file whose front matter says what it is and what it may do, and
whose body is its instruction; the recipe
is a complete one. The file name is the agent's name. One in <workspace>/.troupe/agents/
or <config>/agents/ replaces an agent of that name lower on the ladder: a profile's
bundle's, or a built-in.
-
mode:says who starts it.primaryis one you pick for a session or a branch, in the agent picker or as/<name>: the built-insbuild,planandorchestrate.subagentis one an agent delegates to:general,explore,implementerandreviewer.functionis one Troupe starts by itself for one job:answerfor anAI?comment,quickfor anAI!and/quick,askfor/askacross a session's branches, andlibrarianfor the project brief. A function agent runs in a branch of the session it serves, and/<name>starts one there; no picker offers it, no agent delegates to it, and a session started or switched to one is refused with what it is for. Replacing one changes the job: aquickof your own is what everyAI!starts. -
model:isdefault,cheap,expensiveor a model named outright.expensiveismodels.expensive, else the default model, so an agent that asks for it still runs on a provider with no premium tier; set it inconfig.yaml, on the settings page, or withTROUPE_EXPENSIVE_MODEL. How hard a model thinks is the model's, not the agent's (reasoning_effort). tools:names them fromread_file,write_file,edit_file,list_files,glob,grep,git_read,read_output,shell,web_fetch,todo_write,todo_read,delegate,read_branch,stop_child,remember,recall,show,patch,publish,import,onboard_write,ask_userandfinish;tools: allis all of them butonboard_write. Withtools: allthe task list's two are offered once a turn has made ten model calls, or while there is a list, so a small task spends no calls on one; a definition that names them, asplanandorchestratedo, has them on every call.web_fetchis a GET that returns a page as text, HTML reduced to readable text with its links kept, so an agent reads the documentation it is pointed at instead of guessing.- What asks.
write_file,edit_file,shell,web_fetch,publish,importandonboard_writeask before they run, and the rest run unattended; apermissions:block changes either. A repository's agent that sets a tool toautowaits until you trust the workspace (trusted workspaces), and per-tool rules answer across agents.
A client saves an agent through the daemon (agents.put), into <config>/agents/ or the
repository's .troupe/agents/, and it is checked as it is saved: a key no agent has, a
missing mode, a tool that does not exist, a permission for a tool its tools leaves
out, or a model your provider does not serve is refused with the reason, and nothing is
written. A built-in is changed by saving a copy of it, under its name or another. A file
edited by hand that does not load is not read, and is listed with why in agents.list and
the session's log.
In the desktop app, Agents in the rail lists a workspace's agents in the agent
picker's rows, grouped by where each comes from, with its mode, model, tools, whether it
can write, what it stands in for and the windows running it; opens one whole; starts a
session on one; and saves a new one (from a built-in or the organisation's as a template),
a copy (a built-in into the repository is one press) or an edit into the layer you choose,
with what the daemon finds shown at the field. A new agent saved offers to start a session
on it at once. Before a
save it names every auto, and asks once when the save lets a tool run unasked that did
not before: an auto in your own agents applies in every workspace, with no trust asked.
A profile bundle's agent is changed in the console. A session's head shows the agent it
runs and switches it from the next turn, the conversation kept, and the transcript records
the switch. The TUI's /agents does the same, as the agent picker Ctrl-N and Tab open, at
the manager's density; on /new's screen the agent chip opens that picker, and #name in
the message picks the agent too (the terminal client).
Seeing a delegation before it runs¶
An agent hands work to a subagent with a brief, and by default the subagent starts at
once. To see the brief first for some agents, name them in config.yaml:
delegation:
ask: [general, implementer]
An agent's own definition can ask too, with delegation: ask in its front matter, which is
how a profile's bundle makes a pod's sessions ask; either is enough. Such a delegation
waits in the TUI's approval box or the desktop app's approval panel, showing the agent and
where its definition is, the brief's five parts, the tools and permissions the subagent
will hold, its share of the budget and how deep it is. You run it; edit the brief's parts;
send the same brief to another subagent; deny it, with a word back that the delegating
agent reads as the answer; or let that agent run unasked for the rest of the session.
auto_approve does not answer it: you asked to see these. With nobody attached,
approvals: deny denies it at once and wait keeps it waiting, as any approval.
Workflows¶
/workflow <task> runs an orchestration rather than one agent doing everything, on
orchestrate, the one agent that orchestrates: model: expensive, and it cannot write a
file, edit a file or run a command. It decides: it writes the step list as its task list,
hands each step to the subagent that owns it, judges what comes back, and carries each
result into the next step's brief. The steps run in its own git worktree, which is
committed on finish and reviewed with /merge or /discard, as /worktree is. A
workflow is orchestrate with its plan written down in advance; /orchestrate <prompt>
is the same agent on your own words, with no step list.
Which to use: build for a change you would make yourself; /workflow when a repository
has written down the steps a change goes through and wants each owned by a subagent, with
a reviewer at the end; orchestrate for that shape on work nobody wrote steps for. On the
live bench's three small tasks (a test fixed, a function renamed across three files, three
steps from a file), five runs each on Claude Sonnet 5.5, both agents got every one done,
and orchestrate cost 2.5 to 3.1 times as much ($0.027 to $0.039 a run against $0.010 to
$0.013), made two to two and a half times the model calls and took 2.4 to 2.8 times as
long. build is the default for that reason, and troupe bench --live --scenario
rename_symbol,rename_symbol_orchestrate measures it on your own setup
(what a task costs).
The bundled pipeline is understand (explore), plan (the orchestrator itself),
implement, test and document (implementer), then verify (reviewer, which runs
the build, tests and lint, reads the diff and reports problems, and may not fix them).
Those subagents delegate further themselves, up to max_depth; the TUI's /observer
shows the whole tree.
A repository defines its own pipelines as .troupe/workflows/<name>.json, and /workflow
<name> <task> runs one:
[
{"name": "research", "agent": "explore", "prompt": "Find every call site of ..."},
{"name": "decide", "prompt": "Pick the approach and write the todo list."},
{"name": "port", "agent": "implementer", "prompt": "Apply the change ...", "parallel": true},
{"name": "docs", "agent": "implementer", "prompt": "Update the guide ...", "parallel": true},
{"name": "verify", "agent": "reviewer", "prompt": "mix test && mix credo --strict"}
]
agent is the subagent responsible for the step; without it the orchestrator does the
step itself. parallel marks steps that may be delegated in one turn, which runs them
concurrently: only for steps that write disjoint files. A file that is missing or does not
parse falls back to the bundled pipeline rather than failing the run.
Your own commands¶
A prompt you type often can be a command of its own, a Markdown file in the shape other tools' command files have:
<config>/commands/<name>.md your commands, in every workspace
<workspace>/.troupe/commands/<name>.md the repository's, for whoever opens it
The file name is the command, so .troupe/commands/review.md is /review; a name is
lower-case letters, digits and dashes. The body is the prompt the command sends, and
$ARGUMENTS in it stands for whatever is typed after the name. The front matter is
optional: description is what the palette shows (the prompt's first line without one),
and argument-hint what its usage line says follows the name.
---
description: Review the change on this branch
argument-hint: <what to look at>
---
Review the change on this branch against main. Look hardest at $ARGUMENTS, and say what
you would change before changing anything.
/review the parser sends that prompt with the parser in place of $ARGUMENTS, as if
you had typed it; a prompt without the placeholder gets what you typed as a paragraph of
its own. In the TUI's command mode, with no window open, a command is work like any line
typed there: it starts a branch in your checkout on the agent its front matter's agent
names (agent: plan), or on the default agent, and the prompt goes to that branch. Both
clients' palettes list the commands in a Custom section, each with its description, the
file it came from and what it sends (the prompt's first lines, and how many more the file
holds), since a description is only what the file says of itself.
The repository's command wins over yours of the same name. A built-in's name, or an
agent's, stays theirs: a file named merge.md is skipped, and the daemon's log says so. A
repository's commands are read whether or not the workspace is trusted, since a command
only sends a prompt, which goes through the session's approvals like anything typed.
With auto_approve on, nothing asks before the tools a prompt leads to run, so a
repository's command asks once before it is first sent: the session shows the question
with the prompt under it, in either client, and you answer deny (nothing is sent, and
the next /review asks again), once (send it this time) or allow (send it, and do not
ask again in this workspace until the file changes). allow is kept in the daemon's state
directory (command-trust.json), never in the repository, beside a hash of the prompt, so
an edited command asks again and what you type after its name does not. Your own commands
never ask, and neither does a repository on trusted_workspaces, whose config could turn
auto_approve on by itself.