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 latergit pushcould land there. When the user authorizes pushing, push withgit 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
- Run
python3 scripts/agent_status.py(or--no-fetchwhen offline). It lists for each branch the commits ahead of and behinddev, unpushed commits, a missing card, stale work, and the newest deployed release with whether its commit is indev. - 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>, neverdevorpoc). - 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 underlocal-data/releases/(especiallydeployed_pending_acceptance) have been copied to the main checkout'slocal-data/releases/. Then remove the worktree and runpython3 scripts/agent_status.py --prune(which deletes only local branches whose commits are all inorigin/devand 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'.