Ywc Parallel Executor

ywc-parallel-executor (Parallel Executor)

Announce at start: "I'm using the ywc-parallel-executor skill to run independent tasks concurrently in isolated worktrees."

> Worktree lifecycle is owned by the dedicated [ywc-worktrees](../ywc-worktrees/) skill (priority resolution + --mode create / audit / prune / resolve). This skill delegates worktree creation, audit, and cleanup to ywc-worktrees instead of inlining the procedures. See [ywc-worktrees/SKILL.md](../ywc-worktrees/SKILL.md) for the four-mode contract and the priority chain (.worktrees/ > CLAUDE.md worktree_root > caller-specified > legacy fallback). The bundled audit-worktrees.sh / cleanup-worktree.sh scripts have moved to that skill.

Executes tasks generated by task-generator in parallel using agents.

Rationalization Defense

When tempted to skip a step, check this table first:

| Excuse | Reality | |---|---| | "Tasks look independent, run all in parallel" | Run only tasks whose Ownership and Shared Surfaces do not overlap. Dependency-graph.md is the source of truth. | | "Wave 1 had a partial failure, start Wave 2 anyway" | Wave boundary is a hard gate. All Wave N tasks must succeed before Wave N+1 starts. | | "Worktree cleanup is manual hassle, skip it" | Stale worktrees corrupt subsequent runs. Always cleanup after each task completes via ywc-worktrees --mode prune (see [ywc-worktrees](../ywc-worktrees/)). | | "Conflicts With is just a hint" | If two tasks declare Conflicts With each other, they cannot run in the same wave even if dependencies allow. | | "Task category does not match any specialized agent, skip the assignment" | Default to executor agent. Never silently drop the task. | | "Mid-wave one task is slow, kill it and continue" | A killed task leaves a dirty branch. Stop, report, and let the user decide. | | "--draft creates PR at the end, bot review can wait until un-draft" | Bot review bots (CodeRabbit, Codex Review, Claude Review) post on draft PRs immediately. After creating the draft PR in Step 5, poll for reviews via ../references/pr-bot-polling.md and invoke ywc-handle-pr-reviews if BOT_COUNT > 0. The PR stays draft — responding now avoids a round-trip after un-drafting. ywc-handle-pr-reviews itself also clears CI failures and base conflicts (its three mandatory gates), so handling comments is not "comments only" — it leaves the PR mergeable. | | "The aggregate draft PR passed CI before bot reviews — re-checking CI after bot fixes is extra work" | Bot review fixes push new commits that trigger a fresh CI run. The pre-bot CI result is stale and does not cover the updated code. Always re-verify CI after pushing bot review fixes on the aggregate draft PR (Step 5). | | "Last task in the last wave has no downstream wave, skip delivery for it" | Step 4e is unconditional — every task in every wave, including the last task in the last wave, must complete (a) and (b). The absence of a downstream wave is not a reason to skip delivery. Without delivery (ywc-finish-branch for --local-merge/--draft, or gh pr merge + inline Mark Complete for --per-task-pr), the implementation code is stranded on an orphaned feature branch, tasks/completed/ is wrong, and the base branch is missing the work. | | "All waves done in --draft mode — go straight to Completion Report" | For --draft, before the Completion Report the aggregate draft branch must be created and pushed (Step 5 pre-report). The run does not end at the last wave's 4i; the Step 5 pre-report steps are required. | | "--per-task-pr: the PR is created, move to the next task" | --per-task-pr is now a full-lifecycle mode. Creating the PR is not delivery — you must wait for CI to pass, handle bot reviews, merge the PR (gh pr merge --delete-branch), sync local base, and commit + push the completion marker, all within the task's slot in the wave (Step 4e (a)+(b)). A created-but-unmerged PR is an incomplete task. | | "--per-task-pr: CI is green, merge the PR" | A sibling task in the same wave may have merged first, leaving this PR CONFLICTING or BEHIND. Refresh the branch against the latest base (Step 4e (a) step 4, merge-not-rebase per references/pr-conflict-resolution.md) and re-verify CI before gh pr merge. A real textual conflict on refresh marks the task BLOCKED — never force-merge. | | "concurrency/idempotency 4c Task Verify is slow or hard to satisfy locally — pass lint/typecheck/build instead" | The 4c Task Verify gate already gates the merge. A hard-to-satisfy concurrency check must not be downgraded to a lint/typecheck/build pass; satisfy it via the task's alternative-verification note (code-level lock/transaction proof or an integration test plan). | | "--aggregate-pr: the single PR is created, the group is done" | --aggregate-pr is full-lifecycle, not draft. Creating the aggregate PR is not delivery — you must mark it ready, wait for CI, handle bot reviews, pass the merge-readiness gate, merge it (gh pr merge --delete-branch), and sync local base. A created-but-unmerged aggregate PR is an incomplete group. See [references/aggregate-pr.md](references/aggregate-pr.md) §B. | | "--aggregate-pr: re-Mark-Complete the tasks after the PR merges" | Each task's chore: mark … as completed commit already landed on the aggregate branch during its wave (--defer-push local merge, same as --draft). The aggregate PR merge carries those marker commits into base. Running Mark Complete again would double-move directories. Do not re-mark. | | "Run several --aggregate-pr groups in parallel in this one clone" | They share the local ` branch ref, which the --draft-style accumulation mutates (git reset --hard origin/ + per-task merges) — concurrent groups corrupt each other's base accumulation. Parallel groups need **one clone per group** (or run them back-to-back). See [references/aggregate-pr.md](references/aggregate-pr.md) §C. | | "Use git worktrees to split the parallel groups inside one clone" | Worktrees separate the working tree and the untracked .ywc-run-state.json, but **share .git refs** — the local branch is shared and can be checked out in only one worktree, so the accumulation still collides at the ref layer. Worktrees are not an isolation boundary for this mode; use separate clones. See [references/aggregate-pr.md](references/aggregate-pr.md) §C. | | "Each wave has only one task — worktrees add nothing, just work on the aggregate branch" | Worktree-per-task (Step 4a) is unconditional, independent of wave width and delivery mode. A fully linear chain (every wave = 1 task) is the **wrong input** for this skill — stop and route to ywc-sequential-executor per the Step 2 Linear-chain guard. Never invent an aggregate-branch-serial path. | | "--aggregate-pr accumulates on the aggregate branch, so check it out and commit there" | --aggregate-pr changes only **end-of-run** delivery (Step 5 / §B). Per-task execution (Step 4a–4e) is identical to every mode: isolated worktree + feature branch + --defer-push` local merge. The aggregate branch is carved at Step 5, never used as the per-task work surface. | | "Implement the whole wave, then verify everything at the wave end" | That is outrunning your headlights — behavior-changing tasks crash at runtime when test feedback comes only after a big batch. Tests gate implementation: a behavior-changing worker authors/confirms its failing test before its implementation (Step 4b directive). See [../references/tdd-deep-module-gray-box.md](../references/tdd-deep-module-gray-box.md) §2. | | "Same-wave tasks share an API/DTO, they'll each just edit it" | A shared public surface edited by two parallel workers is a merge/design conflict waiting to happen. Define the contract before worker dispatch (or serialize the tasks across waves); design the interface before the body. See [../references/tdd-deep-module-gray-box.md](../references/tdd-deep-module-gray-box.md) §3 and the Shared Surfaces guard. |

Violating the letter of these rules is violating the spirit. Parallel execution is faster only when wave isolation is honored.

Arguments

| Parameter | Format | Example | Description | |-----------|--------|---------|-------------| | Task specifier | ` or .. | 000001-010..000002-040 | Single task or range. Both 001010 (legacy) and 000001-010 (new 6-digit PHASE) formats are accepted; range matching uses lexical order. | | --all | flag | | Execute all tasks | | --tasks-dir | --tasks-dir | --tasks-dir tasks/ | Tasks directory (default: tasks/) | | --pr-lang | --pr-lang | --pr-lang ko | PR title/description language passed to PR creation (used by --aggregate-pr's final ywc-create-pr call). Default: auto-detect from CLAUDE.md or AGENTS.md, fallback to the project's dominant language | | --review | flag | | Auto-run /ywc-impl-review on each task's worktree branch before the wave merge (Step 4d). Applies the recurring-defects catalog to catch bot-flagged defect classes before the PR opens | | --local-merge | flag | | No PR, merge and push to base-branch directly | | --draft | flag | | Create draft PR after all tasks complete | | --per-task-pr | flag | | Per task: create the PR, wait for CI, handle bot reviews, then **merge the PR** (gh pr merge --delete-branch), sync base, and mark complete — the full lifecycle, mirroring ywc-sequential-executor's default normal-pr mode | | --aggregate-pr | flag | | Whole invocation → **one** branch + **one** PR. Tasks still run in parallel (waves) and accumulate onto a single aggregate branch (same per-wave merge as --draft); the end-of-run PR is marked ready, CI-verified, bot-reviewed, and **merged**. The full-lifecycle twin of --draft. See [references/aggregate-pr.md](references/aggregate-pr.md) | | --group-name | --group-name | --group-name payments | Names the aggregate branch (aggregate/) and disambiguates concurrent groups. --aggregate-pr only; defaults to aggregate/- when omitted | | --terse` | flag | | Compact Completion Report: task table + Completion Status only — no prose reminders, no worktree audit lines, no mode explanations |

--review can be combined with other flags.

Flag conflicts: --local-merge, --draft, --per-task-pr, and --aggregate-pr are mutually exclusive. If multiple are specified, ask for clarification before execution. --group-name is valid only with --aggregate-pr.

Default behavior: When none of --local-merge, --draft, --per-task-pr, or --aggregate-pr is specified, ask the user which mode to use before execution. Do not silently default to any mode — the user must explicitly choose how completed tasks are delivered. Present the four options:

1. --local-merge — No PR, merge and push to base-branch directly
2. --draft — Create a single draft PR after all tasks complete (left open for human merge)
3. --per-task-pr — Create, CI-verify, bot-review, and merge an individual PR per task (full lifecycle, like ywc-sequential-executor's default)
4. --aggregate-pr — One branch + one PR for the whole invocation, CI-verified, bot-reviewed, and merged (the full-lifecycle twin of --draft)

Definition of Done

A task is done only when all of the following have happened, in this order. A task that is "merged but not marked" is not done — downstream waves resolve dependencies by reading /completed/, so a missing move silently breaks the dependency graph for the next wave.

1. The feature branch passed Task Verify (Step 4c) and any optional review (Step 4d).
2. The task was delivered in Step 4e. For --local-merge and --draft, ywc-finish-branch returned DONE — that status enforces the merge with post-merge verification and the move of the task directory to /completed/ with a chore: mark as completed commit. For --per-task-pr, the PR passed CI, was merged via gh pr merge --delete-branch, local base was synced, and the same completion-marker move-commit was made and pushed.
3. For --local-merge and --per-task-pr: every merge / PR-merge and completion-marker commit was pushed immediately during the wave. For --draft: the deferred local merge commits accumulate locally and are pushed once at the end of all waves before the Completion Report.
4. The worktree was removed and the feature branch was deleted (Step 4g) — finish-branch leaves the local branch alive when called with --keep-branch, which is mandatory in this skill because the worktree owns the branch checkout. Step 4g is therefore the source of truth for branch deletion in parallel execution.

If any of the four is missing, the task is incomplete regardless of how git log --oneline base-branch looks. The Wave Delivery + Mark Complete step (Step 4e — ywc-finish-branch for --local-merge/--draft/--aggregate-pr, inline gh pr merge + Mark Complete for --per-task-pr) writes the code and the contract; Step 4g releases the worktree and the branch.

--aggregate-pr group-level done: in addition to every task satisfying the four conditions above (delivered via the same --draft-style per-wave local merge with --defer-push), the group is done only when the single aggregate PR has been marked ready, passed CI, cleared bot review, passed the merge-readiness gate, and been merged with local base synced (Step 5 + [references/aggregate-pr.md](references/aggregate-pr.md) §B). A run whose aggregate PR is created but unmerged is DONE_WITH_CONCERNS at best, never DONE.

Non-Stop Execution Principle

> Action required before creating any worktree: Read [../references/non-stop-execution.md](../references/non-stop-execution.md) now. It defines the exhaustive allowed-stop list, the force-continue rule, tool permission prompt handling, and the Tool Error Recovery policy (how to recover from Edit/Bash failures without entering extended thinking). Do not defer this read to mid-execution.

Execute all waves without interruption. Do not ask the user for confirmation between waves. The shared rule, full stop list, force-continue rule, zero-output rule, and --local-merge rationale live in [../references/non-stop-execution.md](../references/non-stop-execution.md).

The unit for this skill is wave. The Allowed Stop Reasons that are parallel-specific are:

• Pre-flight failure
• Circular dependency detected
• All tasks in a wave failed
• git push rejected by remote
• Merge conflict

The "Zero output between transitions" rule applies to the gap between Step 4g/4h of one wave and Step 4a of the next. Everything else — Force Continue Rule, what not to stop for, tool-permission-prompts-are-not-stop-conditions, and the --local-merge rationale — is in the reference and applies verbatim.

Pre-flight

> Resume check first: Before running the checks below, look for .ywc-run-state.json in the project root. If it exists, follow the Resume Detection procedure in [Checkpoint and Resume](#checkpoint-and-resume). If the user confirms resume, skip Pre-flight and jump to the saved wave and pending tasks. If the user declines or there is no state file, proceed with the checks below. Intent-match guard (do not skip): if this invocation specifies an explicit range/task that does not match the saved run's tasks, never silently resume — surface the divergence and require an explicit choice (resume the saved run vs discard it and start the new range), per the guard in the [Resume Detection](#resume-detection) procedure. A new range hijacked by a stale interrupted run is the failure this guard prevents.

Verify the following conditions before starting:

1. Clean working tree — git status --porcelain must be empty
2. On base branch — Must be on main/develop/master
3. Tasks directory exists — dependency-graph.md and task subdirectories must be present
4. gh CLI authenticated (PR creation modes only) — gh auth status must succeed
5. **No s

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: yongwoon
• Source: yongwoon/ywc-agent-toolkit
• License: MIT

Install and usage instructions live in the source repository linked above.