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 basics ready:

  • Git — installed, with your name and email configured
  • A connected git host — GitHub, GitLab, Bitbucket, or a self-hosted GitLab/Forgejo instance, connected in-app from Settings → Accounts. For GitHub you can just Sign in with GitHub in the browser — no CLI or token needed; other hosts use an access token. (gh/glab/tea CLIs are supported but not required.)
  • An agent CLI — Claude Code or Codex, whichever your model tiers point at. Trinity checks for it on the way into a workspace and again when you open a project, and offers both the install and a one-click switch to the other engine right there.

See the Prerequisites & Tool Setup page for details. Trinity checks for what it needs contextually and tells you exactly how to fix anything that's missing.

Step 1: Create or Import a Project

From the project selector, choose Create New Project (greenfield) or Add Existing Project (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) is chosen when you create the project, as part of project setup. Trinity manages the on-disk workspace location itself — you don't pick a folder.

Import existing points Trinity at a local folder that's a git repo. If it already has a remote, Trinity links that in; if it has none yet, Trinity can create the repository on your connected git host for you (the same way it creates greenfield repos) so a local-only project can still be imported.

Trinity checks that Git is installed and configured and that a git host is connected before showing the form. If something is missing, you'll see exactly what to do and a Check Again button.

Step 2: Greenfield Setup

Greenfield setup is a guided Architect conversation. You describe what you want to build, then answer a short, adaptive question sequence — Trinity only asks what your project actually needs:

  1. Clarify — describe your idea, then settle the targets you're building and the codebase each ships from
  2. Design — visual style per codebase, and one accessibility level per codebase (for codebases with a design surface — even a CLI gets a terminal palette)
  3. Stack — accept or tweak the recommended tech stack, one codebase at a time, once its design settles
  4. Backing services (Docker) — the databases, caches, and queues each codebase runs on (only when its stack needs them)
  5. Structure — choose how your repos are organized: single repo, monorepo, turborepo, or separate repos (always confirmed — a single-target project just confirms single repo vs workspace)
  6. Phasing — settle the ordered phases your project ships in, starting with the MVP
  7. Business details — monetization, compliance, launch timeline, and how many people are building it

From your answers, Architect generates your roadmap and first stories. Throughout the conversation, the sidebar rail shows every decision live — toggle panels to see targets and phasing, or open modals for stack and design system. Core agent skills are scaffolded automatically; service keys are managed from Project Settings → Secrets, not the conversation. For the full Architect surface — sessions, conversation modes, and how slots work — see Architect. You can also set this up together with the rest of your workspace — see Setting up together. For the full walkthrough, see Setting Up a New Project.

Step 3: Generate Your First PRD

Your first plan is generated right in the Architect conversation — once you've answered its questions, it writes your roadmap and first stories, and you land on the stories list ready to run.

Generating the first PRD automatically creates your first release, giving it a readable two-word name (e.g. "Brave Otter"). Every PRD belongs to exactly one release — Architect proposes one for you, and you can steer the choice in the conversation.

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. Package Mapper — scopes each story to the packages its code changes (every target built from them is affected automatically)
  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 live on the Architect's own run bar.

Step 4: Review Your Plan

Once the PRD is generated, review it from the stories area:

  • 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
  • Tune a story's execution settings — reviewers, model tier, reasoning effort (difficulty and surface area are shown read-only)
  • Add or remove dependencies
  • Reassign targets
  • Remove stories you don't want (via Architect's removal flow, which also handles anything that depends on them)

Step 5: Start Execution

Navigate to the Run page (your first release is already selected). Click Run on the Start Run card. The modal repeats the agent-CLI check for the release's own tiers as an informational heads-up — by this point you've already cleared the blocking version of it on the way into the workspace and the project.

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 its own isolated checkout — a git worktree per repo the story touches
  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.)
  • View Recaps — daily summaries of what was accomplished
  • Check Activity — every mutation is recorded with field-level diffs

Step 7: Ship the Release

Once every story in the release is merged or already-done, the release moves to ready (a failed story blocks this until you retry or resolve it). You ship from the Promote panel on the release detail panel, which offers three modes:

Ship — the through-staging path. Open the Stage Target Picker, check the staging targets you want the release deployed to, and click Stage selected — Trinity places the release onto each target branch so you can verify it on your preview deploys (a Staging Drift tile, a CI tile, and per-repo status track each one). A branch not yet on the list can be typed directly; Trinity creates it as a new staging target and keeps it for your next release too. When it looks good, click Ship: Trinity promotes release → dev → main, runs the release pipeline (preflight → SEO audit/fix for web targets → release notes), stops at a human approval gate, and on approval tags the affected repos and lands them on your base branch. The release becomes shipped.

Integrate — click Integrate to Dev to promote straight to your dev branch and stop at On Dev, without a production hop. Use this to get the work integrated on dev without shipping it.

Ship Now — click Ship Now to walk the same release → dev → main spine as Ship, but with the staging gate bypassed.

If a staging deploy looks wrong, click Unstage on that target in the Stage Target Picker — Trinity resets the target's branch in every repo to the anchor it captured when it placed the release. Placements are independent, so unstaging one target never disturbs the others.

Step 8: Iterate

After shipping:

  • Architect adds new PRDs — inline, it proposes either adding to the same release or starting a new one
  • 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
  • Start small — it's easier to add features iteratively than to plan everything upfront