Issuegraph FAQ
Common questions about the Issuegraph specification. The spec is authoritative where this page summarises.
What is Issuegraph?
Issuegraph is an open specification (v0.3.0 draft, Apache-2.0, stewarded by Autonomy LLC) for machine-readable issue dependencies and work ordering. It defines optional YAML frontmatter fields written directly on the issues in your existing tracker, plus writing and reading rules that let a scheduler — or a fleet of autonomous coding agents — work out which issues are ready to start. Read the spec.
Which issue trackers does Issuegraph work with?
Any tracker that stores an issue body as text: GitHub Issues, Linear, Jira and others. There is no server, no new tool and no migration — the fields live in the issue body.
What fields does Issuegraph define?
Seven optional fields: blocked-by, decomposed-from, duplicate-of, serialize-with, together-with, priority and evidence. See §4 The format.
How do AI coding agents decide which issue to work on next with Issuegraph?
The reading rules compute a ready set (open, not a duplicate, every blocker closed, no actively-claimed member of its serialize group), then select by effective priority — importance flows backward along blocking edges, so a minor issue that blocks an urgent one becomes urgent — with newest-first as the default tiebreak.
Can several agents work in parallel without conflicting?
Yes. serialize-with marks issues that must not run at the same time, and together-with groups issues that must ship as a unit; the reading rules use these to derive safe parallelism.
Does Issuegraph track status, claims or who is working on what?
No. Issuegraph describes work, never execution: no claims, leases, in-progress states, retries or logs. Those belong to the system doing the work.
How do I write an Issuegraph block?
Add a YAML frontmatter block at the top of the issue body with an issuegraph: key, e.g. blocked-by: ["#231", "#234"]. Quote # references (it is the YAML comment character) and leave a blank line before the closing ---.
Is there a reference implementation?
Yes — TypeScript packages on npm under the @issuegraph scope: core, reader, writer, derive, cli, store and viewer. They are 0.x and unstable; pin exact versions. Try the live demo.
Is the specification stable?
Not yet. v0.3.0 is a draft for implementation; field names and semantics may change until 1.0.
Who uses Issuegraph?
Descant, an autonomous software-delivery pipeline, uses Issuegraph for graph parsing, ready-set and effective-priority selection, decomposition and grooming writers.
How does Issuegraph relate to MA2H?
They are separate open specs from the same steward. Issuegraph describes the order of work on issues; MA2H is a protocol for agent fleets to notify, ask and hand tasks to a human through one hub, such as OH HAI.
What license is Issuegraph under?
Apache-2.0, for both the specification and the reference implementation. It is stewarded by Autonomy LLC.