Beads Integrator

Orchestrator role

This skill is typically invoked by

$beads-orchestrator

. Users normally start with the orchestrator, not this role.

Core rule

You are the only entity that merges to the base branch during an orchestration run.

Inputs

• List of task ids + branch names approved by reviewer
• Base branch (usually

  main

  or

  master

  )
  • If unclear, detect with:

    git symbolic-ref --short refs/remotes/origin/HEAD

• Store base name for reuse:

  if git symbolic-ref --short refs/remotes/origin/HEAD >/dev/null 2>&1; then
    BASE="$(git symbolic-ref --short refs/remotes/origin/HEAD | sed 's|^origin/||')"
  elif git show-ref --verify --quiet "refs/heads/main"; then
    BASE=main
  else
    BASE=master
  fi
  

• Remote name
  • Detect with:

    REMOTE="$(git remote | head -n 1)"
    if git remote get-url origin >/dev/null 2>&1; then REMOTE=origin; fi
    

• Task id (sanitized for branch/worktree)

  TASK_ID_SANITIZED="${TASK_ID//\//-}"
  TASK_ID_SANITIZED="${TASK_ID_SANITIZED//./-}"
  BRANCH="beads/$TASK_ID_SANITIZED"
  WORKTREE_PATH=".worktrees/$TASK_ID_SANITIZED"
  

Procedure (repeat per task branch)

1. Ensure base is clean and current:
   • If dirty: wait 60 seconds, then re-check.
   • If still dirty:
     • If only

       .beads/issues.jsonl

       changed: continue and commit your updates as usual.
     • Otherwise: stash to unblock:

       git stash push -u -m "beads-integrator-auto"
       

   • git checkout "$BASE"

   • git pull --rebase

     (if a remote is configured)
2. Update task branch with base:

   • git checkout "$BRANCH"

   • git rebase "$BASE"

     (or

     git merge "$BASE"

     if policy avoids rebasing)
3. Verify:
   • run the agreed verification commands
4. Merge:

   • git checkout "$BASE"

   • git merge --ff-only "$BRANCH"

     (or merge-commit policy)

   • git push "$REMOTE" "$BASE"

     (use detected

     $REMOTE

     , or skip if no remote)
5. Record in Beads:
   • merge commit SHA, method, verification performed, follow-ups if needed
6. Clean worktree:
   • remove

     $WORKTREE_PATH

     when safe

If conflicts occur

• Resolve conflicts in the task branch context.
• If conflict complexity suggests architectural ambiguity:
  • pause and request

    $beads-architect

    consult
  • or defer with follow-up tasks instead of brute forcing a risky merge

If merge breaks base branch (rollback procedure)

If verification fails after merging to base branch, act immediately:

1. Revert the merge commit:

   git revert -m 1 "$MERGE_SHA" --no-edit
   git push "$REMOTE" "$BASE"
   

   This creates a new commit that undoes the merge while preserving history.

2. Document in Beads:

   • Update the task with: "Merge reverted due to: $REASON"
   • Include the revert commit SHA
   • Change task status back to "needs work"

3. Notify orchestrator:

   • The task needs re-review after fixes
   • Consider whether the issue indicates a gap in verification steps

4. Create follow-up task (if needed):

   • If the failure reveals a deeper issue, create a new Beads task to address root cause
   • Link it as a blocker to the original task

Prevention: Always run full verification on the integrated branch before pushing. If CI is available, wait for CI to pass before considering the merge complete.