Importing an Existing Project

If you have an existing codebase you want to manage with Trinity, use the Import Existing flow instead of the greenfield onboarding wizard.

Overview

When you import an existing project, Trinity validates the path, detects the repository structure, and then clones from the GitHub remote into its own workspace at ~/.trinity/projects/ — your original working directory is never modified.

The import flow is a 7-step process:

  1. Scan → 2. Review → 3. Secrets → 4. Docs → 5. Skills → 6. Save → 7. Done

Progress is saved automatically — you can close the app and return later.

Before You Start: Path Validation

When you enter a project path, Trinity validates it and detects the repository structure:

  • Single repo — a directory with .git/ and a GitHub remote
  • Monorepo — a single git repo with monorepo tooling detected (Turborepo, Nx, Lerna, or pnpm workspaces). Trinity shows the detected tool and workspace directories.
  • Polyrepo — a parent directory containing multiple child git repos, each with their own remote. Trinity lists the discovered repos and their remote URLs.

If the path isn't a git repo or has no remote, Trinity shows the exact commands to fix it.

Step 1: Scan

Trinity performs a comprehensive filesystem analysis of your codebase:

  • Directory tree — maps the full project structure
  • Git info — current branch, remote URLs, recent commits
  • Framework detection — identifies languages, frameworks, and libraries from package files
  • Quality tools — detects linters, formatters, test frameworks already configured
  • Environment files — finds .env files and identifies required variables
  • CI/CD — detects GitHub Actions, GitLab CI, or other pipeline configs
  • Security signals — flags potential vulnerabilities or security issues

The scan runs automatically when you enter this step.

Step 2: Review

Trinity's AI interprets the scan results and presents a summary for your review:

  • Project summary — what the project does, its architecture
  • Detected targets — platforms identified (Web App, API, Mobile, etc.)
  • Tech stack — languages, frameworks, databases, and tools
  • Repository structure — single repo, monorepo, or polyrepo

Polyrepo projects: target → repo mapping. When the structure is polyrepo, each detected target shows which repo it lives in. Trinity's analyzer picks a best guess (matching target type against repo contents), but the mapping is editable — if Trinity put the API target in the web repo by mistake, pick the right repo from the dropdown. Target and repo paths are normalized to the canonical path model (repo.path + target.path) on save, so downstream planning and execution agents know exactly where to look.

If you have existing PRDs, Trinity cross-references the quality gaps and risks it finds against your planned and merged stories. Findings already covered by a story are separated into an "Already Covered by PRDs" section so your audit checklist stays focused on genuinely unaddressed issues.

You can edit any field the AI got wrong. This is your chance to correct misinterpretations before they propagate into the project configuration.

Step 3: Secrets

Environment variables detected from .env files are presented grouped by service:

  • Review which secrets are needed
  • Import values directly from existing .env files
  • Add or remove entries manually

All secrets are encrypted server-side on trinityailabs.com (the encryption keys never reach your desktop) and injected as environment variables when agents run stories.

Step 4: Docs

Trinity generates four vault pages from the scan results:

  • Architecture — system design and component relationships
  • Tech Stack — detailed technology inventory
  • Features — existing features and capabilities
  • Setup — how to install and run the project

Generation is streamed — you can watch the content appear in real time. These pages form the initial knowledge base that agents will reference during execution.

Step 5: Skills

Trinity searches for Claude Code skills that match your detected tech stack:

  • Skills are auto-selected based on frameworks and tools found in the codebase
  • Review the suggested skills and toggle any you want to add or remove
  • Skills are scaffolded into your repository's .claude/skills/ directory

Core skills (check, review, debug, docs, test, etc.) are always included.

Step 6: Save

Trinity commits everything:

  • Project configuration is updated with scan results
  • .claude/ directory is scaffolded in your repository
  • Analysis report is saved to the vault
  • Detected tech stack is persisted to the stack tracker (marked as pre-existing)
  • Onboarding state is cleared

Step 7: Done

A completion screen confirms the import succeeded and gives you two shortcuts:

  • Run an audit — goes to the Audit page for a health check on the imported codebase (great starting point since the audit findings can feed directly into your first PRD via Architect)
  • Create first PRD — jumps straight into Architect, which auto-creates your first release and fills it with the new PRD

Tips for Importing

  • Your original repo is untouched — Trinity clones from the remote URL into its own workspace (~/.trinity/projects/). All execution, branching, and worktree operations happen in Trinity's copy.
  • Push before importing — Trinity clones from the GitHub remote, so make sure your latest changes are pushed. Unpushed local commits won't be in Trinity's clone.
  • Clean git state — make sure your working tree is clean before scanning. Uncommitted changes won't cause problems, but a clean state gives the most accurate scan.
  • Check the review step carefully — the AI interpretation is usually good but can misidentify targets or tech stack components. Corrections here save time later.
  • Don't skip secrets — if your project needs API keys to build or test, setting them up now prevents execution gate pauses later.
  • Review generated docs — the four vault pages are AI-generated summaries. They're good starting points but may need manual refinement for accuracy.