# Hive.colony Progress Tracker

Claim tasks, record step progress, and verify SOP gates in the colony SQLite queue.

- Repository: https://github.com/aden-hive/hive (11131 stars)
- Category: Engineering
- License: Apache-2.0
- Last updated: 2026-10-26
- Runs scripts: no, instructions only

## Install

Claude Code: `npx skills add aden-hive/hive --skill hive.colony-progress-tracker -g -a claude-code -y`
Codex: `npx skills add aden-hive/hive --skill hive.colony-progress-tracker -g -a codex -y`
Cursor: `npx skills add aden-hive/hive --skill hive.colony-progress-tracker -g -a cursor -y`
Gemini CLI: `npx skills add aden-hive/hive --skill hive.colony-progress-tracker -g -a gemini-cli -y`

## Description

Claim tasks, record step progress, and verify SOP gates in the colony SQLite queue. Applies when your spawn message includes a db_path field.

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

## Operational Protocol: Colony Progress Tracker

**Applies when** your spawn message has `db_path:` and `colony_id:` fields. The DB is your durable working memory, tells you what's done, what to skip, which SOP gates you owe.

Access via `terminal_exec` running `sqlite3 "<db_path>" "..."`. Tables: `tasks` (queue), `steps` (per-task decomposition), `sop_checklist` (hard gates).

### Claim: assigned task (check this FIRST)

If your spawn message includes a `task_id:` field, the queen pre-assigned a specific row to you. Claim that row by id, **do not** use the generic next-pending pattern below:

```bash
sqlite3 "<db_path>" <<'SQL'
UPDATE tasks SET status='claimed', worker_id='<worker-id>',
  claim_token=lower(hex(randomblob(8))),
  claimed_at=datetime('now'), updated_at=datetime('now')
WHERE id='<task_id>' AND status='pending'
RETURNING id, goal, payload;
SQL
```

Empty output → another worker raced you or the row is already done. Stop and report.  Non-empty → that row is yours, proceed to "Load the plan".

### Claim: next pending (fallback when no task_id is assigned)

If your spawn message did NOT include `task_id:`, you are a generic fan-out worker racing on a shared queue. Use the generic next-pending claim:

```bash
sqlite3 "<db_path>" <<'SQL'
UPDATE tasks SET status='claimed', worker_id='<worker-id>',
  claim_token=lower(hex(randomblob(8))),
  claimed_at=datetime('now'), updated_at=datetime('now')
WHERE id=(SELECT id FROM tasks WHERE status='pending'
  ORDER BY priority DESC, seq, created_at LIMIT 1)
RETURNING id, goal, payload;
SQL
```

Empty output → queue drained, exit. Otherwise the returned `id` is yours. **Never SELECT-then-UPDATE**, races.

### Load the plan

```bash
sqlite3 "<db_path>" "SELECT seq, id, title, status FROM steps WHERE task_id='<task-id>' ORDER BY seq;"
sqlite3 "<db_path>" "SELECT key, description, required, done_at FROM sop_checklist WHERE task_id='<task-id>';"
```

The rest: https://github.com/aden-hive/hive/blob/HEAD/core/framework/skills/_default_skills/colony-progress-tracker/SKILL.md