Architect

Architect is the conversational entry point for changing your plan — adding features, modifying existing stories, restructuring work, or starting a whole new PRD. It classifies your request, lets you review + override the scope, generates a preview, and then applies the change.

Accessing Architect

Click Architect in the sidebar's Project section. You can also land on Architect pre-filled from:

  • Audit pages — "Address in Architect" button pre-loads audit findings as context
  • Align findings — "Send to Architect" sends a specific finding as a seed
  • Releases page — "Add to this release" opens Architect with a ?release=<id> param so the release assignment step starts pre-selected

Flow Overview

Architect walks you through a fixed 4-step flow (you can back out at any step):

  1. Describe — natural-language conversation about what you want
  2. Scope — AI classifies your request, you review and optionally override
  3. Preview — see proposed stories / modifications / removals before saving
  4. Done — confirmation + redirect to the stories list (or vault, for roadmap-only updates)

The full PRD planning pipeline only runs when the classified scope is prd. For smaller scopes, Architect uses a lighter generation path.

Step 1: Describe

Describe what you want in natural language. Trinity's chat responds to refine your intent, and you can attach files (specs, wireframes, designs) for context. Examples:

  • "Add user profile pages with avatar upload"
  • "Fix the login flow when session expires"
  • "Change the dashboard to show weekly stats instead of daily"
  • "Split the monolithic API into microservices"

When you click Classify, the chat transcript + any attachments are sent to the scope classifier. You can Start Over to clear the session.

Step 2: Scope Review

The classifier returns two distinct fields:

Scope — the size of the change

Scope Meaning
story A single task
epic Multiple related stories (one epic worth of work)
phase A new area of work (one phase worth of work)
prd A major new direction — triggers the full PRD wizard
roadmap Adjust roadmap pages (vision, phases, milestones, architecture, design) without generating any stories

You can override the scope (except roadmap) with the picker below the AI suggestion — for example, bumping story → epic if you think the request is bigger than Trinity realized.

Mode — the kind of action

Shown as part of the classifier reasoning:

Mode Meaning
add New stories / epic / phase attached to an existing PRD
modify Updates to existing stories (pending ones only — see Safety below)
restructure Broader reorganization — often both adds and modifies
new-prd Generate a full new PRD (paired with scope prd; runs the 5-phase pipeline)

Smart Signals in the Scope Card

The scope card also surfaces:

  • Release hint — "Will join existing release" or "New release candidate" based on existing releases + the scope suggestion

  • New target detected — if your request implies a platform that isn't in project_targets (e.g., "add a mobile app" when you only have a web target), the new target is flagged and auto-added on confirm

  • PRD size warning — when the target PRD already has >12 stories, Architect warns you to consider splitting

  • Risk callouts — concrete, actionable risks only (auth changes, payment scope changes, live-table migrations). Vague warnings are suppressed.

  • Stack implications — if the request implies adding, removing, or swapping stack items, a separate Stack Review card shows the deltas and lets you approve them before generation runs

  • Structural intent — when your request implies a change to how the project is organized in git, Architect proposes one of:

    • Add target to same repo — a new target lives alongside existing ones (e.g., add a CLI to your monorepo)
    • Add target in new repo — the new target warrants its own repository; polyrepo projects gain a repo, single-repo projects grow into polyrepo
    • Consolidate to monorepo — collapse multiple repos into a single plain-folder repo
    • Consolidate to turborepo — collapse multiple repos into one with a workspace declaration (pnpm-workspace.yaml / turbo.json)

    Structural changes only happen when the project is "quiet" — no in-flight stories, no releases currently tagging. Architect refuses consolidations with a clear message if work is running; finish or cancel first.

From this step, clicking Generate Stories (or Update Roadmap for the roadmap scope) runs the generator and moves you to Preview. For scope prd, Start Planning launches the PRD wizard first.

Step 3: Preview

Before anything is saved, Architect shows exactly what would change:

  • Adding — new stories (with descriptions, acceptance criteria, proposed placement) and, for larger scopes, a new epic or phase
  • Modifying — existing stories with before / after diffs. Each entry has a checkbox so you can include or exclude it from the save.
  • Removing — stories that would be deleted, each with a reason
  • Roadmap updates — when the scope is roadmap, this shows which vault sections will be patched

Safety Boundaries for Modifications

Architect respects story status when proposing modifications:

  • Safe to modify — stories in pending status (not yet started)
  • Protected — stories that are currently running, completed, merged, or skipped. Architect won't propose direct edits to these. If you want to change completed work, add a new story that builds on it.

Protected stories are flagged in the preview so you know why a change you expected isn't there.

Release Assignment (new PRDs only)

When the preview belongs to a PRD that doesn't exist yet (scope prd or a new-prd flow), Architect adds an inline release assignment control:

  • First-ever PRD for the project — Architect auto-creates your first release (default v0.1.0, or whatever the project's tag_template + bump_strategy produce)
  • Existing unshipped releases available — Architect suggests either placing this PRD in an existing release (best fit) or starting a new one. You can override via the dropdown.

Releases with releasing or released status are excluded from the picker — they're frozen and can't take on new PRDs.

If you arrived via ?release=<id> from the releases page, the assignment starts on that release.

Step 4: Done

A confirmation card shows a summary ("5 stories created in PRD 2", "3 roadmap sections updated", etc.) and redirects you after a brief delay:

  • Roadmap-only updates → /knowledge (vault)
  • Everything else → the stories list, scoped to the saved release if available, otherwise the PRD

Tips

  • Be specific about scope — "Add user authentication" is broad; "Add email/password login with forgot-password flow using NextAuth" is better
  • Reference existing features — "Add filtering to the existing product list page" helps Architect understand context
  • One feature at a time — for complex additions, a few Architect passes outperform one huge request
  • Attach references — wireframes, API specs, or design mockups give agents concrete targets when the stories execute
  • Watch the stack implications card — Architect will flag when a request implies new dependencies; approving those up front keeps the story stack coherent