Parallel Agent Execution

Read references/mode-and-contract.md when you need the contract templates, the worktree runbook, or the failure-recovery checklist.

Mode Rules

Shared-tree Serialized

Use this when direct edits or a runnable checkout are needed, but one live tree is still the safest place to do the work.

• Only one coding owner edits the shared tree at a time.
• Other helpers may review, inspect, or prepare patches, but they do not edit the same live tree concurrently.
• Ownership may still overlap across the overall task. What stays serialized is live-tree editing.
• Re-baseline between owners if the boundary, branch, or target files change.
• Keep global files with the main agent unless one pass is explicitly assigned to own them.

Patch-Only Parallel

Treat this as the default parallel mode when a runnable checkout is not required.

• Helpers do not edit the live worktree.
• Give each helper a base sha, the exact file or diff anchor, a narrow ownership boundary, the required patch format, and the verification the main agent will rerun after applying.
• The main agent applies patches one at a time, inspects scope, and verifies centrally.
• If a helper ends up needing direct local edits or runnable debugging, stop and re-choose the mode instead of stretching the patch-only contract.

Isolated Worktree Parallel

Use this only when direct edits plus owner-local verification are worth the setup cost.

Require all of the following:

• One exact base sha for every coding owner. Do not rely on branch names alone.
• Create each owner branch and worktree from that exact base sha.
• One short-lived branch per coding owner.
• One explicit path ownership boundary per coding owner.
• One explicit handoff artifact per coding owner: branch name + tip commit sha or another recorded patch artifact the main agent can integrate deterministically.
• Global files default to the main agent unless explicitly assigned.
• Shared prepared state, submodules, caches, or generated artifacts must be rebuilt per owner, owned by the main agent, or exposed as single-writer read-only inputs.
• Coding owners never merge each other's branches. The main agent integrates, verifies, and resolves conflicts.

If the original worktree is dirty, do not assume uncommitted changes carry into new worktrees. Do not stash, reset, or commit user changes just to make worktrees convenient. Either stabilize the needed baseline explicitly or choose shared-tree serialized or patch-only parallel.

Recommended branch naming:

agent/<task-slug>/<owner-id>

Recommended worktree naming:

<worktree-root>/wt-<repo-slug>-<task-slug>-<owner-id>

Sanitize repo, task, and owner tokens into short, lowercase, filesystem-safe and ref-safe slugs before using them in branch or path names. If a branch or worktree name already exists, either remove the stale state first or add a recorded suffix instead of improvising mid-run.

Environment Rules

The main cost is usually duplicated setup, not Git object storage.

• Reuse caches only when they are safe for concurrent use across the chosen base state. If a cache is mutable or not keyed by lockfile, toolchain, or base sha, isolate it per owner or avoid worktrees.
• Avoid copying heavyweight generated directories into each worktree.
• Bootstrap only the minimum environment needed for that owner's boundary.
• If full setup per worktree is too expensive, switch to patch-only parallel, reduce the number of owners, or serialize the risky boundary.
• If the repo uses submodules, generated outputs, or shared prepared artifacts, define whether they are rebuilt per owner, main-agent owned, or exposed as single-writer read-only inputs.
• If isolated caches or prepared state are created per owner, decide up front whether they will be deleted, retained for diagnosis, or handed off as explicit residual state.
• If a repo-specific bootstrap or cache policy exists, follow it rather than inventing a new one.

Integration And Cleanup

Every coding owner must report:

• changed files;
• base sha used;
• handoff artifact used for integration, such as branch + tip commit sha or a recorded patch;
• verification run;
• residual risks;
• whether the owner worktree is clean enough for cleanup, or why it must be retained.

The main agent integrates one owner at a time onto the chosen target branch. If an owner drifted from the agreed base or touched out-of-scope files, stop and re-baseline before continuing. If two owners end up needing the same file, serialize the rest of that boundary instead of forcing parallel merge churn. Before each integration, verify the owner's reported base sha matches the agreed base or a recorded re-baseline, and inspect the owner diff or changed-files list against the ownership boundary. Use a concrete checkable artifact such as an explicit diff, changed-file list, or patch scope record, not memory alone. If either check fails, stop before integrating and re-brief or re-baseline before any further integration.

If post-integration verification fails, do not keep integrating. Keep the failing owner result quarantined for diagnosis as a retained branch, worktree, or patch artifact, undo the attempted integration on the target branch if that is safe, rerun target-branch verification immediately after any undo, record whether rollback restored a stable target state, then tighten the boundary, switch modes, or report the task as blocked.

Treat undo as safe only when it can be done without discarding unrelated user changes or already-accepted owner results. If that is unclear, do not guess: retain the failing state for diagnosis and report the task as blocked.

When reporting blocked, say explicitly whether earlier owner results remain integrated on the target branch, were rolled back, or are being retained outside the target branch for diagnosis. Do not leave the target state ambiguous.

Before closing:

1. Run the most relevant integration verification yourself.
2. Remove finished temporary worktrees and owner-specific caches unless they were intentionally retained for diagnosis.
3. Delete merged short-lived branches unless the user asked to keep them or they are needed for failure analysis.
4. Record any skipped cleanup as explicit residual state.

Final status should make these explicit:

• chosen execution mode;
• branch and base sha;
• owner boundaries;
• owner handoff artifacts;
• which owner results are integrated on the target branch and which are retained only as external branches, worktrees, or patch artifacts;
• verification run by owners and rerun by the main agent;
• cleanup completed, skipped, or intentionally retained.

Repo Overrides

This skill is portable by default. If a repository documents its own agent execution policy, prefer that policy over defaults from this skill.

Look for repo-local guidance in AGENTS.md, .agents/, docs/, or another repository-specific operator guide. Useful overrides include:

• canonical base branch;
• standard bootstrap or verification commands;
• heavy directories or caches;
• files that must stay main-agent owned;
• branch or worktree naming exceptions.