ywc-docker-isolate
(ywc) Use when parallel Git worktrees each run their own Docker stack and collide on host ports ("port is already allocated") — derives a deterministic per-worktree host-port block + COMPOSE_PROJECT_NAME, tears down only that worktree's stack, and audits stale stacks. Delegated from `ywc-parallel-executor` (audit/setup/teardown). Triggers: "docker port 격리", "compose 포트 충돌", "ywc-docker-isolate", "docker isolate", "worktree docker stack", "Docker ポート分離". Do not use for projects without Docker/docker-compose (no-op), non-Docker workspace isolation, infrastructure topology design (use ywc-infra-design), or `ywc-sequential-executor` (single task, no worktree port collision).
- License 许可
- MIT
- 最近更新
- 2026-11-08
- Stars
- ★ 8
- Forks
- 1
01 前言 Front Matter
- name
- ywc-docker-isolate
- description
- (ywc) Use when parallel Git worktrees each run their own Docker stack and collide on host ports ("port is already allocated") — derives a deterministic per-worktree host-port block + COMPOSE_PROJECT_NAME, tears down only that worktree's stack, and audits stale stacks. Delegated from `ywc-parallel-executor` (audit/setup/teardown). Triggers: "docker port 격리", "compose 포트 충돌", "ywc-docker-isolate", "docker isolate", "worktree docker stack", "Docker ポート分離". Do not use for projects without Docker/docker-compose (no-op), non-Docker workspace isolation, infrastructure topology design (use ywc-infra-design), or `ywc-sequential-executor` (single task, no worktree port collision).
02 资源文件 12
- 参考文档README.en.md2.2 KB
- 参考文档README.es.md2.6 KB
- 参考文档README.ja.md2.3 KB
- 参考文档README.ko.md2.3 KB
- 参考文档README.md2.3 KB
- 参考文档README.zh.md2.4 KB
- 参考文档references/port-allocation.md3.5 KB
- 参考文档references/preconditions.md3.7 KB
- 脚本scripts/_lib.sh6.2 KB
- 脚本scripts/audit-docker-stacks.sh2.4 KB
- 脚本scripts/setup-docker-ports.sh10.7 KB
- 脚本scripts/teardown-docker.sh2.9 KB
03 SKILL.md 正文
ywc-docker-isolate
Announce at start: "I'm using the ywc-docker-isolate skill to isolate this worktree's Docker host ports."
Deterministic, per-worktree Docker host-port isolation for parallel Git worktree
development. Each worktree derives a unique port block purely from its task
name — no central registry, no runtime coordination — and writes it to a
worktree-local env-file plus a .ywc-docker-ports persist file. The committed
compose / env-file is never mutated (per-worktree namespacing, not save/restore).
The deterministic engine lives in bundled scripts; this skill is the one-line
interface to them.
Rationalization Defense
When tempted to skip a step, check this table first:
| Excuse | Reality |
|---|---|
| "Only one worktree is active right now — isolation is unnecessary" | Isolation is unconditional in the executor hook. A second worktree may start at any time, and the deterministic block is what guarantees they never collide. Run setup for every task worktree. |
"Just edit the compose ports: / committed .env to free the port" |
The original compose and committed env-file are immutable (NFR-1). Isolation writes only a worktree-local env-file managed block + .ywc-docker-ports; mutating tracked files pollutes git diff and breaks the other worktrees. |
"ss is enough to check whether a port is free" |
ss is Linux-only and absent on macOS. Port checks go through the cross-platform check_port_in_use (ss→lsof→netstat, fail-safe when none exist) — never call ss directly. |
| "Re-running setup can just re-compute the hash to get the same ports" | Reproducibility (AC2) comes from reading back .ywc-docker-ports, not from re-hashing. A re-hash would drift if an external process transiently held a port. Always read back the persist file; re-hash only on first allocation. |
"audit returned exit 0, so there are no leftover stacks" |
audit exit is always 0 — residual stacks are signalled by non-empty stdout, not the exit code. Parse stdout; never gate on the audit exit code. |
| "A leftover stack from a prior run is harmless — proceed" | A stale ywc-<task>_* stack occupies the same deterministic port the next run derives, so resume is guaranteed to collide. Pre-flight audit must fail-loud (or --prune) before setup. |
Modes
The deterministic logic is in scripts/ — invoke it with a single line per mode.
The CLI contract (arguments, writes, exit codes) is authoritative and is what
ywc-parallel-executor integrates against.
setup — allocate and apply the port block
bash "${CLAUDE_SKILL_DIR}/scripts/setup-docker-ports.sh" \
--task-name <task> --worktree-path <dir> [--compose-file <file>] [--port-vars VAR1,VAR2]
- Writes a worktree-local env-file managed block (
COMPOSE_PROJECT_NAME=ywc-<sanitized-task>+ each*_PORT) and the.ywc-docker-portspersist file. - Stdout: the resolved port map (
COMPOSE_PROJECT_NAME+VAR=portlines). - Exit 0 = isolation applied, or no-op (no compose → "no docker — skipping isolation"). Exit 1 = ports hardcoded (cannot isolate) / salt chain exhausted / corrupt persist / squatter live-check / sanitize-empty.
- Re-run on the same worktree reads back
.ywc-docker-ports(deterministic, AC2) and live-checks every port before returning — a squatted port fails loud (AC13).
teardown — remove only this worktree's stack
bash "${CLAUDE_SKILL_DIR}/scripts/teardown-docker.sh" \
(--task-name <task> | --project-name <proj>) --worktree-path <dir> [--keep-volumes]
- Runs
docker compose -p <project> down --volumes(default;--keep-volumespreserves data), idempotent (exit 0 even with no running stack), deletes.ywc-docker-portson success. - Exit 0 = teardown verified / nothing to do. Exit 1 =
compose downfailed (LEAKED_DOCKER_STACKmarker, wave non-blocking) or sanitize/malformed project (SANITIZE_ERRORmarker, wave blocking). Both markers are written to stderr — distinguish the two by the marker string, not the exit code.
audit — report leftover stacks for expected tasks
bash "${CLAUDE_SKILL_DIR}/scripts/audit-docker-stacks.sh" \
--expect <task1,task2,...> [--prune]
- Detects residual
ywc-<task>stacks. Stdout non-empty = residual present (each lineRESIDUAL_DOCKER_STACK: <project> (<n> container(s))); exit is always 0. --prunetears residual stacks down (down --volumes) and confirms each on stdout (pruned residual stack: <project>). Without--prune, the caller (parallel-executor Pre-flight) must fail-loud and abort the run on any residual. Gate on stdout non-empty only when--pruneis not passed — the prune confirmation lines would otherwise read as residuals.
Integration (ywc-parallel-executor)
One-line pointers only (no inline prose in the executor body):
- Pre-flight (after worktree audit):
audit --expect <wave tasks>— non-empty stdout → abort run with the printed stacks +--pruneremediation. - Step 4a (after 4a-verify, per task):
setup --task-name <t> --worktree-path <wt>— exit 1 → task BLOCKED + worktree preserved, wave continues. - Step 4g (before
cleanup-worktree.sh, inside the 4e-DONE loop):teardown --task-name <t> --worktree-path <wt>— preserved (BLOCKED) worktrees skip 4g, so teardown is skipped automatically.
Common Mistakes
- Calling
ssdirectly instead of the cross-platform helper — breaks on macOS. - Gating on the
auditexit code instead of stdout non-empty — misses every residual stack. - Re-hashing on re-run instead of reading back
.ywc-docker-ports— breaks AC2 determinism under transient external port use. - Placing the teardown pointer outside the 4e-DONE loop — would tear down BLOCKED-preserved worktrees.
- Writing isolation values into the committed compose/env-file instead of the worktree-local env-file managed block — pollutes
git diff(NFR-1).
Validation
bash -nclean on allscripts/*.sh.setuptwice with the same--task-nameyields an identical port map (AC2).- Three distinct task names yield three distinct port blocks and
COMPOSE_PROJECT_NAMEvalues (AC1). validate_ywc_skills.pyPASS; README locale set (.md/.en.md/.ja.md/.ko.md) present.
References
Action required before running
setup: Read references/port-allocation.md for the hash formula,var_indexsort rule, salt chain, modulo bias, and the AC2 determinism guarantee.
Action required before running
setup: Read references/preconditions.md for compose detection, env-var mapping limits (short vs long syntax), the YAML parser priority, the platform port-check tool table, and the env-file vs shell-export precedence.
04 同仓库更多 Skills
missing-frontmatter
暂无简介
malformed-frontmatter
暂无简介
fixture-501-fail
(ywc) Use when aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa Do not use for x.
fixture-500-pass
(ywc) Use when aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa aaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa Do not use for x.
ywc-worktrees
(ywc) Use when creating, auditing, pruning, or resolving git worktrees for isolated task workspaces, whether delegated from an executor or used standalone. Triggers: "worktree 생성", "worktree audit", "worktree 정리", "worktree prune", "ywc-worktrees", "create worktree". Do not use for branch creation/deletion alone, PR creation (use ywc-create-pr), CI or merge delivery (use ywc-finish-branch), task orchestration (use ywc-sequential-executor or ywc-parallel-executor), or non-git isolation.
ywc-wayfinder
(ywc) Use when a large or uncertain change needs multi-session discovery with a deterministic local map and exactly one active ticket before planning or implementation. Triggers: "wayfinder", "길찾기", "discovery map", "multi-session discovery", "탐색 ticket", "経路整理", "探索マップ", "ywc-wayfinder". Do not use for ordinary planning (use ywc-plan), idea clarification (use ywc-brainstorm), direct implementation, or tracker/database writes outside the local Markdown map.