# Agent work queue: an Omnigraph use case

A dependency-aware issue queue for coding agents, in the style of beads: file work, link what waits on what, claim what is ready, close it.

| | |
|---|---|
| Category | Engineering |
| Graph ID | beads |
| Sample data | Larkspur, a fictional note-taking app: 26 nodes, 22 edges |
| Schema | 3 node types, 8 edge types |
| Stored queries | 35 reads, 26 writes |
| Source | https://github.com/ModernRelay/omnigraph-cookbooks/tree/main/beads |

## Node types

### Issue

A unit of work (a bead). Identity is the slug, e.g. ob-k3x9qa.

Instruction for agents: Use the dependency edges, never status, to express ordering: an issue is ready when it is open, not deferred, and no open issue blocks it or any of its ancestors.

- `slug: String` (key)
- `title: String`
- `description: String?`
- `design: String?`
- `acceptance: String?`
- `notes: String?`
- `kind: enum(bug, feature, task, epic, chore, decision, spike, story, milestone)`
- `status: enum(open, in_progress, deferred, closed)`
- `priority: I32`
- `labels: [String]?`
- `assignee: String?`
- `created_by: String?`
- `created_at: DateTime`
- `updated_at: DateTime`
- `started_at: DateTime?`
- `closed_at: DateTime?`
- `close_reason: String?`
- `defer_until: DateTime?`
- `due_at: DateTime?`
- `lease_expires_at: DateTime?`
- `external_ref: String?`
- `metadata: String?`
- `embedding: Vector(1536)?`

### Comment

A comment on one issue.

- `slug: String` (key)
- `body: String`
- `author: String?`
- `created_at: DateTime`

### Memory

A durable project insight that `ob prime` gives every new agent session.

- `slug: String` (key)
- `body: String`
- `created_by: String?`
- `updated_at: DateTime`
- `embedding: Vector(1536)?`

## Edge types

- `Issue -[BlockedBy]-> Issue` The source cannot start until the target is closed.
- `Issue -[ChildOf]-> Issue` The source is part of the target (an epic or parent task).
- `Issue -[RelatesTo]-> Issue` A loose see-also link; traverse it undirected.
- `Issue -[DiscoveredFrom]-> Issue` The source was found while working on the target.
- `Issue -[Duplicates]-> Issue` The source duplicates the target, which stays canonical.
- `Issue -[Supersedes]-> Issue` The source replaces the target.
- `Comment -[CommentOn]-> Issue`
- `Memory -[MemoryAbout]-> Issue` The memory concerns this issue.

Full schema: https://github.com/ModernRelay/omnigraph-cookbooks/blob/main/beads/schema.pg

## Questions it answers

### What can an agent claim now?

Claimable work, highest priority first: open, not deferred, and no open blocker on the issue or any ancestor.

```graphql
// Readiness is derived, never stored, with beads' rules: an issue is ready
// when it is open, not deferred into the future, no open issue blocks it, and
// no ancestor passes a block down. An ancestor passes one down when it is not
// closed, no closed issue sits between it and the issue, and at least one of
// its open blockers lies outside its own subtree (an epic waiting on its own
// child must not block that child). The parent and the deeper ancestors are
// separate blocks so that only the deeper ones pay for the closed-in-between
// check; the meaning is the single rule over childOf{1,8}.
query ready() @description("Claimable work, highest priority first: open, not deferred, and no open blocker on the issue or any ancestor.") {
    match {
        $i: Issue { status: "open" }
        $i.defer_until is null or $i.defer_until <= now()
        not { $i blockedBy $b  $b.status != "closed" }
        not { $i childOf $a  $a.status != "closed"  $a blockedBy $c  $c.status != "closed"
              not { $c childOf{1,8} $a } }
        not { $i childOf $p  $p.status != "closed"  $p childOf{1,7} $a  $a.status != "closed"
              $a blockedBy $c  $c.status != "closed"
              not { $c childOf{1,8} $a }
              not { $p childOf{1,7} $x  $x.status = "closed"  $x childOf{1,7} $a } }
    }
    return { $i.slug, $i.title, $i.kind, $i.priority, $i.assignee, $i.labels, $i.created_at }
    order { $i.priority asc, $i.created_at asc, $i.slug asc }
    limit 500
}
```

### What is blocked, and by what?

Unfinished issues with an open direct blocker, one row per blocker.

```graphql
query blocked() @description("Unfinished issues with an open direct blocker, one row per blocker.") {
    match {
        $i: Issue
        $i.status != "closed"
        $i blockedBy $b
        $b.status != "closed"
    }
    return { $i.slug, $i.title, $i.status, $i.priority, $b.slug as blocker, $b.status as blocker_status }
    order { $i.priority asc, $i.slug asc, $b.slug asc }
    limit 10000
}
```

### Which blocks does an issue inherit from its parents?

Blocks an issue inherits from its ancestors.

```graphql
query ancestor_blockers($id: String) @description("Blocks an issue inherits from its ancestors.") {
    match {
        $i: Issue { slug: $id }
        $i childOf{1,8} $a
        $a.status != "closed"
        $a blockedBy $b
        $b.status != "closed"
        not { $b childOf{1,8} $a }
        not { $i childOf{1,8} $x  $x.status = "closed"  $x childOf{1,8} $a }
    }
    return { $a.slug as ancestor, $b.slug as blocker, $b.title, $b.status }
    order { $b.slug asc }
    limit 500
}
```

### What depends on this issue, directly or not?

What transitively waits on an issue, up to 32 links away.

```graphql
query downstream($id: String) @description("What transitively waits on an issue, up to 32 links away.") {
    match {
        $i: Issue { slug: $id }
        $d blockedBy{1,32} $i
    }
    return { $d.slug, $d.title, $d.status, $d.priority }
    order { $d.slug asc }
    limit 2000
}
```

## Stored queries

### queries/issues.gq

- `ready`: Claimable work, highest priority first: open, not deferred, and no open blocker on the issue or any ancestor.
- `ready_count`: How many issues are ready; `ready` itself returns at most 500.
- `unblocked_open_count`: Open issues with no open blocker on themselves or an ancestor; the rest of the open issues are blocked.
- `ready_labeled`: Ready work carrying one label.
- `ready_filtered`: Ready work of the given kinds and priorities, optionally with one label and an assignee (or none).
- `blocked`: Unfinished issues with an open direct blocker, one row per blocker.
- `blocked_by_ancestor`: Unfinished issues blocked because an ancestor passes a block down.
- `ancestor_blockers`: Blocks an issue inherits from its ancestors.
- `show`: One issue with every property except its embedding.
- `out_links`: Edges leaving an issue: what it depends on, its parent, and annotations.
- `in_links`: Edges arriving at an issue: what it blocks, its children, and annotations.
- `comments`: Comments on an issue, oldest first.
- `list`: Issues in the given statuses, highest priority first.
- `assigned`: Issues claimed by one actor that are still in progress.
- `expired_leases`: In-progress issues whose claim lease has run out.
- `children`: Direct children of an issue.
- `upstream`: What an issue transitively waits on, up to 32 links away.
- `downstream`: What transitively waits on an issue, up to 32 links away.
- `reaches`: Whether a BlockedBy path of at most 32 links leads from any of the given issues to another; adding the reverse edge would form a cycle.
- `waits_frontier`: Issues exactly 32 BlockedBy links beyond the given issues.
- `waited_frontier`: Issues exactly 32 BlockedBy links before the given issues.
- `search`: Full-text search over titles and descriptions.
- `similar`: Issues whose title is semantically closest to the text. Needs embeddings.
- `stats`: Issue counts by status.
- `memories`: Every memory, most recently updated first.
- `recall`: Memories ranked by full-text relevance.
- `recall_semantic`: Memories ranked by meaning. Needs embeddings.
- `memories_about`: Memories linked to one issue.
- `export_issues`: Issues after a slug, in slug order, 1,000 at a time.
- `links_from`: Every link leaving the given issues, for export.
- `open_blockers_of`: Open blockers of the given issues.
- `open_children_of`: Unfinished children of the given issues.
- `lineage`: An issue's ancestors, up to eight levels.
- `subtree`: An issue's descendants, up to eight levels, each with its parent.
- `waits_among`: Which of the given issues wait directly on any of the targets.

### queries/mutations.gq

- `claim` (write): Atomically claim an open issue for an actor. Affects 0 nodes when someone else holds it.
- `renew` (write): Extend the lease on an issue the actor holds.
- `release` (write): Give back an issue the actor holds; it becomes open and unassigned.
- `reclaim_expired` (write): Reopen every in-progress issue whose lease has run out.
- `close` (write): Close issues in one commit. Their dependents become ready.
- `reopen` (write): Reopen closed issues, unassigned, so anyone can claim them.
- `defer` (write): Put issues on ice, optionally until a time; a claim on them ends.
- `undefer` (write): Bring deferred issues back to open.
- `link_blocks` (write): The first issue cannot start until the second is closed.
- `link_parent` (write): Make the second issue the parent of the first.
- `link_related` (write)
- `link_discovered_from` (write)
- `link_duplicates` (write)
- `link_supersedes` (write)
- `unlink_blocks` (write)
- `unlink_parent` (write)
- `unlink_related` (write)
- `unlink_discovered_from` (write)
- `unlink_duplicates` (write)
- `unlink_supersedes` (write)
- `comment` (write): Add a comment to an issue.
- `remember` (write): Store or replace a memory under a key.
- `remember_about` (write): Store or replace a memory and link it to an issue.
- `forget` (write): Delete a memory.
- `edit` (write): Replace an issue's editable fields if it is unchanged since it was read.
- `edit_embedded` (write): As edit, also replacing the title embedding.

## Run it

```bash
git clone https://github.com/ModernRelay/omnigraph-cookbooks
cd omnigraph-cookbooks
export COOKBOOK=$PWD/beads
omnigraph cluster validate --config "$COOKBOOK"
omnigraph cluster apply --target "$COOKBOOK" --config "$COOKBOOK" --as act-admin --json
```

The full local setup (server, sample data, queries): https://github.com/ModernRelay/omnigraph-cookbooks#local-setup

Source: https://www.omnigraph.dev/use-cases/beads
