diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 4af2e889..2fce6375 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -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 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 When you're editing gstack skills and want to test them by actually using gstack diff --git a/README.md b/README.md index f95a89fc..c0a5f0b6 100644 --- a/README.md +++ b/README.md @@ -174,12 +174,10 @@ The models are getting better fast. The people who figure out how to work with t | Doc | What it covers | |-----|---------------| -| [Skill Deep Dives](docs/skills.md) | Philosophy, examples, and workflow for every skill | -| [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` | +| [Skill Deep Dives](docs/skills.md) | Philosophy, examples, and workflow for every skill (includes Greptile integration) | | [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 | ## Troubleshooting diff --git a/docs/contributor-mode.md b/docs/contributor-mode.md deleted file mode 100644 index 0989de2a..00000000 --- a/docs/contributor-mode.md +++ /dev/null @@ -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. diff --git a/docs/greptile.md b/docs/greptile.md deleted file mode 100644 index 2875fa1f..00000000 --- a/docs/greptile.md +++ /dev/null @@ -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. diff --git a/docs/skills.md b/docs/skills.md index fa45adba..16045860 100644 --- a/docs/skills.md +++ b/docs/skills.md @@ -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. + +--- + +## 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.