Instruction files and onboarding¶
A repository that carries an AGENTS.md has told coding agents how to work in it, and
Troupe reads it as the other tools do. What other tools keep in files of their own
(CLAUDE.md, Cursor's rules and the rest) is brought into Troupe's files once, by
troupe onboard, and read from there.
What every agent is given¶
These, in this order, each read from disk as a turn begins, so an edit takes effect on the
next turn. They go with the first turn's message, and again with a later one's when one
changed, so the system prompt stays the same all session; with system_prompt: per_turn
they open the system prompt instead, rewritten each turn.
<config>/AGENTS.md: your own, for every repository.AGENTS.mdat the repository root (the nearest directory with a.git; a worktree reads its own checkout's).AGENTS.mdin each directory between the root and where the session works, parents before children. Where the session works is the directory it started in and the directory of every file its conversation has read, edited or written, sofrontend/AGENTS.mdapplies from the turn after the agent first opened something underfrontend/.- The project brief Troupe's own agents write: the commands and conventions among the
repository's facts (
.troupe/memory/facts.jsonl), each that may no longer be true marked so, and a line naming therecalltool for the rest.
Signed in to a plane, a session reads your organisation's memory and then your own before all of these (Memory).
An .agents/AGENTS.md at the root, or in one of those directories, belongs to its
directory and is read right before that directory's own AGENTS.md, so where the two
disagree the directory's own wins; /context names it with its directory's scope
(.agents/AGENTS.md (root)). Your own <config> has none.
Every file applies. A file below the root is about the work under its directory, and where two disagree the nearer wins (which one wins).
The brief is the repository's, kept in its checkout, and a worktree or a folder of the
repository reads it. Which folders are the repository's follows git: one it tracks, or
would add, is; one it ignores is a workspace of its own, as a directory in no repository
is. Such a folder keeps its own brief, and a session there does not start the librarian by
itself (memory_auto_refresh), so it never rewrites the brief of the repository around it;
/memory refresh still writes the folder's own. The instruction files are read as above,
up to the nearest .git, in either.
What is not read¶
Other tools' files are not read: a CLAUDE.md or GEMINI.md in one of those directories,
Copilot's .github/copilot-instructions.md and .github/instructions/*.instructions.md
at the root, and Cursor's .cursorrules and .cursor/rules/*.mdc. Each is listed in the
session's log and /context as not read: run troupe onboard, and once
onboarded as not read: onboarded into AGENTS.md. So a
repository with only a CLAUDE.md gives a session nothing until it is onboarded. A
Copilot file below the root never counted, since Copilot reads its file at the root only,
and says so: not read: Copilot's file counts only at the root.
A file that is a link outside the repository (outside <config>, for your own
AGENTS.md) is not read, and context.get and the session's log list it as outside;
the same goes for .troupe/memory.md, which is then neither read nor written. A file that
is there and cannot be read is unreadable. Every file left out has a reason in words,
which /context prints: not read: outside the repository, not read: permission
denied.
Imports¶
A file can pull in another with @path/to/file.md, on a line of its own or in a
sentence, as Claude Code's do. The path is taken from the importing file's directory
(~/ is your home); the imported file is read right after the one that names it, and may
import again, five deep. Each file is read once, so a cycle ends where it comes back
round. An @ inside a code span or a fenced block is not an import. A repository's files
import only from inside the repository, and your own AGENTS.md only from inside
<config>. An import not followed (missing, outside, depth, cycle) is named on
the file that asked for it in context.get and the session's log, and /context prints
it after that file (@docs/gone.md (root) import not followed: missing).
Rules¶
A repository's rules are Markdown files in .troupe/rules/, each with front matter that
says when it applies, as Cursor's rules do:
---
description: TypeScript in the web app
globs: src/**/*.ts, *.tsx
alwaysApply: false
---
No `any`; prefer `unknown` and narrow it.
Each .troupe/rules/*.md at the root, and in a directory on the way to where the session
works, comes right after that directory's own file, in name order:
alwaysApply: trueputs it in every prompt;globs(a comma-separated string or a list) put it in the prompt from the turn after the agent first read, edited or wrote a file one of them matches, for as long as the conversation holds that call. A glob is taken from the directory that holds.troupe, and one without a/matches a file's name in any directory;- a rule with only a
descriptionis listed in the prompt by it, and the agent reads the file when the description fits the work; - a rule with none of them is not used.
/context says of each rule why it applies (always applied, applied: src/a.ts matches
src/**/*.ts) or why not (applies when a file matching src/**/*.ts is read or edited,
requested by description only: listed in the prompt, not joined). Rules share the
budget below and are held to the repository's edge as every other file is; an @ in a
rule is not followed.
The budget¶
The files share one budget, instructions_max_chars (16,000 characters), a file and what
it imports counting as one scope. The nearest scope is kept whole first; a file the
remainder cannot hold is cut, or left out, and the prompt says so where it happened. The
brief has its own, memory_max_chars. /context in the TUI, and context.get over the
protocol, list every file in force with its scope, its size, what reached the prompt and
its share of the budget; the session's instructions_loaded event records the same, what
was cut included, whenever what was read changed.
Checking them¶
troupe instructions check [--workspace DIR] [--json] checks every file a session in the
workspace would read wherever it worked, nested ones, .troupe/rules and imports
included, and none of the other tools' files. It prints a line for each finding, with the
file and the line:
frontend/AGENTS.md:3: contradiction: how to run the tests: `pnpm test` here, `npm test` in AGENTS.md:3
AGENTS.md:12: path: `docs/setup.md` does not exist
AGENTS.md:20: command: `mise` is not on the PATH (`mise exec -- mix test`)
frontend/AGENTS.md:9: duplicate: the same rule as AGENTS.md:5
- contradiction: two files, one of which applies inside the other, name different
commands for the same job (test, build, lint, format, run) in the same ecosystem, and no
command in common. A root's
mix testandfrontend/'spnpm testare two parts of one repository, not a contradiction, and two sibling directories never are. - path: a path in a code span or a link that is not there, from the file's own
directory (for an
.agents/AGENTS.mdor a rule, also from the directory holding its.agentsor.troupe) or from the root, and an@import that names no file. A span counts as a path when it starts with./or../, or has a slash and ends in one, names a file with an extension, or starts with a directory that is there; a bare file name, a branch likeorigin/mainand a URL are not checked. - command: a command in a code span, or in a fenced block marked as a shell (or with
no language), whose program is not on the
PATH. A span counts as a command when it starts with a known build tool (npm,pnpm,mix,cargo,go,pytest,mise,makeand their like); the shell's own commands and the platform's package managers are not looked for. - duplicate: a paragraph or list item said again in another file.
- drift: a file
troupe onboardwrote whose source, or another file it was made from, has changed or gone since (itsimported_from,imported_hashandimported_also);troupe onboardshows what changed. - outdated: the workspace was onboarded under older onboarding rules than this
build's (
.troupe/onboarded.json'sonboarding);troupe onboardshows what they would write now, and a run that answers every question records the new version.
It would rather miss a finding than make a false one. It exits 0 when it finds nothing, 1
on a finding and 2 when it cannot read the workspace, so a repository can run it in CI;
--json prints the same as one object, with files, onboarded and findings. Your own
<config>/AGENTS.md is checked with the rest, except for paths, which it names for every
repository.
Onboarding another tool's files¶
What another coding tool keeps for a repository, or for you, is brought into Troupe's own
files once, and sessions read Troupe's files from then on. troupe onboard [--workspace
DIR] asks each source Troupe knows what it would write, and shows each file as a diff
against what is there:
.troupe/agents/reviewer.md: new, from .claude/agents/reviewer.md
note: tools: WebSearch left out, Troupe has no such tool
+ ---
+ description: Reviews the change on this branch
+ tools: [read_file, grep]
+ imported_from: ".claude/agents/reviewer.md"
+ imported_hash: "9f2c..."
+ imported_at: "2026-10-09T12:00:00Z"
+ ---
+ You review code.
Write .troupe/agents/reviewer.md? [y/N]
What it brings in:
- Instruction files. A
CLAUDE.mdorGEMINI.md, at the root or in a directory, and Claude Code's.claude/CLAUDE.mdand Copilot's.github/copilot-instructions.mdat the root, are proposed as additions to theAGENTS.mdin the same directory: that file stays as it is, and only what it does not already say is added after it, under the heading it was under. Said already means the same text, spaces aside, or whattroupe instructions checkcalls a duplicate; anything reworded is proposed, and you read the diff. A line that only importsAGENTS.md(@AGENTS.md) is left out. With nothing left to add, nothing is proposed and the file is listed asskipped:, saying so. - Your own instruction files. Your config directory's
CLAUDE.mdandGEMINI.md, and Claude Code's~/.claude/CLAUDE.md, are proposed the same way as additions to your own<config>/AGENTS.md, never to a repository's.CLAUDE.local.mdis yours and usually not committed, so it is proposed nowhere: move what it says into<config>/AGENTS.mdby hand, or keep it. - Rules. Cursor's
.cursor/rules/*.mdc(the root's and a directory's), its legacy.cursorrules, and Copilot's.github/instructions/*.instructions.mdbecome.troupe/rules/<name>.md, with Cursor's front matter,description,globsandalwaysApply, meaning what it meant there. A directory's rule has its globs written from the root (src/**underweb/isweb/src/**); Copilot'sapplyTois its globs, andapplyTo: "**"isalwaysApply: true. - opencode's
instructions. The filesopencode.jsonnames ininstructions, by path or glob, are proposed as additions to the root'sAGENTS.md, after what the other tools' files add, without their front matter; one whose front matter scopes it withglobsbecomes a rule instead. A URL, a file outside the workspace, anAGENTS.md(Troupe reads those itself) and another tool's file onboarded on its own are listed asskipped:, saying why. - Agents and commands, Claude Code's and opencode's, become
.troupe/agents/and.troupe/commands/files.
Creating an AGENTS.md is a question of its own. Every coding tool reads that file,
so when the directory has none, troupe onboard asks AGENTS.md is not there. Create
it?, and --yes never answers it: the file is left for a run at a terminal, and the
summary says so. --json marks each proposal with question, create_agents_md for a new
AGENTS.md and write for the rest, and with --yes gives a new AGENTS.md
"written": false and the reason, which does not fail the run. Adding to an AGENTS.md
that is there is an ordinary proposal.
What it writes¶
Only what you answer yes to, one file at a time, in two places: the workspace's
.troupe/, from the repository's files, and your config directory, from files in your
home directory, never one into the other. There only agents/<name>.md,
commands/<name>.md, rules/<name>.md (the repository's), skills/<name>/...,
workflows/<name>.json, mcp.json and your own AGENTS.md; and besides those, an
AGENTS.md at the workspace's root or in one of its directories that is there and not
hidden. A file that would land anywhere else, through a .. or a .troupe that links
elsewhere, is refused.
Each file written records where it came from: imported_from, imported_hash,
imported_at, imported_also for any other file it was made from (an agent's
permissions in .claude/settings.json, say, or the GEMINI.md an AGENTS.md took from
too), and imported_version, the version of the onboarding rules that wrote it. A
Markdown file keeps them in its front matter; anything else, and an AGENTS.md, which is
read whole into the prompt, in onboarded.json (the workspace's .troupe/onboarded.json
for an AGENTS.md of the workspace's). A file a source found and made nothing of is
listed first, as skipped: with the reason.
Run again, it proposes nothing until a source changes: a file onboarded from an unchanged
source is left alone, your edits to it included, and one you said no to is not asked about
until its source changes (--all asks again; the answer is kept in Troupe's state
directory). A changed source is offered as a diff against the file you have; nothing is
overwritten unasked. --yes writes every proposal without asking; --json prints them as
one object and writes nothing without --yes. It exits 1 when a proposal was refused or a
write failed, and 2 when there was nobody to ask.
Inside a session, an agent whose profile names the onboard_write tool writes the same
files with it, asking before each one; into your config directory, and into an
AGENTS.md, it asks even with auto_approve on, since what lands there runs in every
session unasked, or is read by every tool.
When a session offers it¶
Onboarding proposes by itself and never writes by itself. A session in a git repository
that has other tools' files and nothing onboarded says in one line what troupe onboard
would bring in (1 AGENTS.md, 2 rules and 1 agent), and the TUI and the desktop app ask
about it as the session starts, before the librarian: Onboard 3 files from Claude Code
and Cursor into Troupe's own? [Y/n/r]. Yes writes them, then asks on its own about each
AGENTS.md that is not there yet; r shows each file as troupe onboard does and asks
for it; no leaves them all.
The onboarding rules have a version, recorded in .troupe/onboarded.json as onboarding
when a workspace is first onboarded and again once every question is answered. In a
workspace onboarded under older rules than its build's, a session asks Onboarding rules
changed since this repository was onboarded (v1 to v2). Re-run now? [Y/n]; where an older
librarian's survey wrote the brief (its survey in .troupe/memory.md), it asks whether
to rewrite it; Yes is the default for both. Only then does the librarian start, so it
reads what onboarding wrote. Each is asked at every start until answered, and a no is
remembered for that version in Troupe's state directory (onboard.json). Nothing re-runs
by itself, and a headless run (troupe run) prints the line and asks nothing.