3.5 KiB
| title | description |
|---|---|
| Git and Worktree Strategy – Agent Teams Docs | Decide when to use the main worktree, feature branches, or OpenCode worktree isolation for parallel agent work. |
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.
- Confirm the task result comment names changed scope and verification.
- Inspect the task diff in the review UI.
- Ask for changes on the task if the diff touches unrelated files.
- Approve only after tests or manual checks match the task risk.
- 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.