Running Execution

Execution is where Trinity's agents actually build your project. A coordinator scans for ready stories, workers claim them, and each story runs in its own git worktree through the story or checkpoint pipeline.

Execution is release-scoped — every coordinator is attached to a single (project, release) pair. You need at least one release with PRDs linked before execution can start. Multiple releases can execute simultaneously, each with its own independent coordinator and worker pool.

Starting Execution

Go to Run in the sidebar's Project section
Pick a release in the top-right selector (the Run page persists your last selection)
Click Start on the Start Run card (visible when the selected release has runnable work)

Before the modal is usable, Trinity checks that Git, GitHub CLI, and Claude Code CLI are installed + configured. If anything is missing, an inline alert shows the exact fix command and a Check Again button. The Start Run button also requires that you have push access on the GitHub repo (in team scope — personal scope bypasses that check).

Two cascading dropdowns let you narrow the run to a subset of the release's stories:

Phase Scope — All phases or a specific phase. Each option shows <runnableCount> runnable; phases with 0 runnable are disabled.
Epic Scope — appears after you pick a phase with more than one epic. Same "runnable count" indicator.

The modal shows a live "N stories ready to run" pill below the filters so you can see the effective scope before you click Start.

Workers

1 to 5 parallel workers. Each worker runs one story at a time in its own isolated git worktree (created under the project's Trinity workspace dir and cleaned up after merge). More workers = more concurrency, bounded by your GitHub rate limits and your machine's resources.

Max Stories

Cap the run at N completed stories, or leave as Unlimited. The coordinator auto-stops either way when it hits the cap or finds no more runnable work on consecutive scans.

Mode

Two modes, selected inline:

Manual — you override project automation defaults inline for this run. Unchecked toggles fall back to project settings.
Autopilot — runs without stopping. Makes reasonable assumptions for unclear requirements and auto-skips gates. The automation toggles become read-only (they display the project defaults).

Automation Toggles (manual mode only)

Override project defaults for this run:

Auto-clarify — let the agent proceed when the story description needs minor inference
Auto-create PR — open a PR automatically when implementation finishes
Auto-merge — merge when checks pass
Squash merge — squash commits on merge
Delete branch after merge — clean up after merging
Auto-approve quality checkpoints — run full QA but skip the human gate

Checkpoint Pipeline Tuning (manual mode only)

For quality-checkpoint stories in this run:

Audit perspectives — Auto (scaled from difficulty) or fixed 2–7
Max fix loops — Auto (scaled from difficulty) or fixed 2–5

The Coordinator

One coordinator per (project, release) pair. Responsibilities:

Scan the release's stories for ones whose dependencies are all met
Claim + assign runnable stories to idle workers (atomic, so duplicates are impossible)
Monitor worker health via heartbeat; mark stale workers dead and reclaim their jobs
Auto-stop after consecutive idle scans (no runnable work)

Coordinator Status

Status	Meaning
Running	Actively scanning and assigning work
Stopping	Draining — no new assignments, letting in-flight workers finish
Stopped	Idle; not scanning

Run-level Status (surfaced on the Run page)

Status	Meaning
Idle	Nothing running
Running	Workers are executing stories
Waiting gate	A gate is blocking progress — your approval or feedback is needed
Blocked	Workers are free but nothing is runnable (usually upstream dependencies or a `release_deps` dependency still shipping)

Workers

Workers are the processes that run one story each. Each worker:

Claims a job from the queue atomically
Creates a git worktree for isolated changes
Runs the story through its pipeline (4-phase for standard stories, checkpoint pipeline for quality_checkpoint stories)
Handles PR creation and the merge chain on success (or marks the job failed / cancelled on error)

Worker Status

Status	Meaning
Idle	Ready for an assignment
Busy	Executing a story
Stopping	Finishing the current story; won't claim another
Dead	Crashed or heartbeat timed out — the coordinator will reclaim its job

The Story Pipeline (recap)

Standard stories run the 4-phase pipeline:

Analyst (read-only) — reads the codebase, plans the implementation, checks execution gates. No code changes.
Implementer — writes code and tests. Does not commit.
Auditor — simplifies the code through 1–7 passes scaled by difficulty + surface_bonus. Final pass runs /trinity-app-review + /trinity-app-check.
Documenter — commits the work, opens the PR, walks the merge chain.

quality_checkpoint stories run the separate checkpoint pipeline (see Checkpoints).

Post-merge, Trinity runs a fire-and-forget hook that updates roadmap progress, audit tracking, vault learnings, gotchas, and the daily recap. These updates don't block the pipeline.

Git Worktrees

Every running story gets its own git worktree — an isolated checkout of the project's repos. Benefits:

Multiple stories can run in parallel without clobbering each other
Failed runs leave the base branch untouched
Agents can git reset freely inside their own tree

Worktrees live under the Trinity-owned project directory (~/.trinity/projects/…). They're cleaned up after merge, and an orphan scan reclaims any that were abandoned by a crashed worker.

Monitoring the Run

The Run page splits into two columns:

Active — every story that's running or paused at a gate. Each row shows the pipeline (Analyst / Implementer / Auditor / Documenter for standard; Audit / Fix / Refactor / Document / Consolidate for checkpoints) with the current step highlighted. Rows waiting on a gate flip to a gate-colored pill; click to open the gate dialog.
Queue — stories that are pending, ready, or waiting for an upstream merge. Upcoming work that isn't runnable yet sits at the bottom.

Supporting surfaces:

Progress card — stories done / total for the release
Multi-release status pills — when other releases are also running, switch between their coordinators from here

Gate dialog. Clicking a gated row opens a focused modal with a response panel pinned to the footer. Checkpoint gates tab between Overview, Findings, Fixes, Preflight, Notes, and Consolidation so you can triage a long audit run without drowning in one scroll view. Other gate types (missing assets, external deps, PR review, release approval, release-notes failed, release-to-base, story blocked, missing business details, missing secret, deviation approval) each render a tailored body for the specific decision at hand.

The sidebar task indicator mirrors the high-level state (release name + current phase + gate flag) so you can track progress from other pages.

Stopping Execution

Click Stop on the Run page to stop the coordinator for the active release. It transitions to Stopping (drain mode) — workers finish their current story before going idle. Nothing in-flight is force-killed.

To cancel a specific job that's currently running, use the cancel action on the story itself — the pipeline checks assertJobActive() at critical points and bails out cleanly without marking the job failed.

Concurrent Release Execution

You can run as many releases in parallel as you want, limited only by worker count. Each release has:

Its own coordinator instance (coordinator_state keyed by (project_id, release_id))
Its own worker pool
Its own job queue
Its own status in the multi-release status pills

This is useful for parallel tracks — e.g., v0.2.0 shipping bug fixes while v0.3.0 builds a new feature set.

Retry and Recovery

If a story fails:

Check the agent handoffs on the story detail page for the error trail
Reset the story (set it back to pending) to have the coordinator pick it up on the next scan
Check the Audit / Align findings if the failure points at a structural issue

If Trinity crashes or the desktop is restarted:

Stale coordinators are marked stopped on boot
Orphaned worktrees are detected and cleaned up
Stuck jobs past the stale-job threshold are failed with recovery messages
You can click Start again and the coordinator resumes