Orchestration

Epic & release flow

How a plan gets its own integration branch and how it is released.

Every plan owns a stable epic branch — its private integration line. Tasks fork from and merge into the epic; nothing touches the release base until the plan is released as one unit.

Epic branch

  • Named epic/<slugged-plan-name>-<rand6> and pinned on the plan (plans.branch) before the first task dispatches, so it is stable across re-plans.
  • task_base_branch = the epic (tasks fork/merge here). effective_base_branch = the release base (the eventual merge target).
Bootstrap → execute → release
  1. 1

    Activate plan

    Plan → active; epic branch pinned via Plan::ensureEpicBranch.

  2. 2

    Bootstrap epic

    purpose=bootstrap_epic

    A dedicated run creates the epic worktree, an empty commit and pushes it. Sets epic_bootstrapped_at.

  3. 3

    Tasks land on epic

    purpose=merge

    Each approved task branch is merged into the epic by a deterministic merge run.

  4. 4

    Release

    [RELEASE id]

    When every task is terminal, the lead merges epic → release base with --no-ff. Plan → completed.

  5. 5

    Cleanup

    purpose=release_cleanup

    A follow-up run deletes the epic and all task branches (local + origin) and removes worktrees.

  6. Loops back until the verdict is approved

Bootstrap and release runs carry recovery markers ([BOOTSTRAP id], [RELEASE id]) so the server can re-attach them if the agent run id changes mid-flight.