Key Concepts

Harmonic Composition in Practice

The concepts are clear in isolation. The hard part is applying them together. This page walks through a single realistic scenario — a product team building a staff scheduling feature — and shows exactly what each element of Harmonic Composition looks like when it is being used, not just described.

The scenario

Vantage is a B2B SaaS company that builds project management software for architecture firms. Their customers are project managers at firms with 10–50 staff. The current product does time tracking and project billing reasonably well. Scheduling is the gap: project managers still use spreadsheets to assign staff across active projects.

Three months ago the team started building a scheduling feature. They have a Jira board with 23 tickets. Some are closed. Some have descriptions, most don't. The product manager who defined the original scope left in month two. Two engineers are building from memory, a Figma file, and a Slack channel that nobody searches.

A new engineer joins on Monday. She asks: "What are we building toward?" The two existing engineers can each give a different answer. Neither matches the Figma file.

This is the problem Harmonic Composition addresses.

---

Establishing the Coda

The team's current "goal" is written at the top of their Notion page:

This is not a Coda. It is an aspiration. It does not say what done looks like, what phase it applies to, or what would change if the team successfully delivered it. Every decision made against this goal requires the decision-maker to first decide what "better" means.

The team spends two hours writing an actual Coda:

The difference is not just length. The resolved Coda is specific (a project manager at a defined firm size, a defined workflow), testable (scheduling is no longer a spreadsheet workflow; no confirmed commitment at risk), and phase-scoped (it applies to this phase, not the lifetime of the product). Every subsequent decision can be evaluated against it.

The new engineer can read this in two minutes and understand what the team is delivering.

---

Capturing Notes

Context that shapes the work gets lost. The two engineers both know that staff cannot be double-booked — it came up in a sales call eight months ago — but it was never written down. It is not in Jira. The new engineer would never know it existed. When she builds a scheduling mutation later this week, she will not know to add the guard.

The team captures four Notes from their first working session:

Each Note has a type that classifies its role. The Constraint is non-negotiable — it cannot be softened without a recorded decision. The Decision records what was decided and why, so the team does not revisit the same question six months from now. The Context gives any future team member the domain background that makes the decision legible. The Guidance sets a directional preference without mandating an implementation.

Notes are versioned and discoverable. When an agent is asked to propose a new feature six months from now, it can pull these Notes and reason about the scheduling domain without asking the team to reconstruct it from memory.

---

Defining Beats

The team's current Jira board has 23 tickets:

Each of these closes when it ships. Most have no description. The team has no way to look at this list and answer: "What is the system supposed to be able to do when this phase is complete?"

The team defines three Beats shaped by the Coda:

Notice what changed. "Build calendar view" was an implementation task for one aspect of Scheduling View — it closed when it shipped. The Beat does not close. Six months after the calendar is built, the capability of viewing and adjusting allocation is still relevant. New features will evolve it. The Beat stays open and accumulates Beat Versions as the capability advances.

The tickets do not disappear — they become Revisions under Beat Versions. But the stable reference for "what the system must be able to do" is now the Beat set, not a board of closing tickets.

---

Planning a Beat Version

Beats define what the system must be capable of. They do not define what gets built next. That is the role of Beat Versions.

The team takes the Scheduling View Beat and plans its first Beat Version:

The Beat Version is the plan. It answers "what are we trying to accomplish this increment?" with a description, scope, and binary-testable acceptance criteria. Notice the last acceptance criterion explicitly cites the Constraint Note — the plan is connected to the context that shaped it.

Under this Beat Version, the team creates one or more Revisions — the PR-level delivery units. Each Revision inherits context from the Beat Version, so the plan is not duplicated across pull requests. The chain is:

---

The result

By the end of this session, the Vantage team has replaced 23 closing tickets with a structured delivery system:

• A Coda that gives every decision a reference point. When a stakeholder asks "should we add calendar sync this quarter?" the team can check it against the phase destination and answer clearly.
• Four Notes that preserve the context behind the work. The double-booking constraint is now permanent and discoverable — the new engineer will find it before she writes her first mutation.
• Three Beats that persist as the stable vocabulary of the system's capabilities. Six months from now, anyone joining the team can understand what the system must do in under ten minutes.
• A Beat Version that gives the next sprint a precise target. The acceptance criteria are binary: either the grid renders or it does not; either the constraint is enforced or it is not.

The 23 Jira tickets still exist — they become Revisions, the pull requests that deliver each Beat Version increment. But the planning layer above them now holds the intent. When tickets close, the capability they served remains visible and active.