[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"skill:01M6CWKBDEZ7QFF1ZH3DP52SHA":3,"skill-same:01M6CWKBDEZ7QFF1ZH3DP52SHA":63},{"skillNo":4,"name":5,"nameZh":6,"description":7,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":16,"categories":17,"keywords":18,"publishedAt":28,"linkOnly":29,"markdownContent":30,"markdownBody":31,"frontMatter":32,"refName":34,"commitSha":35,"skillDirectory":36,"forksCount":37,"repositoryHtmlUrl":38,"repositoryHomepageUrl":39,"ownerHtmlUrl":40,"ownerBlogUrl":6,"ownerDescription":41,"updatedAt":42,"install":43,"resources":56},"01M6CWKBDEZ7QFF1ZH3DP52SHA","spec-worktree",null,"Internal helper for caller-owned git worktree isolation. Governed callers are spec-dogfood and spec-work; every caller must provide the forward invocation and intake contract.","leo-kuang-ai\u002Fspec-first","leo-kuang-ai","https:\u002F\u002Favatars.githubusercontent.com\u002Fu\u002F8476392?v=4","01M6CWDM2YRT5M8C3G3QC3YGR5","leokuang","01M6CWDM6X46EFBXT1M1GDB5XC",111,"MIT","https:\u002F\u002Fgithub.com\u002Fleo-kuang-ai\u002Fspec-first\u002Fblob\u002Fmaster\u002Fskills\u002Fspec-worktree\u002FSKILL.md",[],[19,20,21,22,23,24,25,26,27],"spec","worktree","spec worktree","git","intake","Bash","git worktree","work","dogfood","2026-11-10 10:12:30",false,"---\nname: spec-worktree\ndescription: Internal helper for caller-owned git worktree isolation. Governed callers are spec-dogfood and spec-work; every caller must provide the forward invocation and intake contract.\nuser-invocable: false\nallowed-tools: Bash(bash *worktree-manager.sh*)\n---\n\n# Worktree Isolation\n\nDetect whether the current checkout is already isolated, then create or attach a worktree under `.worktrees\u002F\u003Cslug>` only when isolation is still needed. The bundled script adds branch-specific setup that `git worktree add` alone does not handle:\n\n- Does not copy `.env*` files by default; `--copy-env` is an explicit opt-in for workflows that need local env files\n- Detects `mise`\u002F`direnv` configs and prints review commands without changing user trust state\n- Adds `.worktrees` to `.gitignore` if not already ignored\n- Does not modify the main repo checkout — `from-branch` and PR heads are fetched, not checked out\n\n## Step 0: Detect existing isolation\n\nBefore creating anything, invoke the bundled script with `detect --json` through the same `bash -c` wrapper whose command text includes `exec bash ...worktree-manager.sh`:\n\n```bash\nbash -c 'if [ -n \"${CLAUDE_SKILL_DIR:-}\" ]; then exec bash \"$CLAUDE_SKILL_DIR\u002Fscripts\u002Fworktree-manager.sh\" \"$@\"; fi; exec bash \"$(git rev-parse --show-toplevel)\"\u002F\"skills\u002Fspec-worktree\u002Fscripts\u002Fworktree-manager.sh\" \"$@\"' _ detect --json\n```\n\nThe output is the deterministic facts contract `spec-worktree-detect.v1`:\n\n```json\n{\n  \"schema_version\": \"spec-worktree-detect.v1\",\n  \"state\": \"ordinary-checkout | linked-worktree | submodule | unknown\",\n  \"reason_code\": \"same-git-dir | linked-worktree | submodule-superproject | not-git-repo | git-query-failed | output-contract-failed\",\n  \"worktree_root\": \"\u003Cabsolute path or null>\",\n  \"main_worktree_root\": \"\u003Cabsolute path or null>\",\n  \"git_dir\": \"\u003Cresolved absolute path or null>\",\n  \"common_dir\": \"\u003Cresolved absolute path or null>\",\n  \"branch\": \"\u003Ccurrent branch or null>\"\n}\n```\n\n`state=ordinary-checkout` and `state=submodule` mean creation may proceed if the workflow still needs isolation. For `state=submodule`, the new worktree is created under the submodule's own working tree (`\u003Csubmodule-root>\u002F.worktrees\u002F\u003Cbranch>`), not the superproject. `state=linked-worktree` means the current checkout is already isolated; report `worktree_root` and `branch`, then work in place instead of creating another worktree. `state=unknown` or any non-zero detect exit means stop and report `reason_code`; do not fall back to raw `git worktree add`.\n\nThe script computes this by comparing resolved absolute `--absolute-git-dir` and resolved absolute `--git-common-dir`. Equal paths are an ordinary checkout. Different paths plus non-empty `--show-superproject-working-tree` are a submodule. Different paths plus empty superproject output are an existing linked worktree.\n\n`detect --json` requires `node` on `PATH` to serialize the facts. When `node` is missing the command still prints a parseable `state=unknown`\u002F`reason_code=output-contract-failed` object and exits non-zero, so a consumer always gets a structured reason_code rather than empty output.\n\n## Choose the mode\n\nThere are two modes. The caller must choose one before invoking the script:\n\n- **New work:** create a fresh branch from a base branch. Use this when the task has no existing ref to test or modify.\n- **Isolate an existing ref:** attach a worktree to a PR head, existing branch, tag, or commit. Use this for PR review, dogfood, or any workflow that needs to test a target ref without switching the primary checkout.\n\nA branch can be checked out in only one worktree at a time. In existing-ref mode, if the target branch is already checked out anywhere, the script reports `already_checked_out branch=\u003Cname> path=\u003Cpath>` and exits 0 without creating a second checkout. The caller must act on that verdict: work at the reported path, ask the user, or stop. Never force a duplicate branch checkout.\n\n## Creating a new-work worktree\n\nInvoke the bundled script through a `bash -c` wrapper whose command text includes `exec bash ...worktree-manager.sh`. On Claude Code, `${CLAUDE_SKILL_DIR}` resolves to the skill's own runtime directory across marketplace-cached installs and local plugin development. In source or non-Claude runtime contexts, use the repo-root fallback path so generated Codex assets can rewrite it to the installed skill directory. This shape intentionally matches the narrow `allowed-tools` pattern.\n\n```bash\nbash -c 'if [ -n \"${CLAUDE_SKILL_DIR:-}\" ]; then exec bash \"$CLAUDE_SKILL_DIR\u002Fscripts\u002Fworktree-manager.sh\" \"$@\"; fi; exec bash \"$(git rev-parse --show-toplevel)\"\u002F\"skills\u002Fspec-worktree\u002Fscripts\u002Fworktree-manager.sh\" \"$@\"' _ create [--copy-env] \u003Cbranch-name> [from-branch]\n```\n\nDefaults:\n- `from-branch` defaults to origin's default branch (or `main` if that cannot be resolved)\n- The new branch is created at `origin\u002F\u003Cfrom-branch>` (or the local ref if the remote is unavailable)\n- `.env*` files are not copied unless `--copy-env` is passed\n\nExamples:\n```bash\nbash -c 'if [ -n \"${CLAUDE_SKILL_DIR:-}\" ]; then exec bash \"$CLAUDE_SKILL_DIR\u002Fscripts\u002Fworktree-manager.sh\" \"$@\"; fi; exec bash \"$(git rev-parse --show-toplevel)\"\u002F\"skills\u002Fspec-worktree\u002Fscripts\u002Fworktree-manager.sh\" \"$@\"' _ create feat\u002Flogin\nbash -c 'if [ -n \"${CLAUDE_SKILL_DIR:-}\" ]; then exec bash \"$CLAUDE_SKILL_DIR\u002Fscripts\u002Fworktree-manager.sh\" \"$@\"; fi; exec bash \"$(git rev-parse --show-toplevel)\"\u002F\"skills\u002Fspec-worktree\u002Fscripts\u002Fworktree-manager.sh\" \"$@\"' _ create fix\u002Femail-validation develop\nbash -c 'if [ -n \"${CLAUDE_SKILL_DIR:-}\" ]; then exec bash \"$CLAUDE_SKILL_DIR\u002Fscripts\u002Fworktree-manager.sh\" \"$@\"; fi; exec bash \"$(git rev-parse --show-toplevel)\"\u002F\"skills\u002Fspec-worktree\u002Fscripts\u002Fworktree-manager.sh\" \"$@\"' _ create --copy-env feat\u002Flocal-env\n```\n\nAfter creation, switch to the worktree with `cd .worktrees\u002F\u003Cbranch-name>`.\n\nThe `create` command consumes the same detection function before creating `.worktrees\u002F\u003Cbranch>` or running `git worktree add`. It refuses `linked-worktree`, `unknown`, `not-git-repo`, `git-query-failed`, and `output-contract-failed` states so this helper cannot create nested or invisible worktrees by bypassing Step 0.\n\n## Isolating an existing ref\n\nInvoke `isolate` when the caller names a target ref that already exists:\n\n```bash\nbash -c 'if [ -n \"${CLAUDE_SKILL_DIR:-}\" ]; then exec bash \"$CLAUDE_SKILL_DIR\u002Fscripts\u002Fworktree-manager.sh\" \"$@\"; fi; exec bash \"$(git rev-parse --show-toplevel)\"\u002F\"skills\u002Fspec-worktree\u002Fscripts\u002Fworktree-manager.sh\" \"$@\"' _ isolate [--copy-env] \u003Ctarget-ref|pr:\u003Cnumber>|#\u003Cnumber>> [worktree-slug]\n```\n\nExamples:\n\n```bash\nbash -c 'if [ -n \"${CLAUDE_SKILL_DIR:-}\" ]; then exec bash \"$CLAUDE_SKILL_DIR\u002Fscripts\u002Fworktree-manager.sh\" \"$@\"; fi; exec bash \"$(git rev-parse --show-toplevel)\"\u002F\"skills\u002Fspec-worktree\u002Fscripts\u002Fworktree-manager.sh\" \"$@\"' _ isolate feature\u002Flogin\nbash -c 'if [ -n \"${CLAUDE_SKILL_DIR:-}\" ]; then exec bash \"$CLAUDE_SKILL_DIR\u002Fscripts\u002Fworktree-manager.sh\" \"$@\"; fi; exec bash \"$(git rev-parse --show-toplevel)\"\u002F\"skills\u002Fspec-worktree\u002Fscripts\u002Fworktree-manager.sh\" \"$@\"' _ isolate pr:123\nbash -c 'if [ -n \"${CLAUDE_SKILL_DIR:-}\" ]; then exec bash \"$CLAUDE_SKILL_DIR\u002Fscripts\u002Fworktree-manager.sh\" \"$@\"; fi; exec bash \"$(git rev-parse --show-toplevel)\"\u002F\"skills\u002Fspec-worktree\u002Fscripts\u002Fworktree-manager.sh\" \"$@\"' _ isolate '#123' pr-123\n```\n\nBehavior:\n\n- Existing local branch: `git worktree add .worktrees\u002F\u003Cslug> \u003Cbranch>`.\n- Remote-only `origin\u002F\u003Cbranch>`: create a local branch in the new worktree from `origin\u002F\u003Cbranch>`.\n- PR shorthand `pr:\u003Cnumber>` or `#\u003Cnumber>`: fetch `pull\u002F\u003Cnumber>\u002Fhead` into local branch `pr-\u003Cnumber>`, then attach the worktree to that branch so fix commits are not orphaned on `FETCH_HEAD`.\n- Tag or commit: create a detached worktree at that commit.\n- Already in a linked worktree: check the target out in place unless it is already the current branch; do not create a nested worktree.\n- Target branch already checked out elsewhere: report `already_checked_out branch=\u003Cname> path=\u003Cpath>` and do not create a second checkout.\n\n## Env File Opt-In\n\nUse `--copy-env` only when the workflow explicitly needs local environment files in the new worktree. The opt-in path works for both `create` and `isolate`: it copies `.env*` files except `.env.example`, `.env.template`, and `.env.sample`, prints only file names, backs up pre-existing destination files, and appends an owner-only `.env-copy.log` containing only timestamp, basename, and byte size. The log contains no absolute path, content-derived hash, or file contents and is added to the worktree git exclude file.\n\nEven when env files were copied intentionally, downstream staging must still treat them as denied by default. A batch may stage an env file only when the task\u002Fimplementation unit declares the exact env path in `expected_side_effects` and explicitly states that changing that env file is intended.\n\n## Other worktree operations\n\nUse `git` directly — no wrapper is needed and none is provided:\n\n```bash\ngit worktree list                          # list worktrees\ngit worktree remove .worktrees\u002F\u003Cbranch>    # remove a worktree\ncd .worktrees\u002F\u003Cbranch>                     # switch to a worktree\ncd \"$(git rev-parse --show-toplevel)\"      # return to main checkout\n```\n\nDo not manually copy `.env*` files as a default setup step. If an existing worktree needs env files, recreate it with `--copy-env` or copy files manually only after a human explicitly opts in and records the same file-name-only audit information.\n\n## Dev tool trust behavior\n\nTrust stores are user-owned state outside the worktree contract. When mise or direnv configs are present, the script only prints the exact `mise trust \u003Cfile>` or `direnv allow` command and tells the user to review the worktree content first. It never executes either command, even when the config matches a trusted branch; worktree creation success does not imply trust approval.\n\n## When to create a worktree\n\nCreate a worktree when:\n- Reviewing a PR while keeping the main checkout free for other work\n- Running multiple features in parallel without branch-switching overhead\n- Keeping the default branch free of in-progress state\n\nDo not create a new-work worktree for single-task work that can happen on a branch in the main checkout, and never create a nested worktree when Step 0 reports `state=linked-worktree`. For existing-ref isolation, use `isolate` so branch uniqueness and already-checked-out verdicts remain deterministic.\n\n## Integration\n\nThis helper accepts only a caller-owned isolation contract: caller identity, target repo, target ref or new branch, reason isolation is needed, allowed setup side effects, environment-copy authorization, and the return path consumer. It detects or creates the worktree and returns facts. It never selects an execution engine, dispatches a worker, stages, commits, pushes, opens a PR, or decides cleanup. A worker placed in a linked worktree is edit-and-test only: it must not run `git add`, `git commit`, or any command that writes the shared Git index. A worker sandbox `EPERM` is evidence about that worker only, not host capability evidence.\n\n`spec-dogfood` uses existing-ref mode for a PR or non-current branch: `isolate pr:\u003Cnumber>` or `isolate \u003Cbranch>`. It consumes `Worktree ready: \u003Cpath>` or `already_checked_out branch=\u003Cname> path=\u003Cpath>` without switching the primary checkout.\n\n`spec-work` may use new-work or existing-ref mode only after `execution-strategy.md` has locked one target repo and recorded mutation authorization. It owns all implementation and recovery state outside this helper. A linked worktree does not enforce Git-index isolation: before a mutation-capable worker starts, the caller still needs a host receipt that denies writes to the exact Git common directory\u002Findex path and filters credential environment. Without it, use `worker_git_index_enforcement_unavailable`, do not dispatch that worker, and continue inline\u002Fserial. The returned worktree root becomes the snapshot `worktree_identity.repo_root`; any later identity drift routes back to `spec-work` as `run-source-drifted` rather than causing this helper to recreate, reset, or rerun work.\n\n未来 caller 必须先在其 public owner source 中增加 forward invocation 与 intake contract。本 helper 的 reverse claim 不能单独建立 integration edge。\n\n## Troubleshooting\n\n**\"Worktree already exists\"**: the path is already in use. Either switch to it (`cd .worktrees\u002F\u003Cbranch>`) or remove it (`git worktree remove .worktrees\u002F\u003Cbranch>`) before recreating.\n\n**\"Cannot remove worktree: it is the current worktree\"**: `cd` out of the worktree first, then `git worktree remove`.\n\n**Dev tool trust was skipped**: the script prints the manual command. Review the config diff (`git diff \u003Cbase-ref> -- .envrc`), then run the printed command from the worktree directory.\n","# Worktree Isolation\n\nDetect whether the current checkout is already isolated, then create or attach a worktree under `.worktrees\u002F\u003Cslug>` only when isolation is still needed. The bundled script adds branch-specific setup that `git worktree add` alone does not handle:\n\n- Does not copy `.env*` files by default; `--copy-env` is an explicit opt-in for workflows that need local env files\n- Detects `mise`\u002F`direnv` configs and prints review commands without changing user trust state\n- Adds `.worktrees` to `.gitignore` if not already ignored\n- Does not modify the main repo checkout — `from-branch` and PR heads are fetched, not checked out\n\n## Step 0: Detect existing isolation\n\nBefore creating anything, invoke the bundled script with `detect --json` through the same `bash -c` wrapper whose command text includes `exec bash ...worktree-manager.sh`:\n\n```bash\nbash -c 'if [ -n \"${CLAUDE_SKILL_DIR:-}\" ]; then exec bash \"$CLAUDE_SKILL_DIR\u002Fscripts\u002Fworktree-manager.sh\" \"$@\"; fi; exec bash \"$(git rev-parse --show-toplevel)\"\u002F\"skills\u002Fspec-worktree\u002Fscripts\u002Fworktree-manager.sh\" \"$@\"' _ detect --json\n```\n\nThe output is the deterministic facts contract `spec-worktree-detect.v1`:\n\n```json\n{\n  \"schema_version\": \"spec-worktree-detect.v1\",\n  \"state\": \"ordinary-checkout | linked-worktree | submodule | unknown\",\n  \"reason_code\": \"same-git-dir | linked-worktree | submodule-superproject | not-git-repo | git-query-failed | output-contract-failed\",\n  \"worktree_root\": \"\u003Cabsolute path or null>\",\n  \"main_worktree_root\": \"\u003Cabsolute path or null>\",\n  \"git_dir\": \"\u003Cresolved absolute path or null>\",\n  \"common_dir\": \"\u003Cresolved absolute path or null>\",\n  \"branch\": \"\u003Ccurrent branch or null>\"\n}\n```\n\n`state=ordinary-checkout` and `state=submodule` mean creation may proceed if the workflow still needs isolation. For `state=submodule`, the new worktree is created under the submodule's own working tree (`\u003Csubmodule-root>\u002F.worktrees\u002F\u003Cbranch>`), not the superproject. `state=linked-worktree` means the current checkout is already isolated; report `worktree_root` and `branch`, then work in place instead of creating another worktree. `state=unknown` or any non-zero detect exit means stop and report `reason_code`; do not fall back to raw `git worktree add`.\n\nThe script computes this by comparing resolved absolute `--absolute-git-dir` and resolved absolute `--git-common-dir`. Equal paths are an ordinary checkout. Different paths plus non-empty `--show-superproject-working-tree` are a submodule. Different paths plus empty superproject output are an existing linked worktree.\n\n`detect --json` requires `node` on `PATH` to serialize the facts. When `node` is missing the command still prints a parseable `state=unknown`\u002F`reason_code=output-contract-failed` object and exits non-zero, so a consumer always gets a structured reason_code rather than empty output.\n\n## Choose the mode\n\nThere are two modes. The caller must choose one before invoking the script:\n\n- **New work:** create a fresh branch from a base branch. Use this when the task has no existing ref to test or modify.\n- **Isolate an existing ref:** attach a worktree to a PR head, existing branch, tag, or commit. Use this for PR review, dogfood, or any workflow that needs to test a target ref without switching the primary checkout.\n\nA branch can be checked out in only one worktree at a time. In existing-ref mode, if the target branch is already checked out anywhere, the script reports `already_checked_out branch=\u003Cname> path=\u003Cpath>` and exits 0 without creating a second checkout. The caller must act on that verdict: work at the reported path, ask the user, or stop. Never force a duplicate branch checkout.\n\n## Creating a new-work worktree\n\nInvoke the bundled script through a `bash -c` wrapper whose command text includes `exec bash ...worktree-manager.sh`. On Claude Code, `${CLAUDE_SKILL_DIR}` resolves to the skill's own runtime directory across marketplace-cached installs and local plugin development. In source or non-Claude runtime contexts, use the repo-root fallback path so generated Codex assets can rewrite it to the installed skill directory. This shape intentionally matches the narrow `allowed-tools` pattern.\n\n```bash\nbash -c 'if [ -n \"${CLAUDE_SKILL_DIR:-}\" ]; then exec bash \"$CLAUDE_SKILL_DIR\u002Fscripts\u002Fworktree-manager.sh\" \"$@\"; fi; exec bash \"$(git rev-parse --show-toplevel)\"\u002F\"skills\u002Fspec-worktree\u002Fscripts\u002Fworktree-manager.sh\" \"$@\"' _ create [--copy-env] \u003Cbranch-name> [from-branch]\n```\n\nDefaults:\n- `from-branch` defaults to origin's default branch (or `main` if that cannot be resolved)\n- The new branch is created at `origin\u002F\u003Cfrom-branch>` (or the local ref if the remote is unavailable)\n- `.env*` files are not copied unless `--copy-env` is passed\n\nExamples:\n```bash\nbash -c 'if [ -n \"${CLAUDE_SKILL_DIR:-}\" ]; then exec bash \"$CLAUDE_SKILL_DIR\u002Fscripts\u002Fworktree-manager.sh\" \"$@\"; fi; exec bash \"$(git rev-parse --show-toplevel)\"\u002F\"skills\u002Fspec-worktree\u002Fscripts\u002Fworktree-manager.sh\" \"$@\"' _ create feat\u002Flogin\nbash -c 'if [ -n \"${CLAUDE_SKILL_DIR:-}\" ]; then exec bash \"$CLAUDE_SKILL_DIR\u002Fscripts\u002Fworktree-manager.sh\" \"$@\"; fi; exec bash \"$(git rev-parse --show-toplevel)\"\u002F\"skills\u002Fspec-worktree\u002Fscripts\u002Fworktree-manager.sh\" \"$@\"' _ create fix\u002Femail-validation develop\nbash -c 'if [ -n \"${CLAUDE_SKILL_DIR:-}\" ]; then exec bash \"$CLAUDE_SKILL_DIR\u002Fscripts\u002Fworktree-manager.sh\" \"$@\"; fi; exec bash \"$(git rev-parse --show-toplevel)\"\u002F\"skills\u002Fspec-worktree\u002Fscripts\u002Fworktree-manager.sh\" \"$@\"' _ create --copy-env feat\u002Flocal-env\n```\n\nAfter creation, switch to the worktree with `cd .worktrees\u002F\u003Cbranch-name>`.\n\nThe `create` command consumes the same detection function before creating `.worktrees\u002F\u003Cbranch>` or running `git worktree add`. It refuses `linked-worktree`, `unknown`, `not-git-repo`, `git-query-failed`, and `output-contract-failed` states so this helper cannot create nested or invisible worktrees by bypassing Step 0.\n\n## Isolating an existing ref\n\nInvoke `isolate` when the caller names a target ref that already exists:\n\n```bash\nbash -c 'if [ -n \"${CLAUDE_SKILL_DIR:-}\" ]; then exec bash \"$CLAUDE_SKILL_DIR\u002Fscripts\u002Fworktree-manager.sh\" \"$@\"; fi; exec bash \"$(git rev-parse --show-toplevel)\"\u002F\"skills\u002Fspec-worktree\u002Fscripts\u002Fworktree-manager.sh\" \"$@\"' _ isolate [--copy-env] \u003Ctarget-ref|pr:\u003Cnumber>|#\u003Cnumber>> [worktree-slug]\n```\n\nExamples:\n\n```bash\nbash -c 'if [ -n \"${CLAUDE_SKILL_DIR:-}\" ]; then exec bash \"$CLAUDE_SKILL_DIR\u002Fscripts\u002Fworktree-manager.sh\" \"$@\"; fi; exec bash \"$(git rev-parse --show-toplevel)\"\u002F\"skills\u002Fspec-worktree\u002Fscripts\u002Fworktree-manager.sh\" \"$@\"' _ isolate feature\u002Flogin\nbash -c 'if [ -n \"${CLAUDE_SKILL_DIR:-}\" ]; then exec bash \"$CLAUDE_SKILL_DIR\u002Fscripts\u002Fworktree-manager.sh\" \"$@\"; fi; exec bash \"$(git rev-parse --show-toplevel)\"\u002F\"skills\u002Fspec-worktree\u002Fscripts\u002Fworktree-manager.sh\" \"$@\"' _ isolate pr:123\nbash -c 'if [ -n \"${CLAUDE_SKILL_DIR:-}\" ]; then exec bash \"$CLAUDE_SKILL_DIR\u002Fscripts\u002Fworktree-manager.sh\" \"$@\"; fi; exec bash \"$(git rev-parse --show-toplevel)\"\u002F\"skills\u002Fspec-worktree\u002Fscripts\u002Fworktree-manager.sh\" \"$@\"' _ isolate '#123' pr-123\n```\n\nBehavior:\n\n- Existing local branch: `git worktree add .worktrees\u002F\u003Cslug> \u003Cbranch>`.\n- Remote-only `origin\u002F\u003Cbranch>`: create a local branch in the new worktree from `origin\u002F\u003Cbranch>`.\n- PR shorthand `pr:\u003Cnumber>` or `#\u003Cnumber>`: fetch `pull\u002F\u003Cnumber>\u002Fhead` into local branch `pr-\u003Cnumber>`, then attach the worktree to that branch so fix commits are not orphaned on `FETCH_HEAD`.\n- Tag or commit: create a detached worktree at that commit.\n- Already in a linked worktree: check the target out in place unless it is already the current branch; do not create a nested worktree.\n- Target branch already checked out elsewhere: report `already_checked_out branch=\u003Cname> path=\u003Cpath>` and do not create a second checkout.\n\n## Env File Opt-In\n\nUse `--copy-env` only when the workflow explicitly needs local environment files in the new worktree. The opt-in path works for both `create` and `isolate`: it copies `.env*` files except `.env.example`, `.env.template`, and `.env.sample`, prints only file names, backs up pre-existing destination files, and appends an owner-only `.env-copy.log` containing only timestamp, basename, and byte size. The log contains no absolute path, content-derived hash, or file contents and is added to the worktree git exclude file.\n\nEven when env files were copied intentionally, downstream staging must still treat them as denied by default. A batch may stage an env file only when the task\u002Fimplementation unit declares the exact env path in `expected_side_effects` and explicitly states that changing that env file is intended.\n\n## Other worktree operations\n\nUse `git` directly — no wrapper is needed and none is provided:\n\n```bash\ngit worktree list                          # list worktrees\ngit worktree remove .worktrees\u002F\u003Cbranch>    # remove a worktree\ncd .worktrees\u002F\u003Cbranch>                     # switch to a worktree\ncd \"$(git rev-parse --show-toplevel)\"      # return to main checkout\n```\n\nDo not manually copy `.env*` files as a default setup step. If an existing worktree needs env files, recreate it with `--copy-env` or copy files manually only after a human explicitly opts in and records the same file-name-only audit information.\n\n## Dev tool trust behavior\n\nTrust stores are user-owned state outside the worktree contract. When mise or direnv configs are present, the script only prints the exact `mise trust \u003Cfile>` or `direnv allow` command and tells the user to review the worktree content first. It never executes either command, even when the config matches a trusted branch; worktree creation success does not imply trust approval.\n\n## When to create a worktree\n\nCreate a worktree when:\n- Reviewing a PR while keeping the main checkout free for other work\n- Running multiple features in parallel without branch-switching overhead\n- Keeping the default branch free of in-progress state\n\nDo not create a new-work worktree for single-task work that can happen on a branch in the main checkout, and never create a nested worktree when Step 0 reports `state=linked-worktree`. For existing-ref isolation, use `isolate` so branch uniqueness and already-checked-out verdicts remain deterministic.\n\n## Integration\n\nThis helper accepts only a caller-owned isolation contract: caller identity, target repo, target ref or new branch, reason isolation is needed, allowed setup side effects, environment-copy authorization, and the return path consumer. It detects or creates the worktree and returns facts. It never selects an execution engine, dispatches a worker, stages, commits, pushes, opens a PR, or decides cleanup. A worker placed in a linked worktree is edit-and-test only: it must not run `git add`, `git commit`, or any command that writes the shared Git index. A worker sandbox `EPERM` is evidence about that worker only, not host capability evidence.\n\n`spec-dogfood` uses existing-ref mode for a PR or non-current branch: `isolate pr:\u003Cnumber>` or `isolate \u003Cbranch>`. It consumes `Worktree ready: \u003Cpath>` or `already_checked_out branch=\u003Cname> path=\u003Cpath>` without switching the primary checkout.\n\n`spec-work` may use new-work or existing-ref mode only after `execution-strategy.md` has locked one target repo and recorded mutation authorization. It owns all implementation and recovery state outside this helper. A linked worktree does not enforce Git-index isolation: before a mutation-capable worker starts, the caller still needs a host receipt that denies writes to the exact Git common directory\u002Findex path and filters credential environment. Without it, use `worker_git_index_enforcement_unavailable`, do not dispatch that worker, and continue inline\u002Fserial. The returned worktree root becomes the snapshot `worktree_identity.repo_root`; any later identity drift routes back to `spec-work` as `run-source-drifted` rather than causing this helper to recreate, reset, or rerun work.\n\n未来 caller 必须先在其 public owner source 中增加 forward invocation 与 intake contract。本 helper 的 reverse claim 不能单独建立 integration edge。\n\n## Troubleshooting\n\n**\"Worktree already exists\"**: the path is already in use. Either switch to it (`cd .worktrees\u002F\u003Cbranch>`) or remove it (`git worktree remove .worktrees\u002F\u003Cbranch>`) before recreating.\n\n**\"Cannot remove worktree: it is the current worktree\"**: `cd` out of the worktree first, then `git worktree remove`.\n\n**Dev tool trust was skipped**: the script prints the manual command. Review the config diff (`git diff \u003Cbase-ref> -- .envrc`), then run the printed command from the worktree directory.\n",{"name":5,"description":7,"allowed-tools":33,"user-invocable":29},"Bash(bash *worktree-manager.sh*)","master","74655dc86b1270bb52239e0f8bc9517de7a7071c","skills\u002Fspec-worktree",13,"https:\u002F\u002Fgithub.com\u002Fleo-kuang-ai\u002Fspec-first","http:\u002F\u002Fspec-first.cn\u002F","https:\u002F\u002Fgithub.com\u002Fleo-kuang-ai","作为一个初学者或者进阶者，这并没有什么错。当一个有能力的程序员而不是领导者，这也没有什么错。真正的错误是，当你知道应该如何去提高时仍然选择做一名初学者。","2026-11-05 13:30:55",{"source":8,"skillName":5,"commands":44,"prompt":54,"zipAvailable":55},[45,48,51],{"tool":46,"command":47},"npx","npx skills add leo-kuang-ai\u002Fspec-first --skill spec-worktree",{"tool":49,"command":50},"bunx","bunx skills add leo-kuang-ai\u002Fspec-first --skill spec-worktree",{"tool":52,"command":53},"pnpm","pnpm dlx skills add leo-kuang-ai\u002Fspec-first --skill spec-worktree","安装技能，技能地址：https:\u002F\u002Fgithub.com\u002Fleo-kuang-ai\u002Fspec-first\u002Fblob\u002Fmaster\u002Fskills\u002Fspec-worktree\u002FSKILL.md",true,[57],{"path":58,"resourceType":59,"resourceTypeDesc":60,"sizeBytes":61,"sourceHtmlUrl":62},"scripts\u002Fworktree-manager.sh","SCRIPT","脚本",23550,"https:\u002F\u002Fgithub.com\u002Fleo-kuang-ai\u002Fspec-first\u002Fblob\u002Fmaster\u002Fskills\u002Fspec-worktree\u002Fscripts\u002Fworktree-manager.sh",[64,99,121,135,155,175],{"skillNo":65,"name":66,"nameZh":6,"description":67,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":68,"categories":69,"keywords":80,"publishedAt":28},"01M6CWKQCYJXDCW4MEF3FSJE26","using-spec-first","Standalone entry governor for spec-first. Use before substantial work in a spec-first repo or when the user asks what to run next; choose one public `spec-*` workflow, standalone skill, terminal command, or Direct Lane. Do not use to reroute active public workflows or bounded workers, or for lightweight facts, current-context explanations, narrow lookups, user-supplied single-document cleanup, or clearly scoped low-risk edits.","https:\u002F\u002Fgithub.com\u002Fleo-kuang-ai\u002Fspec-first\u002Fblob\u002Fmaster\u002Fskills\u002Fusing-spec-first\u002FSKILL.md",[70,75],{"categoryNo":71,"categoryName":72,"taxonomyType":73,"taxonomyTypeDesc":74},"01JBSEEDCAT000000000000023","Skill与智能体开发","SCENARIO","使用场景",{"categoryNo":76,"categoryName":77,"taxonomyType":78,"taxonomyTypeDesc":79},"01JBSEEDCAT000000000000030","开发工程师","PROFESSION","适用职业",[19,81,82,83,84,85,86,87,26,88,89,90,91,92,93,94,95,96,97,98],"first","using spec first","active","risk","context","command","repo","do","choose","direct","use","lane","run","cleanup","workflows","workflow","terminal","next",{"skillNo":100,"name":101,"nameZh":6,"description":102,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":103,"categories":104,"keywords":106,"publishedAt":28},"01M6CWKK43ZJKQXKVJB3BWWPR1","spec-write-tasks","Public workflow entrypoint (spec-write-tasks): compile a settled local spec-plan into an optional derived task pack for spec-work, or validate an existing local task pack before execution. Use for explicit plan-splitting\u002Ftask-doc requests or high-complexity work suitability; do not use for plan authoring, implementation execution, unresolved scope, small low-risk plans, progress\u002Fapproval state, remote\u002Fgeneric task lists, or generated runtime mirror edits. Keep the plan as single source of truth; tasks are derived and optional.","https:\u002F\u002Fgithub.com\u002Fleo-kuang-ai\u002Fspec-first\u002Fblob\u002Fmaster\u002Fskills\u002Fspec-write-tasks\u002FSKILL.md",[105],{"categoryNo":71,"categoryName":72,"taxonomyType":73,"taxonomyTypeDesc":74},[19,107,108,109,110,111,88,112,113,91,114,26,115,116,84,117,118,119,120,96],"tasks","write","spec write tasks","doc","task","complexity","plan authoring","generated","plan","local","execution","compile","state","validate",{"skillNo":122,"name":123,"nameZh":6,"description":124,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":125,"categories":126,"keywords":128,"publishedAt":28},"01M6CWKEK6CVPQW8EMCNSDPHBJ","spec-write-skill","公开 workflow：创建、修改或迁移项目拥有的 Agent Skill package，或对现有\u002F外部 package 做用户明确要求、零执行的只读验证与 readiness 报告时使用；也用于按已接受的 audit finding 修复 source skill。不要用于一次性回答、解释\u002F总结\u002F翻译、普通代码 review、第三方 Skill 纯安装或导入、跨仓批量修改，或直接修补 generated runtime mirrors。","https:\u002F\u002Fgithub.com\u002Fleo-kuang-ai\u002Fspec-first\u002Fblob\u002Fmaster\u002Fskills\u002Fspec-write-skill\u002FSKILL.md",[127],{"categoryNo":71,"categoryName":72,"taxonomyType":73,"taxonomyTypeDesc":74},[129,130,108,19,114,131,132,133,96,134],"spec write skill","write skill","翻译","audit","package","review",{"skillNo":136,"name":137,"nameZh":6,"description":138,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":139,"categories":140,"keywords":142,"publishedAt":28},"01M6CWK5W4VREMNXGQQKXXSQ3N","spec-work","Execute a settled plan, validated task pack, spec path, or concrete implementation request end-to-end. Use spec-debug for open-ended bugs; stop when target repo, scope, source ownership, or required authorization is unresolved. Not for explicitly requested GitHub PR-review-feedback handling — route those to spec-resolve-pr-feedback.","https:\u002F\u002Fgithub.com\u002Fleo-kuang-ai\u002Fspec-first\u002Fblob\u002Fmaster\u002Fskills\u002Fspec-work\u002FSKILL.md",[141],{"categoryNo":76,"categoryName":77,"taxonomyType":78,"taxonomyTypeDesc":79},[19,26,143,134,144,115,145,110,146,147,148,149,150,111,151,152,153,154,91,87],"spec work","feedback","open","pr","debug","to spec","github","route","github pr","stop","implementation","auto",{"skillNo":156,"name":157,"nameZh":6,"description":158,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":159,"categories":160,"keywords":166,"publishedAt":28},"01M6CWK1MFTSNV9MYD4C8WGB8B","spec-test-xcode","Build and test iOS apps on simulator using XcodeBuildMCP. Use after making iOS code changes, before creating a PR, or when verifying app behavior and checking for crashes on simulator.","https:\u002F\u002Fgithub.com\u002Fleo-kuang-ai\u002Fspec-first\u002Fblob\u002Fmaster\u002Fskills\u002Fspec-test-xcode\u002FSKILL.md",[161,164,165],{"categoryNo":162,"categoryName":163,"taxonomyType":73,"taxonomyTypeDesc":74},"01JBSEEDCAT000000000000008","测试与质量",{"categoryNo":71,"categoryName":72,"taxonomyType":73,"taxonomyTypeDesc":74},{"categoryNo":76,"categoryName":77,"taxonomyType":78,"taxonomyTypeDesc":79},[19,167,168,169,170,91,171,172,173,146,174],"test","spec test xcode","build","default","behavior","ios","code","build and test",{"skillNo":176,"name":177,"nameZh":6,"description":178,"descriptionZh":6,"repositoryFullName":8,"ownerLogin":9,"ownerAvatarUrl":10,"ownerAccountNo":11,"ownerDisplayName":12,"repositoryNo":13,"starsCount":14,"licenseSpdxId":15,"licenseFileUrl":6,"sourceHtmlUrl":179,"categories":180,"keywords":183,"publishedAt":28},"01M6CWJXMAXKVRW5MA4E9EJJQW","spec-test-browser","Run browser tests on pages affected by current PR or branch. Use after code changes when browser verification is requested before review or merge. Not for diagnosing failures those runs uncover — route defects to spec-debug.","https:\u002F\u002Fgithub.com\u002Fleo-kuang-ai\u002Fspec-first\u002Fblob\u002Fmaster\u002Fskills\u002Fspec-test-browser\u002FSKILL.md",[181,182],{"categoryNo":162,"categoryName":163,"taxonomyType":73,"taxonomyTypeDesc":74},{"categoryNo":76,"categoryName":77,"taxonomyType":78,"taxonomyTypeDesc":79},[19,184,185,167,186,147,146,173,148,187,91,188,150,189,93,190,134],"spec test browser","browser","test browser","merge","branch","pipeline","verification"]