docs: update CONTRIBUTING + CLAUDE.md for prefix-aware vendoring

- CONTRIBUTING: vendoring now includes ./setup step for per-skill symlinks
- CONTRIBUTING: prefix choice documented in contributor workflow + dev diagram
- CONTRIBUTING: switching prefix mode section added
- CLAUDE.md: vendored symlink awareness section covers prefix setting

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

CLAUDE.md

@@ -171,6 +171,12 @@ symlink or a real copy. If it's a symlink to your working directory, be aware th
 - During large refactors, remove the symlink (`rm .claude/skills/gstack`) so the
   global install at `~/.claude/skills/gstack/` is used instead
 
+**Prefix setting:** Skill symlinks use either short names (`qa -> gstack/qa`) or
+namespaced (`gstack-qa -> gstack/qa`), controlled by `skill_prefix` in
+`~/.gstack/config.yaml`. When vendoring into a project, run `./setup` after
+symlinking to create the per-skill symlinks with your preferred naming. Pass
+`--no-prefix` or `--prefix` to skip the interactive prompt.
+
 **For plan reviews:** When reviewing plans that modify skill templates or the
 gen-skill-docs pipeline, consider whether the changes should be tested in isolation
 before going live (especially if the user is actively using gstack in other windows).

CONTRIBUTING.md

@@ -45,8 +45,10 @@ the issue, fix it, and open a PR.
    ```bash
    # In your core project (the one where gstack annoyed you)
    ln -sfn /path/to/your/gstack-fork .claude/skills/gstack
-   cd .claude/skills/gstack && bun install && bun run build
+   cd .claude/skills/gstack && bun install && bun run build && ./setup
    ```
+   Setup creates the per-skill symlinks (`qa -> gstack/qa`, etc.) and asks your
+   prefix preference. Pass `--no-prefix` to skip the prompt and use short names.
 5. **Fix the issue** — your changes are live immediately in this project
 6. **Test by actually using gstack** — do the thing that annoyed you, verify it's fixed
 7. **Open a PR from your fork**
@@ -69,8 +71,8 @@ your local edits instead of the global install.
 gstack/                          <- your working tree
 ├── .claude/skills/              <- created by dev-setup (gitignored)
 │   ├── gstack -> ../../         <- symlink back to repo root
-│   ├── review -> gstack/review
+│   ├── review -> gstack/review  <- short names (default)
-│   ├── ship -> gstack/ship
+│   ├── ship -> gstack/ship      <- or gstack-review, gstack-ship if --prefix
 │   └── ...                      <- one symlink per skill
 ├── review/
 │   └── SKILL.md                 <- edit this, test with /review
@@ -82,6 +84,10 @@ gstack/                          <- your working tree
 └── ...
 ```
 
+Skill symlink names depend on your prefix setting (`~/.gstack/config.yaml`).
+Short names (`/review`, `/ship`) are the default. Run `./setup --prefix` if you
+prefer namespaced names (`/gstack-review`, `/gstack-ship`).
+
 ## Day-to-day workflow
 
 ```bash
@@ -309,25 +315,55 @@ When Conductor creates a new workspace, `bin/dev-setup` runs automatically. It d
 
 **This is the recommended way to develop gstack.** Symlink your gstack checkout
 into the project where you actually use it, so your changes are live while you
-do real work:
+do real work.
+
+### Step 1: Symlink your checkout
 
 ```bash
-# In your core project
+# In your core project (not the gstack repo)
 ln -sfn /path/to/your/gstack-checkout .claude/skills/gstack
-cd .claude/skills/gstack && bun install && bun run build
 ```
 
-Now every gstack skill invocation in this project uses your working tree. Edit a
+### Step 2: Run setup to create per-skill symlinks
-template, run `bun run gen:skill-docs`, and the next `/review` or `/qa` call picks
-it up immediately.
 
-**To go back to the stable global install**, just remove the symlink:
+The `gstack` symlink alone isn't enough. Claude Code discovers skills through
+individual symlinks (`qa -> gstack/qa`, `ship -> gstack/ship`, etc.), not through
+the `gstack/` directory itself. Run `./setup` to create them:
+
+```bash
+cd .claude/skills/gstack && bun install && bun run build && ./setup
+```
+
+Setup will ask whether you want short names (`/qa`) or namespaced (`/gstack-qa`).
+Your choice is saved to `~/.gstack/config.yaml` and remembered for future runs.
+To skip the prompt, pass `--no-prefix` (short names) or `--prefix` (namespaced).
+
+### Step 3: Develop
+
+Edit a template, run `bun run gen:skill-docs`, and the next `/review` or `/qa`
+call picks it up immediately. No restart needed.
+
+### Going back to the stable global install
+
+Remove the project-local symlink. Claude Code falls back to `~/.claude/skills/gstack/`:
 
 ```bash
 rm .claude/skills/gstack
 ```
 
-Claude Code falls back to `~/.claude/skills/gstack/` automatically.
+The per-skill symlinks (`qa`, `ship`, etc.) still point to `gstack/...`, so they'll
+resolve to the global install automatically.
+
+### Switching prefix mode
+
+If you vendored gstack with one prefix setting and want to switch:
+
+```bash
+cd .claude/skills/gstack && ./setup --no-prefix   # switch to /qa, /ship
+cd .claude/skills/gstack && ./setup --prefix       # switch to /gstack-qa, /gstack-ship
+```
+
+Setup cleans up the old symlinks automatically. No manual cleanup needed.
 
 ### Alternative: point your global install at a branch
 
@@ -337,10 +373,10 @@ If you don't want per-project symlinks, you can switch the global install:
 cd ~/.claude/skills/gstack
 git fetch origin
 git checkout origin/<branch>
-bun install && bun run build
+bun install && bun run build && ./setup
 ```
 
-This affects all projects. To revert: `git checkout main && git pull && bun run build`.
+This affects all projects. To revert: `git checkout main && git pull && bun run build && ./setup`.
 
 ## Community PR triage (wave process)