git-worktree-tasks-breakdown

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":

1. 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)

2. Install deps — detect lockfile (pnpm-lock.yaml, package-lock.json, etc.) and run install in each worktree

3. 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

4. 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:

# Preview
bash scripts/worktree-manager.sh cleanup --dry-run

# Do it
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