thachvd-kit 1.0.37 → 1.0.39

package/skills/using-git-worktrees/SKILL.md

@@ -1,175 +1,175 @@
----
-name: using-git-worktrees
-description: Use when the user explicitly wants an isolated workspace, especially for parallel feature development
----
-
-# Using Git Worktrees
-
-## Overview
-
-When isolation is intended, ensure 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.
-
-**Core principle:** Determine the intended workspace first. Respect an explicit request to stay on the current branch/workspace. If isolation is requested, prefer native tools, then fall back to git. Never fight the harness.
-
-**Announce at start:** "I'm using the using-git-worktrees skill to set up an isolated workspace."
-
-## Step 0: Detect Existing Isolation
-
-**Before creating anything, check if you are already in an isolated workspace.**
-
-```text
-git rev-parse --git-dir
-git rev-parse --git-common-dir
-git rev-parse --show-toplevel
-git rev-parse --show-superproject-working-tree
-git branch --show-current
-```
-
-**Submodule guard:** differing Git directory results are also possible inside git submodules. Before concluding "already in a worktree," verify you are not in a submodule:
-
-```text
-# If this returns a path, you're in a submodule, not a worktree — treat as normal repo
-git rev-parse --show-superproject-working-tree
-```
-
-**If `--git-dir` differs from `--git-common-dir` (and this is not a submodule):** You are already in a linked worktree. Skip to Step 2 (Project Setup). Do NOT create another worktree.
-
-Report with branch state:
-- On a branch: "Already in isolated workspace at `<path>` on branch `<name>`."
-- Detached HEAD: "Already in isolated workspace at `<path>` (detached HEAD, externally managed). Branch creation needed at finish time."
-
-**If the values match (or this is a submodule):** You are in a normal repo checkout.
-
-If the user explicitly says to work on the current branch/workspace, stay there. If the user invokes `/using-git-worktrees` or explicitly requests isolation, that is consent to isolate. If intent is unspecified, stay in the current workspace by default. Do not recommend or create a worktree solely because an implementation plan is large, risky, or being executed by SDD. Follow a project-level preference only when it explicitly requires isolation.
-
-Honor any existing declared preference without asking. If isolation is not explicitly requested or required by project policy, skip to Step 2 in the current workspace.
-
-## Step 1: Create Isolated Workspace
-
-**You have two mechanisms. Try them in this order.**
-
-### 1a. Native Worktree Tools (preferred)
-
-The user has asked for an isolated workspace (Step 0 consent). Do you already have a way to create a worktree? It might be a tool with a name like `EnterWorktree`, `WorktreeCreate`, a `/worktree` command, or a `--worktree` flag. If you do, use it and skip to Step 2.
-
-Native tools handle directory placement, branch creation, and cleanup automatically. Using `git worktree add` when you have a native tool creates phantom state your harness can't see or manage.
-
-Only proceed to Step 1b if you have no native worktree tool available.
-
-### 1b. Git Worktree Fallback
-
-**Only use this if Step 1a does not apply** — you have no native worktree tool available. Create a worktree manually using git.
-
-#### Directory Selection
-
-Follow this priority order. Explicit user preference always beats observed filesystem state.
-
-1. **Check your instructions for a declared worktree directory preference.** If the user has already specified one, use it without asking.
-
-2. **Check for an existing project-local worktree directory:**
-   ```text
-   PowerShell: Test-Path .worktrees; Test-Path worktrees
-   CMD:        if exist .worktrees echo .worktrees & if exist worktrees echo worktrees
-   ```
-   If found, use it. If both exist, `.worktrees` wins.
-
-3. **If there is no other guidance available**, default to `.worktrees/` at the project root.
-
-#### Safety Verification (project-local directories only)
-
-**MUST verify directory is ignored before creating worktree:**
-
-```text
-git check-ignore .worktrees
-```
-
-If `.worktrees` does not exist, check the directory name you will create:
-
-```text
-git check-ignore worktrees
-```
-
-**If NOT ignored:** Add the appropriate entry to `.gitignore`, show that change clearly, and proceed only after the ignore rule is in place. Do not silently commit unrelated changes.
-
-**Why critical:** Prevents accidentally committing worktree contents to repository.
-
-#### Create the Worktree
-
-```text
-# Determine the path using the host shell, then run the portable Git command.
-git worktree list --porcelain
-git branch --list <branch>
-git worktree add "<path>" -b "<branch>"       # new branch
-git worktree add "<path>" "<branch>"          # existing, unattached branch
-```
-
-Never reset, force-checkout, delete, or steal an existing branch attached to another worktree.
-
-**Sandbox fallback:** If `git worktree add` fails with a permission error (sandbox denial), report that clearly. If isolation was explicitly required, stop rather than silently working on the current branch; otherwise ask whether to continue in the current workspace, then run setup and baseline tests there only with that choice.
-
-## Step 2: Project Setup
-
-Auto-detect and run appropriate setup. Read the repository's `AGENTS.md`, `.agent/docs/tooling.md`, package scripts, and lockfiles first; do not install dependencies that the project workflow does not require:
-
-```text
-package-lock.json -> npm
-pnpm-lock.yaml    -> pnpm
-yarn.lock         -> yarn
-bun.lock*         -> bun
-requirements.txt  -> pip
-uv.lock           -> uv
-Cargo.toml        -> cargo
-go.mod            -> go
-composer.json     -> composer
-```
-
-Use the project's documented bootstrap command after detecting the package manager.
-
-## Step 3: Verify Clean Baseline
-
-Run tests to ensure workspace starts clean:
-
-```text
-# Run the project-appropriate command (one command, not a shell expression):
-npm test
-# or cargo test / pytest / go test ./...
-```
-
-**If tests fail:** Report failures, ask whether to proceed or investigate.
-
-**If tests pass:** Report ready.
-
-### Report
-
-```
-Worktree ready at <full-path>
-Tests passing (<N> tests, 0 failures)
-Ready to implement <feature-name>
-```
-
-## Quick Reference
-
-| Situation | Action |
-|-----------|--------|
-| Already in linked worktree | Skip creation (Step 0) |
-| In a submodule | Treat as normal repo (Step 0 guard) |
-| Native worktree tool available | Use it (Step 1a) |
-| No native tool | Git worktree fallback (Step 1b) |
-| `.worktrees/` exists | Use it (verify ignored) |
-| `worktrees/` exists | Use it (verify ignored) |
-| Both exist | Use `.worktrees/` |
-| Neither exists | Check instruction file, then default `.worktrees/` |
-| Directory not ignored | Add to .gitignore + commit |
-| Permission error on create | Sandbox fallback, work in place |
-| Tests fail during baseline | Report failures + ask |
-| No package.json/Cargo.toml | Skip dependency install |
-
-## Common Rationalizations
-
-| Excuse | Reality |
-|--------|---------|
-| "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. |
-| "`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. |
-| "The worktree directory is surely ignored already" | Run `git check-ignore`. An unignored worktree directory commits the whole tree into the repo. |
-| "Any directory name works" | Explicit instructions beat an existing project-local directory, which beats the `.worktrees/` default. |
-| "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. |
+---
+name: using-git-worktrees
+description: Use when the user explicitly wants an isolated workspace, especially for parallel feature development
+---
+
+# Using Git Worktrees
+
+## Overview
+
+When isolation is intended, ensure 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.
+
+**Core principle:** Determine the intended workspace first. Respect an explicit request to stay on the current branch/workspace. If isolation is requested, prefer native tools, then fall back to git. Never fight the harness.
+
+**Announce at start:** "I'm using the using-git-worktrees skill to set up an isolated workspace."
+
+## Step 0: Detect Existing Isolation
+
+**Before creating anything, check if you are already in an isolated workspace.**
+
+```text
+git rev-parse --git-dir
+git rev-parse --git-common-dir
+git rev-parse --show-toplevel
+git rev-parse --show-superproject-working-tree
+git branch --show-current
+```
+
+**Submodule guard:** differing Git directory results are also possible inside git submodules. Before concluding "already in a worktree," verify you are not in a submodule:
+
+```text
+# If this returns a path, you're in a submodule, not a worktree — treat as normal repo
+git rev-parse --show-superproject-working-tree
+```
+
+**If `--git-dir` differs from `--git-common-dir` (and this is not a submodule):** You are already in a linked worktree. Skip to Step 2 (Project Setup). Do NOT create another worktree.
+
+Report with branch state:
+- On a branch: "Already in isolated workspace at `<path>` on branch `<name>`."
+- Detached HEAD: "Already in isolated workspace at `<path>` (detached HEAD, externally managed). Branch creation needed at finish time."
+
+**If the values match (or this is a submodule):** You are in a normal repo checkout.
+
+If the user explicitly says to work on the current branch/workspace, stay there. If the user invokes `/using-git-worktrees` or explicitly requests isolation, that is consent to isolate. If intent is unspecified, stay in the current workspace by default. Do not recommend or create a worktree solely because an implementation plan is large, risky, or being executed by SDD. Follow a project-level preference only when it explicitly requires isolation.
+
+Honor any existing declared preference without asking. If isolation is not explicitly requested or required by project policy, skip to Step 2 in the current workspace.
+
+## Step 1: Create Isolated Workspace
+
+**You have two mechanisms. Try them in this order.**
+
+### 1a. Native Worktree Tools (preferred)
+
+The user has asked for an isolated workspace (Step 0 consent). Do you already have a way to create a worktree? It might be a tool with a name like `EnterWorktree`, `WorktreeCreate`, a `/worktree` command, or a `--worktree` flag. If you do, use it and skip to Step 2.
+
+Native tools handle directory placement, branch creation, and cleanup automatically. Using `git worktree add` when you have a native tool creates phantom state your harness can't see or manage.
+
+Only proceed to Step 1b if you have no native worktree tool available.
+
+### 1b. Git Worktree Fallback
+
+**Only use this if Step 1a does not apply** — you have no native worktree tool available. Create a worktree manually using git.
+
+#### Directory Selection
+
+Follow this priority order. Explicit user preference always beats observed filesystem state.
+
+1. **Check your instructions for a declared worktree directory preference.** If the user has already specified one, use it without asking.
+
+2. **Check for an existing project-local worktree directory:**
+   ```text
+   PowerShell: Test-Path .worktrees; Test-Path worktrees
+   CMD:        if exist .worktrees echo .worktrees & if exist worktrees echo worktrees
+   ```
+   If found, use it. If both exist, `.worktrees` wins.
+
+3. **If there is no other guidance available**, default to `.worktrees/` at the project root.
+
+#### Safety Verification (project-local directories only)
+
+**MUST verify directory is ignored before creating worktree:**
+
+```text
+git check-ignore .worktrees
+```
+
+If `.worktrees` does not exist, check the directory name you will create:
+
+```text
+git check-ignore worktrees
+```
+
+**If NOT ignored:** Add the appropriate entry to `.gitignore`, show that change clearly, and proceed only after the ignore rule is in place. Do not silently commit unrelated changes.
+
+**Why critical:** Prevents accidentally committing worktree contents to repository.
+
+#### Create the Worktree
+
+```text
+# Determine the path using the host shell, then run the portable Git command.
+git worktree list --porcelain
+git branch --list <branch>
+git worktree add "<path>" -b "<branch>"       # new branch
+git worktree add "<path>" "<branch>"          # existing, unattached branch
+```
+
+Never reset, force-checkout, delete, or steal an existing branch attached to another worktree.
+
+**Sandbox fallback:** If `git worktree add` fails with a permission error (sandbox denial), report that clearly. If isolation was explicitly required, stop rather than silently working on the current branch; otherwise ask whether to continue in the current workspace, then run setup and baseline tests there only with that choice.
+
+## Step 2: Project Setup
+
+Auto-detect and run appropriate setup. Read the repository's `AGENTS.md`, `.agent/docs/tooling.md`, package scripts, and lockfiles first; do not install dependencies that the project workflow does not require:
+
+```text
+package-lock.json -> npm
+pnpm-lock.yaml    -> pnpm
+yarn.lock         -> yarn
+bun.lock*         -> bun
+requirements.txt  -> pip
+uv.lock           -> uv
+Cargo.toml        -> cargo
+go.mod            -> go
+composer.json     -> composer
+```
+
+Use the project's documented bootstrap command after detecting the package manager.
+
+## Step 3: Verify Clean Baseline
+
+Run tests to ensure workspace starts clean:
+
+```text
+# Run the project-appropriate command (one command, not a shell expression):
+npm test
+# or cargo test / pytest / go test ./...
+```
+
+**If tests fail:** Report failures, ask whether to proceed or investigate.
+
+**If tests pass:** Report ready.
+
+### Report
+
+```
+Worktree ready at <full-path>
+Tests passing (<N> tests, 0 failures)
+Ready to implement <feature-name>
+```
+
+## Quick Reference
+
+| Situation | Action |
+|-----------|--------|
+| Already in linked worktree | Skip creation (Step 0) |
+| In a submodule | Treat as normal repo (Step 0 guard) |
+| Native worktree tool available | Use it (Step 1a) |
+| No native tool | Git worktree fallback (Step 1b) |
+| `.worktrees/` exists | Use it (verify ignored) |
+| `worktrees/` exists | Use it (verify ignored) |
+| Both exist | Use `.worktrees/` |
+| Neither exists | Check instruction file, then default `.worktrees/` |
+| Directory not ignored | Add to .gitignore + commit |
+| Permission error on create | Sandbox fallback, work in place |
+| Tests fail during baseline | Report failures + ask |
+| No package.json/Cargo.toml | Skip dependency install |
+
+## Common Rationalizations
+
+| Excuse | Reality |
+|--------|---------|
+| "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. |
+| "`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. |
+| "The worktree directory is surely ignored already" | Run `git check-ignore`. An unignored worktree directory commits the whole tree into the repo. |
+| "Any directory name works" | Explicit instructions beat an existing project-local directory, which beats the `.worktrees/` default. |
+| "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. |