git-worktree-task-dispatch

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 specs
• git-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