mirror of
https://github.com/garrytan/gstack.git
synced 2026-05-08 21:49:45 +08:00
feat: contributor mode, session awareness, recommendation format (#90)
* feat: contributor mode, session awareness, universal RECOMMENDATION format
- Rename {{UPDATE_CHECK}} → {{PREAMBLE}} across all 10 skill templates
- Add session tracking (touch ~/.gstack/sessions/$PPID, count active sessions)
- ELI16 mode when 3+ concurrent sessions detected (re-ground user on context)
- Contributor mode: auto-file field reports to ~/.gstack/contributor-logs/
- Universal AskUserQuestion format: context → question → RECOMMENDATION → options
- Update plan-ceo-review and plan-eng-review to reference preamble baseline
- Add vendored symlink awareness section to CLAUDE.md
- Rewrite CONTRIBUTING.md with contributor workflow and cross-project testing
- Add tests for contributor mode and session awareness in generated output
- Add E2E eval for contributor mode report filing
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* feat: add Enum & Value Completeness to /review critical checklist
New CRITICAL review category that traces new enum values, status strings,
and type constants through every consumer outside the diff. Catches the
class of bugs where a new value is added but not handled in all switch/case
chains, allowlists, or frontend-backend contracts.
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* chore: bump v0.4.1, user-facing changelog, update qa-only template and architecture docs
Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
* docs: add CHANGELOG style guide — user-facing, sell the feature
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* docs: rewrite v0.4.1 changelog to be user-facing and sell the features
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* feat: add evals for RECOMMENDATION format, session awareness, and enum completeness
Free tests (Tier 1): RECOMMENDATION format + session awareness in all
preamble SKILL.md files, enum completeness checklist structure and CRITICAL
classification.
E2E eval: /review catches missed enum handlers when a new status value
is added but not handled in case/switch and notify methods.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* feat: add E2E eval for session awareness ELI16 mode
Stubs _SESSIONS=4, gives agent a decision point on feature/add-payments
branch, verifies the output re-grounds the user with project, branch,
context, and RECOMMENDATION — the ELI16 mode behavior for 3+ sessions.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
* fix: contributor mode eval marked FAIL due to expected browse error
The test intentionally runs a nonexistent binary to trigger contributor
mode. The session runner's browse error detection catches "no such file
or directory...browse" and sets browseErrors, causing recordE2E to mark
passed=false. Override passed to check only exitReason since the browse
error is the expected scenario.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---------
Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
Garry Tan
120
CONTRIBUTING.md
120
CONTRIBUTING.md
@@ -20,9 +20,44 @@ Now edit any `SKILL.md`, invoke it in Claude Code (e.g. `/review`), and see your
|
||||
bin/dev-teardown # deactivate — back to your global install
|
||||
```
|
||||
|
||||
## How dev mode works
|
||||
## Contributor mode
|
||||
|
||||
`bin/dev-setup` creates a `.claude/skills/` directory inside the repo (gitignored) and fills it with symlinks pointing back to your working tree. Claude Code sees the local `skills/` first, so your edits win over the global install.
|
||||
Contributor mode is for people who want to fix gstack when it annoys them. Enable it
|
||||
and Claude Code will automatically log issues to `~/.gstack/contributor-logs/` as you
|
||||
work — what you were doing, what went wrong, repro steps, raw output.
|
||||
|
||||
```bash
|
||||
~/.claude/skills/gstack/bin/gstack-config set gstack_contributor true
|
||||
```
|
||||
|
||||
The logs are for **you**. When something bugs you enough to fix, the report is
|
||||
already written. Fork gstack, symlink your fork into the project where you hit
|
||||
the issue, fix it, and open a PR.
|
||||
|
||||
### The contributor workflow
|
||||
|
||||
1. **Hit friction while using gstack** — contributor mode logs it automatically
|
||||
2. **Check your logs:** `ls ~/.gstack/contributor-logs/`
|
||||
3. **Fork and clone gstack** (if you haven't already)
|
||||
4. **Symlink your fork into the project where you hit the bug:**
|
||||
```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
|
||||
```
|
||||
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**
|
||||
|
||||
This is the best way to contribute: fix gstack while doing your real work, in the
|
||||
project where you actually felt the pain.
|
||||
|
||||
## Working on gstack inside the gstack repo
|
||||
|
||||
When you're editing gstack skills and want to test them by actually using gstack
|
||||
in the same repo, `bin/dev-setup` wires this up. It creates `.claude/skills/`
|
||||
symlinks (gitignored) pointing back to your working tree, so Claude Code uses
|
||||
your local edits instead of the global install.
|
||||
|
||||
```
|
||||
gstack/ <- your working tree
|
||||
@@ -207,69 +242,42 @@ When Conductor creates a new workspace, `bin/dev-setup` runs automatically. It d
|
||||
- **`.env` propagates across worktrees.** Set it once in the main repo, all Conductor workspaces get it.
|
||||
- **`.claude/skills/` is gitignored.** The symlinks never get committed.
|
||||
|
||||
## Testing a branch in another repo
|
||||
## Testing your changes in a real project
|
||||
|
||||
When you're developing gstack in one workspace and want to test your branch in a
|
||||
different project (e.g. testing browse changes against your real app), there are
|
||||
two cases depending on how gstack is installed in that project.
|
||||
**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:
|
||||
|
||||
### Global install only (no `.claude/skills/gstack/` in the project)
|
||||
```bash
|
||||
# In your core project
|
||||
ln -sfn /path/to/your/gstack-checkout .claude/skills/gstack
|
||||
cd .claude/skills/gstack && bun install && bun run build
|
||||
```
|
||||
|
||||
Point your global install at the branch:
|
||||
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.
|
||||
|
||||
**To go back to the stable global install**, just remove the symlink:
|
||||
|
||||
```bash
|
||||
rm .claude/skills/gstack
|
||||
```
|
||||
|
||||
Claude Code falls back to `~/.claude/skills/gstack/` automatically.
|
||||
|
||||
### Alternative: point your global install at a branch
|
||||
|
||||
If you don't want per-project symlinks, you can switch the global install:
|
||||
|
||||
```bash
|
||||
cd ~/.claude/skills/gstack
|
||||
git fetch origin
|
||||
git checkout origin/<branch> # e.g. origin/v0.3.2
|
||||
bun install # in case deps changed
|
||||
bun run build # rebuild the binary
|
||||
git checkout origin/<branch>
|
||||
bun install && bun run build
|
||||
```
|
||||
|
||||
Now open Claude Code in the other project — it picks up skills from
|
||||
`~/.claude/skills/` automatically. To go back to main when you're done:
|
||||
|
||||
```bash
|
||||
cd ~/.claude/skills/gstack
|
||||
git checkout main && git pull
|
||||
bun run build
|
||||
```
|
||||
|
||||
### Vendored project copy (`.claude/skills/gstack/` checked into the project)
|
||||
|
||||
Some projects vendor gstack by copying it into the repo (no `.git` inside the
|
||||
copy). Project-local skills take priority over global, so you need to update
|
||||
the vendored copy too. This is a three-step process:
|
||||
|
||||
1. **Update your global install to the branch** (so you have the source):
|
||||
```bash
|
||||
cd ~/.claude/skills/gstack
|
||||
git fetch origin
|
||||
git checkout origin/<branch> # e.g. origin/v0.3.2
|
||||
bun install && bun run build
|
||||
```
|
||||
|
||||
2. **Replace the vendored copy** in the other project:
|
||||
```bash
|
||||
cd /path/to/other-project
|
||||
|
||||
# Remove old skill symlinks and vendored copy
|
||||
for s in browse plan-ceo-review plan-eng-review review ship retro qa setup-browser-cookies; do
|
||||
rm -f .claude/skills/$s
|
||||
done
|
||||
rm -rf .claude/skills/gstack
|
||||
|
||||
# Copy from global install (strips .git so it stays vendored)
|
||||
cp -Rf ~/.claude/skills/gstack .claude/skills/gstack
|
||||
rm -rf .claude/skills/gstack/.git
|
||||
|
||||
# Rebuild binary and re-create skill symlinks
|
||||
cd .claude/skills/gstack && ./setup
|
||||
```
|
||||
|
||||
3. **Test your changes** — open Claude Code in that project and use the skills.
|
||||
|
||||
To revert to main later, repeat steps 1-2 with `git checkout main && git pull`
|
||||
instead of `git checkout origin/<branch>`.
|
||||
This affects all projects. To revert: `git checkout main && git pull && bun run build`.
|
||||
|
||||
## Shipping your changes
|
||||
|
||||
|
||||
Reference in New Issue
Block a user