# Work Hub

## What this is

The Work Hub is the Hookshot™ operations center for managing work items, decisions, agent-authored changes, and provider sync. It brings together the work that Proteges do with the human review and approval workflows that keep it safe.

## When to use it

Use the Work Hub when you need to:

* Review and approve or reject changes that a Protege wants to make
* Browse work items across queues and portfolios
* Track decisions, context, and activity on items
* Manage provider sync with Asana or Jira

## What you need first

* A workspace with at least one Protege that writes to the Work Hub
* Permission to access the Work Hub view

## Steps

### 1. Understand key concepts

#### Spaces and Portfolios

Spaces are top-level groupings that contain queues. A portfolio is a named group of related queues.

#### Collections (Queues)

A collection is a named queue of work items. Each queue has:

* A default priority
* Optional custom field definitions
* Optional completion rules that determine when an item is done
* Provider sync tracking (import, projection, drift reconciliation status)

#### Items

A work item has standard fields: title, description, status, priority, assignee, and requester. Items can also carry custom field values, source attachments (with preview states), source links to external resources, and references to the Protege runs that created or modified them.

#### Decisions

A decision is an approval or recommendation attached to an item. Proteges can request decisions when they encounter something that needs human judgment. Each decision has a type, status, recommendation, and rationale.

#### Context Records

Context records are notes, attachments, and links that provide background for items. They help Proteges make better decisions by giving them access to relevant reference material.

#### Comments

Comments on items can be:

* **Local only**: Created and managed entirely in Hookshot
* **Provider imported**: Synced from an external provider (Asana, Jira)
* **Provider projected**: Written in Hookshot and pushed to the external provider

### 2. Understand completion rules

Queues can use one of three completion modes:

| Rule                         | How an item is completed                                                |
| ---------------------------- | ----------------------------------------------------------------------- |
| **Explicit completion**      | A human manually changes the item status                                |
| **Provider task completion** | Automatically completed when the linked Asana or Jira task is completed |
| **Custom field option**      | Completed when a specific enum custom field is set to a specific option |

Custom field option completion supports a reopen behavior: either clear the field or set it to a different option.

### 3. Set up provider sync

The Work Hub supports bidirectional sync with external providers (Asana and Jira):

* **Import**: Pull records from the external provider into Work Hub queues
* **Projection**: Push changes from Work Hub back to the external provider (create tasks, update fields, post comments)
* **Event coverage**: Managed event listeners receive real-time updates from the provider
* **Drift reconciliation**: A periodic full sync (every 24 hours) catches changes that event listeners may have missed

{% hint style="info" %}
Provider sync status is tracked per queue. You can see import, projection, and drift reconciliation status on each queue's detail view.
{% endhint %}

### 4. Configure the write policy

The write policy controls whether Protege operations go through directly or require human approval before they are applied.

#### Policy sources

Four sources contribute to the final policy decision:

| Source               | Scope                                                               |
| -------------------- | ------------------------------------------------------------------- |
| **Work Hub default** | Global default for all queues (`autonomous` or `approval_required`) |
| **Queue policy**     | Per-queue override from the queue's SLA policy                      |
| **Protege policy**   | Per-Protege write policy from its access configuration              |
| **Sensitivity**      | Based on the operation type                                         |

If **any** source says `approval_required`, the result is `approval_required`.

#### Operations that always require approval

Some operations always require human review regardless of policy settings:

* Approval-sensitive work (operations that affect visible output)
* Decision approval (when a Protege requests a decision)
* Provider projection (writes that will push to an external provider like Asana or Jira)

#### Autonomous mode

In `autonomous` mode, the Protege's changes are applied immediately and appear in the work item right away. Use autonomous mode for low-risk operations in trusted workflows.

#### Approval required mode

In `approval_required` mode, the Protege's changes create a **Pending Write** that waits for a human to approve or reject it before it is applied. See [Pending Writes](/event-feed/pending-writes.md) for the full review workflow.

### 5. Configure Work Hub settings

Work Hub defaults are configured per team at **Settings → Work Hub**:

* **Write policy**: Default for all queues (autonomous or approval\_required)
* **Outbound default**: How outbound writes behave
* **Comment default**: Default comment sync mode
* **Product label**: Display label for the Work Hub instance

### 6. Navigate Work Hub views

The Work Hub offers several views:

| View          | Purpose                                                 |
| ------------- | ------------------------------------------------------- |
| **Inbox**     | Attention items, pending decisions, and recent activity |
| **Queues**    | Browse queues and portfolios with sync status           |
| **Work**      | Item list within a selected queue                       |
| **Decisions** | Decision list with pending write review                 |
| **Context**   | Context record browser with attachment preview          |

You can filter items using the multi-field filter bar. Active filters appear as removable chips.

## How to verify

* Queues show the expected items from connected providers
* Pending writes appear for approval when Proteges make changes under approval-required policy
* Approved writes are applied to items and projected to external providers where configured
* Drift reconciliation runs periodically and reports sync status per queue

## Common failures

* Enabling autonomous mode for a queue that handles sensitive external writes
* Approving a pending write without reviewing the before/after snapshots
* Importing from a provider without confirming the correct project or portfolio scope
* Ignoring drift reconciliation errors on queues that depend on provider sync
* Assuming a completed item in Work Hub means the provider task is also completed

## Next step

* [Pending Writes](/event-feed/pending-writes.md)
* [Audit](/event-feed/audit.md)
* [Event Feed](/event-feed.md)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://gitbook.tryprotege.com/event-feed/work-hub.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.