Checkpoints & Releases

Checkpoints are special stories that act as quality gates in your development pipeline. They pause execution for human review before work continues.

Checkpoint Pipeline

Quality checkpoints (quality_checkpoint story type) run an intensive audit of the codebase without creating a release:

  1. Analyze — scan the codebase for issues, identify quality targets
  2. Audit/Fix loop — multi-perspective audit scaled by difficulty, fix critical issues, repeat until clean
  3. Documentation — write up findings
  4. Knowledge base consolidation — editorial pass over the project knowledge base to merge duplicates, clean story references, and remove stale content
  5. Human gate — wait for your approval before downstream stories continue

Quality checkpoints do not create releases or tag repos. Use them mid-phase when you want a quality gate before continuing.

Release Pipeline

When you trigger a release (transition a release to Releasing), it runs a separate, more intensive pipeline:

  1. Analyze — scan the codebase for quality gaps and security risks
  2. Audit/Fix loop — multi-perspective audit, fix critical issues, repeat until clean
  3. SEO Audit/Fix (web targets only) — audits against SEO best-practice guides (technical SEO, on-page, content strategy, framework-specific rules). High and critical severity issues are auto-fixed
  4. Documentation — write release notes, update changelogs
  5. Knowledge base consolidation — editorial pass to merge duplicates, clean up story references, and remove stale pages across the entire project knowledge base
  6. Human gate — review the release summary, approve or send back for fixes. On approval: repos are tagged with semver (using the project's tag template and bump strategy) and the merge chain is walked. Per-target release notes and changelogs are generated

The SEO phase only runs for projects with web targets and is skipped entirely for all other project types.

How They Work

Checkpoints can appear anywhere in the story graph — mid-phase, at phase boundaries, or spanning multiple phases. They're flexible, not mandatory at every phase end.

Dependency Gating

Downstream stories should depend on the checkpoint story ID. This ensures the checkpoint acts as a gate: no work continues past it until you approve.

Per-Repo Versioning

Each repo in your project tracks its own version independently via git tags. When a release finishes, Trinity scans existing tags using the project's tag template (default v{major}.{minor}.{patch}) and auto-increments the configured bump strategy component (default: minor).

You can control which repos get tagged using repo:<name> tags on checkpoint stories. No repo tags means all repos get tagged. If tagging partially fails (e.g., one repo succeeds but another hits a network error), the release enters a Partially Released state with a retry option.

Gate Approval

When a checkpoint or release completes its pipeline and reaches the human gate:

  • Approve — marks the checkpoint as passed and unblocks downstream work (or tags repos for releases)
  • Skip — marks the checkpoint as passed without further action
  • Provide feedback — sends the checkpoint back through the feedback pipeline for fixes

Release Branches

If your project has use_release_branches enabled, releases create a release branch instead of merging directly. On gate approval:

  1. Release branch merges to the integration branch
  2. Optionally auto-merges to the base branch (auto_release_to_base)
  3. Optionally deletes the release branch (delete_release_branch)

Stories get a released flag when their code reaches the base branch via the checkpoint chain.

Releases

Releases are first-class entities that group one or more PRDs into a shippable unit. See the Releases page for full details on creating releases, linking PRDs, managing dependencies, and the release lifecycle.

PRDs vs Releases

Don't confuse these two concepts:

  • PRDs are plan iterations identified by simple integers (1, 2, 3)
  • Releases group PRDs into shippable units with semver tags (v0.1, v1.0) managed per-repo by checkpoints

In the UI, plan iterations are always called "PRDs", never "Versions".