From 6314e743994af84fa5280df8f5a692660ff01d3b Mon Sep 17 00:00:00 2001 From: Garry Tan Date: Fri, 27 Mar 2026 09:07:29 -0600 Subject: [PATCH] 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 --- CLAUDE.md | 6 +++++ CONTRIBUTING.md | 62 ++++++++++++++++++++++++++++++++++++++----------- 2 files changed, 55 insertions(+), 13 deletions(-) diff --git a/CLAUDE.md b/CLAUDE.md index b7771f1e..e1ae6c65 100644 --- a/CLAUDE.md +++ b/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). diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index c4c31571..b6dba47c 100644 --- a/CONTRIBUTING.md +++ b/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 -│ ├── ship -> gstack/ship +│ ├── review -> gstack/review <- short names (default) +│ ├── 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 -template, run `bun run gen:skill-docs`, and the next `/review` or `/qa` call picks -it up immediately. +### Step 2: Run setup to create per-skill symlinks -**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/ -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)