mirror of
https://github.com/garrytan/gstack.git
synced 2026-06-09 11:33:56 +02:00
fix: resolve merge conflicts with origin/main (v0.5.1 + v0.5.2)
Merge main's gstack-slug helper, review dashboard, screenshot visibility, and design-consultation enhancements into the office-hours branch. Conflicts resolved: - CHANGELOG: keep both 0.6.0 (ours) and 0.5.1/0.5.2 (main) entries - VERSION: keep 0.6.0 (ours) - design-consultation: use gstack-slug + office-hours naming - plan-eng-review: use gstack-slug - office-hours: adopt gstack-slug for SLUG/BRANCH computation Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
This commit is contained in:
Garry Tan
@@ -139,7 +139,7 @@ ls src/ app/ pages/ components/ 2>/dev/null | head -30
|
||||
Look for office-hours output:
|
||||
|
||||
```bash
|
||||
SLUG=$(git remote get-url origin 2>/dev/null | sed 's|.*[:/]\([^/]*/[^/]*\)\.git$|\1|;s|.*[:/]\([^/]*/[^/]*\)$|\1|' | tr '/' '-')
|
||||
eval $(~/.claude/skills/gstack/bin/gstack-slug 2>/dev/null)
|
||||
ls ~/.gstack/projects/$SLUG/*office-hours* 2>/dev/null | head -5
|
||||
ls .context/*office-hours* .context/attachments/*office-hours* 2>/dev/null | head -5
|
||||
```
|
||||
@@ -148,6 +148,29 @@ If office-hours output exists, read it — the product context is pre-filled.
|
||||
|
||||
If the codebase is empty and purpose is unclear, say: *"I don't have a clear picture of what you're building yet. Want to explore first with `/office-hours`? Once we know the product direction, we can set up the design system."*
|
||||
|
||||
**Find the browse binary (optional — enables visual competitive research):**
|
||||
|
||||
## SETUP (run this check BEFORE any browse command)
|
||||
|
||||
```bash
|
||||
_ROOT=$(git rev-parse --show-toplevel 2>/dev/null)
|
||||
B=""
|
||||
[ -n "$_ROOT" ] && [ -x "$_ROOT/.claude/skills/gstack/browse/dist/browse" ] && B="$_ROOT/.claude/skills/gstack/browse/dist/browse"
|
||||
[ -z "$B" ] && B=~/.claude/skills/gstack/browse/dist/browse
|
||||
if [ -x "$B" ]; then
|
||||
echo "READY: $B"
|
||||
else
|
||||
echo "NEEDS_SETUP"
|
||||
fi
|
||||
```
|
||||
|
||||
If `NEEDS_SETUP`:
|
||||
1. Tell the user: "gstack browse needs a one-time build (~10 seconds). OK to proceed?" Then STOP and wait.
|
||||
2. Run: `cd <SKILL_DIR> && ./setup`
|
||||
3. If `bun` is not installed: `curl -fsSL https://bun.sh/install | bash`
|
||||
|
||||
If browse is not available, that's fine — visual research is optional. The skill works without it using WebSearch and your built-in design knowledge.
|
||||
|
||||
---
|
||||
|
||||
## Phase 1: Product Context
|
||||
@@ -168,17 +191,40 @@ If the README or office-hours output gives you enough context, pre-fill and conf
|
||||
|
||||
If the user wants competitive research:
|
||||
|
||||
**Step 1: Identify competitors via WebSearch**
|
||||
|
||||
Use WebSearch to find 5-10 products in their space. Search for:
|
||||
- "[product category] website design"
|
||||
- "[product category] best websites 2025"
|
||||
- "best [industry] web apps"
|
||||
|
||||
For each competitor found, note: fonts used, color palette, layout approach, aesthetic direction.
|
||||
**Step 2: Visual research via browse (if available)**
|
||||
|
||||
Summarize your findings conversationally:
|
||||
> "I looked at [competitors]. They tend toward [patterns] — lots of [common choices]. The opportunity to be distinctive is [gap]. Here's what I'd recommend based on this..."
|
||||
If the browse binary is available (`$B` is set), visit the top 3-5 competitor sites and capture visual evidence:
|
||||
|
||||
If WebSearch is unavailable or returns poor results, fall back gracefully: *"Couldn't get good research results, so I'll work from my design knowledge of the [industry] space."*
|
||||
```bash
|
||||
$B goto "https://competitor-site.com"
|
||||
$B screenshot "/tmp/design-research-competitor-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.
|
||||
|
||||
If a competitor 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.
|
||||
|
||||
**Step 3: Synthesize findings**
|
||||
|
||||
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..."
|
||||
|
||||
**Graceful degradation:**
|
||||
- Browse available → screenshots + snapshots + WebSearch (richest research)
|
||||
- Browse unavailable → WebSearch only (still good)
|
||||
- WebSearch also unavailable → agent's built-in design knowledge (always works)
|
||||
|
||||
If the user said no research, skip entirely and proceed to Phase 3 using your built-in design knowledge.
|
||||
|
||||
@@ -188,7 +234,7 @@ If the user said no research, skip entirely and proceed to Phase 3 using your bu
|
||||
|
||||
This is the soul of the skill. Propose EVERYTHING as one coherent package.
|
||||
|
||||
**AskUserQuestion Q2 — present the full proposal:**
|
||||
**AskUserQuestion Q2 — present the full proposal with SAFE/RISK breakdown:**
|
||||
|
||||
```
|
||||
Based on [product context] and [research findings / my design knowledge]:
|
||||
@@ -203,12 +249,21 @@ MOTION: [approach] — [rationale]
|
||||
|
||||
This system is coherent because [explain how choices reinforce each other].
|
||||
|
||||
Want to adjust anything? You can drill into any section, or just tell me
|
||||
what feels off and I'll rework it. Or if this looks right, I'll generate
|
||||
a preview page so you can see the fonts and colors rendered.
|
||||
SAFE CHOICES (category baseline — your users expect these):
|
||||
- [2-3 decisions that match category conventions, with rationale for playing safe]
|
||||
|
||||
RISKS (where your product gets its own face):
|
||||
- [2-3 deliberate departures from convention]
|
||||
- For each risk: what it is, why it works, what you gain, what it costs
|
||||
|
||||
The safe choices keep you literate in your category. The risks are where
|
||||
your product becomes memorable. Which risks appeal to you? Want to see
|
||||
different ones? Or adjust anything else?
|
||||
```
|
||||
|
||||
**Options:** A) Looks great — generate the preview page. B) I want to adjust [section]. C) Start over with a different direction. D) Skip the preview, just write DESIGN.md.
|
||||
The SAFE/RISK breakdown is critical. Design coherence is table stakes — every product in a category can be coherent and still look identical. The real question is: where do you take creative risks? The agent should always propose at least 2 risks, each with a clear rationale for why the risk is worth taking and what the user gives up. Risks might include: an unexpected typeface for the category, a bold accent color nobody else uses, tighter or looser spacing than the norm, a layout approach that breaks from convention, motion choices that add personality.
|
||||
|
||||
**Options:** A) Looks great — generate the preview page. B) I want to adjust [section]. C) I want different risks — show me wilder options. D) Start over with a different direction. E) Skip the preview, just write DESIGN.md.
|
||||
|
||||
### Your Design Knowledge (use to inform proposals — do NOT display as tables)
|
||||
|
||||
@@ -298,7 +353,7 @@ The agent writes a **single, self-contained HTML file** (no framework dependenci
|
||||
1. **Loads proposed fonts** from Google Fonts (or Bunny Fonts) via `<link>` tags
|
||||
2. **Uses the proposed color palette** throughout — dogfood the design system
|
||||
3. **Shows the product name** (not "Lorem Ipsum") as the hero heading
|
||||
4. **Font comparison section:**
|
||||
4. **Font specimen section:**
|
||||
- Each font candidate shown in its proposed role (hero heading, body paragraph, button label, data table row)
|
||||
- Side-by-side comparison if multiple candidates for one role
|
||||
- Real content that matches the product (e.g., civic tech → government data examples)
|
||||
@@ -306,11 +361,17 @@ The agent writes a **single, self-contained HTML file** (no framework dependenci
|
||||
- Swatches with hex values and names
|
||||
- Sample UI components rendered in the palette: buttons (primary, secondary, ghost), cards, form inputs, alerts (success, warning, error, info)
|
||||
- Background/text color combinations showing contrast
|
||||
6. **Light/dark mode toggle** using CSS custom properties and a JS toggle button
|
||||
7. **Clean, professional layout** — the preview page IS a taste signal for the skill
|
||||
8. **Responsive** — looks good on any screen width
|
||||
6. **Realistic product mockups** — this is what makes the preview page powerful. Based on the project type from Phase 1, render 2-3 realistic page layouts using the full design system:
|
||||
- **Dashboard / web app:** sample data table with metrics, sidebar nav, header with user avatar, stat cards
|
||||
- **Marketing site:** hero section with real copy, feature highlights, testimonial block, CTA
|
||||
- **Settings / admin:** form with labeled inputs, toggle switches, dropdowns, save button
|
||||
- **Auth / onboarding:** login form with social buttons, branding, input validation states
|
||||
- Use the product name, realistic content for the domain, and the proposed spacing/layout/border-radius. The user should see their product (roughly) before writing any code.
|
||||
7. **Light/dark mode toggle** using CSS custom properties and a JS toggle button
|
||||
8. **Clean, professional layout** — the preview page IS a taste signal for the skill
|
||||
9. **Responsive** — looks good on any screen width
|
||||
|
||||
The page should make the user think "oh nice, they thought of this." It's selling the design system visually, not just listing hex codes.
|
||||
The page should make the user think "oh nice, they thought of this." It's selling the design system by showing what the product could feel like, not just listing hex codes and font names.
|
||||
|
||||
If `open` fails (headless environment), tell the user: *"I wrote the preview to [path] — open it in your browser to see the fonts and colors rendered."*
|
||||
|
||||
|
||||
@@ -49,7 +49,7 @@ ls src/ app/ pages/ components/ 2>/dev/null | head -30
|
||||
Look for office-hours output:
|
||||
|
||||
```bash
|
||||
SLUG=$(git remote get-url origin 2>/dev/null | sed 's|.*[:/]\([^/]*/[^/]*\)\.git$|\1|;s|.*[:/]\([^/]*/[^/]*\)$|\1|' | tr '/' '-')
|
||||
eval $(~/.claude/skills/gstack/bin/gstack-slug 2>/dev/null)
|
||||
ls ~/.gstack/projects/$SLUG/*office-hours* 2>/dev/null | head -5
|
||||
ls .context/*office-hours* .context/attachments/*office-hours* 2>/dev/null | head -5
|
||||
```
|
||||
@@ -58,6 +58,12 @@ If office-hours output exists, read it — the product context is pre-filled.
|
||||
|
||||
If the codebase is empty and purpose is unclear, say: *"I don't have a clear picture of what you're building yet. Want to explore first with `/office-hours`? Once we know the product direction, we can set up the design system."*
|
||||
|
||||
**Find the browse binary (optional — enables visual competitive research):**
|
||||
|
||||
{{BROWSE_SETUP}}
|
||||
|
||||
If browse is not available, that's fine — visual research is optional. The skill works without it using WebSearch and your built-in design knowledge.
|
||||
|
||||
---
|
||||
|
||||
## Phase 1: Product Context
|
||||
@@ -78,17 +84,40 @@ If the README or office-hours output gives you enough context, pre-fill and conf
|
||||
|
||||
If the user wants competitive research:
|
||||
|
||||
**Step 1: Identify competitors via WebSearch**
|
||||
|
||||
Use WebSearch to find 5-10 products in their space. Search for:
|
||||
- "[product category] website design"
|
||||
- "[product category] best websites 2025"
|
||||
- "best [industry] web apps"
|
||||
|
||||
For each competitor found, note: fonts used, color palette, layout approach, aesthetic direction.
|
||||
**Step 2: Visual research via browse (if available)**
|
||||
|
||||
Summarize your findings conversationally:
|
||||
> "I looked at [competitors]. They tend toward [patterns] — lots of [common choices]. The opportunity to be distinctive is [gap]. Here's what I'd recommend based on this..."
|
||||
If the browse binary is available (`$B` is set), visit the top 3-5 competitor sites and capture visual evidence:
|
||||
|
||||
If WebSearch is unavailable or returns poor results, fall back gracefully: *"Couldn't get good research results, so I'll work from my design knowledge of the [industry] space."*
|
||||
```bash
|
||||
$B goto "https://competitor-site.com"
|
||||
$B screenshot "/tmp/design-research-competitor-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.
|
||||
|
||||
If a competitor 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.
|
||||
|
||||
**Step 3: Synthesize findings**
|
||||
|
||||
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..."
|
||||
|
||||
**Graceful degradation:**
|
||||
- Browse available → screenshots + snapshots + WebSearch (richest research)
|
||||
- Browse unavailable → WebSearch only (still good)
|
||||
- WebSearch also unavailable → agent's built-in design knowledge (always works)
|
||||
|
||||
If the user said no research, skip entirely and proceed to Phase 3 using your built-in design knowledge.
|
||||
|
||||
@@ -98,7 +127,7 @@ If the user said no research, skip entirely and proceed to Phase 3 using your bu
|
||||
|
||||
This is the soul of the skill. Propose EVERYTHING as one coherent package.
|
||||
|
||||
**AskUserQuestion Q2 — present the full proposal:**
|
||||
**AskUserQuestion Q2 — present the full proposal with SAFE/RISK breakdown:**
|
||||
|
||||
```
|
||||
Based on [product context] and [research findings / my design knowledge]:
|
||||
@@ -113,12 +142,21 @@ MOTION: [approach] — [rationale]
|
||||
|
||||
This system is coherent because [explain how choices reinforce each other].
|
||||
|
||||
Want to adjust anything? You can drill into any section, or just tell me
|
||||
what feels off and I'll rework it. Or if this looks right, I'll generate
|
||||
a preview page so you can see the fonts and colors rendered.
|
||||
SAFE CHOICES (category baseline — your users expect these):
|
||||
- [2-3 decisions that match category conventions, with rationale for playing safe]
|
||||
|
||||
RISKS (where your product gets its own face):
|
||||
- [2-3 deliberate departures from convention]
|
||||
- For each risk: what it is, why it works, what you gain, what it costs
|
||||
|
||||
The safe choices keep you literate in your category. The risks are where
|
||||
your product becomes memorable. Which risks appeal to you? Want to see
|
||||
different ones? Or adjust anything else?
|
||||
```
|
||||
|
||||
**Options:** A) Looks great — generate the preview page. B) I want to adjust [section]. C) Start over with a different direction. D) Skip the preview, just write DESIGN.md.
|
||||
The SAFE/RISK breakdown is critical. Design coherence is table stakes — every product in a category can be coherent and still look identical. The real question is: where do you take creative risks? The agent should always propose at least 2 risks, each with a clear rationale for why the risk is worth taking and what the user gives up. Risks might include: an unexpected typeface for the category, a bold accent color nobody else uses, tighter or looser spacing than the norm, a layout approach that breaks from convention, motion choices that add personality.
|
||||
|
||||
**Options:** A) Looks great — generate the preview page. B) I want to adjust [section]. C) I want different risks — show me wilder options. D) Start over with a different direction. E) Skip the preview, just write DESIGN.md.
|
||||
|
||||
### Your Design Knowledge (use to inform proposals — do NOT display as tables)
|
||||
|
||||
@@ -208,7 +246,7 @@ The agent writes a **single, self-contained HTML file** (no framework dependenci
|
||||
1. **Loads proposed fonts** from Google Fonts (or Bunny Fonts) via `<link>` tags
|
||||
2. **Uses the proposed color palette** throughout — dogfood the design system
|
||||
3. **Shows the product name** (not "Lorem Ipsum") as the hero heading
|
||||
4. **Font comparison section:**
|
||||
4. **Font specimen section:**
|
||||
- Each font candidate shown in its proposed role (hero heading, body paragraph, button label, data table row)
|
||||
- Side-by-side comparison if multiple candidates for one role
|
||||
- Real content that matches the product (e.g., civic tech → government data examples)
|
||||
@@ -216,11 +254,17 @@ The agent writes a **single, self-contained HTML file** (no framework dependenci
|
||||
- Swatches with hex values and names
|
||||
- Sample UI components rendered in the palette: buttons (primary, secondary, ghost), cards, form inputs, alerts (success, warning, error, info)
|
||||
- Background/text color combinations showing contrast
|
||||
6. **Light/dark mode toggle** using CSS custom properties and a JS toggle button
|
||||
7. **Clean, professional layout** — the preview page IS a taste signal for the skill
|
||||
8. **Responsive** — looks good on any screen width
|
||||
6. **Realistic product mockups** — this is what makes the preview page powerful. Based on the project type from Phase 1, render 2-3 realistic page layouts using the full design system:
|
||||
- **Dashboard / web app:** sample data table with metrics, sidebar nav, header with user avatar, stat cards
|
||||
- **Marketing site:** hero section with real copy, feature highlights, testimonial block, CTA
|
||||
- **Settings / admin:** form with labeled inputs, toggle switches, dropdowns, save button
|
||||
- **Auth / onboarding:** login form with social buttons, branding, input validation states
|
||||
- Use the product name, realistic content for the domain, and the proposed spacing/layout/border-radius. The user should see their product (roughly) before writing any code.
|
||||
7. **Light/dark mode toggle** using CSS custom properties and a JS toggle button
|
||||
8. **Clean, professional layout** — the preview page IS a taste signal for the skill
|
||||
9. **Responsive** — looks good on any screen width
|
||||
|
||||
The page should make the user think "oh nice, they thought of this." It's selling the design system visually, not just listing hex codes.
|
||||
The page should make the user think "oh nice, they thought of this." It's selling the design system by showing what the product could feel like, not just listing hex codes and font names.
|
||||
|
||||
If `open` fails (headless environment), tell the user: *"I wrote the preview to [path] — open it in your browser to see the fonts and colors rendered."*
|
||||
|
||||
|
||||
Reference in New Issue
Block a user