mirror of
https://github.com/garrytan/gstack.git
synced 2026-05-01 19:25:10 +02:00
docs: frame skills as sprint process, rewrite /office-hours examples (#188)
* docs: rewrite /office-hours examples with real session showing premise challenge and reframe Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * docs: anonymize /office-hours examples — remove identifying details Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * docs: tighten See it work example — keep reframe hook, compress details Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * docs: soften user pain description in See it work example Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * docs: reorder skills tables and sections to match sprint workflow Think → plan → review → test → ship → reflect → utilities. /office-hours is now first in both tables and on the page. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> * docs: frame skills as a sprint process, not a tool collection Think → Plan → Build → Review → Test → Ship → Reflect. Each skill feeds into the next. 10-15 parallel sprints is the practical max. Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
Garry Tan
@@ -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.
|
||||
|
||||
@@ -58,79 +59,80 @@ Real files get committed to your repo (not a submodule), so `git clone` just wor
|
||||
## 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** | 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. |
|
||||
| `/debug` | **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. |
|
||||
| `/office-hours` | **YC Office Hours** | Two modes. Startup: six forcing questions on demand, users, and product. Builder: brainstorming for side projects, hackathons, and learning. Writes a design doc with personal observations about how you think. |
|
||||
| `/debug` | **Debugger** | Systematic root-cause debugging. Iron Law: no fixes without investigation. Traces data flow, tests hypotheses, stops after 3 failed fixes. |
|
||||
| `/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. |
|
||||
|
||||
**[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.
|
||||
@@ -141,13 +143,13 @@ One feature. Seven commands. The agent reframed the product, ran an 80-item desi
|
||||
|
||||
**`/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.
|
||||
|
||||
## 10 sessions at once
|
||||
## 10-15 parallel sprints
|
||||
|
||||
gstack is powerful with one session. It is transformative with ten.
|
||||
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 `/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.
|
||||
[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.
|
||||
|
||||
One person, ten parallel agents, each with the right cognitive mode. That is a different way of building software.
|
||||
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.
|
||||
|
||||
---
|
||||
|
||||
|
||||
+160
-121
@@ -4,21 +4,21 @@ Detailed guides for every gstack skill — philosophy, workflow, and examples.
|
||||
|
||||
| Skill | Your specialist | What they do |
|
||||
|-------|----------------|--------------|
|
||||
| [`/office-hours`](#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`](#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`](#plan-eng-review) | **Eng Manager** | Lock in architecture, data flow, diagrams, edge cases, and tests. Forces hidden assumptions into the open. |
|
||||
| [`/plan-design-review`](#plan-design-review) | **Senior Designer** | Interactive plan-mode design review. Rates each dimension 0-10, explains what a 10 looks like, fixes the plan. Works in plan mode. |
|
||||
| [`/design-consultation`](#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`](#review) | **Staff Engineer** | Find the bugs that pass CI but blow up in production. Auto-fixes the obvious ones. Flags completeness gaps. |
|
||||
| [`/ship`](#ship) | **Release Engineer** | Sync main, run tests, audit coverage, push, open PR. Bootstraps test frameworks if you don't have one. One command. |
|
||||
| [`/browse`](#browse) | **QA Engineer** | Give the agent eyes. Real Chromium browser, real clicks, real screenshots. ~100ms per command. |
|
||||
| [`/debug`](#debug) | **Debugger** | Systematic root-cause debugging. Iron Law: no fixes without investigation. Traces data flow, tests hypotheses, stops after 3 failed fixes. |
|
||||
| [`/design-review`](#design-review) | **Designer Who Codes** | Live-site visual audit + fix loop. 80-item audit, then fixes what it finds. Atomic commits, before/after screenshots. |
|
||||
| [`/qa`](#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) | **QA Reporter** | Same methodology as /qa but report only. Use when you want a pure bug report without code changes. |
|
||||
| [`/design-review`](#design-review) | **Designer Who Codes** | Live-site visual audit + fix loop. 80-item audit, then fixes what it finds. Atomic commits, before/after screenshots. |
|
||||
| [`/setup-browser-cookies`](#setup-browser-cookies) | **Session Manager** | Import cookies from your real browser (Chrome, Arc, Brave, Edge) into the headless session. Test authenticated pages. |
|
||||
| [`/retro`](#retro) | **Eng Manager** | Team-aware weekly retro. Per-person breakdowns, shipping streaks, test health trends, growth opportunities. |
|
||||
| [`/office-hours`](#office-hours) | **YC Office Hours** | Two modes. Startup: six forcing questions on demand, users, and product. Builder: brainstorming for side projects, hackathons, and learning. Writes a design doc with personal observations about how you think. |
|
||||
| [`/debug`](#debug) | **Debugger** | Systematic root-cause debugging. Iron Law: no fixes without investigation. Traces data flow, tests hypotheses, stops after 3 failed fixes. |
|
||||
| [`/ship`](#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`](#document-release) | **Technical Writer** | Update all project docs to match what you just shipped. Catches stale READMEs automatically. |
|
||||
| [`/retro`](#retro) | **Eng Manager** | Team-aware weekly retro. Per-person breakdowns, shipping streaks, test health trends, growth opportunities. |
|
||||
| [`/browse`](#browse) | **QA Engineer** | Give the agent eyes. Real Chromium browser, real clicks, real screenshots. ~100ms per command. |
|
||||
| [`/setup-browser-cookies`](#setup-browser-cookies) | **Session Manager** | Import cookies from your real browser (Chrome, Arc, Brave, Edge) into the headless session. Test authenticated pages. |
|
||||
|
||||
---
|
||||
|
||||
@@ -26,25 +26,56 @@ Detailed guides for every gstack skill — philosophy, workflow, and examples.
|
||||
|
||||
This is where every project should start.
|
||||
|
||||
Before you plan, before you review, before you write code — sit down and think about what you're building and why. `/office-hours` is a YC-style conversation that forces clarity before action.
|
||||
Before you plan, before you review, before you write code — sit down with a YC-style partner and think about what you're actually building. Not what you think you're building. What you're *actually* building.
|
||||
|
||||
It works in two modes, and it asks you which one upfront:
|
||||
### The reframe
|
||||
|
||||
Here's what happened on a real project. The user said: "I want to build a daily briefing app for my calendar." Reasonable request. Then it asked about the pain — specific examples, not hypotheticals. They described an assistant missing things, calendar items across multiple Google accounts with stale info, prep docs that were AI slop, events with wrong locations that took forever to track down.
|
||||
|
||||
It came back with: *"I'm going to push back on the framing, because I think you've outgrown it. You said 'daily briefing app for multi-Google-Calendar management.' But what you actually described is a personal chief of staff AI."*
|
||||
|
||||
Then it extracted five capabilities the user didn't realize they were describing:
|
||||
|
||||
1. **Watches your calendar** across all accounts and detects stale info, missing locations, permission gaps
|
||||
2. **Generates real prep work** — not logistics summaries, but *the intellectual work* of preparing for a board meeting, a podcast, a fundraiser
|
||||
3. **Manages your CRM** — who are you meeting, what's the relationship, what do they want, what's the history
|
||||
4. **Prioritizes your time** — flags when prep needs to start early, blocks time proactively, ranks events by importance
|
||||
5. **Trades money for leverage** — actively looks for ways to delegate or automate
|
||||
|
||||
That reframe changed the entire project. They were about to build a calendar app. Now they're building something ten times more valuable — because the skill listened to their pain instead of their feature request.
|
||||
|
||||
### Premise challenge
|
||||
|
||||
After the reframe, it presents premises for you to validate. Not "does this sound good?" — actual falsifiable claims about the product:
|
||||
|
||||
1. The calendar is the anchor data source, but the value is in the intelligence layer on top
|
||||
2. The assistant doesn't get replaced — they get superpowered
|
||||
3. The narrowest wedge is a daily briefing that actually works
|
||||
4. CRM integration is a must-have, not a nice-to-have
|
||||
|
||||
You agree, disagree, or adjust. Every premise you accept becomes load-bearing in the design doc.
|
||||
|
||||
### Implementation alternatives
|
||||
|
||||
Then it generates 2-3 concrete implementation approaches with honest effort estimates:
|
||||
|
||||
- **Approach A: Daily Briefing First** — narrowest wedge, ships tomorrow, M effort (human: ~3 weeks / CC: ~2 days)
|
||||
- **Approach B: CRM-First** — build the relationship graph first, L effort (human: ~6 weeks / CC: ~4 days)
|
||||
- **Approach C: Full Vision** — everything at once, XL effort (human: ~3 months / CC: ~1.5 weeks)
|
||||
|
||||
Recommends A because you learn from real usage. CRM data comes naturally in week two.
|
||||
|
||||
### Two modes
|
||||
|
||||
**Startup mode** — for founders and intrapreneurs building a business. You get six forcing questions distilled from how YC partners evaluate products: demand reality, status quo, desperate specificity, narrowest wedge, observation & surprise, and future-fit. These questions are uncomfortable on purpose. If you can't name a specific human who needs your product, that's the most important thing to learn before writing any code.
|
||||
|
||||
**Builder mode** — for hackathons, side projects, open source, learning, and having fun. You get an enthusiastic collaborator who helps you find the coolest version of your idea. What would make someone say "whoa"? What's the fastest path to something you can share? The questions are generative, not interrogative.
|
||||
|
||||
### The design doc
|
||||
|
||||
Both modes end with a design doc written to `~/.gstack/projects/` — and that doc feeds directly into `/plan-ceo-review` and `/plan-eng-review`. The full lifecycle is now: `office-hours → plan → implement → review → QA → ship → retro`.
|
||||
|
||||
**Personal observations.** After the design doc is approved, `/office-hours` reflects on what it noticed about how you think — not generic praise, but specific callbacks to things you said during the session. The observations appear in the design doc too, so you re-encounter them when you re-read later.
|
||||
|
||||
---
|
||||
|
||||
## `/debug`
|
||||
|
||||
When something is broken and you don't know why, `/debug` is your systematic debugger. It follows the Iron Law: **no fixes without root cause investigation first.**
|
||||
|
||||
Instead of guessing and patching, it traces data flow, matches against known bug patterns, and tests hypotheses one at a time. If three fix attempts fail, it stops and questions the architecture instead of thrashing. This prevents the "let me try one more thing" spiral that wastes hours.
|
||||
After the design doc is approved, `/office-hours` reflects on what it noticed about how you think — not generic praise, but specific callbacks to things you said during the session. The observations appear in the design doc too, so you re-encounter them when you re-read later.
|
||||
|
||||
---
|
||||
|
||||
@@ -409,6 +440,54 @@ I want the model imagining the production incident before it happens.
|
||||
|
||||
---
|
||||
|
||||
## `/debug`
|
||||
|
||||
When something is broken and you don't know why, `/debug` is your systematic debugger. It follows the Iron Law: **no fixes without root cause investigation first.**
|
||||
|
||||
Instead of guessing and patching, it traces data flow, matches against known bug patterns, and tests hypotheses one at a time. If three fix attempts fail, it stops and questions the architecture instead of thrashing. This prevents the "let me try one more thing" spiral that wastes hours.
|
||||
|
||||
---
|
||||
|
||||
## `/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.
|
||||
|
||||
---
|
||||
|
||||
## `/ship`
|
||||
|
||||
This is my **release machine mode**.
|
||||
@@ -435,6 +514,69 @@ A lot of branches die when the interesting work is done and only the boring rele
|
||||
|
||||
---
|
||||
|
||||
## `/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.
|
||||
|
||||
---
|
||||
|
||||
## `/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.
|
||||
|
||||
---
|
||||
|
||||
## `/browse`
|
||||
|
||||
This is my **QA engineer mode**.
|
||||
@@ -480,46 +622,6 @@ 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**.
|
||||
@@ -551,69 +653,6 @@ 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.
|
||||
|
||||
---
|
||||
|
||||
## 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.
|
||||
|
||||
Reference in New Issue
Block a user