SKILL.md
Git Worktree Discipline
Internal shared skill. Optional create/detect isolation before the first non-trivial write (docs or code). Hosts declare it in dependencies and abort if missing.
Name note: intentionally not named using-git-worktrees. Use git-worktree-discipline only. Operational create/detect/setup details live in reference.md (inspired by common worktree practice; no external skill dependency).
When to run
Before the first non-trivial persistent write (docs or code) in the host run. Skip the create offer only when already isolated for this change, or gate/never, or lean/hotfix in-place 留痕 this session.
Loop
- Detect — already in a linked worktree for this change? Reuse (do not nest). Distinguish submodule from worktree before concluding isolation. Commands:
reference.md.
- Resolve preference —
worktree-gate in AGENTS.md / CLAUDE.md: always | never | ask. Unset ≡ ask.
- Recommend (ask / always) — suitability from project state (sibling
../ scripts, full product pack, dirty primary tree). Good for code + unit tests; poor for pack without path rebinding.
- Act by gate
- never → skip create; 【工作区隔离跳过】escape=worktree-gate-never;reason=… - always → create when possible (no ask) - ask → after recommendation, ask: create / decline / lean; do not silently create
- Create — prefer the agent’s native workspace/worktree capability when available (avoids harness-invisible phantom git worktrees); else git fallback under ignored project-local dir (
.worktrees/ preferred). Verify ignore with git check-ignore. Path priority and failure fallback: reference.md.
- Setup + baseline — in the new workspace, run project-appropriate install/build and a baseline test/typecheck when the project has one; if baseline fails, report and ask whether to proceed or investigate. Skip install/baseline only when no project markers apply.
- Lean/hotfix / decline —
【工作区隔离跳过】escape=lean-hotfix|user-decline;reason=…
Do not replace design approval. Do not silently destroy isolation mid-run. Do not imply one-click full product pack inside a worktree.
Cleanup ownership
Destroy/remove after verify/archive → feature-branch-closeout optional cleanup. This skill may note the remove command symmetric to create.
Integration guide
- Hosts: one line before the first artifact/code write — load this skill (worktree gate + optional isolation).
- Compose with
feature-branch-closeout for cleanup only.
- Prefer
user-invocable: false.
- Full detect/create/setup checklist:
reference.md.