--- name: onboarding description: "Set a project up and decide what to do next: read what's connected and how each agent is doing, connect what's missing, then offer to build, improve or optimize. Use when someone starts, or asks to set up their project." metadata: min-cli-version: "0.76.0" next: "build-brainstorm" --- # Onboarding A new project needs three things before an agent is worth building: a home for the agent's code, a place the team talks to it, and the tools the team works in. Ask about each in turn, connect what the owner chooses, and hand over to build. Every step reads what already exists first and asks only about what is missing, so running onboarding again picks up where it stopped, and "later" stores nothing: the next run asks again. ## Before you start - **Make sure the CLI is here and current:** if `introspection --version` isn't found, install it with `npm i -g @introspection-ai/cli`; if it's older than this skill's `min-cli-version`, run `introspection upgrade`. Say in one line what you installed. - **Make sure you're logged in:** `introspection whoami` exits 0 even when logged out, so read its `logged_in`, then prove the login with `introspection runtimes list --query "length(@)"`. On the platform you're already logged in. If `logged_in` is false or that call says the session is missing or expired, tell the owner in one line that you're opening a sign-in, then run `introspection login` with a bash timeout of 600 seconds: it opens the browser and returns once they've signed in. If no browser opens, give them the link and code it prints. Check again before going on, and stop if it still fails. - **Say nothing about these checks when they pass,** on the platform above all, where the owner is always signed in: no "I checked your project" or "you're signed in". Speak only to report something you fixed or something missing, in one line, and otherwise open with the first step's question. ## Read the project first Before the first question, read everything at once, in one shell call, so no question asks about something already set up: ```sh introspection runtimes list --query "[?kind!='platform'].[slug, runtime_group_id]" introspection repositories list --query "[].[name, provider]" introspection integrations repositories --type github --query "length(records)" ``` The last fails with "no active GitHub integration" when GitHub isn't installed. The CLI can't read Slack, Linear or a productivity suite yet: their steps ask. - **No agent of its own yet** (the first list is empty; the platform's own runtimes, `kind: platform`, don't count): take the steps below, skipping each the read already answers. - **An agent already exists:** onboarding is done. Don't ask its questions; go to [what's next](#whats-next). ## How a step reaches the person Every choice is a question with the question tool (`ask_user_question`), one decision per call, never a numbered list in your reply. Every connection is something the person does in their browser. Ask for it with `introspection_open` and `wait: true`, on its own in a turn, naming the target, never a link. The result is `Answer: connected`, `Answer: failed: `, or a decline. | Host | The question tool | `introspection_open {target, wait: true}` becomes | | --- | --- | --- | | The Operator, hosted or `introspection operator` | `ask_user_question` | The tool itself. | | Claude Code, Codex, any host without the tool | A question tool you can see in your tool list, if there is one; otherwise one short question with its options in your reply, and wait for the answer | Run the CLI command that waits, then read its exit: `introspection connectors authorize --subject user` for a connection, `introspection open --runtime --wait` for a page. An integration (GitHub, Slack): `introspection open --integrations --wait` when `introspection open --help` lists it, which opens the organization's integrations page on that provider and returns once it's connected (it fails when it isn't); otherwise send them to **Organization settings → Integrations** and ask them to say when they're done. A connector or sign-in has no command: tell the owner where to go in the dashboard and ask them to say when they're done. Then check it. | **An answer is what the person did, not proof.** After `connected`, read the real state with the command each step names before saying it works. After a decline, record nothing and move on. After `failed`, say what the provider said in one line and offer to try again or move on. ## Steps Take them in order, one at a time: a step's question, then its connection, then the next step's question. They aren't independent questions, so never ask them together in one turn: what the owner connects in one step can change the next. 1. `onboarding-repository`: where the agent's code lives. 2. `onboarding-issues`: where its agents track work (Linear; Jira to follow; or Introspection's own issues). 3. `onboarding-collaboration`: where the team talks to it. 4. `onboarding-productivity`: the productivity suite the team uses (asked only; connecting it isn't available yet). Tell the owner what you're doing in plain words ("Next, where your team talks"), never a skill's name. ## What's next When the project already has an agent, or the owner asks what to do, show them where things stand first. Read every agent's last week at once, then look closer at the most urgent, as [the project's status](references/project-status.md) says: conversations, cost, tool and model errors, patterns that are new or growing, and issues waiting on a person. Say in two or three lines what needs attention and why, then ask one question with the question tool, header "Next": - **Build a new agent.** Always offered. - **Improve :** fix what it gets wrong. Offered for an agent with conversations; recommended for the agent that needs attention, naming what to fix first. - **Make better overall:** quality, cost or speed against its cases (optimize). Offered for an agent with conversations and cases. An agent with no conversations yet has nothing to improve from: say so, and offer to test it (deploy-test) instead. Go to the phase the owner picks: `build-brainstorm`, `improve-collect`, `optimize-quality` or `deploy-test`. ## Done when - Each step is connected or answered, or the owner said later. - Say in two or three lines what is connected and what was left for later, then go straight on to build: read `build-brainstorm` and start it in the same turn with its first question, how to start the new agent (from scratch or from a template), with the question tool. Ask what the agent should do only after they choose from scratch. Don't stop to ask whether to continue.