PRD Planning Pipeline

The planning pipeline transforms your project's roadmap into a structured, executable PRD. It's a 5-phase pipeline that runs when the Architect generates your plan, and that same run opens by drafting the roadmap itself — one run, one read of your project, rather than a roadmap run followed by a plan run. If you've already edited a complete roadmap in this conversation, the run uses it as it stands and goes straight to phase 1 — each phase is focused on one concern and writes its results straight into the plan the Architect is holding for this conversation, which the next phase picks up and builds on. There is one plan the whole way through, and each phase can only change the parts of it that are its job.

Small work runs the same pipeline with no PRD around it. When a change is smaller than a PRD's worth of scaffolding, the Architect plans it as work hanging straight off the release (see Architect). The same five phases run in the same order — what changes is that phase 1 designs no phase spine (one named group for the stories, and none at all when the plan is a single story), phase 3 ends that group on a single quality gate instead of one per phase, and phase 5 checks each story against the scales without the across-the-plan comparison, which a handful of stories has nothing to support. It is one pass, always: parts are slices of a phase spine, and this shape has none.

A big plan runs this pipeline more than once. When your phase spine is bigger than a single PRD can hold, the Architect splits it into consecutive parts before generation starts (see Architect) — and each part is a PRD of its own: its own five phases, its own complexity tier, its own sizing. The parts run one after another, never at the same time, and each one is committed to the release before the next is planned, so its opening stories can wait on the quality gate that closes the part before it.

Each phase is its own background run, started and reviewed by the PRD run you can see in the Architect's run bar — each phase is a step under that run, named after itself (Dependency mapper, and so on) rather than a generic "PRD phase". Four things follow from that. A redirect you send to the PRD run while a phase is working is picked up as soon as that phase lands, rather than at the end of the whole generation — so steering a plan mid-flight is worth doing. You're told when that moment arrives without having to watch for it: each phase sealing leaves a notification in your inbox (Foundation sealed, and so on) that opens that phase's own transcript, and the plan's own notification arrives after the fifth — five checkpoints on a long generation instead of silence until the end. You can also open a phase in the run bar and redirect it directly, which is what you want when that one phase is visibly going wrong and waiting for it to finish would waste the work; a phase you steer that way says so when it reports back, so the PRD run writes the next phase's brief against what actually happened. And if the app closes partway through, the phase that was running is still on the books when Trinity comes back, instead of disappearing with it.

How PRD Generation Works

Phase 1: Foundation

Designs the high-level structure:

  • Phases — major development stages with clear objectives
  • Epics — groups of related work within each phase, each with its own summary of what the group is and why it exists
  • Rationale — why things are organized this way
  • Complexity tier — simple / moderate / complex (affects guidance for downstream phases)

No stories are created yet — this phase focuses on getting the overall shape right.

Phase 2: Story Writer

Creates individual stories inside each epic:

  • Title, description, and acceptance criteria — clear, specific, testable
  • Story type — standard (most stories) or quality_checkpoint (inserted later by the Dependency Mapper). bug stories aren't planned here — they attach straight to a release, outside any PRD
  • Implementation scope — each story is sized to be independently executable by an agent

Phase 3: Dependency Mapper

Walks the story list and adds:

  • depends_on — which stories must complete before each one can start
  • Quality-checkpoint stories — new stories of type quality_checkpoint inserted at natural audit boundaries. These are story-level quality gates (intensive QA pipeline + human approval), not the same as a release's approval gate.
  • Topology assignments — which story installs each thing the plan introduces: a stack item, a design-system assignment, a target, or a package. Each assignment names the entity, its package, and the installing story, and the installing story has to land in the entity's own package — the commit rejects a plan whose assignments don't resolve rather than dropping them silently. This is what lets the Stack card (and every other topology view) say which story is putting a piece in and which one is taking it out.

For large plans (>10 stories), the phase uses a 3-pass strategy (intra-epic → cross-epic within phase → cross-phase), sending off one helper run per epic and per phase in parallel. While the plan is generating, the phase opens in place on the plan run's card in the Agents panel, with one square per helper run that you can click to open what it decided about a single epic and steer it while it works.

Phase 4: Package Mapper

Scopes every story to the packages its code changes — a package being one manifest root, the directory holding a single package.json / Cargo.toml / composer.json. Sends off one helper run per story batch in parallel, each one a square under the phase on the plan run's card in the Agents panel, openable and steerable while it works. If the LLM misses any, Trinity auto-assigns all packages as a safe fallback — the pipeline never leaves a story un-scoped.

Scoping to the package rather than the shipped artifact is deliberate: a story lands as a diff, and a diff lands in directories. Every target built from those packages is credited automatically, so a shared-code change to a React Native codebase that ships both a Mobile and a Web App target is attributed to both without anyone remembering to say so.

Packages are the only scope the phase writes; the artifact set follows from them. See Story scoping for what that means downstream.

Phase 5: Calibrator

The Calibrator does two jobs: it verifies the Story Writer's descriptor hints, and it authors each story's execution settings.

Descriptors — verified comparatively across the whole plan, overriding outliers and enforcing a healthy distribution rather than a flat run of D3/medium ratings:

  • Difficulty (1–5) — how complex the implementation is
  • Surface area (small / medium / large) — how much of the codebase is touched

These two are read-only descriptors: they feed story-selection ordering and analytics, but they don't decide how a story runs. (On quality-checkpoint stories the Calibrator omits them entirely.)

Execution settings — the Calibrator authors two knobs on every story, using its judgment about the work rather than a formula off the descriptors. You can edit either later on the story page:

  • Model tier — which model runs the implementation: reasoning (Opus) for genuinely complex or security-critical work, or standard (Sonnet) for most stories. These two are the only tiers the Calibrator authors; the leaner micro tier is reserved for Trinity's own mechanical background steps (classification, scoring) and never runs a story. frontier is opt-in only, but reachable here too via a manual per-story override.
  • Reasoning effort — low to max (or ultra on models that support it, currently GPT-6 Astra, GPT-6 Sol and GPT-5.6 Terra), defaulting to medium; raised for work that benefits from deeper reasoning. The run path clamps it down to whatever the resolved model actually supports.

The story page also holds a third setting the Calibrator does not author:

  • Reviewers — how many reviewers audit the story in its one review round. The Calibrator doesn't set this: a story inherits the project's Reviewers per Story, and you can give one story its own (0 skips the review for throwaway work, up to 10). On checkpoints it is the number of audit→fix iterations, floored at 1.

Post-Pipeline Validation

Trinity checks the draft before it validates anything: all five phases must have completed and the plan must carry at least one story. A run that stops short fails, naming the phases that never finished — you get a failed task you can retry rather than an empty PRD reported as a success. A retry starts over from Phase 1; there is no resuming a half-finished run.

Once the draft passes that check, Trinity runs an iterative validation + fix loop on it before it's saved:

  • Vague acceptance criteria — flags ACs containing weasel words like properly, appropriately, correctly, as needed, handle all, various
  • Dependency validation — catches circular dependencies, missing references, and targets that fall outside the release the plan belongs to

Each iteration collects warnings, asks the agent to fix them directly in the plan, re-reads the result, and repeats until the plan is clean or the max iteration count is hit. A fix pass can only edit stories — it cannot add or remove one. It edits the stories it was asked about, and only the fields it names, so calibrated values like difficulty and surface_area stay as the Calibrator set them, and the plan you review has exactly the stories the pipeline wrote. The run's summary says what each pass repaired, and the progress line names the pass while it works, so the stretch after the last phase isn't a silent gap.

The coverage check hands you findings, not stories

On a full-PRD run, Trinity also compares the plan against your roadmap — what the round said it would build, minus anything you listed as a non-goal — and reports the capabilities no story covers. When the round is split across several PRDs, each one is checked against the part of the roadmap it was meant to cover, so work belonging to a later PRD isn't reported as a hole in an earlier one.

That report comes to you, on the plan itself, and nothing acts on it automatically. A gap means the plan doesn't cover something the roadmap promised, and what to do about it is a decision rather than a repair: accept it as out of scope for this PRD, ask the Architect for the stories that close it, or carry it into the next PRD. Closing a gap changes what the plan is for, and that stays yours — which is why no step of generation writes a story to make one go away.

Every plan is checked against its own size before it's saved

The complexity tier the pipeline settled at the start is a budget — a story count the plan is sized for, with a little headroom, and an absolute ceiling no PRD may pass whatever its tier. The stories are checked against it when they're first written, and the plan is checked again every time generation saves it — so the tidying, repairs, and final assembly that happen after the last phase can't grow it past what it was sized for. A save that would bust the budget fails with the numbers stated — how many stories the plan carries and how many the tier allows — instead of saving a plan that's outgrown its shape.

Continuation Context (PRD 2+)

When generating a second or later PRD, the pipeline receives a continuation block assembled from prior work:

  • Full story manifests for every previous PRD — phases, epics, and per-story status, each story carrying its display ID (so cross-PRD depends_on can reference a real upstream story by that stable code)
  • Already-done and failed stories with reasons (so the new PRD doesn't repeat failed attempts without a different approach)
  • Your user direction — what you want this next iteration to focus on

This block flows into every phase's prompt, so Foundation can build on the existing structure and Story Writer can cross-reference previous work.

Plan Review Best Practices

After generation, review the plan before starting execution. The planning dashboard and story graph are the fastest ways to skim it.

Check Story Scope

Each story should be:

  • Specific — clearly defined, not vague
  • Independent — executable on its own (given its dependencies)
  • Testable — acceptance criteria an agent can verify

Verify Dependencies

  • Stories that should depend on each other but don't
  • Unnecessary dependencies that serialize work that could run in parallel
  • Missing quality checkpoints where you'd want Trinity to pause and verify things work together

Tune Execution Settings

The Calibrator does a good job, but you know your codebase best. To change how a story runs, open its Execution Settings card and adjust the reviewers, model tier, or reasoning effort directly:

  • Touching unfamiliar third-party APIs → consider raising the tier to reasoning and/or adding a reviewer
  • Story that's similar to existing code → consider a lower tier or 0 reviewers to avoid over-scrutiny
  • Security-critical / real-time / perf-critical → reasoning tier, higher effort, and more reviewers

(Difficulty and surface area are read-only descriptors — they don't change how a story executes, so there's nothing to adjust there.)

Check Quality-Checkpoint Placement

Quality-checkpoint stories are story-level quality gates — they run the intensive checkpoint pipeline (full-lens audit, refactor, re-audit, human approval) before downstream stories continue. Good placements:

  • End of a meaningful feature set
  • Before a major architectural shift
  • At boundaries where downstream stories depend on the earlier work being correct

Release-level approval (tagging, release notes, preflight) is a separate concept — see Releases.

Check Package Scoping

Package Mapper auto-fills any story it misses with every package, which is a safe fallback but often wider than the work. For polyrepos or multi-package projects, skim the story list to make sure each story is scoped to the package(s) it actually changes — a "set up mobile auth" story shouldn't be scoped to the marketing site's package.

You don't need to check target attribution separately. A story is attributed to every target its packages ship, so a shared-code change covering two artifacts is right by construction rather than something to correct.

Editing Stories

You can edit stories directly from the dashboard, graph, or stories list:

  • Click a story to open its detail view
  • Edit description, acceptance criteria, dependencies, targets, or the execution settings (reviewers, model tier, reasoning effort). Difficulty and surface area are shown read-only.
  • Changes save immediately

To drop a story you don't want, use Architect's removal flow — it deletes the story along with anything that depends on it as one reviewed change.

All edits are tracked in the activity feed.