Skip to content
Skills Library
AI & agents · Automation

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.

Repository
rune ↗
Licence
MIT
Last repository change
16.05.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
3
Scripts
0
HTML comments
0
URLs in SKILL.md
3
Deprecation

No signals detected. Repository changed on 16.05.2026, without references to retired models or APIs.

Licence

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

  1. Overview
  2. Worktree Lifecycle
  3. Merge Strategy
  4. Conflict Resolution
  5. Wave-Based Execution
  6. Talisman Configuration
  7. State File Extensions
  8. Safety Notes
  9. Safety Net (Worktree Lifecycle Guard)
  10. Known Limitations (Upstream)
Original SKILL.md headings · 164 lines, 1,040 words
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

RepositoryScoreLicence
This page · vinhnxv/rune100MIT
iliaal/ai-skills100MIT
marcusrbrown/systematic100MIT
davidondrej/skills100MIT
bahayonghang/my-ai-cli-toolkit100MIT
yuri-xyz/skills100MIT
julianobarbosa/claude-code-skills100MIT
NikiforovAll/claude-code-rules100Apache-2.0
siva01c/claude-plugins100MIT

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.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.