mirror of
https://github.com/garrytan/gstack.git
synced 2026-05-05 13:15:24 +02:00
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
+1
-1
@@ -86,7 +86,7 @@ Read the philosophy: https://garryslist.org/posts/boil-the-ocean
|
||||
## 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.
|
||||
- **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.
|
||||
|
||||
## 0.5.1 — 2026-03-17
|
||||
|
||||
@@ -1,123 +1,95 @@
|
||||
# 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
|
||||
- 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
|
||||
Created by [Garry Tan](https://x.com/garrytan), President & CEO of [Y Combinator](https://www.ycombinator.com/).
|
||||
|
||||
| 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-eng-review` | Eng manager / tech lead | Lock in architecture, data flow, diagrams, edge cases, and tests. |
|
||||
| `/plan-design-review` | Senior product designer | Designer's eye audit. 80-item checklist, letter grades, AI Slop detection, DESIGN.md inference. Report only — never touches code. |
|
||||
| `/design-consultation` | Design consultant | Build a complete design system from scratch. Browses competitors to get in the ballpark, proposes safe choices AND creative risks, generates realistic product mockups, and writes DESIGN.md. |
|
||||
| `/review` | Paranoid staff engineer | Find the bugs that pass CI but blow up in production. Auto-fixes obvious issues. Triages Greptile review comments. Flags completeness gaps. |
|
||||
| `/ship` | Release engineer | Sync main, run tests, audit coverage, resolve Greptile reviews, push, open PR. Auto-bootstraps test frameworks if your project doesn't have one. |
|
||||
| `/browse` | QA engineer | Give the agent eyes. It logs in, clicks through your app, takes screenshots, catches breakage. Full QA pass in 60 seconds. |
|
||||
| `/qa` | QA + fix engineer | Test app, find bugs, fix them with atomic commits, re-verify. Auto-generates regression tests for every fix. Three tiers: Quick, Standard, Exhaustive. |
|
||||
| `/qa-only` | QA reporter | Report-only QA testing. Same methodology as /qa but never fixes anything. Use when you want a pure bug report without code changes. |
|
||||
| `/qa-design-review` | Designer + frontend engineer | Same design audit as /plan-design-review, then fixes what it finds. Atomic `style(design):` commits, before/after screenshots, CSS-safe self-regulation. |
|
||||
| `/setup-browser-cookies` | Session manager | Import cookies from your real browser (Comet, Chrome, Arc, Brave, Edge) into the headless session. Test authenticated pages without logging in manually. |
|
||||
| `/retro` | Engineering manager | Team-aware retro: your deep-dive + per-person praise and growth opportunities for every contributor. Tracks test health. |
|
||||
| `/document-release` | Technical writer | Update README, ARCHITECTURE, CONTRIBUTING, and project docs to match what you just shipped. |
|
||||
| `/plan-ceo-review` | Founder | Rethink the problem. Find the 10-star product hiding inside the request. |
|
||||
| `/plan-eng-review` | Eng manager | Lock in architecture, data flow, diagrams, edge cases, and tests. |
|
||||
| `/plan-design-review` | Senior designer | 80-item design audit with letter grades and AI Slop detection. Report only. |
|
||||
| `/design-consultation` | Design partner | Build a complete design system from scratch. Knows the landscape, proposes creative risks, generates realistic mockups. |
|
||||
| `/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, push, open PR. One command. |
|
||||
| `/browse` | QA engineer | Give the agent eyes. Real browser, real clicks, real screenshots. ~100ms per command. |
|
||||
| `/qa` | QA lead | Test your app, find bugs, fix them, re-verify. Generates regression tests for every fix. |
|
||||
| `/qa-only` | QA reporter | Same testing methodology as /qa but report only — never touches code. |
|
||||
| `/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 into the headless session. Test authenticated pages. |
|
||||
| `/retro` | Eng manager | Team-aware weekly retro with per-person breakdowns, metrics, and trends. |
|
||||
| `/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]
|
||||
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: I want to add seller photo upload to the listing app.
|
||||
|
||||
You: /plan-ceo-review
|
||||
|
||||
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
|
||||
looks like: auto-identify the product from the photo, pull specs and
|
||||
pricing comps from the web, draft the title and description, suggest
|
||||
the best hero image...
|
||||
create listings that actually sell. Here's the 10-star version:
|
||||
auto-identify the product, pull specs and comps from the web,
|
||||
draft the title and description, suggest the best hero image...
|
||||
|
||||
You: /plan-eng-review
|
||||
|
||||
Claude: [Architecture diagram, state machine for upload → classify → enrich
|
||||
→ draft pipeline, async job boundaries, failure modes, test matrix]
|
||||
|
||||
You: [exit plan mode, implement the plan]
|
||||
You: [implement the plan]
|
||||
|
||||
You: /review
|
||||
|
||||
Claude: Race condition: two tabs can overwrite cover-photo selection.
|
||||
Trust boundary: pulling web data into draft generation creates
|
||||
a prompt injection vector. Missing: orphan cleanup for failed uploads.
|
||||
Trust boundary: web data into draft generation = prompt injection.
|
||||
[AUTO-FIXED] 2 issues. 1 needs your input.
|
||||
|
||||
You: (fix the remaining issue)
|
||||
|
||||
You: /ship
|
||||
|
||||
Claude: [Syncs main, runs tests, coverage audit, pushes branch, opens PR]
|
||||
Tests: 42 → 47 (+5 new). PR: github.com/you/app/pull/42
|
||||
Claude: 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.
|
||||
[Tests /listings/new, /listings/:id, /api/listings against localhost:3000]
|
||||
All 3 routes working. Upload + enrichment flow passes end to end.
|
||||
Regression test generated: test/qa-regression-001.test.ts
|
||||
Claude: All 3 affected routes working. Upload + enrichment flow passes
|
||||
end to end. Regression test generated.
|
||||
|
||||
You: /plan-design-review https://staging.myapp.com
|
||||
|
||||
Claude: Design Score: B | AI Slop Score: C
|
||||
"The site communicates competence but not confidence."
|
||||
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
|
||||
|
||||
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.
|
||||
|
||||
## 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.
|
||||
|
||||
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.
|
||||
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.
|
||||
|
||||
## 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
|
||||
|
||||
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.
|
||||
|
||||
@@ -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.
|
||||
|
||||
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).
|
||||
|
||||
### 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
|
||||
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.
|
||||
|
||||
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](https://greptile.com) is a YC company that reviews your PRs automatically. gstack triages Greptile's comments as part of `/review` and `/ship` — valid issues get fixed, false positives get pushed back with evidence, already-fixed issues get auto-acknowledged.
|
||||
|
||||
**Setup:** Install Greptile on your GitHub repo at [greptile.com](https://greptile.com). gstack picks up its comments automatically.
|
||||
|
||||
**[Full Greptile integration guide](docs/greptile.md)**
|
||||
|
||||
---
|
||||
[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)**
|
||||
|
||||
## 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.
|
||||
|
||||
**[Contributor mode guide](docs/contributor-mode.md)**
|
||||
|
||||
---
|
||||
Turn on contributor mode and gstack files bug reports when something goes wrong. Fork gstack and fix it yourself. **[Guide](docs/contributor-mode.md)**
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
**Skill not showing up in Claude Code?**
|
||||
Run `cd ~/.claude/skills/gstack && ./setup` (or `cd .claude/skills/gstack && ./setup` for project installs). This rebuilds symlinks so Claude can discover the skills.
|
||||
**Skill not showing up?**
|
||||
`cd ~/.claude/skills/gstack && ./setup`
|
||||
|
||||
**`/browse` fails or binary not found?**
|
||||
Run `cd ~/.claude/skills/gstack && bun install && bun run build`. This compiles the browser binary. Requires Bun v1.0+.
|
||||
**`/browse` fails?**
|
||||
`cd ~/.claude/skills/gstack && bun install && bun run build`
|
||||
|
||||
**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?**
|
||||
Install it: `curl -fsSL https://bun.sh/install | bash`
|
||||
`curl -fsSL https://bun.sh/install | bash`
|
||||
|
||||
## 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.
|
||||
|
||||
Or set `auto_upgrade: true` in `~/.gstack/config.yaml` to upgrade automatically whenever a new version is available.
|
||||
Run `/gstack-upgrade` in Claude Code. Or set `auto_upgrade: true` in `~/.gstack/config.yaml`.
|
||||
|
||||
## 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.
|
||||
|
||||
## Documentation
|
||||
## Docs
|
||||
|
||||
| Doc | What it covers |
|
||||
|-----|---------------|
|
||||
@@ -228,16 +162,6 @@ Paste this into Claude Code:
|
||||
| [Contributing](CONTRIBUTING.md) | Dev setup, testing, and dev mode |
|
||||
| [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
|
||||
|
||||
MIT
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
name: design-consultation
|
||||
version: 1.0.0
|
||||
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
|
||||
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.
|
||||
@@ -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?"
|
||||
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:
|
||||
|
||||
**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:
|
||||
- "[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)**
|
||||
|
||||
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
|
||||
$B goto "https://competitor-site.com"
|
||||
$B screenshot "/tmp/design-research-competitor-name.png"
|
||||
$B goto "https://example-site.com"
|
||||
$B screenshot "/tmp/design-research-site-name.png"
|
||||
$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.
|
||||
|
||||
@@ -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).
|
||||
|
||||
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:**
|
||||
- Browse available → screenshots + snapshots + WebSearch (richest research)
|
||||
|
||||
@@ -2,7 +2,7 @@
|
||||
name: design-consultation
|
||||
version: 1.0.0
|
||||
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
|
||||
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.
|
||||
@@ -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?"
|
||||
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:
|
||||
|
||||
**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:
|
||||
- "[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)**
|
||||
|
||||
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
|
||||
$B goto "https://competitor-site.com"
|
||||
$B screenshot "/tmp/design-research-competitor-name.png"
|
||||
$B goto "https://example-site.com"
|
||||
$B screenshot "/tmp/design-research-site-name.png"
|
||||
$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.
|
||||
|
||||
@@ -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).
|
||||
|
||||
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:**
|
||||
- Browse available → screenshots + snapshots + WebSearch (richest research)
|
||||
|
||||
+3
-3
@@ -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.
|
||||
|
||||
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.
|
||||
|
||||
@@ -217,7 +217,7 @@ You: /design-consultation
|
||||
|
||||
Claude: From the README, this looks like a developer analytics dashboard
|
||||
for engineering teams. Sound right? Tell me about the feeling
|
||||
you want — and would you like me to browse some competitors
|
||||
you want — and would you like me to look at what's out there
|
||||
first so we can see the landscape?
|
||||
|
||||
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
|
||||
uses a serif. It creates instant hierarchy contrast and
|
||||
signals "we care about craft" in a space full of sans-serifs.
|
||||
Single teal accent instead of blue — every competitor uses blue.
|
||||
Single teal accent instead of blue — everyone else in this space uses blue.
|
||||
Teal is close enough to feel trustworthy, different enough
|
||||
to be recognizable.
|
||||
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.
|
||||
|
||||
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.`,
|
||||
workingDirectory: designDir,
|
||||
|
||||
Reference in New Issue
Block a user