Onboard into a project
- For
- A developer joining a project that is new to them
- When
- Day one, or any time you pick up an unfamiliar repo
- Takes
- About five minutes of agent time
- You get
- A draft project primer in onecell, a few remembered facts every later agent session starts with, and the three things to read or ask first
Onboard me to <repo> using onecell. Save the result to <cell> (default: my Inbox). 1. Check onecell first. Call list_cells, then search for the project and repo name, and list_decisions for any cell that covers it. Open only the hits you will use with get_document, and cite them as cell · heading · passage. Don't repeat what onecell already holds; link to it. 2. Read the repo without changing anything: the README, CONTRIBUTING, AGENTS.md or CLAUDE.md, package manifests, entry points, CI config, `git log --oneline -30` and the open branches. 3. Draft a document titled "Project primer: <repo>" with create_document (dry run first). Include: - What it is, in three sentences, and a stats block of headline numbers - A mermaid diagram of the main components and how requests flow - Run it locally: a steps block with the exact commands - Conventions: a table of rules, each with the file it comes from - Recent activity: a timeline of notable merges - Decisions already made (cited), and open questions as a checklist - Where things live: bookmarks 4. Call recall for <repo>, then remember 3 to 5 durable facts with entity "<repo>": how to run the tests, how it deploys, who owns it. If a fact contradicts one onecell already holds, tell me instead of replacing it. 5. Reply with the document link and the three things I should read or ask first. Keep the document a draft; don't publish or share it unless I ask.
What your agent does
Checks what onecell already knows
list_cells, search and list_decisions find earlier notes and accepted decisions about the project, so the primer links to them instead of starting from nothing.Reads the repo, read-only
The README, contribution and agent guides, manifests, CI config and recent git history. Nothing in the repo changes.Writes the primer as a draft
create_document, dry run first, into the cell you named or your private Inbox.Remembers the durable facts
recall first, then remember a few facts under the repo's name, so the next agent session, in any tool, starts informed. Conflicts come back to you rather than being overwritten.Tells you where to start
A link to the primer and the three things to read or ask first.
What you get back
Open the full example →A primer for Tally, a made-up invoicing app. Note the open questions at the end: they are the part to take to the team.
Sample project primer: the Tally repo, for a new engineer
What Tally is
Tally sends invoices for freelancers and small studios, chases late ones with polite reminders, and takes card and bank payments through Stripe. About 2,300 paying accounts. The team is seven people; Sam Okafor leads engineering.
How the repo is laid out
| Path | What lives there |
|---|---|
| app/ | The web app (Next.js): invoices, clients, settings |
| lib/billing/ | Invoice totals, taxes and currencies; the part with the most tests |
| lib/reminders/ | Late-payment reminders, now moving onto the job queue |
| jobs/ | The background worker: reminders, exports, Stripe webhooks |
| db/migrations/ | Postgres schema, numbered; run on every deploy |
Run it
pnpm install
pnpm db:up # Postgres in Docker
pnpm migrate
pnpm dev # app on :3000
pnpm worker # background jobs, in a second terminalRead these three first
Decision: retry failed payments three times, then stop
Explains the payment states you will see everywhere in
lib/billing.Postmortem: invoice reminders sent twice
Why reminders are moving to the job queue, and what to be careful of there.
Handoff: moving reminders to the job queue
Where that work stands today. It is the most likely first task.
What onecell already knew
Twelve documents in the engineering cell, four decisions, and two facts worth knowing on day one: production deploys go out from main after review, and the worker must never send an email outside 8am–8pm in the client's time zone.
Open questions for your first week
- Why do invoice numbers have their own sequence per account rather than a global one?
- Who owns the Stripe webhook secret rotation?
Variations
Joining a team that already uses onecell
Point it at the team's hive: set <cell> to the hive and add “Search the hive before reading the repo, and treat what's there as the source of truth.” Publish the primer only after a teammate has read it, so the next new joiner finds a checked version.
Onboarding someone else
A lead runs the recipe before the new hire starts, then adds: “Write it for a new engineer named <name>, and end with a first-week checklist.” Share the cell with them, as a viewer to start.
Briefing a new agent instead of a person
Ask for a short agent brief instead of a primer: the conventions and the commands only. Then have it add a pointer to the primer's cell in the repo's AGENTS.md or CLAUDE.md, so every agent that opens the repo knows where to look.
Tips
- Keep the primer a draft until someone who knows the project has read it.
- Run it again after a big release: it updates the timeline and catches docs that have drifted.
- The open questions are the valuable part. Take them to the team instead of guessing.
- To keep up week to week, follow it with Recipe: repo snapshot.