fix(setup): mirror support files + asset dirs alongside SKILL.md in link_claude_skill_dirs

[NikhileshNanduri]

Summary

Closes #1499.

link_claude_skill_dirs in ./setup previously only symlinked SKILL.md into each skill directory. Skills like /review reference sibling files — checklist.md, greptile-triage.md, design-checklist.md, TODOS-format.md, and specialists/ — via the .claude/skills/review/ path. Those files were never linked, so /review hit its own STOP point ("If the file cannot be read, STOP and report the error") on every global install. 20 releases since the regression was introduced.

This is Option B from the issue — the durable fix. It teaches the linker to mirror all sibling assets, not just SKILL.md. No SKILL.md.tmpl path hacks needed.

What changed

setup — link_claude_skill_dirs(): after the existing SKILL.md symlink, two new loops:

1. Supporting .md files — iterates $gstack_dir/$dir_name/*.md, skips SKILL.md (already linked), links the rest (checklist.md, greptile-triage.md, TODOS-format.md, etc.)
2. Asset directories — iterates $gstack_dir/$dir_name/*/, skips build/source dirs (dist, src, test, tests, scripts, node_modules), links the rest (specialists/, bin/, references/, templates/, migrations/, etc.)

Both loops are idempotent (rm then ln -snf) — ./setup re-runs cleanly over existing installs.

test/gen-skill-docs.test.ts: two new unit tests that verify the linker body contains the new loops and the correct exclusion list.

Affected skills (verified by functional test)

Skill	Previously missing	Now linked
review/	checklist.md, greptile-triage.md, design-checklist.md, TODOS-format.md, specialists/	✅ All 5
qa/	references/, templates/	✅ Both
careful/	bin/	✅
freeze/	bin/	✅
plan-devex-review/	dx-hall-of-fame.md	✅
cso/	ACKNOWLEDGEMENTS.md	✅
setup-gbrain/	memory.md	✅
gstack-upgrade/	migrations/	✅

browse/ correctly gets bin/ but NOT src/, dist/, test/, scripts/ (all excluded).

Supersedes #1486

PR #1486 added only bin/ symlinks. This PR is a superset — it covers bin/ and all other asset types — so #1486 can be closed if this merges.

Testing scenarios

Scenario 1: /review checklist loads on a fresh global install

# Before fix
ls ~/.claude/skills/review/
# → SKILL.md only

# After ./setup with this fix
ls ~/.claude/skills/review/
# → SKILL.md  checklist.md  design-checklist.md  greptile-triage.md  TODOS-format.md  specialists/

# Verify /review Step 2 can now read the checklist
cat ~/.claude/skills/review/checklist.md  # must not 404
ls ~/.claude/skills/review/specialists/   # must show testing.md, security.md, etc.

Scenario 2: Idempotency — re-running ./setup doesn't break existing installs

# Run ./setup twice
./setup --host claude
./setup --host claude

# review/ should still have all support files, no duplicates, no broken symlinks
ls -la ~/.claude/skills/review/
find ~/.claude/skills/review/ -maxdepth 1 -name "*.md" | wc -l  # stable count

Scenario 3: build dirs are excluded from browse/

ls ~/.claude/skills/browse/
# Must contain: SKILL.md  bin/  PLAN-snapshot-dropdown-interactive.md
# Must NOT contain: src/  dist/  test/  scripts/

Scenario 4: careful/ and freeze/ get their bin/ dirs (hooks now resolve)

ls ~/.claude/skills/careful/bin/   # must show check-careful.sh or equivalent
ls ~/.claude/skills/freeze/bin/    # must show check-freeze.sh

Scenario 5: Upgrade from old install (symlinks overwrite old state)

# Manually break the state first
rm ~/.claude/skills/review/checklist.md
./setup --host claude
# checklist.md must be restored
ls ~/.claude/skills/review/checklist.md

Scenario 6: bun test passes (no regressions)

bun test
# 3 known pre-existing failures (document-generate doc inventory, gbrain CLI not in PATH)
# All other tests pass — including the 2 new unit tests for this fix

Notes

• Pure bash change — no TypeScript, no binaries, no config changes
• The .tmpl exclusion is implicit: glob is *.md, and SKILL.md.tmpl ends in .tmpl not .md
• Windows MSYS users running ./setup: the same fix applies but MSYS ln -s creates copies (per Windows (MSYS/Git Bash): link_claude_skill_dirs creates file copies, not symlinks — skills do not update on git pull #1456/v1.33.3.0 fix: use file copies instead of symlinks on Windows for skill installation #1462); this PR does not change that behavior

🤖 Generated with Claude Code