| name | git-worktree-tasks-breakdown |
| description | Use when the user wants to break a project into independent parallel workstreams. Analyzes the repo, proposes a split plan with branches and specs, and creates persistent worktrees with the bundled script. Triggers on "break this down", "tasks breakdown", "split this work", "parallelize", "work on X and Y in parallel", or when they want to plan multiple features or branches. |
Git Worktree Tasks Breakdown
When someone says "I need to work on X, Y, and Z in parallel" or "I want to split this feature into independent tracks," this skill breaks down the work into a concrete plan — every branch, every spec — and creates the persistent worktrees.
It bundles scripts/worktree-manager.sh which handles the fiddly bits git worktree add doesn't: copying .env files, gitignoring the worktrees directory, and trusting mise/direnv configs safely.
See also
git-worktree-task-variants — creates multiple worktrees with the same spec to compare approaches or models (standalone, not a dependency)
When to use this vs git-worktree-task-variants
| git-worktree-tasks-breakdown | git-worktree-task-variants |
|---|
| Specs | Different specs per worktree | Same spec in all worktrees |
| Branches | feat/, fix/, etc. | variants/ |
| Purpose | Implement different features/tasks in parallel | Compare implementations or models on the same task |
| Standalone? | Yes | Yes |
Use tasks-breakdown when each branch does something different (e.g., hero redesign, pricing page, auth flow). Use task-variants when all branches implement the same thing for comparison (e.g., sonnet vs opus on the same auth spec).
How it works
1. Understand the ask
First, figure out what actually needs splitting. If the user points at a GitHub issue or describes a feature, explore the codebase to map the work. Don't propose a split until you know the terrain.
2. Propose a concrete plan
Design the entire split upfront — every branch, every spec — so the user can approve the whole thing at once.
Branch naming: Follow the convention in CONTEXT.md (short prefixes: feat/, fix/, refactor/, optimize/, docs/, chore/, review/). Derive the name from the work — e.g., feat/user-dashboard, fix/email-validation, review/123. See references/branch-naming.md for examples.
Per-branch spec (git-worktree-spec.md in each worktree root):
- Goal — one line, what this branch delivers
- Requirements — context, constraints, links to issues
- Implementation Scope — checklist with actual file paths
- Acceptance Criteria — how to verify it's done
- Technical Constraints — conventions, interfaces, things not to touch
- Cross-branch Notes — merge order, shared dependencies
- Completeness Rubric — append the full checklist from
references/completeness-rubric.md as a section at the bottom of each spec. This is the implementer's guard against under-engineering — it forces them to confront error paths, empty states, rollback, observability, and integration before they call it done
Present the plan as a markdown block in chat. Don't write roadmap files to the repo. If you need persistence, dump to /tmp/git-worktree-tasks-breakdown.md.
3. Execute on approval
Once the user says "go":
-
Create worktrees — run scripts/worktree-manager.sh create <branch> [from-branch] for each. This:
- Creates
.worktrees/<branch> with the new branch
- Copies
.env* (skips .env.example) from the main repo
- Adds
.worktrees/ to .gitignore if missing
- Auto-trusts mise/direnv for trusted base branches (see below)
-
Install deps — detect lockfile (pnpm-lock.yaml, package-lock.json, etc.) and run install in each worktree
-
Write specs — drop the git-worktree-spec.md into each worktree root, fully populated. Include the Completeness Rubric section (from references/completeness-rubric.md) at the bottom of each spec
-
Verify — git worktree list and confirm everything looks right
5. Offer next steps
After worktrees are created and specs are written, you have two paths:
Worktrees created. You have two paths:
| Path | What to type | When to use |
|---|
| A. Manual | cd .worktrees/<branch> && pi per worktree, then /git-exec-worktree-spec | You want full control, one branch at a time |
| B. Parallel dispatch | /skill:git-worktree-task-dispatch | Execute all specs in parallel, move fast |
Note: If you want to compare the same spec across models, use /skill:git-worktree-task-variants separately — it creates its own worktrees with the same spec for comparison.
--- (mise / direnv)
worktree-manager.sh create tries to trust configs so you don't get blocked on interactive prompts. It's conservative:
| Branch type | Trust baseline | Auto direnv allow? |
|---|
main, develop, dev, trunk, staging, release/* | That branch | Yes |
| Everything else (features, fixes, reviews) | Default branch | No — prints manual command |
Modified configs are never auto-trusted. The script prints the exact command to run after you review the diff.
Manual trust for an existing worktree:
bash scripts/worktree-manager.sh trust .worktrees/<branch-name>
Troubleshooting
| Problem | Fix |
|---|
| "Worktree already exists" | cd .worktrees/<branch> to switch, or git worktree remove .worktrees/<branch> to nuke it |
| "Cannot remove: current worktree" | cd out of it first, then remove |
| "Trust was skipped" | Script prints the manual command. git diff <base-ref> -- .envrc, then run the printed command from the worktree |
| "Worktree not found" | git worktree list — it may have been removed or never created |
Cleanup
When branches are merged, clean up their worktrees:
bash scripts/worktree-manager.sh cleanup --dry-run
bash scripts/worktree-manager.sh cleanup
This finds branches merged into the default branch (git branch --merged <default>), skips protected ones (main, master, develop, dev, trunk, staging, release/*), and removes the matching .worktrees/<branch> directories.
Integration notes
- Relative paths (
scripts/worktree-manager.sh) resolve against the skill directory (parent of this SKILL.md). Pi injects baseDir so the LLM resolves them — no env vars needed.
- Default path is
.worktrees/<branch>, auto-gitignored.
- Standard git commands work:
git worktree list, git worktree remove, cd .worktrees/<branch>. No wrapper needed.
References
- Git Branch naming: references/branch-naming.md
- Completeness Rubric: references/completeness-rubric.md
