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 shows every story in every PRD attached to that release. Deep links that carry ?release=<id> or ?prd=<id> override the defaults.

List / Graph Toggle

A pill at the top switches between the list view and the dependency graph. The graph is the same one documented on the Dependency Graph page — it renders here via the ?view=graph query param.

Filters

Two dropdown filters sit above the status tabs:

  • PRD — narrow to a single PRD inside the current release (shown when the release has more than one PRD)
  • Phase — narrow further to a single phase (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 (when release branches are enabled)
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 merge chain (e.g., story → integration → main)

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 & Model 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 → 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
  • Model overrides — use a different model per tier (max / high / medium / micro) just for this story

Leave any toggle unset to inherit from the project (or team / global) default. Overrides don't cascade to other stories.

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.