Creating Your First Project

This guide walks you through creating a new project in Trinity, from initial setup to your first running story.

Before You Start

Make sure you have the required tools installed:

  • Git — with your name and email configured
  • GitHub CLI — installed and authenticated (gh auth login)
  • Claude Code CLI — installed for when you're ready to run stories

See the Prerequisites & Tool Setup page for install instructions for macOS and Linux. Trinity checks for these tools contextually and tells you exactly what to run if something is missing.

Step 1: Create or Import a Project

From the project selector, choose New Project (greenfield) or Import Existing (existing codebase).

New project asks for:

  • Name — lowercase, dashes only. Used for the workspace folder Trinity creates under ~/.trinity/projects/.
  • Description — optional one-liner for the project.

Per-repo visibility (public / private GitHub) is set later in the onboarding wizard's Repos step. Trinity manages the on-disk workspace location itself — you don't pick a folder.

Import existing validates that the folder is a git repo with a GitHub remote, then links it in.

Trinity checks that Git and GitHub CLI are ready before showing the form. If something is missing, you'll see the exact command to run and a Check Again button.

Step 2: Onboarding Wizard

The onboarding wizard is an 11-step conversational flow. Trinity asks questions and refines its understanding based on your answers — no step is final, so don't worry about getting things perfect on the first pass.

The Steps

  1. Plan — describe what you want to build, then answer clarifying questions about stack and requirements
  2. Phasing — define build order (when you have multiple platforms/targets)
  3. Design — answer visual style and accessibility questions
  4. Stack — accept or tweak the recommended tech stack (per target)
  5. Structure — choose how the project is organized in git: monorepo, turborepo, or polyrepo
  6. Repos — review and edit each proposed GitHub repo (name, visibility, description) before Trinity creates them
  7. Roadmap — read each generated section (Vision, Phases, Architecture, Design System), then click Continue to advance
  8. Business — fill in business details (for user-facing apps only — company name, contact email, socials, etc.)
  9. API Keys — paste-only service keys (Stripe, Resend, Clerk, etc.)
  10. Tools & Auth — work through CLI-driven setup flows (gcloud, firebase, supabase, vercel, etc.)
  11. Skills — pick Claude Code skills to scaffold into your project's workspace trunk

Each step can be revisited later from project settings. Trinity scaffolding (skills, hooks, quality checks) lands at the workspace-trunk level next to your repo clones — your project repos stay clean apart from AGENTS.md. The CLAUDE.md / GEMINI.md pointer files Trinity needs live at the workspace-trunk root, not inside each repo.

Step 3: Generate Your First PRD

After onboarding, you land on the planning dashboard. Click Generate PRD to create your first plan.

Generating the first PRD automatically creates your first release (default v0.1.0, configurable per project via tag_template + bump_strategy). Every PRD belongs to exactly one release — the Architect flow proposes one for you and lets you override.

The planning pipeline runs in 5 phases:

  1. Architect — designs the phase and epic structure with rationale
  2. Story Writer — writes individual stories with acceptance criteria
  3. Dependency Mapper — populates depends_on and places quality checkpoints
  4. Target Mapper — assigns each story to the right project targets (web, api, mobile, etc.)
  5. Calibrator — verifies the writer's difficulty / surface-area hints, overrides outliers, and enforces a healthy comparative distribution across the plan

This takes a few minutes. You can watch progress in the sidebar task indicator.

Step 4: Review Your Plan

Once the PRD is generated, review it on the planning dashboard:

  • Phase view — see the high-level phase/epic structure
  • Story graph — visualize dependencies between stories
  • Story list — browse individual stories, edit descriptions, adjust dependencies and targets

Make sure the plan makes sense before starting execution. You can:

  • Edit story descriptions and acceptance criteria
  • Adjust difficulty and surface area
  • Add or remove dependencies
  • Reassign targets
  • Skip stories you don't want executed

Step 5: Start Execution

Navigate to the Run page (your first release is already selected). Click Run on the Start Run card. Trinity will check that Claude Code CLI is installed — if it's missing, you'll see install instructions inline.

Once started, the coordinator:

  1. Identifies stories in the active release whose dependencies are all met
  2. Assigns them to available workers, each running in an isolated git worktree
  3. Each worker executes the story through the 4-phase pipeline (Analyst → Implementer → Auditor → Documenter)

You can configure the number of parallel workers and automation settings in the run modal.

Step 6: Monitor Progress

While execution runs, you can:

  • Watch the Run page — see which stories are in progress, completed, or queued
  • Approve gates — respond when agents pause for a decision (deviation approval, missing secret, missing assets, etc.)
  • Browse the Knowledge Base — agents write learnings as they work
  • View Recaps — daily summaries of what was accomplished
  • Check Activity — every mutation is recorded with field-level diffs

Step 7: Ship the Release

Once all stories in the release are terminal (complete / failed / skipped), the release moves to ready. Shipping is a two-stage manual flow: push to staging first, then release. Both stages are triggered from the release detail panel.

Stage 1 — Push to Staging. Click Push to Staging on the release detail panel (or the Run page's "Ready to release" card). Trinity walks each repo up its staging chain (default dev → staging), force-resets the chain tips to the release branch's tip, and snapshots those tips into release_repo_states. The release moves to staging_in_progress and then staged when the walk completes cleanly. While the release is staged, the detail panel surfaces a Staging Drift tile, a CI on Staging tile, and per-repo status — verify everything looks good on your preview deploy before continuing.

Stage 2 — Release. Click Release on the staged release. Trinity:

  1. Runs the release pipeline: preflight → SEO audit/fix (web targets) → release notes → documentation → consolidation
  2. Stops at a human gate asking you to approve before tagging
  3. On approval, tags the affected repos with the configured semver template and merges the release branch into the production branch
  4. Release becomes released

If anything looks wrong on staging, click Yank Back instead. Trinity force-resets each repo's staging-chain tips to the pre-staging snapshot and returns the release to ready so you can fix what's broken and push to staging again.

Step 8: Iterate

After shipping:

  • Architect adds new PRDs — inline, it proposes either adding to the same release or starting a new one
  • Align checks project health (drift detection post-PRD)
  • Audit scans your codebase for quality gaps and security risks
  • Metrics shows execution efficiency and AI cost

Tips for Success

  • Be specific during onboarding — the more detail you provide, the better the generated plans will be
  • Review plans before execution — catching issues in planning is much cheaper than during execution
  • Address gates promptly — the pipeline pauses at gates, so responding quickly keeps things moving
  • Check the Knowledge Base — agent discoveries compound over time
  • Start small — it's easier to add features iteratively than to plan everything upfront