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.

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. Plan → 2. Phasing → 3. Design → 4. Stack → 5. Structure → 6. Repos → 7. Roadmap → 8. Business → 9. Setup → 10. Skills

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: 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 2: 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 3: 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 4: 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)
  • 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).

Step 5: 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 6: 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.

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 7: Roadmap

Trinity generates your initial roadmap and asks you to approve it section by section. Sections include vision, phases, milestones, and target-specific plans.

You can request changes to any section — Trinity regenerates that section without touching the others. Once every section is reviewed, the step advances.

Step 8: 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 9: Setup

For every external service detected in your stack (Stripe, Resend, Clerk, etc.), Trinity generates a dynamic, step-by-step setup guide and asks for the required API keys. Keys are encrypted at rest and injected as environment variables when agents run stories.

You can skip a service here — Trinity will pause with a missing_secret gate the first time a story needs it.

Step 10: Skills

Trinity recommends Claude Code skills from a curated registry based on your stack, and lets you search for more. Selected skills are scaffolded into your repo's .claude/skills/ directory when onboarding saves. Core skills (the trinity-app-* set) are always scaffolded regardless of selection.

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.