Importing an Existing Project

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

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 an 8-step process:

Scan → 2. Files → 3. Repos → 4. Design → 5. Docs → 6. Skills → 7. Save → 8. Done

Progress is saved automatically — you can leave the wizard at any step, or close the app, and come back to the step you were on. Until you confirm the import in the Save step, the project lives in the wizard: its sidebar shows an Import entry that takes you back, and opening the project from the project selector or its dashboard lands you there too. Architect isn't available until the import is confirmed — opening it brings you back to the wizard.

Before You Start: Path Validation

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

Monorepo — a single git repo with everything in one place. The simplest case.
Turborepo — a single git repo with declared workspace tooling (Turborepo, Nx, Lerna, or pnpm workspaces). Trinity shows the detected tool and the workspace directories it found.
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 — each repo's current branch, remote URL and recent commits
Framework detection — identifies languages, frameworks, and libraries from package files, including cross-platform setups (React Native Web, Capacitor, Tauri) where one codebase ships to more than one place
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. It keeps going if you leave the wizard, and when you come back Trinity shows it still running or moves you on with its results, without starting a second scan. If a scan fails, Retry Scan starts it again.

Rescan on the Files and Repos steps scans your codebase again. The wizard goes back to this step and shows the new scan running; when it finishes, its results replace the earlier ones and any review edits you made. Coming back to this step after a scan has finished shows the result, with Review files to carry on and Rescan to scan again.

Step 2: Files

Before Trinity snapshots your ambient project files, you can mark anything it should skip — typically large build artifacts, local dumps, vendored archives, or anything you simply don't want travelling with the workspace. The file picker lets you select individual files and entire folders; folder exclusions skip the folder and everything beneath it.

Nested git repositories are already handled automatically (Trinity stops at each .git boundary and clones those from GitHub), so you don't need to exclude them. This step is about the loose files and directories that live around the repos.

You can also skip this step entirely if you're happy with Trinity capturing everything ambient in the project root.

Step 3: Repos

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

Project summary — what the project does, its architecture
Packages & Targets — the code Trinity found and what it ships. A package is one dependency manifest — the folder holding a package.json, Cargo.toml, composer.json, or equivalent. A target is one thing you ship from it, picked from the target kinds (Web App, Website, Mobile, Desktop, CLI, API, Library, Extension), each with a short description so you can tell them apart. Targets are listed underneath the package they build from, so you can see at a glance which folder produces what.
Tech stack — languages, frameworks, databases, and tools
Repository structure — single repo, monorepo, or polyrepo, and the repos in it. Each repo is listed under the name Trinity gave it when it created the project: main for a single repo, and each repo's folder name for a polyrepo. The Docs step and Save find each repo by that name, so those repos keep their name and folder and can't be removed here. A repo you add yourself can be named and removed freely.
Branches — each repo's production branch and, if you ship through a staging flow, its merge chain (the same model as the Multi-Repo card in Project Settings)

One folder can ship more than one thing. A React Native codebase that also builds for the browser is a single package with two targets (Mobile and Web App), and Trinity detects that from the cross-platform library in your dependencies. Going the other way, an internal workspace package that other packages depend on but never ships on its own — a shared library, a common utils folder — can still turn up from the scan with no targets attached: it has its own dependencies and its own .env, but nothing to release yet. That's editable, not final: add a target to it (Library is the usual fit for shared internal code), drag an existing target onto it with the package dropdown, or remove the package if it shouldn't be tracked at all. Every package needs at least one target before you can continue — the review step flags any package still shipping nothing, and Trinity won't save the import until it's resolved.

Give each target a clear label — so a project with two mobile apps reads as "Mobile (Client)" and "Mobile (Driver)" rather than one ambiguous entry.

Monorepos and turborepos: workspace members are packages, not repos. Keep one repo entry; list apps/web, packages/ui, and the rest as packages. Trinity keeps the folder paths exactly as it found them, so nothing moves on disk.

Polyrepo projects: package → repo mapping. When the structure is polyrepo, each package shows which repo it lives in. Trinity's analyzer picks a best guess (matching the folder against repo contents), but the mapping is editable — if Trinity put the core package in the web repo by mistake, pick the right repo from the dropdown. Targets follow their package, so you only place each folder once. Paths are normalized to the canonical path model (repo.path + package.path) on save — a target locates through the package it ships from — so downstream planning and execution agents know exactly where to look.

Read-only dependencies. Each repo row carries a Managed / Read-only dep toggle. Use Read-only dep for upstream forks, vendored libraries, or any repo you don't have write access to — Trinity still clones it into the workspace so agents can read it, but it won't branch, commit, open PRs, merge, or tag it. Use Managed (the default) for every repo Trinity should drive end-to-end. You can change this later in Project Settings if you mis-classify a repo.

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

Step 4: Design

If your codebase has UI targets, Trinity reads the colors and typography already used in your code — CSS custom properties, Tailwind config, MUI/Chakra themes, SCSS variables, or a plain usage scan when nothing more structured is found — and groups your targets into one or more design systems. Two targets that render with visibly the same palette are grouped into one shared system; targets whose palettes clearly differ stay separate.

If your project runs a framework Trinity recognises — shadcn (spotted by the components.json its CLI writes) or Bootstrap — you get a complete palette back even when your code only overrides a colour or two. The colours you never touched aren't missing from your app: it renders the framework's own defaults for them, so Trinity fills those in from the framework's published values instead of inventing replacements. Anything you did declare always wins over a framework default. A project with no recognised framework is read exactly as before — this fills gaps, it doesn't override what your code says.

Where your code names its corner rounding, elevation, animation-timing, spacing and text-sizing tokens outright (Tailwind v4's @theme block), Trinity picks those up too and saves them with the system, exactly as written. Glow and translucency are read another way, because no framework publishes a name for either: Trinity reads them off how your stylesheet actually paints — a blur behind a see-through panel, a tight unoffset shadow burning in one of your own brand colours — and it works the glow out after your palette resolves, so the colour it burns is recorded as one of your roles rather than as a loose value. Elevation, animation timing, and the spacing/type-scale/line-height set that makes up density are all-or-nothing: a partly-declared set is left out rather than half-guessed, and anything Trinity doesn't find just uses Trinity's own default. Glow and translucency are the exception to that last part — they have no default to fall back on. Finding none isn't a gap to fill: it means your app doesn't glow and isn't glassy, which is a real answer and the one Trinity records. Project Settings draws each system's palette, typography and motion scale on its Design Systems tab; everything else the system carries is read by the agents that build against it rather than shown there.

For each detected system you can review:

Palette — every color role (background, primary, borders, feedback colors, and more), shown as swatches for light and dark mode. Click any swatch to pick a different color.
Typography — the display and body fonts detected, shown as live specimens.
Confidence — how clean the detection was, and whether any colors had to be guessed outright rather than found or filled from a known default (a small dot marks only a genuinely guessed swatch). A color filled in from a recognised framework's own published defaults isn't flagged — it's not a guess, it's exactly what your app already renders.

For each UI target, choose which design system it uses — or skip if you'd rather start that target without one (you can always create a design system later, in Project Settings). Assigning two targets to the same system merges them; moving a target to a different system splits it back out. If nothing was detected, skipping is always available and nothing here blocks you from continuing.

You'll need to make a decision (assign or skip) for every UI target before you can save the import in the final step — but you can move past this step to review docs and skills first and come back to it.

Step 5: Docs

Trinity writes four starter pages for each package in your project, from the scan results and from the package's own AGENTS.md, README, docs/ and .agents/ folders:

Architecture — how the package is built and how its parts fit together
Tech stack — the technologies it uses
Features — what it ships, as the person using it sees it
Setup and development — how to install, run, test and build it

The step lists each package with its four pages. Each page appears as it finishes, and you can refine or regenerate any of them before moving on. A page that fails to generate is marked Failed with a Retry button, and the other pages still stand.

A package that already has a .trinity/docs/ folder, from an earlier import of the same repo, is marked Existing docs kept: Trinity leaves that folder as it is and writes no starter pages for it.

Step 6: 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 the workspace trunk's .agents/skills/ directory and overlaid into each story worktree at runtime

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

Step 7: Save

Trinity commits everything:

Project configuration is updated with scan results
The workspace trunk gets an AGENTS.md that lists every repo, every package in it, and where each package's documentation starts (.trinity/docs/index.md inside the package). It also holds the CLAUDE.md pointer file plus the canonical .agents/ directory (skills, commands, hooks — projected per-harness) and .trinity/quality-checks/, all of which materialize into every story worktree
Nothing is committed to your repos' branches directly. Each repo whose packages got starter pages gets one pull request, Add Trinity starter docs, into its dev branch (see Starter docs pull requests)
A repo without a starter-docs pull request gets its AGENTS.md sections pointing at its documentation when the first story that works in that repo runs, committed with the story's work (see Routing sections in your AGENTS.md)
Detected tech stack is persisted to the stack tracker (marked as pre-existing), scoped to each package — the stack belongs to the folder that declares the dependencies, so a multi-package project starts with the detected set on every package and you prune it per package from Project Settings
The design systems you reviewed and assigned in the Design step are saved, and the codebase behind each target is linked to its chosen system
Onboarding state is cleared

Starter docs pull requests

For each repo, Trinity opens one pull request from the branch trinity/starter-docs into the repo's dev branch. It carries each package's starter pages in that package's .trinity/docs/ folder, an index.md linking them, and the repo's AGENTS.md sections pointing at that index. It is committed and opened as you, with the account you connected for that repo's host.

Your repo's checkout in Trinity is left exactly as it was; the pull request is made on a separate branch.
If Trinity cannot work out which account and commit email to use for the repo's host, it writes nothing for that repo, and the Done screen says which one is missing.
If a trinity/starter-docs branch from an earlier import is still on the remote, Trinity writes nothing new for that repo and leaves that branch as it is. The Done screen links its open pull request, or says the branch has none and can be deleted.
If the repo has no dev branch yet, Trinity creates it from your production branch first, so the pull request has a branch to target. If it can't create the branch, it writes nothing for that repo and the Done screen says why.
A package whose pages fail Trinity's documentation check is left out of the pull request and listed with what the check found; the repo's other packages are still included.
If the repo's .gitignore holds a Trinity block that ignores .trinity/, the pull request removes that block so the docs can be committed. Every other line stays as it is.
If a rule of your own ignores .trinity/, Trinity writes nothing for that repo, and the Done screen names a file the rule hides. Remove the rule, and the docs can land.

Routing sections in your `AGENTS.md`

Trinity writes one section into the AGENTS.md at the workspace trunk, at each repo root and in each package folder, so an agent working anywhere reaches the documentation for the code it is in. The section sits between two markers,  and :

Trinity rewrites only what is between the markers. The workspace trunk's section follows your packages as soon as they change (an import, a package added, moved or merged into another repo); a repo's or package's section follows the next time a story works in that repo, and is committed with that story's work. A story that changes nothing else in a repo leaves the section out of it, so it never opens a change for the section alone. Everything else in the file is yours and stays exactly as you wrote it, however long it is.
A repo or package with no AGENTS.md gets one holding just the section, and a CLAUDE.md pointing at it if it has none.
Your repo's own docs/ and .agents/ folders are never touched.

Step 8: Done

A completion screen confirms the import succeeded. The import is finished now: Import leaves the sidebar, Architect takes its place, and opening the project lands on its dashboard. It lists each repo's starter docs: a link to its pull request, or why no docs were written for it. It gives you one shortcut:

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.
Use the Files step to keep the workspace tidy — exclude large build outputs, local databases, or any data/ dump you don't want Trinity snapshotting. Exclusions stick; what you skip here never lands in the workspace asset store.
Check the review step carefully — the AI interpretation is usually good but can misidentify packages, targets, or tech stack components. Corrections here save time later. Worth a second look in a workspace: whether a shared internal package needs a Library target added (or should be dropped from the import), and whether a cross-platform app got both of its targets.
Set up secrets after importing — the import flow doesn't collect secrets. If your project needs API keys to build or test, add them from Project Settings → Secrets before your first run to prevent execution gate pauses later.
Review generated docs — the starter pages are AI-generated summaries. They're good starting points, and the pull request is the place to correct them before they reach your dev branch.