Key Concepts
Notes, Beats, Beat Versions, Revisions, and Coda — the primitive concepts that give every part of the system an explicit name and role.
Key Concepts
Harmonic Composition is built from four primitive concepts. Together, they give every part of a delivery system a named, explicit role — from preserved context to durable capability to incremental progress to a defined destination.
Notes
Explicit, versioned, discoverable context that preserves the reasoning behind the work. Every Note has a type that classifies its role, making it easier to find, evaluate, and apply at any point in the delivery lifecycle.
Note types
Every Note carries a type that classifies its role in the system. The five types are:
Confirmed domain knowledge and background. Context Notes document what the team knows about the problem space, the facts and conditions that inform the work without being rules or choices in themselves.
Non-negotiable rules the system must satisfy. Constraint Notes record hard boundaries — technical, legal, organizational, or architectural — that shape what is possible regardless of preference.
Directional preferences, important but not absolute. Guidance Notes communicate how the team prefers to approach a problem without mandating a specific solution.
Recorded choices with rationale. Decision Notes document what was decided, why, and under what conditions, making the reasoning available to anyone who needs to understand or revisit a choice.
Content extracted from uploaded files. Document Notes bring external material — briefs, specifications, reference documents — into the system as structured, discoverable context.
Why Notes matter
The most significant source of waste in delivery is not incomplete work — it is lost context. When a decision is made, the conditions that produced it are rarely written down. As teams change and time passes, those conditions become invisible. Notes make them permanent and retrievable.
Notes are versioned: they accumulate as the system evolves, building a record of how understanding developed over time. They are discoverable: structured so anyone working in the system can find and read them, not only those who were present when they were written.
Notes in the delivery lifecycle
Notes established early in a project capture the reasoning behind the Coda — the constraints and assumptions that shaped the destination. As Beats move through quality evaluation and Revisions are delivered, Notes grow to capture the decisions made along the way.
Notes are not a substitute for real-time communication. They are the residue of communication — the part worth keeping because it will matter later.
Coda
The specific, resolved end-state the system converges toward. The Coda defines what done looks like for the current phase of delivery.
Why a Coda is necessary
Delivery without a defined destination is not delivery — it is indefinite work. The Coda resolves this by making the intended end-state explicit and agreed upon before significant work begins. It gives every subsequent decision a reference point: does this advance us toward the Coda, or away from it?
The Coda is specific: it describes a concrete state of the system, not an aspiration. And it is resolved: it has been evaluated, discussed, and accepted as the intended destination for the phase in progress.
The Coda is phase-scoped
A Coda applies to a phase, not to the entire life of a system. As phases progress and understanding deepens, the Coda may evolve — sharpened by what was learned, adjusted by new constraints, or replaced entirely when the destination changes. This is not failure; it is the expected behavior of a system that is honestly tracking reality.
The Coda and the Beats
The Coda shapes which Beats are relevant. A Beat that does not contribute to the current Coda does not belong in the current phase. Conversely, a Coda that cannot be supported by the Beats in the system signals that the Beats are incomplete or mis-scoped.
This relationship is part of quality evaluation: Beats are assessed not only against the quality dimensions but also against how well they collectively support the destination the Coda describes.
Establishing the Coda
The Coda is established early in the project, alongside the initial capture of Notes. It should reflect both the desired outcome and the constraints — technical, organizational, or otherwise — that shape what is achievable in the current phase.
Beats
Durable, outcome-oriented capabilities the system must possess. Beats persist as long as the capability is relevant — they are not one-time tasks, deliverables, or features.
What a Beat represents
A Beat describes what a system must be able to do, not what needs to be built by a certain date. This distinction is deliberate. Tasks and features close when they ship. A capability — the thing that makes a system actually useful — continues to matter long after the first version is delivered.
Beats are outcome-oriented: they define the end result the system must achieve, leaving room for how that result is reached to evolve over time through Revisions.
Beats are not tasks
A common source of fragility in delivery systems is conflating capability with work items. When capabilities are expressed as tickets, they get closed, archived, and forgotten — even though the underlying need remains. A Beat stays open and active as long as the system depends on what it describes.
Quality evaluation
Before a Beat can be considered ready, it must satisfy six quality dimensions: Distinctive, Harmonious, Substantial, Durable, Clear, and Strategically Aligned. This evaluation ensures the Beat is well-formed before Revisions begin.
Beat lifecycle
Beats are first identified and refined, evaluated against the quality dimensions, and advanced through Beat Versions and Revisions. A Beat remains in the system, actively shaped and refined, for as long as the capability it describes is relevant to the Coda.
A system with well-formed Beats has a stable vocabulary for capability. Team members at any point in the project can understand what the system must do and why, without reconstructing that understanding from scratch.
Beat Versions & Revisions
Beat Versions are the planning increment of a Beat, carrying its description, scope, and acceptance criteria for a planned slice of capability. Each Beat Version is delivered through one or more Revisions, which are the PR-level execution units. The two concepts coexist — Beat Versions did not replace Revisions.
Beat Versions and Beats
A Beat evolves through Beat Versions: the planning increment of a Beat. Each Beat Version carries the planning specification for a planned slice of the Beat's capability: its description, scope, and acceptance criteria. Beat Versions sit between a Beat and its Revisions: a Beat Version defines what is planned; one or more Revisions deliver it.
The chain: a Beat defines the durable capability → a Beat Version defines a planned increment of that capability → Revisions deliver the planned work. This separation keeps the long-lived definition of the capability distinct from the near-term planning of its delivery and the delivery itself.
Division of labor
A Beat Version is the plan — description, scope, acceptance criteria, rationale. It answers "what are we trying to accomplish?" Its quality is judged by plan_quality, and it moves through a lifecycle from idea to live.
A Revision is the delivery — one pull request. It carries almost no planning content of its own; it inherits meaning from the parent Beat Version so the plan doesn't get duplicated across PRs. Its quality is judged by build_quality, and its status is just binary: active or archived.
The two also track position differently. A Beat Version's state reflects conceptual progress (planning, building, ready_for_drop, in_staging…). A Revision's scm.state mirrors GitHub directly (draft, open, merged, closed). That split keeps the work's intent cleanly separated from the mechanics of the PR shipping it.
What makes a Revision
A Revision has two defining properties: it is shippable — meaning it represents a real, deployable increment of work — and it evolves a specific Beat, moving that capability closer to what the Coda requires. Each one should leave the Beat in a meaningfully better state: more capable, more reliable, or better aligned to the current understanding of the destination.
Continuity over pivoting
A key function of Revisions is to preserve continuity. When understanding changes — and it always does — the instinct is often to discard what exists and start fresh. Revisions offer a different path: acknowledge the change, refine the direction, and advance from where the system actually is rather than from a hypothetical clean slate. This is a recognition that resets are expensive, and that most changes in direction are better handled as evolution than replacement.
Revisions during delivery
Revisions are the primary unit of progress during delivery. As each Revision ships, the system moves incrementally toward the Coda. The Notes accumulated through earlier phases provide the context that keeps each Revision aligned with the intent established at the outset.
Orphan Revisions
Hotfixes and small operational fixes — bug fixes, dependency bumps, config tweaks — skip the Beat Version entirely. Create the Revision with beatVersionId omitted and an inline description. Orphan Revisions carry their own description since there is no Beat Version context to inherit, and no plan_quality or beat_quality guards apply.
Orphan Revisions are only valid when (a) the change is operational, not a new capability, and (b) there are no acceptance criteria worth grading.
A well-sequenced series of Revisions tells the story of how a capability developed — not just where it ended up.
How the elements relate
The Coda establishes where the system is headed. Beats define the durable capabilities needed to get there. Each Beat is planned as one or more Beat Versions, increments that carry the planning specification for a slice of the capability. Revisions deliver each Beat Version incrementally, one PR at a time. Notes carry the context that keeps all of these coherent — across handoffs, over time, and through changes in the people doing the work.
See how these elements come together in the Beat arc →Overview
A framework for continuous, coherent software delivery, built to preserve the context, capability, and intent that connect decisions to outcomes.
The Beat Arc
How a single Beat progresses from initial identification through quality evaluation to live delivery — and how to apply this to both new and existing work.