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 — used as the GitHub repo name and workspace folder name (e.g., my-todo-app)
  • Location — parent directory where the workspace folder is created
  • Visibility — public or private GitHub repo

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 a 10-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 questions and review suggested tools/frameworks
  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 — review and approve each generated roadmap section
  8. Business — fill in business details (for user-facing apps only — company name, contact email, socials, etc.)
  9. Setup — configure API keys for detected services (e.g., Stripe, Resend)
  10. Skills — pick Claude Code skills to scaffold into your project

Each step can be revisited later from project settings.

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 — calibrates difficulty and surface-area ratings comparatively

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 Start. 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. Triggering the release pipeline is always a manual action — you do it when you're ready to ship. Two entry points:

  • Run page — shows a "Ready to release" card with a Trigger Release Pipeline button once the release is ready
  • Releases page — open the release detail panel and use the status control there

Either path:

  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
  4. Release becomes released

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