| name | git-worktree-task-dispatch |
| description | Dispatch parallel subagents to implement git-worktree-spec.md files across persistent worktrees. Use when the user wants to execute all worktree specs in parallel, implement multiple branches at once, dispatch agents to worktrees, or batch-run feature specs. Also accepts --model to use a specific model for all agents (e.g. after running git-worktree-task-variants, use that winning model for all worktrees). Triggers on "implement all worktrees", "run all specs", "dispatch to worktrees", "parallelize implementation". |
Git Worktree Task Dispatch
You've created worktrees (via git-worktree-tasks-breakdown or git-worktree-task-variants) and now want to implement them all at once. This skill dispatches one subagent per persistent worktree, each working in its own .worktrees/<branch> directory, all running in parallel.
Related skills:
git-worktree-tasks-breakdown — splits work into branches with different specsgit-worktree-task-variants — creates variants with the same spec (dispatch to execute and compare)
How it works
1. Discover worktrees
Run the worktree manager to find all .worktrees/<branch> directories that have a spec:
bash scripts/worktree-manager.sh list
Filter for entries with [spec ✓]. These are the candidates for dispatch.
If no worktrees with specs are found, abort and tell the user to run /skill:git-worktree-tasks-breakdown first or write specs manually.
2. Parse specs for dependencies & conflicts
For each git-worktree-spec.md, read:
- Cross-branch Notes — look for merge-order instructions like "merge feat/auth before feat/pricing" or "depends on feat/auth"
- Implementation Scope — surface the checklist items so you can track progress
- Technical Constraints — any shared files agents must not touch unless they coordinate
Build a dependency DAG if cross-branch dependencies exist. Branches with no deps go first (wave 1). Dependent branches go in later waves.
3. Speculative merge check
For each branch, run a speculative merge against the default branch to detect conflicts before dispatching agents:
git merge --no-commit --no-ff <branch> 2>/dev/null || echo "CONFLICT: $branch"
git merge --abort 2>/dev/null || true
Track:
| Branch | Conflict? | Shared files touched? |
|---|
| feat/hero | No | — |
| feat/pricing | Yes — package.json | package.json, pnpm-lock.yaml |
| feat/auth | No | — |
If shared-file conflicts exist, warn the user with the exact files and ask:
"These worktrees will likely conflict when merged: feat/pricing modifies package.json and pnpm-lock.yaml. Proceed anyway?"
4. Dispatch strategy
| Scenario | Dispatch pattern |
|---|
| No dependencies, no conflicts | Single parallel wave — all worktrees at once |
| Dependency DAG exists | Staged waves — wave 1 (no deps) first, then wave 2, etc. |
| Shared-file conflicts detected | Warn, ask user confirmation, then proceed or skip conflicting worktrees |
| Mixed (deps + conflicts) | Staged waves + per-wave conflict warnings |
5. Launch parallel subagents
Use subagent in PARALLEL mode with per-task cwd pointing to each persistent worktree.
Important: Do NOT use worktree: true at the top level. Worktree isolation for this skill means "each agent works in a persistent git worktree", not "each agent gets a new ephemeral temp worktree". The persistent worktrees were already created by git-worktree-tasks-breakdown.
Per task:
{
"agent": "worker",
"cwd": ".worktrees/<branch-name>",
"model": "<optional-model>",
"task": "Read ./git-worktree-spec.md in this directory and follow the instructions in prompts/git-exec-worktree-spec.md. After completing each Implementation Scope item, mark it [x] in the spec file. Verify all Acceptance Criteria pass. Complete the Completeness Rubric walkthrough. Report your results.",
"acceptance": {
"criteria": [
{
"id": "spec-complete",
"must": "All Implementation Scope items in git-worktree-spec.md are checked [x]",
"severity": "required"
},
{
"id": "acceptance-pass",
"must": "All Acceptance Criteria pass (tests run, dev server validates, etc.)",
"severity": "required"
},
{
"id": "rubric-done",
"must": "Completeness Rubric section in git-worktree-spec.md is fully checked",
"severity": "required"
}
],
"verify": [
{
"id": "no-unchecked",
"command": "grep -c '^- \\[ \\]' git-worktree-spec.md || true",
"allowFailure": true
},
{
"id": "git-status",
"command": "git status --short",
"allowFailure": true
}
]
}
}
Model override: If the user passed --model <model-id> (e.g., from running variants), set that model on every task. Otherwise omit model to use the default worker.
6. Collect results
After all agents complete, present:
=== Dispatch Results ===
| Worktree | Branch | Status | Files Changed | Tests | Rubric | Warnings |
|----------|--------|--------|---------------|-------|--------|----------|
| .worktrees/feat/hero | feat/hero | ✅ Done | +42/-3 | 8/8 | ✅ | — |
| .worktrees/feat/pricing | feat/pricing | ✅ Done | +89/-12 | 12/12 | ✅ | package.json modified |
| .worktrees/feat/auth | feat/auth | ❌ Failed | — | — | — | Test timeout on auth flow |
Summary: 2/3 succeeded, 1 failed
Then offer next actions:
- Retry failed — dispatch just the failed worktree(s) again
- Review individually —
cd .worktrees/<branch> and inspect
- Merge —
git merge <branch> for the passing ones (warn about shared-file conflicts first)
- Clean up —
bash scripts/worktree-manager.sh cleanup --dry-run
Composing with git-worktree-task-variants
If you ran task variants on a spec and want to use the winning model for dispatch:
/skill:git-worktree-task-variants .worktrees/feat/auth/git-worktree-spec.md --models sonnet,opus
→ Winner: opus
/skill:git-worktree-task-dispatch --model opus
→ All agents use opus
Troubleshooting
| Problem | Fix |
|---|
| "No worktrees with specs found" | Run /skill:git-worktree-tasks-breakdown or write git-worktree-spec.md manually |
| "Agent failed in worktree X" | cd .worktrees/<branch> and run /git-exec-worktree-spec manually to see the error |
| "Merge conflict on shared file" | Resolve in each worktree first, or re-dispatch after the upstream worktree merges |
| "Cross-branch dependency not met" | Dispatch only the dependency first, then re-run dispatch for dependents |
Integration notes
- Relative paths (
scripts/worktree-manager.sh) resolve against the skill directory via Pi's baseDir injection
- The
--model parameter only accepts model IDs available in the user's pi config
- For staged waves, simply run multiple
subagent PARALLEL calls sequentially — one per wave
