Welcome to Trinity

Trinity is a next-generation Integrated Development Environment. It coordinates multiple AI agents to plan, build, review, and ship your software projects — while you stay in the driver's seat for the decisions that matter.

What Trinity Does

Trinity runs the full lifecycle of software development:

  1. Plans your project by generating structured PRDs (Product Requirement Documents), each grouped under a shippable release
  2. Executes stories autonomously through a multi-agent pipeline that writes, reviews, and tests code
  3. Ships releases — running preflight, writing release notes, and tagging repos on a per-release pipeline
  4. Records each execution as a recap, so what shipped and what it cost stays readable afterwards
  5. Reports on progress with an activity feed, recaps, metrics, and exportable PDF reports

Core Concepts

Projects

A project is your top-level container — the software product you're building. Projects can target multiple platforms simultaneously (e.g., Web App + API + Mobile app). Each target ships from a codebase, and it's the codebase that maps onto a GitHub repo Trinity clones and manages — so one codebase can ship two targets, and one repo can hold several codebases.

Releases

Releases are the primary unit of work in Trinity. A release groups a body of work into something you actually ship — PRDs, and any work you attach to it directly. Every screen that matters day-to-day — dashboard, story list, story detail, and Architect — is release-scoped.

Each release has a lifecycle: created → in_progress (first story merged) → ready (all stories terminal) → promoting → integrated (landed on your dev branch) → promoting → shipped (tagged on your base branch). Along the way a release can hold staging placements on target branches; an Integrate promote stops at integrated, and a Ship Now promote ships straight through.

Releases can depend on other releases through a dependency graph, and Trinity can run multiple releases in parallel as long as their upstream dependencies are already shipped.

PRDs (Product Requirement Documents)

PRDs are plan iterations inside a release — numbered (1, 2, 3) and containing:

  • Phases — high-level development stages (e.g., "Foundation", "Core Features")
  • Epics — groups of related work within a phase, each carrying a summary of what the group is and why it exists
  • Stories — individual units of work that agents execute

Not every story needs a PRD. Small work can skip the plan and attach straight to the release:

  • A loose epic — a group of related stories hanging off the release itself, with no PRD or phase above it. Use it when the work wants grouping but not a plan iteration. Like a PRD, it ends in its own quality checkpoint, and its stories run in order behind that gate. Its summary is what makes it self-describing with no PRD above it to carry the narrative.
  • A bare story — one story on the release, with no PRD, phase, or epic at all. This is what a bug story has always been, and any story can take the shape.

Release membership is the part that never flexes: every story belongs to exactly one release, however much plan sits above it.

A release can contain multiple PRDs as your plan grows; one PRD belongs to exactly one release. The first PRD you generate auto-creates your first release, giving it a readable two-word name (e.g. "Brave Otter"). After that, Architect proposes either an existing unshipped release or a new one every time you add a PRD — you settle the choice in the conversation before it commits the plan.

Stories

Stories are the atomic unit of execution. Each story has:

  • A clear description and acceptance criteria
  • Difficulty and surface-area ratings
  • Dependencies on other stories
  • Target platforms (which repos/targets it applies to)
  • A lifecycle: pending → in progress → completed → merged (or failed, or already done when the work already exists)

The Three Pipelines

Trinity runs three distinct agent pipelines depending on what's executing:

1. Story pipeline — every regular story runs through four phases:

  1. Analyst (read-only) — reads the codebase, checks for blockers, plans the implementation
  2. Implementer — writes the code and tests, committing as it goes
  3. Auditor — runs one review round over the code, with as many reviewers as your project sets, and leaves a review on the story's pull request
  4. Documenter — writes the documentation of each package the story touched, checks it, and commits it with the code

2. Quality checkpoint pipeline — stories of type quality_checkpoint (placed anywhere in the graph) run an intensive inspection: an audit/implement loop (audit across all seven review lenses → implement the findings → re-audit, looping until clean) → documentation → consolidation → human approval gate. Downstream stories can depend on a quality checkpoint so it acts as a hard quality gate.

3. Release pipeline — runs when you promote a release (ready → promoting): SEO audit/fix (web targets) → preflight → release notes → human approval gate, then tags the repos.

Execution Gates

Gates are checkpoints where Trinity pauses for your input. They fire when:

  • An agent detects a genuine blocker (EOL tech, incompatible framework, external dependency, missing secret)
  • A story references assets or business details that aren't populated
  • A story is blocked by something the agent can't resolve
  • A release or quality checkpoint is ready and needs approval before moving on

Gates ensure you stay in control of critical decisions.

Quick Orientation

The Sidebar

The sidebar has three collapsible sections, sorted by how far their rows reach: Workspace (workspace-wide), Project (the active project), and Help (User Guide, Help Assistant, Report Bug).

Workspace — always available:

  • Activity — global activity feed with filters (project, category, actor)
  • Recaps — activity summaries and PDF report export
  • Metrics — execution analytics and AI cost tracking across the workspace's projects

Project — appears when you have a project selected; rows unlock as the project advances through its phases:

  • Dashboard — release-scoped planning view with PRDs, phases, and stats
  • Code — read-only code browser for your project's repos (browse files, switch branches, Cmd+P search)
  • Stories — browse and filter stories for the active release
  • Run — start/stop execution, watch active stories, approve gates
  • Releases — create releases, wire dependencies, manage release state
  • Design — gallery of the project's Architect-generated prototypes, shown as thumbnail cards
  • Architect — conversational interface to add features or modify stories
  • Share — every live share link in the project, filterable by kind and revocable in bulk
  • Runtime — manage the skills, commands, and hooks your project's agents use, and review AI-authored or imported drafts before they go live
  • Settings — per-project configuration, including encrypted secrets (API keys, runtime env values, config files)

The two pickers sit above the sections, narrowing the same way they do: the workspace switcher first — which is also where Members, Settings, and New workspace live — and the active project selector under it. Your own account settings hang off the avatar in the sidebar's header, and the Inbox at the foot of the sidebar carries one count for everything waiting on you across every workspace you belong to.

Typical Workflow

  1. Create a project through the Architect conversation (greenfield setup happens there), or import an existing codebase
  2. Generate your first PRD — Trinity auto-creates your first release (a readable two-word name, e.g. "Brave Otter") and fills it with your plan
  3. Review the plan — adjust stories, dependencies, and targets on the Dashboard or Story Graph
  4. Start execution from the Run page — Trinity's coordinator assigns stories to workers inside the active release
  5. Monitor progress — watch stories flow through the pipeline, approve gates as they appear
  6. Ship the release — once all stories are terminal the release becomes ready; promote it from the release detail panel and Trinity runs the release pipeline and tags your repos
  7. Iterate — Architect drops new PRDs into the same release or starts a fresh one; keep building

What's Next