Onboarding Wizard

The onboarding wizard guides you through setting up a new (greenfield) project. It's a 10-step conversational process that helps Trinity understand your project deeply enough to generate good plans — and you can go through it together with your team (see Onboarding with your team).

Your progress is saved automatically to the server — you can close the app and return later without losing any work. The active step is derived from the state you've entered, not stored separately, which means jumping back to an earlier step is always safe.

Overview

The wizard progresses through these steps, in order:

  1. Destination → 2. Plan → 3. Phasing → 4. Design → 5. Stack → 6. Structure → 7. Repos → 8. Roadmap → 9. Business → 10. Skills

Setting up API keys and command-line tools is not a wizard step — you configure services afterward from Project Settings → Secrets, and Trinity prompts you for anything a story actually needs when it needs it.

Two steps are conditional and automatically skipped when they don't apply:

  • Phasing is skipped when your project has a single target (nothing to sequence)
  • Business is skipped when your project has no user-facing targets (i.e., none of Web App, Website, Mobile, or Desktop)

Step 1: Destination

Before you describe anything, Trinity asks where your project's repos will be created and who you act as when it creates them:

  • Host + workspace — the git host (GitHub, GitLab, or a self-hosted Gitea/Forgejo instance) and the owner/organization new repositories land in. Trinity offers the accounts your CLIs (gh, glab, tea) are already signed in to, and Connect account lets you add another. Picking an account that isn't signed in on this device opens a guided CLI login right there.
  • Acting as — which connected identity Trinity uses for this project's git operations.
  • Transport — HTTPS or SSH for the managed git connection.
  • Also set as my default destination for new projects — optionally save this choice so future projects start here.

The step opens with your default destination already selected — your own default in a personal workspace ("Where will this project's repos live?"), the org your team creates repos in for a team ("Confirm where this project's repos live") — so Continue simply confirms it; pick a different workspace to override the destination for this project only. You can change the destination any time before the repos are actually created.

Click Continue to confirm, or Set up later to defer — you can still describe and plan your project, and Trinity falls back to your default destination when it's time to create repos.

Step 2: Plan

The Plan step has two sub-views that flow into each other:

Describe

A conversation where you describe what you want to build. Talk naturally — Trinity acts as a co-thinker, not just a listener:

  • Describe your idea at whatever level you have — vague or detailed
  • Upload reference files — Trinity analyzes images, documents, and fonts to ground the rest of the flow in your actual materials
  • Add reference URLs — websites or tools you want Trinity to learn from
  • Trinity offers interpretations — if you're struggling to articulate something, it'll propose concrete framings for you to react to
  • Risks get surfaced early — if your idea involves significant complexity (real-time, offline, multi-tenant, etc.), Trinity flags it
  • Targets are probed naturally — the conversation steers toward who uses it, what platforms it runs on, and key architectural dimensions

The more context you provide here, the faster the later steps go — many clarify questions will already be answered from this conversation.

Clarify

Once a description has been captured, Trinity asks targeted one-at-a-time questions about specific technical details:

  • Target platforms (Web App, Mobile, Desktop, CLI, API, Website, Library, Extension)
  • Frameworks and languages
  • Database preferences
  • Authentication approach
  • Key integrations

Each question offers options with explanations. If an option carries risk (experimental framework, paid service, EOL, etc.), you'll see a risk badge.

Tip
Trinity prefers free and open-source defaults. Paid services are flagged explicitly.

Step 3: Phasing

Skipped for single-target projects.

When your project has multiple targets (e.g., Web App + Mobile + API), Trinity asks about build order:

  • Which target to build first?
  • Can any targets be built in parallel?
  • Are there dependencies between targets (e.g., Mobile needs API first)?

Step 4: Design

Visual and UX questions, asked one at a time:

  • Color scheme and visual mood
  • Layout style and density
  • Component library preferences
  • Responsive / platform-specific design choices

These answers feed the design guide the agent reads during implementation.

Step 5: Stack

Trinity suggests specific tools and frameworks for each target platform — one target at a time. For each suggestion you can:

  • Accept it
  • Swap it for an alternative (Trinity offers side-by-side options)
  • Find alternatives — the refresh button on each suggestion card asks Trinity to surface a few alternatives in the same category, no chat required
  • Ask about it — a chat lets you discuss trade-offs before deciding
  • Override with your own preference

Stack choices are per-target, so a Web App and a Mobile app can pick independently. Accepted suggestions flow into the stack tracker (so you can see them in Project Settings → Stack later).

Trinity prefers free and open-source tools by default. When a suggestion is paid, it's tagged with 💰 Paid and the rationale leads with the free tier (e.g. "Free tier: 5K events/mo, then $26/mo — fine for solo projects.") so a tag doesn't scare you off a tool that's free for typical use. There's always at least one fully-free option among any set of alternatives.

Trinity's suggestions are grounded in the project description and the framework / tooling answers you gave during Plan — if you said "SvelteKit + IndexedDB" or "local-only, no backend", the suggestions will respect that. The picks aren't guessed from the project name.

Step 6: Structure

Choose how your project is organized in git:

  • Monorepo — a single repo with everything side-by-side in plain folders (e.g. apps/web, apps/mobile, packages/shared) but no declared workspace tooling
  • Turborepo — a single repo with declared workspaces (Turborepo, Nx, pnpm workspaces, or package.json#workspaces)
  • Polyrepo — separate repositories per target, coordinated at a workspace root Trinity manages for you

Trinity generates an ASCII folder tree preview for each option. Your choice determines how many GitHub repos Trinity proposes in the next step.

Step 7: Repos

Trinity proposes repo drafts based on your structure + targets — one for monorepo/turborepo, one per target for polyrepo. For each draft you can edit the name, visibility (public/private), and description before Trinity creates them.

  • Auto-suggested descriptions — Trinity drafts each repo's GitHub description in the background, grounded in your project summary, chosen stack, structure, and the target role each repo plays. Edit any field freely; your edits always win, and a per-repo Regenerate button rewrites a single description on demand. The Regenerate button disappears once the repo has been created on GitHub.
  • "Contains" preview — each card lists the targets that'll land on that repo (e.g. Web App · Customer, API · Backend) so you can confirm placement before submitting. This mirrors the server-side mapping exactly: single-repo projects collapse every target onto the only repo, polyrepo projects use the order from the Plan step with overflow on the primary repo.

When you submit, Trinity creates each repo on GitHub, clones them into the workspace, and kicks off roadmap generation in the background. Until this step completes, no GitHub repo exists yet — the Create New Project screen only registers the project internally.

Step 8: Roadmap

Trinity generates your initial roadmap in four sections — vision, phases, architecture, and design. Pages stream into the project's knowledge vault as they finish, so you don't have to wait for the full roadmap before reading the first one.

Use Next and Back to flip between sections. Each button is enabled as soon as the section it would show has finished generating. Navigation is local to your screen — moving forward and back doesn't trigger any save, so you can re-read sections freely.

Discuss Roadmap opens a single team discussion covering the whole roadmap — vision, phases, architecture, and design all at once. Ask about any section or how the sections fit together; the agent can propose a change to a section's direction or its stack as a card you Apply or Dismiss. Trinity rewrites the affected section based on your feedback (and any other sections that need to cascade), and the change appears in the vault as soon as it's done. Your edits never get clobbered by later sections still streaming in.

When you reach the last section and you're happy with the roadmap, click Continue to advance. The roadmap pages already live in the vault by then — the Continue button just records your approval so the wizard moves on to the next step.

Step 9: Business

Skipped for projects with no user-facing targets.

Trinity auto-extracts business details from the Plan conversation and presents a form for you to confirm or edit:

  • Company / product name
  • Tagline
  • Contact email and phone
  • Address
  • Legal name and copyright
  • Social media links

These fields are used by execution gates — stories that need contact info, footers, or branding will pause with a missing_business_details gate if these fields are empty (unless you've turned on Skip business details check). Always editable later in Project Settings → Business.

Step 10: Skills

Trinity recommends skills from a curated registry based on your stack, and lets you search for more. Selected skills are scaffolded into the workspace trunk's .agents/skills/ directory when onboarding saves; each story worktree gets an overlaid copy at runtime. Core skills (the trinity-app-* set) are always scaffolded regardless of selection. Your project repos themselves stay clean — Trinity only writes AGENTS.md into each repo. The CLAUDE.md pointer file lives at the workspace trunk, not inside the repos.

Onboarding with your team

If your project has more than one member, the Plan step asks whether to onboard as a team: keep the conversation private to you, or make it visible to everyone in the project. When you onboard as a team, the wizard becomes a shared, real-time conversation:

  • See who's here — a row of participant avatars shows everyone in the conversation; replies and answers stream to all of you live.
  • Tag the agent — type @ in the Plan composer or a discussion and pick @agent to pull the onboarding assistant into the conversation. In a shared (team) conversation the agent only replies when it's tagged, so you and your teammates can talk to each other without it jumping in; in a solo conversation it answers every message.
  • Discuss any question — each clarify/phasing/design question card has Chat about this and Discuss something else, which open a side discussion panel. A badge on the card shows who's discussing it and how many messages there are.
  • AI proposals — inside a discussion the AI can propose an answer, a side question, or a stack change as a card you Apply or Dismiss; applied cards show who applied them.
  • Side questions (tangents) — promoting a side question takes the whole team to it and then returns everyone to where you were, with a banner showing who started the tangent.
  • Answer attribution — every answered question shows which teammate answered it.

Picking skills, and clicking Continue through the gates, all work the same whether you onboard solo or as a team.

After Onboarding

Once complete, you land on the planning dashboard where you can generate your first PRD. Your onboarding answers are preserved — not deleted — so they remain visible as reference in Project Settings and can be revisited for future PRDs.