Ywc Sequential Executor

Sequential Executor

Announce at start: "I'm using the ywc-sequential-executor skill to run tasks through their full lifecycle in strict order."

Execute tasks generated by the ywc-task-generator skill through the full development lifecycle: branch creation, implementation, commit, PR, CI verification, merge, and local sync.

Rationalization Defense

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

| Excuse | Reality | |---|---| | "Task A and Task B are independent, run them in parallel" | This is the sequential executor. For parallel runs, the user must explicitly switch to ywc-parallel-executor. | | "CI is taking long, --skip-ci-wait gets the next task started" | Skipping CI hides regressions in subsequent tasks. Skip only if user explicitly approved. | | "Previous task partially succeeded, I'll continue and clean up later" | Each task must leave the codebase buildable. Stop and report on partial success. | | "Merge conflict is small, I'll resolve and continue" | Conflicts during sequential execution mean a base branch shifted. Stop, sync, get user direction. | | "PR is created, mark task complete" | Task is complete only when merged + cleaned up + branch deleted. PR alone is not done. | | "Task spec is unclear, I'll infer from neighbors" | Stop. Inferring from neighbors compounds error across the sequence. Ask user. | | "Local merge with --local-merge is faster, default to it" | Default is PR-based. --local-merge only when user explicitly opts in (e.g., personal repo). | | "Lint/format failed in Step 4 with --draft, I'll stop and report" | Lint/format failures are auto-fixable. Run the project's fix command (e.g., eslint --fix, prettier --write, ruff --fix), commit the result, re-run verification, then continue to Step 5. Only stop if auto-fix fails to resolve residual errors after 2 attempts. | | "--draft creates the PR and stops — bot review is for later" | Bot review bots (CodeRabbit, Codex Review, Claude Review) post on draft PRs immediately. After finish-branch creates the draft PR, poll for reviews and invoke ywc-handle-pr-reviews. The PR stays draft — responding now avoids a round-trip after un-drafting. | | "normal-pr range: CI passed and no bot comments yet — proceed to merge" | Bot reviewers post 1–5 minutes after CI completes, not immediately. ywc-finish-branch runs a mandatory 60-second initial wait plus a 300-second polling window before concluding no bots are active. BOT_COUNT == 0 right after CI is not evidence that no bots are active — it means they have not posted yet. The polling window is a required wait gate in range mode, not a pause to skip. | | "Bot comments were addressed via ywc-handle-pr-reviews — the PR is handled, proceed to merge" | Addressing comments clears only one of three blockers. The review-fix push triggers a fresh CI run that can fail, and the base may have advanced into a CONFLICTING state meanwhile. ywc-finish-branch re-verifies CI green and mergeable == MERGEABLE (Step 4 + Step 4-final merge-readiness gate) after every bot iteration — never merge on the strength of "comments addressed" alone. CI failure and base conflict are delivery blockers independent of comments. | | "Last task in --local-merge range: no following task needs this merge, skip finish-branch" | Step 5 (Delivery) is unconditional — every task, including the last, must have its feature branch merged into base, the completion-marker committed, and the push executed via ywc-finish-branch. Without it, the implementation code is stranded on an orphaned feature branch, tasks/completed/ is wrong, and the remote base branch is missing the work. The absence of a next task is not a reason to skip delivery. | | "concurrency/idempotency Task Verify is slow or hard to satisfy locally — pass lint/typecheck/build instead" | Task Verify Layer-1 already gates the merge. A hard-to-satisfy concurrency check must not be downgraded to Layer-4 (lint/build); satisfy it via the task's alternative-verification note (code-level lock/transaction proof or an integration test plan). | | "Last task in normal-pr range: it's the last one, no need to omit --defer-push" | --defer-push must be omitted on the last task in normal-pr range — that omission IS the flush. If --defer-push is set on the last task, all accumulated completion-marker commits stay local and are never pushed. The last task's ywc-finish-branch invocation performs the single batch push; no separate git push runs after the loop. | | "--aggregate-pr: all tasks local-merged onto the work branch, the run is done" | The work branch is not the base branch. The group is delivered only when the single work → base PR is created, marked ready, CI-verified, bot-reviewed, merged, and local base synced (Section C of [references/aggregate-pr.md](./references/aggregate-pr.md)). A work branch full of merged tasks with no merged PR is an incomplete group. | | "--aggregate-pr: per task, deliver to the real base like local-merge" | Per-task delivery targets the work branch (--base-branch work/ in finish-branch local-merge), never the real base. Merging tasks straight onto the real base would defeat the single-PR goal and mutate base before review. Each task branches from and merges into the work branch only. | | "--worktree: the cycle runs in the worktree, so the skill just cds there once and proceeds" | This skill is an LLM prompt with no persistent shell — a cd does not survive between Bash calls. Every git command must be git -C "$WT" …, every Edit/Write must target an absolute path under $WT, and every test/lint must be cd "$WT" && inside a single Bash call. See [references/worktree-run.md](./references/worktree-run.md) §A1. | | "--worktree non-aggregate DONE: prune the worktree and its integration branch together" | Non-aggregate prune must pass --keep-branch so the integration branch survives — it is what the user opens the final integration→trunk PR from. Omitting --keep-branch deletes that branch and strands the whole run's work with no path to trunk. Only --aggregate-pr (whose work/ is already merged) prunes the branch. See [references/worktree-run.md](./references/worktree-run.md) §A3. | | "I'll add tests after the implementation is working" | For behavior changes, the failing test comes first — a bugfix needs a regression test that fails on the old code, a feature needs a failing unit/integration test before implementation. Without test feedback gating each step you outrun your headlights and the code crashes at runtime. Docs/config/mechanical tasks are the only exception (record it). See [../references/tdd-deep-module-gray-box.md](../references/tdd-deep-module-gray-box.md) §2. | | "This task only changes internals, no contract to write down" | If the change alters a public contract (exported function, endpoint, event, DTO, schema, props, CLI flag), design and write the interface before the body, and report it. Shallow single-use wrappers around cohesive behavior are the maze AI gets lost in later. See [../references/tdd-deep-module-gray-box.md](../references/tdd-deep-module-gray-box.md) §3. | | "I reviewed the whole implementation line by line" | Default review is gray-box — verify the contract, delegate internals. The exception is critical paths (auth, payment, crypto, PII, external input): those get internal review and /ywc-security-audit, forced even without --review. Uniform-depth review wastes effort on safe code and under-scrutinizes dangerous code. See [../references/tdd-deep-module-gray-box.md](../references/tdd-deep-module-gray-box.md) §4. |

Violating the letter of these rules is violating the spirit. Sequential execution exists because each task's correctness depends on the previous task's stable state.

Arguments

Parse $ARGUMENTS for the following parameters:

| Parameter | Format | Example | Description | |-----------|--------|---------|-------------| | Task specifier | ` or .. | 000001-010-db-create-users or 000001-010..000002-030 | Single task or range (phase+sequence prefix match). Both 001010 (legacy) and 000001-010 (new 6-digit PHASE) formats are accepted; prefix matching works with either. | | --pr-lang | --pr-lang | --pr-lang ja | PR title/description language. Default: auto-detect from CLAUDE.md or AGENTS.md, fallback to project's dominant language | | --tasks-dir | --tasks-dir | --tasks-dir ./docs/tasks | Tasks directory path. Default: tasks/ | | --skip-ci-wait | flag | | Skip CI wait and auto-merge (create PR only) | | --draft | flag | | Create PR as draft, skip merge | | --local-merge | flag | | Skip PR creation entirely — merge the feature branch into the base branch locally and push. Mutually exclusive with --draft and --skip-ci-wait | | --base-branch | --base-branch | --base-branch develop | Base branch override. Default: auto-detect (develop > main > master) | | --dry-run | flag | | Show the execution plan (task order, dependencies, modes) without executing anything | | --terse | flag | | Compact Completion Report: task table + Completion Status only — no prose reminders, no mode explanations, no advisor notes | | --review | flag | | Auto-run /ywc-impl-review after each task, before PR creation or merge | | --run-tests-locally | flag | | Before merging in --local-merge mode, detect and run the project's test command. On failure: mark task FAIL and do not merge. Ignored in PR-based modes. | | --aggregate-pr | flag | | Deliver the whole range as **one work branch + one PR**: each task is local-merged onto a work/ branch sequentially, then a single PR delivers the group to the base branch (ready → CI → bot → merge). The real base is never mutated until the final merge. See [references/aggregate-pr.md](./references/aggregate-pr.md) | | --group-name | --group-name | --group-name project-health | Names the work branch (work/). --aggregate-pr only; defaults to work/- when omitted | | --worktree | flag | | Run the **whole range inside one isolated git worktree** so the main checkout stays free. Run-level isolation — tasks still run strictly sequentially. **Independent flag**, not part of the mutual-exclusion group: combines with all four delivery modes and --review`. Full lifecycle in [references/worktree-run.md](./references/worktree-run.md). |

Flag conflicts: --local-merge, --draft, --skip-ci-wait, and --aggregate-pr are mutually exclusive. If the user passes more than one, stop before any branch or implementation work and ask which mode they actually want. The reason is that --local-merge skips PRs entirely while the others assume a PR exists — silently picking one would surprise the user. --group-name is valid only with --aggregate-pr. --worktree is orthogonal to this group — it is not a fifth member and may combine with any one delivery mode (§A8 S4); see [references/worktree-run.md](./references/worktree-run.md).

Example:

/ywc-sequential-executor 000001-010 --local-merge --draft
# → Stop. Report: "--local-merge and --draft are mutually exclusive
#   (local-merge produces no PR; draft requires one). Which mode did you want?"

--review can be combined with any delivery mode flag.

--run-tests-locally has no effect without --local-merge (PR CI handles tests in PR-based modes).

If no task specifier is given, detect the next executable task from the dependency graph.

Dry Run Mode

When --dry-run is set, perform Pre-flight and Task Resolution as usual, then display:

• Resolved task list in execution order (with phase+sequence and full name)
• Dependency status for each task (satisfied / pending)
• Active mode flags (--draft, --skip-ci-wait, --local-merge, --aggregate-pr, or normal)
• Base branch that would be used (and, for --aggregate-pr, the work/ branch that would be created)

Do not create branches, modify files, or run any git commands beyond read-only operations (git branch --show-current, git status). Exit after displaying the plan.

Context

• Current branch: !git branch --show-current
• Changed files: !git status --short
• Tasks directory: !ls tasks/ 2>/dev/null || echo "No tasks/ directory found"

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 task and step. 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 range, 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 [references/checkpoint-resume.md](./references/checkpoint-resume.md). A new range hijacked by a stale interrupted run is the failure this guard prevents.

Before starting execution, verify these conditions:

1. Clean working tree — git status --porcelain must be empty. If dirty, warn the user and stop.
2. On base branch — Should be on main/develop/master. If on a feature branch, warn and ask whether to continue.
3. gh CLI ready — gh auth status must succeed.
4. Tasks directory exists — The tasks directory must contain task subdirectories and dependency-graph.md.
5. Spec-Reference external URL policy — Determine whether this project allows fetching external URLs (Notion, Confluence, Figma, etc.) listed in a task's Spec Reference section. See [External URL Policy](#external-url-policy) below. This check runs once per project, not once per task.

State Init (non-resume runs only): Initialize .ywc-run-state.json now using the Write tool (see format in [Checkpoint and Resume](#checkpoint-and-resume)). Do not modify .gitignore during execution; the ignore entry must already be committed or present in repo-local exclude before the run:

grep -qxF '.ywc-run-state.json' .gitignore 2>/dev/null \
  || grep -qxF '.ywc-run-state.json' .git/info/exclude 2>/dev/null \
  || { echo "Missing .ywc-run-state.json ignore entry; add it to tracked .gitignore before the run or to .git/info/exclude for local-only state."; exit 1; }

External URL Policy

Tasks generated by ywc-task-generator may list external URLs in Spec Reference > Primary Sources. Fetching external content mid-task is unpredictable (network, rate limits, SSO walls) and is also a privacy decision the user must make once per project.

Procedure: at Pre-flight, check .claude/settings.local.json for taskExecutor.externalSpecUrls. If present, use it silently. If missing, ask the user once to choose deny (default), allow, or allowlist, then persist the decision under the taskExecutor key (preserving every other key in the file). During Step 1b enforcement, apply the chosen policy: deny skips all http(s):// URLs, allow fetches everything, allowlist fetches only matching host+path prefixes.

For full procedure, jsonc schema, exact prompt wording, and rationale, see [references/external-url-policy.md](./references/external-url-policy.md).

Definition of Done

A task is done only when all of the following have happened, in this order. A task that has been "merged but not moved to completed/" is not done — Step 6's auto-detect logic and other tasks' dependency validation read /completed/ as the source of truth, so a missing move silently breaks dependency resolution for the next task in any range and for any future invocation of this skill.

1. Implementation passed all four layers of Step 4 verification (Task Verify commands, task-local tests, full project test suite, lint/typecheck/build).
2. ywc-finish-branch retur

…

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.