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 +
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 +
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 +
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 +
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.

Paste into
  • Claude Code
  • Codex
  • Antigravity

Read https://www.omnigraph.dev/onboarding.md and set up Omnigraph for me with the Development graph cookbook: https://github.com/ModernRelay/omnigraph-cookbooks/tree/main/dev-graph

[More use cases]