mirror of
https://github.com/garrytan/gstack.git
synced 2026-05-02 11:45:20 +02:00
docs: rename DEVELOPING_GSTACK.md to CONTRIBUTING.md
Rewritten as a contributor-friendly guide instead of a dry plan doc. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
Garry Tan
@@ -0,0 +1,85 @@
|
||||
# Contributing to gstack
|
||||
|
||||
Thanks for wanting to make gstack better. Whether you're fixing a typo in a skill prompt or building an entirely new workflow, this guide will get you up and running fast.
|
||||
|
||||
## Quick start
|
||||
|
||||
```bash
|
||||
bin/dev-setup # activate dev mode — skills resolve from your working tree
|
||||
```
|
||||
|
||||
That's it. Edit any `SKILL.md`, run the skill in Claude Code (e.g. `/review`), and your changes take effect immediately. No copying, no deploying, no restarting.
|
||||
|
||||
When you're done:
|
||||
|
||||
```bash
|
||||
bin/dev-teardown # deactivate — back to your global install
|
||||
```
|
||||
|
||||
## How dev mode works
|
||||
|
||||
Claude Code discovers skills from `.claude/skills/` (project-local) or `~/.claude/skills/` (global). `bin/dev-setup` creates a local `.claude/skills/` with symlinks pointing back to your working tree, so Claude Code picks up your edits live.
|
||||
|
||||
```
|
||||
gstack/ <- your working tree
|
||||
├── .claude/skills/ <- created by dev-setup (gitignored)
|
||||
│ ├── gstack -> ../../ <- symlink back to repo root
|
||||
│ ├── review -> gstack/review
|
||||
│ ├── ship -> gstack/ship
|
||||
│ └── ... <- one symlink per skill
|
||||
├── review/
|
||||
│ └── SKILL.md <- edit this, test with /review
|
||||
├── ship/
|
||||
│ └── SKILL.md
|
||||
├── browse/
|
||||
│ ├── src/ <- TypeScript source
|
||||
│ └── dist/ <- compiled binary (gitignored)
|
||||
└── ...
|
||||
```
|
||||
|
||||
## Day-to-day workflow
|
||||
|
||||
```bash
|
||||
# 1. Enter dev mode
|
||||
bin/dev-setup
|
||||
|
||||
# 2. Edit a skill
|
||||
vim review/SKILL.md
|
||||
|
||||
# 3. Test it in Claude Code — changes are live
|
||||
# > /review
|
||||
|
||||
# 4. Editing browse source? Rebuild the binary
|
||||
bun run build
|
||||
|
||||
# 5. Done for the day? Tear down
|
||||
bin/dev-teardown
|
||||
```
|
||||
|
||||
## Running tests
|
||||
|
||||
```bash
|
||||
bun test # all tests (browse integration + snapshot)
|
||||
bun run dev <cmd> # run CLI in dev mode, e.g. bun run dev goto https://example.com
|
||||
bun run build # compile binary to browse/dist/browse
|
||||
```
|
||||
|
||||
Tests run against the browse binary directly — they don't require dev mode.
|
||||
|
||||
## Things to know
|
||||
|
||||
- **SKILL.md changes are instant.** They're just Markdown. Edit, save, invoke.
|
||||
- **Browse source changes need a rebuild.** If you touch `browse/src/*.ts`, run `bun run build`.
|
||||
- **Dev mode shadows your global install.** Project-local skills take priority over `~/.claude/skills/gstack`. `bin/dev-teardown` restores the global one.
|
||||
- **Conductor workspaces are independent.** Each workspace is its own clone. Run `bin/dev-setup` in the one you're working in.
|
||||
- **`.claude/skills/` is gitignored.** The symlinks never get committed.
|
||||
|
||||
## Shipping your changes
|
||||
|
||||
When you're happy with your skill edits:
|
||||
|
||||
```bash
|
||||
/ship
|
||||
```
|
||||
|
||||
This runs tests, reviews the diff, bumps the version, and opens a PR. See `ship/SKILL.md` for the full workflow.
|
||||
@@ -1,93 +0,0 @@
|
||||
# Developing gstack
|
||||
|
||||
How to test gstack skills from within the gstack repo itself.
|
||||
|
||||
## The problem
|
||||
|
||||
Claude Code discovers skills from `.claude/skills/` (project-local) or `~/.claude/skills/` (global). When developing gstack, you want to edit a SKILL.md and test it immediately — without copying files or deploying to the global install.
|
||||
|
||||
## Dev mode
|
||||
|
||||
```bash
|
||||
bin/dev-setup # activate — skills resolve from this working tree
|
||||
bin/dev-teardown # deactivate — back to global install
|
||||
```
|
||||
|
||||
### What `bin/dev-setup` does
|
||||
|
||||
1. Creates `.claude/skills/` inside the repo (gitignored)
|
||||
2. Symlinks `.claude/skills/gstack` → repo root
|
||||
3. Runs `./setup` which:
|
||||
- Builds the browse binary (if needed)
|
||||
- Creates individual skill symlinks: `.claude/skills/review` → `.claude/skills/gstack/review`, etc.
|
||||
|
||||
After this, Claude Code in this directory discovers skills from your working tree. Edit `review/SKILL.md`, run `/review` — changes take effect immediately.
|
||||
|
||||
### What `bin/dev-teardown` does
|
||||
|
||||
Removes all symlinks under `.claude/skills/` and cleans up the directory. Your global install (`~/.claude/skills/gstack`) becomes active again.
|
||||
|
||||
## Directory structure in dev mode
|
||||
|
||||
```
|
||||
gstack/ ← your working tree (repo root)
|
||||
├── .claude/ ← gitignored
|
||||
│ └── skills/
|
||||
│ ├── gstack → ../../ ← symlink back to repo root
|
||||
│ ├── review → gstack/review
|
||||
│ ├── ship → gstack/ship
|
||||
│ ├── browse → gstack/browse
|
||||
│ ├── qa → gstack/qa
|
||||
│ ├── retro → gstack/retro
|
||||
│ ├── plan-ceo-review → gstack/plan-ceo-review
|
||||
│ ├── plan-eng-review → gstack/plan-eng-review
|
||||
│ └── setup-browser-cookies → gstack/setup-browser-cookies
|
||||
├── review/
|
||||
│ ├── SKILL.md ← edit this, test with /review
|
||||
│ ├── checklist.md
|
||||
│ └── greptile-triage.md
|
||||
├── ship/
|
||||
│ └── SKILL.md
|
||||
├── browse/
|
||||
│ ├── SKILL.md
|
||||
│ ├── src/ ← TypeScript source
|
||||
│ └── dist/ ← compiled binary (gitignored)
|
||||
└── ...
|
||||
```
|
||||
|
||||
## Workflow
|
||||
|
||||
```bash
|
||||
# 1. Start dev mode
|
||||
bin/dev-setup
|
||||
|
||||
# 2. Edit a skill
|
||||
vim review/SKILL.md
|
||||
|
||||
# 3. Test it — Claude Code picks up changes immediately
|
||||
# (in Claude Code): /review
|
||||
|
||||
# 4. Edit browse source? Rebuild the binary
|
||||
bun run build
|
||||
|
||||
# 5. Done developing? Tear down
|
||||
bin/dev-teardown
|
||||
```
|
||||
|
||||
## Gotchas
|
||||
|
||||
- **Project-local skills override global.** While dev mode is active, the global install at `~/.claude/skills/gstack` is shadowed. `bin/dev-teardown` restores it.
|
||||
- **Browse binary changes need a rebuild.** SKILL.md changes are instant (they're just Markdown). But if you edit `browse/src/*.ts`, run `bun run build` to recompile.
|
||||
- **`.claude/` is gitignored.** The dev symlinks never get committed. This is intentional.
|
||||
- **Conductor workspaces.** Each Conductor workspace is an independent clone. Run `bin/dev-setup` in the workspace you're developing in. Other workspaces are unaffected.
|
||||
- **Don't mix dev and global.** If you have dev mode active and also update the global install, the project-local one wins. Tear down first if you want to test the global install.
|
||||
|
||||
## Running tests
|
||||
|
||||
```bash
|
||||
bun test # all tests (browse integration + snapshot)
|
||||
bun run dev <cmd> # run CLI in dev mode, e.g. bun run dev goto https://example.com
|
||||
bun run build # compile binary to browse/dist/browse
|
||||
```
|
||||
|
||||
Tests don't require dev mode — they test the browse binary directly, not the skill prompts.
|
||||
Reference in New Issue
Block a user