git-worktree
/git-worktree
Use when running /rune:strive with --worktree flag or when work.worktree.enabled is set in talisman. Use when a worker's direct commit fails due to parallel isolation conflicts, when a merge conflict is detected during wave merge (merge broker escalation), or when branches from multiple workers need sequential merging into the feature branch. Covers: worktree lifecycle, wave-based execution, merge strategy, conflict resolution patterns, direct commit vs patch generation. Keywords: worktree, isolation, wave, merge broker, branch merge, conflict, parallel isolation, --worktree, direct commit.
Assessment and security
- Files in this package
- 3
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 3
No signals detected. Repository changed on 16.05.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
Use when running /rune:strive with --worktree flag or when work.worktree.enabled is set in talisman. Use when a worker's direct commit fails due to parallel isolation conflicts, when a merge conflict is detected during wave merge (merge broker escalation), or when branches from multiple workers need sequential merging into the feature branch. Covers: worktree lifecycle, wave-based execution, merge strategy, conflict resolution patterns, direct commit vs patch generation. Keywords: worktree, isolation, wave, merge broker, branch merge, conflict, parallel isolation, --worktree, direct commit.
Original author description
Use when running /rune:strive with --worktree flag or when work.worktree.enabled is set in talisman. Use when a worker's direct commit fails due to parallel isolation conflicts, when a merge conflict is detected during wave merge (merge broker escalation), or when branches from multiple workers need sequential merging into the feature branch. Covers: worktree lifecycle, wave-based execution, merge strategy, conflict resolution patterns, direct commit vs patch generation. Keywords: worktree, isolation, wave, merge broker, branch merge, conflict, parallel isolation, --worktree, direct commit.
How it works
- Overview
- Worktree Lifecycle
- Merge Strategy
- Conflict Resolution
- Wave-Based Execution
- Talisman Configuration
- State File Extensions
- Safety Notes
- Safety Net (Worktree Lifecycle Guard)
- Known Limitations (Upstream)
SKILL.md preview
---
name: git-worktree
description: |
Use when running /rune:strive with --worktree flag or when
work.worktree.enabled is set in talisman. Use when a worker's direct commit
fails due to parallel isolation conflicts, when a merge conflict is detected
during wave merge (merge broker escalation), or when branches from multiple
workers need sequential merging into the feature branch.
Covers: worktree lifecycle, wave-based execution, merge strategy,
conflict resolution patterns, direct commit vs patch generation.
Keywords: worktree, isolation, wave, merge broker, branch merge, conflict,
parallel isolation, --worktree, direct commit.
user-invocable: false
disable-model-invocation: false # Intentional: model loads this skill when worktree mode detected
allowed-tools:
- Read
- Glob
- Grep
---
# Git Worktree — Isolation Mode for /rune:strive
## Overview
Git worktree mode gives each swarm worker its own isolated working copy via
`isolation: "worktree"` on the Agent tool. Workers commit directly in their
worktrees instead of generating patches. After each wave of workers completes,
the orchestrator merges worktree branches back into the feature branch.
**Two execution modes** coexist in `/rune:strive`:
| Mode | Flag | Worker Behavior | Commit Strategy |
|------|------|----------------|-----------------|
| **Patch** (default) | `--patch` or no flag | Shared working tree | Patch -> commit broker |
| **Worktree** | `--worktree` | `isolation: "worktree"` | Direct commit -> merge broker |
Talisman override: `work.worktree.enabled: true` makes worktree mode the default.
## Worktree Lifecycle
Each worker's worktree follows a 6-phase lifecycle: CREATE (SDK creates worktree + branch), WORK (isolated implementation), COMMIT (direct commit, one per task), SEAL (report completion), MERGE (orchestrator merges after wave), CLEANUP (remove worktree + branch). Includes crash recovery protocol.
See [worktree-lifecycle.md](references/worktree-lifecycle.md) for the full 6-phase protocol and crash handling.
## Merge Strategy
Worktree mode uses **sequential merge with `--no-ff`** for clear, revertable history.
### Why Sequential (not Octopus)
| Strategy | Pros | Cons |
|----------|------|------|
| Sequential `--no-ff` | Conflict isolation, partial progress, revertable | Slower for many branches |
| Octopus merge | Single commit | All-or-nothing, no conflict resolution |
| Rebase | Linear history | Rewrites SHAs, harder to audit |
| Cherry-pick | Selective | Loses branch context |
**Decision**: Sequential `--no-ff` (ADR 4) because:
- Know exactly which two branches conflict
- 3 of 5 can merge cleanly even if 2 conflict
- Each merge is individually revertable via `git revert -m1`
- Deterministic history (sorted by task ID)
### Merge Broker Algorithm
See [worktree-merge.md](../strive/references/worktree-merge.md) for the
complete merge broker algorithm, including:
- Branch validation against `BRANCH_RE`
- Deduplication guard (`mergedBranches` Set)
- Empty branch detection (skip no-change workers)
- Pre-wave checkpoint tags
- Conflict escalation flow
- Cleanup procedures
## Conflict Resolution
**Critical rule (C1)**: No auto-resolution. On ANY merge conflict, escalate to user.
```
Conflict detected in {file}
|
v
AskUserQuestion: How to resolve?
|
+-- "Accept theirs" -> git checkout --theirs {file} && git add {file}
+-- "Accept ours" -> git checkout --ours {file} && git add {file}
+-- "Manual resolve" -> pause pipeline, user edits, git add, continue
+-- "Abort merge" -> git merge --abort, mark NEEDS_MANUAL_MERGE
```
**Why no auto-resolve**: `git checkout --theirs` replaces the ENTIRE file with the
incoming version, discarding all "ours" changes. This is too destructive for automated use.
User must make an informed choice for each conflict.
## Wave-Based Execution
Tasks are grouped into waves by dependency depth. Wave 0 has no dependencies, Wave N depends only on Wave 0..N-1. Each wave runs workers in parallel, then merges all branches before proceeding. Includes DFS cycle detection and pre-wave checkpoint tags.
See [wave-execution.md](references/wave-execution.md) for the full wave grouping, dependency depth calculation, and execution flow.
## Talisman Configuration
```yaml
work:
worktree:
enabled: false # Default: patch mode
max_workers_per_wave: 3 # Max parallel workers per wave
merge_strategy: "sequential" # Only "sequential" supported
auto_cleanup: true # Remove worktrees after merge
conflict_resolution: "escalate" # "escalate" (ask user) | "abort"
sparse_paths: [] # empty = disabled; specify paths for cone-mode checkout
```
| Key | Type | Default | Description |
|-----|------|---------|-------------|
| `work.worktree.enabled` | boolean | `false` | Make worktree mode the default |
| `work.worktree.max_workers_per_wave` | number | `3` | Max parallel workers per wave |
| `work.worktree.merge_strategy` | string | `"sequential"` | Merge strategy (only sequential) |
| `work.worktree.auto_cleanup` | boolean | `true` | Auto-remove worktrees after merge |
| `work.worktree.conflict_resolution` | string | `"escalate"` | Conflict handling mode |
| `work.worktree.sparse_paths` | string[] | `[]` | Paths for cone-mode sparse checkout; empty = full checkout |
**Relationship to existing keys**:
- `work.max_workers` caps total workers across the session
- `work.worktree.max_workers_per_wave` caps per-wave concurrency
- Effective per-wave cap: `min(max_workers, max_workers_per_wave)`
## State File Extensions
When worktree mode is active, the state file (`tmp/.rune-work-{timestamp}.json`)
includes additional fields:
```javascript
{
// ... existing fields ...
worktree_mode: true, // Absent in patch mode (falsy)
waves: [[taskIds], [taskIds]], // Task IDs grouped by wave
current_wave: 0, // Currently executing wave index
merged_branches: [] // Branches successfully merged
}
```
## Safety Notes
- **Blast radius reduction**: A rogue worker only damages its own worktree (primary benefit)
- **Disk usage**: Each worktree creates a full working copy (shared `.git` objects)
- **Dependency blindness**: Workers cannot see other workers' uncommitted changes
- **SDK canary**: Phase 0 validates `isolation: "worktree"` support before proceeding
- **Experimental**: Worktree mode is marked experimental in initial release
## Safety Net (Worktree Lifecycle Guard)
When Phase 6 cleanup is not reached (crash, session end, agent idle), three safety nets
ensure worktrees are eventually cleaned:
1. **Stop hook** (`on-session-stop.sh` Phase 4): Auto-cleans orphaned `rune-work-*` worktrees on session exit (capped at 3 for timeout budget)
2. **SessionStart** (`session-team-hygiene.sh`): Detects orphaned worktrees, reports to user
3. **`/rune:rest`**: Manual cleanup via standard mode or `--heal`
All three use the shared `scripts/lib/worktree-gc.sh` library with:
- PID liveness checks (never cleans live sessions' worktrees)
- `config_dir` isolation (cross-installation safety)
- `jq` dependency guard (fail-open if missing)
- Path traversal + symlink guards
- Salvage patches for uncommitted work (rest mode only)
## Known Limitations (Upstream)
| Issue | Impact | Workaround | Status |
|-------|--------|------------|--------|
| [#28041](https://github.com/anthropics/claude-code/issues/28041) | Worktrees don't include `.claude/` subdirs | `setup-worktree.sh` hook copies files | Active — hook mitigates |
| [#27436](https://github.com/anthropics/claude-code/issues/27436) | Bare repos hang during worktree creation | `setup-worktree.sh` emits post-creation advisory | Active — advisory only |
| [#29256](https://github.com/anthropics/claude-code/issues/29256) | `/resume` may not work in submodule worktrees | `setup-worktree.sh` emits submodule advisory | Active — advisory only |
| Model degradation | Worktree agents may lose project context | `WORKTREE_CONTEXT.md` reinforcement (~10% effective) | Mitigated |
| Disk space | Large repos can exhaust disk on worktree create | `setup-worktree.sh` pre-flight 2x safety check | Mitigated |
| Submodule false positive | `worktree-resolve.sh` misdetects submodule `.git` files | Fixed — parses `.git` file gitdir path to distinguish `/.git/worktrees/` from `/.git/modules/` | Resolved |
## References
- [worktree-merge.md](../strive/references/worktree-merge.md) — Merge broker algorithm, conflict handling, cleanup
- [worker-prompts.md](../strive/references/worker-prompts.md) — Worker prompt templates (patch + worktree modes)
- [parse-plan.md](../strive/references/parse-plan.md) — Task extraction and dependency parsing
Files in this package (3)
- SKILL.md 9 KB
- references/wave-execution.md 2 KB
- references/worktree-lifecycle.md 2 KB
Versions
| Repository | Score | Licence |
|---|---|---|
| This page · vinhnxv/rune | 100 | MIT |
| iliaal/ai-skills | 100 | MIT |
| marcusrbrown/systematic | 100 | MIT |
| davidondrej/skills | 100 | MIT |
| bahayonghang/my-ai-cli-toolkit | 100 | MIT |
| yuri-xyz/skills | 100 | MIT |
| julianobarbosa/claude-code-skills | 100 | MIT |
| NikiforovAll/claude-code-rules | 100 | Apache-2.0 |
| siva01c/claude-plugins | 100 | MIT |
Database snapshot: 13.11.2026 · package version ee97f64bf6d8 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 100git-operations
Git command patterns, branching strategy, and safety protocols. TRIGGER when: managing branches, resolving merge conflicts, or running commit/merge/push operations. SKIP: worktree lifecycle and isolation recovery (use worktree-management); CI automation (use github-actions-template). - 90git
Commit, open a pull request, merge, or clean up branches under the git law in ~/.foxrun/config/git.md, and make a worktree only on a direct word. Merge always runs the law check first. Use for /git commit, /git pr, /git merge, /git clean, /git worktree, or when someone says commit this or merge it. - 100worktree-management
Scaffolding worktree lifecycle, diagnostics, and recovery. TRIGGER when: debugging worktree isolation, recovering a stuck worktree, or managing task isolation. SKIP: ordinary branch/commit/merge operations (use git-operations). - 100git-workflow
Git branching strategy, commit messages, PR workflow, conflict resolution. Use when setting up a branching strategy, writing commit messages, creating pull requests, or resolving merge conflicts. - 90worktree-merge
Integrate any number of feature branches from parallel worktrees through one safe integration branch, validating after each merge and running the project's full check suite before touching the main line. Use when parallel worktree development is done and the branches need to be… - 86git-workflow-standards
Use for branch hygiene, merge conflict resolution, and worktree cleanup.