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.

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
Staged Walked up the staging chain and verified on the preview deploy
Released Part of a release that transitioned to released (so stories shipped with a git tag)
Skipped Manually excluded from execution; doesn't block downstream stories

A seventh status, blocked, exists in code for stories with unmet dependencies the coordinator can't resolve — it surfaces as a warning inside the Run page's Blocked Stories card.

Story Detail

Click any story to open its detail view. 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.

Metadata

  • Display ID — prdSeq:phase.epic.story (e.g., 1:1.2.3 means PRD 1 / Phase 1 / Epic 2 / Story 3). This is the same format used in depends_on references and cross-PRD links.
  • Difficulty — 1 (trivial) to 5 (very complex)
  • Surface area — small, medium, or large
  • Story type — standard (most stories) or quality_checkpoint
  • Dependencies — other stories that must complete first
  • Targets — which project targets (Web App, API, Mobile, etc.) the story applies to
  • Tags — custom labels, including repo:<name> tags for multi-repo projects

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: analyze codebase → multi-perspective audit → fix critical issues → refactor → re-audit → documentation → consolidation → human gate

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, simplification passes, and vault entries written.

Stack Items

Stories can be linked to stack items — the frameworks, databases, or tools they're responsible for introducing. During planning, the dependency mapper assigns unassigned items to the first story that will use them. After a story merges, the post-merge scanner verifies the assignments and flags mismatches as suggestions in Project Settings → Stack.

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 walking the configured staging chain (default story → dev → staging → production)

Story Types

Standard (standard)

Regular development work — features, bug fixes, refactors. Flows through the 4-phase story pipeline.

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. Stories that are in_progress, completed, merged, or released are 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.

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:

Global → Team → User per-scope → Project → User per-project → Entity (story/release) → Job

Per-story overrides available:

  • Auto PR — open a PR automatically when implementation finishes
  • 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 team / global) default. Overrides don't cascade to other stories. Model selection is project-level — set under Project Settings → AI Models — and is not overridable per story.

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.