Development graph
Issues, epics, specs, decisions, pull requests, releases and incidents as one graph, with the Git host still the record for code.
- Graph ID
- dev
- Sample data
- Meridian, a fictional collaborative-document product · 102 nodes, 239 edges
- Schema
- 22 node types · 92 edge types
- Stored queries
- 57 reads · 23 writes
- Updated
- Nov 17, 2026
[Ontology]
Drag types to rearrange · pinch or ⌘-scroll to zoom
All 22 types as a list
Epic4 in sample
Multi-issue scope of work. Owner and target release are edges.
slug · title · summary · status · businessValue · legacyRef · embedding · createdAt · createdBy · updatedAt · updatedBy
EpicContainsIssue → Issue · EpicTargetsComponent → Component · EpicTargetsRelease → Release · EpicBlocksEpic → Epic · EpicParentChildIssue → Issue · EpicOwnedBy → Actor · EpicTagged → Label
SpecFile5 in sample
Design doc / RFC. Mutable until approved; edits bump version.
slug · title · body · status · version · url · legacyRef · embedding · createdAt · createdBy · updatedAt · updatedBy
SpecSpecifies → Epic · SpecDescribes → Component · SpecSupersedes → SpecFile · SpecReferences → SpecFile · SpecAuthoredBy → Actor · SpecTagged → Label
Component8 in sample
Logical unit of code (service, module, top-level package). Owner is an edge; repo via RepoHasComponent.
slug · name · summary · criticality · createdAt · createdBy · updatedAt · updatedBy
ComponentHasSubcomponent → Component · ComponentDependsOn → Component · ComponentOwnedBy → Actor · ComponentTagged → Label
Repo2 in sample
VCS unit.
slug · name · defaultBranch · host · visibility · githubRef · createdAt · createdBy · updatedAt · updatedBy
RepoHasComponent → Component · RepoOwnedBy → Actor
PR7 in sample
Proposed change set. GitHub-authoritative. Branches are strings; commits via PrIncludesCommit.
slug · title · body · status · sourceBranch · targetBranch · invariantReviewDone · githubRef · legacyRef · embedding · createdAt · createdBy · updatedAt · updatedBy
PrClosesIssue → Issue · PrTouchesComponent → Component · PrIncludesCommit → Commit · PrBlocksPr → PR · PrWaitsForGate → Gate · PrWaitsForBlocker → ExternalBlocker · PrAuthoredBy → Actor · PrReviewedBy → Actor · PrTagged → Label · PrWidensGap → Gap · PrNarrowsGap → Gap
Release3 in sample
Versioned bundle. GitHub-authoritative. Coherence checklist + breaking changes as JSON strings.
slug · versionTag · status · releaseNotes · releaseNotesDoc · breakingChanges · artifactsChecklist · githubRef · createdAt · createdBy · updatedAt · updatedBy
ReleaseIncludesPr → PR · ReleaseInRepo → Repo · ReleaseSupersedes → Release
Incident1 in sample
Production issue. Commander is an edge.
slug · title · summary · status · severity · env · startedAt · mitigatedAt · resolvedAt · embedding · createdAt · createdBy · updatedAt · updatedBy
IncidentAffectsComponent → Component · IncidentCausedByPr → PR · IncidentCausedByDeployment → Deployment · IncidentCausedByCommit → Commit · IncidentCommandedBy → Actor · IncidentTagged → Label
Issue18 in sample
Work item. Replaces a tracker issue. Owner is an edge. Terminal states: done, canceled, duplicate.
slug · title · description · status · priority · issueType · acceptanceCriteria · designNotes · legacyRef · embedding · createdAt · createdBy · updatedAt · updatedBy
IssueTargetsComponent → Component · IssueTargetsRelease → Release · IssueImplementedBy → PR · IssueBlocksIssue → Issue · IssueParentChildIssue → Issue · IssueConditionalBlocksIssue → Issue · IssueWaitsForIssue → Issue · IssueWaitsForGate → Gate · IssueWaitsForBlocker → ExternalBlocker · IssueRelated → Issue · IssueDiscoveredFrom → Issue · IssueOwnedBy → Actor · IssueTagged → Label · IssueNarrowsGap → Gap
Actor7 in sample
Person or agent that creates, owns, reviews, or authors. agent slugs use 'agent:<name>'.
slug · name · actorKind · handle · email · createdAt · createdBy · updatedAt · updatedBy
Gate2 in sample
External waitable. kind is a closed enum (queryable); externalRef is the free-form handle.
slug · kind · status · externalRef · createdAt · createdBy · updatedAt · updatedBy
Label5 in sample
Cross-cutting tag.
slug · name · color · scope · createdAt · createdBy · updatedAt · updatedBy
Invariant4 in sample
Checkable property the system maintains. Violation = bug. Internal twin of Assumption.
slug · statement · status · guardRef · specRef · embedding · createdAt · createdBy · updatedAt · updatedBy
InvariantAboutComponent → Component · InvariantDescribedIn → SpecFile
Principle3 in sample
Prescriptive design rule reviewed against on every PR. Violation = rejected PR. polarity prescribes|forbids.
slug · statement · rationale · polarity · correctAlternative · status · specRef · embedding · createdAt · createdBy · updatedAt · updatedBy
PrExceptionToPrinciple → PR · PrincipleDescribedIn → SpecFile
Gap2 in sample
Tracked architectural debt — a desired Invariant not yet held. Can be widened by a PR.
slug · title · currentBehavior · targetBehavior · state · embedding · createdAt · createdBy · updatedAt · updatedBy
GapUnderminesInvariant → Invariant · GapDescribedIn → SpecFile
ExternalBlocker2 in sample
External issue/PR/release gating internal work (e.g. an upstream library fix). Durable cousin of Gate.
slug · system · upstreamUrl · status · pinnedVersion · shippedInVersion · residualWorkaround · createdAt · createdBy · updatedAt · updatedBy
Assumption2 in sample
Checkable belief about an EXTERNAL system's API/behavior, optionally guard-backed. External twin of Invariant.
slug · statement · status · guardRef · assumptionKind · embedding · createdAt · createdBy · updatedAt · updatedBy
AssumptionCoversBlocker → ExternalBlocker · AssumptionAboutComponent → Component
Capability4 in sample
Functional capability of the product, tagged by provenance. Different axis from Component; mapped M:N via CapabilityImplementedBy.
slug · name · summary · tier · status · embedding · createdAt · createdBy · updatedAt · updatedBy
CapabilityImplementedBy → Component · CapabilityTrackedBy → Epic · CapabilityDescribedIn → SpecFile
Decision6 in sample
Architecture Decision Record. Immutable once accepted; corrected via DecisionSupersedes.
slug · title · context · decision · consequences · status · legacyRef · embedding · createdAt · createdBy
DecisionAppliesToComponent → Component · DecisionAppliesToSpec → SpecFile · DecisionSupersedes → Decision · DecisionEmergedFromIssue → Issue · DecisionEmergedFromIncident → Incident · DecisionAuthoredBy → Actor · DecisionEstablishesInvariant → Invariant · DecisionEstablishesPrinciple → Principle · DecisionRelaxesInvariant → Invariant · DecisionRelaxesPrinciple → Principle
Commit5 in sample
Immutable VCS point, modeled only when referenced by a PR or incident (no full commit DAG).
slug · sha · message · githubRef · authoredAt · createdAt · createdBy
CommitAuthoredBy → Actor
Deployment4 in sample
Act of deploying a Release to an environment. env carries where; current-release-per-env is derived.
slug · env · outcome · startedAt · finishedAt · createdAt · createdBy
DeploymentOfRelease → Release · DeploymentTriggeredBy → Actor
Learning3 in sample
Captured lesson: incident analysis, retro takeaway, discovered gotcha, or design hindsight.
slug · title · body · learningKind · embedding · createdAt · createdBy
LearningAnalyzesIncident → Incident · LearningAboutComponent → Component · LearningAboutBlocker → ExternalBlocker · LearningAboutAssumption → Assumption · LearningAboutGap → Gap · LearningFromEpic → Epic · LearningReferencesDecision → Decision · LearningTagged → Label
Comment5 in sample
Thread message on an artifact. Never edited; corrections are new Comments. Target via CommentOn*.
slug · body · embedding · createdAt · createdBy
CommentOnIssue → Issue · CommentOnPr → PR · CommentOnSpec → SpecFile · CommentOnDecision → Decision · CommentOnIncident → Incident · CommentOnEpic → Epic · CommentPostedBy → Actor
[Questions it answers]
Each one is a stored query in the cookbook, written once and run by name from the CLI, the SDKs or an agent.
ready
What is ready to pick up?
Issues ready to pick up: backlog/todo, no incoming block, no outgoing wait
Show the query +Hide the query −
query ready()
@description("Issues ready to pick up: backlog/todo, no incoming block, no outgoing wait")
@instruction("Excludes started + terminal states and any incoming Blocks/ParentChild or outgoing WaitsFor*. The strict 'blocking source must itself be non-terminal' / 'gate must be pending' refinement is left to the caller; this returns the structural candidates.")
{
match {
$i: Issue
not { $_ issueBlocksIssue $i }
not { $_ issueParentChildIssue $i }
not { $_ epicParentChildIssue $i }
not { $i issueWaitsForIssue $_ }
not { $i issueWaitsForGate $_ }
not { $i issueWaitsForBlocker $_ }
$i.status != "in_progress"
$i.status != "needs_review"
$i.status != "hold"
$i.status != "done"
$i.status != "canceled"
$i.status != "duplicate"
}
return { $i.slug, $i.title, $i.priority, $i.issueType }
order { $i.priority }
}blocked_on_upstream
Which issues are waiting on a fix upstream?
Non-terminal issues gated on an external (upstream) blocker — the cross-system dependency view
Show the query +Hide the query −
query blocked_on_upstream()
@description("Non-terminal issues gated on an external (upstream) blocker — the cross-system dependency view")
{
match {
$i: Issue
$i issueWaitsForBlocker $blk
$i.status != "done"
$i.status != "canceled"
$i.status != "duplicate"
}
return { $i.slug, $i.title, $blk.slug, $blk.system, $blk.status, $blk.shippedInVersion, $blk.pinnedVersion, $blk.residualWorkaround }
}epic_spec
Which spec describes this epic?
The spec file(s) that specify an epic
Show the query +Hide the query −
query epic_spec($epic: String)
@description("The spec file(s) that specify an epic")
{
match {
$e: Epic { slug: $epic }
$s specSpecifies $e
}
return { $s.slug, $s.title, $s.status, $s.version }
}release_prs
Which pull requests shipped in this release?
PRs included in a release (the per-release changeset)
Show the query +Hide the query −
query release_prs($release: String)
@description("PRs included in a release (the per-release changeset)")
{
match {
$r: Release { slug: $release }
$r releaseIncludesPr $p
}
return { $p.slug, $p.title, $p.githubRef, $p.status }
}[80 stored queries]
Reads answer questions; writes are the typed mutations agents and people use to change the graph, each one commit.
queries/issues-dashboard.gq18 queries+
- open_epicsOpen epics (shaping or active), most-recently-updated first
- epic_issue_countsIssue count by status within an epic (completion at a glance)
- epic_specThe spec file(s) that specify an epic
- epic_releaseRelease(s) an epic targets
- epic_ownerActor that owns an epic
- issue_detailFull issue detail incl. acceptance criteria + design notes
- issue_ownerActor that owns an issue
- issue_labelsLabels tagged on an issue
- issue_blockersIssues blocking this one via incoming IssueBlocksIssue, with status. This is only the hard issue-blocks-issue dimension — for parent/gate/upstream blocks see issue_parents, issue_parent_epic, issue_gates, issue_waits_on.
- issue_parentsParent issues of this one (incoming IssueParentChildIssue) — this issue is blocked when a parent is. The inverse of issue_children.
- issue_parent_epicParent epic gating this issue via EpicParentChildIssue (the blocking parent-child edge, distinct from EpicContainsIssue membership)
- issue_relatedIssues explicitly related to this one (IssueRelated)
- issue_childrenSub-issues of this one (IssueParentChildIssue)
- issue_waits_onExternal blockers this issue waits for (IssueWaitsForBlocker)
- issue_gatesGates this issue waits for (IssueWaitsForGate)
- issue_decisionsDecisions that emerged from this issue (DecisionEmergedFromIssue)
- issue_componentsComponents an issue targets (IssueTargetsComponent)
- issue_commentsComments on this issue, oldest first; createdBy is the author actor slug
queries/queries.gq62 queries+
- issue_lookupFetch an issue by slug
- epic_lookupFetch an epic by slug
- pr_lookupFetch a PR by slug
- readyIssues ready to pick up: backlog/todo, no incoming block, no outgoing wait
- blockedNon-terminal issues blocked by another issue (incoming IssueBlocksIssue). ready() also excludes parent/gate/wait/upstream blocks — see blocked_by_parent, blocked_by_epic, blocked_by_gate, blocked_by_wait, blocked_on_upstream for those dimensions.
- blocked_by_parentNon-terminal issues with a parent issue (incoming IssueParentChildIssue) — a child is blocked when its parent is
- blocked_by_epicNon-terminal issues gated by a parent epic (incoming EpicParentChildIssue — the blocking parent-child edge, distinct from EpicContainsIssue membership)
- blocked_by_gateNon-terminal issues waiting on a Gate (outgoing IssueWaitsForGate) — check the gate's status to see if it still blocks
- blocked_by_waitNon-terminal issues waiting on another issue (outgoing IssueWaitsForIssue) — a soft aggregation dependency, distinct from a hard IssueBlocksIssue
- blocked_on_upstreamNon-terminal issues gated on an external (upstream) blocker — the cross-system dependency view
- stale_candidatesActive (non-terminal) issues, oldest-updated first
- epic_issuesAll issues contained by an epic
- epic_open_issuesNon-terminal issues remaining in an epic (completion = 1 - open/total)
- release_prsPRs included in a release (the per-release changeset)
- issue_implementationsPRs that implement an issue
- prs_for_componentPRs that touch a component — component churn input
- issues_for_componentIssues targeting a component
- incident_root_causeMulti-hop: incident → causing PR → its commits
- incident_componentsComponents an incident affected — blast-radius first hop
- learnings_for_incidentLearnings that analyze an incident
- unheld_invariantsInvariants currently violated (incl. aspirational ones not yet held)
- gaps_undermining_invariantsOpen gaps and the invariants they fall short of
- assumptionsAll assumptions with their guard reference and status
- assumptions_for_blockerSurface-guard assumptions covering an external blocker (failing guard ⇒ blocker moved)
- capabilities_by_tierCapabilities of a given provenance tier (owned/inherited) and their implementing components
- decisions_for_componentAccepted decisions (ADRs) that apply to a component
- components_without_specComponents with no SpecFile describing them — documentation gap
- capabilities_without_componentCapabilities with no implementing component — planning gap
- search_issuesSemantic search over issues
- search_epicsSemantic search over epics
- search_specsSemantic search over spec/RFC docs
- search_decisionsSemantic search over ADRs / decisions
- search_learningsSemantic search over learnings (incident reviews, gotchas, hindsight)
- search_invariantsSemantic search over invariants
- search_principlesSemantic search over principles
- search_gapsSemantic search over architectural gaps
- search_capabilitiesSemantic search over product capabilities
- search_prsSemantic search over PRs
- search_incidentsSemantic search over incidents
- create_issuewriteCreate a work item. status: backlog|todo|in_progress|needs_review|hold|done|canceled|duplicate; issueType: bug|feature|task|chore|question|risk.
- create_epicwriteCreate an epic. status: shaping|active|done|abandoned.
- create_prwriteCreate a PR record (VCS-host-authoritative). status: draft|open|merged|closed; githubRef required, e.g. meridian#128.
- update_issue_statuswriteTransition an issue's status.
- set_issue_prioritywriteSet issue priority (0=none,1=urgent,2=high,3=medium,4=low).
- update_epic_statuswriteTransition an epic's status.
- update_pr_statuswriteTransition a PR's status (draft/open/merged/closed).
- resolve_incidentwriteUpdate an incident's status; stamps resolvedAt (use status=resolved).
- set_invariant_statuswriteFlip an invariant between holds/violated.
- update_gap_statewriteMove a gap through narrowing/widened/closed.
- mark_blocker_shippedwriteUpdate an external blocker (status: open|closed|shipped); record shippedInVersion.
- update_capability_statuswriteMove a capability through planned/shipped/deprecated.
- add_issue_to_epicwriteEpicContainsIssue: place an issue under an epic.
- link_issue_blocks_issuewriteIssueBlocksIssue: source blocks target (target has it incoming).
- link_pr_closes_issuewritePrClosesIssue: takes effect on merge.
- link_issue_implemented_by_prwriteIssueImplementedBy: a PR implements an issue.
- link_issue_targets_componentwriteIssueTargetsComponent: which component the issue touches.
- assign_issue_ownerwriteIssueOwnedBy: set the issue owner (ownership is an edge, not a field).
- add_comment_on_issuewriteAppend a comment to an issue thread (Comment is never edited).
- record_decisionwriteRecord an ADR (append-only). status: proposed|accepted|rejected|superseded.
- supersede_decisionwriteDecisionSupersedes: a new decision replaces an earlier one (create the new Decision first).
- record_deploymentwriteRecord a deployment (append-only). env: dev|staging|prod|preview; outcome: success|rolled_back|failed.
- add_learningwriteCapture a learning from an incident (append-only).
[Run it with your agent]
Paste this into a coding agent. It installs Omnigraph if it has to, creates the graph from this cookbook, loads the sample data and runs the queries above.
- Claude Code
- Codex
- Antigravity
Read https://www.omnigraph.dev/
[More use cases]
[Engineering]
Agent work queue
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.
3 node types · 8 edge types · 35 queries
[Company]
Company brain
A company's people, projects, claims, decisions and commitments, each tied to the exact words it rests on, shared by its people and agents.
8 node types · 18 edge types · 41 queries
[Hardware]
Hardware program
Requirements, budgets, interfaces and verification for a hardware program, with "verified" and "over budget" worked out from the evidence on every read.
15 node types · 28 edge types · 39 queries