Stages and Roles

A stage is one step of your process: Icebox, Backlog, Review, or a step you define yourself. Stages replace the older idea of a work type as the thing you configure. You describe your process once as a set of stages, map your tracker's statuses onto them, and decide which cards run in each. The workflow itself stays the same when you add a card or a stage, which is what keeps it small.

Each stage has:

The system stagesCopy Anchor Link

Every organization inherits eight system stages. They are not copied into your org: they stay in one place and you override or disable them where you need to.

The system stages reference only system cards. The stages carry no tracker status names: which of your tracker's statuses means "Backlog" is something each project says in its status mapping.

RolesCopy Anchor Link

The platform makes decisions from a stage's role, never from its name. That is why you can rename Backlog to "Ready" or add a stage called "Security review" without changing any workflow.

Two rules follow from the roles:

• A status change dispatches a run only when the issue lands in a stage with the role intake, inflight, review or rework. A hold stage runs a card only on an explicit mention. Stages with the role done or closed never dispatch.
• The role cannot be changed on an existing stage, and an override can never set one. Work already in flight keeps its meaning.

Where stages are defined: the cascadeCopy Anchor Link

Stage definitions resolve through four scopes, from the broadest to the narrowest:

system  ->  org  ->  project  ->  workflow

The set of stages a project sees is computed from these scopes each time. It is never copied, so a change at the org level reaches every project that has not overridden it.

At each scope you can do three things.

Rules the platform enforces:

• A key can be defined only once in a chain. Defining a key that already exists at or above your scope is refused; create an override instead.
• An override needs a stage with that key defined above it.
• Outcome targets must name stages in the effective set of the scope you are writing, or stay.
• Removing a stage you defined (Remove) or dropping your override (Reset) archives your row. Removing a stage is refused while a tracker's status mapping still points at it.

Fields inherit one by one. A project that overrides only the description of Review still gets the org's outcomes and cards. Outcomes merge per outcome, so a project can change success on one stage without restating the other four.

Each stage in the settings list shows where it stands at the scope you are viewing:

Where to editCopy Anchor Link

• Organization: Settings, then Stages. Organization admins edit; members see a read-only view.
• Project: the project's Settings, then Stages. Project admins edit; other members see a read-only view. This page also holds the tracker status mapping and the first-run checklist from First-Run Setup.
• Workflow: a workflow can override stages for itself. Workflow-scope rows are written through the project stages API with a workflowId; the settings pages show the org and project scopes.

Map tracker statuses to stagesCopy Anchor Link

A project's tracker has its own status names. The status mapping tells the platform which stage each status belongs to. Each tracker linked to a project has its own mapping, so a project can use more than one tracker.

The mapping has two parts:

• Reading: each tracker status maps to exactly one stage. Several statuses can map to the same stage (for example, both Triage and Backlog to backlog). Only enabled stages can be mapped.
• Writing: reading maps many statuses to one stage, but writing needs a single answer. Every mapped stage therefore names one write status: the tracker status the platform sets when work moves into that stage. The write status must be one of the statuses that map to that stage.

A save is refused with the reason if a status maps to a stage that does not exist or is disabled, if a stage is mapped without a write status, or if a write status is not one of that stage's own statuses.

Example mappings:

In the project's Stages page, choose a stage for each status, pick the write status for each mapped stage, and select Save mapping. Saving writes only that tracker's mapping.

An issue whose status is mapped to no stage does not start a run. With the portable template, the platform replies once on the issue asking you to map the project's statuses.

What the agent is told about its stageCopy Anchor Link

A dispatch carries a short stage context, and the same text goes into the starting prompt:

• the stage name and role;
• the tracker status the issue was dispatched from;
• the card that runs and why it was chosen (the stage default, a matching condition, a mention, or a card the workflow fixed);
• the issue's parent, and a bounded list of its sub-issues with their statuses.

Tracker text in this block is cut to one line and a fixed length. Issue descriptions are never included.

In the CLICopy Anchor Link

The CLI shows the same vocabulary. rensei host watch groups the runs waiting under the platform strip by stage and role, in the form Stage name · role, with the dispatched card's handle. When the platform sends no stage for a run, the line falls back to the run's work type. Topology cards use the same label on their issue line. Labels that come from the platform are length-bounded and stripped of control characters before they are drawn in the terminal.

The dispatch-budget reset command renamed its --stage build|review flag to --phase, because a budget phase is a spend bucket and not a workflow stage. --stage still works there as a hidden, deprecated alias that prints a notice, and passing both with different values is refused.

The card listing commands (agent cards list and marketplace browse) also accept a --stage filter. It needs a platform that reports each card's stage, and the dispatch cards route does not report one yet, so the CLI refuses the flag with a message naming it instead of returning an empty list.

APICopy Anchor Link

Org routes accept a browser session, a user token or an org-wide API key. Project routes accept a session or a user token only. Org routes take the organization id and project routes the project id.

A PUT to the cards route replaces that scope's full list for the stage. A write that names a model or profile the scope cannot see is answered with 404, and a duplicate card or more than one default is a 400.

Related pagesCopy Anchor Link

• Stage Cards
• Outcomes and Transitions
• Work Types
• Default SDLC Template
• First-Run Setup