---
name: worker
description: Team worker protocol (ACK, mailbox, task lifecycle) for tmux-based Omagy teams.
---

# Worker

This skill is for an Antigravity CLI session started as an Omagy Team worker
inside a tmux pane. It is not a user-facing planning or review workflow.

## Identity

You MUST be running with `OMAGY_TEAM_WORKER` set:

`<team-name>/worker-<n>`

Example:

`alpha/worker-2`

Parse it into `team_name` and `worker` before any task work.

## Source Of Truth

Use `omagy team api ... --json` for all team state reads and writes. Do not
directly edit `.omagy/state/team/**` JSON files.

Use these environment variables when present:

- `OMAGY_TEAM_WORKER`: canonical `<team>/<worker>` identity.
- `OMAGY_TEAM_STATE_ROOT`: canonical state root for this worker.
- `OMAGY_TEAM_LEADER_CWD`: leader workspace path.

If environment variables are missing, stop and report the missing value. Do not
guess a sibling team.

## Startup ACK

Before task work, send one deterministic ACK to the leader mailbox:

```bash
omagy team api send-message --input '{"team_name":"<teamName>","from_worker":"<workerName>","to_worker":"leader-fixed","body":"ACK: <workerName> initialized"}' --json
```

Then read your mailbox and inbox:

```bash
omagy team api mailbox-list --input '{"team_name":"<teamName>","worker":"<workerName>"}' --json
```

Your inbox is informational; the task lifecycle still goes through the API.

## Task Lifecycle

1. List tasks:

```bash
omagy team api list-tasks --input '{"team_name":"<teamName>"}' --json
```

2. Pick the first unblocked task assigned to your worker or matching your role.
3. Claim it before doing work:

```bash
omagy team api claim-task --input '{"team_name":"<teamName>","task_id":"<id>","worker":"<workerName>"}' --json
```

4. Do the work.
5. Transition with the returned claim token:

```bash
omagy team api transition-task-status --input '{"team_name":"<teamName>","task_id":"<id>","from":"in_progress","to":"completed","claim_token":"<token>","result":"PASS: <evidence>"}' --json
```

Use `to:"failed"` with an `error` field when the task cannot be completed.

Use `release-task-claim` only for rollback or requeue, not for successful
completion.

## Mailbox

Mailbox messages are durable state. A tmux nudge is only a wake-up signal.

After reading a mailbox message, mark it delivered:

```bash
omagy team api mailbox-mark-delivered --input '{"team_name":"<teamName>","worker":"<workerName>","message_id":"<messageId>"}' --json
```

Reply to the leader with short status messages when useful:

```bash
omagy team api send-message --input '{"team_name":"<teamName>","from_worker":"<workerName>","to_worker":"leader-fixed","body":"DONE: <summary>"}' --json
```

## Heartbeat

Record heartbeat evidence during long work:

```bash
omagy team api update-worker-heartbeat --input '{"team_name":"<teamName>","worker":"<workerName>","turn_count":1,"alive":true}' --json
```

## Shutdown

If the leader sends a shutdown request, finish any safe cleanup, acknowledge via
the API, then exit the worker session:

```bash
omagy team api write-shutdown-ack --input '{"team_name":"<teamName>","worker":"<workerName>","reason":"worker drained"}' --json
```