[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M7C1SF1JSWHPJDVGE3Q2CFZ5":3,"skill-same:01M7C1SF1JSWHPJDVGE3Q2CFZ5":44},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":15,"categories":16,"keywords":17,"publishedAt":18,"linkOnly":19,"markdownContent":20,"markdownBody":21,"frontMatter":22,"refName":23,"commitSha":24,"skillDirectory":25,"forksCount":26,"repositoryHtmlUrl":27,"repositoryHomepageUrl":6,"ownerHtmlUrl":28,"ownerBlogUrl":6,"ownerDescription":6,"updatedAt":29,"install":30,"resources":43},"01M7C1SF1JSWHPJDVGE3Q2CFZ5","use-worktrees",null,"Use when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback","zak-keown\u002Fmoe","zak-keown","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F320717241?v=4","01M7BZFXME0NW6TQX0H7AZM2KS","01M7BZFXN32VR0JN5AATRD53H4",0,"Apache-2.0","https:\u002F\u002Fgithub.com\u002Fzak-keown\u002Fmoe\u002Fblob\u002Fmain\u002Fplugins\u002Fmoe\u002F.pi\u002Fskills\u002Fuse-worktrees\u002FSKILL.md",[],[],"2026-11-15 14:19:17",false,"---\nname: use-worktrees\ndescription: Use when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback\n---\n\n# Using Git Worktrees\n\n## Overview\n\nEnsure work happens in an isolated workspace. Prefer your platform's native worktree tools. Fall back to manual git worktrees only when no native tool is available.\n\n**Core principle:** Identify the work lifecycle and pin its base first. Then\ndetect existing isolation, use native tools, or fall back to git. Never let the\ncaller's current `HEAD` choose a new branch's base implicitly.\n\n**Announce at start:** \"I'm using the use-worktrees skill to set up an isolated workspace.\"\n\n## Lifecycle Gate (before Step 0)\n\nBefore inspecting the checkout, establish four values:\n\n- `WORKSPACE_ID` — stable identity for this project, feature, or plan;\n- `WORK_MODE` — `new` or `continue`;\n- `BASE_BRANCH` — the branch this work must eventually merge into; and\n- `BASE_SHA` — the verified commit from which a new worktree must fork.\n\nThe plan or calling workflow should provide these values. For new work with no\ndeclared base, resolve the repository's configured default branch and confirm it\nwith your human partner before creating anything. Then resolve the commit:\n\n```bash\nBASE_SHA=$(git rev-parse \"${BASE_BRANCH}^{commit}\")\n```\n\nRecord `WORKSPACE_ID`, `BASE_BRANCH`, and `BASE_SHA` in the plan ledger or other\ndurable workflow state. A branch name alone can move; a SHA alone does not\npreserve merge intent.\n\n`WORK_MODE=continue` is an explicit continuation declaration. It must name the\nexpected existing work branch or detached workspace. Never infer continuation\nmerely because the current directory is a linked worktree.\n\n## Step 0: Detect Existing Isolation\n\n**Before creating anything, check if you are already in an isolated workspace.**\n\n```bash\nGIT_DIR=$(cd \"$(git rev-parse --git-dir)\" 2>\u002Fdev\u002Fnull && pwd -P)\nGIT_COMMON=$(cd \"$(git rev-parse --git-common-dir)\" 2>\u002Fdev\u002Fnull && pwd -P)\nBRANCH=$(git branch --show-current)\n```\n\n**Submodule guard:** `GIT_DIR != GIT_COMMON` is also true inside git submodules. Before concluding \"already in a worktree,\" verify you are not in a submodule:\n\n```bash\n# If this returns a path, you're in a submodule, not a worktree — treat as normal repo\ngit rev-parse --show-superproject-working-tree 2>\u002Fdev\u002Fnull\n```\n\n**If `GIT_DIR != GIT_COMMON` (and not a submodule):** You are already in a\nlinked worktree. Reuse it only when `WORK_MODE=continue` and its branch\u002Fworkspace\nmatches `WORKSPACE_ID`'s recorded state. Verify that `BASE_SHA` is the recorded\nbase (or an ancestor when the base branch has advanced).\n\nFor `WORK_MODE=new`, or when the recorded identity does not match, this is an\nunrelated linked worktree. Do not reuse it and do not branch from its `HEAD`.\nCreate the new workspace from the repository's main checkout using the pinned\n`BASE_SHA` in Step 1.\n\nReport with branch state:\n- On a branch: \"Already in isolated workspace at `\u003Cpath>` on branch `\u003Cname>`.\"\n- Detached HEAD: \"Already in isolated workspace at `\u003Cpath>` (detached HEAD, externally managed). Branch creation needed at finish time.\"\n\n**If `GIT_DIR == GIT_COMMON` (or in a submodule):** You are in a normal repo checkout.\n\nHas the user already indicated their worktree preference in your instructions? If not, ask for consent before creating a worktree:\n\n> \"Would you like me to set up an isolated worktree? It protects your current branch from changes.\"\n\nHonor any existing declared preference without asking. If the user declines consent, work in place and skip to Step 2.\n\n## Step 1: Create Isolated Workspace\n\n**Choose the branch name first, then try the two creation mechanisms in order.**\n\n### 1a. Branch Name\n\nA native worktree tool and the git fallback both need the work branch name.\nDerive it before creating either workspace.\n\nFor repos on any other forge, use whatever convention that repo's `CONTRIBUTING`\nor `CODEOWNERS` documents; if there is none, `feature\u002F\u003Cslug>` is a safe default.\n\n### 1b. Native Worktree Tools (preferred)\n\nThe user has asked for an isolated workspace (Step 0 consent). Do you already\nhave a way to create a worktree? It might be a tool with a name like\n`EnterWorktree`, `WorktreeCreate`, a `\u002Fworktree` command, or a `--worktree`\nflag. **In this repo, use `moe jig worktree create \u003Cbranch> [--base \u003Cref>]`** —\nit handles placement in `.moe\u002Fworktrees\u002F`, gitignore, and lineage verification.\nIf you have a native tool, use it and skip to Step 2.\n\nNative tools handle directory placement, branch creation, and cleanup\nautomatically, but they do not get to choose lineage. Pass `BASE_SHA` when the\ntool accepts a base. If it only branches from the caller's `HEAD`, invoke it\nonly from a checkout whose `HEAD` equals `BASE_SHA`, then verify the created\nworkspace's merge base. If neither is possible, do not silently stack the new\nwork on the current branch; use the git fallback or report that the harness\ncannot create the requested workspace safely.\n\nOnly proceed to Step 1c if you have no usable native worktree tool available.\n\n### 1c. Git Worktree Fallback\n\n**Only use this if Step 1b does not apply** — you have no native worktree tool available. Create a worktree manually using git.\n\n#### Directory Selection\n\nResolve the primary checkout from the common Git directory so directory\nselection does not happen inside an unrelated linked worktree:\n\n```bash\nPRIMARY_ROOT=$(git -C \"$GIT_COMMON\u002F..\" rev-parse --show-toplevel)\n```\n\nFollow this priority order under `PRIMARY_ROOT`. Explicit user preference\nalways beats observed filesystem state.\n\n1. **Check your instructions for a declared worktree directory preference.** If the user has already specified one, use it without asking.\n\n2. **Check for an existing project-local worktree directory:**\n   ```bash\n   ls -d \"$PRIMARY_ROOT\u002F.moe\u002Fworktrees\" 2>\u002Fdev\u002Fnull # Preferred\n   ls -d \"$PRIMARY_ROOT\u002F.worktrees\" 2>\u002Fdev\u002Fnull     # Legacy\n   ls -d \"$PRIMARY_ROOT\u002Fworktrees\" 2>\u002Fdev\u002Fnull      # Alternative\n   ```\n   If found, use the first match. `.moe\u002Fworktrees` wins over `.worktrees` wins over `worktrees`.\n\n3. **If there is no other guidance available**, default to `.moe\u002Fworktrees\u002F` at the project root.\n\n#### Safety Verification (project-local directories only)\n\n**MUST verify directory is ignored before creating worktree:**\n\n```bash\ngit -C \"$PRIMARY_ROOT\" check-ignore -q .moe\u002Fworktrees 2>\u002Fdev\u002Fnull ||\n  git -C \"$PRIMARY_ROOT\" check-ignore -q .worktrees 2>\u002Fdev\u002Fnull ||\n  git -C \"$PRIMARY_ROOT\" check-ignore -q worktrees 2>\u002Fdev\u002Fnull\n```\n\n**If NOT ignored:** Add to .gitignore, commit the change, then proceed.\n\n**Why critical:** Prevents accidentally committing worktree contents to repository.\n\n#### Create the Worktree\n\n```bash\n# Determine path based on chosen location\npath=\"$LOCATION\u002F$BRANCH_NAME\"\n\ngit -C \"$PRIMARY_ROOT\" worktree add \"$path\" -b \"$BRANCH_NAME\" \"$BASE_SHA\"\ncd \"$path\"\n\ntest \"$(git merge-base HEAD \"$BASE_SHA\")\" = \"$BASE_SHA\"\n```\n\n**Sandbox fallback:** If `git worktree add` fails with a permission error (sandbox denial), tell the user the sandbox blocked worktree creation and you're working in the current directory instead. Then run setup and baseline tests in place.\n\n### 1d. One Worktree Per Parallel Worker\n\nWhen dispatching parallel implementer subagents per the worktree gate\n(`dispatch-agents`, \"The gate\"), each concurrent worker gets its\nOWN linked worktree. Two workers writing into one checkout defeats the\nisolation the gate is built on and reintroduces the exact `(conflicts)`\nhazard the parallel-implementation ban was rooted in.\n\nFor each worker, follow Step 1b first — use the harness's native worktree tool\nwhen one is available, per the \"never fight the harness\" rule. Only fall back\nto `git worktree add` (Step 1c) when no native tool is offered. Whichever path\nyou take, create the worktree BEFORE dispatch: the worker's brief hands it a\nconcrete path to `cd` into, not an instruction to make one for itself.\n\nEach parallel worker's worktree branches from ONE recorded base SHA shared\nacross the wave (see `sdd` \"Wave grouping\" and\n`dispatch-agents` \"The divergent-tree rule\"). A worker branched\nfrom a stale base will cite the same file coordinates as its siblings but\nread different content there. Recording the base once, before the wave\ndispatches, is the safeguard.\n\nCreate every worktree first, then validate the complete set before dispatching\nany worker. **In this repo, use `moe jig worktree create` per worker and\n`moe jig worktree validate \u003Cpath1> \u003Cpath2> ...` to check the set.** Without\njig, verify manually:\n\n```bash\ngit -C \"$worker_cwd\" rev-parse --path-format=absolute --git-dir\ngit -C \"$worker_cwd\" rev-parse --path-format=absolute --git-common-dir\n```\n\nFor every worker, the resolved Git directory must differ from the resolved\ncommon directory; that proves the cwd is a linked worktree rather than the main\ncheckout. The resolved paths must also be pairwise-unique linked Git directories\nacross the wave; comparing cwd strings is not enough because two aliases or\nsymlinks can name the same checkout.\n\nParallel implementation has exactly two rungs: (1) worktree-isolated parallel\ndispatch after the complete set passes validation, then (2) sequential dispatch\nof the entire wave. If native creation, `git worktree add`, or any validation\ncommand fails for even one worker, use rung two from the controller's current,\nvalidated tree. Do not dispatch the valid subset in parallel, and never fall\nback to parallel dispatch without isolation.\n\n## Step 2: Project Setup\n\nAuto-detect and run appropriate setup:\n\n```bash\n# Node.js\nif [ -f package.json ]; then npm install; fi\n\n# Rust\nif [ -f Cargo.toml ]; then cargo build; fi\n\n# Python\nif [ -f requirements.txt ]; then pip install -r requirements.txt; fi\nif [ -f pyproject.toml ]; then poetry install; fi\n\n# Go\nif [ -f go.mod ]; then go mod download; fi\n```\n\n## Step 3: Verify Clean Baseline\n\nRun tests to ensure workspace starts clean:\n\n```bash\n# Use project-appropriate command\nnpm test \u002F cargo test \u002F pytest \u002F go test .\u002F...\n```\n\n**If tests fail:** Report failures, ask whether to proceed or investigate.\n\n**If tests pass:** Report ready.\n\n### Report\n\n```\nWorktree ready at \u003Cfull-path>\nTests passing (\u003CN> tests, 0 failures)\nReady to implement \u003Cfeature-name>\n```\n\n## Quick Reference\n\n| Situation | Action |\n|-----------|--------|\n| New work | Record `WORKSPACE_ID`, `BASE_BRANCH`, and `BASE_SHA` before inspecting isolation |\n| Matching linked worktree + explicit continuation | Reuse it after verifying recorded identity and base |\n| Unrelated linked worktree | Never reuse its branch or implicit `HEAD` |\n| In a submodule | Treat as normal repo (Step 0 guard) |\n| Branch name needed (any path) | Derive per Step 1a |\n| Native worktree tool available | Use it with the pinned base (Step 1b) |\n| No usable native tool | Git worktree fallback (Step 1c) |\n| Parallel worker dispatch | Validate pairwise-unique linked Git dirs for every worker (Step 1d) |\n| Any parallel worktree setup failure | Dispatch the entire wave sequentially (Step 1d) |\n| `.moe\u002Fworktrees\u002F` exists | Use it (verify ignored) |\n| `.worktrees\u002F` exists | Use it — legacy (verify ignored) |\n| `worktrees\u002F` exists | Use it (verify ignored) |\n| Multiple exist | `.moe\u002Fworktrees\u002F` wins over `.worktrees\u002F` wins over `worktrees\u002F` |\n| None exists | Check instruction file, then default `.moe\u002Fworktrees\u002F` |\n| Directory not ignored | Add to .gitignore + commit |\n| Permission error on create | Sandbox fallback, work in place |\n| Tests fail during baseline | Report failures + ask |\n| No package.json\u002FCargo.toml | Skip dependency install |\n\n## Common Rationalizations\n\n| Excuse | Reality |\n|--------|---------|\n| \"I'm obviously not in a worktree — no need to check\" | Run Step 0. Harness-created isolation and submodules both fool eyeballing; the detection commands settle it. |\n| \"`git worktree add` is quicker than hunting for a native tool\" | A native tool (e.g. `EnterWorktree`) owns placement, branching, and cleanup. Bypassing it is the #1 mistake — it creates phantom state your harness can't see or manage. |\n| \"The worktree directory is surely ignored already\" | Run `git check-ignore`. An unignored worktree directory commits the whole tree into the repo. |\n| \"Any directory name works\" | Explicit instructions beat an existing project-local directory, which beats the `.moe\u002Fworktrees\u002F` default. |\n| \"The workspace is fresh — baseline tests can wait\" | A dirty baseline makes every later failure ambiguous. Run the tests now; proceeding past failures is your human partner's call. |\n","# Using Git Worktrees\n\n## Overview\n\nEnsure work happens in an isolated workspace. Prefer your platform's native worktree tools. Fall back to manual git worktrees only when no native tool is available.\n\n**Core principle:** Identify the work lifecycle and pin its base first. Then\ndetect existing isolation, use native tools, or fall back to git. Never let the\ncaller's current `HEAD` choose a new branch's base implicitly.\n\n**Announce at start:** \"I'm using the use-worktrees skill to set up an isolated workspace.\"\n\n## Lifecycle Gate (before Step 0)\n\nBefore inspecting the checkout, establish four values:\n\n- `WORKSPACE_ID` — stable identity for this project, feature, or plan;\n- `WORK_MODE` — `new` or `continue`;\n- `BASE_BRANCH` — the branch this work must eventually merge into; and\n- `BASE_SHA` — the verified commit from which a new worktree must fork.\n\nThe plan or calling workflow should provide these values. For new work with no\ndeclared base, resolve the repository's configured default branch and confirm it\nwith your human partner before creating anything. Then resolve the commit:\n\n```bash\nBASE_SHA=$(git rev-parse \"${BASE_BRANCH}^{commit}\")\n```\n\nRecord `WORKSPACE_ID`, `BASE_BRANCH`, and `BASE_SHA` in the plan ledger or other\ndurable workflow state. A branch name alone can move; a SHA alone does not\npreserve merge intent.\n\n`WORK_MODE=continue` is an explicit continuation declaration. It must name the\nexpected existing work branch or detached workspace. Never infer continuation\nmerely because the current directory is a linked worktree.\n\n## Step 0: Detect Existing Isolation\n\n**Before creating anything, check if you are already in an isolated workspace.**\n\n```bash\nGIT_DIR=$(cd \"$(git rev-parse --git-dir)\" 2>\u002Fdev\u002Fnull && pwd -P)\nGIT_COMMON=$(cd \"$(git rev-parse --git-common-dir)\" 2>\u002Fdev\u002Fnull && pwd -P)\nBRANCH=$(git branch --show-current)\n```\n\n**Submodule guard:** `GIT_DIR != GIT_COMMON` is also true inside git submodules. Before concluding \"already in a worktree,\" verify you are not in a submodule:\n\n```bash\n# If this returns a path, you're in a submodule, not a worktree — treat as normal repo\ngit rev-parse --show-superproject-working-tree 2>\u002Fdev\u002Fnull\n```\n\n**If `GIT_DIR != GIT_COMMON` (and not a submodule):** You are already in a\nlinked worktree. Reuse it only when `WORK_MODE=continue` and its branch\u002Fworkspace\nmatches `WORKSPACE_ID`'s recorded state. Verify that `BASE_SHA` is the recorded\nbase (or an ancestor when the base branch has advanced).\n\nFor `WORK_MODE=new`, or when the recorded identity does not match, this is an\nunrelated linked worktree. Do not reuse it and do not branch from its `HEAD`.\nCreate the new workspace from the repository's main checkout using the pinned\n`BASE_SHA` in Step 1.\n\nReport with branch state:\n- On a branch: \"Already in isolated workspace at `\u003Cpath>` on branch `\u003Cname>`.\"\n- Detached HEAD: \"Already in isolated workspace at `\u003Cpath>` (detached HEAD, externally managed). Branch creation needed at finish time.\"\n\n**If `GIT_DIR == GIT_COMMON` (or in a submodule):** You are in a normal repo checkout.\n\nHas the user already indicated their worktree preference in your instructions? If not, ask for consent before creating a worktree:\n\n> \"Would you like me to set up an isolated worktree? It protects your current branch from changes.\"\n\nHonor any existing declared preference without asking. If the user declines consent, work in place and skip to Step 2.\n\n## Step 1: Create Isolated Workspace\n\n**Choose the branch name first, then try the two creation mechanisms in order.**\n\n### 1a. Branch Name\n\nA native worktree tool and the git fallback both need the work branch name.\nDerive it before creating either workspace.\n\nFor repos on any other forge, use whatever convention that repo's `CONTRIBUTING`\nor `CODEOWNERS` documents; if there is none, `feature\u002F\u003Cslug>` is a safe default.\n\n### 1b. Native Worktree Tools (preferred)\n\nThe user has asked for an isolated workspace (Step 0 consent). Do you already\nhave a way to create a worktree? It might be a tool with a name like\n`EnterWorktree`, `WorktreeCreate`, a `\u002Fworktree` command, or a `--worktree`\nflag. **In this repo, use `moe jig worktree create \u003Cbranch> [--base \u003Cref>]`** —\nit handles placement in `.moe\u002Fworktrees\u002F`, gitignore, and lineage verification.\nIf you have a native tool, use it and skip to Step 2.\n\nNative tools handle directory placement, branch creation, and cleanup\nautomatically, but they do not get to choose lineage. Pass `BASE_SHA` when the\ntool accepts a base. If it only branches from the caller's `HEAD`, invoke it\nonly from a checkout whose `HEAD` equals `BASE_SHA`, then verify the created\nworkspace's merge base. If neither is possible, do not silently stack the new\nwork on the current branch; use the git fallback or report that the harness\ncannot create the requested workspace safely.\n\nOnly proceed to Step 1c if you have no usable native worktree tool available.\n\n### 1c. Git Worktree Fallback\n\n**Only use this if Step 1b does not apply** — you have no native worktree tool available. Create a worktree manually using git.\n\n#### Directory Selection\n\nResolve the primary checkout from the common Git directory so directory\nselection does not happen inside an unrelated linked worktree:\n\n```bash\nPRIMARY_ROOT=$(git -C \"$GIT_COMMON\u002F..\" rev-parse --show-toplevel)\n```\n\nFollow this priority order under `PRIMARY_ROOT`. Explicit user preference\nalways beats observed filesystem state.\n\n1. **Check your instructions for a declared worktree directory preference.** If the user has already specified one, use it without asking.\n\n2. **Check for an existing project-local worktree directory:**\n   ```bash\n   ls -d \"$PRIMARY_ROOT\u002F.moe\u002Fworktrees\" 2>\u002Fdev\u002Fnull # Preferred\n   ls -d \"$PRIMARY_ROOT\u002F.worktrees\" 2>\u002Fdev\u002Fnull     # Legacy\n   ls -d \"$PRIMARY_ROOT\u002Fworktrees\" 2>\u002Fdev\u002Fnull      # Alternative\n   ```\n   If found, use the first match. `.moe\u002Fworktrees` wins over `.worktrees` wins over `worktrees`.\n\n3. **If there is no other guidance available**, default to `.moe\u002Fworktrees\u002F` at the project root.\n\n#### Safety Verification (project-local directories only)\n\n**MUST verify directory is ignored before creating worktree:**\n\n```bash\ngit -C \"$PRIMARY_ROOT\" check-ignore -q .moe\u002Fworktrees 2>\u002Fdev\u002Fnull ||\n  git -C \"$PRIMARY_ROOT\" check-ignore -q .worktrees 2>\u002Fdev\u002Fnull ||\n  git -C \"$PRIMARY_ROOT\" check-ignore -q worktrees 2>\u002Fdev\u002Fnull\n```\n\n**If NOT ignored:** Add to .gitignore, commit the change, then proceed.\n\n**Why critical:** Prevents accidentally committing worktree contents to repository.\n\n#### Create the Worktree\n\n```bash\n# Determine path based on chosen location\npath=\"$LOCATION\u002F$BRANCH_NAME\"\n\ngit -C \"$PRIMARY_ROOT\" worktree add \"$path\" -b \"$BRANCH_NAME\" \"$BASE_SHA\"\ncd \"$path\"\n\ntest \"$(git merge-base HEAD \"$BASE_SHA\")\" = \"$BASE_SHA\"\n```\n\n**Sandbox fallback:** If `git worktree add` fails with a permission error (sandbox denial), tell the user the sandbox blocked worktree creation and you're working in the current directory instead. Then run setup and baseline tests in place.\n\n### 1d. One Worktree Per Parallel Worker\n\nWhen dispatching parallel implementer subagents per the worktree gate\n(`dispatch-agents`, \"The gate\"), each concurrent worker gets its\nOWN linked worktree. Two workers writing into one checkout defeats the\nisolation the gate is built on and reintroduces the exact `(conflicts)`\nhazard the parallel-implementation ban was rooted in.\n\nFor each worker, follow Step 1b first — use the harness's native worktree tool\nwhen one is available, per the \"never fight the harness\" rule. Only fall back\nto `git worktree add` (Step 1c) when no native tool is offered. Whichever path\nyou take, create the worktree BEFORE dispatch: the worker's brief hands it a\nconcrete path to `cd` into, not an instruction to make one for itself.\n\nEach parallel worker's worktree branches from ONE recorded base SHA shared\nacross the wave (see `sdd` \"Wave grouping\" and\n`dispatch-agents` \"The divergent-tree rule\"). A worker branched\nfrom a stale base will cite the same file coordinates as its siblings but\nread different content there. Recording the base once, before the wave\ndispatches, is the safeguard.\n\nCreate every worktree first, then validate the complete set before dispatching\nany worker. **In this repo, use `moe jig worktree create` per worker and\n`moe jig worktree validate \u003Cpath1> \u003Cpath2> ...` to check the set.** Without\njig, verify manually:\n\n```bash\ngit -C \"$worker_cwd\" rev-parse --path-format=absolute --git-dir\ngit -C \"$worker_cwd\" rev-parse --path-format=absolute --git-common-dir\n```\n\nFor every worker, the resolved Git directory must differ from the resolved\ncommon directory; that proves the cwd is a linked worktree rather than the main\ncheckout. The resolved paths must also be pairwise-unique linked Git directories\nacross the wave; comparing cwd strings is not enough because two aliases or\nsymlinks can name the same checkout.\n\nParallel implementation has exactly two rungs: (1) worktree-isolated parallel\ndispatch after the complete set passes validation, then (2) sequential dispatch\nof the entire wave. If native creation, `git worktree add`, or any validation\ncommand fails for even one worker, use rung two from the controller's current,\nvalidated tree. Do not dispatch the valid subset in parallel, and never fall\nback to parallel dispatch without isolation.\n\n## Step 2: Project Setup\n\nAuto-detect and run appropriate setup:\n\n```bash\n# Node.js\nif [ -f package.json ]; then npm install; fi\n\n# Rust\nif [ -f Cargo.toml ]; then cargo build; fi\n\n# Python\nif [ -f requirements.txt ]; then pip install -r requirements.txt; fi\nif [ -f pyproject.toml ]; then poetry install; fi\n\n# Go\nif [ -f go.mod ]; then go mod download; fi\n```\n\n## Step 3: Verify Clean Baseline\n\nRun tests to ensure workspace starts clean:\n\n```bash\n# Use project-appropriate command\nnpm test \u002F cargo test \u002F pytest \u002F go test .\u002F...\n```\n\n**If tests fail:** Report failures, ask whether to proceed or investigate.\n\n**If tests pass:** Report ready.\n\n### Report\n\n```\nWorktree ready at \u003Cfull-path>\nTests passing (\u003CN> tests, 0 failures)\nReady to implement \u003Cfeature-name>\n```\n\n## Quick Reference\n\n| Situation | Action |\n|-----------|--------|\n| New work | Record `WORKSPACE_ID`, `BASE_BRANCH`, and `BASE_SHA` before inspecting isolation |\n| Matching linked worktree + explicit continuation | Reuse it after verifying recorded identity and base |\n| Unrelated linked worktree | Never reuse its branch or implicit `HEAD` |\n| In a submodule | Treat as normal repo (Step 0 guard) |\n| Branch name needed (any path) | Derive per Step 1a |\n| Native worktree tool available | Use it with the pinned base (Step 1b) |\n| No usable native tool | Git worktree fallback (Step 1c) |\n| Parallel worker dispatch | Validate pairwise-unique linked Git dirs for every worker (Step 1d) |\n| Any parallel worktree setup failure | Dispatch the entire wave sequentially (Step 1d) |\n| `.moe\u002Fworktrees\u002F` exists | Use it (verify ignored) |\n| `.worktrees\u002F` exists | Use it — legacy (verify ignored) |\n| `worktrees\u002F` exists | Use it (verify ignored) |\n| Multiple exist | `.moe\u002Fworktrees\u002F` wins over `.worktrees\u002F` wins over `worktrees\u002F` |\n| None exists | Check instruction file, then default `.moe\u002Fworktrees\u002F` |\n| Directory not ignored | Add to .gitignore + commit |\n| Permission error on create | Sandbox fallback, work in place |\n| Tests fail during baseline | Report failures + ask |\n| No package.json\u002FCargo.toml | Skip dependency install |\n\n## Common Rationalizations\n\n| Excuse | Reality |\n|--------|---------|\n| \"I'm obviously not in a worktree — no need to check\" | Run Step 0. Harness-created isolation and submodules both fool eyeballing; the detection commands settle it. |\n| \"`git worktree add` is quicker than hunting for a native tool\" | A native tool (e.g. `EnterWorktree`) owns placement, branching, and cleanup. Bypassing it is the #1 mistake — it creates phantom state your harness can't see or manage. |\n| \"The worktree directory is surely ignored already\" | Run `git check-ignore`. An unignored worktree directory commits the whole tree into the repo. |\n| \"Any directory name works\" | Explicit instructions beat an existing project-local directory, which beats the `.moe\u002Fworktrees\u002F` default. |\n| \"The workspace is fresh — baseline tests can wait\" | A dirty baseline makes every later failure ambiguous. Run the tests now; proceeding past failures is your human partner's call. |\n",{"name":5,"description":7},"main","728894f3f85fbd4e788f015ddfd72bb6155d5dd5","plugins\u002Fmoe\u002F.pi\u002Fskills\u002Fuse-worktrees",1,"https:\u002F\u002Fgithub.com\u002Fzak-keown\u002Fmoe","https:\u002F\u002Fgithub.com\u002Fzak-keown","2026-09-05 06:29:06",{"source":8,"skillName":5,"commands":31,"prompt":41,"zipAvailable":42},[32,35,38],{"tool":33,"command":34},"npx","npx skills add zak-keown\u002Fmoe --skill use-worktrees",{"tool":36,"command":37},"bunx","bunx skills add zak-keown\u002Fmoe --skill use-worktrees",{"tool":39,"command":40},"pnpm","pnpm dlx skills add zak-keown\u002Fmoe --skill use-worktrees","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fzak-keown\u002Fmoe\u002Fblob\u002Fmain\u002Fplugins\u002Fmoe\u002F.pi\u002Fskills\u002Fuse-worktrees\u002FSKILL.md",true,[],[45,52,59,66,73,80],{"skillNo":46,"name":47,"nameZh":6,"description":48,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":49,"categories":50,"keywords":51,"publishedAt":18},"01M7C1Z5362Y8NVRZ69HWP0ZD0","write-skill","Use when creating new skills, editing existing skills, or verifying skills work before deployment","https:\u002F\u002Fgithub.com\u002Fzak-keown\u002Fmoe\u002Fblob\u002Fmain\u002Fplugins\u002Fmoe\u002Fskills\u002Fwrite-skill\u002FSKILL.md",[],[],{"skillNo":53,"name":54,"nameZh":6,"description":55,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":56,"categories":57,"keywords":58,"publishedAt":18},"01M7C1YZ9966WK9R6ZRPCGWF3G","write-plan","Use when you have a spec or requirements for a multi-step task, before touching code","https:\u002F\u002Fgithub.com\u002Fzak-keown\u002Fmoe\u002Fblob\u002Fmain\u002Fplugins\u002Fmoe\u002Fskills\u002Fwrite-plan\u002FSKILL.md",[],[],{"skillNo":60,"name":61,"nameZh":6,"description":62,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":63,"categories":64,"keywords":65,"publishedAt":18},"01M7C1YMR4SJD7BPBBPXZCVGVH","write-clearly","Apply Strunk's timeless writing rules to ANY prose humans will read—documentation, commit messages, error messages, explanations, reports, or UI text. Makes your writing clearer, stronger, and more professional.","https:\u002F\u002Fgithub.com\u002Fzak-keown\u002Fmoe\u002Fblob\u002Fmain\u002Fplugins\u002Fmoe\u002Fskills\u002Fwrite-clearly\u002FSKILL.md",[],[],{"skillNo":67,"name":68,"nameZh":6,"description":69,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":70,"categories":71,"keywords":72,"publishedAt":18},"01M7C1YH9805YSM0N20VQAVSXF","windows-vm","Create, manage, or connect to a headless Windows 11 VM running in Docker with SSH access. Use when the user wants to spin up, stop, restart, or SSH into a Windows VM.","https:\u002F\u002Fgithub.com\u002Fzak-keown\u002Fmoe\u002Fblob\u002Fmain\u002Fplugins\u002Fmoe\u002Fskills\u002Fwindows-vm\u002FSKILL.md",[],[],{"skillNo":74,"name":75,"nameZh":6,"description":76,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":77,"categories":78,"keywords":79,"publishedAt":18},"01M7C1YD87SCNEJ2C9B8HFR2NQ","verify-completion","Use when about to claim work is complete, fixed, or passing, before committing or creating MRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always","https:\u002F\u002Fgithub.com\u002Fzak-keown\u002Fmoe\u002Fblob\u002Fmain\u002Fplugins\u002Fmoe\u002Fskills\u002Fverify-completion\u002FSKILL.md",[],[],{"skillNo":81,"name":82,"nameZh":6,"description":83,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":6,"repositoryNo":12,"starsCount":13,"licenseSpdxId":14,"licenseFileUrl":6,"sourceHtmlUrl":84,"categories":85,"keywords":86,"publishedAt":18},"01M7C1YARDEHT0TJ9BRG30ZCF4","using-moe","Use when starting any conversation - establishes how to find and use skills, requiring skill invocation before ANY response including clarifying questions","https:\u002F\u002Fgithub.com\u002Fzak-keown\u002Fmoe\u002Fblob\u002Fmain\u002Fplugins\u002Fmoe\u002Fskills\u002Fusing-moe\u002FSKILL.md",[],[]]