mirror of
https://github.com/garrytan/gstack.git
synced 2026-05-07 05:56:41 +02:00
Merge branch 'main' into garrytan/team-supabase-store
Resolved conflicts across 23 files. Key merge decisions: - Adopted main's TemplateContext type in gen-skill-docs.ts - Adopted main's new features (trigger phrases, codex integration, analytics, proactive config, review chaining) - Replaced gstack-review-log/gstack-review-read helpers with inline approach using $PROJECTS_DIR/$SLUG/reviews/$BRANCH.jsonl paths - Added "commit":"COMMIT" field to all review log entries (from main) - Kept our $PROJECTS_DIR/$SLUG path reorganization throughout - Added Codex E2E test from main + our E2E isolation cleanup Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
Garry Tan
@@ -16,7 +16,7 @@ In the last 60 days I have written **over 600,000 lines of production code** —
|
||||
|
||||
Same person. Different era. The difference is the tooling.
|
||||
|
||||
**gstack is how I do it.** It is my open source software factory. It turns Claude Code into a virtual engineering team you actually manage — a CEO who rethinks the product, an eng manager who locks the architecture, a designer who catches AI slop, a paranoid reviewer who finds production bugs, a QA lead who opens a real browser and clicks through your app, and a release engineer who ships the PR. Thirteen specialists, all as slash commands, all Markdown, **all free, MIT license, available right now.**
|
||||
**gstack is how I do it.** It is my open source software factory. It turns Claude Code into a virtual engineering team you actually manage — a CEO who rethinks the product, an eng manager who locks the architecture, a designer who catches AI slop, a paranoid reviewer who finds production bugs, a QA lead who opens a real browser and clicks through your app, and a release engineer who ships the PR. Fifteen specialists and six power tools, all as slash commands, all Markdown, **all free, MIT license, available right now.**
|
||||
|
||||
I am learning how to get to the edge of what agentic systems can do as of March 2026, and this is my live experiment. I am sharing it because I want the whole world on this journey with me.
|
||||
|
||||
@@ -30,10 +30,11 @@ Fork it. Improve it. Make it yours. Don't player hate, appreciate.
|
||||
## Quick start: your first 10 minutes
|
||||
|
||||
1. Install gstack (30 seconds — see below)
|
||||
2. Run `/plan-ceo-review` on any feature idea
|
||||
3. Run `/review` on any branch with changes
|
||||
4. Run `/qa` on your staging URL
|
||||
5. Stop there. You'll know if this is for you.
|
||||
2. Run `/office-hours` — describe what you're building. It will reframe the problem before you write a line of code.
|
||||
3. Run `/plan-ceo-review` on any feature idea
|
||||
4. Run `/review` on any branch with changes
|
||||
5. Run `/qa` on your staging URL
|
||||
6. Stop there. You'll know if this is for you.
|
||||
|
||||
Expect first useful run in under 5 minutes on any repo with tests already set up.
|
||||
|
||||
@@ -47,88 +48,102 @@ Expect first useful run in under 5 minutes on any repo with tests already set up
|
||||
|
||||
Open Claude Code and paste this. Claude does the rest.
|
||||
|
||||
> Install gstack: run **`git clone https://github.com/garrytan/gstack.git ~/.claude/skills/gstack && cd ~/.claude/skills/gstack && ./setup`** then add a "gstack" section to CLAUDE.md that says to use the /browse skill from gstack for all web browsing, never use mcp\_\_claude-in-chrome\_\_\* tools, and lists the available skills: /plan-ceo-review, /plan-eng-review, /plan-design-review, /design-consultation, /review, /ship, /browse, /qa, /qa-only, /qa-design-review, /setup-browser-cookies, /retro, /document-release. Then ask the user if they also want to add gstack to the current project so teammates get it.
|
||||
> Install gstack: run **`git clone https://github.com/garrytan/gstack.git ~/.claude/skills/gstack && cd ~/.claude/skills/gstack && ./setup`** then add a "gstack" section to CLAUDE.md that says to use the /browse skill from gstack for all web browsing, never use mcp\_\_claude-in-chrome\_\_\* tools, and lists the available skills: /office-hours, /plan-ceo-review, /plan-eng-review, /plan-design-review, /design-consultation, /review, /ship, /browse, /qa, /qa-only, /design-review, /setup-browser-cookies, /retro, /investigate, /document-release, /codex, /careful, /freeze, /guard, /unfreeze, /gstack-upgrade. Then ask the user if they also want to add gstack to the current project so teammates get it.
|
||||
|
||||
### Step 2: Add to your repo so teammates get it (optional)
|
||||
|
||||
> Add gstack to this project: run **`cp -Rf ~/.claude/skills/gstack .claude/skills/gstack && rm -rf .claude/skills/gstack/.git && cd .claude/skills/gstack && ./setup`** then add a "gstack" section to this project's CLAUDE.md that says to use the /browse skill from gstack for all web browsing, never use mcp\_\_claude-in-chrome\_\_\* tools, lists the available skills: /plan-ceo-review, /plan-eng-review, /plan-design-review, /design-consultation, /review, /ship, /browse, /qa, /qa-only, /qa-design-review, /setup-browser-cookies, /retro, /document-release, and tells Claude that if gstack skills aren't working, run `cd .claude/skills/gstack && ./setup` to build the binary and register skills.
|
||||
> Add gstack to this project: run **`cp -Rf ~/.claude/skills/gstack .claude/skills/gstack && rm -rf .claude/skills/gstack/.git && cd .claude/skills/gstack && ./setup`** then add a "gstack" section to this project's CLAUDE.md that says to use the /browse skill from gstack for all web browsing, never use mcp\_\_claude-in-chrome\_\_\* tools, lists the available skills: /office-hours, /plan-ceo-review, /plan-eng-review, /plan-design-review, /design-consultation, /review, /ship, /browse, /qa, /qa-only, /design-review, /setup-browser-cookies, /retro, /investigate, /document-release, /codex, /careful, /freeze, /guard, /unfreeze, /gstack-upgrade, and tells Claude that if gstack skills aren't working, run `cd .claude/skills/gstack && ./setup` to build the binary and register skills.
|
||||
|
||||
Real files get committed to your repo (not a submodule), so `git clone` just works. Everything lives inside `.claude/`. Nothing touches your PATH or runs in the background.
|
||||
|
||||
## See it work
|
||||
|
||||
```
|
||||
You: I want to add photo upload for sellers.
|
||||
You: /plan-ceo-review
|
||||
Claude: "Photo upload" is not the feature. The real job is helping
|
||||
sellers create listings that actually sell. What if we
|
||||
auto-identify the product, pull specs and comps from the
|
||||
web, and draft the listing automatically? That's 10 stars.
|
||||
"Upload a photo" is 3 stars. Which are we building?
|
||||
[8 expansion proposals, you cherry-pick 5, defer 3 to backlog]
|
||||
You: I want to build a daily briefing app for my calendar.
|
||||
You: /office-hours
|
||||
Claude: [asks about the pain — specific examples, not hypotheticals]
|
||||
|
||||
You: /plan-design-review
|
||||
Claude: Design Score: B | AI Slop Score: C
|
||||
"Upload flow looks like a default Bootstrap form."
|
||||
[80-item audit, infers your design system, exports DESIGN.md]
|
||||
[flags 3 AI slop patterns: gradient hero, icon grid, uniform radius]
|
||||
You: Multiple Google calendars, events with stale info, wrong locations.
|
||||
Prep takes forever and the results aren't good enough...
|
||||
|
||||
Claude: I'm going to push back on the framing. You said "daily briefing
|
||||
app." But what you actually described is a personal chief of
|
||||
staff AI.
|
||||
[extracts 5 capabilities you didn't realize you were describing]
|
||||
[challenges 4 premises — you agree, disagree, or adjust]
|
||||
[generates 3 implementation approaches with effort estimates]
|
||||
RECOMMENDATION: Ship the narrowest wedge tomorrow, learn from
|
||||
real usage. The full vision is a 3-month project — start with
|
||||
the daily briefing that actually works.
|
||||
[writes design doc → feeds into downstream skills automatically]
|
||||
|
||||
You: /plan-ceo-review
|
||||
[reads the design doc, challenges scope, runs 10-section review]
|
||||
|
||||
You: /plan-eng-review
|
||||
Claude: ┌─────────┐ ┌──────────┐ ┌──────────┐ ┌─────────┐
|
||||
│ Upload │───▶│ Classify │───▶│ Enrich │───▶│ Draft │
|
||||
│ (sync) │ │ (async) │ │ (async) │ │ (async) │
|
||||
└─────────┘ └──────────┘ └──────────┘ └─────────┘
|
||||
[ASCII diagrams for every data flow, state machine, error path]
|
||||
[14-case test matrix, 6 failure modes mapped, 3 security concerns]
|
||||
[ASCII diagrams for data flow, state machines, error paths]
|
||||
[test matrix, failure modes, security concerns]
|
||||
|
||||
You: Approve plan. Exit plan mode.
|
||||
[Claude writes 2,400 lines across 11 files — models, services,
|
||||
controllers, views, migrations, and tests. ~8 minutes.]
|
||||
[writes 2,400 lines across 11 files. ~8 minutes.]
|
||||
|
||||
You: /review
|
||||
Claude: [AUTO-FIXED] Orphan S3 cleanup on failed upload
|
||||
[AUTO-FIXED] Missing index on listings.status
|
||||
[ASK] Race condition on hero image selection → You: yes
|
||||
[traces every new enum value through all switch statements]
|
||||
3 issues — 2 auto-fixed, 1 fixed.
|
||||
[AUTO-FIXED] 2 issues. [ASK] Race condition → you approve fix.
|
||||
|
||||
You: /qa https://staging.myapp.com
|
||||
Claude: [opens real browser, logs in, uploads photos, clicks through flows]
|
||||
Upload → classify → enrich → draft: end to end ✓
|
||||
Mobile: ✓ | Slow connection: ✓ | Bad image: ✓
|
||||
[finds bug: preview doesn't clear on second upload — fixes it]
|
||||
Regression test generated.
|
||||
[opens real browser, clicks through flows, finds and fixes a bug]
|
||||
|
||||
You: /ship
|
||||
Claude: Tests: 42 → 51 (+9 new)
|
||||
Coverage: 14/14 code paths (100%)
|
||||
PR: github.com/you/app/pull/42
|
||||
Tests: 42 → 51 (+9 new). PR: github.com/you/app/pull/42
|
||||
```
|
||||
|
||||
One feature. Seven commands. The agent reframed the product, ran an 80-item design audit, drew the architecture, wrote 2,400 lines of code, found a race condition I would have missed, auto-fixed two issues, opened a real browser to QA test, found and fixed a bug I didn't know about, wrote 9 tests, and generated a regression test. That is not a copilot. That is a team.
|
||||
You said "daily briefing app." The agent said "you're building a chief of staff AI" — because it listened to your pain, not your feature request. Then it challenged your premises, generated three approaches, recommended the narrowest wedge, and wrote a design doc that fed into every downstream skill. Eight commands. That is not a copilot. That is a team.
|
||||
|
||||
## The team
|
||||
## The sprint
|
||||
|
||||
gstack is a process, not a collection of tools. The skills are ordered the way a sprint runs:
|
||||
|
||||
**Think → Plan → Build → Review → Test → Ship → Reflect**
|
||||
|
||||
Each skill feeds into the next. `/office-hours` writes a design doc that `/plan-ceo-review` reads. `/plan-eng-review` writes a test plan that `/qa` picks up. `/review` catches bugs that `/ship` verifies are fixed. Nothing falls through the cracks because every step knows what came before it.
|
||||
|
||||
One sprint, one person, one feature — that takes about 30 minutes with gstack. But here's what changes everything: you can run 10-15 of these sprints in parallel. Different features, different branches, different agents — all at the same time. That is how I ship 10,000+ lines of production code per day while doing my actual job.
|
||||
|
||||
| Skill | Your specialist | What they do |
|
||||
|-------|----------------|--------------|
|
||||
| `/office-hours` | **YC Office Hours** | Start here. Six forcing questions that reframe your product before you write code. Pushes back on your framing, challenges premises, generates implementation alternatives. Design doc feeds into every downstream skill. |
|
||||
| `/plan-ceo-review` | **CEO / Founder** | Rethink the problem. Find the 10-star product hiding inside the request. Four modes: Expansion, Selective Expansion, Hold Scope, Reduction. |
|
||||
| `/plan-eng-review` | **Eng Manager** | Lock in architecture, data flow, diagrams, edge cases, and tests. Forces hidden assumptions into the open. |
|
||||
| `/plan-design-review` | **Senior Designer** | 80-item design audit with letter grades. AI Slop detection. Infers your design system. Report only — never touches code. |
|
||||
| `/plan-design-review` | **Senior Designer** | Rates each design dimension 0-10, explains what a 10 looks like, then edits the plan to get there. AI Slop detection. Interactive — one AskUserQuestion per design choice. |
|
||||
| `/design-consultation` | **Design Partner** | Build a complete design system from scratch. Knows the landscape, proposes creative risks, generates realistic product mockups. Design at the heart of all other phases. |
|
||||
| `/review` | **Staff Engineer** | Find the bugs that pass CI but blow up in production. Auto-fixes the obvious ones. Flags completeness gaps. |
|
||||
| `/ship` | **Release Engineer** | Sync main, run tests, audit coverage, push, open PR. Bootstraps test frameworks if you don't have one. One command. |
|
||||
| `/browse` | **QA Engineer** | Give the agent eyes. Real Chromium browser, real clicks, real screenshots. ~100ms per command. |
|
||||
| `/investigate` | **Debugger** | Systematic root-cause debugging. Iron Law: no fixes without investigation. Traces data flow, tests hypotheses, stops after 3 failed fixes. |
|
||||
| `/design-review` | **Designer Who Codes** | Same audit as /plan-design-review, then fixes what it finds. Atomic commits, before/after screenshots. |
|
||||
| `/qa` | **QA Lead** | Test your app, find bugs, fix them with atomic commits, re-verify. Auto-generates regression tests for every fix. |
|
||||
| `/qa-only` | **QA Reporter** | Same methodology as /qa but report only. Use when you want a pure bug report without code changes. |
|
||||
| `/design-review` | **Designer Who Codes** | Same audit as /plan-design-review, then fixes what it finds. Atomic commits, before/after screenshots. |
|
||||
| `/setup-browser-cookies` | **Session Manager** | Import cookies from your real browser (Chrome, Arc, Brave, Edge) into the headless session. Test authenticated pages. |
|
||||
| `/retro` | **Eng Manager** | Team-aware weekly retro. Per-person breakdowns, shipping streaks, test health trends, growth opportunities. |
|
||||
| `/ship` | **Release Engineer** | Sync main, run tests, audit coverage, push, open PR. Bootstraps test frameworks if you don't have one. One command. |
|
||||
| `/document-release` | **Technical Writer** | Update all project docs to match what you just shipped. Catches stale READMEs automatically. |
|
||||
| `/retro` | **Eng Manager** | Team-aware weekly retro. Per-person breakdowns, shipping streaks, test health trends, growth opportunities. |
|
||||
| `/browse` | **QA Engineer** | Give the agent eyes. Real Chromium browser, real clicks, real screenshots. ~100ms per command. |
|
||||
| `/setup-browser-cookies` | **Session Manager** | Import cookies from your real browser (Chrome, Arc, Brave, Edge) into the headless session. Test authenticated pages. |
|
||||
|
||||
### Power tools
|
||||
|
||||
| Skill | What it does |
|
||||
|-------|-------------|
|
||||
| `/codex` | **Second Opinion** — independent code review from OpenAI Codex CLI. Three modes: review (pass/fail gate), adversarial challenge, and open consultation. Cross-model analysis when both `/review` and `/codex` have run. |
|
||||
| `/careful` | **Safety Guardrails** — warns before destructive commands (rm -rf, DROP TABLE, force-push). Say "be careful" to activate. Override any warning. |
|
||||
| `/freeze` | **Edit Lock** — restrict file edits to one directory. Prevents accidental changes outside scope while debugging. |
|
||||
| `/guard` | **Full Safety** — `/careful` + `/freeze` in one command. Maximum safety for prod work. |
|
||||
| `/unfreeze` | **Unlock** — remove the `/freeze` boundary. |
|
||||
| `/gstack-upgrade` | **Self-Updater** — upgrade gstack to latest. Detects global vs vendored install, syncs both, shows what changed. |
|
||||
|
||||
**[Deep dives with examples and philosophy for every skill →](docs/skills.md)**
|
||||
|
||||
## What's new and why it matters
|
||||
|
||||
**`/office-hours` reframes your product before you write code.** You say "daily briefing app." It listens to your actual pain, pushes back on the framing, tells you you're really building a personal chief of staff AI, challenges your premises, and generates three implementation approaches with effort estimates. The design doc it writes feeds directly into `/plan-ceo-review` and `/plan-eng-review` — so every downstream skill starts with real clarity instead of a vague feature request.
|
||||
|
||||
**Design is at the heart.** `/design-consultation` doesn't just pick fonts. It researches what's out there in your space, proposes safe choices AND creative risks, generates realistic mockups of your actual product, and writes `DESIGN.md` — and then `/design-review` and `/plan-eng-review` read what you chose. Design decisions flow through the whole system.
|
||||
|
||||
**`/qa` was a massive unlock.** It let me go from 6 to 12 parallel workers. Claude Code saying *"I SEE THE ISSUE"* and then actually fixing it, generating a regression test, and verifying the fix — that changed how I work. The agent has eyes now.
|
||||
@@ -137,15 +152,25 @@ One feature. Seven commands. The agent reframed the product, ran an 80-item desi
|
||||
|
||||
**Test everything.** `/ship` bootstraps test frameworks from scratch if your project doesn't have one. Every `/ship` run produces a coverage audit. Every `/qa` bug fix generates a regression test. 100% test coverage is the goal — tests make vibe coding safe instead of yolo coding.
|
||||
|
||||
**`/document-release` is the engineer you never had.** It reads every doc file in your project, cross-references the diff, and updates everything that drifted. README, ARCHITECTURE, CONTRIBUTING, CLAUDE.md, TODOS — all kept current automatically.
|
||||
**`/document-release` is the engineer you never had.** It reads every doc file in your project, cross-references the diff, and updates everything that drifted. README, ARCHITECTURE, CONTRIBUTING, CLAUDE.md, TODOS — all kept current automatically. And now `/ship` auto-invokes it — docs stay current without an extra command.
|
||||
|
||||
## 10 sessions at once
|
||||
**Browser handoff when the AI gets stuck.** Hit a CAPTCHA, auth wall, or MFA prompt? `$B handoff` opens a visible Chrome at the exact same page with all your cookies and tabs intact. Solve the problem, tell Claude you're done, `$B resume` picks up right where it left off. The agent even suggests it automatically after 3 consecutive failures.
|
||||
|
||||
gstack is powerful with one session. It is transformative with ten.
|
||||
**Multi-AI second opinion.** `/codex` gets an independent review from OpenAI's Codex CLI — a completely different AI looking at the same diff. Three modes: code review with a pass/fail gate, adversarial challenge that actively tries to break your code, and open consultation with session continuity. When both `/review` (Claude) and `/codex` (OpenAI) have reviewed the same branch, you get a cross-model analysis showing which findings overlap and which are unique to each.
|
||||
|
||||
[Conductor](https://conductor.build) runs multiple Claude Code sessions in parallel — each in its own isolated workspace. One session running `/qa` on staging, another doing `/review` on a PR, a third implementing a feature, and seven more on other branches. All at the same time.
|
||||
**Safety guardrails on demand.** Say "be careful" and `/careful` warns before any destructive command — rm -rf, DROP TABLE, force-push, git reset --hard. `/freeze` locks edits to one directory while debugging so Claude can't accidentally "fix" unrelated code. `/guard` activates both. `/investigate` auto-freezes to the module being investigated.
|
||||
|
||||
One person, ten parallel agents, each with the right cognitive mode. That is a different way of building software.
|
||||
**Proactive skill suggestions.** gstack notices what stage you're in — brainstorming, reviewing, debugging, testing — and suggests the right skill. Don't like it? Say "stop suggesting" and it remembers across sessions.
|
||||
|
||||
## 10-15 parallel sprints
|
||||
|
||||
gstack is powerful with one sprint. It is transformative with ten running at once.
|
||||
|
||||
[Conductor](https://conductor.build) runs multiple Claude Code sessions in parallel — each in its own isolated workspace. One session running `/office-hours` on a new idea, another doing `/review` on a PR, a third implementing a feature, a fourth running `/qa` on staging, and six more on other branches. All at the same time. I regularly run 10-15 parallel sprints — that's the practical max right now.
|
||||
|
||||
The sprint structure is what makes parallelism work. Without a process, ten agents is ten sources of chaos. With a process — think, plan, build, review, test, ship — each agent knows exactly what to do and when to stop. You manage them the way a CEO manages a team: check in on the decisions that matter, let the rest run.
|
||||
|
||||
---
|
||||
|
||||
## Come ride the wave
|
||||
|
||||
@@ -157,7 +182,7 @@ Same tools, different outcome — because gstack gives you structured roles and
|
||||
|
||||
The models are getting better fast. The people who figure out how to work with them now — really work with them, not just dabble — are going to have a massive advantage. This is that window. Let's go.
|
||||
|
||||
Thirteen specialists. All slash commands. All Markdown. All free. **[github.com/garrytan/gstack](https://github.com/garrytan/gstack)** — MIT License
|
||||
Fifteen specialists and six power tools. All slash commands. All Markdown. All free. **[github.com/garrytan/gstack](https://github.com/garrytan/gstack)** — MIT License
|
||||
|
||||
> **We're hiring.** Want to ship 10K+ LOC/day and help harden gstack?
|
||||
> Come work at YC — [ycombinator.com/software](https://ycombinator.com/software)
|
||||
@@ -186,9 +211,10 @@ Thirteen specialists. All slash commands. All Markdown. All free. **[github.com/
|
||||
```
|
||||
## gstack
|
||||
Use /browse from gstack for all web browsing. Never use mcp__claude-in-chrome__* tools.
|
||||
Available skills: /plan-ceo-review, /plan-eng-review, /plan-design-review,
|
||||
/design-consultation, /review, /ship, /browse, /qa, /qa-only, /qa-design-review,
|
||||
/setup-browser-cookies, /retro, /document-release.
|
||||
Available skills: /office-hours, /plan-ceo-review, /plan-eng-review, /plan-design-review,
|
||||
/design-consultation, /review, /ship, /browse, /qa, /qa-only, /design-review,
|
||||
/setup-browser-cookies, /retro, /investigate, /document-release, /codex, /careful,
|
||||
/freeze, /guard, /unfreeze, /gstack-upgrade.
|
||||
```
|
||||
|
||||
### Team sync (optional)
|
||||
|
||||
Reference in New Issue
Block a user