Onboarding Wizard

The onboarding wizard guides you through setting up a new (greenfield) project. It's an 11-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. API Keys → 10. Tools & Auth → 11. 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)
  • 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 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.

  • 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 7: 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 chat for the section you're on. Trinity rewrites that 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 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: API Keys

For every paste-only service detected in your stack (Stripe, Resend, Clerk, OpenAI, etc.), Trinity generates a dynamic, step-by-step guide that walks you through grabbing each value from the dashboard and pasting it in. Keys are encrypted the moment you enter them, never sent to AI agents, and every field is optional — leave anything blank and fill it in later from Project Settings → Secrets.

If a service needs a CLI rather than a paste, it shows up in the next step instead. Projects with no paste-only services skip straight through.

Step 10: Tools & Auth

For every CLI-driven service in your stack (e.g. gcloud auth login, firebase login, vercel login, supabase login), Trinity walks you through the flow interactively — capturing each value as the CLI emits it and encrypting it before it lands on disk.

Each service can be left for later — the project still finishes onboarding, and you can resume any unfinished setup from Project Settings. Trinity will pause with a missing_secret (or service_setup_required for CLI flows) gate the first time a story needs the missing value.

Step 11: 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 the workspace trunk's .claude/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 / GEMINI.md pointer files live at the workspace trunk, not inside the repos.

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.