CalvinBackup/gstack
1
0
Fork 0
mirror of https://github.com/garrytan/gstack.git synced 2026-05-06 13:45:35 +02:00
Code Issues Packages Projects Releases Wiki Activity

docs: split README into lean intro + docs/ directory (gh CLI pattern)

Browse Source 
README: 875 → 243 lines. Keeps intro, skill table, demo, install, and
troubleshooting. All per-skill deep dives, Greptile integration guide,
and contributor mode docs moved to docs/ directory.

- docs/skills.md — full philosophy and examples for all 13 skills
- docs/greptile.md — Greptile setup and triage workflow
- docs/contributor-mode.md — how to enable and use contributor mode
- README now links to docs/ via Documentation table
- Updated skill table entries with latest features (fix-first, regression
  tests, test health, completeness gaps)
- Updated demo transcript with AUTO-FIXED, coverage audit, regression test

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
Garry Tan
2026-03-17 12:38:32 -07:00
parent 916efd6fa1
commit 1d360003a4
4 changed files with 716 additions and 661 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.md
+28 -661
View File
@@ -25,19 +25,19 @@ Thirteen opinionated workflow skills for [Claude Code](https://docs.anthropic.co
| `/plan-eng-review` | Eng manager / tech lead | Lock in architecture, data flow, diagrams, edge cases, and tests. |
| `/plan-design-review` | Senior product designer | Designer's eye audit. 80-item checklist, letter grades, AI Slop detection, DESIGN.md inference. Report only — never touches code. |
| `/design-consultation` | Design consultant | Build a complete design system from scratch. Browses competitors to get in the ballpark, proposes safe choices AND creative risks, generates realistic product mockups, and writes DESIGN.md. |
| `/review` | Paranoid staff engineer | Find the bugs that pass CI but blow up in production. Triages Greptile review comments. |
| `/review` | Paranoid staff engineer | Find the bugs that pass CI but blow up in production. Auto-fixes obvious issues. Triages Greptile review comments. Flags completeness gaps. |
| `/ship` | Release engineer | Sync main, run tests, audit coverage, resolve Greptile reviews, push, open PR. Auto-bootstraps test frameworks if your project doesn't have one. |
| `/browse` | QA engineer | Give the agent eyes. It logs in, clicks through your app, takes screenshots, catches breakage. Full QA pass in 60 seconds. |
| `/qa` | QA + fix engineer | Test app, find bugs, fix them with atomic commits, re-verify. Before/after health scores and ship-readiness summary. Three tiers: Quick, Standard, Exhaustive. |
| `/qa` | QA + fix engineer | Test app, find bugs, fix them with atomic commits, re-verify. Auto-generates regression tests for every fix. Three tiers: Quick, Standard, Exhaustive. |
| `/qa-only` | QA reporter | Report-only QA testing. Same methodology as /qa but never fixes anything. Use when you want a pure bug report without code changes. |
| `/qa-design-review` | Designer + frontend engineer | Same design audit as /plan-design-review, then fixes what it finds. Atomic `style(design):` commits, before/after screenshots, CSS-safe self-regulation. |
| `/setup-browser-cookies` | Session manager | Import cookies from your real browser (Comet, Chrome, Arc, Brave, Edge) into the headless session. Test authenticated pages without logging in manually. |
| `/retro` | Engineering manager | Team-aware retro: your deep-dive + per-person praise and growth opportunities for every contributor. |
| `/retro` | Engineering manager | Team-aware retro: your deep-dive + per-person praise and growth opportunities for every contributor. Tracks test health. |
| `/document-release` | Technical writer | Update README, ARCHITECTURE, CONTRIBUTING, and project docs to match what you just shipped. |
## Demo: one feature, five modes
**[Detailed skill guides with examples and philosophy](docs/skills.md)**
I start almost every feature in plan mode. I describe what I want to build, then use `/plan-ceo-review` to pressure-test whether I am even building the right thing. Only after the product direction is locked do I shift into engineering, review, ship, and test.
## Demo: one feature, five modes
```
You: [enter plan mode, describe the feature]
@@ -65,50 +65,33 @@ You: /review
Claude: Race condition: two tabs can overwrite cover-photo selection.
Trust boundary: pulling web data into draft generation creates
a prompt injection vector. Missing: orphan cleanup for failed uploads.
[AUTO-FIXED] 2 issues. 1 needs your input.
You: (fix the issues)
You: (fix the remaining issue)
You: /ship
Claude: [Syncs main, runs tests, pushes branch, opens PR — 6 tool calls, done]
Claude: [Syncs main, runs tests, coverage audit, pushes branch, opens PR]
Tests: 42 → 47 (+5 new). PR: github.com/you/app/pull/42
You: /qa
Claude: Analyzing branch diff... 8 files changed, 3 routes affected.
[Tests /listings/new, /listings/:id, /api/listings against localhost:3000]
All 3 routes working. Upload + enrichment flow passes end to end.
You: /setup-browser-cookies staging.myapp.com
Claude: Imported 8 cookies for staging.myapp.com from Chrome.
You: /qa https://staging.myapp.com --quick
Claude: [Smoke test: homepage + 5 pages, 30 seconds]
Health Score: 91/100. No critical issues. 1 medium: mobile nav overlap.
Regression test generated: test/qa-regression-001.test.ts
You: /plan-design-review https://staging.myapp.com
Claude: Design Score: B | AI Slop Score: C
"The site communicates competence but not confidence."
"I notice the spacing between sections is uniform — nothing feels important."
"The first 3 things my eye goes to are: the gradient hero, a 3-column
feature grid with icons in circles, and a cookie-cutter CTA."
"If I had to describe this in one word: template."
Top issues: generic typography (Inter everywhere), AI slop patterns
(3-column icon grid, purple gradient), flat heading scale.
Top issues: generic typography, AI slop patterns, flat heading scale.
[Full report with letter grades, 12 findings, inferred design system]
Want me to save this as your DESIGN.md?
You: /qa-design-review
Claude: [Runs the same audit, then fixes 8 design issues]
style(design): FINDING-001 — replace Inter with system font stack
style(design): FINDING-003 — add heading scale contrast
style(design): FINDING-007 — break 3-column grid into asymmetric layout
Design Score: B → A- | AI Slop Score: C → A
```
@@ -185,649 +168,25 @@ I want explicit gears.
These skills let me tell the model what kind of brain I want right now. I can switch cognitive modes on demand — founder, eng manager, paranoid reviewer, release machine. That is the unlock.
---
## `/plan-ceo-review`
This is my **founder mode**.
This is where I want the model to think with taste, ambition, user empathy, and a long time horizon. I do not want it taking the request literally. I want it asking a more important question first:
**What is this product actually for?**
I think of this as **Brian Chesky mode**.
The point is not to implement the obvious ticket. The point is to rethink the problem from the user's point of view and find the version that feels inevitable, delightful, and maybe even a little magical.
### Example
Say I am building a Craigslist-style listing app and I say:
> "Let sellers upload a photo for their item."
A weak assistant will add a file picker and save an image.
That is not the real product.
In `/plan-ceo-review`, I want the model to ask whether "photo upload" is even the feature. Maybe the real feature is helping someone create a listing that actually sells.
If that is the real job, the whole plan changes.
Now the model should ask:
* Can we identify the product from the photo?
* Can we infer the SKU or model number?
* Can we search the web and draft the title and description automatically?
* Can we pull specs, category, and pricing comps?
* Can we suggest which photo will convert best as the hero image?
* Can we detect when the uploaded photo is ugly, dark, cluttered, or low-trust?
* Can we make the experience feel premium instead of like a dead form from 2007?
That is what `/plan-ceo-review` does for me.
It does not just ask, "how do I add this feature?"
It asks, **"what is the 10-star product hiding inside this request?"**
Four modes, depending on what you need:
- **SCOPE EXPANSION** — dream big. The agent proposes the ambitious version. Every expansion is presented as an individual decision you opt into.
- **SELECTIVE EXPANSION** — hold your current scope as the baseline, but see what else is possible. The agent surfaces opportunities one by one — you cherry-pick the ones worth doing.
- **HOLD SCOPE** — maximum rigor on the existing plan. No expansions surfaced.
- **SCOPE REDUCTION** — find the minimum viable version. Cut everything else.
Visions and decisions are persisted to `~/.gstack/projects/` so they survive beyond the conversation. Exceptional visions can be promoted to `docs/designs/` in your repo for the team.
That is a very different kind of power.
---
## `/plan-eng-review`
This is my **eng manager mode**.
Once the product direction is right, I want a different kind of intelligence entirely. I do not want more sprawling ideation. I do not want more "wouldn't it be cool if." I want the model to become my best technical lead.
This mode should nail:
* architecture
* system boundaries
* data flow
* state transitions
* failure modes
* edge cases
* trust boundaries
* test coverage
And one surprisingly big unlock for me: **diagrams**.
LLMs get way more complete when you force them to draw the system. Sequence diagrams, state diagrams, component diagrams, data-flow diagrams, even test matrices. Diagrams force hidden assumptions into the open. They make hand-wavy planning much harder.
So `/plan-eng-review` is where I want the model to build the technical spine that can carry the product vision.
### Example
Take the same listing app example.
Let's say `/plan-ceo-review` already did its job. We decided the real feature is not just photo upload. It is a smart listing flow that:
* uploads photos
* identifies the product
* enriches the listing from the web
* drafts a strong title and description
* suggests the best hero image
Now `/plan-eng-review` takes over.
Now I want the model to answer questions like:
* What is the architecture for upload, classification, enrichment, and draft generation?
* Which steps happen synchronously, and which go to background jobs?
* Where are the boundaries between app server, object storage, vision model, search/enrichment APIs, and the listing database?
* What happens if upload succeeds but enrichment fails?
* What happens if product identification is low-confidence?
* How do retries work?
* How do we prevent duplicate jobs?
* What gets persisted when, and what can be safely recomputed?
And this is where I want diagrams — architecture diagrams, state models, data-flow diagrams, test matrices. Diagrams force hidden assumptions into the open. They make hand-wavy planning much harder.
That is `/plan-eng-review`.
Not "make the idea smaller."
**Make the idea buildable.**
---
## `/plan-design-review`
This is my **senior designer mode**.
Most developers cannot tell whether their site looks AI-generated. I could not, until I started paying attention. There is a growing class of sites that are functional but soulless — they work fine but scream "an AI built this and nobody with taste looked at it." Purple gradients, 3-column icon grids, uniform bubbly border-radius on everything, centered text on every section, decorative blobs floating in the background. The ChatGPT aesthetic.
`/plan-design-review` gives the agent a designer's eye.
It opens your site and reacts to it the way a Stripe or Linear designer would — immediately, viscerally, with opinions. The first output is a structured gut reaction: what the site communicates at a glance, what the eye is drawn to, and a one-word verdict. That is the most valuable part. Everything after is supporting evidence.
Then it extracts your actual design system by reading the CSS: how many fonts are you really using? What is your heading scale? How many colors? Is your spacing on a grid or arbitrary? It structures this as an **Inferred Design System** and offers to save it as a `DESIGN.md` — so now you have a design system you never had before, derived from what you actually shipped.
The audit covers 80 items across 10 categories. Typography, spacing, hierarchy, color, responsive design, interaction states, motion, content quality, performance feel, and — the headline feature — **AI Slop Detection**. Ten specific anti-patterns that mark a site as machine-generated.
Every finding gets a letter grade (A through F) per category. The report opens with two headline scores: **Design Score** and **AI Slop Score**. "Your site got a B on design but a D on AI Slop" tells you exactly where to focus.
### Example
```
You: /plan-design-review https://myapp.com
Claude: Design Score: C | AI Slop Score: D
"The site communicates generic SaaS energy."
"I notice the hero section uses a blue-to-purple gradient
with a 3-column feature grid below it — the single most
recognizable AI-generated layout pattern."
"The first 3 things my eye goes to are: the gradient, the
symmetrical icon grid, and a 'Get Started' button that
looks like every other 'Get Started' button."
"If I had to describe this in one word: template."
Inferred Design System:
- Fonts: Inter (body), Inter (headings) — 1 font family
- Colors: 14 unique non-gray colors (flag: >12)
- Heading scale: 36/24/18/16 — flat, no drama between sizes
- Spacing: mostly 16px and 24px — no rhythm
Top 5 Design Improvements:
1. Break the 3-column icon grid (High, AI Slop)
2. Add heading scale contrast — at least 2:1 ratio (High, Typography)
3. Replace uniform border-radius with intentional hierarchy (Medium, Spacing)
4. Kill the gradient hero — use a real image or bold typography (High, AI Slop)
5. Add a second font for headings — Inter-only reads as generic (Medium, Typography)
[Full report saved to .gstack/design-reports/]
Want me to save this inferred design system as your DESIGN.md?
```
This is report only — it never touches your code. Use `/qa-design-review` when you want it to fix what it finds.
---
## `/design-consultation`
This is my **design partner mode**.
`/plan-design-review` audits a site that already exists. `/design-consultation` is for when you have nothing yet — no design system, no font choices, no color palette. You are starting from zero and you want a senior designer to sit down with you and build the whole visual identity together.
It is a conversation, not a form. The agent asks about your product, your users, and your audience. It thinks about what your product needs to communicate — trust, speed, craft, warmth, whatever fits — and works backward from that to concrete choices. Then it proposes a complete, coherent design system: aesthetic direction, typography (3+ fonts with specific roles), color palette with hex values, spacing scale, layout approach, and motion strategy. Every recommendation comes with a rationale. Every choice reinforces every other choice.
But coherence is table stakes. Every dev tool dashboard looks the same — clean sans-serif, muted grays, a blue accent. They are all coherent. They are all forgettable. The difference between a product that looks "nice" and one that people actually recognize is the **deliberate creative risks**: the unexpected serif for headings, the bold accent nobody else in your category uses, the tighter spacing that makes your data feel authoritative instead of airy.
That is what `/design-consultation` is really about. It does not just propose a safe system. It proposes safe choices AND risks — and tells you which is which. "Here are the choices that keep you literate in your category. And here is where I think you should break from convention, and why." You pick which risks to take. The agent checks that the whole system still coheres either way.
If you want, the agent will browse your competitors' actual sites — take screenshots, analyze their fonts and colors and spacing — so you can see the landscape before you make choices. This is not about copying. It is about getting in the ballpark so you know what the conventions are, and then deciding which ones are worth breaking.
After you agree on the system, it generates an interactive HTML preview page — not just swatches and font samples, but realistic product pages. If you are building a dashboard, you see a dashboard with a sidebar, data tables, and stat cards. If you are building a marketing site, you see a hero section with real copy and a CTA. Everything rendered in your design system, with your product name, in light and dark mode. You see what your product could feel like before a single line of production code is written.
Then it writes `DESIGN.md` to your repo root — your project's design source of truth — and updates `CLAUDE.md` so every future Claude Code session respects the system. From that point on, `/qa-design-review` can audit against it, and any agent working on your frontend knows the rules.
```
You: /design-consultation
Claude: From the README, this looks like a developer analytics dashboard
for engineering teams. Sound right? Tell me about the feeling
you want — and would you like me to browse some competitors
first so we can see the landscape?
You: Yes, it's for eng managers. Show me what's out there.
Claude: [browses Linear, Vercel, Datadog, Posthog — takes screenshots]
Here's the landscape. They all converge on clean sans-serifs
and muted blue-gray palettes. Linear stands out with dark-first
and tight spacing. The rest feel interchangeable.
Here's my proposal — and where I'd play it safe vs. take risks:
AESTHETIC: Industrial/Utilitarian — data-first, every pixel earns its place
TYPOGRAPHY: Geist (body + UI), Instrument Serif (display), JetBrains Mono (data)
COLOR: Restrained — slate neutrals, single teal accent (#0D9488)
SPACING: 4px base, compact density
LAYOUT: Grid-disciplined, 12-column
MOTION: Minimal-functional — only transitions that aid comprehension
SAFE CHOICES (match category expectations):
Geist for body — your users already know this font from Vercel
Slate neutrals — warm grays feel right for data-heavy UIs
Grid-disciplined layout — dashboards need predictable alignment
RISKS (where you'd stand out):
Instrument Serif for display headings — nobody in dev tools
uses a serif. It creates instant hierarchy contrast and
signals "we care about craft" in a space full of sans-serifs.
Single teal accent instead of blue — every competitor uses blue.
Teal is close enough to feel trustworthy, different enough
to be recognizable.
4px compact density — tighter than Linear, says "we respect
your screen real estate."
The safe choices keep you literate. The risks are where your
product gets its own face. Which risks appeal to you?
You: Love the serif risk. Let's see it.
Claude: Preview opened in your browser.
[/tmp/design-consultation-preview-1710000000.html]
The page shows a realistic dashboard: sidebar nav, header with
avatar, stat cards, data table — all in your design system.
Instrument Serif at hero scale, Geist in body text, JetBrains
Mono in the data table. Teal accent on buttons and active states.
Light and dark mode toggle in the corner.
How does it feel? Want to adjust anything before I write DESIGN.md?
You: Ship it.
Claude: Wrote DESIGN.md (typography, color, spacing, layout, motion).
Updated CLAUDE.md with design system guidelines.
All future sessions will respect these choices.
```
---
## `/qa-design-review`
This is my **designer who codes mode**.
`/plan-design-review` tells you what is wrong. `/qa-design-review` fixes it.
It runs the same 80-item audit, then enters a fix loop: for each design finding, it locates the source file, makes the minimal CSS/styling change, commits with `style(design): FINDING-NNN`, re-navigates to verify, and takes before/after screenshots. One commit per fix, fully bisectable.
The self-regulation heuristic is tuned for design work — CSS-only changes get a free pass (they are inherently safe and reversible), but changes to component JSX/TSX files count against the risk budget. Hard cap at 30 fixes. If the risk score exceeds 20%, it stops and asks.
```
You: /qa-design-review https://myapp.com
Claude: [Runs full design audit — same output as /plan-design-review]
Design Score: C | AI Slop Score: D
12 findings (4 high, 5 medium, 3 polish)
Fixing 9 design issues...
style(design): FINDING-001 — replace 3-column icon grid with asymmetric layout
style(design): FINDING-002 — add heading scale 48/32/24/18/16
style(design): FINDING-003 — remove gradient hero, use bold typography
style(design): FINDING-004 — add second font for headings
style(design): FINDING-005 — vary border-radius by element role
style(design): FINDING-006 — left-align body text, reserve center for headings
style(design): FINDING-007 — add hover/focus states to all interactive elements
style(design): FINDING-008 — add prefers-reduced-motion media query
style(design): FINDING-009 — set max content width to 680px for body text
Final audit:
Design Score: C → B+ | AI Slop Score: D → A
9 fixes applied (8 verified, 1 best-effort). 3 deferred.
[Report with before/after screenshots saved to .gstack/design-reports/]
```
Nine commits, each touching one concern. The AI Slop score went from D to A because the three most recognizable patterns (gradient hero, 3-column grid, uniform radius) are gone. The design score improved two grades because the typography now has a scale, the spacing has hierarchy, and interactive elements have proper states.
---
## `/review`
This is my **paranoid staff engineer mode**.
Passing tests do not mean the branch is safe.
`/review` exists because there is a whole class of bugs that can survive CI and still punch you in the face in production. This mode is not about dreaming bigger. It is not about making the plan prettier. It is about asking:
**What can still break?**
This is a structural audit, not a style nitpick pass. I want the model to look for things like:
* N+1 queries
* stale reads
* race conditions
* bad trust boundaries
* missing indexes
* escaping bugs
* broken invariants
* bad retry logic
* tests that pass while missing the real failure mode
### Example
Suppose the smart listing flow is implemented and the tests are green.
`/review` should still ask:
* Did I introduce an N+1 query when rendering listing photos or draft suggestions?
* Am I trusting client-provided file metadata instead of validating the actual file?
* Can two tabs race and overwrite cover-photo selection or item details?
* Do failed uploads leave orphaned files in storage forever?
* Can the "exactly one hero image" rule break under concurrency?
* If enrichment APIs partially fail, do I degrade gracefully or save garbage?
* Did I accidentally create a prompt injection or trust-boundary problem by pulling web data into draft generation?
That is the point of `/review`.
I do not want flattery here.
I want the model imagining the production incident before it happens.
---
## `/ship`
This is my **release machine mode**.
Once I have decided what to build, nailed the technical plan, and run a serious review, I do not want more talking. I want execution.
`/ship` is for the final mile. It is for a ready branch, not for deciding what to build.
This is where the model should stop behaving like a brainstorm partner and start behaving like a disciplined release engineer: sync with main, run the right tests, make sure the branch state is sane, update changelog or versioning if the repo expects it, push, and create or update the PR.
Momentum matters here.
A lot of branches die when the interesting work is done and only the boring release work is left. Humans procrastinate that part. AI should not.
If your project doesn't have a test framework, `/ship` will set one up — detect your runtime, research the best framework, install it, write real tests for your actual code, set up CI/CD, and create TESTING.md. After that, every session writes tests naturally. 100% test coverage is the goal — tests make vibe coding safe instead of yolo coding.
### Example
Suppose the smart listing flow is finished.
The product thinking is done.
The architecture is done.
The review pass is done.
Now the branch just needs to get landed.
That is what `/ship` is for.
It takes care of the repetitive release hygiene so I do not bleed energy on:
* syncing with main
* rerunning tests
* checking for weird branch state
* updating changelog/version metadata
* pushing the branch
* opening or updating the PR
At this point I do not want more ideation.
I want the plane landed.
**[Read the full philosophy and per-skill deep dives](docs/skills.md)**
---
## 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.
[Greptile](https://greptile.com) is a YC company that reviews your PRs automatically. gstack triages Greptile's comments as part of `/review` and `/ship` — valid issues get fixed, false positives get pushed back with evidence, already-fixed issues get auto-acknowledged.
**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.
**Setup:** Install Greptile on your GitHub repo at [greptile.com](https://greptile.com). gstack picks up its comments automatically.
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.
It also learns. 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.
→ 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.
**[Full Greptile integration guide](docs/greptile.md)**
---
## `/browse`
## Contributor mode
This is my **QA engineer mode**.
Turn on contributor mode (`gstack-config set gstack_contributor true`) and gstack automatically files bug reports when something goes wrong — what you were doing, what broke, repro steps. Fork gstack and fix it yourself.
`/browse` is the skill that closes the loop. Before it, the agent could think and code but was still half blind. It had to guess about UI state, auth flows, redirects, console errors, empty states, and broken layouts. Now it can just go look.
That is a real step-change. The full cycle becomes: plan, code, run the app, inspect the UI, reproduce the bug, verify the fix, ship. QA stops being "go click around manually" and becomes part of the same agentic loop. It gives the agent eyes. Now it can do the boring, high-context QA work itself: click through the app, catch breakage, verify the fix, and keep going. That feels like having a real operator in the machine.
It is a compiled binary that talks to a persistent Chromium daemon — built on [Playwright](https://playwright.dev/) by Microsoft. First call starts the browser (~3s). Every call after that: ~100-200ms. The browser stays running between commands, so cookies, tabs, and localStorage carry over.
After I push a branch, I tell Claude to go check staging. It does the entire QA pass for me:
```
You: /browse staging.myapp.com — log in, test the signup flow, and check
every page I changed in this branch
Claude: [18 tool calls, ~60 seconds]
> browse goto https://staging.myapp.com/signup
> browse snapshot -i
> browse fill @e2 "test@example.com"
> browse fill @e3 "password123"
> browse click @e5 (Submit)
> browse screenshot /tmp/signup.png
> Read /tmp/signup.png
Signup works. Redirected to onboarding. Now checking changed pages.
> browse goto https://staging.myapp.com/dashboard
> browse screenshot /tmp/dashboard.png
> Read /tmp/dashboard.png
> browse console
Dashboard loads. No console errors. Charts render with sample data.
> browse goto https://staging.myapp.com/settings/billing
> browse screenshot /tmp/billing.png
> Read /tmp/billing.png
Billing page loads. Plan selector shows Free/Pro/Enterprise.
Stripe elements render correctly.
> browse goto https://staging.myapp.com/api/health
> browse text
API health endpoint returns {"status":"ok","version":"2.4.1"}.
All 4 pages load correctly. No console errors. No broken layouts.
Signup → onboarding → dashboard flow works end to end.
```
18 tool calls, about a minute. It signed up a test user, navigated every page I changed, took screenshots, read them, checked the console for errors, and verified the API. That is a full QA pass. I did not open a browser.
It works for reading documentation, verifying deployments, filling out forms, taking screenshots, comparing pages across environments, and anything else where Claude needs eyes on a live URL.
**Security note:** `/browse` runs a persistent Chromium session. Cookies, localStorage, and session state carry over between commands. Do not use it against sensitive production environments unless you intend to — it is a real browser with real state. The session auto-shuts down after 30 minutes of idle time.
For the full command reference, technical internals, and architecture details, see [BROWSER.md](BROWSER.md).
---
## `/qa`
This is my **QA lead mode**.
`/browse` gives the agent eyes. `/qa` gives it a testing methodology.
The most common use case: you're on a feature branch, you just finished coding, and you want to verify everything works. Just say `/qa` — it reads your git diff, identifies which pages and routes your changes affect, spins up the browser, and tests each one. No URL required. No manual test plan. It figures out what to test from the code you changed.
```
You: /qa
Claude: Analyzing branch diff against main...
12 files changed: 3 controllers, 2 views, 4 services, 3 tests
Affected routes: /listings/new, /listings/:id, /api/listings
Detected app running on localhost:3000.
[Tests each affected page — navigates, fills forms, clicks buttons,
screenshots, checks console errors]
QA Report: 3 routes tested, all working.
- /listings/new: upload + enrichment flow works end to end
- /listings/:id: detail page renders correctly
- /api/listings: returns 200 with expected shape
No console errors. No regressions on adjacent pages.
```
Four modes:
- **Diff-aware** (automatic on feature branches) — reads `git diff main`, identifies affected pages, tests them specifically. The fastest path from "I just wrote code" to "it works."
- **Full** — systematic exploration of the entire app. 5-15 minutes depending on app size. Documents 5-10 well-evidenced issues.
- **Quick** (`--quick`) — 30-second smoke test. Homepage + top 5 nav targets. Loads? Console errors? Broken links?
- **Regression** (`--regression baseline.json`) — run full mode, then diff against a previous baseline. Which issues are fixed? Which are new? What's the score delta?
```
You: /qa https://staging.myapp.com
Claude: [Explores 12 pages, fills 3 forms, tests 2 flows]
QA Report: staging.myapp.com — Health Score: 72/100
Top 3 Issues:
1. CRITICAL: Checkout form submits with empty required fields
2. HIGH: Mobile nav menu doesn't close after selecting an item
3. MEDIUM: Dashboard chart overlaps sidebar below 1024px
[Full report with screenshots saved to .gstack/qa-reports/]
```
Reports and screenshots accumulate in `.gstack/qa-reports/` so you can track quality over time and compare runs.
**Testing authenticated pages:** Use `/setup-browser-cookies` first to import your real browser sessions, then `/qa` can test pages behind login.
---
## `/setup-browser-cookies`
This is my **session manager mode**.
Before `/qa` or `/browse` can test authenticated pages, they need cookies. Instead of manually logging in through the headless browser every time, `/setup-browser-cookies` imports your real sessions directly from your daily browser.
It auto-detects installed Chromium browsers (Comet, Chrome, Arc, Brave, Edge), decrypts cookies via the macOS Keychain, and loads them into the Playwright session. An interactive picker UI lets you choose exactly which domains to import — no cookie values are ever displayed.
```
You: /setup-browser-cookies
Claude: Cookie picker opened — select the domains you want to import
in your browser, then tell me when you're done.
[You pick github.com, myapp.com in the browser UI]
You: done
Claude: Imported 2 domains (47 cookies). Session is ready.
```
Or skip the UI entirely:
```
You: /setup-browser-cookies github.com
Claude: Imported 12 cookies for github.com from Comet.
```
First import per browser triggers a macOS Keychain prompt — click "Allow" or "Always Allow."
---
## `/retro`
This is my **engineering manager mode**.
At the end of the week I want to know what actually happened. Not vibes — data. `/retro` analyzes commit history, work patterns, and shipping velocity and writes a candid retrospective.
It is team-aware. It identifies who is running the command, gives you the deepest treatment on your own work, then breaks down every contributor with specific praise and growth opportunities — the kind of feedback you would actually give in a 1:1. It computes metrics like commits, LOC, test ratio, PR sizes, and fix ratio. It detects coding sessions from commit timestamps, finds hotspot files, tracks shipping streaks, and identifies the biggest ship of the week.
```
You: /retro
Claude: Week of Mar 1: 47 commits (3 contributors), 3.2k LOC, 38% tests, 12 PRs, peak: 10pm | Streak: 47d
## Your Week
32 commits, +2.4k LOC, 41% tests. Peak hours: 9-11pm.
Biggest ship: cookie import system (browser decryption + picker UI).
What you did well: shipped a complete feature with encryption, UI, and
18 unit tests in one focused push...
## Team Breakdown
### Alice
12 commits focused on app/services/. Every PR under 200 LOC — disciplined.
Opportunity: test ratio at 12% — worth investing before payment gets more complex.
### Bob
3 commits — fixed the N+1 query on dashboard. Small but high-impact.
Opportunity: only 1 active day this week — check if blocked on anything.
[Top 3 team wins, 3 things to improve, 3 habits for next week]
```
It saves a JSON snapshot to `.context/retros/` so the next run can show trends. Run `/retro compare` to see this week vs last week side by side.
---
## `/document-release`
This is my **technical writer mode**.
After `/ship` creates the PR but before it merges, `/document-release` reads every documentation file in the project and cross-references it against the diff. It updates file paths, command lists, project structure trees, and anything else that drifted. Risky or subjective changes get surfaced as questions — everything else is handled automatically.
```
You: /document-release
Claude: Analyzing 21 files changed across 3 commits. Found 8 documentation files.
README.md: updated skill count from 9 to 10, added new skill to table
CLAUDE.md: added new directory to project structure
CONTRIBUTING.md: current — no changes needed
TODOS.md: marked 2 items complete, added 1 new item
All docs updated and committed. PR body updated with doc diff.
```
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.
**[Contributor mode guide](docs/contributor-mode.md)**
---
@@ -857,9 +216,17 @@ Paste this into Claude Code:
> Uninstall gstack: remove the skill symlinks by running `for s in browse plan-ceo-review plan-eng-review plan-design-review design-consultation review ship retro qa qa-only qa-design-review setup-browser-cookies document-release; do rm -f ~/.claude/skills/$s; done` then run `rm -rf ~/.claude/skills/gstack` and remove the gstack section from CLAUDE.md. If this project also has gstack at .claude/skills/gstack, remove it by running `for s in browse plan-ceo-review plan-eng-review plan-design-review design-consultation review ship retro qa qa-only qa-design-review setup-browser-cookies document-release; do rm -f .claude/skills/$s; done && rm -rf .claude/skills/gstack` and remove the gstack section from the project CLAUDE.md too.
## Development
## Documentation
See [CONTRIBUTING.md](CONTRIBUTING.md) for setup, testing, and dev mode. See [ARCHITECTURE.md](ARCHITECTURE.md) for design decisions and system internals. See [BROWSER.md](BROWSER.md) for the browse command reference.
| Doc | What it covers |
|-----|---------------|
| [Skill Deep Dives](docs/skills.md) | Philosophy, examples, and workflow for every skill |
| [Greptile Integration](docs/greptile.md) | Setup and triage workflow |
| [Contributor Mode](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 |
| [Contributing](CONTRIBUTING.md) | Dev setup, testing, and dev mode |
| [Changelog](CHANGELOG.md) | What's new in every version |
### Testing
docs/contributor-mode.md
+37
View File
@@ -0,0 +1,37 @@
# 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.
docs/greptile.md
+76
View File
@@ -0,0 +1,76 @@
# 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.
docs/skills.md
+575
View File
@@ -0,0 +1,575 @@
# Skill Deep Dives
Detailed guides for every gstack skill — philosophy, workflow, and examples.
**Quick reference:** See the [skill table in the README](../README.md) for the one-line summary of each skill.
---
## `/plan-ceo-review`
This is my **founder mode**.
This is where I want the model to think with taste, ambition, user empathy, and a long time horizon. I do not want it taking the request literally. I want it asking a more important question first:
**What is this product actually for?**
I think of this as **Brian Chesky mode**.
The point is not to implement the obvious ticket. The point is to rethink the problem from the user's point of view and find the version that feels inevitable, delightful, and maybe even a little magical.
### Example
Say I am building a Craigslist-style listing app and I say:
> "Let sellers upload a photo for their item."
A weak assistant will add a file picker and save an image.
That is not the real product.
In `/plan-ceo-review`, I want the model to ask whether "photo upload" is even the feature. Maybe the real feature is helping someone create a listing that actually sells.
If that is the real job, the whole plan changes.
Now the model should ask:
* Can we identify the product from the photo?
* Can we infer the SKU or model number?
* Can we search the web and draft the title and description automatically?
* Can we pull specs, category, and pricing comps?
* Can we suggest which photo will convert best as the hero image?
* Can we detect when the uploaded photo is ugly, dark, cluttered, or low-trust?
* Can we make the experience feel premium instead of like a dead form from 2007?
That is what `/plan-ceo-review` does for me.
It does not just ask, "how do I add this feature?"
It asks, **"what is the 10-star product hiding inside this request?"**
### Four modes
- **SCOPE EXPANSION** — dream big. The agent proposes the ambitious version. Every expansion is presented as an individual decision you opt into. Recommends enthusiastically.
- **SELECTIVE EXPANSION** — hold your current scope as the baseline, but see what else is possible. The agent surfaces opportunities one by one with neutral recommendations — you cherry-pick the ones worth doing.
- **HOLD SCOPE** — maximum rigor on the existing plan. No expansions surfaced.
- **SCOPE REDUCTION** — find the minimum viable version. Cut everything else.
Visions and decisions are persisted to `~/.gstack/projects/` so they survive beyond the conversation. Exceptional visions can be promoted to `docs/designs/` in your repo for the team.
---
## `/plan-eng-review`
This is my **eng manager mode**.
Once the product direction is right, I want a different kind of intelligence entirely. I do not want more sprawling ideation. I do not want more "wouldn't it be cool if." I want the model to become my best technical lead.
This mode should nail:
* architecture
* system boundaries
* data flow
* state transitions
* failure modes
* edge cases
* trust boundaries
* test coverage
And one surprisingly big unlock for me: **diagrams**.
LLMs get way more complete when you force them to draw the system. Sequence diagrams, state diagrams, component diagrams, data-flow diagrams, even test matrices. Diagrams force hidden assumptions into the open. They make hand-wavy planning much harder.
So `/plan-eng-review` is where I want the model to build the technical spine that can carry the product vision.
### Example
Take the same listing app example.
Let's say `/plan-ceo-review` already did its job. We decided the real feature is not just photo upload. It is a smart listing flow that:
* uploads photos
* identifies the product
* enriches the listing from the web
* drafts a strong title and description
* suggests the best hero image
Now `/plan-eng-review` takes over.
Now I want the model to answer questions like:
* What is the architecture for upload, classification, enrichment, and draft generation?
* Which steps happen synchronously, and which go to background jobs?
* Where are the boundaries between app server, object storage, vision model, search/enrichment APIs, and the listing database?
* What happens if upload succeeds but enrichment fails?
* What happens if product identification is low-confidence?
* How do retries work?
* How do we prevent duplicate jobs?
* What gets persisted when, and what can be safely recomputed?
And this is where I want diagrams — architecture diagrams, state models, data-flow diagrams, test matrices. Diagrams force hidden assumptions into the open. They make hand-wavy planning much harder.
That is `/plan-eng-review`.
Not "make the idea smaller."
**Make the idea buildable.**
### Review Readiness Dashboard
Every review (CEO, Eng, Design) logs its result. At the end of each review, you see a dashboard:
```
+====================================================================+
| REVIEW READINESS DASHBOARD |
+====================================================================+
| Review | Runs | Last Run | Status | Required |
|-----------------|------|---------------------|-----------|----------|
| Eng Review | 1 | 2026-03-16 15:00 | CLEAR | YES |
| CEO Review | 1 | 2026-03-16 14:30 | CLEAR | no |
| Design Review | 0 | — | — | no |
+--------------------------------------------------------------------+
| VERDICT: CLEARED — Eng Review passed |
+====================================================================+
```
Eng Review is the only required gate (disable with `gstack-config set skip_eng_review true`). CEO and Design are informational — recommended for product and UI changes respectively.
### Plan-to-QA flow
When `/plan-eng-review` finishes the test review section, it writes a test plan artifact to `~/.gstack/projects/`. When you later run `/qa`, it picks up that test plan automatically — your engineering review feeds directly into QA testing with no manual copy-paste.
---
## `/plan-design-review`
This is my **senior designer mode**.
Most developers cannot tell whether their site looks AI-generated. I could not, until I started paying attention. There is a growing class of sites that are functional but soulless — they work fine but scream "an AI built this and nobody with taste looked at it." Purple gradients, 3-column icon grids, uniform bubbly border-radius on everything, centered text on every section, decorative blobs floating in the background. The ChatGPT aesthetic.
`/plan-design-review` gives the agent a designer's eye.
It opens your site and reacts to it the way a Stripe or Linear designer would — immediately, viscerally, with opinions. The first output is a structured gut reaction: what the site communicates at a glance, what the eye is drawn to, and a one-word verdict. That is the most valuable part. Everything after is supporting evidence.
Then it extracts your actual design system by reading the CSS: how many fonts are you really using? What is your heading scale? How many colors? Is your spacing on a grid or arbitrary? It structures this as an **Inferred Design System** and offers to save it as a `DESIGN.md` — so now you have a design system you never had before, derived from what you actually shipped.
The audit covers 80 items across 10 categories. Typography, spacing, hierarchy, color, responsive design, interaction states, motion, content quality, performance feel, and — the headline feature — **AI Slop Detection**. Ten specific anti-patterns that mark a site as machine-generated.
Every finding gets a letter grade (A through F) per category. The report opens with two headline scores: **Design Score** and **AI Slop Score**. "Your site got a B on design but a D on AI Slop" tells you exactly where to focus.
### Example
```
You: /plan-design-review https://myapp.com
Claude: Design Score: C | AI Slop Score: D
"The site communicates generic SaaS energy."
"I notice the hero section uses a blue-to-purple gradient
with a 3-column feature grid below it — the single most
recognizable AI-generated layout pattern."
"The first 3 things my eye goes to are: the gradient, the
symmetrical icon grid, and a 'Get Started' button that
looks like every other 'Get Started' button."
"If I had to describe this in one word: template."
Inferred Design System:
- Fonts: Inter (body), Inter (headings) — 1 font family
- Colors: 14 unique non-gray colors (flag: >12)
- Heading scale: 36/24/18/16 — flat, no drama between sizes
- Spacing: mostly 16px and 24px — no rhythm
Top 5 Design Improvements:
1. Break the 3-column icon grid (High, AI Slop)
2. Add heading scale contrast — at least 2:1 ratio (High, Typography)
3. Replace uniform border-radius with intentional hierarchy (Medium, Spacing)
4. Kill the gradient hero — use a real image or bold typography (High, AI Slop)
5. Add a second font for headings — Inter-only reads as generic (Medium, Typography)
[Full report saved to .gstack/design-reports/]
Want me to save this inferred design system as your DESIGN.md?
```
This is report only — it never touches your code. Use `/qa-design-review` when you want it to fix what it finds.
---
## `/design-consultation`
This is my **design partner mode**.
`/plan-design-review` audits a site that already exists. `/design-consultation` is for when you have nothing yet — no design system, no font choices, no color palette. You are starting from zero and you want a senior designer to sit down with you and build the whole visual identity together.
It is a conversation, not a form. The agent asks about your product, your users, and your audience. It thinks about what your product needs to communicate — trust, speed, craft, warmth, whatever fits — and works backward from that to concrete choices. Then it proposes a complete, coherent design system: aesthetic direction, typography (3+ fonts with specific roles), color palette with hex values, spacing scale, layout approach, and motion strategy. Every recommendation comes with a rationale. Every choice reinforces every other choice.
But coherence is table stakes. Every dev tool dashboard looks the same — clean sans-serif, muted grays, a blue accent. They are all coherent. They are all forgettable. The difference between a product that looks "nice" and one that people actually recognize is the **deliberate creative risks**: the unexpected serif for headings, the bold accent nobody else in your category uses, the tighter spacing that makes your data feel authoritative instead of airy.
That is what `/design-consultation` is really about. It does not just propose a safe system. It proposes safe choices AND risks — and tells you which is which. "Here are the choices that keep you literate in your category. And here is where I think you should break from convention, and why." You pick which risks to take. The agent checks that the whole system still coheres either way.
If you want, the agent will browse your competitors' actual sites — take screenshots, analyze their fonts and colors and spacing — so you can see the landscape before you make choices. This is not about copying. It is about getting in the ballpark so you know what the conventions are, and then deciding which ones are worth breaking.
After you agree on the system, it generates an interactive HTML preview page — not just swatches and font samples, but realistic product pages. If you are building a dashboard, you see a dashboard with a sidebar, data tables, and stat cards. If you are building a marketing site, you see a hero section with real copy and a CTA. Everything rendered in your design system, with your product name, in light and dark mode. You see what your product could feel like before a single line of production code is written.
Then it writes `DESIGN.md` to your repo root — your project's design source of truth — and updates `CLAUDE.md` so every future Claude Code session respects the system. From that point on, `/qa-design-review` can audit against it, and any agent working on your frontend knows the rules.
### Example
```
You: /design-consultation
Claude: From the README, this looks like a developer analytics dashboard
for engineering teams. Sound right? Tell me about the feeling
you want — and would you like me to browse some competitors
first so we can see the landscape?
You: Yes, it's for eng managers. Show me what's out there.
Claude: [browses Linear, Vercel, Datadog, Posthog — takes screenshots]
Here's the landscape. They all converge on clean sans-serifs
and muted blue-gray palettes. Linear stands out with dark-first
and tight spacing. The rest feel interchangeable.
Here's my proposal — and where I'd play it safe vs. take risks:
AESTHETIC: Industrial/Utilitarian — data-first, every pixel earns its place
TYPOGRAPHY: Geist (body + UI), Instrument Serif (display), JetBrains Mono (data)
COLOR: Restrained — slate neutrals, single teal accent (#0D9488)
SPACING: 4px base, compact density
LAYOUT: Grid-disciplined, 12-column
MOTION: Minimal-functional — only transitions that aid comprehension
SAFE CHOICES (match category expectations):
Geist for body — your users already know this font from Vercel
Slate neutrals — warm grays feel right for data-heavy UIs
Grid-disciplined layout — dashboards need predictable alignment
RISKS (where you'd stand out):
Instrument Serif for display headings — nobody in dev tools
uses a serif. It creates instant hierarchy contrast and
signals "we care about craft" in a space full of sans-serifs.
Single teal accent instead of blue — every competitor uses blue.
Teal is close enough to feel trustworthy, different enough
to be recognizable.
4px compact density — tighter than Linear, says "we respect
your screen real estate."
The safe choices keep you literate. The risks are where your
product gets its own face. Which risks appeal to you?
You: Love the serif risk. Let's see it.
Claude: Preview opened in your browser.
[/tmp/design-consultation-preview-1710000000.html]
The page shows a realistic dashboard: sidebar nav, header with
avatar, stat cards, data table — all in your design system.
Instrument Serif at hero scale, Geist in body text, JetBrains
Mono in the data table. Teal accent on buttons and active states.
Light and dark mode toggle in the corner.
How does it feel? Want to adjust anything before I write DESIGN.md?
You: Ship it.
Claude: Wrote DESIGN.md (typography, color, spacing, layout, motion).
Updated CLAUDE.md with design system guidelines.
All future sessions will respect these choices.
```
---
## `/qa-design-review`
This is my **designer who codes mode**.
`/plan-design-review` tells you what is wrong. `/qa-design-review` fixes it.
It runs the same 80-item audit, then enters a fix loop: for each design finding, it locates the source file, makes the minimal CSS/styling change, commits with `style(design): FINDING-NNN`, re-navigates to verify, and takes before/after screenshots. One commit per fix, fully bisectable.
The self-regulation heuristic is tuned for design work — CSS-only changes get a free pass (they are inherently safe and reversible), but changes to component JSX/TSX files count against the risk budget. Hard cap at 30 fixes. If the risk score exceeds 20%, it stops and asks.
### Example
```
You: /qa-design-review https://myapp.com
Claude: [Runs full design audit — same output as /plan-design-review]
Design Score: C | AI Slop Score: D
12 findings (4 high, 5 medium, 3 polish)
Fixing 9 design issues...
style(design): FINDING-001 — replace 3-column icon grid with asymmetric layout
style(design): FINDING-002 — add heading scale 48/32/24/18/16
style(design): FINDING-003 — remove gradient hero, use bold typography
style(design): FINDING-004 — add second font for headings
style(design): FINDING-005 — vary border-radius by element role
style(design): FINDING-006 — left-align body text, reserve center for headings
style(design): FINDING-007 — add hover/focus states to all interactive elements
style(design): FINDING-008 — add prefers-reduced-motion media query
style(design): FINDING-009 — set max content width to 680px for body text
Final audit:
Design Score: C → B+ | AI Slop Score: D → A
9 fixes applied (8 verified, 1 best-effort). 3 deferred.
[Report with before/after screenshots saved to .gstack/design-reports/]
```
Nine commits, each touching one concern. The AI Slop score went from D to A because the three most recognizable patterns (gradient hero, 3-column grid, uniform radius) are gone.
---
## `/review`
This is my **paranoid staff engineer mode**.
Passing tests do not mean the branch is safe.
`/review` exists because there is a whole class of bugs that can survive CI and still punch you in the face in production. This mode is not about dreaming bigger. It is not about making the plan prettier. It is about asking:
**What can still break?**
This is a structural audit, not a style nitpick pass. I want the model to look for things like:
* N+1 queries
* stale reads
* race conditions
* bad trust boundaries
* missing indexes
* escaping bugs
* broken invariants
* bad retry logic
* tests that pass while missing the real failure mode
* forgotten enum handlers — add a new status or type constant, and `/review` traces it through every switch statement and allowlist in your codebase, not just the files you changed
### Fix-First
Findings get action, not just listed. Obvious mechanical fixes (dead code, stale comments, N+1 queries) are applied automatically — you see `[AUTO-FIXED] file:line Problem → what was done` for each one. Genuinely ambiguous issues (security, race conditions, design decisions) get surfaced for your call.
### Completeness gaps
`/review` now flags shortcut implementations where the complete version costs less than 30 minutes of CC time. If you chose the 80% solution and the 100% solution is a lake, not an ocean, the review will call it out.
### Example
Suppose the smart listing flow is implemented and the tests are green.
`/review` should still ask:
* Did I introduce an N+1 query when rendering listing photos or draft suggestions?
* Am I trusting client-provided file metadata instead of validating the actual file?
* Can two tabs race and overwrite cover-photo selection or item details?
* Do failed uploads leave orphaned files in storage forever?
* Can the "exactly one hero image" rule break under concurrency?
* If enrichment APIs partially fail, do I degrade gracefully or save garbage?
* Did I accidentally create a prompt injection or trust-boundary problem by pulling web data into draft generation?
That is the point of `/review`.
I do not want flattery here.
I want the model imagining the production incident before it happens.
---
## `/ship`
This is my **release machine mode**.
Once I have decided what to build, nailed the technical plan, and run a serious review, I do not want more talking. I want execution.
`/ship` is for the final mile. It is for a ready branch, not for deciding what to build.
This is where the model should stop behaving like a brainstorm partner and start behaving like a disciplined release engineer: sync with main, run the right tests, make sure the branch state is sane, update changelog or versioning if the repo expects it, push, and create or update the PR.
### Test bootstrap
If your project doesn't have a test framework, `/ship` sets one up — detects your runtime, researches the best framework, installs it, writes 3-5 real tests for your actual code, sets up CI/CD (GitHub Actions), and creates TESTING.md. 100% test coverage is the goal — tests make vibe coding safe instead of yolo coding.
### Coverage audit
Every `/ship` run builds a code path map from your diff, searches for corresponding tests, and produces an ASCII coverage diagram with quality stars. Gaps get tests auto-generated. Your PR body shows the coverage: `Tests: 42 → 47 (+5 new)`.
### Review gate
`/ship` checks the [Review Readiness Dashboard](#review-readiness-dashboard) before creating the PR. If the Eng Review is missing, it asks — but won't block you. Decisions are saved per-branch so you're never re-asked.
A lot of branches die when the interesting work is done and only the boring release work is left. Humans procrastinate that part. AI should not.
---
## `/browse`
This is my **QA engineer mode**.
`/browse` is the skill that closes the loop. Before it, the agent could think and code but was still half blind. It had to guess about UI state, auth flows, redirects, console errors, empty states, and broken layouts. Now it can just go look.
It is a compiled binary that talks to a persistent Chromium daemon — built on [Playwright](https://playwright.dev/) by Microsoft. First call starts the browser (~3s). Every call after that: ~100-200ms. The browser stays running between commands, so cookies, tabs, and localStorage carry over.
### Example
```
You: /browse staging.myapp.com — log in, test the signup flow, and check
every page I changed in this branch
Claude: [18 tool calls, ~60 seconds]
> browse goto https://staging.myapp.com/signup
> browse snapshot -i
> browse fill @e2 "test@example.com"
> browse fill @e3 "password123"
> browse click @e5 (Submit)
> browse screenshot /tmp/signup.png
> Read /tmp/signup.png
Signup works. Redirected to onboarding. Now checking changed pages.
> browse goto https://staging.myapp.com/dashboard
> browse screenshot /tmp/dashboard.png
> Read /tmp/dashboard.png
> browse console
Dashboard loads. No console errors. Charts render with sample data.
All 4 pages load correctly. No console errors. No broken layouts.
Signup → onboarding → dashboard flow works end to end.
```
18 tool calls, about a minute. Full QA pass. No browser opened.
**Security note:** `/browse` runs a persistent Chromium session. Cookies, localStorage, and session state carry over between commands. Do not use it against sensitive production environments unless you intend to — it is a real browser with real state. The session auto-shuts down after 30 minutes of idle time.
For the full command reference, see [BROWSER.md](../BROWSER.md).
---
## `/qa`
This is my **QA lead mode**.
`/browse` gives the agent eyes. `/qa` gives it a testing methodology.
The most common use case: you're on a feature branch, you just finished coding, and you want to verify everything works. Just say `/qa` — it reads your git diff, identifies which pages and routes your changes affect, spins up the browser, and tests each one. No URL required. No manual test plan.
Four modes:
- **Diff-aware** (automatic on feature branches) — reads `git diff main`, identifies affected pages, tests them specifically
- **Full** — systematic exploration of the entire app. 5-15 minutes. Documents 5-10 well-evidenced issues.
- **Quick** (`--quick`) — 30-second smoke test. Homepage + top 5 nav targets.
- **Regression** (`--regression baseline.json`) — run full mode, then diff against a previous baseline.
### Automatic regression tests
When `/qa` fixes a bug and verifies it, it automatically generates a regression test that catches the exact scenario that broke. Tests include full attribution tracing back to the QA report.
### Example
```
You: /qa https://staging.myapp.com
Claude: [Explores 12 pages, fills 3 forms, tests 2 flows]
QA Report: staging.myapp.com — Health Score: 72/100
Top 3 Issues:
1. CRITICAL: Checkout form submits with empty required fields
2. HIGH: Mobile nav menu doesn't close after selecting an item
3. MEDIUM: Dashboard chart overlaps sidebar below 1024px
[Full report with screenshots saved to .gstack/qa-reports/]
```
**Testing authenticated pages:** Use `/setup-browser-cookies` first to import your real browser sessions, then `/qa` can test pages behind login.
---
## `/setup-browser-cookies`
This is my **session manager mode**.
Before `/qa` or `/browse` can test authenticated pages, they need cookies. Instead of manually logging in through the headless browser every time, `/setup-browser-cookies` imports your real sessions directly from your daily browser.
It auto-detects installed Chromium browsers (Comet, Chrome, Arc, Brave, Edge), decrypts cookies via the macOS Keychain, and loads them into the Playwright session. An interactive picker UI lets you choose exactly which domains to import — no cookie values are ever displayed.
```
You: /setup-browser-cookies
Claude: Cookie picker opened — select the domains you want to import
in your browser, then tell me when you're done.
[You pick github.com, myapp.com in the browser UI]
You: done
Claude: Imported 2 domains (47 cookies). Session is ready.
```
Or skip the UI entirely:
```
You: /setup-browser-cookies github.com
Claude: Imported 12 cookies for github.com from Comet.
```
---
## `/retro`
This is my **engineering manager mode**.
At the end of the week I want to know what actually happened. Not vibes — data. `/retro` analyzes commit history, work patterns, and shipping velocity and writes a candid retrospective.
It is team-aware. It identifies who is running the command, gives you the deepest treatment on your own work, then breaks down every contributor with specific praise and growth opportunities. It computes metrics like commits, LOC, test ratio, PR sizes, and fix ratio. It detects coding sessions from commit timestamps, finds hotspot files, tracks shipping streaks, and identifies the biggest ship of the week.
It also tracks test health: total test files, tests added this period, regression test commits, and trend deltas. If test ratio drops below 20%, it flags it as a growth area.
### Example
```
You: /retro
Claude: Week of Mar 1: 47 commits (3 contributors), 3.2k LOC, 38% tests, 12 PRs, peak: 10pm | Streak: 47d
## Your Week
32 commits, +2.4k LOC, 41% tests. Peak hours: 9-11pm.
Biggest ship: cookie import system (browser decryption + picker UI).
What you did well: shipped a complete feature with encryption, UI, and
18 unit tests in one focused push...
## Team Breakdown
### Alice
12 commits focused on app/services/. Every PR under 200 LOC — disciplined.
Opportunity: test ratio at 12% — worth investing before payment gets more complex.
### Bob
3 commits — fixed the N+1 query on dashboard. Small but high-impact.
Opportunity: only 1 active day this week — check if blocked on anything.
[Top 3 team wins, 3 things to improve, 3 habits for next week]
```
It saves a JSON snapshot to `.context/retros/` so the next run can show trends.
---
## `/document-release`
This is my **technical writer mode**.
After `/ship` creates the PR but before it merges, `/document-release` reads every documentation file in the project and cross-references it against the diff. It updates file paths, command lists, project structure trees, and anything else that drifted. Risky or subjective changes get surfaced as questions — everything else is handled automatically.
```
You: /document-release
Claude: Analyzing 21 files changed across 3 commits. Found 8 documentation files.
README.md: updated skill count from 9 to 10, added new skill to table
CLAUDE.md: added new directory to project structure
CONTRIBUTING.md: current — no changes needed
TODOS.md: marked 2 items complete, added 1 new item
All docs updated and committed. PR body updated with doc diff.
```
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.