Core concepts

This page defines the vocabulary Motriz uses. Every term here is the word the app itself shows. The rest of the documentation builds on these definitions.

Products

A product is the one thing you add to Motriz and the only noun the app uses for it — "Add a product…", "Rename product", "Remove this product?". An idea, a stalled codebase, or a live repository each opens as a product in the sidebar's product switcher. There are two kinds:

• Journey products (lightbulb icon) carry the product journey and the co-founder. They can begin without a repository and connect one later.
• Repository products (git-folder icon) are a repository added directly, with no journey. The coding harness is a complete product on its own; product guidance is strictly opt-in, through the "Start product journey" button on the product's Dashboard.

Removing a product removes its work, messages, and run history from Motriz. Repository files on disk are never touched. See Products and the Dashboard.

The four destinations

Every product gets up to four destinations in the sidebar, always in the locked order Dashboard · Journey · Co-founder · Build:

Which destinations appear follows the product's mode:

Build availability is repository-driven, not stage-driven: a journey product that connects a repository keeps its Build destination at every stage — guidance is never a toll on building. Every product opens on Dashboard, and every fresh app launch starts there.

Work and work items

Below the destinations, the sidebar shows the "Work" group. A work item is one persisted piece of work in a product, created from "Start work" (⌘N). Nothing persists until you send the first message. Motriz presents work items as three kinds — a conversation (Chat), a build run (Build), and design work (Product design) — and its dialogs use those nouns exactly: "Delete this conversation?", "Rename build run". Work items can be renamed, archived, deleted, and grouped into folders; deleting a folder keeps its work and moves it back to the top level. The empty state is "No work yet." See Work and runs.

Runs

A run is one live agent execution inside a work item — the app says "Run in progress", "Run finished", "Run failed". Single-agent runs are first-class: pick a provider, model, reasoning effort, optional "Fast" tier, and role in the composer and go — no flow required. See Providers and models.

Activity streams inline in the conversation; there is no separate run view. Tool calls, thinking, flow steps, sub-agents, and deep research all render as rows in one stream, and each turn folds into a single lead row by default. A finished turn settles into a one-line receipt with its totals — 41.2k in · 3.1k out · $0.86 · 3m 12s — and unfolds back into the exact rows it streamed. While anything runs, a "{n} RUNNING" pill sits on the Build row (or on Dashboard when the product has no Build entry).

Roles

A role is the system prompt an agent runs with. The same role works on any configured provider, which keeps flows provider-neutral.

• Build roles, in the composer's role pill and in flow steps: Coder (the default), Planner, Heavy Planner, Reviewer, and System Architect.
• Assistant — the Chat role. It is instructed to answer and analyze rather than make changes, but roles are not access-control boundaries.
• Product Specialist and Product/UI Designer — Product design sessions only.
• Co-founder — the persistent partner in the durable conversation. Whatever it delegates internally, you see one face: "Co-founder · {activity}", for example "Co-founder · Mapping the competition".
• In flow steps, "Custom" means no role: the step's instructions become the entire system prompt.

Flows

A flow is an optional pipeline of steps; each step picks its own provider, model, and reasoning effort. Flows are reusable configuration — runs are the concrete executions. Each step has one of three execution modes: "Single run" (one agent invocation), "Plan executor" (executes the previous step's plan item by item, then runs completion checks), or "Fan-out" (parallel branches that join before the next step). Any step can also "Loop back to an earlier step until approved". Built-in flows such as "Plan → Build" and "Plan → Execute → Review" are seeded and carry a "built-in" badge; manage them from the sidebar footer's "Flows" page. See Flows.

Tasks

A task is a durable build prompt, keyed MTZ-{n} — numbers are per-product and never reused. The task editor states it plainly: "Tasks are durable build prompts. Assign a flow or an explicit model before they can run." The assignment is snapshotted when the task enters the queue.

The task queue lives in Build. Tasks are created manually, from a finished Product design build prompt, or seeded by the build handoff. Each executed task creates a build run titled with the task's title, so queue work shows up in the Work list like anything else. Parallel stages run in isolated Git worktrees — see Git, worktrees, and GitHub.

Artifacts

An artifact is a durable output meant to outlive the message that produced it. Artifacts are saved in Motriz's app data, not silently written into your repository. The gallery groups them into twelve kinds: Briefs, Memos, Research, Plans, PRDs, Prototypes, Specs, Build prompts, Documents, Saved links, Images, Files.

Artifacts live in two places: the Dashboard's artifact gallery — the Dashboard body is the gallery — and the workspace's Artifacts tab beside a conversation. Every artifact keeps provenance back to its product, work item, and run, plus a version counter that bumps each time a run publishes a change. A build prompt can become a queued task or start new build work with its text prefilled. See Workspace and artifacts.

Product knowledge

Motriz builds a background working understanding of each product — the app calls it product context. It builds quietly while normal work continues, and agents read it during runs. Its one visible surface is the status chip in the Dashboard, Journey, and Build title bars, with exactly these states: "Build product context", "Product context queued…", "Building product context…", "Updating product context…", "Context ready", and "Context failed · Retry". On journey products, knowledge also accretes from the co-founder conversation as it happens. See The co-founder.

Journey decisions

Decisions are recorded at checkpoints on the Journey, and the label set is exactly five:

The co-founder can prepare a scorecard with its recommendation, but every decision is recorded by you — "your call, always" is literal UI copy, and overriding a recommendation records both positions. See The product journey.

Reviewed and Shipped

Work items in Build carry one of seven states, shown as chips:

A run that finishes after "Mark reviewed" reopens the review. Merging stays yours, in your repository: there is no merge button anywhere on the review path.