From rune
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. <example> Context: Orchestrator activating worktree mode for /rune:strive user: "/rune:strive plans/feat-api-plan.md --worktree" assistant: "Worktree mode active. Workers will operate in isolated worktrees with direct commit." </example> <example> Context: Merge conflict during wave merge user: (internal — merge broker detects conflict) assistant: "Conflict detected in src/api.ts during Wave 1 merge. Escalating to user." </example>
npx claudepluginhub vinhnxv/rune --plugin runeThis skill is limited to using the following tools:
Git worktree mode gives each swarm worker its own isolated working copy via
Manages Git worktree lifecycle: creates isolated .claude/worktrees/ for parallel development or experiments, lists rune/* branches, cleans up stale or merged ones. Enforces max 3 active.
Creates isolated git worktrees for parallel development without disrupting the main workspace. Includes safety verification, .gitignore checks, and directory selection. Use for feature work or PR reviews.
Mandates invoking relevant skills via tools before any response in coding sessions. Covers access, priorities, and adaptations for Claude Code, Copilot CLI, Gemini CLI.
Share bugs, ideas, or general feedback.
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.
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 for the full 6-phase protocol and crash handling.
Worktree mode uses sequential merge with --no-ff for clear, revertable history.
| 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:
git revert -m1See worktree-merge.md for the complete merge broker algorithm, including:
BRANCH_REmergedBranches Set)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.
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 for the full wave grouping, dependency depth calculation, and execution flow.
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 sessionwork.worktree.max_workers_per_wave caps per-wave concurrencymin(max_workers, max_workers_per_wave)When worktree mode is active, the state file (tmp/.rune-work-{timestamp}.json)
includes additional fields:
{
// ... 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
}
.git objects)isolation: "worktree" support before proceedingWhen Phase 6 cleanup is not reached (crash, session end, agent idle), three safety nets ensure worktrees are eventually cleaned:
on-session-stop.sh Phase 4): Auto-cleans orphaned rune-work-* worktrees on session exit (capped at 3 for timeout budget)session-team-hygiene.sh): Detects orphaned worktrees, reports to user/rune:rest: Manual cleanup via standard mode or --healAll three use the shared scripts/lib/worktree-gc.sh library with:
config_dir isolation (cross-installation safety)jq dependency guard (fail-open if missing)| Issue | Impact | Workaround | Status |
|---|---|---|---|
| #28041 | Worktrees don't include .claude/ subdirs | setup-worktree.sh hook copies files | Active — hook mitigates |
| #27436 | Bare repos hang during worktree creation | setup-worktree.sh emits post-creation advisory | Active — advisory only |
| #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 |