/iblai-vibe-start
Ask four questions, write the answers down, route. Every later skill reads
the answers instead of asking again. Takes two minutes; prevents the two
expensive mistakes (building a single-org app that needed to be multi-org,
and wiring SSO into something that only needed a server token).
Words: docs/glossary.md.
Sign-in mechanics and the three architectures in full: docs/auth-model.md.
The entities every app is built on: docs/domain-model.md.
Step 0: Skip what is already answered
Read iblai.env if it exists. These keys are the record of this conversation;
any that are present are settled — ask only the missing ones:
PROJECT=new | existing
ARCHITECTURE=single-org | multi-org | headless
ACCESS=members | public | none
DOMAIN_FOCUS=users,memories,agents,organizations # comma-separated subset
If all four are present, say so in one line and go to Step 5.
Step 1: New or existing?
Is this a new project, or am I adding ibl.ai to an existing codebase?
- Look before asking: no
package.json → new. A package.json with next →
existing Next.js app. Anything else (Vite, Remix, Expo, a Python backend) →
existing, and note the framework — the ui skills target Next.js; the api
skills work anywhere.
Step 2: One organization, many, or none?
Who is this for?
- One organization — mine, or one customer I deploy it to. Members sign in; the app is pinned to that org. (most apps)
- Many organizations — one deployment, users move between orgs, like os.ibl.ai.
- No sign-in at all — a script, a CI job, or my own backend calling the platform.
Map to ARCHITECTURE=single-org | multi-org | headless. Explain in one
sentence why it matters: single-org pins the org key and uses one
server-to-server token; multi-org puts the org in the URL and re-authenticates
per org; headless never touches SSO. Recommend single-org when unsure —
everything carries over to multi-org later.
Step 3: Who signs in?
Skip when ARCHITECTURE=headless (ACCESS=none).
Who reaches the app?
- Members only — people who belong to the organization (invited, or self-joined). (default)
- The public too — at least one agent is reachable without an account (a public assistant, a lead-capture bot, a demo).
Map to ACCESS=members | public. public means: mark that agent
allow_anonymous and leave its route out of AuthProvider's protection
(docs/auth-model.md §4).
Step 4: What is it about?
Which of these does the app revolve around? Pick all that apply:
- Users — profiles, per-user settings, roles and admins
- Memories — the app remembers things about each person; agents personalize
- Agents — creating or configuring agents, not just chatting with one
- Organizations — org-level settings, branding, billing, many customers
Map to DOMAIN_FOCUS=…. Most apps say "users and agents"; that is fine.
Step 5: Record and route
Write the four keys to iblai.env (create the file from
iblai.env.example when missing; keep existing lines).
If a project CLAUDE.md / AGENTS.md exists, add or replace a
## Decisions block:
## Decisions (from /iblai-vibe-start)
- Project: new | existing (<framework>)
- Architecture: single-org | multi-org | headless — <one line why>
- Access: members | public (<which agent is public>) | none
- Focus: users, memories, agents, organizations
Credentials: run /iblai-vibe-connect (browser round trip; falls back to
manual questions). Skip it when iblai.env already holds a real PLATFORM
and TOKEN, or the host exports IBLAI_API_KEY.
Route — say which skill you are opening and why:
| Answers |
Next |
new + single-org |
/iblai-vibe-ops-init — vibe-starter already is this architecture (pinned org, /setup, admin area, user + org settings) |
new + multi-org |
/iblai-vibe-ops-init, then /iblai-vibe-auth → "Going multi-org" (the OS pattern: org in the URL, TenantSwitcher, per-agent anonymous rule) |
existing Next.js + single-org / multi-org |
/iblai-vibe-auth (providers, store, SSO callback), then the feature skills for the focus |
existing non-Next.js, any ACCESS |
The api family: /iblai-api-login, then /iblai-vibe-api's server-route pattern adapted to the framework; the SDK's React components need Next.js |
headless |
/iblai-api-login, then the iblai-api-* skill per family; tutorials/ for end-to-end recipes |
ACCESS=public (any) |
after the above: /iblai-vibe-agent-setting (allow_anonymous) and docs/auth-model.md §4 |
- Then by focus:
| Focus |
Open |
| users |
/iblai-vibe-profile ★, /iblai-vibe-user-metadata ★, /iblai-vibe-admin |
| memories |
/iblai-vibe-memory-guide ★ |
| agents |
/iblai-vibe-agent-create ★ → /iblai-vibe-agent-setting ★ → /iblai-vibe-agent |
| organizations |
/iblai-vibe-org-metadata, /iblai-vibe-account, /iblai-vibe-pricing |
Always finish with /iblai-vibe-ops-test before showing work, and mention
/iblai-vibe-ops-deploy / /iblai-vibe-ops-build as the way to ship.
Notes
- Never ask for a password, and never for the Platform API Token before
/iblai-vibe-ops-init or /iblai-api-login needs it (they say where it
comes from).
- The answers are not permanent: re-run this skill to change them; the
record in
iblai.env is the source of truth for later skills.
- Installed skills are a copy — if
.claude/skills/iblai-vibe/SKILL.md is
older than two weeks, suggest /iblai-vibe-ops-upgrade first.
1---2name: iblai-vibe-start3description: The first conversation for anything on ibl.ai — four questions that decide the whole shape of the work before any file is touched (new project or existing codebase; single-organization app, multi-organization app, or headless server-to-server; who signs in — members, the public, or nobody; which of users, memories, agents, and organizations the app is about), recorded in iblai.env and the project CLAUDE.md, then routed to the right skills. Use when the user says "start", "I want to build", "new app", "integrate ibl.ai into", "add ibl.ai to my project", "which skills do I need", "where do I start", or describes an app with users, agents, organizations, or memories without saying which. For scaffolding see /iblai-vibe-ops-init; for adding sign-in to an existing app see /iblai-vibe-auth; for headless work see /iblai-api-login.4---56# /iblai-vibe-start78Ask four questions, write the answers down, route. Every later skill reads9the answers instead of asking again. Takes two minutes; prevents the two10expensive mistakes (building a single-org app that needed to be multi-org,11and wiring SSO into something that only needed a server token).1213> Words: [docs/glossary.md](https://raw.githubusercontent.com/iblai/vibe/refs/heads/main/docs/glossary.md).14> Sign-in mechanics and the three architectures in full: [docs/auth-model.md](https://raw.githubusercontent.com/iblai/vibe/refs/heads/main/docs/auth-model.md).15> The entities every app is built on: [docs/domain-model.md](https://raw.githubusercontent.com/iblai/vibe/refs/heads/main/docs/domain-model.md).1617## Step 0: Skip what is already answered1819Read `iblai.env` if it exists. These keys are the record of this conversation;20any that are present are settled — ask only the missing ones:2122```23PROJECT=new | existing24ARCHITECTURE=single-org | multi-org | headless25ACCESS=members | public | none26DOMAIN_FOCUS=users,memories,agents,organizations # comma-separated subset27```2829If all four are present, say so in one line and go to **Step 5**.3031## Step 1: New or existing?3233> Is this a **new project**, or am I adding ibl.ai to an **existing** codebase?3435- Look before asking: no `package.json` → new. A `package.json` with `next` →36 existing Next.js app. Anything else (Vite, Remix, Expo, a Python backend) →37 existing, and note the framework — the `ui` skills target Next.js; the `api`38 skills work anywhere.3940## Step 2: One organization, many, or none?4142> Who is this for?43> - **One organization** — mine, or one customer I deploy it to. Members sign in; the app is pinned to that org. *(most apps)*44> - **Many organizations** — one deployment, users move between orgs, like os.ibl.ai.45> - **No sign-in at all** — a script, a CI job, or my own backend calling the platform.4647Map to `ARCHITECTURE=single-org | multi-org | headless`. Explain in one48sentence why it matters: single-org pins the org key and uses one49server-to-server token; multi-org puts the org in the URL and re-authenticates50per org; headless never touches SSO. Recommend **single-org** when unsure —51everything carries over to multi-org later.5253## Step 3: Who signs in?5455Skip when `ARCHITECTURE=headless` (`ACCESS=none`).5657> Who reaches the app?58> - **Members only** — people who belong to the organization (invited, or self-joined). *(default)*59> - **The public too** — at least one agent is reachable without an account (a public assistant, a lead-capture bot, a demo).6061Map to `ACCESS=members | public`. `public` means: mark that agent62`allow_anonymous` and leave its route out of `AuthProvider`'s protection63(docs/auth-model.md §4).6465## Step 4: What is it about?6667> Which of these does the app revolve around? Pick all that apply:68> - **Users** — profiles, per-user settings, roles and admins69> - **Memories** — the app remembers things about each person; agents personalize70> - **Agents** — creating or configuring agents, not just chatting with one71> - **Organizations** — org-level settings, branding, billing, many customers7273Map to `DOMAIN_FOCUS=…`. Most apps say "users and agents"; that is fine.7475## Step 5: Record and route76771. Write the four keys to `iblai.env` (create the file from78 `iblai.env.example` when missing; keep existing lines).792. If a project `CLAUDE.md` / `AGENTS.md` exists, add or replace a80 `## Decisions` block:8182 ```markdown83 ## Decisions (from /iblai-vibe-start)84 - Project: new | existing (<framework>)85 - Architecture: single-org | multi-org | headless — <one line why>86 - Access: members | public (<which agent is public>) | none87 - Focus: users, memories, agents, organizations88 ```89903. Credentials: run `/iblai-vibe-connect` (browser round trip; falls back to91 manual questions). Skip it when `iblai.env` already holds a real `PLATFORM`92 and `TOKEN`, or the host exports `IBLAI_API_KEY`.93944. Route — say which skill you are opening and why:9596| Answers | Next |97|---|---|98| `new` + `single-org` | `/iblai-vibe-ops-init` — vibe-starter already is this architecture (pinned org, `/setup`, admin area, user + org settings) |99| `new` + `multi-org` | `/iblai-vibe-ops-init`, then `/iblai-vibe-auth` → "Going multi-org" (the OS pattern: org in the URL, `TenantSwitcher`, per-agent anonymous rule) |100| `existing` Next.js + `single-org` / `multi-org` | `/iblai-vibe-auth` (providers, store, SSO callback), then the feature skills for the focus |101| `existing` non-Next.js, any `ACCESS` | The `api` family: `/iblai-api-login`, then `/iblai-vibe-api`'s server-route pattern adapted to the framework; the SDK's React components need Next.js |102| `headless` | `/iblai-api-login`, then the `iblai-api-*` skill per family; `tutorials/` for end-to-end recipes |103| `ACCESS=public` (any) | after the above: `/iblai-vibe-agent-setting` (`allow_anonymous`) and `docs/auth-model.md` §4 |1041055. Then by focus:106107| Focus | Open |108|---|---|109| users | `/iblai-vibe-profile` ★, `/iblai-vibe-user-metadata` ★, `/iblai-vibe-admin` |110| memories | `/iblai-vibe-memory-guide` ★ |111| agents | `/iblai-vibe-agent-create` ★ → `/iblai-vibe-agent-setting` ★ → `/iblai-vibe-agent` |112| organizations | `/iblai-vibe-org-metadata`, `/iblai-vibe-account`, `/iblai-vibe-pricing` |113114Always finish with `/iblai-vibe-ops-test` before showing work, and mention115`/iblai-vibe-ops-deploy` / `/iblai-vibe-ops-build` as the way to ship.116117## Notes118119- Never ask for a password, and never for the Platform API Token before120 `/iblai-vibe-ops-init` or `/iblai-api-login` needs it (they say where it121 comes from).122- The answers are not permanent: re-run this skill to change them; the123 record in `iblai.env` is the source of truth for later skills.124- Installed skills are a copy — if `.claude/skills/iblai-vibe/SKILL.md` is125 older than two weeks, suggest `/iblai-vibe-ops-upgrade` first.
iblai