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 Run on the Start Run card (visible when the selected release has runnable work)

Trinity probes Git plus whichever harness CLIs (Claude Code, Codex) the release's effective tier→harness map can actually reach, and shows the result as an inline Tool Checks section inside the modal. This is informational only — a heads-up if a tool a configured tier would invoke is missing, never a blocker. The Start Run button is disabled only while the start request is in flight or when you lack push access on the GitHub repo (the forge's answer, asked in every workspace); a missing tool never disables it.

The blocking version of that question happens earlier, on the way into the workspace and into the project (see Prerequisites → When Checks Happen), so by the time you reach this modal a red row here usually means a tier this particular release overrides — or a binary that went away since. Either way the run still starts. Each story then re-checks git and the CLIs its own steps resolve to before its first phase, and a spawn that loses its CLI later is caught the same way — both pause at the Tool Not Installed gate rather than failing.

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 checkout — a git worktree per repo the story touches (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 has had no runnable work for about 30 seconds.

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-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
Auto-approve technology deviations — skip the approval gate when the analyst proposes a technology deviation (the deviation still surfaces in the PR)

Every story with changes opens its pull request, so there is no toggle for that: the PR is opened by the Implementer, and the review, the close-out and any request-changes feedback land on it.

How a checkpoint audits — how many audit→fix iterations it runs, which model tier, and how much reasoning effort — is set per story in its Execution Settings card, not from this run modal. See Stories → Execution Settings.

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 about 30 seconds with 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)
Runs the merge chain on the PRs the story opened, 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, and files the story's issue in each repo it touches (see Story Issues). No code changes.
Implementer — writes code and tests, committing as it goes, then opens the story's pull request in each repo it changed. A story whose implementer stops before opening them is retried.
Auditor — runs one review round over the committed change. The round's depth is the number of reviewers: the story's own override if you set one, else the project's Reviewers per Story (see Project Settings). The Auditor reads the change itself, hands other reviewers one angle each (correctness, reuse and simplification, acceptance and conventions, efficiency and altitude), weighs what they report, fixes what it accepts, has a fresh reviewer check the fix, and leaves a review on each repo's PR with inline comments. A story whose reviewers are set to 0 skips this step.
Documenter — writes the documentation of each package the story touched into the repo, checks it against the documentation standard, and commits it with the code. It then posts a close-out comment on every repo's PR and on its story issue: what the story changed there, links to the story's other PRs, and whether the acceptance criteria were met. Trinity then 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 and the daily recap. These updates don't block the pipeline.

Git Worktrees

Every running story gets its own isolated checkout of the project's repos — a separate git worktree per repo the story touches, so a multi-repo story provisions one worktree for each repo it needs. 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 has two sections, stacked top to bottom:

Active — every story that's running or paused at a gate. A story that a worker has just claimed first shows a Preparing step while its worktree is set up. Each row then shows the pipeline (Analyst / Implementer / Auditor / Documenter for standard; Audit / Implement / Docs / Consolidate for checkpoints, the audit/implement pair looping until clean) with the current step highlighted. The tail of the row is a PR → Merge → Done stepper derived from what has actually merged, so it reflects real progress rather than a guess; the active step captions as Creating PR → Merging (or Resolving conflict) before the story moves to terminal. Rows waiting on a gate flip to a gate-colored pill; click to open the gate dialog. Click into a story's pipeline to drill in — the Active list swaps to a full pipeline detail view for that one story, with a Back button to return to the list. The detail view has two tabs: Progress (the pipeline steps and handoff history) and Live — a real-time feed of what the agent is doing right now (tool calls, reasoning, file changes, commands), grouped per turn. The Live feed replays recent activity on reconnect, so it stays current even across a brief disconnect.
Queue — stories that are pending, ready, or waiting for an upstream merge, each labeled with its real coordinator run-state rather than a blanket "Queued". Upcoming work that isn't runnable yet sits at the bottom.

Supporting surfaces:

Progress card — stories done / total for the release
Budget strip — a row of stat cards summarizing cumulative spend for the active release: Cost (USD), Tokens, and Wall Time (total agent runtime). Values update as agents complete turns; an axis with no data yet shows a dash.
Multi-release status pills — when other releases are also running, switch between their coordinators from here

Failed Stories on the Run Page

Failed stories surface with urgency proportional to what they block:

A failed story's queue row shows the failure cause in plain words (plus the recorded reason) and — when other stories are stuck behind it — a "blocking N stories" badge.
The architect's drafted resolution proposal renders directly under the failed row, so the fix is one click from the failure — see Stories → Failed Stories.
When a failure wedges the entire run — every remaining story is failed or stuck behind a failure — a prominent "Run stalled" banner at the top of the page names the blocking story, embeds the drafted proposal, and Trinity sends a push notification the same way it does for approval gates. Resolve the named story (approve the proposal, Retry, or handle it manually) and the run resumes.

A failure that blocks nothing stays quiet — its row shows the cause, the run keeps going, and the proposal waits on the story.

Gate dialog. Clicking a gated row opens a focused modal with a response panel pinned below the scrolling body, so the gate's actions stay visible however long the body is. Checkpoint gates tab between Overview, Findings, Fixes, Preflight & SEO, Notes, and Consolidation so you can triage a long audit run without drowning in one scroll view. The Preflight & SEO tab groups its build-gate results by package — the checkpoint scans every package the gated run touched, each against its own accessibility level and backing-services config. Other gate types (missing assets, external deps, PR review, merge conflict, story blocked, story failed, missing business details, missing secret, provider key missing, 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.

If a drain is taking too long or you need to halt immediately, Kill force-stops the coordinator without waiting for workers to finish their current story. Stopping or killing a run is a deliberate halt — it isn't treated as a failure.

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.

A job stopped this way lands on Cancelled, its own final state alongside Complete and Failed. That distinction is what keeps a deliberate halt out of your failure counts and off the retry paths a real failure takes: a cancelled job carries no cause to resolve, nothing waits on it, and nothing tries to bring it back.

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:

Review the Architect proposal card on the story — a drafted resolution (retry, reshape, or delete) is usually already waiting
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

If Trinity crashes or the desktop is restarted:

Stale coordinators are marked stopped on boot; if the website is not reachable yet, Trinity keeps retrying for a while
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; Start also requeues any story whose worker has been silent for three minutes or more, so that story is picked up again; a worker that went quiet more recently is recovered once it passes that mark