hai/gstack
1
0
Fork 0
mirror of https://github.com/garrytan/gstack.git synced 2026-05-20 19:29:56 +08:00
Code Issues Packages Projects Releases Wiki Activity

docs: consolidate — roll contributor-mode into CONTRIBUTING, greptile into skills

Browse Source 
- docs/contributor-mode.md → merged into CONTRIBUTING.md (session awareness section)
- docs/greptile.md → merged into docs/skills.md (Greptile integration section)
- Reordered docs table: Skills > Architecture > Browser > Contributing > Changelog

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
Garry Tan
2026-03-17 14:33:18 -07:00
parent 43ba86cfe8
commit 3a82d3c1f7
5 changed files with 67 additions and 118 deletions
Download Patch File Download Diff File Expand all files Collapse all files

4
CONTRIBUTING.md
View File

@@ -54,6 +54,10 @@ the issue, fix it, and open a PR.
This is the best way to contribute: fix gstack while doing your real work, in the This is the best way to contribute: fix gstack while doing your real work, in the
project where you actually felt the pain. project where you actually felt the pain.
### Session awareness
When you have 3+ gstack sessions open simultaneously, every question tells you which project, which branch, and what's happening. No more staring at a question thinking "wait, which window is this?" The format is consistent across all 13 skills.
## Working on gstack inside the gstack repo ## Working on gstack inside the gstack repo
When you're editing gstack skills and want to test them by actually using gstack When you're editing gstack skills and want to test them by actually using gstack

8
README.md
View File

@@ -174,12 +174,10 @@ The models are getting better fast. The people who figure out how to work with t
| Doc | What it covers | | Doc | What it covers |
|-----|---------------| |-----|---------------|
| [Skill Deep Dives](docs/skills.md) | Philosophy, examples, and workflow for every skill | | [Skill Deep Dives](docs/skills.md) | Philosophy, examples, and workflow for every skill (includes Greptile integration) |
| [Greptile Integration](docs/greptile.md) | PR review triage with [Greptile](https://greptile.com) |
| [How to Contribute](docs/contributor-mode.md) | How to help improve gstack |
| [Browser Reference](BROWSER.md) | Full command reference for `/browse` |
| [Architecture](ARCHITECTURE.md) | Design decisions and system internals | | [Architecture](ARCHITECTURE.md) | Design decisions and system internals |
| [Contributing](CONTRIBUTING.md) | Dev setup, testing, and dev mode | | [Browser Reference](BROWSER.md) | Full command reference for `/browse` |
| [Contributing](CONTRIBUTING.md) | Dev setup, testing, contributor mode, and dev mode |
| [Changelog](CHANGELOG.md) | What's new in every version | | [Changelog](CHANGELOG.md) | What's new in every version |
## Troubleshooting ## Troubleshooting

37
docs/contributor-mode.md
View File

@@ -1,37 +0,0 @@
# Contributor Mode
gstack is open source. If something annoys you, you can fix it yourself. Contributor mode makes that easier by automatically detecting friction and writing up what went wrong.
## Enable it
```
gstack-config set gstack_contributor true
```
## How it works
At the end of each major workflow step, the agent reflects on the gstack tooling it just used. It rates the experience 0-10. If it wasn't a 10, it thinks about why. If there's an obvious, actionable bug or an insightful improvement, it files a **field report** to `~/.gstack/contributor-logs/`.
Reports include:
- What the user/agent was trying to do
- What actually happened instead
- A 0-10 rating with one-sentence explanation
- Steps to reproduce
- Raw output (the actual error or unexpected behavior)
- "What would make this a 10" — one sentence focusing on the actionable fix
## Calibration
The bar is set at real-but-small bugs. Example: `$B js "await fetch(...)"` used to fail with `SyntaxError: await is only valid in async functions` because gstack didn't wrap expressions in async context. The input was reasonable, gstack should have handled it — that's worth filing.
Things NOT worth filing: your app's bugs, network errors to your URL, auth failures on your site, your own JS logic bugs. Those aren't gstack's fault.
## What to do with reports
Browse `~/.gstack/contributor-logs/` periodically. Each report is a self-contained bug report. Fork gstack, fix the issue, and submit a PR. Max 3 reports per session to avoid noise.
## Session awareness
When you have 3+ gstack sessions open simultaneously, every question tells you which project, which branch, and what's happening. No more staring at a question thinking "wait, which window is this?"
Every question — in every skill, even in a single session — states the project and branch, explains the problem in plain English, and gives an opinionated recommendation. The format is consistent across all 13 skills.

76
docs/greptile.md
View File

@@ -1,76 +0,0 @@
# Greptile Integration
[Greptile](https://greptile.com) is a YC company that reviews your PRs automatically. It catches real bugs — race conditions, security issues, things that pass CI and blow up in production. It has genuinely saved my ass more than once. I love these guys.
## Setup
Install Greptile on your GitHub repo at [greptile.com](https://greptile.com) — it takes about 30 seconds. Once it's reviewing your PRs, gstack picks up its comments automatically. No additional configuration.
## How it works
The problem with any automated reviewer is triage. Greptile is good, but not every comment is a real issue. Some are false positives. Some flag things you already fixed three commits ago. Without a triage layer, the comments pile up and you start ignoring them — which defeats the purpose.
gstack solves this. `/review` and `/ship` are now Greptile-aware. They read Greptile's comments, classify each one, and take action:
- **Valid issues** get added to the critical findings and fixed before shipping
- **Already-fixed issues** get an auto-reply acknowledging the catch
- **False positives** get pushed back — you confirm, and a reply goes out explaining why it's wrong
The result is a two-layer review: Greptile catches things asynchronously on the PR, then `/review` and `/ship` triage those findings as part of the normal workflow. Nothing falls through the cracks.
## Learning from history
Every false positive you confirm gets saved to `~/.gstack/greptile-history.md`. Future runs auto-skip known FP patterns for your codebase. And `/retro` tracks Greptile's batting average over time — so you can see whether the signal-to-noise ratio is improving.
## Two-tier reply system
- **Tier 1 (friendly):** First response to a comment. Includes inline diff, explanation, and evidence.
- **Tier 2 (firm):** When Greptile re-flags the same issue after a prior reply. Full evidence chain + re-rank request.
Every reply includes evidence — inline diffs, code references, suggested severity re-ranking. No vague one-line replies.
## Example
```
You: /ship
Claude: [syncs main, runs tests, pre-landing review...]
Greptile found 3 comments on this PR:
[VALID] app/services/payment_service.rb:47 — Race condition:
concurrent charges can double-debit. Recommend DB-level advisory
lock around the charge block.
→ https://github.com/you/app/pull/42#discussion_r123
[ALREADY FIXED] app/models/user.rb:12 — Missing null check
on email before downcase.
→ Already fixed in commit abc1234. Auto-replying.
[FALSE POSITIVE] lib/auth.rb:88 — "Token comparison should
use constant-time comparison." We already use
ActiveSupport::SecurityUtils.secure_compare here.
→ https://github.com/you/app/pull/42#discussion_r125
Fixing the race condition in payment_service.rb...
Applied advisory lock. Committed: fix: address Greptile
review — advisory lock on concurrent charges
The auth token comment is a false positive — we're already
using secure_compare.
Options for the false positive:
A) Reply to Greptile explaining (recommended)
B) Fix it anyway
C) Ignore
You: A
Claude: Replied to Greptile. Re-running tests after the fix...
All tests pass. Continuing to version bump.
[creates PR with Greptile Review section in body]
PR: https://github.com/you/app/pull/42
```
Three Greptile comments. One real fix. One auto-acknowledged. One false positive pushed back with a reply. Total extra time: about 30 seconds. And the PR body has the full audit trail.

60
docs/skills.md
View File

@@ -587,3 +587,63 @@ Claude: Analyzing 21 files changed across 3 commits. Found 8 documentation files
``` ```
It also polishes CHANGELOG voice (without ever overwriting entries), cleans up completed TODOS, checks cross-doc consistency, and asks about VERSION bumps only when appropriate. It also polishes CHANGELOG voice (without ever overwriting entries), cleans up completed TODOS, checks cross-doc consistency, and asks about VERSION bumps only when appropriate.
---
## Greptile integration
[Greptile](https://greptile.com) is a YC company that reviews your PRs automatically. It catches real bugs — race conditions, security issues, things that pass CI and blow up in production. It has genuinely saved my ass more than once. I love these guys.
### Setup
Install Greptile on your GitHub repo at [greptile.com](https://greptile.com) — it takes about 30 seconds. Once it's reviewing your PRs, gstack picks up its comments automatically. No additional configuration.
### How it works
The problem with any automated reviewer is triage. Greptile is good, but not every comment is a real issue. Some are false positives. Some flag things you already fixed three commits ago. Without a triage layer, the comments pile up and you start ignoring them — which defeats the purpose.
gstack solves this. `/review` and `/ship` are now Greptile-aware. They read Greptile's comments, classify each one, and take action:
- **Valid issues** get added to the critical findings and fixed before shipping
- **Already-fixed issues** get an auto-reply acknowledging the catch
- **False positives** get pushed back — you confirm, and a reply goes out explaining why it's wrong
The result is a two-layer review: Greptile catches things asynchronously on the PR, then `/review` and `/ship` triage those findings as part of the normal workflow. Nothing falls through the cracks.
### Learning from history
Every false positive you confirm gets saved to `~/.gstack/greptile-history.md`. Future runs auto-skip known FP patterns for your codebase. And `/retro` tracks Greptile's batting average over time — so you can see whether the signal-to-noise ratio is improving.
### Example
```
You: /ship
Claude: [syncs main, runs tests, pre-landing review...]
Greptile found 3 comments on this PR:
[VALID] app/services/payment_service.rb:47 — Race condition:
concurrent charges can double-debit. Recommend DB-level advisory
lock around the charge block.
[ALREADY FIXED] app/models/user.rb:12 — Missing null check
on email before downcase.
→ Already fixed in commit abc1234. Auto-replying.
[FALSE POSITIVE] lib/auth.rb:88 — "Token comparison should
use constant-time comparison." We already use
ActiveSupport::SecurityUtils.secure_compare here.
Fixing the race condition in payment_service.rb...
The auth token comment is a false positive.
Options: A) Reply to Greptile explaining B) Fix anyway C) Ignore
You: A
Claude: Replied to Greptile. All tests pass.
PR: github.com/you/app/pull/42
```
Three Greptile comments. One real fix. One auto-acknowledged. One false positive pushed back with a reply. Total extra time: about 30 seconds.