Stage Cards

An agent card says what an agent is. A stage card is that card's membership in a stage: it says that this card may run when an issue is in this stage, and how. A card can sit in many stages. Research, for example, can run in Icebox and also in Rework.

This is what keeps workflows small. Adding a card to Icebox is a change to the Icebox stage, not an edit to workflow nodes. The shipped workflow calls one generic "dispatch stage" step, and that step asks the stage which card to run.

What a stage card holdsCopy Anchor Link

The same card can use a stronger model as a reviewer in one stage and a cheaper one in another, because model selection lives on the stage card.

How the platform picks the cardCopy Anchor Link

When an issue enters a stage, or the agent is mentioned on it, the platform picks one card. The first rule that applies wins.

1. A mention names a card listed on the stage. That card runs, and the run records that it was chosen by mention.
2. A mention names a card the stage does not list. Nothing runs, and the platform replies with the cards the stage does list.
3. A listed card's condition matches. The first such card, in position order, runs instead of the default.
4. The stage has a default card. It runs.
5. Otherwise nothing runs. A stage with cards but no default replies once asking for a mention. A stage with no cards at all runs nothing.

A card the workflow fixes explicitly overrides this choice, and the run records the reason as workflow. A hold stage still refuses a workflow-fixed card unless the dispatch came from a mention.

MentionsCopy Anchor Link

Mention the agent and put the card right after it, in the first words of the comment:

@rensei research Why is the nightly import slow?
@rensei backlog-writer Turn the research above into a backlog item

The platform removes the @mentions, reads the first words of what is left, and matches them, ignoring case, against each card listed on the stage:

• the card's handle, which is its name in lowercase with words joined by dashes (Backlog Writer becomes backlog-writer);
• the card's metadata id, such as sdlc.backlog-writer;
• any mention keyword set on that stage card.

A keyword must be followed by a space, a colon or the end of the comment, so research: and research Why... both match. When two names could match, the longer one wins.

A one-word mention that names no card at all (for example @rensei reasearch) gets a reply listing the cards the stage offers. A longer mention that matches no card is treated as a plain request, and the stage's normal choice applies.

Conditions: hasChildrenCopy Anchor Link

A condition lets one stage run different cards for different issues. The only condition in 1.0 is hasChildren. The system Backlog stage uses it:

An issue in Backlog with sub-issues runs Development Coordination. An issue without them runs Development. If the payload that reached the platform does not say whether the issue has children, the condition is treated as unknown and does not match, so the default runs.

In the stage cards editor the condition is the checkbox Only when the issue has sub-issues. A condition set at a higher scope cannot be cleared from a lower one.

Hold stages accept mentions onlyCopy Anchor Link

A stage with the role hold never dispatches on its own. Moving an issue into Icebox does not start Research. A mention does:

• @rensei research ... in Icebox runs Research.
• @rensei backlog-writer ... in Icebox runs Backlog Writer.
• A bare mention with no card name in a hold stage gets a reply that the stage is on hold, with the list of cards you can mention.

A bare mention in a hold stage does not fall back to the stage's default card. You always name the card.

Replies when nothing runsCopy Anchor Link

Edit a stage's cardsCopy Anchor Link

Open Settings, then Stages, at the organization or project level and choose Edit on a stage (or Customize first, if the stage is inherited). The cards section lists each card with where it comes from.

• Add a card. Pick from Add a card. Cards are found and installed in the Marketplace, under Agents, and placed here.
• Make a card the default. Select the radio button next to it.
• Mention keywords. Add words that should select this card.
• Condition and position. Tick Only when the issue has sub-issues, and set the order.
• Model. Use Model for this card to override the model. Leaving it as inherit uses the stage's, project's, org's or system's model.
• Exclude. Hides an inherited card at this scope. Include again undoes it.
• Reset card. Drops this scope's changes to an inherited card. Remove deletes a card you added here.

Choose Save cards to write the list.

Cards combine across scopes. A scope can add cards, exclude inherited ones, and change a card's fields one at a time. The default is the lowest scope's default whose card is still in the stage.

Which cards a stage may hold depends on its scope. An org stage can hold system cards and the org's cards. A project stage can also hold that project's cards. A stage cannot hold a card that is not visible to its scope.

Related pagesCopy Anchor Link

• Stages and Roles
• Outcomes and Transitions
• Agent Cards
• Skills