Skip to main content
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: 
GET /browse/:key/transitions
Or with the CLI: 
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:
ModeDescription
Text acknowledgmentThe caller must explicitly accept a requirement description
Checklist itemsThe caller must confirm each item in a list is complete
To progress through a stage gate via the API: 
POST /browse/:key/stage-gates/:gateKey/progress
Or with the CLI: 
# 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: 
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: 
GET  /workflows/:id/fields
POST /workflows/:id/fields

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

1

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.
2

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.
3

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.
4

Advance through stage gates

Call POST /browse/:key/stage-gates/:gateKey/progress as you complete each stage gate.
5

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.
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.

​
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.
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.

​
Managing workflows

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