Git and Worktree Strategy

Git gives Agent Teams the strongest review path: narrow diffs, branch visibility, task-scoped changes, and safer parallel work.

Choose a strategy

Strategy	Use when	Tradeoff
Main worktree	Solo work, docs-only edits, or one teammate at a time	Simple, but parallel edits can collide
Feature branch	One team is working on one coherent change	Clean review target, but teammates still share files
Worktree isolation	Multiple OpenCode teammates may edit the same repo in parallel	Better isolation, but merge/review needs more discipline

Start simple. Add worktree isolation when parallel edits are likely, not because every task needs a separate checkout.

When to enable worktree isolation

Enable it for OpenCode teammates when:

• two or more teammates may edit the same repository at once
• a task may run formatters, code generators, or broad tests
• you want each teammate's branch and diff to stay separate
• the lead workspace is dirty and should not receive direct edits

Keep it off when:

• the task is read-only
• one teammate owns all edits
• the repo is not Git-tracked
• you need a runtime path that does not support this isolation mode

WARNING

Worktree isolation currently applies to OpenCode members and requires a Git-tracked project.

Branch hygiene

Before starting parallel work:

git status --short
git branch --show-current

Use a clean branch when possible. If the main worktree already has user changes, tell agents not to revert unrelated files and keep task scope narrow.

Recommended branch style:

agent/<team-or-task>/<short-purpose>

Examples:

agent/docs/mcp-guide
agent/review/task-log-filtering
agent/ui/code-review-polish

Review flow

For isolated worktrees, review the teammate's diff before merging or applying changes back to the main workspace.

1. Confirm the task result comment names changed scope and verification.
2. Inspect the task diff in the review UI.
3. Ask for changes on the task if the diff touches unrelated files.
4. Approve only after tests or manual checks match the task risk.
5. Merge or apply changes deliberately.

Do not auto-merge worktree output just because the task is complete. Completion means the agent believes the work is ready for review.

Conflict policy

Use this policy for parallel teams:

Situation	Action
Two teammates edit the same file	Pause one task or make one owner responsible for integration
Generated files changed broadly	Require a comment explaining the generator and command
Main worktree has unrelated changes	Preserve them and review only task-owned changes
Worktree branch diverges	Rebase or merge manually after review, not inside a vague agent task

Task prompt example

Implement the settings validation fix in your assigned worktree. Keep edits inside src/features/settings and focused tests. Do not touch provider auth or task storage. Post the test command and result before completing the task.

This prompt works because it names the allowed area, sensitive boundaries, and completion evidence.

Related guides

• Create a team
• Code review
• Team brief examples
• Runtime setup