droboticflow/docs/agents/branch-workflow.md

3.9 KiB

Branch workflow for parallel agents

Several agents work on this repository at once. Every task branch must answer three questions without anyone reading its history: what it is for, what it was built on, and whether it has reached dev. Git answers the last two; the task card answers the first.

When to create a dedicated worktree

Choose isolation by parallel conflict risk and impact scope, not by line count:

  • Read-only Q&A, code audits, and diagnosis: stay in the current checkout; do not create a worktree or .scratch/<slug>/work.md.
  • Follow-up fixes and small adjustments within an already-authorized task or unified worktree (such as local-data/worktrees/recent-integration): continue in the existing worktree and update its task card scope if needed.
  • New independent tasks or changes that risk parallel conflict: create a dedicated worktree from origin/dev.

Starting an isolated task

git fetch origin
git worktree add --no-track -b <agent>/<slug> local-data/worktrees/<slug> origin/dev
  • <agent> is the tool's usual prefix (codex, claude, ...). <slug> is a short topic without a date, and is the same slug as .scratch/<slug>/.
  • Start from origin/dev. To build on an unmerged branch, the user must ask for it. Its PR then contains that branch's commits too, so say so in the PR description.
  • Keep --no-track: without it the new branch tracks the remote branch it started from, and a later git push could land there. When the user authorizes pushing, push with git push -u origin <agent>/<slug>.

Task card

The first commit on a new task branch adds .scratch/<slug>/work.md. Keep it short. Do not record status in it: scripts/agent_status.py derives status from git.

# <one-line title>

Goal: what the user asked for, in one line
Agent: tool and session that owns the branch
Base: origin/dev @ <short sha>   (or the unmerged branch the user chose, and why)
Scope: modules or files this task may change
Out of scope: related work deliberately left out
Risk: API, data, delivery-format or deployment impact; "display only" when none

Update Scope, Out of scope and Risk when the plan changes. The card merges into dev with the work and stays as the record of why the change was made.

Ending a task

  1. Run python3 scripts/agent_status.py (or --no-fetch when offline). It lists for each branch the commits ahead of and behind dev, unpushed commits, a missing card, stale work, and the newest deployed release with whether its commit is in dev.
  2. Do not push or open a PR without the user's explicit authorization. Report the branch's local state and tell the user when it is ready. The user may authorize pushing and creating a PR together in one instruction ("push and create PR") or authorize only one of them; approving only one never implicitly authorizes the other. When push is authorized, push only the authorized task branch (<agent>/<slug>, never dev or poc).
  3. Only clean up a worktree after verifying all four conditions: its commits are merged into origin/dev, the working tree has no uncommitted or untracked work to keep, no running dev service (Vite / Go API) occupies it, and any release records under local-data/releases/ (especially deployed_pending_acceptance) have been copied to the main checkout's local-data/releases/. Then remove the worktree and run python3 scripts/agent_status.py --prune (which deletes only local branches whose commits are all in origin/dev and that no worktree has checked out).

Release records

scripts/release.py writes its ledger under the checkout it runs from, so records are spread across worktrees. agent_status.py reads all of them. Do not delete a worktree that holds an unaccepted release record, unmerged recovery materials, or active services.

Tests: python3 -m unittest discover -s tests/agents -p 'test_*.py'.