Project Settings

Project settings let you configure how Trinity manages your project's git workflow, automation, AI models, secrets, and more. Settings are organized into nine tabs.

Accessing Settings

Click Settings inside the Project section of the sidebar (the one directly below the project's own nav items), or navigate to /projects/{id}/settings.

General

Details

  • Project name — display name used throughout the UI (also seeds the GitHub repo name for new projects)
  • Description — short summary shown in project lists

Targets — Accessibility

Visible only when the project has at least one UI-bearing target. A WCAG 2.1 picker per target (A, AA, AAA, or off) — a polyrepo can hold a marketing site at AA next to an internal admin tool with no a11y requirement. Each level propagates into the design guide and the per-story prompts for that target; for stories that span multiple targets, agents take the strictest level. Releases use the strictest level across the whole project.

Stories

Visible once at least one PRD exists. Pick which PRD's stories show by default on the Stories page.

Automation Toggles

Cascade defaults from global → team → user per-scope → project → user per-project → entity → job. Turn a toggle on/off at the project level to override the team / global default; flip it on Project Settings → Mine to override only for your own runs.

Toggle Effect
Auto PR Open PRs automatically when a story finishes
Auto-merge Merge PRs automatically when checks pass
Squash merge Use squash merges instead of merge commits
Delete branch after merge Clean up story branches after merging
Skip asset check Bypass the missing_assets execution gate (analyst stops declaring)
Skip business details check Bypass the missing_business_details execution gate
Skip checkpoint asset audit Skip the full-worktree image-placeholder scan at quality checkpoints
Skip checkpoint business audit Skip the contact-placeholder scan at quality checkpoints
Skip release asset audit Skip the image scan at release approval
Skip release business audit Skip the contact scan at release approval
AI triage (checkpoint) Let an agent classify placeholder hits at checkpoint (default off)
AI triage (release) Let an agent classify placeholder hits at release (default on)
Auto-approve quality checkpoints Run full QA but skip the human gate (release gates are always manual)

Audit Codebase

Runs the same placeholder scan that checkpoint + release gates run, on demand. Scans the whole worktree for image placeholders (placeholder.svg, picsum.photos, Lorem ipsum) and contact placeholders (example.com, 555-*, John Doe, stale copyright years), groups findings per file with line refs, and — if AI triage is on — shows suggested replacements. Informational only; nothing blocks and no gate fires.

Placeholder Audit Excludes

Add glob patterns to exclude from placeholder scans on top of the built-in excludes (node_modules/, **/__tests__/**, etc.). A .trinityignore file at the worktree root is also respected (gitignore syntax).

Permission Overrides (team scope only)

Override team-level permissions for this specific project. Each permission resolves as project → team → default (owner).

Permission What it gates
Approve checkpoint Approving quality-checkpoint and release gates
Manage secrets Editing project / team secrets
Delete project Archiving / hard-deleting the project
Reclaim job Force-reclaiming execution jobs

Values: owner (team owners + managers only) or all (any team member).

Project Assets

Manage uploaded reference files (wireframes, brand assets, specs, screenshots). See Project Assets.

Storage

Configure where project assets are stored:

Option Description
Local Only Files stay on your machine. Not available for team projects (assets must be reachable from every member's machine).
Trinity Cloud Managed Cloudflare R2 storage. No setup needed. Default for team projects.
BYO S3-Compatible Bring your own bucket — AWS S3, Cloudflare R2, Backblaze B2, DigitalOcean Spaces, MinIO, etc. Configure endpoint, region, bucket, access key, and secret key.

Trinity Cloud limits: every paid seat gets a single 5 GB managed pool that's shared across the user's personal scope and every team they own. Team projects don't get a separate bucket — their bytes come out of the team owner's pool. Adding team members does not grow the pool; only the owner buying add-on packs does.

  • Personal / team you own: you charge your own 5 GB pool plus any 10 GB add-on packs ($5/mo each, no cap on how many you can stack)
  • Team you're a member of: uploads charge the team owner's pool. If the owner's pool is full, your upload is blocked — the error names the owner so you know whose pool needs more space.
  • BYO S3 / Local Only: no Trinity-imposed limits. Switch to BYO S3 for teams that need real volume without paying per-seat for storage.

When you hit the cap, uploads block immediately. Reads keep working for 7 days (grace period); after that, reads block too until the pool owner frees space or buys an add-on.

Business

Company / product information used by execution gates and agent-generated content:

  • Company / product name
  • Tagline
  • Contact email and phone
  • Address
  • Legal name and copyright
  • Social media links

These are initially extracted from onboarding and can be edited at any time. Stories that need branding or contact info check these fields — missing values pause with a missing_business_details gate (unless you've turned on Skip business details check).

Git

Branching Strategy

Project-level branching defaults. Individual repos (in the Repositories card below) can override each value.

  • Branch strategy — what entity a branch represents (story / epic / phase)
  • Branch prefix — optional prefix prepended to all story branches
  • Story branch template — pattern (e.g., feature/{story_slug})
  • Epic branch template, Phase branch template — pattern for epic / phase branches when those strategies are in use

Template variables: {prefix}, {prd}, {phase}, {epic}, {story}, {slug}, {story_slug}, {phase_slug}, {epic_slug}, {prd_slug}.

Release branches:

  • Release template — naming pattern for the release branch each release creates (e.g., release/{version})
  • Delete release branch after merge — clean up the release branch on approval

Every release creates a release branch from the project's production branch; stories merge into it instead of straight to production. Individual releases can pin their own automation override on the release detail page's automation tab.

Release Defaults

Controls how Trinity picks versions when auto-creating or bumping releases:

  • Tag template — git tag pattern (default v{major}.{minor}.{patch}; supports any format like release-{major}.{minor} or {major}.{minor}.{patch}-rc)
  • Bump strategy — which semver component Architect's "create new release" suggestion increments: major, minor (default), or patch

These defaults also flow into the first release that's auto-created when you save your first PRD.

Merge Configuration

  • Staging chain — the ordered chain of branches a story walks on merge (default dev → staging, followed by the production branch as the final hop)
  • Merge level — how branches merge (merge commit, squash, rebase)
  • Production branch — the final base branch for the project (default main)

Repositories

Projects can contain one or more git repositories. Each repo shows:

  • Name — identifier (e.g., web, api, mobile)
  • Path — relative path from the workspace root
  • Production branch — repo-specific production branch (overrides the project default)
  • Branch templates — per-repo overrides for branch naming
  • Read-only dep — when enabled, Trinity clones the repo so agents can read it but never branches, commits, opens PRs, merges, or tags it. Use this for upstream forks, vendored libraries, or any repo you don't have write access to.

For monorepos you typically have a single repo entry pointing to the root. For polyrepos each repository gets its own entry.

Collaborators (GitHub)

Manage who has access to your project's GitHub repos directly from Trinity. The card shows each collaborator's avatar, username, and permission level. For polyrepo projects a repo selector lets you switch between repos.

Invite by GitHub username. Permission levels:

Permission Access
Read View code and clone
Write Push commits and manage issues
Maintain Manage repo without admin access
Admin Full repository access

In team scope, the username field autocompletes from your team members' linked GitHub handles.

In team scope, Trinity also gates its own UI/API actions by your actual GitHub permission level on the repo:

Your GitHub level What Trinity lets you do
Read View project, browse knowledge base
Write Run stories, respond to gates, manage collaborators
Maintain All Write actions plus project settings
Admin Full access including danger zone

Personal scope bypasses this check entirely.

AI Models

Model Overrides

Override the global model selection per-tier for this project. Model tiers:

  • Reasoning — complex agent work (planning, story pipeline)
  • Standard — default agent tier
  • Fast — faster subagents
  • Micro — lightweight / parallel tasks

See AI Model Configuration for the tier ladder.

Provider Keys

Provide your own API keys for Anthropic, DeepSeek, Moonshot, Z.ai, Qwen, or Ollama scoped to this project. Keys are encrypted server-side.

Skills

Manage the Claude Code skills scaffolded into this project's workspace-trunk .claude/skills/ directory (overlaid into each story worktree at runtime):

  • See which core trinity-app-* skills are installed
  • Add skills from the registry
  • Re-scaffold skills to refresh them from the templates

Secrets

The Secrets tab is split into three sub-tabs that share the same underlying encrypted store:

  • Overview — a glance card with counts ("configured" / "need setup"), a pending-setup list per stack service, and a "Re-sync files" button for materializable rows. Use it to see at a glance what's wired up and what still needs values.
  • Shared — project-wide secrets visible to teammates (cascade tier 3/4). Full table view with search, target filters, bulk .env paste import, and per-target editing.
  • Yours — your personal per-project overrides (cascade tier 1/2). Same editor, scoped to your account; teammates never see these rows.

Pick Shared for keys the whole team needs (an API endpoint, a non-secret config value), pick Yours for keys that are only yours to use (your own LLM provider key, your personal storage credentials).

Secrets are AES-256-GCM encrypted server-side. The encryption keys live on trinityailabs.com and never reach your desktop. Signing out invalidates access since decryption requires your Bearer token. Cascade resolution at consume time picks target-specific → project-wide → global for the same key — so a single project-wide value works for every target unless you override it.

Codebase

The Codebase Map is Trinity's living index of your project files with AI-generated descriptions. The card lets you:

  • Trigger a full rebuild of the map
  • See map freshness (last scanned branch/commit)
  • Browse file descriptions

The map is what agents read to orient themselves before touching code — keeping it fresh reduces the chance of duplicated or misplaced work.

Stack

Every technology decision tracked for this project: frameworks, databases, ORMs, auth providers, architectural tools. Items come from several sources:

Source When
Onboarding Technologies chosen during the greenfield wizard or detected during import
Planning The dependency mapper assigns pending stack items to the story that will first install them
Post-merge After each story merges, Trinity scans for newly introduced tools and flags them as suggestions
Scan Use the "Scan a branch" field to detect tools added outside Trinity (e.g., manual commits)

Item Status

Status Meaning
Active Accepted and in use
Pending Review Suggested by an agent — accept or dismiss
Deprecated Superseded by another tool (shows replacement link)
Removed No longer part of the stack

Assignment Tracking

Each stack item shows which story is responsible for installing it:

  • pre-existing — already in the codebase (imported projects)
  • unassigned — not yet assigned to a story (shown in amber)
  • story 1:2.3.1 — assigned to a specific story by the planning pipeline

During planning, the dependency mapper automatically assigns unassigned items to the story that will first configure them. After execution, the post-merge scanner verifies assignments and flags mismatches.

Worktrees

View and manage the on-disk git worktrees Trinity uses to run stories in isolation:

  • Active worktrees with the story they're assigned to
  • Orphaned worktrees (from crashed or killed workers)
  • Full history of past worktrees
  • Manual cleanup actions

You usually don't need to touch this — Trinity manages worktrees automatically. The tab is there for debugging when something gets stuck.

Danger

Reset Project

Greenfield projects only — imported projects don't show this card. Their repos are your own pre-existing codebase, not something Trinity created, so resetting and recreating them isn't safe. Use Delete instead if you want the project gone.

Reset is a delete-and-recreate cycle. It stops the coordinator, removes worktrees, closes PRs, deletes the GitHub repos and the on-disk workspace, clears the project's sync-DB tables, and removes the knowledge base. The next pass through onboarding's Repos step recreates the repos from scratch — same name, same description, fresh history.

Trinity preflights git and gh (including the delete_repo scope and the gh auth setup-git credential routing) before tear-down so you get a clean error up front instead of a half-reset project. If your token is missing the delete_repo permission, the dialog embeds a one-click flow to add it without re-authing.

The reset dialog has a Delete uploaded assets toggle:

  • Trinity Cloud (managed): locked on. Trinity-hosted assets can't outlive the project they belong to.
  • BYO S3 / Local Only: defaults to off, so the files you uploaded survive the reset and you can re-attach them. Flip it on to wipe the local cache and asset records too. Objects in your S3 bucket are never deleted by Trinity — only the local-only files and the asset rows pointing at them.

Move Project

Transfer a project between personal and team scopes. Only the project owner (owner_id) can initiate a move.

  • Move to Team — transfers a personal project into a team scope. All data syncs to the team's Turso DB. If using Trinity Cloud storage, assets are migrated to the team's R2 bucket.
  • Move to Personal — transfers a team project back to your personal scope. Assets migrate accordingly.

Moving requires typing the project name to confirm. Storage migration runs server-side automatically — no manual file moves needed.

Approval workflow: if the team has transfer policies requiring approval, the move creates a move_request instead of executing immediately. Owners and managers approve or reject from the Requests page from any scope — the page renders one section per team you belong to, so you can act on a team's transfer requests without first switching into that team. Once approved, the move executes on the requester's next sync. See Teams for transfer-policy details.

Delete Project

Hard-delete the project. Permanently removes the project row and optionally the GitHub repos (requires gh auth refresh -s delete_repo). The same Delete uploaded assets toggle applies — on for Trinity Cloud, your choice on BYO S3 / Local Only. Trinity preflights git and gh (including the gh auth setup-git credential routing) before tear-down so you get a clean error up front instead of a half-deleted project; once it succeeds you're redirected to the New Project screen. Requires typing the project name to confirm. Gated by the Delete project permission in team scope.