     1→---
     2→name: design-consultation
     3→version: 1.0.0
     4→description: |
     5→  Design consultation: understands your product, researches the landscape, proposes a
     6→  complete design system (aesthetic, typography, color, layout, spacing, motion), and
     7→  generates font+color preview pages. Creates DESIGN.md as your project's design source
     8→  of truth. For existing sites, use /plan-design-review to infer the system instead.
     9→allowed-tools:
    10→  - Bash
    11→  - Read
    12→  - Write
    13→  - Edit
    14→  - Glob
    15→  - Grep
    16→  - AskUserQuestion
    17→  - WebSearch
    18→---
    19→
    20→{{PREAMBLE}}
    21→
    22→# /design-consultation: Your Design System, Built Together
    23→
    24→You are a senior product designer with strong opinions about typography, color, and visual systems. You don't present menus — you listen, think, research, and propose. You're opinionated but not dogmatic. You explain your reasoning and welcome pushback.
    25→
    26→**Your posture:** Design consultant, not form wizard. You propose a complete coherent system, explain why it works, and invite the user to adjust. At any point the user can just talk to you about any of this — it's a conversation, not a rigid flow.
    27→
    28→---
    29→
    30→## Phase 0: Pre-checks
    31→
    32→**Check for existing DESIGN.md:**
    33→
    34→```bash
    35→ls DESIGN.md design-system.md 2>/dev/null || echo "NO_DESIGN_FILE"
    36→```
    37→
    38→- If a DESIGN.md exists: Read it. Ask the user: "You already have a design system. Want to **update** it, **start fresh**, or **cancel**?"
    39→- If no DESIGN.md: continue.
    40→
    41→**Gather product context from the codebase:**
    42→
    43→```bash
    44→cat README.md 2>/dev/null | head -50
    45→cat package.json 2>/dev/null | head -20
    46→ls src/ app/ pages/ components/ 2>/dev/null | head -30
    47→```
    48→
    49→Look for brainstorm output:
    50→
    51→```bash
    52→eval $(~/.claude/skills/gstack/bin/gstack-slug 2>/dev/null)
    53→ls ~/.gstack/projects/$SLUG/*brainstorm* 2>/dev/null | head -5
    54→ls .context/*brainstorm* .context/attachments/*brainstorm* 2>/dev/null | head -5
    55→```
    56→
    57→If brainstorm output exists, read it — the product context is pre-filled.
    58→
    59→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 brainstorm first with `/brainstorm`? Once we know the product direction, we can set up the design system."*
    60→
    61→**Find the browse binary (optional — enables visual competitive research):**
    62→
    63→{{BROWSE_SETUP}}
    64→
    65→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.
    66→
    67→---
    68→
    69→## Phase 1: Product Context
    70→
    71→Ask the user a single question that covers everything you need to know. Pre-fill what you can infer from the codebase.
    72→
    73→**AskUserQuestion Q1 — include ALL of these:**
    74→1. Confirm what the product is, who it's for, what space/industry
    75→2. What project type: web app, dashboard, marketing site, editorial, internal tool, etc.
    76→3. "Want me to research what top products in your space are doing for design, or should I work from my design knowledge?"
    77→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."
    78→
    79→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?"*
    80→
    81→---
    82→
    83→## Phase 2: Research (only if user said yes)
    84→
    85→If the user wants competitive research:
    86→
    87→**Step 1: Identify what's out there via WebSearch**
    88→
    89→Use WebSearch to find 5-10 products in their space. Search for:
    90→- "[product category] website design"
    91→- "[product category] best websites 2025"
    92→- "best [industry] web apps"
    93→
    94→**Step 2: Visual research via browse (if available)**
    95→
    96→If the browse binary is available (`$B` is set), visit the top 3-5 sites in the space and capture visual evidence:
    97→
    98→```bash
    99→$B goto "https://example-site.com"
   100→$B screenshot "/tmp/design-research-site-name.png"
   101→$B snapshot
   102→```
   103→
   104→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.
   105→
   106→If a site blocks the headless browser or requires login, skip it and note why.
   107→
   108→If browse is not available, rely on WebSearch results and your built-in design knowledge — this is fine.
   109→
   110→**Step 3: Synthesize findings**
   111→
   112→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).
   113→
   114→Summarize conversationally:
   115→> "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..."
   116→
   117→**Graceful degradation:**
   118→- Browse available → screenshots + snapshots + WebSearch (richest research)
   119→- Browse unavailable → WebSearch only (still good)
   120→- WebSearch also unavailable → agent's built-in design knowledge (always works)
   121→
   122→If the user said no research, skip entirely and proceed to Phase 3 using your built-in design knowledge.
   123→
   124→---
   125→
   126→## Phase 3: The Complete Proposal
   127→
   128→This is the soul of the skill. Propose EVERYTHING as one coherent package.
   129→
   130→**AskUserQuestion Q2 — present the full proposal with SAFE/RISK breakdown:**
   131→
   132→```
   133→Based on [product context] and [research findings / my design knowledge]:
   134→
   135→AESTHETIC: [direction] — [one-line rationale]
   136→DECORATION: [level] — [why this pairs with the aesthetic]
   137→LAYOUT: [approach] — [why this fits the product type]
   138→COLOR: [approach] + proposed palette (hex values) — [rationale]
   139→TYPOGRAPHY: [3 font recommendations with roles] — [why these fonts]
   140→SPACING: [base unit + density] — [rationale]
   141→MOTION: [approach] — [rationale]
   142→
   143→This system is coherent because [explain how choices reinforce each other].
   144→
   145→SAFE CHOICES (category baseline — your users expect these):
   146→  - [2-3 decisions that match category conventions, with rationale for playing safe]
   147→
   148→RISKS (where your product gets its own face):
   149→  - [2-3 deliberate departures from convention]
   150→  - For each risk: what it is, why it works, what you gain, what it costs
   151→
   152→The safe choices keep you literate in your category. The risks are where
   153→your product becomes memorable. Which risks appeal to you? Want to see
   154→different ones? Or adjust anything else?
   155→```
   156→
   157→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.
   158→
   159→**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.
   160→
   161→### Your Design Knowledge (use to inform proposals — do NOT display as tables)
   162→
   163→**Aesthetic directions** (pick the one that fits the product):
   164→- Brutally Minimal — Type and whitespace only. No decoration. Modernist.
   165→- Maximalist Chaos — Dense, layered, pattern-heavy. Y2K meets contemporary.
   166→- Retro-Futuristic — Vintage tech nostalgia. CRT glow, pixel grids, warm monospace.
   167→- Luxury/Refined — Serifs, high contrast, generous whitespace, precious metals.
   168→- Playful/Toy-like — Rounded, bouncy, bold primaries. Approachable and fun.
   169→- Editorial/Magazine — Strong typographic hierarchy, asymmetric grids, pull quotes.
   170→- Brutalist/Raw — Exposed structure, system fonts, visible grid, no polish.
   171→- Art Deco — Geometric precision, metallic accents, symmetry, decorative borders.
   172→- Organic/Natural — Earth tones, rounded forms, hand-drawn texture, grain.
   173→- Industrial/Utilitarian — Function-first, data-dense, monospace accents, muted palette.
   174→
   175→**Decoration levels:** minimal (typography does all the work) / intentional (subtle texture, grain, or background treatment) / expressive (full creative direction, layered depth, patterns)
   176→
   177→**Layout approaches:** grid-disciplined (strict columns, predictable alignment) / creative-editorial (asymmetry, overlap, grid-breaking) / hybrid (grid for app, creative for marketing)
   178→
   179→**Color approaches:** restrained (1 accent + neutrals, color is rare and meaningful) / balanced (primary + secondary, semantic colors for hierarchy) / expressive (color as a primary design tool, bold palettes)
   180→
   181→**Motion approaches:** minimal-functional (only transitions that aid comprehension) / intentional (subtle entrance animations, meaningful state transitions) / expressive (full choreography, scroll-driven, playful)
   182→
   183→**Font recommendations by purpose:**
   184→- Display/Hero: Satoshi, General Sans, Instrument Serif, Fraunces, Clash Grotesk, Cabinet Grotesk
   185→- Body: Instrument Sans, DM Sans, Source Sans 3, Geist, Plus Jakarta Sans, Outfit
   186→- Data/Tables: Geist (tabular-nums), DM Sans (tabular-nums), JetBrains Mono, IBM Plex Mono
   187→- Code: JetBrains Mono, Fira Code, Berkeley Mono, Geist Mono
   188→
   189→**Font blacklist** (never recommend):
   190→Papyrus, Comic Sans, Lobster, Impact, Jokerman, Bleeding Cowboys, Permanent Marker, Bradley Hand, Brush Script, Hobo, Trajan, Raleway, Clash Display, Courier New (for body)
   191→
   192→**Overused fonts** (never recommend as primary — use only if user specifically requests):
   193→Inter, Roboto, Arial, Helvetica, Open Sans, Lato, Montserrat, Poppins
   194→
   195→**AI slop anti-patterns** (never include in your recommendations):
   196→- Purple/violet gradients as default accent
   197→- 3-column feature grid with icons in colored circles
   198→- Centered everything with uniform spacing
   199→- Uniform bubbly border-radius on all elements
   200→- Gradient buttons as the primary CTA pattern
   201→- Generic stock-photo-style hero sections
   202→- "Built for X" / "Designed for Y" marketing copy patterns
   203→
   204→### Coherence Validation
   205→
   206→When the user overrides one section, check if the rest still coheres. Flag mismatches with a gentle nudge — never block:
   207→
   208→- Brutalist/Minimal aesthetic + expressive motion → "Heads up: brutalist aesthetics usually pair with minimal motion. Your combo is unusual — which is fine if intentional. Want me to suggest motion that fits, or keep it?"
   209→- Expressive color + restrained decoration → "Bold palette with minimal decoration can work, but the colors will carry a lot of weight. Want me to suggest decoration that supports the palette?"
   210→- Creative-editorial layout + data-heavy product → "Editorial layouts are gorgeous but can fight data density. Want me to show how a hybrid approach keeps both?"
   211→- Always accept the user's final choice. Never refuse to proceed.
   212→
   213→---
   214→
   215→## Phase 4: Drill-downs (only if user requests adjustments)
   216→
   217→When the user wants to change a specific section, go deep on that section:
   218→
   219→- **Fonts:** Present 3-5 specific candidates with rationale, explain what each evokes, offer the preview page
   220→- **Colors:** Present 2-3 palette options with hex values, explain the color theory reasoning
   221→- **Aesthetic:** Walk through which directions fit their product and why
   222→- **Layout/Spacing/Motion:** Present the approaches with concrete tradeoffs for their product type
   223→
   224→Each drill-down is one focused AskUserQuestion. After the user decides, re-check coherence with the rest of the system.
   225→
   226→---
   227→
   228→## Phase 5: Font & Color Preview Page (default ON)
   229→
   230→Generate a polished HTML preview page and open it in the user's browser. This page is the first visual artifact the skill produces — it should look beautiful.
   231→
   232→```bash
   233→PREVIEW_FILE="/tmp/design-consultation-preview-$(date +%s).html"
   234→```
   235→
   236→Write the preview HTML to `$PREVIEW_FILE`, then open it:
   237→
   238→```bash
   239→open "$PREVIEW_FILE"
   240→```
   241→
   242→### Preview Page Requirements
   243→
   244→The agent writes a **single, self-contained HTML file** (no framework dependencies) that:
   245→
   246→1. **Loads proposed fonts** from Google Fonts (or Bunny Fonts) via `<link>` tags
   247→2. **Uses the proposed color palette** throughout — dogfood the design system
   248→3. **Shows the product name** (not "Lorem Ipsum") as the hero heading
   249→4. **Font specimen section:**
   250→   - Each font candidate shown in its proposed role (hero heading, body paragraph, button label, data table row)
   251→   - Side-by-side comparison if multiple candidates for one role
   252→   - Real content that matches the product (e.g., civic tech → government data examples)
   253→5. **Color palette section:**
   254→   - Swatches with hex values and names
   255→   - Sample UI components rendered in the palette: buttons (primary, secondary, ghost), cards, form inputs, alerts (success, warning, error, info)
   256→   - Background/text color combinations showing contrast
   257→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:
   258→   - **Dashboard / web app:** sample data table with metrics, sidebar nav, header with user avatar, stat cards
   259→   - **Marketing site:** hero section with real copy, feature highlights, testimonial block, CTA
   260→   - **Settings / admin:** form with labeled inputs, toggle switches, dropdowns, save button
   261→   - **Auth / onboarding:** login form with social buttons, branding, input validation states
   262→   - 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.
   263→7. **Light/dark mode toggle** using CSS custom properties and a JS toggle button
   264→8. **Clean, professional layout** — the preview page IS a taste signal for the skill
   265→9. **Responsive** — looks good on any screen width
   266→
   267→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.
   268→
   269→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."*
   270→
   271→If the user says skip the preview, go directly to Phase 6.
   272→
   273→---
   274→
   275→## Phase 6: Write DESIGN.md & Confirm
   276→
   277→Write `DESIGN.md` to the repo root with this structure:
   278→
   279→```markdown
   280→# Design System — [Project Name]
   281→
   282→## Product Context
   283→- **What this is:** [1-2 sentence description]
   284→- **Who it's for:** [target users]
   285→- **Space/industry:** [category, peers]
   286→- **Project type:** [web app / dashboard / marketing site / editorial / internal tool]
   287→
   288→## Aesthetic Direction
   289→- **Direction:** [name]
   290→- **Decoration level:** [minimal / intentional / expressive]
   291→- **Mood:** [1-2 sentence description of how the product should feel]
   292→- **Reference sites:** [URLs, if research was done]
   293→
   294→## Typography
   295→- **Display/Hero:** [font name] — [rationale]
   296→- **Body:** [font name] — [rationale]
   297→- **UI/Labels:** [font name or "same as body"]
   298→- **Data/Tables:** [font name] — [rationale, must support tabular-nums]
   299→- **Code:** [font name]
   300→- **Loading:** [CDN URL or self-hosted strategy]
   301→- **Scale:** [modular scale with specific px/rem values for each level]
   302→
   303→## Color
   304→- **Approach:** [restrained / balanced / expressive]
   305→- **Primary:** [hex] — [what it represents, usage]
   306→- **Secondary:** [hex] — [usage]
   307→- **Neutrals:** [warm/cool grays, hex range from lightest to darkest]
   308→- **Semantic:** success [hex], warning [hex], error [hex], info [hex]
   309→- **Dark mode:** [strategy — redesign surfaces, reduce saturation 10-20%]
   310→
   311→## Spacing
   312→- **Base unit:** [4px or 8px]
   313→- **Density:** [compact / comfortable / spacious]
   314→- **Scale:** 2xs(2) xs(4) sm(8) md(16) lg(24) xl(32) 2xl(48) 3xl(64)
   315→
   316→## Layout
   317→- **Approach:** [grid-disciplined / creative-editorial / hybrid]
   318→- **Grid:** [columns per breakpoint]
   319→- **Max content width:** [value]
   320→- **Border radius:** [hierarchical scale — e.g., sm:4px, md:8px, lg:12px, full:9999px]
   321→
   322→## Motion
   323→- **Approach:** [minimal-functional / intentional / expressive]
   324→- **Easing:** enter(ease-out) exit(ease-in) move(ease-in-out)
   325→- **Duration:** micro(50-100ms) short(150-250ms) medium(250-400ms) long(400-700ms)
   326→
   327→## Decisions Log
   328→| Date | Decision | Rationale |
   329→|------|----------|-----------|
   330→| [today] | Initial design system created | Created by /design-consultation based on [product context / research] |
   331→```
   332→
   333→**Update CLAUDE.md** (or create it if it doesn't exist) — append this section:
   334→
   335→```markdown
   336→## Design System
   337→Always read DESIGN.md before making any visual or UI decisions.
   338→All font choices, colors, spacing, and aesthetic direction are defined there.
   339→Do not deviate without explicit user approval.
   340→In QA mode, flag any code that doesn't match DESIGN.md.
   341→```
   342→
   343→**AskUserQuestion Q-final — show summary and confirm:**
   344→
   345→List all decisions. Flag any that used agent defaults without explicit user confirmation (the user should know what they're shipping). Options:
   346→- A) Ship it — write DESIGN.md and CLAUDE.md
   347→- B) I want to change something (specify what)
   348→- C) Start over
   349→
   350→---
   351→
   352→## Important Rules
   353→
   354→1. **Propose, don't present menus.** You are a consultant, not a form. Make opinionated recommendations based on the product context, then let the user adjust.
   355→2. **Every recommendation needs a rationale.** Never say "I recommend X" without "because Y."
   356→3. **Coherence over individual choices.** A design system where every piece reinforces every other piece beats a system with individually "optimal" but mismatched choices.
   357→4. **Never recommend blacklisted or overused fonts as primary.** If the user specifically requests one, comply but explain the tradeoff.
   358→5. **The preview page must be beautiful.** It's the first visual output and sets the tone for the whole skill.
   359→6. **Conversational tone.** This isn't a rigid workflow. If the user wants to talk through a decision, engage as a thoughtful design partner.
   360→7. **Accept the user's final choice.** Nudge on coherence issues, but never block or refuse to write a DESIGN.md because you disagree with a choice.
   361→8. **No AI slop in your own output.** Your recommendations, your preview page, your DESIGN.md — all should demonstrate the taste you're asking the user to adopt.
   362→


Let me check for template variables used in the gen-skill-docs file:


Bash

grep -E "^function generate|const.*=.*function|resolvers\[" /root/projects/gits/gstack/scripts/gen-skill-docs.ts | head -30


node "${CLAUDE_PLUGIN_ROOT}/scripts/hooks/run-with-flags.js" "pre:bash:tmux-reminder" "scripts/hooks/pre-bash-tmux-reminder.js" "strict"


node "${CLAUDE_PLUGIN_ROOT}/scripts/hooks/run-with-flags.js" "pre:bash:git-push-reminder" "scripts/hooks/pre-bash-git-push-reminder.js" "strict"


bash "${CLAUDE_PLUGIN_ROOT}/scripts/hooks/run-with-flags-shell.sh" "pre:observe" "skills/continuous-learning-v2/hooks/observe.sh" "standard,strict"


node "${CLAUDE_PLUGIN_ROOT}/scripts/hooks/run-with-flags.js" "pre:insaits-security" "scripts/hooks/insaits-security-wrapper.js" "standard,strict"


bash "${CLAUDE_PLUGIN_ROOT}/scripts/hooks/run-with-flags-shell.sh" "post:observe" "skills/continuous-learning-v2/hooks/observe.sh" "standard,strict"


     1→---
     2→name: gstack
     3→version: 1.1.0
     4→description: |
     5→  Fast headless browser for QA testing and site dogfooding. Navigate any URL, interact with
     6→  elements, verify page state, diff before/after actions, take annotated screenshots, check
     7→  responsive layouts, test forms and uploads, handle dialogs, and assert element states.
     8→  ~100ms per command. Use when you need to test a feature, verify a deployment, dogfood a
     9→  user flow, or file a bug with evidence.
    10→allowed-tools:
    11→  - Bash
    12→  - Read
    13→  - AskUserQuestion
    14→
    15→---
    16→<!-- AUTO-GENERATED from SKILL.md.tmpl — do not edit directly -->
    17→<!-- Regenerate: bun run gen:skill-docs -->
    18→
    19→## Preamble (run first)
    20→
    21→```bash
    22→_UPD=$(~/.claude/skills/gstack/bin/gstack-update-check 2>/dev/null || .claude/skills/gstack/bin/gstack-update-check 2>/dev/null || true)
    23→[ -n "$_UPD" ] && echo "$_UPD" || true
    24→mkdir -p ~/.gstack/sessions
    25→touch ~/.gstack/sessions/"$PPID"
    26→_SESSIONS=$(find ~/.gstack/sessions -mmin -120 -type f 2>/dev/null | wc -l | tr -d ' ')
    27→find ~/.gstack/sessions -mmin +120 -type f -delete 2>/dev/null || true
    28→_CONTRIB=$(~/.claude/skills/gstack/bin/gstack-config get gstack_contributor 2>/dev/null || true)
    29→_BRANCH=$(git branch --show-current 2>/dev/null || echo "unknown")
    30→echo "BRANCH: $_BRANCH"
    31→_LAKE_SEEN=$([ -f ~/.gstack/.completeness-intro-seen ] && echo "yes" || echo "no")
    32→echo "LAKE_INTRO: $_LAKE_SEEN"
    33→```
    34→
    35→If output shows `UPGRADE_AVAILABLE <old> <new>`: read `~/.claude/skills/gstack/gstack-upgrade/SKILL.md` and follow the "Inline upgrade flow" (auto-upgrade if configured, otherwise AskUserQuestion with 4 options, write snooze state if declined). If `JUST_UPGRADED <from> <to>`: tell user "Running gstack v{to} (just updated!)" and continue.
    36→
    37→If `LAKE_INTRO` is `no`: Before continuing, introduce the Completeness Principle.
    38→Tell the user: "gstack follows the **Boil the Lake** principle — always do the complete
    39→thing when AI makes the marginal cost near-zero. Read more: https://garryslist.org/posts/boil-the-ocean"
    40→Then offer to open the essay in their default browser:
    41→
    42→```bash
    43→open https://garryslist.org/posts/boil-the-ocean
    44→touch ~/.gstack/.completeness-intro-seen
    45→```
    46→
    47→Only run `open` if the user says yes. Always run `touch` to mark as seen. This only happens once.
    48→
    49→## AskUserQuestion Format
    50→
    51→**ALWAYS follow this structure for every AskUserQuestion call:**
    52→1. **Re-ground:** State the project, the current branch (use the `_BRANCH` value printed by the preamble — NOT any branch from conversation history or gitStatus), and the current plan/task. (1-2 sentences)
    53→2. **Simplify:** Explain the problem in plain English a smart 16-year-old could follow. No raw function names, no internal jargon, no implementation details. Use concrete examples and analogies. Say what it DOES, not what it's called.
    54→3. **Recommend:** `RECOMMENDATION: Choose [X] because [one-line reason]` — always prefer the complete option over shortcuts (see Completeness Principle). Include `Completeness: X/10` for each option. Calibration: 10 = complete implementation (all edge cases, full coverage), 7 = covers happy path but skips some edges, 3 = shortcut that defers significant work. If both options are 8+, pick the higher; if one is ≤5, flag it.
    55→4. **Options:** Lettered options: `A) ... B) ... C) ...` — when an option involves effort, show both scales: `(human: ~X / CC: ~Y)`
    56→
    57→Assume the user hasn't looked at this window in 20 minutes and doesn't have the code open. If you'd need to read the source to understand your own explanation, it's too complex.
    58→
    59→Per-skill instructions may add additional formatting rules on top of this baseline.
    60→
    61→## Completeness Principle — Boil the Lake
    62→
    63→AI-assisted coding makes the marginal cost of completeness near-zero. When you present options:
    64→
    65→- If Option A is the complete implementation (full parity, all edge cases, 100% coverage) and Option B is a shortcut that saves modest effort — **always recommend A**. The delta between 80 lines and 150 lines is meaningless with CC+gstack. "Good enough" is the wrong instinct when "complete" costs minutes more.
    66→- **Lake vs. ocean:** A "lake" is boilable — 100% test coverage for a module, full feature implementation, handling all edge cases, complete error paths. An "ocean" is not — rewriting an entire system from scratch, adding features to dependencies you don't control, multi-quarter platform migrations. Recommend boiling lakes. Flag oceans as out of scope.
    67→- **When estimating effort**, always show both scales: human team time and CC+gstack time. The compression ratio varies by task type — use this reference:
    68→
    69→| Task type | Human team | CC+gstack | Compression |
    70→|-----------|-----------|-----------|-------------|
    71→| Boilerplate / scaffolding | 2 days | 15 min | ~100x |
    72→| Test writing | 1 day | 15 min | ~50x |
    73→| Feature implementation | 1 week | 30 min | ~30x |
    74→| Bug fix + regression test | 4 hours | 15 min | ~20x |
    75→| Architecture / design | 2 days | 4 hours | ~5x |
    76→| Research / exploration | 1 day | 3 hours | ~3x |
    77→
    78→- This principle applies to test coverage, error handling, documentation, edge cases, and feature completeness. Don't skip the last 10% to "save time" — with AI, that 10% costs seconds.
    79→
    80→**Anti-patterns — DON'T do this:**
    81→- BAD: "Choose B — it covers 90% of the value with less code." (If A is only 70 lines more, choose A.)
    82→- BAD: "We can skip edge case handling to save time." (Edge case handling costs minutes with CC.)
    83→- BAD: "Let's defer test coverage to a follow-up PR." (Tests are the cheapest lake to boil.)
    84→- BAD: Quoting only human-team effort: "This would take 2 weeks." (Say: "2 weeks human / ~1 hour CC.")
    85→
    86→## Contributor Mode
    87→
    88→If `_CONTRIB` is `true`: you are in **contributor mode**. You're a gstack user who also helps make it better.
    89→
    90→**At the end of each major workflow step** (not after every single command), reflect on the gstack tooling you used. Rate your experience 0 to 10. If it wasn't a 10, think about why. If there is an obvious, actionable bug OR an insightful, interesting thing that could have been done better by gstack code or skill markdown — file a field report. Maybe our contributor will help make us better!
    91→
    92→**Calibration — this is the bar:** For example, `$B js "await fetch(...)"` used to fail with `SyntaxError: await is only valid in async functions` because gstack didn't wrap expressions in async context. Small, but the input was reasonable and gstack should have handled it — that's the kind of thing worth filing. Things less consequential than this, ignore.
    93→
    94→**NOT worth filing:** user's app bugs, network errors to user's URL, auth failures on user's site, user's own JS logic bugs.
    95→
    96→**To file:** write `~/.gstack/contributor-logs/{slug}.md` with **all sections below** (do not truncate — include every section through the Date/Version footer):
    97→
    98→```
    99→# {Title}
   100→


node "${CLAUDE_PLUGIN_ROOT}/scripts/hooks/run-with-flags.js" "post:bash:pr-created" "scripts/hooks/post-bash-pr-created.js" "standard,strict"


node "${CLAUDE_PLUGIN_ROOT}/scripts/hooks/run-with-flags.js" "post:bash:build-complete" "scripts/hooks/post-bash-build-complete.js" "standard,strict"


function generateCommandReference(): string {
function generateSnapshotFlags(): string {
function generatePreamble(): string {
function generateBrowseSetup(): string {
function generateBaseBranchDetect(): string {
function generateQAMethodology(): string {
function generateDesignReviewLite(): string {
function generateDesignMethodology(): string {
function generateReviewDashboard(): string {
function generateTestBootstrap(): string {


Perfect! Now I have a comprehensive understanding of the gstack skill system. Let me compile my findings into a complete report.

## Summary: gstack Skill System Architecture

I've thoroughly explored the gstack project's skill template system. Here's the complete picture of how all 15 skills compose together:

### **Core Architecture**

The skill system is built on **template-based generation** using TypeScript. Every skill has:
- A `.tmpl` template file (Markdown with placeholder variables)
- A generated `.md` file (regenerated via `bun run gen:skill-docs`)
- A YAML frontmatter declaring metadata, allowed tools, and description

Template variables (placeholders like `{{PREAMBLE}}`) are resolved by `/root/projects/gits/gstack/scripts/gen-skill-docs.ts`, which defines 10 key generator functions:

1. `generatePreamble()` — shared initialization + upgrade flow + Completeness Principle
2. `generateBrowseSetup()` — locate the browse binary
3. `generateBaseBranchDetect()` — detect main/master branch
4. `generateQAMethodology()` — QA testing phases 1-6 (shared by /qa and /qa-only)
5. `generateDesignMethodology()` — design audit phases 1-6 (shared by /design-review)
6. `generateDesignReviewLite()` — lightweight design audit (embedded in /ship and /review)
7. `generateReviewDashboard()` — status dashboard (used by /ship, /plan-eng-review, /plan-design-review)
8. `generateCommandReference()` — all browse commands + categories (from browse/src/commands.ts)
9. `generateSnapshotFlags()` — all snapshot flags (from browse/src/snapshot.ts)
10. `generateTestBootstrap()` — test framework detection (used by /qa, /design-review)

---

### **15 Skills Across 4 Workflow Tiers**

#### **Tier 1: Foundation Tools (Supporting Skills)**
These are utilities every workflow depends on:

**1. `/browse` (version 1.1.0)** — Headless QA browser
- Location: `browse/SKILL.md.tmpl`
- Auto-starts Chromium, ~100ms per command
- Powers all QA testing, screenshots, interactions
- Uses: `{{PREAMBLE}}`, `{{BROWSE_SETUP}}`, `{{SNAPSHOT_FLAGS}}`, `{{COMMAND_REFERENCE}}`

**2. `/gstack` (version 1.1.0)** — Main entry point (project root skill)
- Location: `SKILL.md.tmpl`
- Same as browse but named "gstack" for project context
- Uses: `{{PREAMBLE}}`, `{{BROWSE_SETUP}}`, `{{SNAPSHOT_FLAGS}}`, `{{COMMAND_REFERENCE}}`

**3. `/setup-browser-cookies` (version 1.0.0)** — Import browser sessions
- Location: `setup-browser-cookies/SKILL.md.tmpl`
- Imports cookies from Chrome, Arc, Brave, Edge, Comet
- Interactive picker UI in browser
- Uses: `{{PREAMBLE}}`, `{{BROWSE_SETUP}}`

**4. `/gstack-upgrade` (version 1.1.0)** — Version management
- Location: `gstack-upgrade/SKILL.md.tmpl`
- Detects global vs local/vendored install
- Auto-upgrade or snooze flow (escalating backoff)
- Referenced inline by preamble when upgrade is available

---

#### **Tier 2: Pre-Ship Planning (Plan Review Skills)**
Review plans BEFORE implementation. Interactive, opinionated, work in plan mode:

**5. `/plan-eng-review` (version 1.0.0)** — Engineering manager review
- Location: `plan-eng-review/SKILL.md.tmpl`
- Walks through: Scope Challenge (Step 0) → Architecture → Code Quality → Tests → Performance
- Produces: "NOT in scope" section, "What already exists" section, test diagram, TODOS proposals
- One AskUserQuestion per issue (never batch)
- Outputs test plan artifact to `~/.gstack/projects/{slug}/{user}-{branch}-test-plan-{datetime}.md`
- Writes review log to `~/.gstack/projects/{slug}/$BRANCH-reviews.jsonl`
- Uses: `{{PREAMBLE}}`, `{{BASE_BRANCH_DETECT}}`, `{{REVIEW_DASHBOARD}}`

**6. `/plan-design-review` (version 2.0.0)** — Designer's eye plan review
- Location: `plan-design-review/SKILL.md.tmpl`
- Seven-pass design review: Info Architecture → Interaction States → User Journey → AI Slop Risk → Design System Alignment → Responsive/A11y → Unresolved Decisions
- Rates each dimension 0-10, fixes to get to 10
- Produces: completion summary, design score before/after, deferred decisions
- Writes review log to `~/.gstack/projects/{slug}/$BRANCH-reviews.jsonl`
- Uses: `{{PREAMBLE}}`, `{{BASE_BRANCH_DETECT}}`, `{{REVIEW_DASHBOARD}}`

**7. `/plan-ceo-review` (version 1.0.0)** — CEO/founder-mode plan review
- Location: `plan-ceo-review/SKILL.md.tmpl` (50KB template file)
- Four modes: SCOPE EXPANSION, SELECTIVE EXPANSION, HOLD SCOPE, SCOPE REDUCTION
- Rethinks the problem, finds the 10-star product, challenges premises
- Expands scope when it creates a better product
- Uses: `{{PREAMBLE}}`, `{{BASE_BRANCH_DETECT}}`

**8. `/design-consultation` (version 1.0.0)** — Complete design system builder
- Location: `design-consultation/SKILL.md.tmpl` (18KB template)
- Phase 0 (pre-checks) → Phase 1 (context) → Phase 2 (research via WebSearch) → Phase 3 (complete proposal) → Phase 4 (drill-downs) → Phase 5 (beautiful preview page) → Phase 6 (write DESIGN.md)
- Generates HTML preview with fonts, colors, mockups, light/dark mode toggle
- Creates DESIGN.md as the design source of truth
- Updates CLAUDE.md with design system reference
- Uses: `{{PREAMBLE}}`, `{{BROWSE_SETUP}}`

---

#### **Tier 3: Implementation QA (Test & Fix Skills)**
Test applications and fix bugs found:

**9. `/qa` (version 2.0.0)** — Test, find bugs, fix bugs
- Location: `qa/SKILL.md.tmpl` (85KB template)
- Phases 1-6: QA baseline testing (same as qa-only)
- Phase 7-11: Triage → Fix Loop → Final QA → Report → TODOS.md Update
- Three tiers: Quick (critical+high) → Standard (+ medium) → Exhaustive (+ cosmetic)
- Phase 8e.5: Generates regression tests (mocks external deps, traces bug codepath first)
- Self-regulation heuristic (WTF-likelihood) after 5 fixes, hard cap at 50 fixes
- Requires clean working tree
- Outputs: `qa-report-{domain}-{YYYY-MM-DD}.md`, before/after screenshots, project-scoped test outcome
- Uses: `{{PREAMBLE}}`, `{{BASE_BRANCH_DETECT}}`, `{{BROWSE_SETUP}}`, `{{TEST_BOOTSTRAP}}`, `{{QA_METHODOLOGY}}`

**10. `/qa-only` (version 1.0.0)** — Report-only QA testing
- Location: `qa-only/SKILL.md.tmpl` (70KB template)
- Phases 1-6: Systematically test, produce report with evidence
- **NEVER fixes bugs** — report only
- Diff-aware mode: auto-detects feature branches and tests changed code
- Checks for rich test plan sources before falling back to git diff heuristics
- Outputs: `qa-report-{domain}-{YYYY-MM-DD}.md`, project-scoped test outcome
- Uses: `{{PREAMBLE}}`, `{{BROWSE_SETUP}}`, `{{TEST_BOOTSTRAP}}`, `{{QA_METHODOLOGY}}`

---

#### **Tier 4: Ship & Post-Ship (Delivery Skills)**
Merge and ship code, then update documentation:

**11. `/review` (version 1.0.0)** — Pre-landing PR review
- Location: `review/SKILL.md.tmpl` (55KB template)
- Standalone pre-landing review (also called from `/ship` as Step 3.5)
- Two-pass review: CRITICAL (SQL & Data Safety, Race Conditions, LLM Trust, Enums) → INFORMATIONAL (Conditional Side Effects, Dead Code, Prompts, Tests, View/Frontend)
- Reads `.claude/skills/review/checklist.md` (required)
- Step 2.5: Greptile review comment classification with escalation detection
- Step 4.5: Design Review (lite) — calls `{{DESIGN_REVIEW_LITE}}`
- Step 5: Fix-First workflow (auto-fix mechanical issues, ask about structural)
- Step 5.5: TODOS cross-reference (does PR close open TODOs?)
- Step 5.6: Documentation staleness check
- Greptile reply templates from `.claude/skills/review/greptile-triage.md`
- Uses: `{{PREAMBLE}}`, `{{BASE_BRANCH_DETECT}}`, `{{DESIGN_REVIEW_LITE}}`

**12. `/ship` (version 1.0.0)** — Fully automated ship workflow
- Location: `ship/SKILL.md.tmpl` (165KB template — largest skill)
- **Non-interactive, fully automated** (user says `/ship`, next thing they see is PR URL)
- Steps:
  - Step 1: Pre-flight (branch check, uncommitted changes, review dashboard)
  - Step 2: Merge base branch (auto-resolve simple conflicts)
  - Step 2.5: Test framework bootstrap
  - Step 3: Run tests (Rails + Vitest in parallel)
  - Step 3.25: Eval suites (if prompt files changed)
  - Step 3.4: Test coverage audit (ASCII diagram of code paths + user flows, gap detection, test generation)
  - Step 3.5: Pre-landing review (calls `/review` workflow)
  - Step 3.75: Greptile review comments (classified, replied-to)
  - Step 4: Version bump (auto-decide MICRO/PATCH, ask for MINOR/MAJOR)
  - Step 5: CHANGELOG auto-generate (from all commits on branch)
  - Step 5.5: TODOS.md auto-update (marks completed items)
  - Step 6: Commit (bisectable chunks, logical ordering, version+changelog always last)
  - Step 7: Push (with `-u`)
  - Step 8: Create PR (with comprehensive body: Summary, Test Coverage, Pre-Landing Review, Design Review, Eval Results, Greptile, TODOS, Test Plan)
- Only stops for: merge conflicts, test failures, pre-landing ASK items, MINOR/MAJOR bumps
- Uses: `{{PREAMBLE}}`, `{{BASE_BRANCH_DETECT}}`, `{{REVIEW_DASHBOARD}}`, `{{TEST_BOOTSTRAP}}`, `{{DESIGN_REVIEW_LITE}}`

**13. `/document-release` (version 1.0.0)** — Post-ship doc update
- Location: `document-release/SKILL.md.tmpl` (70KB template)
- Runs AFTER `/ship` (code committed, PR exists) but BEFORE merge
- Steps:
  - Step 1: Pre-flight + diff analysis
  - Step 2: Per-file audit (README, ARCHITECTURE, CONTRIBUTING, CLAUDE.md)
  - Step 3: Apply auto-updates (Edit tool, never Write on CHANGELOG)
  - Step 4: Ask about risky/questionable changes
  - Step 5: CHANGELOG voice polish (preserve content, polish wording only)
  - Step 6: Cross-doc consistency check + discoverability
  - Step 7: TODOS.md cleanup (mark completed items, capture deferred work)
  - Step 8: VERSION bump (never silent — always ask)
  - Step 9: Commit docs + update PR body
- Outputs: structured doc health summary table
- Uses: `{{PREAMBLE}}`, `{{BASE_BRANCH_DETECT}}`

**14. `/design-review` (version 2.0.0)** — Live site design audit + fix
- Location: `design-review/SKILL.md.tmpl` (100KB template)
- Like `/qa` but for visual/UX issues
- Phases 1-6: Design audit baseline (like QA methodology)
- Phase 7: Triage (High Impact → Medium Impact → Polish)
- Phase 8: Fix loop (locate source → fix → commit → re-test → classify)
- Phase 8e.5: Regression tests (CSS-only skipped, JS behavior tested)
- Phase 8f: Self-regulation (design-fix risk heuristic, hard cap 30 fixes)
- Phase 9-11: Final audit, report, TODOS.md update
- Requires clean working tree
- Outputs: `design-audit-{domain}-{YYYY-MM-DD}.md`, before/after screenshot pairs
- Uses: `{{PREAMBLE}}`, `{{BROWSE_SETUP}}`, `{{TEST_BOOTSTRAP}}`, `{{DESIGN_METHODOLOGY}}`

**15. `/retro` (version 2.0.0)** — Weekly engineering retrospective
- Location: `retro/SKILL.md.tmpl` (80KB template)
- Analyzes commit history, work patterns, code quality metrics
- Arguments: `/retro`, `/retro 24h`, `/retro 14d`, `/retro compare`
- Steps 1-14:
  - Raw data gathering (12 parallel git commands in one bash block)
  - Metrics computation (per-author leaderboard, test health, backlog health, Greptile signal)
  - Commit time distribution (hourly histogram in Pacific time)
  - Work session detection (45-min gap threshold, classify deep/medium/micro)
  - Commit type breakdown (feat/fix/refactor/test/chore/docs percentages)
  - Hotspot analysis (most-changed files)
  - PR size distribution
  - Focus score + Ship of the Week
  - Team member analysis (per-person praise + growth area)
  - Week-over-week trends (if window >= 14d)
  - Streak tracking (consecutive days with commits, team + personal)
  - Load history & compare (vs prior retro)
  - Save JSON snapshot to `.context/retros/{date}-{seq}.json`
  - Write narrative (tweetable summary, tables, prose)
- Outputs: Console narrative (3000-4500 words), JSON snapshot
- Uses: `{{PREAMBLE}}`

---

### **Shared Template Variables (Generated Functions)**

Each template variable is resolved to dynamically generated markdown:

| Variable | Generator | Used By | Contents |
|----------|-----------|---------|----------|
| `{{PREAMBLE}}` | generatePreamble() | All 15 skills | Update check, branch detection, gstack-upgrade inline flow, Completeness Principle intro, Contributor mode, AskUserQuestion format |
| `{{BROWSE_SETUP}}` | generateBrowseSetup() | /browse, /gstack, /setup-browser-cookies, /qa, /qa-only, /design-review, /design-consultation | Shell code to locate `$B` binary, auto-start server, setup paths |
| `{{BASE_BRANCH_DETECT}}` | generateBaseBranchDetect() | /ship, /review, /plan-eng-review, /plan-design-review, /plan-ceo-review, /qa, /document-release | Detects main/master dynamically, `git diff <base>...HEAD`, `git log <base>..HEAD` |
| `{{SNAPSHOT_FLAGS}}` | generateSnapshotFlags() | /browse, /gstack | All snapshot command flags (-i, -a, -o, -D, -C, etc.) as markdown table |
| `{{COMMAND_REFERENCE}}` | generateCommandReference() | /browse, /gstack | All ~50 browse commands grouped by category (Navigation, Reading, Interaction, etc.) |
| `{{QA_METHODOLOGY}}` | generateQAMethodology() | /qa, /qa-only | Phases 1-6 testing workflow (scope detection, diff analysis, page visits, interaction testing, screenshot evidence, health score) |
| `{{DESIGN_METHODOLOGY}}` | generateDesignMethodology() | /design-review | Phases 1-6 design audit (visual inspection, hierarchy, spacing, contrast, slop detection, accessibility, components, animation) |
| `{{DESIGN_REVIEW_LITE}}` | generateDesignReviewLite() | /ship (Step 3.5), /review (Step 4.5) | Lightweight design audit (single pass, not full /design-review, embedded in code review) |
| `{{REVIEW_DASHBOARD}}` | generateReviewDashboard() | /ship (Step 1), /plan-eng-review (footer), /plan-design-review (footer) | Status display reading `~/.gstack/projects/{slug}/$BRANCH-reviews.jsonl` (Eng Review, CEO Review, Design Review status) |
| `{{TEST_BOOTSTRAP}}` | generateTestBootstrap() | /ship (Step 2.5), /qa, /design-review | Detects test framework (npm test, pytest, rspec, bin/test-lane) and offers to bootstrap if missing |

---

### **Key Composition Patterns**

1. **Preamble in every skill** — All 15 skills start with `{{PREAMBLE}}`, which gives them:
   - Upgrade detection + inline upgrade flow
   - Completeness Principle intro (once per gstack session)
   - Contributor mode (field reports)
   - Shared AskUserQuestion format

2. **Browser tools as foundation** — `/browse` and `/gstack` provide the QA infrastructure. All QA skills (`/qa`, `/qa-only`, `/design-review`, `/design-consultation`) depend on the browse binary location.

3. **Review workflow composition** — `/review` is standalone AND called from `/ship` Step 3.5. Both use the same checklist.md + greptile-triage.md + design-review-lite.

4. **Methodology sharing** — QA phases 1-6 and Design phases 1-6 are shared across multiple skills:
   - `/qa` and `/qa-only` both use `{{QA_METHODOLOGY}}`
   - `/design-review` uses `{{DESIGN_METHODOLOGY}}`
   - `/ship` and `/review` both embed `{{DESIGN_REVIEW_LITE}}`

5. **Status persistence** — Plan review skills (`/plan-eng-review`, `/plan-design-review`) write to `~/.gstack/projects/{slug}/$BRANCH-reviews.jsonl`. This is read by:
   - `/ship` Step 1 (review dashboard)
   - `/plan-design-review` and `/plan-eng-review` footers (to show prior reviews)

6. **Test plan artifact** — `/plan-eng-review` writes a test plan to `~/.gstack/projects/{slug}/{user}-{branch}-test-plan-{datetime}.md` which is consumed by `/qa` and `/qa-only` to replace lossy git diff heuristics.

7. **Skill hierarchy**:
   ```
   Plan Phase (/plan-*) → Implementation Phase (/qa or /design-review) → Ship Phase (/ship) → Post-Ship (/document-release)
   Or: Foundation (/browse) ← QA/Design skills ← Ship (/ship) ← All reporting
   ```

---

### **File Locations (Absolute Paths)**

- `/root/projects/gits/gstack/SKILL.md.tmpl` — Root project skill (gstack)
- `/root/projects/gits/gstack/browse/SKILL.md.tmpl` — Browse binary interface
- `/root/projects/gits/gstack/setup-browser-cookies/SKILL.md.tmpl`
- `/root/projects/gits/gstack/gstack-upgrade/SKILL.md.tmpl`
- `/root/projects/gits/gstack/plan-eng-review/SKILL.md.tmpl`
- `/root/projects/gits/gstack/plan-design-review/SKILL.md.tmpl`
- `/root/projects/gits/gstack/plan-ceo-review/SKILL.md.tmpl`
- `/root/projects/gits/gstack/design-consultation/SKILL.md.tmpl`
- `/root/projects/gits/gstack/qa/SKILL.md.tmpl`
- `/root/projects/gits/gstack/qa-only/SKILL.md.tmpl`
- `/root/projects/gits/gstack/review/SKILL.md.tmpl`
- `/root/projects/gits/gstack/ship/SKILL.md.tmpl`
- `/root/projects/gits/gstack/document-release/SKILL.md.tmpl`
- `/root/projects/gits/gstack/design-review/SKILL.md.tmpl`
- `/root/projects/gits/gstack/retro/SKILL.md.tmpl`

Generator script: `/root/projects/gits/gstack/scripts/gen-skill-docs.ts`

---

This architecture enables each skill to be self-contained yet coordinated. Skills can be invoked standalone or as part of a larger workflow, and the template system ensures consistent methodology, messaging, and integration points across the entire gstack ecosystem.