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

# Work Items

> Create, update, claim, and complete work items with the `oi` CLI.

Work items are the core executable unit in OpenIndex. The `oi work-item` command group covers the full lifecycle: listing, creating, updating, transitioning through workflow stages, scheduling, collaborating via comments, and managing attachments, dependencies, and custom fields.

## List and get

```bash theme={null}
oi work-item list [flags]
oi work-item get <key>
oi work-item agent-context <key>
oi work-item hierarchy <key>
oi work-item delete <key>
```

`agent-context` returns the agent-oriented workflow bundle for a work item. In `--json` mode it returns the full backend payload from `/browse/:key/agent-context`. In human mode it summarises the current goal, allowed exits, blocked exits, and required fields.

### List filters

| Flag                     | Description                                         |
| ------------------------ | --------------------------------------------------- |
| `--key`                  | Filter by work item key                             |
| `--kind`                 | `project`, `task`, or `sub_task`                    |
| `--domain-id`            | Filter by domain                                    |
| `--owner-user-id`        | Filter by owner user ID                             |
| `--assigned-to-me`       | `true` or `false`                                   |
| `--personal-only`        | `true` or `false`                                   |
| `--parent-key`           | Parent key (aliases: `--project-key`, `--task-key`) |
| `--workflow-id`          | Filter by workflow                                  |
| `--status`               | Filter by status                                    |
| `--priority`             | Filter by priority                                  |
| `--execution-target`     | `human`, `agent`, or `either`                       |
| `--active-agent-id`      | Filter by active agent ID (supports `none`)         |
| `--resolution`           | `unresolved`, `resolved`, or `cancelled`            |
| `--resolved-after`       | RFC3339 timestamp                                   |
| `--schedule-granularity` | `none`, `date`, or `datetime`                       |
| `--search`               | Full-text search                                    |

## Create

```bash theme={null}
oi work-item create --kind <project|task|sub_task> --title <text> [flags]
```

| Flag                 | Description                                                   |
| -------------------- | ------------------------------------------------------------- |
| `--domain-id`        | Domain to create the item in                                  |
| `--parent-key`       | Parent work item key (aliases: `--project-key`, `--task-key`) |
| `--workflow-id`      | Workflow to assign                                            |
| `--description`      | Item description                                              |
| `--status`           | Initial status                                                |
| `--priority`         | Initial priority                                              |
| `--execution-target` | `human` or `agent`                                            |
| `--owner-user-id`    | Owner user ID                                                 |
| `--assignee-user-id` | Assignee user ID                                              |
| `--objective-state`  | Objective state value                                         |

## Update

```bash theme={null}
oi work-item update <key> [flags]
```

| Flag                 | Description                              |
| -------------------- | ---------------------------------------- |
| `--title`            | New title                                |
| `--description`      | New description                          |
| `--status`           | New status                               |
| `--priority`         | New priority                             |
| `--workflow-id`      | Reassign workflow                        |
| `--execution-target` | `human` or `agent`                       |
| `--owner-user-id`    | New owner user ID                        |
| `--assignee-user-id` | New assignee user ID                     |
| `--resolution`       | `unresolved`, `resolved`, or `cancelled` |
| `--active-agent-id`  | Set active agent ID                      |
| `--clear-agent`      | Clear the active agent field             |
| `--error`            | Set error message                        |
| `--attempt`          | Set attempt counter                      |

## Claim and complete

```bash theme={null}
oi work-item claim <key> --to-status <status> [--agent-id <id>]
oi work-item complete <key> --to-status <status> [--agent-id <id>]
oi work-item done <key> [--to-stage <stage>]
```

* `claim` requires a valid workflow transition from the current status.
* `complete` requires a valid transition to a terminal status, clears active agent fields, and marks the item as resolved.
* `done` auto-progresses through valid stage gates to a completion stage (`completed` by default).

<Tip>
  If `complete` fails because the target status is not terminal, the CLI suggests `oi work-item progress --to-stage ...` as a next step.
</Tip>

## Progress through stage gates

Use `progress` to advance a work item through a workflow stage gate:

```bash theme={null}
oi work-item progress <key> --stage-gate-key <gate-key> [flags]
oi work-item progress <key> --to-stage <stage-key> [flags]
```

| Flag                         | Description                                     |
| ---------------------------- | ----------------------------------------------- |
| `--stage-gate-key`           | Explicit gate key from `transitions` output     |
| `--to-stage`                 | Resolve gate from current `availableStageGates` |
| `--accept-requirements-text` | Required when gate requirements mode is `text`  |
| `--checked-requirement-item` | Repeat for each completed checklist requirement |
| `--note`                     | Optional audit note                             |

## Transitions

Inspect valid transitions and available stage gates for a work item:

```bash theme={null}
oi work-item transitions <key>
```

Always run this before `claim`, `complete`, or `progress` when you are unsure of the allowed next states.

## Schedule placement

```bash theme={null}
oi work-item schedule <key> --date <YYYY-MM-DD>
oi work-item schedule <key> --start <RFC3339> --end <RFC3339>
oi work-item schedule <key> --clear
```

| Form                | Schedule granularity                                  |
| ------------------- | ----------------------------------------------------- |
| `--date`            | Date-only (`scheduleGranularity: date`)               |
| `--start` + `--end` | Timed (`scheduleGranularity: datetime`)               |
| `--clear`           | Returns item to backlog (`scheduleGranularity: none`) |

## Hierarchy

```bash theme={null}
oi work-item hierarchy <key>
```

Returns the full parent/child hierarchy for a work item, including its domain, project, task, and sub-task relationships.

## Comments

```bash theme={null}
oi work-item comment list <key>
oi work-item comment create <key> --body <text> [--visibility internal|external]
oi work-item comment update <key> --comment-id <id> --body <text>
oi work-item comment delete <key> --comment-id <id>
```

* `--body` is required for `create` and `update`.
* `--visibility` defaults to `internal`. Pass `external` to share the comment outside the team.

## Custom fields

```bash theme={null}
oi work-item custom-fields get <key>
oi work-item custom-fields update <key> --values-json '{"field_key":"value"}'
```

`--values-json` accepts a JSON object keyed by workflow custom field key.

## Attachments

```bash theme={null}
oi work-item attachment list <key>
oi work-item attachment link <key> --url <https://...> [--filename <name>]
oi work-item attachment upload <key> --file </path/file> [--filename <name>] [--mime-type <mime>] [--checksum <value>]
oi work-item attachment delete <key> --attachment-id <id>
```

## Dependencies

```bash theme={null}
oi work-item dependency list <key>
oi work-item dependency create <key> --to-key <other-key>
oi work-item dependency delete <key> --dependency-id <id>
```

## Audit log

```bash theme={null}
oi work-item audit list <key> [filters]
oi work-item audit export <key> [--format json|csv] [--output <path>] [filters]
```

Export the full audit trail for a work item to JSON or CSV. Use `--output` to write directly to a file.