wt-parallel

Files (3)

• SKILL.md
• uncommitted-changes.md · questions/
• worktree-dir.md · questions/

SKILL.md (first lines)

# wt-parallel

Use this workflow for implementation tasks with independent chunks. If the task is missing, ask for it. If the work is tightly coupled or concurrent subagents are unavailable, explain why and offer serial execution instead.

Use plain Git throughout. Worktrunk is not required or automatically selected; its lifecycle hooks and merge defaults are outside this workflow.

## 1. Establish the target

Read the repository instructions and inspect:

```bash
git rev-parse --show-toplevel
git branch --show-current
git rev-parse HEAD
git status
git status --porcelain=v1 --untracked-files=all
git worktree list --porcelain
```

Record the absolute current worktree root as `target`, its checked-out branch as the integration branch, and its HEAD as `start-sha`. The target may itself be a linked worktree. Do not assume the default branch is the target.

Require an existing commit, a named branch, and no merge, rebase, cherry-pick, or revert in progress. Ask the user to resolve these conditions before proceeding. For uncommitted changes, follow [the dirty-worktree decision](./questions/uncommitted-changes.md).

Before creating branches, confirm permission for local task commits, merges into the named target branch, and removal of successfully integrated task worktrees and branches. Ask once if this was not explicitly authorized. This does not authorize committing pre-existing changes or pushing anything.

## 2. Plan independent chunks

Inspect the relevant code and test commands before splitting the task. Give each chunk a kebab-case name, scope, acceptance criteria, verification commands, and explicit dependencies. Keep changes to shared interfaces, dependency manifests, lockfiles, and generated outputs under one owner or serialize them.

Show the dependency graph, merge order, and concurrency limit. Use two workers by default, capped by available agent capacity and resources. A chunk is ready only when all its dependencies have been merged and verified on the target, not merely finished by a worker.

For example:

```text
contract -> api, client -> integration-tests
```

Here `api` and `client` may run together, and `integration-tests` waits for both. If no independent chunks remain, use serial execution rather than manufacture parallelism.

Keep a task ledger in the session with each chunk's dependencies, state, branch, absolute path, base SHA, final SHA, and test results. Use states `pending`, `running`, `verified`, `merged`, `blocked`. Do not put orchestration notes into the repository unless requested.

## 3. Choose worktree locations

Follow an explicit user path or repository convention first. Otherwise use `<target>/.worktrees` only if Git ignores it. Check a candidate child with `git -C "<target>" check-ignore -- ".worktrees/<run-id>/<chunk>"`, rather than searching for a literal line in `.gitignore`. Exit 0 confirms exclusion; exit 1 means it is not ignored. Investigate other errors. If no location is established, follow [the location decision](./questions/worktree-dir.md).

Resolve the chosen root to an absolute path and verify its parent and required permissions before creating it. Pick a unique run ID, such as a timestamp with a random suffix. Name branches `agent-local/<run-id>/<chunk>` and paths `<root>/<run-id>/<chunk>`.

Validate each branch with `git check-ref-format --branch "<branch>"`. Check for an existing branch with `git -C "<target>" show-ref --verify --quiet "refs/heads/<branch>"`; exit 0 means occupied, 1 means absent, and other errors need investigation. Inspect registered worktrees with `git worktree list --porcelain` and paths with the filesystem tools. All names and paths must be unused. On a collision, choose a fresh name; preserve existing worktrees, directories, and branches.

## 4. Run a batch

Select ready chunks up to the concurrency limit. Recheck that the target is clean, on the recorded branch, and at the expected HEAD. If someone changed it, pause integration and reconcile with the user rather than overwriting their work. Record the current target HEAD as `base-sha` for every chunk in this batch.

Replace placeholders with the recorded values; quote paths and use explicit working directories for every tool call. For each chunk:

```bash
git -C "<target>" worktree add -b "<branch>" "<path>" "<base-sha>"
git -C "<path>" rev-parse --show-toplevel
git -C "<path>" branch --show-current
git -C "<path>" rev-parse HEAD
```

Verify the path, branch, and base SHA before launching its worker. On creation failure, inspect what Git created and record leftovers; do not dispatch into an unverified directory.

Dispatch workers concurrently. Each worker's brief must contain:

- The absolute worktree path, assigned branch, base SHA, and instruction to read that worktree's repository guidance.
- The task, owned files or modules, interface agreements, acceptance criteria, and explicit exclusions. Include dependency outcomes; workers do not inherit the conversation.
- Setup and test commands discovered from the project. A worktree does not copy untracked files, ignored configuration, or dependencies. Use the documented setup; obtain approval before copying secrets. Isolate ports, databases, and other writable external resources per worker or serialize tests that share them.
- Instructions to edit only its assigned worktree and commit only its task changes on the assigned branch. Check status, diff, and recent commit style before staging explicit files. Preserve hooks and report commit failures.
- Instructions to leave other branches, worktrees, shared Git configuration, and the target alone. Only the coordinator integrates or removes worktrees; workers do not push, merge, rebase, or delegate overlapping work.
- A required return report with branch, final commit SHA, changed files, acceptance-criteria results, exact test commands and outcomes, and blockers. Leave a clean worktree and stop writing after reporting completion. If no changes are needed, explain why instead of making an empty commit.

Wait for the batch to finish before integration. If a worker fails or times out, confirm it has stopped before resuming it or assigning a replacement to the same worktree. Preserve partial work. Failed chunks and their dependents stay blocked; independent verified chunks may still be integrated. If a blocker cannot be resolved in this session, stop dispatching, stop or await active workers, and give the final report from step 6 without cleanup. Include any merge left in progress and the decision needed to resume.

## 5. Verify and integrate serially

For each reported success, inspect its actual branch, HEAD, clean status, commits, and full diff from its recorded base. Confirm that the base is an ancestor of the reported final SHA and that the branch still points to it. Check the scope and acceptance criteria, and run the relevant tests in that worktree. A worker's success message alone is not verification. Return incomplete work to the worker before merging.

Integrate verified chunks one at a time in the planned order. Before each merge, recheck the target branch, expected HEAD, clean status, and absence of an operation in progress. Merge the verified commit, not a branch tip that might have moved:

```bash
git -C "<target>" merge --no-edit --no-autostash "<final-sha>"
```

Use history-preserving merges, not squash or rebase, so cleanup can prove reachability. Check the exit status. On conflict, inspect both changes and preserve their intended behavior. Resolve only when the task and tests establish the answer; otherwise ask the user. Stage only resolved files and finish the merge with `git -C "<target>" commit --no-edit`. If abandoning this merge, use `git -C "<target>" merge --abort` only for the merge started by this run, after confirming no unrelated edits appeared.

After each merge, run relevant integration checks and record the new expected target HEAD. Mark the chunk `merged` only when its final SHA is an ancestor of target HEAD and those checks pass. If checks fail, pause integration, fix and commit the integration issue, then rerun checks. Keep the task worktrees until verification succeeds. A later batch starts from the updated target HEAD, so it includes its dependencies.

## 6. Verify the result and clean up

When all chunks are integrated, run the project-wide checks selected for the task and inspect the combined diff from `start-sha`. Report any unavailable checks rather than treating them as passed. Failed or unavailable required checks block cleanup unless the user explicitly accepts the limitation.

For each worktree created by this run, confirm its worker has stopped, its branch and HEAD still match the ledger, and `git status --porcelain=v1 --untracked-files=all` is empty. Inspect ignored files too; normal status does not show them, and removal can delete them. Preserve anything valuable or of unknown ownership and stop only processes started by this run.

Recheck the target identity and execute these commands in order, proceeding only when the preceding command succeeds:

```bash
git -C "<target>" merge-base --is-ancestor "<final-sha>" HEAD
git -C "<target>" worktree remove "<path>"
git -C "<target>" branch -d "<branch>"
```

If removal or branch deletion refuses, keep the remaining resources and report the reason. Do not escalate to force deletion, recursive directory deletion, or global pruning. Worktrees with submodules may need manual cleanup.

Finish by checking target status and the worktree/ref lists against the ledger. Report the target branch and final SHA, completed and blocked chunks, checks run, and any retained paths or branches with reasons. Claim completion only when every acceptance criterion is accounted for. Leave unrelated worktrees and branches untouched.

From m3nowak/skills, MIT.

More from m3nowak/skills