git-worktree-task-variants

name

git-worktree-task-variants

description

Create multiple worktrees with the same implementation spec, then dispatch subagents to execute them in parallel and compare results. Use when the user says "task variants", "try variants", "run variants", "compare implementations", "best of n", "compare approaches", or "same spec, different models". Requires pi-subagents installed. Composes with git-worktree-task-dispatch: dispatch the variants to execute, then compare results.

Git Worktree Task Variants

You want to try the same implementation spec in multiple worktrees and compare results — different models, different approaches, or just running multiple implementations in parallel. This skill creates multiple persistent worktrees, writes the same spec to all of them, then asks whether to dispatch subagents or execute manually.

This skill is standalone. It does NOT require git-worktree-tasks-breakdown to have been run first. It handles its own planning and worktree creation.

Requires: pi-subagents extension for parallel dispatch. If not installed, tell the user: "Install pi-subagents to dispatch variants in parallel: pi install npm:pi-subagents"

---

How it works

1. Understand the task

First, figure out what the user wants to implement. If they point at a GitHub issue or describe a feature, explore the codebase to understand the scope. Don't proceed until you have a clear picture of the task.

If the user already provides a spec file, use it directly. Otherwise, do the research yourself — map the work, identify requirements, and draft a spec.

2. Decide on variants

Ask the user how many variants they want and what differentiates them:

Variant type	What goes in each	Example
Different models	Same spec, different LLM model	sonnet vs opus vs haiku
Different approaches	Same spec, different implementation strategy	REST vs GraphQL
Same model, run twice	Same spec, same model, multiple runs	Compare consistency

Minimum: 2 worktrees. One variant is not enough to compare.

If the user doesn't specify, suggest 2–3 sensible variants. Default to different models (e.g., sonnet + opus) since that's the most useful comparison.

3. Design branch names

For each variant, derive a branch name from the task + variant identifier:

variants/<task>-<variant>

Examples:

• variants/user-auth-sonnet
• variants/user-auth-opus
• variants/pricing-rest
• variants/pricing-graphql

Follow the same branch naming conventions in CONTEXT.md (short prefixes: feat/, fix/, review/, etc. are reserved for tasks-breakdown splits — use variants/ here to distinguish).

4. Create worktrees and write specs

For each variant, run scripts/worktree-manager.sh create <branch>:

bash scripts/worktree-manager.sh create variants/user-auth-sonnet
bash scripts/worktree-manager.sh create variants/user-auth-opus

Then write the same git-worktree-spec.md to each worktree root. The spec content (Goal, Requirements, Implementation Scope, Acceptance Criteria, Technical Constraints) stays identical across all variants — only the branch name differs.

Include the Completeness Rubric section (from references/completeness-rubric.md) at the bottom of each spec.

After all worktrees are created, verify:

git worktree list

Confirm each worktree has the spec file.

5. Ask what to do next

Present a summary of what was created:

=== Variants Created ===

| Variant | Branch | Worktree | Spec |
|---------|--------|----------|------|
| 1 | variants/user-auth-sonnet | .worktrees/variants/user-auth-sonnet | ✅ |
| 2 | variants/user-auth-opus | .worktrees/variants/user-auth-opus | ✅ |

Same spec written to all worktrees.

Then ask the user to choose:

Dispatch all variants in parallel (/skill:git-worktree-task-dispatch) — if pi-subagents is installed and the user wants agents to implement all worktrees at once. Each variant runs independently in its own worktree.

Execute manually (/git-exec-worktree-spec) — for one-at-a-time manual execution. The user can cd into each worktree and run the command themselves.

Next step options:

A. Dispatch in parallel
   /skill:git-worktree-task-dispatch
   → Runs all variants in parallel via subagents

B. Execute manually
   cd .worktrees/variants/user-auth-sonnet && pi
   /git-exec-worktree-spec
   → Work through one worktree at a time, manually

If the user picks A, pass --model <chosen-model> to use the same model across all, or let each worktree use its default. If the user wants to compare models, run WITHOUT --model so each worktree uses whatever model is configured.

---

Prompt template

For reusable invocations, use the prompt template at prompts/git-worktree-task-variants.md. It provides a structured format for specifying the task, number of variants, and evaluation criteria.

---

Integration with other skills

This skill is standalone — it does its own planning and worktree creation. It does NOT call git-worktree-tasks-breakdown.

It composes with:

• git-worktree-task-dispatch — dispatch the variants to execute in parallel and compare results
• git-exec-worktree-spec — manual per-worktree execution without subagents

Typical flow:

/skill:git-worktree-task-variants
    → Creates N worktrees with the same spec
    → Asks: dispatch or manual?

/skill:git-worktree-task-dispatch
    → Runs all variants in parallel
    → Compare results

---

Composing with git-worktree-task-dispatch

After variants worktrees are created, dispatch all of them in parallel:

/skill:git-worktree-task-dispatch

Or specify a model to use across all:

/skill:git-worktree-task-dispatch --model opus

After execution completes, compare the variants:

• Which covered more rubric items?
• Which handled edge cases better?
• Any patterns across models or approaches?

---

References

• Completeness Rubric: references/completeness-rubric.md
• Branch naming: references/branch-naming.md

Notes

• Same spec, different worktrees. All variants share identical git-worktree-spec.md content. The difference is in the implementation — different models may produce different code for the same requirements.
• Worktrees are persistent — they are NOT auto-cleaned after comparison. Decide what to do with results before removing them.
• variants/ prefix distinguishes these branches from git-worktree-tasks-breakdown splits (which use feat/, fix/, etc.).
• If you used worktree-manager.sh create, mise/direnv configs are already handled per the trust policy in git-worktree-tasks-breakdown.