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

> Understand the Domain → Project → Task → Sub-task hierarchy in OpenIndex.

Every piece of work in OpenIndex lives in a four-level hierarchy. Understanding this structure helps you create, organize, and act on work correctly — whether you're a human configuring a domain or an agent executing tasks.

## The hierarchy

```
Domain
└── Project
    └── Task
        └── Sub-task
```

<CardGroup cols={2}>
  <Card title="Domain" icon="building">
    The top-level operational boundary. Owns workflows, members, categories, mailboxes, and all work items beneath it.
  </Card>

  <Card title="Project" icon="folder">
    A container for a larger objective inside a domain. Groups related tasks under a single trackable item.
  </Card>

  <Card title="Task" icon="check">
    The standard executable work item under a project. Tasks are what humans and agents actually do.
  </Card>

  <Card title="Sub-task" icon="list">
    A granular executable unit under a task. Sub-tasks let you break a task into independently trackable steps.
  </Card>
</CardGroup>

## Work item kinds

Every work item has a `kind` field that identifies its level in the hierarchy:

| Kind       | Description                                   |
| ---------- | --------------------------------------------- |
| `project`  | Container for a larger objective              |
| `task`     | Standard executable work item under a project |
| `sub_task` | Granular executable work item under a task    |

## Work item keys

Work item keys are domain-scoped and sequential. When you create a work item in a domain with the key `OPS`, the platform assigns keys like `OPS-1`, `OPS-2`, `OPS-123`.

Sub-task keys extend their parent task key with an ordinal suffix:

| Item            | Key         |
| --------------- | ----------- |
| Task            | `ABC-123`   |
| First sub-task  | `ABC-123.1` |
| Second sub-task | `ABC-123.2` |

<Note>
  Tasks can only move within the same domain. You cannot reassign a task from one domain to another — keys are permanently scoped to the domain where the item was created.
</Note>

## Work item fields

Every work item shares a common set of fields:

| Field              | Description                                                   |
| ------------------ | ------------------------------------------------------------- |
| `title`            | Short label for the work item                                 |
| `description`      | Free-text detail about the work                               |
| `status`           | Current workflow status (e.g., `todo`, `in_progress`, `done`) |
| `priority`         | Relative urgency of the item                                  |
| `execution_target` | Who should execute this item: `human`, `agent`, or `either`   |
| `assignee`         | The user currently assigned to the item                       |
| `owner`            | The user who owns the item                                    |
| `schedule`         | Optional date or datetime range for when work is planned      |

The `execution_target` field is particularly important for agent workflows. When an agent calls `oi queue list`, only items with `execution_target` set to `agent` or `either` appear in the `available` bucket.

## Categories

Categories are domain-scoped labels you attach to work items for organization and filtering. A work item can have multiple categories.

You manage categories on a work item through the `/browse/:key/categories` endpoint:

```bash theme={null}
GET  /browse/:key/categories
POST /browse/:key/categories
DELETE /browse/:key/categories/:categoryId
```

## Dependencies

Work items can depend on other work items. Dependencies let you express ordering and blocking relationships across your backlog.

```bash theme={null}
GET    /browse/:key/dependencies
POST   /browse/:key/dependencies
DELETE /browse/:key/dependencies/:dependencyId
```

## Comments

Comments on work items support two visibility levels:

| Visibility | Description                                                   |
| ---------- | ------------------------------------------------------------- |
| `internal` | Visible only to domain members (default)                      |
| `external` | Included in outbound email threads for external collaborators |

```bash theme={null}
oi work-item comment create ABC-123 --body "Investigation complete." --visibility internal
```

## Attachments

You can attach files or link external URLs to any work item. File uploads go through a two-step initiate/complete flow; URL attachments are added directly.

```bash theme={null}
oi work-item attachment upload ABC-123 --file ./report.pdf
oi work-item attachment link  ABC-123 --url https://example.com/doc
```

## Custom fields

Workflows can define additional fields that are required when a work item transitions through specific stage gates. These custom fields are stored per work item and keyed to the workflow definition.

```bash theme={null}
oi work-item custom-fields get ABC-123
oi work-item custom-fields update ABC-123 --values-json '{"acceptance_criteria": "All tests pass"}'
```

<Tip>
  Use `oi work-item agent-context ABC-123` to see which custom fields are required before you can advance through the next stage gate. The response includes `requiredFields` for the current transition.
</Tip>

## Audit history

Every mutation to a work item — status changes, field updates, comments, assignments — is recorded in the audit log. You can retrieve and export the history for any item:

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

The audit log includes correlation IDs, making it easy to trace a sequence of related changes.