docs / guides / track progress with initiatives

Track progress with initiatives.

Initiatives are named clusters of decisions with a live progress rollup. Progress derives from merged work, not from status updates anyone typed.

The one convention

When a pull request delivers a decision's work, cite the decision id in the PR body:

# in the PR body, not the commit message implements decision_ab12cd34ef56 # or name the criteria this PR delivered, repeating the id implements decision_ab12cd34ef56#c1 decision_ab12cd34ef56#c2

Cite the id in full. A shortened prefix does not resolve: the first few characters are not unique enough to attach evidence or check work off, so a truncated id reads as ordinary prose and the PR attaches to nothing. Agents that went through setup follow this convention on their own.

The bare line claims the whole decision, so a pull request that delivers only some of its criteria names each one and repeats the id. A criterion number written apart from an id claims nothing, because there is no way to tell which decision it belongs to.

The implements line is what claims delivery. A decision named anywhere else in the body, to record what governed the work, attaches the pull request as evidence and checks nothing off, so a pull request can cite the decisions it followed without holding their criteria open.

What happens on merge

With GitHub connected, the merged PR attaches to the decision as evidence and the matching definition-of-done criteria check off automatically. Linked work is what proves them, in one of two shapes: a criterion bound to pull requests is met when every PR linked to it is merged, and a criterion bound to issues is met when every issue linked to it is completed. A canceled issue does not count, because dropped is not delivered.

Some criteria are not the kind linked work can settle. A decision can carry acceptance criteria: a separate, receiver-side list naming the difference the work is meant to make for whoever it is for. balladeer accept signs those off. For a decision that carries no acceptance list, it signs the judgment criteria in the definition of done instead, the completion facts only a person can vouch for (a review happened, a design was approved).

How decisions join an initiative

Membership is many-to-many and never automatic. Creating an initiative can assemble candidate decisions by consequence to its goal: your agent runs that assembly by default, and on the command line you ask for it with balladeer initiative create --assemble, or later with balladeer initiative assemble <id>. Each candidate stays a suggestion until someone joins it. When an agent records a decision that clearly serves an open initiative, its save receipt keeps the decision as the headline and identifies the membership with both the readable name and stable id: initiative: "Queue migration" (initiative_a91c4e76b223). An unlinked decision says not linked to an initiative instead. The join test is dependency, not resemblance: does completing this decision advance the initiative? Opening an initiative stays a human call; agents never create one unprompted, and a wrong member is one removal away.

Nesting and closing an initiative

An initiative can roll up into one larger initiative. Set it when you create the initiative, or later with balladeer initiative parent <id> <parentId>; your agent has the same move, and --clear makes it a root again. An initiative has a single parent, cycles are refused, and nesting depth is capped. The parent's progress then includes its children's, deduped by decision, so a decision that serves two nested initiatives counts once. When an initiative is finished, balladeer initiative close archives it with its history.

Reading progress

Ask your agent to “give me a brief on X,” or run balladeer brief <initiative_id>, for the finished story: the intended state, where the work stands, the difference it is meant to make, what remains, and the right next step. The brief brings in supporting decisions outside the initiative when they are needed to explain why the work is shaped this way. Balladeer composes it when you ask and does not save the generated narrative.

An unconfirmed decision may still matter to the story, but confirmation is optional: it is review context, not work the brief tells you must complete. The brief addresses a next step to you only when the recorded evidence shows that built work is actually awaiting your sign-off. Its finished prose uses human names and claims rather than internal ids; exact addresses remain available in the explicit inspection read.

For the underlying progress evidence, run balladeer initiative show <initiative_id>. It reports the initiative's goal, owner, parent and children, direct and tree-wide decision counts, work state, definition-of-done and acceptance rollups, and any visibility gaps. Add --include-decisions to see its visible direct member decisions; decisions inside child initiatives stay collapsed. Your agent has the same explicit inspection tool as get_initiative.

balladeer roadmap remains the compact whole-picture read: open initiatives nested under their parents, with live progress derived from merged work. A criterion that linked work proves is recalculated every time you read it, so one whose delivering work has not arrived stays open and the progress line stays honest.

Verified from live product as of 4 Aug 2026.