name: git-worktree
description: "Worktree-isolated patch-and-apply workflow: agents work in git worktrees, generate patches, and an integrator applies them sequentially to the integration branch."
states:
working:
prompts:
enter: >
Set up an isolated git worktree for this task by running these commands:
git worktree add ../worktree-{{task_id}} -b worktree/{{task_id}}
cd ../worktree-{{task_id}}
Verify your setup:
git worktree list # Confirm worktree exists
pwd # Confirm you are in the worktree directory
git branch --show-current # Confirm branch is worktree/{{task_id}}
File coordination: call mark_file(file=[paths], task="{{task_id}}") for files you intend to modify.
Progress: call thinking(thought="what you're doing") periodically to broadcast status.
IMPORTANT RULES:
- Work EXCLUSIVELY in the worktree directory. Do NOT modify files in the main working tree.
- Do NOT push your branch to the remote or directly to the integration branch.
- All changes go through the patch workflow — you generate a patch, the integrator applies it.
exit: >
STOP — before transitioning out of working state, generate and submit a patch:
1. Stage and commit all changes in your worktree:
cd ../worktree-{{task_id}}
git add -A && git commit -m "{{task_id}}: {{task_title}}"
2. Generate the patch against the integration branch:
git format-patch $INTEGRATION --stdout > {{task_id}}.patch
3. Verify the patch is valid:
git apply --check {{task_id}}.patch
4. Attach the patch to the task:
attach(task="{{task_id}}", type="patch", content="<paste full patch content here>")
5. Satisfy the patch gate:
attach(task="{{task_id}}", type="gate/patch", content="Patch submitted for integration")
Do NOT push your branch directly. Do NOT merge into the integration branch yourself.
The integrator role handles patch application.
patching:
timed: true
exits: [working, completed, failed]
prompts:
enter: >
Your patch has been submitted. While in patching state, do the following:
1. Do NOT make further code changes or push any branches.
2. Monitor for conflict feedback — check periodically:
attachments(task="{{task_id}}")
If you see a note about conflicts, the integrator has moved you back to working.
3. Keep your worktree intact — do NOT delete it yet. You may need to rebase
if the integrator reports conflicts.
Wait for the integrator to apply your patch. You will be moved to:
- completed: if the patch applied cleanly
- working: if conflicts arose and you need to rebase and regenerate
- failed: if the patch is fundamentally incompatible
exit: >
You are leaving patching state. If returning to working (due to conflicts), rebase immediately:
cd ../worktree-{{task_id}}
git fetch origin
git rebase $INTEGRATION
If rebase has conflicts, resolve them:
git status # See conflicted files
# Edit each conflicted file
git add <resolved_files>
git rebase --continue
Then regenerate your patch and resubmit (follow the exit~working instructions).
completed:
prompts:
enter: >
Task is complete. Clean up your worktree NOW by running:
git worktree remove ../worktree-{{task_id}}
git branch -d worktree/{{task_id}}
If removal fails with "worktree is dirty", first commit or discard changes:
cd ../worktree-{{task_id}} && git checkout -- .
Then retry the removal.
If branch deletion fails with "not fully merged", use:
git branch -D worktree/{{task_id}}
gates:
status:completed:
- type: gate/patch
enforcement: warn
description: "Patches should be submitted for integration before completing. Attach gate/patch or use force=true for non-code tasks."
- type: gate/commit
enforcement: warn
description: "Commit all changes before marking task complete"
tag:worktree-isolated:
- type: gate/patch
enforcement: warn
description: "Worktree-isolated tasks should submit a patch before completing. Attach gate/patch with submission details."
roles:
integrator:
description: "Agent responsible for sequential patch application to the integration branch"
tags: [integrator, integration-lead]
max_claims: 1
role_prompts:
integrator:
claim_guidance: >
As integrator, you are responsible for applying patches to the integration branch
in dependency order. Monitor tasks entering the patching state. For each:
1. Retrieve the patch attachment from the task
2. Apply it to the integration branch (see patch_workflow prompt)
3. If the patch applies cleanly, move the task to completed
4. If conflicts arise, move the task back to working with conflict details
Keep the integration branch buildable at all times.
patch_workflow: >
Patch application sequence:
1. Ensure integration branch is up to date:
git checkout $INTEGRATION && git pull
2. Apply the patch in check mode first:
git apply --check {{task_id}}.patch
3. If check passes, apply for real:
git am {{task_id}}.patch
Or for plain diffs:
git apply {{task_id}}.patch && git commit -m "Integrate: {{task_id}} — {{task_title}}"
4. If check fails (conflict), record the conflict details:
git apply --reject {{task_id}}.patch 2>&1
Move the task back to working state with conflict info attached as a note.
5. Run integration tests after each patch to catch regressions early.
advisories:
worktree-setup:
phase: [explore, plan, implement]
role: [worker, lead]
content: |
# Git Worktree Setup
Task: **{{task_title}}** ({{task_id}})
## Creating a Worktree
```bash
# From the main repo directory
git worktree add ../worktree-{{task_id}} -b worktree/{{task_id}}
cd ../worktree-{{task_id}}
```
## Naming Conventions
- **Worktree directory**: `../worktree-{{task_id}}`
- **Branch name**: `worktree/{{task_id}}`
- **Patch file**: `{{task_id}}.patch`
## Important Rules
- Each agent works in its own worktree — never share worktrees between agents
- Do not modify files in the main working tree while using a worktree
- Keep your worktree branch up to date with the integration branch
- Use `git worktree list` to see all active worktrees
## Verifying Your Setup
```bash
git worktree list # Confirm worktree exists
pwd # Confirm you're in the worktree directory
git branch --show-current # Confirm you're on worktree/{{task_id}}
```
patch-generate:
phase: [implement, review, integrate]
role: [worker]
content: |
# Generating Patches from Your Worktree
Task: **{{task_title}}** ({{task_id}})
## Using git format-patch (preferred)
```bash
cd ../worktree-{{task_id}}
git add -A
git commit -m "{{task_id}}: {{task_title}}"
git format-patch $INTEGRATION --stdout > {{task_id}}.patch
```
`format-patch` preserves commit metadata (author, message) and is preferred
for clean integration via `git am`.
## Using git diff (alternative)
```bash
cd ../worktree-{{task_id}}
git diff $INTEGRATION > {{task_id}}.patch
```
Use `git diff` when you have uncommitted changes or need a simple diff without
commit metadata. The integrator will create the commit manually.
## Patch Quality Checklist
- [ ] All changes are staged and committed
- [ ] Patch applies cleanly against current $INTEGRATION: `git apply --check {{task_id}}.patch`
- [ ] No unrelated changes included (check with `git diff --stat $INTEGRATION`)
- [ ] Commit message is descriptive
## Submitting the Patch
```
attach(task="{{task_id}}", type="patch", content="<patch content>")
attach(task="{{task_id}}", type="gate/patch", content="Patch submitted for integration")
```
Then transition to patching state to await integration.
patch-apply:
role: [integrator, lead, coordinator]
content: |
# Applying Patches to the Integration Branch
## Sequential Application Order
Apply patches in dependency order. Check task dependencies with `list_tasks(ready=true)`
to identify which patches are unblocked and ready for integration.
## Step-by-Step Process
1. **Fetch the patch** from the task's attachments:
`attachments(task="<task_id>")`
2. **Save the patch** to a temporary file:
`<task_id>.patch`
3. **Dry-run check**:
```bash
git checkout $INTEGRATION
git pull
git apply --check <task_id>.patch
```
4. **Apply the patch**:
- For format-patch output: `git am <task_id>.patch`
- For plain diffs: `git apply <task_id>.patch && git commit -m "Integrate: <task_id>"`
5. **Run integration tests**:
Verify the build passes after each patch application.
6. **Update task status**:
- Clean apply → move task to completed
- Conflict → move task back to working with conflict details
## Batch Integration
When multiple patches are queued, apply them one at a time in order.
Do NOT attempt to merge multiple patches simultaneously — sequential
application makes conflict attribution straightforward.
patch-conflict:
role: [integrator, lead, coordinator, worker]
content: |
# Resolving Patch Conflicts
## For Integrators
When `git apply --check` fails:
1. **Identify the conflict scope**:
```bash
git apply --reject <task_id>.patch 2>&1
```
This creates `.rej` files showing failed hunks.
2. **Assess severity**:
- Minor (whitespace, import order): Resolve in-place and commit
- Moderate (overlapping edits): Move task back to working with details
- Major (structural conflict): Task needs full rebase
3. **Moving back to working**:
```
update(task="<task_id>", state="working")
attach(task="<task_id>", type="note", content="Patch conflict: <details of conflicting files and hunks>")
```
## For Workers (Rebasing After Conflict)
When your task is moved back to working due to conflicts:
1. **Update your worktree**:
```bash
cd ../worktree-<task_id>
git fetch origin
git rebase $INTEGRATION
```
2. **Resolve conflicts** during rebase:
```bash
# Edit conflicted files
git add <resolved_files>
git rebase --continue
```
3. **Regenerate and resubmit** your patch (see patch-generate advisory).
worktree-rebase:
phase: [implement]
role: [worker]
content: |
# Rebasing Your Worktree
Task: **{{task_title}}** ({{task_id}})
## When to Rebase
- Integration branch has advanced (other patches were applied)
- Your patch was rejected due to conflicts
- You want to minimize future conflicts proactively
## Rebase Process
```bash
cd ../worktree-{{task_id}}
git fetch origin
git rebase $INTEGRATION
```
## Handling Rebase Conflicts
```bash
# For each conflicted file:
git status # See which files conflict
# Edit the conflicted files to resolve
git add <resolved_files>
git rebase --continue
```
## After Rebasing
Regenerate your patch against the updated integration branch:
```bash
git format-patch $INTEGRATION --stdout > {{task_id}}.patch
```
Then resubmit: `attach(task="{{task_id}}", type="patch", content="<updated patch>")`
## Avoiding Conflicts
- Rebase frequently — don't let your worktree drift far from $INTEGRATION
- Keep changes focused and minimal to reduce overlap with other agents
- Coordinate with other agents working on the same files via task dependencies
worktree-cleanup:
phase: [review, deliver]
content: |
# Worktree Cleanup
## Removing a Single Worktree
```bash
# From the main repo directory (not from within the worktree)
git worktree remove ../worktree-<task_id>
git branch -d worktree/<task_id>
```
## Bulk Cleanup
```bash
# List all worktrees
git worktree list
# Prune stale worktree references (for worktrees whose directories were deleted)
git worktree prune
# Remove all task worktrees (be careful — only after all patches are integrated)
for dir in ../worktree-*; do
git worktree remove "$dir" 2>/dev/null
done
```
## Cleanup Checklist
- [ ] All patches from this worktree have been integrated
- [ ] No uncommitted changes in the worktree (`git status` is clean)
- [ ] Worktree branch has been merged or is no longer needed
- [ ] Worktree directory has been removed
- [ ] Local branch has been deleted
## Troubleshooting
- **"worktree is dirty"**: Commit or stash changes first, or use `--force`
- **"branch is not fully merged"**: Use `git branch -D` (capital D) if you're sure the patch was applied
- **Stale references**: Run `git worktree prune` to clean up
layered-worktree:
title: "Layered worktree strategy for multi-round coordination"
roles: [lead, coordinator, integrator]
content: |
For round N+1, create worktrees from the merged round N integration branch,
NOT from the original master/main. This eliminates duplicate-creation conflicts
where workers recreate code already produced in earlier rounds.
Example workflow:
# After merging Round 1 patches into integration branch:
git checkout integration
# Create Round 2 worktrees from integration (not master):
git worktree add ../worktree-{{task_id}} -b worktree/{{task_id}}
This ensures Round 2 workers see all Round 1 changes as their starting point.