sc-git-worktree: global install leaves literal {{REPO_NAME}} in skill/command/agent docs; expand at runtime instead

[randlee]

Summary

sc-git-worktree (v0.14.0, commit 984494f) cannot be installed globally (sc-install.py install sc-git-worktree --global) without shipping a literal {{REPO_NAME}} placeholder into the agent-facing instructions. The manifest marks the package install.scope: local-only because of this, but the installer does not enforce that scope, so a global install succeeds and leaves broken docs behind.

The underlying scripts are fine: worktree_shared.get_repo_name() / worktree_create.py derive the base path from git rev-parse --show-toplevel at runtime when worktree_base is omitted. Only the prose that tells the agent what the default is depends on install-time substitution.

A globally installed skill has to work in every repo, so the expansion belongs at runtime (done by the agent), not at install time.

Reproduction

python tools/sc-install.py install sc-git-worktree --global
grep -rn "{{REPO_NAME}}" ~/.claude/skills ~/.claude/commands ~/.claude/agents

Output:

~/.claude/skills/sc-git-worktree/SKILL.md:63:- Default worktree base: `../{{REPO_NAME}}-worktrees`.
~/.claude/commands/sc-git-worktree.md:56:- Worktree base: `../{{REPO_NAME}}-worktrees/<branch>`.
~/.claude/commands/sc-git-worktree.md:57:- Tracking file: `../{{REPO_NAME}}-worktrees/worktree-tracking.jsonl` ...
~/.claude/agents/sc-git-worktree-update.md:26:- worktree_base (optional): defaults to `../{{REPO_NAME}}-worktrees`

_git_repo_basename(dest_path) in src/sc_cli/install.py returns empty for ~/.claude, so cmd_install skips expansion silently.

Failure mode: an agent that takes the documented default literally passes ../{{REPO_NAME}}-worktrees as worktree_base, creating a directory with braces in its name next to the repo.

Affected source files

• packages/sc-git-worktree/skills/sc-git-worktree/SKILL.md line 63
• packages/sc-git-worktree/commands/sc-git-worktree.md lines 56-57
• packages/sc-git-worktree/agents/sc-git-worktree-update.md line 26
• packages/sc-git-worktree/manifest.yaml (variables.REPO_NAME, install.scope: local-only)

Edits applied to the installed global copies (proposed fix)

These were applied by hand to ~/.claude/... and mirrored to ~/.codex/skills/sc-git-worktree/. They should land in the package source so a forced reinstall does not revert them.

skills/sc-git-worktree/SKILL.md line 63, replace:

- Default worktree base: `../{{REPO_NAME}}-worktrees`.

with:

- Default worktree base: `../<REPO_NAME>-worktrees`, where `<REPO_NAME>` is the repo folder name.
  This skill is installed globally, so derive it at runtime, never hardcode it:
  `REPO_NAME=$(basename "$(git rev-parse --show-toplevel)")` (PowerShell: `Split-Path -Leaf (git rev-parse --show-toplevel)`).
  Pass the resolved value as `worktree_base` to every agent/script call.

commands/sc-git-worktree.md lines 56-57, replace:

- Worktree base: `../{{REPO_NAME}}-worktrees/<branch>`.
- Tracking file: `../{{REPO_NAME}}-worktrees/worktree-tracking.jsonl` (disable or override if tracking is not used).

with:

- REPO_NAME: derive at runtime as `basename $(git rev-parse --show-toplevel)` (this command is installed globally; never assume a fixed name).
- Worktree base: `../<REPO_NAME>-worktrees/<branch>`.
- Tracking file: `../<REPO_NAME>-worktrees/worktree-tracking.jsonl` (disable or override if tracking is not used).
- Always pass the resolved `worktree_base` explicitly in every subagent `<input_json>`.

agents/sc-git-worktree-update.md line 26, replace:

- worktree_base (optional): defaults to `../{{REPO_NAME}}-worktrees`

with:

- worktree_base (optional): defaults to `../<REPO_NAME>-worktrees`, where REPO_NAME = `basename $(git rev-parse --show-toplevel)` resolved at runtime

Follow-ups for the package itself

1. Remove variables.REPO_NAME and install.scope: local-only from manifest.yaml once the docs no longer need substitution. The package becomes Tier 0 (no token expansion).
2. Either enforce install.scope in src/sc_cli/install.py (refuse --global for local-only packages) or drop the field, since today it is documentation only.
3. Pre-existing, separate: get_repo_name() uses --show-toplevel, so when run from inside an existing worktree the derived name is the branch folder, not the repo. Using git rev-parse --git-common-dir and taking its parent's basename would fix that for both the scripts and the doc instruction above.

Related

While installing on Windows, sc-install.py crashes with UnicodeEncodeError: 'charmap' codec can't encode character '✓' because info() prints a checkmark and the console defaults to cp1252. Workaround is PYTHONIOENCODING=utf-8. Can be filed separately.