mirror of https://github.com/garrytan/gstack.git
docs: remove "competitor" language, rewrite README in Garry's voice
Replace "browses competitors" with "knows the landscape" / "what's out there" throughout all user-facing copy. Trim README from 243 to 167 lines — tighter, more opinionated, less listicle energy. Remove Completeness Principle from README top (it lives in CLAUDE.md and the skill preambles where Claude actually reads it). Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
Garry Tan
parent
1d360003a4
commit
b18ab5ad9e
|
|
@ -86,7 +86,7 @@ Read the philosophy: https://garryslist.org/posts/boil-the-ocean
|
||||||
## 0.5.2 — 2026-03-17
|
## 0.5.2 — 2026-03-17
|
||||||
|
|
||||||
- **Your design consultant now takes creative risks.** `/design-consultation` doesn't just propose a safe, coherent system — it explicitly breaks down SAFE CHOICES (category baseline) vs. RISKS (where your product stands out). You pick which rules to break. Every risk comes with a rationale for why it works and what it costs.
|
- **Your design consultant now takes creative risks.** `/design-consultation` doesn't just propose a safe, coherent system — it explicitly breaks down SAFE CHOICES (category baseline) vs. RISKS (where your product stands out). You pick which rules to break. Every risk comes with a rationale for why it works and what it costs.
|
||||||
- **See the competition before you choose.** When you opt into research, the agent browses competitor sites with screenshots and accessibility tree analysis — not just web search results. You see what the landscape looks like before making design decisions.
|
- **See the landscape before you choose.** When you opt into research, the agent browses real sites in your space with screenshots and accessibility tree analysis — not just web search results. You see what's out there before making design decisions.
|
||||||
- **Preview pages that look like your product.** The preview page now renders realistic product mockups — dashboards with sidebar nav and data tables, marketing pages with hero sections, settings pages with forms — not just font swatches and color palettes.
|
- **Preview pages that look like your product.** The preview page now renders realistic product mockups — dashboards with sidebar nav and data tables, marketing pages with hero sections, settings pages with forms — not just font swatches and color palettes.
|
||||||
|
|
||||||
## 0.5.1 — 2026-03-17
|
## 0.5.1 — 2026-03-17
|
||||||
|
|
|
||||||
172
README.md
172
README.md
|
|
@ -1,123 +1,95 @@
|
||||||
# gstack
|
# gstack
|
||||||
|
|
||||||
**gstack turns Claude Code from one generic assistant into a team of specialists you can summon on demand.**
|
**Thirteen opinionated skills that turn Claude Code into a team you can manage.**
|
||||||
|
|
||||||
Thirteen opinionated workflow skills for [Claude Code](https://docs.anthropic.com/en/docs/claude-code). Plan review, design review, code review, one-command shipping, browser automation, QA testing, engineering retrospectives, and post-ship documentation — all as slash commands.
|
Planning is not review. Review is not shipping. Founder taste is not engineering rigor. If you blur all of that together, you get a mediocre blend of all four.
|
||||||
|
|
||||||
**The Completeness Principle:** Every gstack skill follows one rule — always recommend the complete implementation when AI makes the marginal cost near-zero. No more "Choose B because it's 90% of the value for half the effort" when option A is 70 more lines of code that a machine writes in seconds. We call this **boil the lake** — not boil the ocean (AGI is not here yet), but do the complete thing machines can now do, instead of the incomplete thing humans could only afford in the past. 100% test coverage, full edge case handling, complete implementations. Every recommendation shows both human-team and CC+gstack time so you can see the real cost of completeness.
|
I want explicit gears. I want to tell the model what kind of brain to use right now — founder, eng manager, paranoid reviewer, release machine — and have it commit to that mode completely.
|
||||||
|
|
||||||
### Without gstack
|
That is what gstack does.
|
||||||
|
|
||||||
- The agent takes your request literally — it never asks if you're building the right thing
|
Created by [Garry Tan](https://x.com/garrytan), President & CEO of [Y Combinator](https://www.ycombinator.com/).
|
||||||
- It will implement exactly what you said, even when the real product is something bigger
|
|
||||||
- It recommends shortcuts to save you time — even when the complete version costs 2 minutes of machine time
|
|
||||||
- "Review my PR" gives inconsistent depth every time
|
|
||||||
- "Ship this" turns into a long back-and-forth about what to do
|
|
||||||
- The agent can write code but can't see your app — it's half blind
|
|
||||||
- You still do QA by hand: open browser, click around, check pages, squint at layouts
|
|
||||||
- Your project has no tests, and the agent never suggests setting them up
|
|
||||||
|
|
||||||
### With gstack
|
|
||||||
|
|
||||||
| Skill | Mode | What it does |
|
| Skill | Mode | What it does |
|
||||||
|-------|------|--------------|
|
|-------|------|--------------|
|
||||||
| `/plan-ceo-review` | Founder / CEO | Rethink the problem. Find the 10-star product hiding inside the request. Four modes: Expansion, Selective Expansion, Hold Scope, Reduction. |
|
| `/plan-ceo-review` | Founder | Rethink the problem. Find the 10-star product hiding inside the request. |
|
||||||
| `/plan-eng-review` | Eng manager / tech lead | Lock in architecture, data flow, diagrams, edge cases, and tests. |
|
| `/plan-eng-review` | Eng manager | 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. |
|
| `/plan-design-review` | Senior designer | 80-item design audit with letter grades and AI Slop detection. Report only. |
|
||||||
| `/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. |
|
| `/design-consultation` | Design partner | Build a complete design system from scratch. Knows the landscape, proposes creative risks, generates realistic mockups. |
|
||||||
| `/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. |
|
| `/review` | Staff engineer | Find the bugs that pass CI but blow up in production. Auto-fixes the obvious ones. |
|
||||||
| `/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. |
|
| `/ship` | Release engineer | Sync main, run tests, audit coverage, push, open PR. One command. |
|
||||||
| `/browse` | QA engineer | Give the agent eyes. It logs in, clicks through your app, takes screenshots, catches breakage. Full QA pass in 60 seconds. |
|
| `/browse` | QA engineer | Give the agent eyes. Real browser, real clicks, real screenshots. ~100ms per command. |
|
||||||
| `/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` | QA lead | Test your app, find bugs, fix them, re-verify. Generates regression tests for every fix. |
|
||||||
| `/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-only` | QA reporter | Same testing methodology as /qa but report only — never touches code. |
|
||||||
| `/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. |
|
| `/qa-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 (Comet, Chrome, Arc, Brave, Edge) into the headless session. Test authenticated pages without logging in manually. |
|
| `/setup-browser-cookies` | Session manager | Import cookies from your real browser into the headless session. Test authenticated pages. |
|
||||||
| `/retro` | Engineering manager | Team-aware retro: your deep-dive + per-person praise and growth opportunities for every contributor. Tracks test health. |
|
| `/retro` | Eng manager | Team-aware weekly retro with per-person breakdowns, metrics, and trends. |
|
||||||
| `/document-release` | Technical writer | Update README, ARCHITECTURE, CONTRIBUTING, and project docs to match what you just shipped. |
|
| `/document-release` | Technical writer | Update all project docs to match what you just shipped. |
|
||||||
|
|
||||||
**[Detailed skill guides with examples and philosophy](docs/skills.md)**
|
**[Detailed guides with examples and philosophy for every skill](docs/skills.md)**
|
||||||
|
|
||||||
## Demo: one feature, five modes
|
## Demo
|
||||||
|
|
||||||
```
|
```
|
||||||
You: [enter plan mode, describe the feature]
|
You: I want to add seller photo upload to the listing app.
|
||||||
I want to add seller photo upload to the listing app. Sellers
|
|
||||||
should be able to upload a photo of their item and we create
|
|
||||||
the listing from it.
|
|
||||||
|
|
||||||
You: /plan-ceo-review
|
You: /plan-ceo-review
|
||||||
|
|
||||||
Claude: "Photo upload" is not the feature. The real job is helping sellers
|
Claude: "Photo upload" is not the feature. The real job is helping sellers
|
||||||
create listings that actually sell. Here's what the 10-star version
|
create listings that actually sell. Here's the 10-star version:
|
||||||
looks like: auto-identify the product from the photo, pull specs and
|
auto-identify the product, pull specs and comps from the web,
|
||||||
pricing comps from the web, draft the title and description, suggest
|
draft the title and description, suggest the best hero image...
|
||||||
the best hero image...
|
|
||||||
|
|
||||||
You: /plan-eng-review
|
You: /plan-eng-review
|
||||||
|
|
||||||
Claude: [Architecture diagram, state machine for upload → classify → enrich
|
Claude: [Architecture diagram, state machine for upload → classify → enrich
|
||||||
→ draft pipeline, async job boundaries, failure modes, test matrix]
|
→ draft pipeline, async job boundaries, failure modes, test matrix]
|
||||||
|
|
||||||
You: [exit plan mode, implement the plan]
|
You: [implement the plan]
|
||||||
|
|
||||||
You: /review
|
You: /review
|
||||||
|
|
||||||
Claude: Race condition: two tabs can overwrite cover-photo selection.
|
Claude: Race condition: two tabs can overwrite cover-photo selection.
|
||||||
Trust boundary: pulling web data into draft generation creates
|
Trust boundary: web data into draft generation = prompt injection.
|
||||||
a prompt injection vector. Missing: orphan cleanup for failed uploads.
|
|
||||||
[AUTO-FIXED] 2 issues. 1 needs your input.
|
[AUTO-FIXED] 2 issues. 1 needs your input.
|
||||||
|
|
||||||
You: (fix the remaining issue)
|
|
||||||
|
|
||||||
You: /ship
|
You: /ship
|
||||||
|
|
||||||
Claude: [Syncs main, runs tests, coverage audit, pushes branch, opens PR]
|
Claude: Tests: 42 → 47 (+5 new). PR: github.com/you/app/pull/42
|
||||||
Tests: 42 → 47 (+5 new). PR: github.com/you/app/pull/42
|
|
||||||
|
|
||||||
You: /qa
|
You: /qa https://staging.myapp.com
|
||||||
|
|
||||||
Claude: Analyzing branch diff... 8 files changed, 3 routes affected.
|
Claude: All 3 affected routes working. Upload + enrichment flow passes
|
||||||
[Tests /listings/new, /listings/:id, /api/listings against localhost:3000]
|
end to end. Regression test generated.
|
||||||
All 3 routes working. Upload + enrichment flow passes end to end.
|
|
||||||
Regression test generated: test/qa-regression-001.test.ts
|
|
||||||
|
|
||||||
You: /plan-design-review https://staging.myapp.com
|
You: /plan-design-review https://staging.myapp.com
|
||||||
|
|
||||||
Claude: Design Score: B | AI Slop Score: C
|
Claude: Design Score: B | AI Slop Score: C
|
||||||
"The site communicates competence but not confidence."
|
"The site communicates competence but not confidence."
|
||||||
Top issues: generic typography, AI slop patterns, 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]
|
|
||||||
Design Score: B → A- | AI Slop Score: C → A
|
|
||||||
```
|
```
|
||||||
|
|
||||||
## Who this is for
|
## Who this is for
|
||||||
|
|
||||||
You already use Claude Code heavily and want consistent, high-rigor workflows instead of one mushy generic mode. You want to tell the model what kind of brain to use right now — founder taste, engineering rigor, paranoid review, or fast execution.
|
You already use Claude Code and want it to stop being one mushy generic mode. You want the model to have opinions, catch things you would miss, and execute without hand-holding.
|
||||||
|
|
||||||
This is not a prompt pack for beginners. It is an operating system for people who ship.
|
This is not a prompt pack for beginners. It is an operating system for people who ship.
|
||||||
|
|
||||||
## How to fly: 10 sessions at once
|
## 10 sessions at once
|
||||||
|
|
||||||
gstack is powerful with one Claude Code session. It is transformative with ten.
|
gstack is powerful with one session. It is transformative with ten.
|
||||||
|
|
||||||
[Conductor](https://conductor.build) runs multiple Claude Code sessions in parallel — each in its own isolated workspace. That means you can have one session running `/qa` on staging, another doing `/review` on a PR, a third implementing a feature, and seven more working 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 `/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.
|
||||||
|
|
||||||
Each workspace gets its own isolated browser instance automatically — separate Chromium process, cookies, tabs, and logs stored in `.gstack/` inside each project root. No port collisions, no shared state, no configuration needed. `/browse` and `/qa` sessions never interfere with each other, even across ten parallel workspaces.
|
Each workspace gets its own isolated browser instance automatically. No port collisions, no shared state, no configuration. One person, ten parallel agents, each with the right cognitive mode. That is a different way of building software.
|
||||||
|
|
||||||
This is the setup I use. One person, ten parallel agents, each with the right cognitive mode for its task. That is not incremental improvement. That is a different way of building software.
|
|
||||||
|
|
||||||
## Install
|
## Install
|
||||||
|
|
||||||
**Requirements:** [Claude Code](https://docs.anthropic.com/en/docs/claude-code), [Git](https://git-scm.com/), [Bun](https://bun.sh/) v1.0+. `/browse` compiles a native binary — works on macOS and Linux (x64 and arm64).
|
**Requirements:** [Claude Code](https://docs.anthropic.com/en/docs/claude-code), [Git](https://git-scm.com/), [Bun](https://bun.sh/) v1.0+
|
||||||
|
|
||||||
### Step 1: Install on your machine
|
### Step 1: Install on your machine
|
||||||
|
|
||||||
Open Claude Code and paste this. Claude will do the rest.
|
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: /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.
|
||||||
|
|
||||||
|
|
@ -125,15 +97,7 @@ Open Claude Code and paste this. Claude will do the rest.
|
||||||
|
|
||||||
> 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: /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.
|
||||||
|
|
||||||
Real files get committed to your repo (not a submodule), so `git clone` just works. The binary and node\_modules are gitignored — teammates just need to run `cd .claude/skills/gstack && ./setup` once to build (or `/browse` handles it automatically on first use).
|
Real files get committed to your repo (not a submodule), so `git clone` just works. The binary and node\_modules are gitignored — teammates run `cd .claude/skills/gstack && ./setup` once to build.
|
||||||
|
|
||||||
### What gets installed
|
|
||||||
|
|
||||||
- Skill files (Markdown prompts) in `~/.claude/skills/gstack/` (or `.claude/skills/gstack/` for project installs)
|
|
||||||
- Symlinks at `~/.claude/skills/browse`, `~/.claude/skills/qa`, `~/.claude/skills/review`, etc. pointing into the gstack directory
|
|
||||||
- Browser binary at `browse/dist/browse` (~58MB, gitignored)
|
|
||||||
- `node_modules/` (gitignored)
|
|
||||||
- `/retro` saves JSON snapshots to `.context/retros/` in your project for trend tracking
|
|
||||||
|
|
||||||
Everything lives inside `.claude/`. Nothing touches your PATH or runs in the background.
|
Everything lives inside `.claude/`. Nothing touches your PATH or runs in the background.
|
||||||
|
|
||||||
|
|
@ -156,67 +120,37 @@ Everything lives inside `.claude/`. Nothing touches your PATH or runs in the bac
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## How I use these skills
|
|
||||||
|
|
||||||
Created by [Garry Tan](https://x.com/garrytan), President & CEO of [Y Combinator](https://www.ycombinator.com/).
|
|
||||||
|
|
||||||
I built gstack because I do not want AI coding tools stuck in one mushy mode.
|
|
||||||
|
|
||||||
Planning is not review. Review is not shipping. Founder taste is not engineering rigor. If you blur all of that together, you usually get a mediocre blend of all four.
|
|
||||||
|
|
||||||
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.
|
|
||||||
|
|
||||||
**[Read the full philosophy and per-skill deep dives](docs/skills.md)**
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Greptile integration
|
## Greptile integration
|
||||||
|
|
||||||
[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.
|
[Greptile](https://greptile.com) 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 guide](docs/greptile.md)**
|
||||||
|
|
||||||
**Setup:** Install Greptile on your GitHub repo at [greptile.com](https://greptile.com). gstack picks up its comments automatically.
|
|
||||||
|
|
||||||
**[Full Greptile integration guide](docs/greptile.md)**
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Contributor mode
|
## Contributor 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.
|
Turn on contributor mode and gstack files bug reports when something goes wrong. Fork gstack and fix it yourself. **[Guide](docs/contributor-mode.md)**
|
||||||
|
|
||||||
**[Contributor mode guide](docs/contributor-mode.md)**
|
|
||||||
|
|
||||||
---
|
|
||||||
|
|
||||||
## Troubleshooting
|
## Troubleshooting
|
||||||
|
|
||||||
**Skill not showing up in Claude Code?**
|
**Skill not showing up?**
|
||||||
Run `cd ~/.claude/skills/gstack && ./setup` (or `cd .claude/skills/gstack && ./setup` for project installs). This rebuilds symlinks so Claude can discover the skills.
|
`cd ~/.claude/skills/gstack && ./setup`
|
||||||
|
|
||||||
**`/browse` fails or binary not found?**
|
**`/browse` fails?**
|
||||||
Run `cd ~/.claude/skills/gstack && bun install && bun run build`. This compiles the browser binary. Requires Bun v1.0+.
|
`cd ~/.claude/skills/gstack && bun install && bun run build`
|
||||||
|
|
||||||
**Project copy is stale?**
|
**Project copy is stale?**
|
||||||
Run `/gstack-upgrade` — it updates both the global install and any vendored project copy automatically.
|
Run `/gstack-upgrade`
|
||||||
|
|
||||||
**`bun` not installed?**
|
**`bun` not installed?**
|
||||||
Install it: `curl -fsSL https://bun.sh/install | bash`
|
`curl -fsSL https://bun.sh/install | bash`
|
||||||
|
|
||||||
## Upgrading
|
## Upgrading
|
||||||
|
|
||||||
Run `/gstack-upgrade` in Claude Code. It detects your install type (global or vendored), upgrades, syncs any project copies, and shows what's new.
|
Run `/gstack-upgrade` in Claude Code. Or set `auto_upgrade: true` in `~/.gstack/config.yaml`.
|
||||||
|
|
||||||
Or set `auto_upgrade: true` in `~/.gstack/config.yaml` to upgrade automatically whenever a new version is available.
|
|
||||||
|
|
||||||
## Uninstalling
|
## Uninstalling
|
||||||
|
|
||||||
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.
|
> 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.
|
||||||
|
|
||||||
## Documentation
|
## Docs
|
||||||
|
|
||||||
| Doc | What it covers |
|
| Doc | What it covers |
|
||||||
|-----|---------------|
|
|-----|---------------|
|
||||||
|
|
@ -228,16 +162,6 @@ Paste this into Claude Code:
|
||||||
| [Contributing](CONTRIBUTING.md) | Dev setup, testing, and dev mode |
|
| [Contributing](CONTRIBUTING.md) | Dev setup, testing, and dev mode |
|
||||||
| [Changelog](CHANGELOG.md) | What's new in every version |
|
| [Changelog](CHANGELOG.md) | What's new in every version |
|
||||||
|
|
||||||
### Testing
|
|
||||||
|
|
||||||
```bash
|
|
||||||
bun test # free static tests (<5s)
|
|
||||||
EVALS=1 bun run test:evals # full E2E + LLM evals (~$4, ~20min)
|
|
||||||
bun run eval:watch # live dashboard during E2E runs
|
|
||||||
```
|
|
||||||
|
|
||||||
E2E tests stream real-time progress, write machine-readable diagnostics, and persist partial results that survive kills. See CONTRIBUTING.md for the full eval infrastructure.
|
|
||||||
|
|
||||||
## License
|
## License
|
||||||
|
|
||||||
MIT
|
MIT
|
||||||
|
|
|
||||||
|
|
@ -2,7 +2,7 @@
|
||||||
name: design-consultation
|
name: design-consultation
|
||||||
version: 1.0.0
|
version: 1.0.0
|
||||||
description: |
|
description: |
|
||||||
Design consultation: understands your product, researches competitors, proposes a
|
Design consultation: understands your product, researches the landscape, proposes a
|
||||||
complete design system (aesthetic, typography, color, layout, spacing, motion), and
|
complete design system (aesthetic, typography, color, layout, spacing, motion), and
|
||||||
generates font+color preview pages. Creates DESIGN.md as your project's design source
|
generates font+color preview pages. Creates DESIGN.md as your project's design source
|
||||||
of truth. For existing sites, use /plan-design-review to infer the system instead.
|
of truth. For existing sites, use /plan-design-review to infer the system instead.
|
||||||
|
|
@ -197,7 +197,7 @@ Ask the user a single question that covers everything you need to know. Pre-fill
|
||||||
3. "Want me to research what top products in your space are doing for design, or should I work from my design knowledge?"
|
3. "Want me to research what top products in your space are doing for design, or should I work from my design knowledge?"
|
||||||
4. **Explicitly say:** "At any point you can just drop into chat and we'll talk through anything — this isn't a rigid form, it's a conversation."
|
4. **Explicitly say:** "At any point you can just drop into chat and we'll talk through anything — this isn't a rigid form, it's a conversation."
|
||||||
|
|
||||||
If the README or brainstorm gives you enough context, pre-fill and confirm: *"From what I can see, this is [X] for [Y] in the [Z] space. Sound right? And would you like me to research competitors, or should I work from what I know?"*
|
If the README or brainstorm gives you enough context, pre-fill and confirm: *"From what I can see, this is [X] for [Y] in the [Z] space. Sound right? And would you like me to research what's out there in this space, or should I work from what I know?"*
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
|
|
@ -205,7 +205,7 @@ If the README or brainstorm gives you enough context, pre-fill and confirm: *"Fr
|
||||||
|
|
||||||
If the user wants competitive research:
|
If the user wants competitive research:
|
||||||
|
|
||||||
**Step 1: Identify competitors via WebSearch**
|
**Step 1: Identify what's out there via WebSearch**
|
||||||
|
|
||||||
Use WebSearch to find 5-10 products in their space. Search for:
|
Use WebSearch to find 5-10 products in their space. Search for:
|
||||||
- "[product category] website design"
|
- "[product category] website design"
|
||||||
|
|
@ -214,17 +214,17 @@ Use WebSearch to find 5-10 products in their space. Search for:
|
||||||
|
|
||||||
**Step 2: Visual research via browse (if available)**
|
**Step 2: Visual research via browse (if available)**
|
||||||
|
|
||||||
If the browse binary is available (`$B` is set), visit the top 3-5 competitor sites and capture visual evidence:
|
If the browse binary is available (`$B` is set), visit the top 3-5 sites in the space and capture visual evidence:
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
$B goto "https://competitor-site.com"
|
$B goto "https://example-site.com"
|
||||||
$B screenshot "/tmp/design-research-competitor-name.png"
|
$B screenshot "/tmp/design-research-site-name.png"
|
||||||
$B snapshot
|
$B snapshot
|
||||||
```
|
```
|
||||||
|
|
||||||
For each competitor, analyze: fonts actually used, color palette, layout approach, spacing density, aesthetic direction. The screenshot gives you the feel; the snapshot gives you structural data.
|
For each site, analyze: fonts actually used, color palette, layout approach, spacing density, aesthetic direction. The screenshot gives you the feel; the snapshot gives you structural data.
|
||||||
|
|
||||||
If a competitor site blocks the headless browser or requires login, skip it and note why.
|
If a site blocks the headless browser or requires login, skip it and note why.
|
||||||
|
|
||||||
If browse is not available, rely on WebSearch results and your built-in design knowledge — this is fine.
|
If browse is not available, rely on WebSearch results and your built-in design knowledge — this is fine.
|
||||||
|
|
||||||
|
|
@ -233,7 +233,7 @@ If browse is not available, rely on WebSearch results and your built-in design k
|
||||||
The goal of research is NOT to copy. It is to get in the ballpark — to understand the visual language users in this category already expect. This gives you the baseline. The interesting design work starts after you have the baseline: deciding where to follow conventions (so the product feels literate) and where to break from them (so the product is memorable).
|
The goal of research is NOT to copy. It is to get in the ballpark — to understand the visual language users in this category already expect. This gives you the baseline. The interesting design work starts after you have the baseline: deciding where to follow conventions (so the product feels literate) and where to break from them (so the product is memorable).
|
||||||
|
|
||||||
Summarize conversationally:
|
Summarize conversationally:
|
||||||
> "I looked at [competitors]. Here's the landscape: they converge on [patterns]. Most of them feel [observation — e.g., interchangeable, polished but generic, etc.]. The opportunity to stand out is [gap]. Here's where I'd play it safe and where I'd take a risk..."
|
> "I looked at what's out there. Here's the landscape: they converge on [patterns]. Most of them feel [observation — e.g., interchangeable, polished but generic, etc.]. The opportunity to stand out is [gap]. Here's where I'd play it safe and where I'd take a risk..."
|
||||||
|
|
||||||
**Graceful degradation:**
|
**Graceful degradation:**
|
||||||
- Browse available → screenshots + snapshots + WebSearch (richest research)
|
- Browse available → screenshots + snapshots + WebSearch (richest research)
|
||||||
|
|
|
||||||
|
|
@ -2,7 +2,7 @@
|
||||||
name: design-consultation
|
name: design-consultation
|
||||||
version: 1.0.0
|
version: 1.0.0
|
||||||
description: |
|
description: |
|
||||||
Design consultation: understands your product, researches competitors, proposes a
|
Design consultation: understands your product, researches the landscape, proposes a
|
||||||
complete design system (aesthetic, typography, color, layout, spacing, motion), and
|
complete design system (aesthetic, typography, color, layout, spacing, motion), and
|
||||||
generates font+color preview pages. Creates DESIGN.md as your project's design source
|
generates font+color preview pages. Creates DESIGN.md as your project's design source
|
||||||
of truth. For existing sites, use /plan-design-review to infer the system instead.
|
of truth. For existing sites, use /plan-design-review to infer the system instead.
|
||||||
|
|
@ -76,7 +76,7 @@ Ask the user a single question that covers everything you need to know. Pre-fill
|
||||||
3. "Want me to research what top products in your space are doing for design, or should I work from my design knowledge?"
|
3. "Want me to research what top products in your space are doing for design, or should I work from my design knowledge?"
|
||||||
4. **Explicitly say:** "At any point you can just drop into chat and we'll talk through anything — this isn't a rigid form, it's a conversation."
|
4. **Explicitly say:** "At any point you can just drop into chat and we'll talk through anything — this isn't a rigid form, it's a conversation."
|
||||||
|
|
||||||
If the README or brainstorm gives you enough context, pre-fill and confirm: *"From what I can see, this is [X] for [Y] in the [Z] space. Sound right? And would you like me to research competitors, or should I work from what I know?"*
|
If the README or brainstorm gives you enough context, pre-fill and confirm: *"From what I can see, this is [X] for [Y] in the [Z] space. Sound right? And would you like me to research what's out there in this space, or should I work from what I know?"*
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
|
|
@ -84,7 +84,7 @@ If the README or brainstorm gives you enough context, pre-fill and confirm: *"Fr
|
||||||
|
|
||||||
If the user wants competitive research:
|
If the user wants competitive research:
|
||||||
|
|
||||||
**Step 1: Identify competitors via WebSearch**
|
**Step 1: Identify what's out there via WebSearch**
|
||||||
|
|
||||||
Use WebSearch to find 5-10 products in their space. Search for:
|
Use WebSearch to find 5-10 products in their space. Search for:
|
||||||
- "[product category] website design"
|
- "[product category] website design"
|
||||||
|
|
@ -93,17 +93,17 @@ Use WebSearch to find 5-10 products in their space. Search for:
|
||||||
|
|
||||||
**Step 2: Visual research via browse (if available)**
|
**Step 2: Visual research via browse (if available)**
|
||||||
|
|
||||||
If the browse binary is available (`$B` is set), visit the top 3-5 competitor sites and capture visual evidence:
|
If the browse binary is available (`$B` is set), visit the top 3-5 sites in the space and capture visual evidence:
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
$B goto "https://competitor-site.com"
|
$B goto "https://example-site.com"
|
||||||
$B screenshot "/tmp/design-research-competitor-name.png"
|
$B screenshot "/tmp/design-research-site-name.png"
|
||||||
$B snapshot
|
$B snapshot
|
||||||
```
|
```
|
||||||
|
|
||||||
For each competitor, analyze: fonts actually used, color palette, layout approach, spacing density, aesthetic direction. The screenshot gives you the feel; the snapshot gives you structural data.
|
For each site, analyze: fonts actually used, color palette, layout approach, spacing density, aesthetic direction. The screenshot gives you the feel; the snapshot gives you structural data.
|
||||||
|
|
||||||
If a competitor site blocks the headless browser or requires login, skip it and note why.
|
If a site blocks the headless browser or requires login, skip it and note why.
|
||||||
|
|
||||||
If browse is not available, rely on WebSearch results and your built-in design knowledge — this is fine.
|
If browse is not available, rely on WebSearch results and your built-in design knowledge — this is fine.
|
||||||
|
|
||||||
|
|
@ -112,7 +112,7 @@ If browse is not available, rely on WebSearch results and your built-in design k
|
||||||
The goal of research is NOT to copy. It is to get in the ballpark — to understand the visual language users in this category already expect. This gives you the baseline. The interesting design work starts after you have the baseline: deciding where to follow conventions (so the product feels literate) and where to break from them (so the product is memorable).
|
The goal of research is NOT to copy. It is to get in the ballpark — to understand the visual language users in this category already expect. This gives you the baseline. The interesting design work starts after you have the baseline: deciding where to follow conventions (so the product feels literate) and where to break from them (so the product is memorable).
|
||||||
|
|
||||||
Summarize conversationally:
|
Summarize conversationally:
|
||||||
> "I looked at [competitors]. Here's the landscape: they converge on [patterns]. Most of them feel [observation — e.g., interchangeable, polished but generic, etc.]. The opportunity to stand out is [gap]. Here's where I'd play it safe and where I'd take a risk..."
|
> "I looked at what's out there. Here's the landscape: they converge on [patterns]. Most of them feel [observation — e.g., interchangeable, polished but generic, etc.]. The opportunity to stand out is [gap]. Here's where I'd play it safe and where I'd take a risk..."
|
||||||
|
|
||||||
**Graceful degradation:**
|
**Graceful degradation:**
|
||||||
- Browse available → screenshots + snapshots + WebSearch (richest research)
|
- Browse available → screenshots + snapshots + WebSearch (richest research)
|
||||||
|
|
|
||||||
|
|
@ -204,7 +204,7 @@ But coherence is table stakes. Every dev tool dashboard looks the same — clean
|
||||||
|
|
||||||
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.
|
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.
|
If you want, the agent will research what's already out there in your space — take screenshots of real sites, 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.
|
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.
|
||||||
|
|
||||||
|
|
@ -217,7 +217,7 @@ You: /design-consultation
|
||||||
|
|
||||||
Claude: From the README, this looks like a developer analytics dashboard
|
Claude: From the README, this looks like a developer analytics dashboard
|
||||||
for engineering teams. Sound right? Tell me about the feeling
|
for engineering teams. Sound right? Tell me about the feeling
|
||||||
you want — and would you like me to browse some competitors
|
you want — and would you like me to look at what's out there
|
||||||
first so we can see the landscape?
|
first so we can see the landscape?
|
||||||
|
|
||||||
You: Yes, it's for eng managers. Show me what's out there.
|
You: Yes, it's for eng managers. Show me what's out there.
|
||||||
|
|
@ -246,7 +246,7 @@ Claude: [browses Linear, Vercel, Datadog, Posthog — takes screenshots]
|
||||||
Instrument Serif for display headings — nobody in dev tools
|
Instrument Serif for display headings — nobody in dev tools
|
||||||
uses a serif. It creates instant hierarchy contrast and
|
uses a serif. It creates instant hierarchy contrast and
|
||||||
signals "we care about craft" in a space full of sans-serifs.
|
signals "we care about craft" in a space full of sans-serifs.
|
||||||
Single teal accent instead of blue — every competitor uses blue.
|
Single teal accent instead of blue — everyone else in this space uses blue.
|
||||||
Teal is close enough to feel trustworthy, different enough
|
Teal is close enough to feel trustworthy, different enough
|
||||||
to be recognizable.
|
to be recognizable.
|
||||||
4px compact density — tighter than Linear, says "we respect
|
4px compact density — tighter than Linear, says "we respect
|
||||||
|
|
|
||||||
|
|
@ -1886,7 +1886,7 @@ Write DESIGN.md and CLAUDE.md (or update it) in the working directory.`,
|
||||||
|
|
||||||
This is a civic tech data platform called CivicPulse. Read the README.md.
|
This is a civic tech data platform called CivicPulse. Read the README.md.
|
||||||
|
|
||||||
DO research competitors before proposing — search for civic tech and government data platform designs. Skip the font preview page. Skip any AskUserQuestion calls — this is non-interactive.
|
DO research what's out there before proposing — search for civic tech and government data platform designs. Skip the font preview page. Skip any AskUserQuestion calls — this is non-interactive.
|
||||||
|
|
||||||
Write DESIGN.md to the working directory.`,
|
Write DESIGN.md to the working directory.`,
|
||||||
workingDirectory: designDir,
|
workingDirectory: designDir,
|
||||||
|
|
|
||||||
Loading…
Reference in New Issue