Skip to main content

​
From Free-form Branches to Workstreams

Early Enagrams tracked a single “active branch” per workspace and nudged agents to pull when someone else committed. That was a stopgap. The current model is workstreams: a named unit of work mapped to a shared Git branch (ena/<slug>) that multiple agents and humans can join. Everything that used to be called “branch coordination” now runs through workstreams:
Old conceptWorkstream equivalent
sync({ branch }) sets active branchworkstream_start creates the workstream and branch, or workstream_join joins an existing one
branch_directive in syncsync returns the caller’s active_workstream with its branch, members, and reservations
pull_required flag after decideAuto-sync (enagrams watch) fetches and applies approved commits as they land
Commit signals via decidesync_commit records the actual commit and links it to the test-gate receipt

​
Why the Change

Free-form “active branch” tracking worked for two people editing a prototype. It broke for larger teams:
  • No notion of work scope. Two unrelated tasks ended up on the same “active branch” because no one explicitly started a new one.
  • Commits were advisory. pull_required was a hint; nothing verified the commit actually built or passed tests.
  • No membership. There was no way to say “I’m working on this with you.”
Workstreams fix all three: explicit scope (title + description), explicit membership (workstream_join/workstream_leave), and gated commits (test gate + sync_commit).

​
Auto-sync Replaces “Pull Required”

Run enagrams watch once. From then on:
  1. Teammate clears the test gate on workstream ena/auth-refactor.
  2. API emits a gate_approved event.
  3. Your watch process fetches the commit and fast-forwards your local ena/auth-refactor (if you’re on it).
No more “please pull” in Slack.

​
Passive Branch Detection

Hooks still report your current git branch --show-current and changed files as metadata. That lets the dashboard and sync tell other agents what you’re touching even when you haven’t joined a workstream explicitly — useful for quick hotfixes on main.

​
Best Practices

  • Start a workstream for anything multi-commit. Even solo work benefits from scope and gated commits.
  • Keep enagrams watch running. Auto-sync is the “zero ceremony” payoff.
  • Don’t rely on active_branch directives in new code. They still exist for backwards compatibility but workstreams are the source of truth.
See Workstreams for the full lifecycle and tools.