--- slug: "parallel-agent-worktree-skill" source_type: "skill_md" source_url: "https://cdn.jsdelivr.net/gh/TheAhmadOsman/parallel-agent-worktree-skill@main/SKILL.md" repo: "https://github.com/TheAhmadOsman/parallel-agent-worktree-skill" source_file: "SKILL.md" branch: "main" --- --- name: parallel-agent-worktree-skill description: Plan and execute complex work with parallel CLI agent-harness workers in git worktrees. Use for task decomposition, tmux worker spawning, deterministic loops, integration, verification, changelogs, and cleanup. license: Apache-2.0 --- # Parallel Agent Worktrees Use this skill when a broad implementation request benefits from parallel workers run through any CLI-based agent harness. The helper scripts are generic; the bundled JSON examples use Kimi CLI only as one concrete harness mapping. The workflow is: plan independent tasks, run workers in isolated git worktrees, review their output rigorously, integrate only useful work, verify the final tree, update changelogs, and clean up after the run. ## Non-Negotiables - Always verify the selected agent harness with ` --help` during preflight and follow the current CLI surface. Do not assume approval flags, prompt stdin, work-directory flags, sandboxing, or logging behavior transfer between harnesses. - For the bundled Kimi example only: as of 2026-04-11, `--yolo`/`--yes`/`--dangerously-auto-approve` automatically approves actions; `--print` is non-interactive and implicitly adds yolo. Prefer interactive `kimi --yolo` in tmux only after the user has approved that risk. - Keep every worker in its own branch and git worktree. Never let parallel workers edit the same checkout. - Do not start workers until you understand enough code, tests, docs, and constraints to write bounded task prompts with clear ownership. - Do not trust worker summaries. Review diffs, run tests, and inspect actual files before integrating anything. - Protect user work. Check for uncommitted changes up front and do not overwrite, stash, reset, or delete anything you did not intentionally create. - Integrate only reviewed work. Reject or send follow-up prompts for incomplete, speculative, conflicting, or unverified output. - Every parallel worker must update the repo-standard changelog or produce a per-worker changelog fragment for its change. The coordinator must reconcile fragments into the canonical changelog before final merge. - Final integration must merge accepted work back into the branch that was checked out at preflight. If that cannot be done, leave a clear report explaining why, where the work lives, what is still missing, and the exact next commands. - For self-hosted infrastructure, production-like services, or any work requiring backups, use deterministic loop generation with explicit backup gates instead of improvised parallel prompts. - When the user wants another agent harness, convert this skill recursively instead of doing a shallow search/replace. Update docs, scripts, examples, tests, poster copy, command equivalents, and edge-case guidance together. - For any non-Kimi harness, read `references/harness-portability.md` and resolve the installed target CLI at runtime. Do not assume Codex CLI, Claude Code, OpenCode, Droid Factory, Pi, or any other harness accepts Kimi-style flags or prompt stdin. ## Preflight Run: ```sh git status --short --branch git rev-parse --show-toplevel git branch --show-current command -v uv command -v tmux AGENT_CLI="${AGENT_CLI:-kimi}" AGENT_INTERACTIVE_ARGS="${AGENT_INTERACTIVE_ARGS:---yolo}" AGENT_NONINTERACTIVE_ARGS="${AGENT_NONINTERACTIVE_ARGS:---print --yolo --input-format text}" command -v "$AGENT_CLI" "$AGENT_CLI" --help ``` If the main worktree has uncommitted changes, classify them before spawning workers: - If they are unrelated user changes, leave them alone and branch workers from `HEAD`. - If workers need those changes, either include the relevant diff in each prompt or ask the user how they want the changes made visible to worktrees. - If the tree is not a git repository, stop and use a non-worktree approach. Set shared names: ```sh PROJECT_DIR="$(git rev-parse --show-toplevel)" INTEGRATION_BRANCH="$(git branch --show-current)" test -n "$INTEGRATION_BRANCH" BASE_REF="$INTEGRATION_BRANCH" WORKTREE_ROOT="${PROJECT_DIR}.worktrees" ``` Use a different `BASE_REF` only when there is a concrete reason, such as a feature branch or a known integration branch. Even then, keep `INTEGRATION_BRANCH` as the final merge target unless there is a clear blocker. Find the changelog convention before spawning workers: ```sh find "$PROJECT_DIR" -maxdepth 3 \ \( -iname 'CHANGELOG*' -o -iname '*release*notes*' -o -path '*/changes/*' \) \ -print ``` If the repo has a single shared changelog that would create conflicts, require each worker to write a unique fragment such as `.worker-runs/changelog/.md` and merge those fragments into the canonical changelog during integration. ## Plan The Work Read enough of the repo to make a real implementation plan. Cover architecture, entrypoints, tests, docs, build steps, and likely conflict points. For each proposed worker task, write: ```text Task: Branch/worktree name: Owned files or modules: May read: Must not edit: Goal: Acceptance criteria: Verification commands: Changelog path or fragment: Integration risk: Dependencies: ``` Choose parallel tasks only when their write scopes are disjoint enough to review and merge independently. Keep tightly coupled design work, shared API changes, migrations, or cross-cutting refactors local or serial unless you deliberately split them into clear phases. For competing approaches, spawn alternative workers with explicit branch names such as `alt-router-state-a` and `alt-router-state-b`, then integrate only the better result. ## Spawn Workers The bundled helper script avoids fragile tmux quoting and long-prompt problems. In this repository, run it through `uv run python`; in another environment, use the available Python 3 interpreter. Interactive workers assume the selected harness can run in a TTY and accept pasted follow-up prompts after startup. If the harness only supports one-shot prompt arguments, use deterministic loop mode or write a wrapper script. ```sh uv run python .agents/skills/parallel-agent-worktree-skill/scripts/agent_workers.py spawn \ --base "$BASE_REF" \ --prompt-file /tmp/.prompt \ --agent-cli "$AGENT_CLI" \ --agent-args "$AGENT_INTERACTIVE_ARGS" ``` If this skill is installed somewhere else, locate `scripts/agent_workers.py` in the skill directory and run that path instead. Worker prompt template: ```text You are a parallel agent worker running in an isolated git worktree. This worker is using this agent harness: Agent CLI: Agent args: Task: Ownership: - You may edit: - You may read: - You must not edit: Context: Requirements: - First inspect the relevant AGENTS.md files, code, and tests. - Keep changes scoped to your ownership. - You are not alone in the codebase. Other workers are editing disjoint scopes. Do not revert or rewrite work outside your task. - Use repo-standard commands such as `uv run ...`, `make format`, `make check`, or targeted pytest commands as appropriate. - Add or update focused tests when behavior changes. - Update the repo-standard changelog/release notes for your task. If the changelog is a shared conflict point, write a unique fragment at `.worker-runs/changelog/.md` or the repo's standard fragment directory, then report the path. - Commit your finished work on this branch with a Conventional Commit message. Final response: - Commit SHA - Changed files - Changelog file or fragment path - Verification commands and results - Known gaps or risks ``` Manual fallback: ```sh NAME="" BRANCH="$NAME" WORKTREE="$WORKTREE_ROOT/$NAME" SESSION="agent-worker-$NAME" git worktree add "$WORKTREE" -b "$BRANCH" "$BASE_REF" tmux new-session -d -s "$SESSION" -x 200 -y 50 \ "cd '$WORKTREE' && '$AGENT_CLI' $AGENT_INTERACTIVE_ARGS" sleep 5 tmux load-buffer -b "$SESSION-prompt" /tmp/$NAME.prompt tmux paste-buffer -t "$SESSION" -b "$SESSION-prompt" tmux send-keys -t "$SESSION" Enter ``` ## Generate Deterministic Loops Use deterministic Bash or Python loops when task fan-out is driven by conditions, inventory, backup status, maintenance windows, or other logic that should be auditable and repeatable. This is the safer path for self-hosted upgrades, Docker/LXC/VM changes, database migrations, fleet-wide config edits, package bumps across services, or any task where a failed preflight must prevent every worker from starting. Read [references/deterministic-loops.md](https://github.com/TheAhmadOsman/parallel-agent-worktree-skill/blob/HEAD/references/deterministic-loops.md) when the request involves backups, rollback, containers, VMs, LXC, Docker Compose, databases, remote hosts, generated task lists, or conditional execution. Render a loop from a JSON plan: ```sh uv run python .agents/skills/parallel-agent-worktree-skill/scripts/render_worker_loop.py \ --config .agents/skills/parallel-agent-worktree-skill/examples/self-hosted-upgrade.json \ --language python \ --output /tmp/run-agent-workers.py uv run python .agents/skills/parallel-agent-worktree-skill/scripts/render_worker_loop.py \ --config .agents/skills/parallel-agent-worktree-skill/examples/self-hosted-upgrade.json \ --language bash \ --output /tmp/run-agent-workers.sh ``` Generated loops: - Run preflight commands first. - Run backup commands only when their conditions pass, and fail closed when a required backup command fails. - Create one git branch and worktree per task. - Run the configured `agent.cli`, optional `agent.work_dir_arg`, `agent.args`, and `agent.prompt_mode` non-interactively in each worktree. - Capture prompts, agent output, verification logs, and a manifest under `.worker-runs/`. The default task output file is `agent.log`, configurable with `agent.log_name`. - Write rollback commands into the run log directory when tasks fail. - Respect `DRY_RUN=1`, `RUN_ID=...`, and `LOG_ROOT=...` environment overrides. Prefer Python output when you need concurrent workers, timeouts, structured manifests, or clearer error handling. Prefer Bash output when the environment is minimal and the logic is mostly shell-native. ## Convert This Skill To Another Harness If the user asks to replace the example harness with another agent harness, read [references/harness-portability.md](https://github.com/TheAhmadOsman/parallel-agent-worktree-skill/blob/HEAD/references/harness-portability.md) and [references/harness-conversion.md](https://github.com/TheAhmadOsman/parallel-agent-worktree-skill/blob/HEAD/references/harness-conversion.md). Do not assume flag compatibility. Run the target harness help command, map interactive and non-interactive modes, approval bypass, work-dir handling, prompt delivery (`stdin`, `argument`, or `file`), sandboxing, auth, logging, and cleanup semantics, then update the whole skill package. First-pass converter: ```sh uv run python .agents/skills/parallel-agent-worktree-skill/scripts/convert_harness.py \ --config .agents/skills/parallel-agent-worktree-skill/examples/harness-codex.json \ --output-dir /tmp/codex-worker ``` The converter copies this skill, renames the worker helper, rewrites generic defaults to target-harness defaults, and writes `CONVERSION_REPORT.md`. Treat the output as a draft. An agent must inspect and patch the converted package for target-specific semantics before it is used. Self-recursive runtime update prompt: ```text Convert this skill to . First run ` --help`. Create a harness mapping JSON, run scripts/convert_harness.py into a new skill directory, then comprehensively update README, SKILL.md, references, examples, scripts, tests, poster copy, and validation commands with the target harness equivalents. Cover interactive mode, non-interactive mode, approval bypass, work-dir semantics, prompt delivery mode, logging, cleanup, failure modes, auth, sandboxing, and edge cases. Run validation and report remaining manual checks. Finish with: › Let's unit test and integerate test comprehensively and extensively covering any and all things + any and all possible edge cases. ``` The final stage / execution for every converted skill is: ```text › Let's unit test and integerate test comprehensively and extensively covering any and all things + any and all possible edge cases. ``` ## Monitor And Steer Check workers regularly: ```sh uv run python .agents/skills/parallel-agent-worktree-skill/scripts/agent_workers.py status uv run python .agents/skills/parallel-agent-worktree-skill/scripts/agent_workers.py capture --lines 120 ``` Send follow-up instructions instead of abandoning a worker at the first issue: ```sh uv run python .agents/skills/parallel-agent-worktree-skill/scripts/agent_workers.py send \ --prompt-file /tmp/-followup.prompt ``` Use follow-ups for failed tests, overbroad edits, missed requirements, conflicts with another worker, or a better local discovery made after spawn. Keep follow-ups bounded. ## Review Worker Output For each worker, inspect the worktree from the main coordination session: ```sh WT="$WORKTREE_ROOT/" BRANCH="" git -C "$WT" status --short git -C "$WT" log --oneline "$BASE_REF"..HEAD git -C "$WT" diff --stat "$BASE_REF"...HEAD git -C "$WT" diff "$BASE_REF"...HEAD ``` Run the worker's verification commands yourself in that worktree. Add targeted tests or broader checks when the blast radius is larger than the worker assumed. Decision rules: - Accept when the diff is scoped, correct, tested, and compatible with the integration plan. - Accept only when the worker included a changelog update or fragment, unless the repository truly has no changelog convention. Record that exception explicitly. - Send back for fixes when the approach is sound but incomplete or tests fail. - Reject when the worker changed the wrong scope, invented APIs, ignored constraints, produced excessive churn, or overlaps a better accepted branch. - Keep notes on every accepted, rejected, and pending branch with the reason. ## Integrate Before integration, return to the main worktree and confirm it is clean except for changes you intentionally own: ```sh git status --short --branch test "$(git branch --show-current)" = "$INTEGRATION_BRANCH" ``` Prefer one of these paths: ```sh # Integrate a whole reviewed branch. git merge --no-ff # Integrate selected reviewed commits. git cherry-pick ``` Resolve conflicts in the integration worktree, not inside random worker checkouts. After each substantial merge or cherry-pick, run the relevant focused tests. After the full batch, run the repo-level checks appropriate to the change, usually some subset of: ```sh make format make check make test ``` If integration reveals a design conflict, either fix it locally after understanding both branches or send a precise follow-up to the relevant worker worktree. Before the final merge is considered done, reconcile every accepted worker changelog entry into the canonical changelog/release notes. Then verify the integrated result is on the original checked-out branch: ```sh git branch --show-current git status --short git log --oneline "$BASE_REF"..HEAD ``` If accepted work was integrated on a temporary integration branch, merge that branch back into `INTEGRATION_BRANCH` before reporting completion: ```sh git switch "$INTEGRATION_BRANCH" git merge --no-ff ``` If final merge-back is impossible, do not imply completion. Leave a clear report with: - Original checked-out branch from preflight. - Current branch and all worker/integration branches containing accepted work. - Exact blocker: conflicts, failed tests, dirty user changes, missing changelog, or missing permissions. - Completed work, missing work, and validation already run. - Exact next commands for the user or next agent to resume safely. ## Cleanup After accepted work is integrated and rejected work has been recorded, stop sessions and remove worktrees: ```sh uv run python .agents/skills/parallel-agent-worktree-skill/scripts/agent_workers.py cleanup --branch-delete git worktree prune ``` Use `--branch-delete` for branches already merged. Use `--force-branch-delete` only when the branch is intentionally discarded, its useful details have been recorded, and no user work will be lost. If there is doubt, remove the worktree but keep the branch and report it. ## Final Report Report: - What was integrated, with worker branches and commit SHAs. - What was rejected or left out, with reasons. - Verification commands run and their results. - Remaining missing work, risks, or follow-up tasks. - Cleanup performed, including removed tmux sessions, worktrees, and branches.