> For the complete documentation index, see [llms.txt](https://docs.tryprotege.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.tryprotege.com/event-feed/work-hub.md).

# Work Hub

## What this is

The Work Hub is the Hookshot™ operations center for managing tasks, 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 tasks across projects and workstreams
* Track decisions, context, and activity on tasks
* 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

#### Workstreams and Imported Workstreams

Workstreams are named groups that organize projects within the Projects view. An imported workstream is a group of projects synced from an external provider such as Asana or Jira.

#### Projects

A project is a named set of tasks. Each project has:

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

#### Tasks

A task has standard fields: title, description, status, priority, assignee, and requester. Tasks 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 a task. Proteges can request decisions when they encounter something that needs human judgment. Each decision has a type, status, recommendation, and rationale.

#### Artifacts

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

#### Comments

Comments on tasks can be:

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

### 2. Understand completion rules

Projects can use one of three completion modes:

| Rule                         | How a task is completed                                                 |
| ---------------------------- | ----------------------------------------------------------------------- |
| **Explicit completion**      | A human manually changes the task 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.

#### Provider task completion behaviors

When a queue is linked to an external provider, the **Provider task completion** mode controls how completing or reopening an item syncs back to the provider.

**Asana behaviors** (set in queue settings under "Provider completion behavior"):

| Behavior           | What happens when an item is completed                             |
| ------------------ | ------------------------------------------------------------------ |
| **Completed flag** | Marks the Asana task as completed                                  |
| **Custom field**   | Sets a specific custom field option to mark completion             |
| **Both**           | Marks the Asana task as completed AND sets the custom field option |

When using custom field or both, you choose which enum field and which option represents "done." Reopen behavior can either clear the field value or set it to a different option.

**Jira behaviors** (set in queue settings under "Provider completion behavior"):

| Setting             | What it does                                                       |
| ------------------- | ------------------------------------------------------------------ |
| **Complete status** | The Jira status name to transition to when completing (e.g., Done) |
| **Reopen status**   | The Jira status name to transition to when reopening (e.g., To Do) |

#### Provider-native status display

By default, work item statuses are normalized to the local Work Hub status set (open, review, blocked, done, etc.). You can switch a queue to **provider-native statuses** to display the provider's own status names instead — for example, showing "In Progress" or "Ready for QA" from Asana, or "In Review" from Jira.

This setting is configured per queue under **Status display mode** in queue settings.

### 3. Set up provider sync

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

* **Import**: Pull records from the external provider into Work Hub projects
* **Outbound sync**: Push changes from Work Hub back to the external provider (create tasks, update fields, post comments). Asana supports outbound sync. Jira does not.
* **Event coverage**: Asana supports managed event listeners that receive real-time updates. Jira does not have managed event listeners — it relies on periodic polling instead.
* **Drift reconciliation**: A periodic full sync (every 24 hours) catches changes that real-time listeners or polling may have missed

{% hint style="info" %}
Provider sync status is tracked per project. You can see import, outbound sync, and drift reconciliation status on each project'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 projects (`autonomous` or `approval_required`) |
| **Project policy**   | Per-project override from the project'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 sync (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 task 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 projects (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. This is the default view when you open the Work Hub. |
| **Projects**  | Browse projects and workstreams with sync status                                                              |
| **Work**      | Task list within a selected project                                                                           |
| **Decisions** | Decision list with pending write review                                                                       |
| **Artifacts** | Artifact browser with attachment preview                                                                      |

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

## How to verify

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

## Common failures

* Enabling autonomous mode for a project 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 projects that depend on provider sync
* Assuming a completed task 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
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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, and the optional `goal` query parameter:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.