Reusable case workflows
Reusable case workflows give a company a shared set of instructions for repeatable work. A workflow definition is adopted by a case, copied into the primary task as its working instructions, and then used as agents move the same task through named phases. This page complements agent work management, issue execution, and case handoffs and continuity.
Workflow definitions
Workflow definitions are company-scoped templates for case work. They contain a name and a Markdown prompt that describes the intended phases, evidence, handoffs, waits, and completion rules. The prompt is guidance for agents, not a server-enforced state machine.
Reusable instructions
The reusable definition gives new cases a consistent starting point without making their later work share one mutable document. A case adopts the latest prompt when it starts work or when a later handoff selects the definition.
Definitions can be changed for future adoptions. Existing cases keep the task copy that they already adopted, so a refresh must be an explicit workflow adoption during a handoff. This keeps an in-progress case stable while allowing the company template to improve.
References: packages/…/workflows.ts• L5-14 packages/…/workflows.ts• L17-43 packages/…/case-data.ts• L98-101
Workflow guidance
Workflow text can describe a phase graph with Mermaid and prose. The guidance should name each transition, its condition, required output, destination agent, human wait behavior, and bounded correction or retry path. The server stores this content and records transitions, but agents decide when the described transition is ready.
References: packages/…/case-data.ts• L116-135 packages/…/handoff-case.ts• L3
Case and task orchestration
A case is the durable business record, while its primary task is the executable work record. The primary task keeps one task identity as agents change, and each handoff changes the current phase, assignment, instructions, and optional workflow adoption.
Case kickoff
Case kickoff creates or selects a case, establishes its primary task, assigns the first agent, and supplies the first phase. The kickoff can use a reusable workflow ID or provide inline workflow text. In either path, the selected instructions become the task document with the reserved workflow key before the agent starts.
The same entry point can seed other task documents. These documents support the work but do not replace the workflow document. A case cannot silently reuse an unrelated task as its primary task.
References: packages/…/case-data.ts• L137-165 server/…/case-handoffs.ts• L386-505
Case handoffs
An agent handoff transfers the primary task to another agent and records the next phase. The handoff carries the sender's instructions and version checks, then applies the assignment and workflow change only after the outgoing execution is safe to release.
The workflow choice has three meanings:
- Omit
workflowIdto keep the current definition and task instructions. - Supply a workflow ID to adopt its latest prompt, including the current ID to refresh the task copy.
- Supply
nullto detach the case from the shared definition while keeping its current task instructions.
The handoff history records the previous and next workflow, phase, and task-document revision. This makes routing changes visible without making the shared definition the source of truth for an already active case.
References: server/…/case-workflows.ts• L8-23 server/…/case-workflows.ts• L25-45 server/…/case-handoffs.ts• L242-282 packages/…/handoff-case.ts• L3
Task completion
Completion is a terminal handoff on an existing primary task. It records the final phase and instructions, then lets the normal task completion path close the case. The case does not create a replacement task for the final step.
References: server/…/case-handoffs.ts• L285-333 packages/…/handoff-case.ts• L37-45
Native runner workflow tools
Workflow-aware native runner tools let an agent inspect and maintain company workflow definitions through the same governed runner boundary used for case work. They are available only when the Cases feature is enabled and remain bound to the agent's company.
Workflow tool actions
The runner exposes four focused actions:
| Action | Purpose |
|---|---|
list_workflows | Find reusable definitions in the current company. |
read_workflow | Read a definition's name and prompt. |
create_workflow | Publish a new company-shared definition. |
update_workflow | Change a definition for future adoptions. |
Create and update use an idempotency key so a lost response can be retried without creating a second change. Large reads use bounded text pages and a content snapshot; a changed definition requires a fresh read from the start.
References: packages/…/workflows.ts• L9-43 server/…/native-workflow-tools.ts• L9-44
Workflow and case boundaries
A workflow definition is task data, not trusted system instruction. Reading a definition does not change the active case, and updating a definition does not update existing task documents. Agents use the case and handoff tools to adopt a definition and move work.
References: packages/…/workflows.ts• L17-43 packages/…/case-data.ts• L54-61 packages/…/handoff-case.ts• L3
Lifecycle execution
The workflow lifecycle joins a shared prompt to a durable task and then carries the task through controlled handoffs. The server checks the current case, task, assignment, and version before it applies each transfer, while the runner starts the next agent only after the prior execution settles.
This diagram shows how a definition becomes task instructions and how the task moves through repeatable phases.
flowchart LR
D[Shared workflow definition] --> K[Case kickoff]
K --> T[Primary task with workflow document]
T --> R[Agent runs current phase]
R --> H[Handoff request]
H --> C{Adopt workflow?}
C -->|Keep| N[Next phase and agent]
C -->|Refresh or select| A[Copy selected prompt to task]
C -->|Detach| X[Keep task instructions without shared link]
A --> N
X --> N
N --> R
R --> F[Terminal completion]
Handoff lifecycle
When an agent requests a handoff, the system first records durable intent. It then validates ownership and versions, applies any selected workflow prompt, reassigns the same task, and wakes the receiving agent. A conflict leaves the prior task state intact and requires the caller to reload current case or task data.
References: server/…/case-handoffs.ts• L336-385 server/…/case-handoffs.ts• L411-528 server/…/case-handoff-lifecycle.ts• L156-221
Execution context
The active task document is the working copy that agents read during execution. A retained run receives changed case facts and handoff instructions, while a new or unproven run receives the needed case bootstrap. The reusable definition remains a source for adoption rather than a live instruction stream.
References: server/…/case-workflows.ts• L25-45 server/…/case-context-projection.test.ts• L56-86 packages/…/workflows.ts• L17-20
API and UI surfaces
The API and native runner expose the write paths for repeatable work, while the web UI gives operators a read view of current case execution. Together they show which workflow and phase are active, which task and agent own the work, and where a handoff is waiting or has failed.
Workflow API
The workflow API lists and reads company definitions and creates or updates them when the Cases feature is enabled. Company access is checked for every operation, and full reads return a snapshot suitable for safe continuation.
References: server/…/workflows.ts• L11-44 server/…/workflows.ts• L29-64 packages/…/workflows.ts• L4-17
Case operation API
Case creation and handoff APIs connect a definition to executable work. They support a reusable workflow ID or inline workflow text at kickoff, and later handoffs can preserve, refresh, or detach the current workflow. The same APIs expose handoff retry and cancellation for work that is waiting for delivery.
References: packages/…/case-data.ts• L137-165 ui/…/cases.ts• L346-364 server/…/case-handoffs.ts• L534-539
Case work views
The Cases list supports search, filters, grouping, sorting, and paging. The case detail view shows the primary task, workflow name, phase, assignee, task status, documents, and handoff history. Handoff rows show the workflow transition and any current wait or error, so operators can follow the same lifecycle that agents use.
References: ui/…/Cases.tsx• L41-69 ui/…/CaseDetail.tsx• L92-145 ui/…/CaseWorkSummary.tsx• L29-47 ui/…/CaseHandoffHistory.tsx• L22-76
Change checklist
When these files or sections are changed, remember to consider these:
- Keep reusable-definition changes separate from task-document adoption. Updating a shared prompt must not silently rewrite active cases.
- Keep
workflowId, the task'sworkflowdocument, case phase, and handoff transition aligned when changing kickoff or handoff contracts. - Keep paged workflow reads tied to their snapshot and keep create or update retries tied to the same idempotency key and input.
- Keep API, native runner action schemas, and UI case payloads consistent when adding workflow or handoff fields.
- Keep handoff version and task status version checks aligned with assignment changes so a stale transfer cannot move the primary task.
Important failure modes
| Trigger | Consequence | Guard |
|---|---|---|
| A shared workflow is edited after a case adopts it | The case continues with its task copy and does not receive the edit | Require an explicit workflow adoption during a later handoff |
| A paged workflow read continues without the returned snapshot | The response can mix revisions or be rejected after a change | Send the same snapshot with each continuation page and restart at offset zero after a conflict |
| A handoff uses stale case or task versions | A newer assignment or decision could be overwritten | Check handoff version and task status version before applying the transfer |
| A task document changes while a workflow adoption waits | The selected prompt could overwrite newer task instructions | Apply the adoption with a base revision and hold on revision conflict |
| A handoff loses its response and uses a new idempotency key | Duplicate case work or duplicate workflow changes can be created | Retry with the original key and identical input |
| Cases are disabled or the actor lacks company access | Workflow or case operation is refused | Enforce the feature gate and company authorization at the API and runner boundary |
Key files
| File | Why to read it |
|---|---|
| server/…/workflows.ts | Defines the shared workflow read and write service and its authorization boundary. |
| server/…/case-workflows.ts | Shows how workflow selection becomes a case transition and task-document adoption. |
| server/…/case-handoffs.ts | Defines case kickoff, handoff application, version checks, and terminal completion. |
| server/…/workflows.ts | Shows the REST surface for listing, reading, creating, and updating definitions. |
| packages/…/workflows.ts | Defines the native runner actions for workflow discovery and maintenance. |
| packages/…/case-data.ts | Defines case kickoff data and the workflow document contract. |
| packages/…/handoff-case.ts | Defines the agent-facing handoff and workflow adoption choices. |
| ui/…/CaseDetail.tsx | Shows the operator view that joins case data, task work, documents, and handoff history. |
| ui/…/CaseWorkSummary.tsx | Shows the current workflow, phase, assignment, task status, and pending work. |
| ui/…/CaseHandoffHistory.tsx | Shows workflow transitions and handoff state over time. |