A spec for issue dependencies
Issuegraph defines seven optional fields you add to the top of an issue as YAML frontmatter. The fields record how issues depend on each other. Any tracker can store them, and any tool can read them to work out which issues are ready to start.
YAML frontmatter
---
issuegraph:
blocked-by: ["#231", "#234"]
decomposed-from: "#230"
serialize-with: "#232"
priority: 1
---
Fields
blocked-bylist of refsMust close before this issue can start.serialize-withrefNot worked at the same time. Either can go first.together-withrefWorked together with this issue as one unit.duplicate-ofrefThe original. Readers ignore the duplicate.decomposed-fromrefThe issue this was split from. No effect on order.priorityinteger, 0–3 · default 20 is most urgent.evidence"asserted" | "verified"Whether the writer checked the issue’s claims.ref is an issue ID as your tracker writes it: 231, "#231", ABC-231, or owner/repo#231. All fields are optional.
Reading the graph
Ready
An issue is ready when everything it’s blocked by is closed and nothing it’s serialized with is in progress.
Effective priority
An issue takes the highest priority of anything waiting on it, so a P3 that blocks a P0 is treated as P0.
Parallel work
Ready issues with no dependency path between them can be worked at the same time.
Build with issuegraph
Try the CLI with no install. This reads the block at the top of an issue body and prints what it declares:
printf -- '---\nissuegraph:\n blocked-by: ["#231"]\n priority: 1\n---\nShip the parser.\n' \ | npx -y @issuegraph/cli parse
npm install -g @issuegraph/clinpm install @issuegraph/readernpm install @issuegraph/writernpm install @issuegraph/derivenpm install @issuegraph/corenpm install @issuegraph/storenpm install @issuegraph/editorEvery package is TypeScript, Apache-2.0, and runs on Node 18 or later. None of them fetches anything or needs a credential.
Issuegraph describes the work, not how it gets done. Assignees, status, and progress stay in your tracker.