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

# Workflows

> How workflows, statuses, stages, and stage gates control work progression in OpenIndex.

Workflows define the lifecycle of your work. They control which statuses are available, how work progresses through stages, and what requirements must be met before moving forward. Every work item in OpenIndex follows a workflow.

## What a workflow is

A workflow is a process definition scoped to a domain or a personal domain. It specifies:

* The **statuses** a work item can be in
* The valid **transitions** between statuses
* The **stages** that group statuses into logical phases
* The **stage gates** that checkpoint transitions between stages
* The **custom fields** required at specific stage transitions

Once a workflow is assigned to a work item, the `workflowId` is immutable. Status transitions, stage gate requirements, and custom field validation are all enforced server-side against that workflow definition — invalid moves are rejected before they reach storage.

## Components

### Statuses

Statuses are the discrete states a work item can occupy at any moment — for example, `todo`, `in_progress`, `blocked`, `done`. The set of valid statuses and the transitions between them are defined by the workflow.

The server validates every status transition. To see which transitions are available from the current status of a work item:

```bash theme={null}
GET /browse/:key/transitions
```

Or with the CLI:

```bash theme={null}
oi work-item transitions ABC-123
```

The response includes `allowedTransitions`, `terminalStatuses`, and `availableStageGates` — everything you need to plan the next move.

### Stages

Stages are logical groupings of statuses for progression tracking. Where statuses describe the exact current state, stages describe the broader phase — for example, a "Review" stage might include both `in_review` and `awaiting_approval` statuses.

Stages give you a coarse-grained view of where work is in its lifecycle without needing to reason about every individual status value.

### Stage gates

Stage gates are transition checkpoints between stages. Before work can move from one stage to the next, the gate's requirements must be satisfied.

A stage gate can require:

| Mode                | Description                                                 |
| ------------------- | ----------------------------------------------------------- |
| Text acknowledgment | The caller must explicitly accept a requirement description |
| Checklist items     | The caller must confirm each item in a list is complete     |

To progress through a stage gate via the API:

```bash theme={null}
POST /browse/:key/stage-gates/:gateKey/progress
```

Or with the CLI:

```bash theme={null}
# Accept a text requirement
oi work-item progress ABC-123 --stage-gate-key review_gate --accept-requirements-text

# Complete checklist items
oi work-item progress ABC-123 --stage-gate-key deploy_gate \
  --checked-requirement-item "Tests passing" \
  --checked-requirement-item "Changelog updated"
```

You can also resolve the gate by stage rather than gate key:

```bash theme={null}
oi work-item progress ABC-123 --to-stage completed
```

### Custom fields

Workflows can define additional fields that extend the base work item model. These custom fields can be required when progressing through specific stage gates — for example, requiring an `acceptance_criteria` field before a task can move to "Done".

Custom field values are stored per work item and keyed to the workflow:

```bash theme={null}
GET  /workflows/:id/fields
POST /workflows/:id/fields
```

```bash theme={null}
GET  /browse/:key/custom-fields
POST /browse/:key/custom-fields
```

When an agent calls `oi work-item agent-context ABC-123`, the response includes `requiredFields` for the current transition so the agent knows exactly what to populate before attempting to progress.

## How transitions work

<Steps>
  <Step title="Read current state">
    Call `GET /browse/:key/transitions` (or `oi work-item transitions`) to get the current status, allowed transitions, terminal statuses, and available stage gates.
  </Step>

  <Step title="Meet any requirements">
    If the next stage gate has custom field requirements, populate them via `POST /browse/:key/custom-fields`. If it has text or checklist requirements, prepare to pass those when progressing.
  </Step>

  <Step title="Claim the item">
    Call `POST /browse/:key/claim` (or `oi work-item claim`) to move to an in-progress status and set yourself as the active agent.
  </Step>

  <Step title="Advance through stage gates">
    Call `POST /browse/:key/stage-gates/:gateKey/progress` as you complete each stage gate.
  </Step>

  <Step title="Complete the item">
    Call `POST /browse/:key/complete` (or `oi work-item complete`) with a terminal status to mark the work done and clear the active agent fields.
  </Step>
</Steps>

<Note>
  Workflow definitions use an immutable `workflowId` after they are assigned to a work item. Updating the workflow definition does not retroactively change work items that already reference it.
</Note>

## Agent-required stages

Stages can be marked as requiring agent execution. When a work item enters an agent-required stage, an assistant provider must be configured on the instance for that stage to be completable. Instance admins configure assistant providers under `/admin/ai/providers`.

<Warning>
  If no assistant provider is configured and a work item reaches an agent-required stage, the stage gate cannot be progressed until an admin adds a provider. A human override is always available to manually advance or reassign the item.
</Warning>

## Managing workflows

<Tabs>
  <Tab title="API">
    ```bash theme={null}
    GET    /workflows
    POST   /workflows
    GET    /workflows/:id
    PATCH  /workflows/:id
    DELETE /workflows/:id

    GET    /workflows/:id/fields
    POST   /workflows/:id/fields
    PATCH  /workflows/:id/fields/:fieldId
    DELETE /workflows/:id/fields/:fieldId

    # Assign a workflow to a domain
    GET  /domains/:id/workflows
    POST /domains/:id/workflows
    ```
  </Tab>

  <Tab title="CLI">
    ```bash theme={null}
    # List workflows in a domain
    oi settings domain workflows list --domain OPS

    # Get a specific workflow
    oi settings domain workflows get TRIAGE --domain OPS

    # List custom fields for a workflow
    oi settings domain workflows fields list TRIAGE --domain OPS

    # List personal-domain workflows
    oi settings personal workflows list
    ```
  </Tab>
</Tabs>