> ## Documentation Index
> Fetch the complete documentation index at: https://playerzero.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuring Workflows

> Set up stages, transitions, approvals, archival, and manage workflows through the visual builder and inbox.

## Stages

Each stage defines what the agent does during that phase of work.

### Stage Properties

| Property            | Description                                                                                                                                                                                                                                                                        |
| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Name**            | Short identifier (e.g., "Triage", "RCA", "Fix"). Must be unique within a project.                                                                                                                                                                                                  |
| **Instructions**    | Detailed prompt for the agent — what to do, what to look for, what outputs to produce. Supports the `/` slash command to insert [Skill](/docs/features/playbooks) instructions.                                                                                                         |
| **Type**            | Derived from the transitions you draw: **Entry** (starting point, each workflow may only have one entry stage), **Work** (intermediate), or **Terminal** (end point, may have multiple). Stage types are listed as **Unassigned** if they have no connections to any other stages. |
| **Model**           | How much horsepower the stage's work gets: **Economy**, **Standard** (the default), or **Pro** (unlocks a team of agents).                                                                                                                                                         |
| **Auto-approve**    | If enabled, transitions out of this stage happen without human approval.                                                                                                                                                                                                           |
| **Approver config** | Who can approve: **Let PlayerZero decide** (based on available context), **Specific individuals**, or **Someone from a specific role**.                                                                                                                                            |
| **Run simulations** | Whether the agent validates its work at this stage with scenario simulations. Off by default, with optional guidance on what to simulate.                                                                                                                                          |
| **Archive config**  | How completed threads are archived: **Never**, **Manual**, or **Automatic** (after N days).                                                                                                                                                                                        |
| **Ask a human**     | Optional guidance on when the agent should stop and escalate to a person.                                                                                                                                                                                                          |

### Referencing a Skill in Stage Instructions

Type `/` in a stage's **Instructions** field to browse your organization's Skills, then press **Enter** on the one you want. The Skill appears in the prompt in bold and underlined, and the workflow references it at the point that stage runs.

This is a good way to combine organization-wide best practices with project-specific process. Encode the standards that should hold everywhere — document brand and style guidelines, or branch naming and commit rules — as Skills, then reference them from whichever team's workflow needs them. Each team keeps its own stages while drawing on the same shared conventions.

### Stage Types

A stage's type is read from the transition graph. Every workflow keeps exactly one **Entry** stage, and the rest follows from how you connect things.

* **Entry**: Where work can start. One stage per workflow holds this designation, and it keeps it even when other stages transition back into it.
* **Work**: Transitions to another stage in the same workflow. This is where intermediate processing happens.
* **Terminal**: Reachable from the graph but never routes to another stage, including a stage whose only next step hands work to a different workflow. Work concludes here.
* **Unassigned**: Connected in neither direction. A stage you have just created reads as unassigned until you draw a transition.

### Execution Mode

The **Model** setting decides how much horsepower a stage's work gets. Each mode runs an ordered set of models that PlayerZero refines and updates over time, so a stage keeps its intent as the underlying models change.

* **Economy**: Its own set of faster, less expensive models, for routine, low-risk work.
* **Standard**: The default. A balance of quality, speed, and cost for everyday work.
* **Pro**: For complex or high-stakes work. Pro is the only mode where the agent can put a team of agents on the task instead of working alone, using [Hive Mode](/docs/features/hive-mode), and it is billed at a higher rate than Standard.

Set it per stage, so a triage stage can run Economy while the stage that investigates or writes a fix runs Pro.

### Running Simulations at a Stage

Turn on **Run simulations at this stage** and the agent validates its work there with [Code Simulations](/docs/features/code-sim) before asking to move on. When it is on, you can add guidance describing what to simulate at that stage and how the agent should use the results.

### Using Stages to Trigger Integration Actions

If your project has connectors enabled (e.g., Jira, Linear, Slack), the AI agent can use those integrations as part of any stage. Write stage instructions that tell the agent when and how to use them.

**Examples:**

* **Create a Jira ticket after triage:** *"After completing your analysis, create a Jira ticket in the PROJ project summarizing the issue, severity, and recommended fix. Include code references."*
* **Post to Slack:** *"Notify the #engineering channel in Slack with a summary of your findings."*
* **Update a Linear issue:** *"Update the linked Linear issue with your root cause analysis and change the status to In Progress."*

The agent automatically has access to all connected integrations — you don't need to configure anything beyond writing clear instructions in the stage's instruction field. The agent decides how to use the tools based on your instructions and the conversation context.

<Note>
  Integration actions require the relevant connector to be set up at the project or organization level. See [Connectors](/docs/connector/introduction) for setup guides.
</Note>

***

## Transitions

Transitions define the allowed paths between stages.

### Creating a Transition

In the workflow builder, draw a connection from one stage to another. A dialog will prompt you to describe the transition conditions — the rules that tell the agent when to take this path.

### Transition Conditions

Each transition includes an instruction field. Write specific conditions, not vague ones:

* **Good**: "Promote to Fix when root cause has been clearly identified, the issue requires code changes, and failing scenarios demonstrate the bug."
* **Avoid**: "Move to the next stage when ready."

The agent uses these conditions to decide which transition to request.

***

## Approvals

### Auto-approve vs. Manual

* **Auto-approve on**: The agent transitions immediately when it determines the stage work is complete.
* **Auto-approve off** (default): The agent requests the transition and waits for a human to approve.

When a human reviews a transition request, they are approving the work completed in the current stage — confirming the agent's output meets expectations before it moves on.

### Approver Configuration

* **Let PlayerZero decide**: The agent suggests an approver based on available context (e.g., who last modified the affected code). Any project member can approve.
* **Specific individuals**: Specific team members are designated as approvers for that stage. Only they can approve.
* **Someone from a specific role**: Anyone whose job role is on the list can approve, so the gate survives a person changing teams or leaving.

When a stage names individuals or roles, that restriction holds. The request can only be passed to someone else on the list.

<Note>
  If the configured approvers match no current member of the organization, PlayerZero routes the request to whoever it can rather than leaving it unanswerable.
</Note>

***

## Archival

### Archive Modes

| Mode          | Behavior                                                                   |
| ------------- | -------------------------------------------------------------------------- |
| **Never**     | Thread is never auto-archived from this stage                              |
| **Manual**    | Users can archive threads manually from the thread title bar or the inbox  |
| **Automatic** | Threads are archived after a configurable number of days (1, 7, 14, or 30) |

Archiving marks a thread with an archived flag — it does not move the thread to a different stage. Archived threads can be viewed using the **Archived** filter in the inbox, with sub-filters for **Manually Archived** and **Automatically Archived**. Archived threads can be restored at any time.

***

## Workflow Versioning

Workflows use a draft and publish lifecycle:

* **Draft** — Edit stages, transitions, and rules without affecting running work. Changes are saved to the draft.
* **Publish** — When the draft is ready, publish it to make it the active version. New work uses the published version.
* **Version history** — PlayerZero keeps every published version. Review past versions and **roll back** to a previous one when needed.

The inbox, monitors, and ticketing resolve against the published version of each workflow.

## Starting from a Template

PlayerZero ships with built-in workflow templates you can use as starting points: Documentation, Engineering Scoping, L1 Support, PR Review, Product Scoping, QA Testing, and SRE Alert Response. Create a new workflow from a template, then adjust the stages to fit how your team works.

You can also create a workflow by **importing** one — from a JSON export or from another project's published workflow.

## The Workflow Builder

The visual editor for designing workflows. Access it from **Project Settings → Workflows** in your project, then open a workflow to edit its stages and transitions on the canvas.

### Canvas

* **Drag and drop** stage nodes to arrange the layout
* **Draw connections** between stages to create transitions
* **Click a stage** to view or edit its properties in a side panel
* **Click an edge** to view or edit the transition rule

### Sidebar

Lists all stages grouped by type (Entry, Work, Terminal, Unassigned) with buttons to add new stages.

### Validation

The builder displays warning indicators on stages that are missing:

* Incoming connections (no way to reach this stage)
* Outgoing transitions (non-terminal stage with no next steps)

A stage missing both reads as **Unassigned** rather than passing validation as though it were finished.

### Toolbar

* **Zoom** in/out and fit view
* **Reorganize** — auto-arrange stages in a hierarchical layout
* **Delete all** — reset the workflow. A confirmation dialog prompts you to download a backup before deleting (enabled by default). The backup is a JSON file containing all stages, transitions, agent rules, and layout positions — the same format used by the Export button. Uncheck the backup option if you don't need it.

### Deleting a Stage

When you delete a stage that has active threads, you'll be prompted to choose a destination stage. All threads currently in the deleted stage are moved to the destination, and any pending transition requests targeting the deleted stage are automatically redirected.

If some threads fail to transition (for example, due to a network issue or a stuck session), the dialog shows which threads failed and why. You can retry the operation, or click **Delete Anyway** to remove the stage regardless — threads that couldn't be moved will remain in their current state and can be reassigned manually.

### Export & Import

Export your workflow as JSON (stages, transitions, agent rules, layout positions). Import into other projects to replicate workflows across your organization.

Each stage carries its own settings, including its model and whether it runs simulations, so an imported stage behaves the way it behaved in the project it came from. The same is true when a template you started from publishes an update: those settings are part of what the update offers you.

You can also import directly from another project's published workflow, so a process proven in one project can be reused in another without exporting a file first.

When you export or import a workflow, note that any configured cross-workflow transitions do not convey, and neither do specific approver configurations, whether named individuals or a named role. Only the choice of approver method carries over. This prevents broken configuration in other projects where the specified workflows or people are not available.

When importing into a project that already has stages, the import dialog detects conflicting stage names and lets you resolve each one individually:

* **Merge** — Overwrites the existing stage with the imported definition
* **Create Copy** — Imports the stage as a new stage with an auto-generated unique name (e.g., "Triage (1)")

When conflicts are found, all are initially set to Merge. You can change individual stages to Copy, or use the bulk action buttons to set all conflicts to the same resolution at once.

Stages that don't conflict with existing names are imported automatically without prompting.

***

## The Workflow Inbox

The inbox is the operational view for managing active threads across your workflow. For full documentation, see [Workflow Inbox](/docs/features/workflow-inbox).

***

## Related

* [Monitors](/docs/features/monitors) — Set up automated checks that can trigger workflow stages on failure