Working with Stories

Stories are the atomic unit of work Trinity executes. Each story is sized to be completed end-to-end by one agent run through the 4-phase story pipeline (or, for quality checkpoints, the checkpoint pipeline).

Stories Page

Navigate to Stories in the sidebar's Project section. The page is release-scoped — it opens on the active release (persisted per-user, synced across your devices) and lists the stories of one PRD inside that release at a time. The release picker (top right) and PRD picker (filter row) drive what's rendered; both are required pickers, not optional filters. Deep link with ?prd=<id> to land directly on a specific PRD inside the active release.

Reading the Roadmap

The Roadmap button in the Stories page header opens the roadmap of the PRD on screen — the same planning round said in plain English rather than as a story graph, across five sections: Overview, Vision, Phasing, Architecture and Design system. It belongs to that PRD and is reached through it, so switching the PRD picker switches the roadmap with it. A PRD whose planning round never drafted one says so rather than opening empty.

A story that was planned on its own — hanging straight off the release rather than under a PRD — can carry a roadmap of its own, and shows it as a Roadmap tab on its detail page (see Story Detail). A small change's roadmap is short: it shows an Overview and only the sections that apply to the change, so a one-line fix reads as a single paragraph rather than five sections of filler. A story under a PRD, or under a group of loose stories, has no tab of its own; the roadmap of the PRD or group above it covers it.

Sharing the Plan

Two Share controls sit in the Stories page header — Share roadmap and Share PRD. They publish the two documents of the PRD on screen, for two different readers, as two independent links (revoking one leaves the other live):

• Share roadmap publishes the five prose sections above. This is the one to hand a client.
• Share PRD publishes the committed plan of that same PRD in full — every story with its description, acceptance criteria, dependencies, and its display_id handle. This is the one to hand someone implementing it.

Both are the same kind of share you already use for prototypes, reports, drafts and recaps: pick who the link is for and how long it lasts, optionally require an access code, then Copy link, Rotate code or Unshare. A shared PRD reads in exactly the order the app shows — phases, epics and stories in their real sequence, not the order they happened to be written.

A shared plan is a snapshot, like every other Trinity share: the reader keeps seeing it as it stood when you shared it until you choose to update. Update share appears whenever the source has moved since the link went out — for the PRD, a story retitled or rewritten, an acceptance criterion changed, a dependency added, anything reordered, renamed, added or removed; for the roadmap, an edit to any of its five sections. Each link tracks only its own document, so rewriting a roadmap section never nags you to republish the PRD. Neither appears just because work is progressing: stories completing, merging and shipping don't change the plan or the roadmap's authored prose, so a plan you're actively executing stays quiet rather than nagging you to republish every hour. Updating rebuilds the page behind the same link — the URL, its audience, its expiry and its access code all stay as they were.

List / Graph Toggle

A pill at the top of the page switches between the list view and the dependency graph. The toggle persists via the ?view=graph query param, and the graph rendered here is the same one documented on the Dependency Graph page — so a deep link with ?view=graph opens straight to the graph view of the current release / PRD.

Filters

Two dropdowns sit above the status tabs:

• PRD — picks which PRD inside the active release to render (shown when the release has more than one PRD; defaults to the first PRD by sequence number)
• Phase — narrow further to a single phase within the active PRD (shown as Phase 1, Phase 2, etc., with the phase name when available)

Epics are grouped under their phase in the list view — there's no separate epic filter, but each phase section has its own "all epics / specific epic" selector you can use inline.

Status Tabs

Tabs with live counts group stories by lifecycle status:

Tab	Meaning
All	Everything the filters returned
Pending	Not yet started — still waiting on dependencies or for a worker to claim it
In Progress	A worker has claimed the story and it's running through the pipeline
Completed	All pipeline phases ran successfully; the story is merged into its branch and ready to ship
Merged	Merged into the release branch (stories whose release is mid-staging show here too)
Released	Part of a release that transitioned to released (so stories shipped with a git tag)
Already Done	The Analyst found the work already satisfied and short-circuited before the Implementer ran — no diff, no PR. The Documenter still runs, so it can produce a report. Counts as done and satisfies dependents without a merge.
Failed	Execution didn't pass — attempts exhausted, a merge conflict, an externally-closed PR, an audit rejection, an authentication failure, or an empty result. Blocks dependents until resolved — see Failed Stories.

Two more states exist in code without a dedicated tab: blocked (stories with unmet dependencies the coordinator can't resolve — surfaced as a warning inside the Run page's Blocked Stories card) and staged (stories whose release currently holds a live staging placement — they appear under the Merged tab).

Story Detail

Click any story to open its detail view. A story planned on its own, with no PRD or group above it, also has a Roadmap tab beside Details, showing the plain-English account the planning run wrote for it — only the sections that carry text. Sections:

Description + Acceptance Criteria

Free-form description of what to build, plus a checklist of testable acceptance criteria. Agents use the ACs to verify their work before handing off.

Intent, description, and acceptance criteria all render as Markdown, with different latitude for each: description supports full rich formatting — lists, tables, inline code, and diagrams — while intent stays a short plain-prose blurb (no headings or diagrams) and each acceptance entry renders as a single line (inline code only, no lists, tables, or headings).

Metadata

• Display ID — a stable 8-character code (like A3F9K2XQ) shown in the story header. It names the story wherever it's referenced — including depends_on references and cross-PRD links — and doesn't change when stories are reordered or reparented.
• Difficulty — 1 (trivial) to 5 (very complex), shown read-only. Describes the story for selection ordering and analytics; it does not drive how the story runs.
• Surface area — small, medium, or large, shown read-only — same role as difficulty.
• Story type — standard (most stories), bug (fix work attached straight to a release), or quality_checkpoint
• Dependencies — other work that must complete first. A dependency can be another story, or a whole epic or phase as a rollup (shown as epic:<label> / phase:<label> chips) — "wait on the whole group": the story stays blocked until every story in that epic or phase is done. Either kind can point at work in another PRD of the same release
• Packages — which packages the story's code lands in, and the targets that resolves to. See Story scoping below.
• Tags — custom labels, including repo:<name> tags for multi-repo projects

How long a dependency holds depends on the Merge Level in force — the release's own override if it sets one, otherwise the project's. At story — the default — every story merges straight to the release branch, so a dependency clears the moment its upstream merges. At epic, phase, or prd, stories batch onto a shared branch first, and where the two sides sit decides the bar:

• Same batch — the dependency clears as soon as the upstream's pull request lands in the batch branch they share. That branch is what the waiting story will be cut from, so the code is already there for it.
• Different batch, same release — the dependency holds until the upstream's whole batch merges on to the release branch. Its own pull request landing isn't enough: until the batch cascades, that code sits in a branch the waiting story never sees. This is the case where an upstream can read Merged while its dependent is still Pending — the upstream merged into its batch, not yet into the release.
• Different release — the dependency holds until the upstream release has shipped, same as at any merge level.

An upstream bare on the release — in no epic at all (see Story types below) — is in no group a batch branch could be named from, so it merges straight to the release branch at every merge level and clears its dependents on that merge. There is no batch behind it to wait for. A story in a loose epic is different: the epic is its group, so at epic, phase, or prd it batches on the epic's own branch — a loose epic has no phase or PRD above it to batch any wider — and its dependents wait by the same rules as any other epic's.

Story scoping

A story is scoped to packages, not to shipped artifacts. A package is one manifest root — the directory holding a single package.json / Cargo.toml / composer.json. A story lands as a diff, a diff lands in directories, so the packages it touches are the honest statement of what it changes.

Everything the run needs follows from that one fact: the working directory it runs in, the .env it composes, the accepted stack it reads, and the repo it pushes to are all properties of the packages it lands in.

A story can span as many packages as the change touches, and that's the point of the checkout. Your workspace holds the project with all of its repos, so a change to a client and to the API it calls is one story rather than two you have to keep in step. The run reads all of them: the secrets check covers every package's keys at once, the stack context carries each package's decisions, and the accessibility bar is the strictest level among them — a story reaching into a AAA codebase is held to AAA wherever else it also writes.

Which targets a story affects is then derived, not typed in. A story affects every target its packages ship. A React Native codebase that emits a Mobile target and a Web App target is one package, so a shared-code change there shows up on both — release notes credit it to both, and nobody had to remember to tick a second box.

There is no per-story artifact list to maintain, and no way for a story to claim one artifact of a package while disclaiming another: the code is shared by everything the package builds, so at coding time the distinction has nothing to act on.

Scoping is set during planning by the Package Mapper phase and changed through the Architect conversation.

Execution Settings

The Execution Settings card controls how the story runs. The calibrator authors everything here during planning; you can edit any of it to override. (Difficulty and surface area are shown read-only at the bottom of the card — they describe the story but don't set its execution behavior.)

Reviewers sits above the grid and applies to the whole story — how many independent reviewers read the implementation in the Auditor's one review round. A story inherits the project's Reviewers per Story, shown with a project default badge; type or step a number to give this story its own, up to a cap of 10, and Use project default hands it back. 1 is the Auditor reviewing alone, each step above that adds a reviewer for one more angle (correctness, reuse and simplification, acceptance and conventions, efficiency and altitude, and past 5 the angles repeat as independent re-reads), and 0 skips the review entirely. Raise it for multi-concern or security-critical work. On quality_checkpoint stories this control is labelled Audit → Fix Iterations and is the number of audit→fix cycles, floored at 1 — where 1 is an audit-only gate (it reports but doesn't auto-fix), and 2–3 fixes and re-checks until clean.

Below it, Pipeline Steps is a grid with one row per phase — Analyst, Implement, Audit, and Docs on a standard story; Audit, Implement, and Docs on a checkpoint — and each row carries its own four controls, so you can spend reasoning power on the step that needs it and keep the rest cheap:

• Tier — Frontier, Reasoning, or Standard for that one step. The calibrator only ever authors Reasoning or Standard; this grid is the only place a story reaches Frontier, and only because you picked it by hand.
• Model — either Tier default (<model>) or a specific model at that tier. A model listed only because it is its provider's best available — it sits below the tier's own bar — is labelled "— best available", so a clamped pick never reads as a genuine one.
• Effort — how hard that step reasons: Low, Medium, High, Extra High, Max, or Ultra. A note under the row shows the effective effort for the model that row resolves to — most models cap at Max (Ultra is reachable on GPT-6 Astra, GPT-6 Sol and GPT-5.6 Terra), some cap below Max, and a few (e.g. Haiku) take no effort setting at all.
• Speed — Standard or Fast for that one step. Fast asks the vendor to answer sooner and is billed at its premium rate for that tier, so it is the one control here that costs more rather than less; it stays on Standard unless you change it, and the calibrator can't set it at all. The control is only enabled where the step's resolved model publishes a faster tier — today the GPT models Trinity runs through Codex — and is greyed out on models whose vendor sells only one speed. Under heavy load a vendor may answer a Fast request at standard speed and charge standard rates for it.

The model this card names is the model the run will use. Tier default (<model>) and the Effective: … note both read the same answer the pipeline resolves for this story, so a project model override — or your own per-project override, or a per-story one — is reflected here rather than being invisible until the run records what it actually spent. Until that answer arrives the card says Tier default with no model and "Resolving this step's effective model…" in place of the note; it never fills the gap with a guess.

Pipeline Status

When a story is running, you can see which agent phase it's in, the current operation, and any gate that's blocking progress. Which pipeline runs depends on story type:

• standard stories — the 4-phase story pipeline: Analyst → Implementer → Auditor → Documenter
• quality_checkpoint stories — the intensive checkpoint pipeline: an audit/implement loop (audit across all seven review lenses → implement the findings → re-audit, looping until clean) → documentation → consolidation → human gate

Failed Stories: Paths to Resolution

When a story can't get through, it lands in the Failed state instead of stalling — and a failed story is never a dead end: it carries an honest cause, it blocks its dependents (so nothing builds on missing work), and the architect drafts a way forward the moment it fails. Failing never deletes anything — branches, PRs, and repos that already merged keep their code.

The detail view shows a Details card with the failure cause and a short reason:

Cause	What happened
retries exhausted	Automatic attempts ran out — the retry threshold was hit, or you marked a story failed when its agent was stuck (outside the audit phase)
run not converging	Trinity stopped a run that kept churning files without making real progress, and parked it for you to diagnose
run stuck in a loop	Trinity detected the agent looping — repeating the same tool calls or spiraling without progress — and stopped it
merge conflict	A conflict (or a partially-failed multi-repo merge) couldn't be resolved and you marked the story failed at the merge gate
PR closed externally	The story's PR was closed outside Trinity and you marked the story failed instead of recreating it
implementer produced no changes	The implement run finished without producing a diff
audit criticals	The audit phase escalated blocking findings it couldn't fix, and you marked the story failed
authentication failed	A git operation hit an authentication failure and you declined to re-authenticate
required tool not installed	git, Claude Code, or Codex wasn't installed on the device, and you marked the story failed instead of installing it

The Architect's Proposal

Every failure files a dossier for the architect — the cause, the attempt count, the gate's details, conflict-resolution findings, and which stories the failure blocks — and the architect immediately drafts a resolution proposal from it, so the choice is usually ready by the time you open the story. The proposal renders as an Architect proposal card — on the story detail page, under the failed row on the Run page, and inside the run-stalled banner — with the rationale, the concrete changes, and two buttons:

• Approve — applies the drafted resolution:
  • Retry as-is — nothing structural is wrong (say, the conflict has since been resolved upstream); the failure clears and the story re-queues on the next scan.
  • Reshape & retry — the story as written can't land; the proposal rewrites it (title, description, acceptance, dependencies, tags), then clears it for re-run.
  • Delete with reconciliation — the story shouldn't exist; the proposal removes it with an explicit decision for every story that depended on it — drop the dependency or repoint it — so nothing is left dangling.
• Dismiss — sets the proposal aside; the story stays Failed for you to handle manually.

Retry & Diagnose

The manual paths stay available alongside the proposal:

• Retry — clears the failure and resets the attempt count so the coordinator runs the story again from scratch.
• Diagnose — on the failure gates (merge conflict, externally-closed PR, agent-blocked, hard-failed), opens a diagnostic chat to investigate what went wrong on that run. Submitting your findings returns to the gate and kicks off the retry path. A story that hits a hard failure (the implementer hung with no report, an agent timed out, or retries ran out) parks at the Story Failed gate for exactly this — see Gates → Story Failed.

How many times a story retries before it's marked Failed is governed by a retry-exhaustion threshold (default 3 attempts).

Agent Handoffs

Each phase posts a structured report when it hands off. Standard stories produce four reports (analyst, implementer, auditor, documenter); checkpoints produce their own set. Reports include decisions made, detected services, and simplification passes. The Handoff History shows each report with the time it was created and processed, so you can see how long each phase took. A request-changes round posts the same reports: the analyst's plan reads as a written plan, and the auditor's handoff carries the implementer's report.

Pull Requests and Review Rounds

A story with changes always has a pull request in each repo it changed; nothing turns that off. The Implementer opens it, and each PR's description links the story's issue for that repo (Tracks) and lists the story's other PRs under Related pull requests; on a host with no issue tracker the description carries the plan itself instead. The story then collects review rounds on those PRs. One round is one pass of the Auditor: it posts a review on each repo's PR, with inline comments on the lines it found problems at and the rest in the review body, marking each finding fixed, declined or open. The Documenter then posts its close-out on the same PRs, and on the story's issue for each repo. When you ask for changes at the PR Review gate, your text is posted on every repo's PR too, and the round that follows picks up from it. The gate shows all of this, round by round.

Story Issues

Trinity publishes each story as an issue on your repository host, one in every repo the story touches, so the plan is visible where your team already tracks work. Nothing in the run depends on them: if an issue can't be filed, the story carries on and its pull request opens without one.

What gets filed, and when. The Analyst files the issues as soon as its plan is written, before the Implementer starts. Each issue holds the story's intent, its acceptance criteria (every box still open, since nothing has been audited yet), the Analyst's plan, and links to the story's other repos under Also touches. If a repo has no issue when the Implementer opens its pull request, that is when it is filed. A request-changes round updates the same issues with the new plan rather than filing more. A quality checkpoint's fix-branch pull request files one too, with the checkpoint's audit as its plan (see Checkpoints).

What gets skipped. Nothing is switched off: every story is published on every repo, public or private, since your repo's visibility is already your choice about who sees it. A host without an issue tracker has no issue to file, so the plan is written into the pull request description instead. On Bitbucket the documenter's close-out is posted as a comment on the pull request. What Each Git Host Supports lists which hosts take issues.

When an issue closes. A repo's issue closes as completed when that repo's pull request merges, whether Trinity merged it or you did on the host. It closes as not planned when the story ends without merging: the story is deleted (on its own, with its project or release, by a project reset, or by an Architect plan that removes it), the analyst finds it already satisfied and it completes with nothing to merge, a quality checkpoint is skipped or stopped at its checks gate, or a repo finishes with no changes to merge. An issue that is already closed keeps the reason it closed with. A story's issues stay open when you reset the story: a rerun updates the same issues. Trinity can only reach an issue while the repo is on this machine and an account that can write to it is connected, so an issue it can't reach stays open.

Stack Items

Stories can be linked to stack items — the frameworks, databases, or tools they're responsible for introducing. During planning, the dependency mapper names which story installs each thing the plan introduces — not just stack items, but design-system assignments, targets, and packages too. In the Documenter phase, before the story merges, Trinity reads the story's own changes and records anything it added, dropped, or swapped as a proposed item linked to that story. After the story merges, the post-merge scanner verifies the assignments and flags mismatches as suggestions in Project Settings → Stack.

A story that never merges leaves its proposals sitting as proposals — they're a record of what was decided, not a claim that anything was built.

PR and Merge Status

For completed stories, the detail view shows:

• Pull-request link + status per repo (in multi-repo projects, one row per repo)
• Branch names used (derived from the project's branch template)
• Merge status — the story merges into its release branch (batched per the project's Merge Level); the release later promotes from there through your Dev Branch, optional Staging Targets, and on to the Base Branch

Once a story is merged, the detail view also shows a collapsible Changes section with the full merged diff rendered inline — one panel per repo — so you can read exactly what shipped without leaving the page or opening the code viewer.

Reset story

The Reset story button (on the story detail view) takes a story all the way back to a clean slate so you can run it again from scratch. Resetting closes the story's open pull requests, deletes its branch and worktree, and clears its run history — its jobs, handoffs, activity, and review rounds — leaving the story Pending with no run state. The story's issues stay open, and a rerun updates them rather than filing new ones. The confirm dialog ("Reset this story from scratch?") summarizes what gets removed before you commit.

Two guards protect you from a destructive mistake:

• A merged or released story can't be reset — its code has already shipped, so the button doesn't appear.
• A story that's currently running has to be stopped first; resetting never cancels a live run out from under a worker.

Reset is the right tool when a story went down the wrong path and you want a genuine fresh start, rather than Retry (which re-runs from the existing branch) or editing a Pending story in place.

Story Types

Standard (standard)

Planned development work — features, refactors, anything the Architect laid out. Usually lives under a PRD's phase/epic tree, and flows through the 4-phase story pipeline. It can also sit outside a PRD entirely: under a loose epic on the release, or bare on the release itself, for work that doesn't warrant a plan iteration.

Bug (bug)

Fix work that attaches straight to a release instead of to a PRD — no plan iteration, no phase, no epic. Use it when something is broken and writing a planning document around the fix would only fabricate structure nobody wants. (Any story type can take that shape; bug is purely about what the work IS, and it routes no branches of its own.)

A bug story is a first-class member of its release: it blocks the release from going Ready until it lands, its work shows up in metrics, and it appears in the generated release notes, exactly like a planned story.

Where it merges follows from its shape, not its type: a batch branch is named after the group a story sits in, so a story bare on the release — a bug story, or any story in no epic — has no batch to open a PR against and merges straight to the release branch at every Merge Level. A story in a loose epic batches on its epic's branch at epic, phase, and prd alike, and that branch merges to the release branch once every story in the epic has landed.

When you want several fixes to stage together and land as one, that is what a release-level merge override is for: put them in a release set to epic and give them a shared epic. Speed is the other direction — a release set to story sends every story it holds straight to the branch, whatever the project's default.

Quality Checkpoint (quality_checkpoint)

Placed by the Dependency Mapper at natural audit boundaries (end of a feature set, before a major shift, anywhere downstream stories depend on earlier work being correct). Runs the intensive checkpoint pipeline with a mandatory human approval gate (which can be auto-approved via the autoApproveQualityCheckpoints setting — gate still logs for audit trail).

Quality checkpoints do not tag repos or ship a release — that's a separate pipeline, described in Releases.

Editing Stories

Pending stories are fully editable — open the detail view and change the fields inline; edits save immediately. Once a story is past pending — in progress, completed, merged, staged, released, already-done, or failed — it's protected from edits to avoid disrupting active or shipped work. If you need to change something that already ran, add a new story that builds on it (Architect is the clean way to do this).

All edits are tracked in the activity feed with field-level diffs.

Comments

Each story has a Comments tab (the count of comments shows next to the tab label). Comments are how you add clarifications or constraints to a story after it was written — "don't use X this time", "match the pattern in Y", "this needs to handle Z".

When the story runs, the Analyst and Implementer read every unresolved comment and treat it as a constraint: an unresolved comment overrides the default the agents would otherwise have chosen, and they call out in their handoff reports which comments shaped the work. Resolve a comment once it no longer applies and the agents ignore it.

This is the way to steer a story you can no longer edit. Pending stories are editable inline (see Editing Stories above); once a story is in progress or later it's locked — but a comment still reaches the agents on the next phase or re-attempt that reads the thread.

Architect sees the thread too. A story's comments are part of the story, so whenever Architect reads a story — one story, a search, a whole PRD, or a plan it checked out to edit — the discussion comes with it, resolved comments included. That means you can point Architect at a story and it already knows what was said about it, rather than needing you to repeat it. Architect can also reply on a thread and mark comments resolved once the point is settled, so a question you left on a story can be answered in place.

Automation Overrides (per-story)

Every story has an Automation tab letting you override settings just for that story. Overrides sit between the project-level default and the job-level config in the cascade:

Trinity defaults → Workspace → My workspace → Project → My project → Entity (story/release) → Job

Per-story overrides available:

• Auto-merge — merge when checks pass without waiting for you
• Squash merge — squash commits on merge
• Delete branch after merge — clean up after merging
• Auto-approve quality checkpoints — skip the human gate on quality_checkpoint stories
• Placeholder-audit toggles — fine-grained control over which placeholder categories the audit step flags

Leave any toggle unset to inherit from the project (or the workspace) default. Overrides don't cascade to other stories. This card carries automation toggles only — the models a story runs on are set per pipeline step in Execution Settings above, over the per-tier defaults from Project Settings → AI Models.

Multi-Repo Stories

In polyrepo / multi-target projects, one story can touch multiple repos. Each repo is tracked independently:

• Separate branches per repo (each computed from the repo's branch template)
• Independent PR + merge status per repo
• repo:<name> tags on the release control which repos are tagged when the release ships (no repo tag = all repos tagged)

The story detail view groups per-repo state so you can see at a glance which repos are green vs. blocked.