Skip to main content
Onboarding is a conversation with your own agent. It reads before it asks, interviews you in rounds, then shows you every word before saving. Run it once your agent is connected:
Your agent does the looking. You do the deciding. It should not ask you to type something it could have read.

​
What happens, in order

1

Which repos are this project

It names the repo you are standing in, lists the others on your GitHub account by most recent push, and asks which of them belong to this project. Add anything the list cannot see — a repo you contribute to but do not own, or one that is not on GitHub at all.
2

It reads them

Your agent builds a local digest of those repos: descriptions, READMEs, languages, recent pull requests, open issue counts, ninety days of commit subjects, branches, layout, package manifests.This step runs entirely on your machine. No model sees it but your own agent, and nothing leaves your computer.If a repo could not be read (not cloned, private, org behind SSO), it names the repo and asks about it. It does not treat the gap as a small project.
3

The interview

Short rounds, a few questions at a time, each with the answer it would give. In Claude Code these are the usual multiple-choice prompts.It starts from what it already believes, so the first round is you correcting, not explaining from scratch. It is trying to learn: a sentence you would recognise as yours, who it is for, what success looks like and by when, what is built versus planned, the decisions the code cannot show, and what worries you.Stop whenever you like. The graph is built to be added to.
4

It writes what your project is

Two standing documents. Overview (what the project is and how you work) is in every future session. Positioning is optional, fetched when needed.You see the full text and say yes before anything is saved. A save with no preview in the last thirty minutes is refused, and so is one whose text changed after you read it.
5

It writes your plan

Phases, the enablers under each, and a handful of starter cards — shown to you as a shape first, saved only after you agree. Same thirty-minute preview rule.Expect it sparse: two to four phases, a few enablers each.
6

It draws your factory map

Finally it proposes districts and modules, each tied to files it actually saw. Agree to the list, then open alicein.app/workspace (or refresh if it is already open). The factory map lives under Settings → Show factory tab until you turn it on.

​
Already tracking work somewhere else

If you use Linear, say so during the interview and it comes across in the same session — pulled, mapped into phases, enablers and cards, and grouped so you answer once about the parts it cannot place confidently instead of forty times. Other trackers do not have a puller yet, but your agent can still import them by reading them directly. See Bringing in existing work.

​
If something goes wrong halfway

When the interview ends, your agent writes your answers to a file in the repo before it talks to the workspace. If the workspace is down, it tells you where that file is and lands it when the connection is back.

​
Running it again later

The first write of the plan and the factory map is one-time. If the workspace already has real content, onboarding will not overwrite it. It adds what is missing, card by card, for you to ratify. For everything after the first run, change things directly: drag enablers on the project map, edit standing documents in the knowledge view, or just tell your agent what changed.