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. Learns from each execution, building a knowledge base of patterns, gotchas, and decisions
  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 mapped to one or more GitHub repos that Trinity clones and manages.

Releases

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

Each release has a lifecycle: created → ready (all stories terminal) → releasing (per-release pipeline runs preflight, SEO audit/fix for web targets, release notes, documentation, consolidation, then a human approval gate) → released.

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 released.

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
  • Stories — individual units of work that agents execute

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 (default v0.1.0, configurable per-project). After that, Architect proposes either an existing unshipped release or a new one every time you add a PRD — you can override the suggestion before confirming.

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 → running → complete (or failed / cancelled)

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
  3. Auditor — simplifies the code through multiple passes scaled by difficulty and surface area
  4. Documenter — commits the work

2. Quality checkpoint pipeline — stories of type quality_checkpoint (placed anywhere in the graph) run an intensive inspection: analyze codebase → multi-perspective audit → fix critical issues → refactor → re-audit → 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 a release transitions to releasing: preflight → SEO audit/fix (web targets) → release notes → documentation → consolidation → 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.

Knowledge Base (Vault)

The vault is Trinity's memory. It stores:

  • Project architecture and design decisions
  • Learnings captured during story execution
  • Gotchas and pitfalls discovered along the way
  • Audit reports tied back to the stories that address them

Agents read from and write to the vault, creating a feedback loop where discoveries compound across executions.

Quick Orientation

The Sidebar

The sidebar has two collapsible sections: Project (active-project items) and Hub (workspace-wide).

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

  • Roadmap — onboarding roadmap (visible during onboarding only)
  • 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
  • Architect — conversational interface to add features or modify stories
  • Align — project health check (roadmap review pre-PRD, drift detection post-PRD)
  • Audit — on-demand codebase scan for quality, security, and architecture gaps
  • Recaps — activity summaries and PDF report export
  • Metrics — execution analytics and AI cost tracking
  • Settings — per-project configuration

Hub — always available:

  • Activity — global activity feed with filters (project, category, actor)
  • Knowledge — project knowledge base (vault)
  • Gotchas — curated pitfalls library by language, framework, and tool
  • Teams — team management and invitations
  • Requests — pending invites, sponsorship offers, and move approvals (badge shows count)
  • Team Settings — team-wide defaults (visible to team owners and managers in team scope only)
  • Settings — app-wide configuration

The active project selector sits at the top of the sidebar, above both sections; a team/personal scope switcher sits above that.

Typical Workflow

  1. Create a project through the onboarding wizard, or import an existing codebase
  2. Generate your first PRD — Trinity auto-creates your first release (e.g., v0.1.0) 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; transition to releasing 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