Other tools' instruction files are onboarded once, their substance into the AGENTS.md beside them and their rules into .troupe/rules/, a new AGENTS.md is its own question, a session's start proposes and never writes, and onboarding and the brief carry a version¶
Decision 827 · accepted · 2026-10-10 · issue #516
Issue #516, slice 2, and the maintainer's decisions for this chunk's second wave: other
tools' instruction files stop being read at run time (Decision 828 removes the readers)
and are onboarded once instead; Cursor's rules are onboarded too, not read; onboarding
proposes by itself and never writes by itself; creating an AGENTS.md that does not exist
is asked as its own question; and what onboarding writes, and the librarian's brief,
record the version of the rules that wrote them.
- A source for instruction files.
Troupe.Onboard.Instructionsis registered first in@sources.CLAUDE.mdandGEMINI.md(at the root and in any directory), and.github/copilot-instructions.mdat the root only (Decision 806: Copilot reads it nowhere else, so a nested one is skipped), are other tools' names for a directory'sAGENTS.md. They make one proposal per directory, for theAGENTS.mdin that directory: the first file found, in the orderCLAUDE.md,GEMINI.md, Copilot's, issourceand the othersalso_from, so a change to any is drift and a new proposal. Rules make one proposal each:.cursor/rules/*.mdc(the root's and a directory's), the root's legacy.cursorrules(always applied), and Copilot's.github/instructions/*.instructions.md(the root's) become.troupe/rules/<name>.md. Found astroupe instructions checkfinds files:.gitignore,node_modules, a nested repository and hidden directories other than.githuband.cursorare not entered, and the root's own files are looked for by name whatever.gitignoresays, since their tools read them anyway. A file linked out of the workspace is not read; aCLAUDE.mdthat is the directory'sAGENTS.mdunder another name gives nothing; each is listed as skipped with why, as is a nested Copilot file or.cursorrules, a rule in a folder under.cursor/rules, an empty file, and one whose every unit is said already. - Claude Code's other names, and the person's own files. Once the readers are retired
(Decision 828), files the loader read as a person's own
AGENTS.mdwould stop counting with nothing to bring them in, so the source covers them too. A repository's.claude/CLAUDE.md(Claude Code's other place for its project file) is one more name for the root'sAGENTS.md, added afterCLAUDE.mdand beforeGEMINI.md; its@imports are read from the root once there, which its note says. The person's own<config>/CLAUDE.mdand<config>/GEMINI.md(the config directory's other names for itsAGENTS.md, which the loader read as such) and Claude Code's~/.claude/CLAUDE.mdbecome one proposal for<config>/AGENTS.md,target: :user, merged the same way: the writer's existing user target, recorded in<config>/onboarded.json, and asked whateverauto_approvesays when the librarian writes it (Decision 823). Each is named from the home directory (~/...), as a:usersource must be; a config directory kept outside the home directory is skipped with a sentence, since onboarding takes the person's own files from there only. Sources are now givenconfig_dirbesidehome.CLAUDE.local.mdis Claude Code's personal file, usually not committed: it is never proposed into a file that is, and is skipped with how to keep it, moved by hand into<config>/AGENTS.mdor left where it is. A session's notice asks only for the workspace's proposals: the person's own would be news in every workspace's first session. It asks the sources for them alone (targets: [:workspace, :repo], whichTroupe.Onboard.plan/2passes to every source and holds their proposals to), so a start reads nothing in the person's home or config directory; counting the workspace's after the sources had read and hashed~/.claude/CLAUDE.mdand<config>/CLAUDE.mdread the person's files at every first start only to drop them.troupe onboardasks for every target. No mapping of a file already onboarded changes, so the version stays 1. - Merge, don't duplicate, judged conservatively. The
AGENTS.mdthat is there is kept byte for byte (its Windows line endings too) and what each other file adds comes after it. A file is read as Markdown units: a paragraph, a list item, a fenced block, a table, a heading. A unit is said already, and left out, in exactly two cases: its text equals a unit of the directory'sAGENTS.md, of its.agents/AGENTS.md, or of a file before it in the same proposal, spaces aside; or it is, introupe instructions check's terms, the same rule as one of theirs (a paragraph or list item of five words or more, compared without case, code marks, emphasis or a final period:Check.Text's rules, so the check and onboarding never disagree about what a duplicate is). Nothing else counts: a reworded rule is proposed, and the person reads the diff, since a duplicate in anAGENTS.mdcosts a few characters and a dropped rule is lost; a file's own repeats are its own business, as the check says. An added unit keeps the heading it was under, written once before it (a file's title only when nothing is there yet). A line that only imports theAGENTS.mdbeing written (@AGENTS.md, Claude Code's way of pointing at it) is left out with a note, and a first heading naming the other tool's file (# CLAUDE.md) is written# AGENTS.mdin a new file and left out of an addition to one. When nothing is left to add, nothing is proposed: the file is skipped, "everything it says is in AGENTS.md already", which is also what a second run says once its proposal was written. Not chosen: a section-level merge (a matching heading would hide new text under it), or a model's paraphrase (#516: the onboarding step must be reviewable and the same files must give the same proposals). - Rules keep Decision 809's meaning. A rule is Markdown with
description,globs(a YAML list of quoted strings, which 809's line reader and YAML both read) andalwaysApply: true, then the body; only the keys that say something are written, and any other key is left out with a note. The front matter is read as 809 read.mdcfiles (a line per key;globsa comma-separated string, a list, or-lines), byTroupe.Instructions.FrontMatter, the one reader the loader reads.troupe/rules/with (Decision 828), so a rule onboarding read one way is never read another once written. A directory's rule is read from the root once in.troupe/rules/, so its globs are rewritten from the root as 809 matched them from its directory (src/**underweb/isweb/src/**, a glob without a/isweb/**/<glob>), and itsalwaysApplybecomesglobs: ["web/**"], which is when Cursor and 809 applied it; a description-only one is listed everywhere now, which its note says. Copilot'sapplyTois its globs;**,**/*or*isalwaysApply: true. A rule with nothing that says when it applies is still proposed, with a note that no session joins it by itself. Names are made lowercase with dashes (Docs Guide.mdcisdocs-guide); a directory's rule is named after the directory first (web-style); two that come out the same are told apart by a number, the root's Cursor rules first, then.cursorrules, then Copilot's, then the directories'. G26 reads them (Decision 828). - opencode's
instructions(version 2).opencode.json'sinstructions(andopencode.jsonc's, read first, as opencode reads.jsonover it) is a list of more files opencode joins into every prompt besideAGENTS.md, each a path or a glob, which opencode looks for from where it runs up to the repository root; onboarding runs at the root, so they are found from there. opencode's own documentation's examples areCONTRIBUTING.md,docs/guidelines.md,.cursor/rules/*.mdandpackages/*/AGENTS.md. Each file named becomes an addition to the root'sAGENTS.md, merged as the other tools' files are (after them, in the order named, asalso_from, so a change to one is drift), with its front matter left out and a note saying so, since opencode joined every one into every prompt and the root'sAGENTS.mdis what every prompt has. A glob in the list does not make a rule: it says which files, not when they apply, and opencode applied each always. A file whose own front matter scopes it is a rule:globswithoutalwaysApply: true, read by the one front-matter reader, becomes.troupe/rules/<name>.mdwith those globs (from the root, as the file says them), after the other rules in the name order, with a note that opencode joined it always and its globs now say when it joins, as Cursor read them (the.cursor/rules/*.mdof opencode's own example are such files). Not chosen: every file a rule (an always rule is anAGENTS.mdaddition under another name, and keeps the substance from the file every tool reads); an@import inAGENTS.md(other tools readingAGENTS.mddo not follow it, and nothing is recorded to drift from). Skipped, each with its sentence onopencode.json: a URL (opencode fetches it; onboarding takes only the workspace's files), a path outside the workspace (~/, absolute, or out through..), an entry that matches no file, one that is not text; and a file named that is anAGENTS.md(Troupe reads it in its directory), Troupe's own under.troupe/, or another tool's file this source takes on its own (CLAUDE.md, a Cursor rule), so nothing is proposed twice. A file linked out of the workspace is skipped as the others are. The person's own~/.config/opencode/opencode.jsonis not read.found?/1looks foropencode.jsonandopencode.jsonctoo. This changes what onboarding writes for the same files, soTroupe.Onboard.version/0is 2, and a workspace onboarded under version 1 is told once to runtroupe onboardagain. - The writer's new targets.
rules/<name>.mdjoins the repository's whitelist (not the person's: no reader looks for<config>/rules/). And a third target,:workspace, writesAGENTS.mdand onlyAGENTS.md, at the workspace's root or in a directory of it: every other name, a directory whose name starts with a dot (.git,.troupe,.agents, whoseAGENTS.mdis that directory's other file), a directory that is not there (onboarding makes none: anAGENTS.mdis written beside the files it came from), and a path that resolves, links followed, outside the workspace or into a hidden directory are refused. Its provenance goes in the workspace's.troupe/onboarded.json, under aworkspacesection besidefiles, keyed by its path from the workspace (a skill's ownAGENTS.mdunder.troupe/skills/cannot collide with it), and a.troupethat links out refuses the write before anything is written. Its source is a repository file, as:repo's is.drift/2reads the section, and a manifest key that names no file onboarding writes there is not taken for a record, in either section. - A new
AGENTS.mdis its own question. Every coding tool reads that file, so creating one commits every other tool too (#516's seventh decision).plan/2marks a proposalquestion: :create_agents_mdwhen itsAGENTS.mdis not there,:writeotherwise.troupe onboardasks it in its own words, "AGENTS.md is not there. Create it? Every coding tool reads AGENTS.md, not only Troupe.", and--yesnever answers it: the file is left, the line says why, the summary counts it, and the run still exits 0.--jsongives each proposalquestion(create_agents_mdorwrite) and, with--yes, a leftAGENTS.md"written": falsewith the reason, not counted as a failure. Adding to anAGENTS.mdthat is there is an ordinary proposal, shown as "adds to the one that is there". Theonboard_writetool'starget: "workspace"asks always, astarget: "user"does (must_ask?/1, whateverauto_approveor the profile says): the call cannot tell a new file from an addition before it runs, and anAGENTS.mdis every tool's, so an unasked write to it is never right. The librarian's prompt tells it to make the call that creates one on its own, so the approval asks exactly that. - A session's start proposes, never writes.
Troupe.Onboard.Notice.due/2, asked byTroupe.start_session/1for a local session with no bundle on a machine no worker runs on, gives oneonboarding_suggestedevent (additive to the protocol) or nothing. In a workspace with other tools' files, nothing onboarded (no.troupe/onboarded.json, no file recording where it came from) and nothing declined, it counts whattroupe onboardwould propose by kind (instructions,rules,agents,commands,skills,workflows,mcp), never the content, and says how to run it. It asks only the sources whosefound?/1, a new optional callback ofTroupe.Onboard.Source, finds their files at the workspace's root, so a workspace with none costs a fewstatcalls a start; a repository whose only other-tool file is nested is found bytroupe onboardbut not announced. The terminal UI shows the event'smessageas a line. Once per workspace and version: what was said is remembered in the state directory'sonboard.json(suggested, keyed by the workspace's real path, with the versions said), beside the person's declines and never in the repository; onboarding the workspace or declining a proposal in it ends the first notice for good. Not chosen: a notice at every start until onboarded (noise in every session of a repository the person has decided to leave as it is), or remembering it in.troupe/(a write into the repository nobody asked for). - Versions.
Troupe.Onboard.version/0(2; 1 until opencode'sinstructionswere onboarded) is the version of the onboarding rules, raised in the pull request that changes what any source writes for the same files. Every file written records it asimported_version(last in a frontmatter, so the lines a drift finding names stay where they were; in a manifest entry). The manifest records, asonboarding, the version the workspace was onboarded under as a whole: set when the manifest is first written (every write now writes it, so it is the one place that says a workspace was onboarded) and raised only bystamp/1, whichtroupe onboardcalls after a run that left nothing unanswered (--jsonwithout--yes, nobody to ask, or a newAGENTS.md--yesleft, stamp nothing), never by one file's write, so the librarian bringing one file in under newer rules does not mark the rest current. A manifest from before versions is version - A file recorded under older rules from unchanged sources is left alone when the new
rules would write the same content, and otherwise offered once as a diff, so a change of
rules is shown and the person's own edits are not taken back unasked. A workspace
onboarded under older rules is told, at a session's start, to run
troupe onboardagain, once per version, andtroupe instructions checkreports it as a finding of its own kind,outdated, on the manifest'sonboardingline: it comes fromTroupe.Onboard.drift/2, which the check already prints; the check's@type kindand its documentation name it besidedrift. The brief has its own:Troupe.Memory.survey_version/0(1), written assurveyin.troupe/memory.md's frontmatter whenever a brief is stamped as built or checked (Memory.stamp/3). Beside it the brief'sheadis written quoted (head: "4572e29"): YAML reads a bare short hash of digits and oneeas a float and one of digits with a leading zero as a number without it, and a brief read and written again then carried4.572e32. A head an older build wrote bare reads back as the one word on its line; one that is not a word there ([4572e29]) cannot be told from what YAML made of it and reads as no head, which decides nothing (stale?/2ignores it) and the next refresh writes again. A brief with an oldersurvey, or none, is told at a start to be written again with/memory refresh, in the same notice, once per survey version. Nothing re-runs either, and an older brief is not called stale:memory_auto_refreshstill asks only for absent or stale ones (Decision 649's client rule). - The librarian. Its prompt says what is in every prompt now (
AGENTS.md,.agents/AGENTS.md,.troupe/rules/) and that other tools' files are not; its first step is an onboarding pass that finds them, reads them, and proposes each throughonboard_write(anAGENTS.mdaddition that keeps what is there and repeats nothing, a rule with 809's front matter), and never creates anAGENTS.mdbut by a call of its own. The brief still never copies whatAGENTS.mdsays (Decision 649), nor what the person did not let it onboard.
Governs: apps/troupe_core/lib/troupe/onboard.ex, apps/troupe_core/lib/troupe/onboard/instructions.ex, apps/troupe_core/lib/troupe/onboard/notice.ex, apps/troupe_core/lib/troupe/onboard/source.ex, apps/troupe_core/lib/troupe/tools/onboard_write.ex, apps/troupe_core/lib/troupe/instructions/front_matter.ex