> ## Documentation Index
> Fetch the complete documentation index at: https://docs.enagrams.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Workstreams

> Scoped units of work mapped 1:1 to shared git branches

## The Idea

A workstream is a named feature in flight. Every workstream maps to one git branch, `ena/<slug>`. Every agent that joins the workstream checks out that branch locally and works on it together. When the workstream finishes, you squash-merge and move on.

This replaces the per-developer branch pattern (Alice on `alice/add-stripe`, Bob on `bob/add-stripe-v2`, both drifting) with a shared working branch that everyone coordinates on.

## Lifecycle

<Steps>
  <Step title="Start">
    Any agent calls [`workstream_start`](/mcp/workstream-start) with a title. The API creates the row and reserves `ena/<slug>`. Check the branch out locally.
  </Step>

  <Step title="Join">
    Teammates' agents call [`workstream_join`](/mcp/workstream-join) with the slug. Their sessions flip to coordinated mode; symbol-level reservations and negotiations become available.
  </Step>

  <Step title="Work">
    Everyone commits to the same branch. The [test gate](/concepts/test-gate) validates changes before they're fanned out to other machines via `enagrams watch`.
  </Step>

  <Step title="Complete">
    Any participant calls [`workstream_complete`](/mcp/workstream-complete) without `pr_url` to get a squash-merge plan, runs the printed `git` + `gh` commands, then calls again with the PR URL to finalize.
  </Step>
</Steps>

## Auto-detection

Any git branch matching the pattern `ena/<slug>` puts the session in coordinated mode automatically — you don't have to `workstream_join` explicitly if you already checked out the branch. The hook script detects the branch on `sessionStart` and wires up the current workstream.

## Visibility

* `team` (default) — appears in every teammate's `workstream_list` and `sync` responses
* `private` — only visible to participants; useful for experiments you don't want advertised

## When Not to Use One

Workstreams are overhead for:

* Single-file typo fixes
* README updates
* Solo spikes you plan to throw away

Use the plain file-reservation flow for those. Workstreams earn their keep when two or more agents will touch the same area.