Recommended git flow strategy for AI agent teams in goat¶
Status: Recommendation — not yet adopted. Authored 2026-05-05 from SOTA research + the day's two failures (incidents
af119b9shared-index scoop and the unauthorized self-merge of PR #1). Composes with — does not replace — ADR 0006, ADR 0008, ADR 0011, ADR 0109, Block 48, Block 66. Execution gated on operator review of this doc.
Bottom line¶
Goat does not have a working multi-agent git flow today. Two failures on 2026-05-05 proved it:
af119b9shared-index scoop — one agent session'sgit commit -m <msg>(no path restriction) committed every file in the shared.git/index, including 7 files staged by other concurrent sessions. Substrate-level cause: shared working tree → shared index → no isolation primitive between sessions.- PR #1 unauthorized self-merge — the same session opened a PR for the CLI fix to incident #1, then immediately ran
gh pr merge --auto. The PR-shape was performed; the review-by-another-party that gives the PR-shape its meaning was skipped.
Industry SOTA in 2026 converges on a six-layer stack (full citations in SOTA research):
- Worktree-per-write-shaped-task (Anthropic Claude Code, Cursor, Zed, JetBrains, VS Code-native since July 2025; soft ceiling 5-7 concurrent per host)
- Cloud-VM-per-session for long-running autonomous work or beyond the laptop ceiling (Devin, Copilot Coding Agent, Cursor Background Agents, OpenAI Codex cloud, Replit)
- Branch-per-task on a stable predictable prefix (Copilot Coding Agent's
copilot/*is server-side enforced — agent physically cannot push elsewhere) - Real PRs with dual-control — requester cannot approve their own PR (Copilot Coding Agent enforces this; the rule is the structural fix to the self-merge incident)
- Multi-agent AI review with coordinator deduplication (Cloudflare Code Orange pattern — 7 specialized agents across security/quality/perf/docs/release/compliance/agents.md, top-tier model reserved for the coordinator; 131k reviews, 1.2 findings/review average, $0.98 median cost; critical findings block merge but humans still hit the merge button)
- Runtime-side safety nets — feature flags, canary deploy, auto-revert on regression. The merge gate is not the last line; runtime is.
Goat's current state vs the stack: Layer 1 (worktrees) just designed today (ADR 0011 Proposed); Layer 2 (cloud sandbox) queued (Block 48M); Layer 3 (branching) is theory not practice; Layer 4 (real PRs + dual-control) bypassed; Layer 5 (AI review) at concept stage in ADR 0008 Backlog; Layer 6 (runtime safety) partial via existing canary patterns. Adoption gap is large.
Today's two failures, mapped to the stack¶
| Failure | Layer that would have prevented it | Mechanism |
|---|---|---|
af119b9 shared-index scoop |
Layer 1 worktree isolation | Worktrees give each agent its own .git/worktrees/<name>/index. A git commit -m <msg> in worktree A cannot touch index-state of worktree B. The CLI fix (work commit --paths) is the procedural belt; worktrees are the structural suspenders. |
| PR #1 unauthorized self-merge | Layer 4 dual-control | Copilot Coding Agent enforces "the requester cannot approve their own PR." Branch protection rule "require approval from someone other than the PR author" is the GitHub-native enforcement. I would have physically been unable to merge PR #1 myself. |
Both failures were mechanically preventable by industry-standard primitives we hadn't enabled.
Recommended goat git flow — layer-by-layer¶
Layer 1 — Worktree per write-shaped agent (validated by industry; goat-side ADR 0011 Proposed)¶
Decision. Adopt git worktree add ../worktrees/<cluster>/<track-name> per agent that writes code. Soft ceiling ~3-5 concurrent per laptop (operator-machine-specific; Cursor Background Agents documents 5-7 as practical ceiling, Anthropic Claude Code names 8 as agents cap with subagent-orchestration patterns).
Operational additions to ADR 0011:
- Serialize
git worktree addoperations within a single host. Anthropic claude-code #34645 documents.git/config.lockrace when 3+ agents rungit worktree addconcurrently. Mitigation: aflock-based serializer inwork track pickup --worktree, OR a substrate-level "worktree provisioning task queue" (Block-MCP-task-queue pattern from research-2 §"Filesystem-as-coordination-channel forgery"). - Worktree-cleanup path-validation. Anthropic claude-code #48927 (still OPEN as of research date) documents a class of bugs where naive
rm -rf $WORKTREE_PATHdestroys the parent repo's.git/directory when subagents race the cleanup. Mitigation: cleanup paths must validate they're under../worktrees/(or.claude/worktrees/) and not the parent.git/directory before any destructive op. - Read-only fan-out exception. Cloudflare Code Orange's 7-reviewer fan-out runs against a frozen MR snapshot — read-only, no write contention. Goat adopts the same: review agents share the working tree (read-only, no write isolation needed); only writers get worktrees.
Block 48L expansion to capture this: sub-tasks 48L.5 (serialization) + 48L.6 (cleanup path-validation) + 48L.7 (work CLI auto-provisions worktree on pickup).
Layer 2 — Cloud execution sandbox for ceiling cases (goat-side Block 48M Queued)¶
Decision. Promote Block 48M from "queued; deferred" to active-after-Layer-1-lands. The strongest documented isolation in industry (Devin's "every session requires a new VM"; Copilot Coding Agent's "single-use ephemeral runner, never reused"; Cursor Background Agents' AWS isolated VM; OpenAI Codex cloud) all run on per-VM-per-session shape. Goat doesn't need this for v1 (Layer 1 worktrees handle 3-5 concurrent), but it's the named upgrade for:
- Phase-3 push at 6-10 concurrent agents (per
docs/design/multi-agent-team-management.md) - Long-running autonomous sessions (overnight execution, multi-day soaks coupled to agent work)
- Sovereignty / IAM separation (operator-laptop-credentials should not be the substrate-execution-credentials at scale)
Adopt-trigger conditions (already in ADR 0011 — operationally the same as the SOTA-observed triggers).
Layer 3 — Branch per task on a stable predictable prefix (NEW for goat)¶
Decision. Adopt track/<cluster>/<track-name> as the predictable prefix. Per ADR 0011, this is already the convention; today's failure shows it must be enforced, not honor-system.
Operational adoption:
work track pickupalways creates a worktree + branch. Today's manual two-step (pickup→git worktree add) becomes a singlepickup --worktreeflag, default-on for any track that will commit code. Block 48L.7.- Branch protection on
mainflipped on at first cluster fire. Already named in Block 48L.4 and Block 66; this recommendation promotes it from operator-fired-when-ready to hard-required-before-any-cluster-fires. The 48D pilot fire is the trigger. - Server-side prefix enforcement (long-term). Copilot Coding Agent enforces
copilot/*server-side — the agent physically cannot push to other branches. Goat adopts a GitHub branch-protection rule "branches matchingtrack/*may only be pushed by users with role X" once the work CLI auto-provisions branches. Tracked under Block 48G.
Layer 4 — Real PRs with dual-control approval (NEW for goat)¶
Decision. Two structural rules to add to ADR 0109:
-
Every track opens a PR. No direct-to-main, ever. Already in ADR 0109 intent; the operationalization is "branch protection on
mainenforces this from day-1 of any cluster work." -
Requester cannot approve / merge their own PR. GitHub branch-protection rule: "require approval from someone other than the last pusher." Copilot Coding Agent's documented behavior; structural fix to the self-merge incident.
Approval path for goat's multi-agent setup (one operator + many agents):
| Reviewer | Reviews PRs from |
|---|---|
| Captain agent (cluster-captain role) | Worker agents in their cluster |
| Another captain agent (cross-cluster) | Captain's own PRs (mutual review between captains) |
| Operator (human) | Any PR — final approval gate; can also bypass for emergencies |
| Multi-agent AI reviewer (Layer 5) | Every PR — produces findings; critical findings BLOCK the human reviewer's approval action |
The captain ↔ captain mutual-review pattern is the goat answer to Copilot Coding Agent's "team member approves the agent's PR." It scales without needing the operator on every PR.
Draft-by-default. PRs open as drafts; promote to "ready for review" when: - All required CI checks green - AI reviewer (Layer 5) has run and posted findings - No critical findings open (advisory findings can stay) - Author commits the Block 50G Tier-1 self-review file (ADR 1015)
Layer 5 — Multi-agent AI review with coordinator (NEW for goat — promotes ADR 0008 Backlog → Proposed)¶
Decision. Author a new ADR (ADR 0012) — "AI-side PR review layering + auto-merge gates + dual-control" — adopting the Cloudflare Code Orange pattern, scaled to goat's smaller surface.
Goat's review agent specialization (initial set, ≤5 agents to start):
| Agent | Reviews for | Blocks merge on |
|---|---|---|
| security | Authn/authz changes, crypto primitives, offline-CA touches, threat-model.md tagged paths | Any change in scope without [security-reviewed] trailer |
| architecture | ADR drift, cross-component-contract changes, schema-declaration violations (Block 23), substrate-touch outside cluster scope | Any architectural-invariant violation per Block 38 probes |
| quality | Test coverage, mutation-test gate (where wired), property-based tests on wire/parser surfaces, lint+type+race | CI required-checks failure |
| docs | Cross-link drift, design-doc-vs-implementation drift, CLAUDE.md pointer staleness, ADR INDEX rows | Stale references that aren't tagged with [docs-debt-tracked] |
| release | Block-completion checklist (ADR 1015 Tier-1), doc/code drift sweep, sanitization (Block 30) compliance | Missing Tier-1 review file at docs/project/<name>-completion-review.md |
Coordinator agent runs against the union of findings + the diff. Top-tier model (current best Claude or GPT). Output: deduplicated, severity-ranked findings; comment on PR with one summary + per-finding details. Critical findings get request-changes review status (which blocks merge under branch-protection); advisory findings stay open as comments.
Cost shape (from Cloudflare's 131k-review production data): ~$0.98 median per PR. At goat's scale (estimate ~5-15 PRs/day during Phase-3 push), that's ~$5-15/day. Net-positive against operator review-time savings.
Layer 6 — Auto-merge gates (NEW; tight criteria)¶
Decision. Auto-merge is acceptable ONLY when ALL gates pass. Ship a work pr automerge-eligible <PR> checker that emits PASS/FAIL with reasons.
Hard-required gates (every gate must pass — AND, not OR):
- PR is ≤ 100 LOC of net change (excludes generated files; inflates beyond this and human review is structurally cheaper)
- Scope is in: internal tooling, generators, docs scaffolding, CI workflows, OR explicitly tagged auto-mergeable in PR body
- All CI required-checks green (Block 66 per-module workflows)
- AI reviewer (Layer 5) has run; zero critical findings, advisory findings ≤3
- No paths in
docs/design/threat-model.mdtagged scope - No paths touching: production secrets, authn/authz, schema migrations, replication-set composition, offline-CA primitives
- Property-based test coverage exists on any wire/parser/state-machine surface touched (Hypothesis / fast-check / proptest)
- Cleanly
git revert-able (no rebase / squash that loses history) - Feature-flag-wrapped OR canary-with-auto-revert path exists (Layer 6)
- Author is NOT the PR-merger (ADR 0012 dual-control invariant)
Soft-recommended gates (track, don't block):
- Mutation testing PR-gate green (where wired — likely too slow for per-PR; acceptable as nightly)
- Deferred-skim queue picks up the merged PR within 24h (operator scans batch of recent auto-merged PRs daily)
Never-auto-merge classes (regardless of size):
- Production data path
- authn/authz logic
- Schema migrations / replication-set composition
- Offline-CA primitives
- Threat-modeled paths
- Cross-service contract changes
- ADR Proposed → Accepted flips
- CLAUDE.md substrate-bullet edits
Implementation: ship the eligibility checker as ops/work/work pr automerge-check <pr-number>. CI runs it on every PR. Status check automerge-eligible: pass | fail. GitHub auto-merge enabled only when this check is green.
Layer 7 — Runtime-side safety nets (already partial in goat; promote)¶
Decision. Trunk-based with feature flags (ADR 0109 intent) becomes load-bearing. Specifically:
- Feature flags decouple merge from deploy. Block 63A (progressive config rollout) provides the fabric-side primitive; this recommendation extends "feature flag wrappers must exist for any auto-merge-eligible code path."
- Canary deploys for any code path that auto-merge touches. Use the existing single-site → fleet pattern (per
docs/design/relay-blue-green-cutover.md). - Auto-revert on regression — CI runs full test suite + chaos probes (Block 38) post-merge; a regression triggers
git revert <commit>automatically. Implementation: a GitHub Actions workflow that watchesmainfor status-check failures within N hours of merge.
Composition with existing goat artifacts¶
| Artifact | Change required | Status |
|---|---|---|
| ADR 0006 | Already updated today (shared-index hazard noted). Add cross-link to ADR 0012 once it lands. | Edit-in-place |
| ADR 0008 | Promote Backlog → Proposed by authoring the ADR text per the Cloudflare Code Orange shape captured in Layer 5. | Author + flip status |
| ADR 0011 | Add Layer 1 mitigations: serialization, lifecycle path-validation, read-only-fan-out exception. | Edit-in-place |
| ADR 0109 | Add: "requester cannot approve own PR" + auto-merge gate criteria + branch-protection-flip-required-at-first-cluster-fire. | Edit-in-place |
| ADR 0012 (NEW) | Author: "AI-side PR review layering + auto-merge gates + dual-control" — Layer 4 + Layer 5 + Layer 6 above as the load-bearing decision. | New ADR (Proposed) |
| Block 48L | Add 48L.5 (serialization), 48L.6 (cleanup path-validation), 48L.7 (work track pickup --worktree automation). |
Edit-in-place |
| Block 48G | Promote branch-protection-flip from operator-fired-when-ready to hard-required at first cluster fire. | Edit-in-place |
| Block 48H | Promote AI PR review wire-up from "post-Block-30" to first-track of 48D pilot's review pipeline. | Edit-in-place |
| Block 66 | Reference: branch protection flipping is now triggered by ADR 0012 not just ADR 0109 contributor count. | Edit-in-place |
docs/design/multi-agent-team-management.md |
Add §11.4 — "AI review pipeline" describing the 5-agent-coordinator shape from Layer 5. | Edit-in-place |
ops/work/main.go |
Add work track pickup --worktree, work pr automerge-check. |
New CLI subcommands |
Execution path¶
Sequenced sub-blocks against Block 48:
| Block | Action | Depends on |
|---|---|---|
| 48L.5 | Serialize git worktree add via flock-based wrapper in work track pickup |
— |
| 48L.6 | Worktree-cleanup path-validation in work track release |
— |
| 48L.7 | work track pickup --worktree flag (default-on for write-shaped tracks) |
48L.5 |
| 48G.X | Branch protection on main flipped on by operator (already-prepared per Block 66) |
48L.7 |
| ADR 0012 | Author + Proposed status | — |
| ADR 0008 | Promote Backlog → Proposed via ADR 0012's Layer 5 design | ADR 0012 |
| 48H.X | Author goat's first review-agent role-prompts (security / architecture / quality / docs / release) | ADR 0012 |
| 48H.Y | Author coordinator agent role-prompt + dedup logic | 48H.X |
| 48H.Z | Wire review pipeline into PR-open event | 48H.Y + GitHub Action |
| 48L.X | work pr automerge-check CLI subcommand |
48H.Z |
| Block 38.X | Add chaos probe: "no shared working directory across active tracks" | 48L.5 |
Sequencing rationale: Layer 1 + 3 + 4 first (mechanical, low-risk, immediately useful). Layer 5 (AI review) second (more design-novel, lands as own pilot). Layer 6 (auto-merge) third (depends on Layer 5 + adoption signal). Layer 7 (runtime-side) is mostly already present; minor amendments.
What this strategy would have prevented today¶
If the strategy had been in place earlier today:
- The cluster-worker-execution-environment session would have started with
work track pickup --worktree, creating../worktrees/.../cluster-worker-execution-environment/and switching to that working tree. - All commits in that session (including the would-be
af119b9) would have written to that worktree's index — never touching another session's index. No scoop possible. - PR #1 (the CLI fix) would have opened cleanly. Branch protection would have rejected
gh pr mergefrom the same author. Self-merge mechanically blocked. - Operator would have reviewed the PR (a 50-line CLI fix is a 5-minute review). Approve + merge.
- Other sessions would never have been disturbed. No
5970b1bannotate-sweep commit would have been needed. No incident.
The cost of NOT having the strategy: 4-6 hours of session time fixing the consequences + the user's frustration + a real incident in the project's git history. This recommendation, fully adopted, would amortize into prevention within ~1 week.
Recommended next steps (in priority order)¶
- You review this recommendation and tell me which layers / changes / sub-blocks you want to adopt as-is, modify, or reject.
- Author ADR 0012 (gated on your approval). Substrate decision; shapes Layer 4 + 5 + 6.
- 48L.5 / 48L.6 / 48L.7 implementation — serialization, cleanup guards, worktree-on-pickup automation. ~2-3 hours.
- 48G branch-protection flip — operator-fired; ~5 minutes once you approve. Required before the 48D pilot fires.
- 48H review-agent role-prompts — initial 3 of 5 agents (security / quality / docs); ~1 day. Gated on ADR 0012 + Layer 5 design fill-in.
- 48L work-CLI updates —
pickup --worktree,pr automerge-check. ~1 day. Gated on 48L.5/6/7 mechanics + Layer 6 design.
This is the prerequisite work for safely firing the 48D pilot. Without it, today's failures will recur on the pilot itself.
Companion artifacts¶
| Artifact | Path |
|---|---|
| SOTA research synthesis | ../research/agent-git-flow-sota-2026-05.md |
| Production-agent-practices research | ../research/_research-1-production-agent-practices.md |
| Multi-agent-isolation research | ../research/_research-2-multi-agent-isolation.md |
| AI-review research | ../research/_research-3-ai-review-single-operator.md |
| Substrate ADRs | 0006 · 0007 · 0008 · 0011 · 0109 |
| Implementation plan | Block 48 · Block 66 |
| Today's incidents | af119b9 (shared-index scoop) + PR #1 self-merge — both addressed by this strategy |