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

# Managing Work Items

> Create, update, and organize projects, tasks, and sub-tasks in OpenIndex.

Work items are the core unit of work in OpenIndex. Every piece of work — whether a large initiative, an individual task, or a granular step — lives as a work item with a consistent structure and key.

OpenIndex has three kinds of work items that follow the hierarchy `Project → Task → Sub-task`:

<CardGroup cols={3}>
  <Card title="Project" icon="folder">
    A container for larger objectives inside a domain.
  </Card>

  <Card title="Task" icon="check-square">
    A standard executable work item under a project.
  </Card>

  <Card title="Sub-task" icon="list">
    A granular step under a task, keyed as `DOMAIN-123.1`.
  </Card>
</CardGroup>

Work-item keys are domain-scoped and sequential — for example, `OPS-42` or `OPS-42.1` for a sub-task.

***

## Creating a work item

### Via CLI

```bash theme={null}
# Create a task in a domain
oi work-item create --kind task --title "My task" --domain-id <id>

# Create a sub-task under a parent
oi work-item create --kind sub_task --title "Sub-task" --parent-key ABC-123
```

Additional create flags:

| Flag                 | Description                        |
| -------------------- | ---------------------------------- |
| `--workflow-id`      | Attach a workflow at creation time |
| `--description`      | Body text for the work item        |
| `--status`           | Initial status value               |
| `--priority`         | Priority level                     |
| `--execution-target` | `human`, `agent`, or `either`      |
| `--assignee-user-id` | Assign to a specific user          |
| `--owner-user-id`    | Set the owner                      |

### Via API

`POST /browse` with a JSON body:

```json theme={null}
{
  "kind": "task",
  "title": "My task",
  "domainId": "<domain-id>",
  "parentKey": "ABC-123",
  "workflowId": "<workflow-id>",
  "description": "Optional description",
  "status": "backlog",
  "priority": "medium",
  "executionTarget": "agent"
}
```

***

## Listing work items

```bash theme={null}
oi work-item list
```

Filter the list with any combination of these flags:

| Flag                 | Description                              |
| -------------------- | ---------------------------------------- |
| `--kind`             | `project`, `task`, or `sub_task`         |
| `--domain-id`        | Scope to a domain                        |
| `--status`           | Filter by status value                   |
| `--priority`         | Filter by priority                       |
| `--execution-target` | `human`, `agent`, or `either`            |
| `--search`           | Full-text search across titles           |
| `--parent-key`       | List children of a specific work item    |
| `--assigned-to-me`   | Show only items assigned to you          |
| `--resolution`       | `unresolved`, `resolved`, or `cancelled` |

***

## Getting a work item

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

This returns the full work item record, including its current status, priority, workflow assignment, schedule, and metadata.

The equivalent API call is `GET /browse/:key`.

***

## Updating a work item

```bash theme={null}
oi work-item update ABC-123 --title "New title"
```

Available update flags:

| Flag                 | Description                      |
| -------------------- | -------------------------------- |
| `--title`            | Update the title                 |
| `--description`      | Update the body                  |
| `--status`           | Change the status                |
| `--priority`         | Change the priority              |
| `--workflow-id`      | Reassign to a different workflow |
| `--execution-target` | Change execution target          |
| `--assignee-user-id` | Reassign to a user               |

The equivalent API call is `PATCH /browse/:key`.

<Note>
  Status changes must respect valid workflow transitions. Use `oi work-item transitions ABC-123` to see which statuses are reachable from the current state.
</Note>

***

## Scheduling a work item

You can schedule work to a specific date or a timed block, or clear a schedule to move it back to the backlog.

```bash theme={null}
# Date-only scheduling
oi work-item schedule ABC-123 --date 2026-03-01

# Timed scheduling
oi work-item schedule ABC-123 --start 2026-03-01T15:00:00Z --end 2026-03-01T16:00:00Z

# Clear schedule (back to backlog)
oi work-item schedule ABC-123 --clear
```

Scheduled work items appear alongside external calendar events in the calendar view.

***

## Managing comments

Comments let you leave notes and collaborate on a work item. You can control visibility to keep some notes internal.

```bash theme={null}
# Create a comment
oi work-item comment create ABC-123 --body "This is a comment"

# Create an external-visible comment
oi work-item comment create ABC-123 --body "Update for the customer" --visibility external

# List comments
oi work-item comment list ABC-123

# Update a comment
oi work-item comment update ABC-123 --comment-id <id> --body "Updated text"

# Delete a comment
oi work-item comment delete ABC-123 --comment-id <id>
```

The `--visibility` flag accepts `internal` (default) or `external`. External comments are visible in email conversation threads.

***

## Managing attachments

You can attach local files or link external URLs to a work item.

```bash theme={null}
# Upload a file
oi work-item attachment upload ABC-123 --file ./report.pdf

# Link a URL
oi work-item attachment link ABC-123 --url "https://example.com/doc" --filename "Design doc"

# List attachments
oi work-item attachment list ABC-123

# Delete an attachment
oi work-item attachment delete ABC-123 --attachment-id <id>
```

***

## Managing dependencies

Track relationships between work items using dependencies.

```bash theme={null}
# Create a dependency
oi work-item dependency create ABC-123 --to-key DEF-456

# List dependencies
oi work-item dependency list ABC-123

# Delete a dependency
oi work-item dependency delete ABC-123 --dependency-id <id>
```

The API equivalents are `POST /browse/:key/dependencies`, `GET /browse/:key/dependencies`, and `DELETE /browse/:key/dependencies/:dependencyId`.

***

## Managing categories

Categories are domain-scoped labels for organizing work items.

```bash theme={null}
# Assign a category
oi work-item categories add ABC-123 --category-id <id>

# Remove a category
oi work-item categories remove ABC-123 --category-id <id>
```

The API equivalents are `POST /browse/:key/categories` and `DELETE /browse/:key/categories/:categoryId`.

***

## Viewing hierarchy

See the full parent-child tree for a work item:

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

The API equivalent is `GET /browse/:key/hierarchy`.

***

## Audit history

Every mutation to a work item is recorded. To inspect the change history:

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

You can also export the audit log:

```bash theme={null}
oi work-item audit export ABC-123 --format json --output ./audit.json
```

***

## Deleting a work item

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

The API equivalent is `DELETE /browse/:key`. Deletion is permission-checked and key-targeted.

<Warning>
  Deleting a work item is permanent. There is no undo.
</Warning>