The onboarding note in most repositories says something like: clone it, run the setup script, read CLAUDE.md, ask in the channel if anything is unclear. That holds up fine until the person reading it opens the project in a different AI assistant than the rest of you use. They get as far as the instruction file, notice it is named after a tool they do not run, and ask the question nobody wrote an answer for: does any of this apply to me, or am I starting from zero?
Almost all of it applies. The part that genuinely does not transfer is smaller and more specific than people assume, and it is worth naming out loud before their first session rather than letting them discover it by following advice that quietly does not fit their setup.
The onboarding note assumes your tool
The assumption is rarely explicit. It shows up in the small instructions: "use the /review command before pushing", "the linter hook will catch that", "just ask it to read the decisions file". Each of those depends on something configured inside one assistant. A teammate on Cursor or Codex reads them, tries, gets nothing, and reasonably concludes the project's setup is for other people.
Meanwhile the things that actually carry the project knowledge are plain Markdown and work anywhere. Nobody says that part out loud either, so the new person undervalues it.
Two piles: project facts and tool wiring
Before you write an onboarding message, sort your setup into what describes the project and what configures a tool. The first pile travels. The second does not.
| Travels to any assistant | Belongs to one assistant |
|---|---|
CLAUDE.md / AGENTS.md content (conventions, commands, boundaries) | Custom slash commands and prompt shortcuts |
| Decision records and rejected approaches | Tool permission settings and approval rules |
| Saved session transcripts worth rereading | Hooks that run on edit or commit |
| Architecture notes, current-state notes, open questions | MCP server configuration and connected tools |
| Test and build commands | Model choice, context limits, session resume behaviour |
The left column is the onboarding. The right column is local setup each person does once for their own tool, and it is fine for it to differ across the team.
Context that reads the same in a different AI assistant
An instruction file is a Markdown document that explains how to work in this repository. There is nothing tool-specific inside it unless you put something tool-specific inside it, which is the actual thing to check.
Open yours and look for lines that only make sense in one assistant. "Run /deploy-check" is one. "Accept the hook's formatting" is another. Rewrite them as project facts: "Before pushing, run pnpm test and pnpm lint. Formatting is enforced by Prettier with the repo config, so do not hand-format." Now the instruction is true for everyone, and the person who has a slash command for it still has it.
File naming is the other snag. Claude Code reads CLAUDE.md; Codex and several other agents read AGENTS.md. Which files a given tool picks up automatically changes often enough that you should not build onboarding on it. Keep one file as the source of content, point the other at it, and tell the newcomer where the real text lives so they can load it manually if their tool does not. CLAUDE.md vs AGENTS.md: one file or two, without drift goes through the trade-off; writing project instructions your assistant follows covers what belongs in the content itself.
Memory files need no translation at all. A decision record saying why the queue retries three times, dated, with the consequence written down, is equally useful to a session in any tool. So is a note listing what you tried and dropped. That is the highest-value thing you hand a new contributor, and it is also the part most onboarding docs forget to mention because the team has stopped noticing it is there.
The habits that don't survive the switch
Session habits are where cross-tool onboarding gets uneven, and they are hard to document because they feel like personal style.
How you scope a session, when you start a fresh one, whether you work from a written plan or iterate in the chat: these depend partly on the tool and partly on the person. Do not prescribe them. Say what the outcome needs to be instead. "Keep a session to one change so the transcript stays readable" is portable. "Use plan mode" is not.
Two things are worth flagging explicitly in the first message, because getting them wrong is expensive. First, what the assistant is allowed to touch without asking: migrations, anything under infra/, dependency changes. Permission systems differ by tool, so state the rule in prose and let each person enforce it however their assistant does. Second, what must never enter context. Secret handling does not come for free from any tool's defaults, and a new person with a new setup is exactly the moment a .env ends up in a transcript. Keeping secrets out of your AI context is a reasonable thing to send on day one.
First-session checklist for the incoming assistant
Hand this over as-is. It assumes nothing about which tool they opened.
Read before writing code
- The instruction file content, whatever it is called in this repo. If their assistant does not load it automatically, they open it and paste the relevant part into the session.
- The decisions file, most recent entries first. Looking for what is already settled, and for the approaches already rejected.
- The current-state or handoff note, if one exists, for what is half-finished.
Confirm in their own setup
- Build, test and lint commands run locally and match what the instruction file claims.
- Their assistant is not auto-approving edits to paths the team protects.
- Ignore rules cover local env files, and they know what to check before sharing a transcript.
First real task
- Something small with an existing test. Not the refactor.
- Before accepting a suggestion, check it against the decisions file. A fresh session in any tool will happily re-propose the library you removed in March.
- Write down anything they had to ask a human. That answer belongs in project memory, and a newcomer is the only person who can still see what is missing.
A short version of this lives well in the repo itself. Onboarding a new contributor with project context covers the wider handoff; if your team is running several tools permanently rather than just during onboarding, multiple AI assistants on one codebase is the setup to aim at.
Staying assistant-agnostic as the team grows
The drift is gradual. Someone adds a hook, documents it in the instruction file, and six weeks later half the onboarding text only applies to one tool again. A cheap guard: when you write a line into an instruction or memory file, ask whether it would still be true for a teammate using something else. If not, phrase the requirement rather than the mechanism.
Keeping that shared project context as plain files in a versioned repository is what makes it portable in the first place. We built PrjLab for exactly this shape of handoff: instructions, memory and the sessions you chose to keep live in .prjcontext/, pushed with prj push, and a new teammate runs prj clone and reads the same context everyone else has, in whatever assistant they prefer. Nothing is locked inside one tool's session state, so there is no reformatting step before they can start. The getting-started guide walks through the first push if you want to try it on a project you are about to hand over.
