start

GSP uses a dual-diamond architecture:

• Diamond 1 — Branding (4 skills, 4 phases): brand-research → brand-strategy → brand-identity → brand-patterns (optional: brand-audit before evolving)
• Diamond 2 — Project (6 phases): brief → research → design → critique → build → review
• Optional: launch (on request)

Multiple brands and projects can coexist. Projects reference a brand.

<execution_context> @${CLAUDE_SKILL_DIR}/../../references/questioning.md @${CLAUDE_SKILL_DIR}/../../templates/branding/brief.md @${CLAUDE_SKILL_DIR}/../../templates/branding/state.md @${CLAUDE_SKILL_DIR}/../../templates/branding/config.json @${CLAUDE_SKILL_DIR}/../../templates/branding/roadmap.md @${CLAUDE_SKILL_DIR}/../../templates/projects/brief.md @${CLAUDE_SKILL_DIR}/../../templates/projects/state.md @${CLAUDE_SKILL_DIR}/../../templates/projects/config.json @${CLAUDE_SKILL_DIR}/../../templates/projects/roadmap.md @${CLAUDE_SKILL_DIR}/../../templates/exports-index.md </execution_context>

<questioning_principles> Follow these principles throughout all conversations:

1. Inference over interrogation — state assumptions, let them correct. "SaaS dashboard for enterprise" → you already know: professional, data-dense, web-first.
2. Progressive disclosure — don't dump all questions at once. Flow in natural rounds.
3. Concrete options over open-ended — "More like Stripe's clean approach or Duolingo's playful style?" beats "What style do you want?"
4. Know when you have enough — fill gaps with smart defaults. Don't over-ask.
5. One message per round — ask a cohesive set of related questions, not one at a time. </questioning_principles>

Step 1a: Scan .design/ (sync — fast)

Scan .design/ for existing brands and projects:

• Check .design/branding/ for brand directories (each has a config.json with project_type: "brand")
• Check .design/projects/ for project directories (each has a config.json with project_type: "design")
• Check for legacy flat .design/config.json at root (pre-0.4.0 structure)
• For each brand/project found, read its config.json to get phase statuses
• If .design/CHANGELOG.md doesn't exist, create it from templates/changelog.md

Step 1b: Run design system scan (background)

Spawn a background agent with run_in_background: true that follows the /gsp:design-system skill methodology:

• Use subagent_type: "general-purpose"
• Prompt: "Follow the /gsp:design-system skill methodology. Scan the codebase and produce .design/system/{STACK,COMPONENTS,TOKENS,CONVENTIONS,CONCERNS}.md. Read the templates from .claude/templates/system/ for output format. If no package.json exists, write minimal greenfield versions."
• Store the task reference — you'll read results in Step 3 Round 2 or Step 4.

This produces workspace-level documents consumed by downstream skills and agents.

Step 1c: Greet

Greet based on .design/ findings from Step 1a. Use AskUserQuestion with clickable options to guide the user into the right flow.

If a package.json exists (quick check via glob — don't wait for the full scan), add to the greeting: "I'm scanning your codebase in the background — I'll factor in what I find."

Adapt the greeting based on what the scan revealed. Use plain text with Unicode characters for visual hierarchy:

• Diamonds: ◆ complete, ◈ active/in-progress, ◇ pending
• Dividers: ─── Label ────────────────── as section separators
• Pipeline flow: phases connected by ───, diamond prefix per phase
• Summary box: ┌──┐│└──┘ border with key-value pairs inside

Fresh start (no .design/):

  /gsp: ◇◇

  looks like a fresh start.

If package.json exists, append:

  i scanning your codebase in the background — i'll factor in what i find.

Then use AskUserQuestion with options:

• Brand identity — "define who you are — strategy, voice, visuals"
• Design project — "design screens and flows for something you're building"
• Both (brand + project) — "full pipeline — brand first, then design"
• Quick project — "skip branding — pick a style preset and start designing"

Legacy .design/ detected (flat structure, pre-0.4.0): Acknowledge the legacy project, note it still works with current commands. Use AskUserQuestion:

• Start fresh brand — "new dual-diamond brand alongside your legacy project"
• Start design project — "new project using the updated pipeline"
• Keep working — "continue with the legacy structure"

Brands exist, no projects: Show brand name + pipeline flow. Then use AskUserQuestion with:

• One option per existing brand — "start a project with {brand name}"
• Create new brand — "start a new brand identity"

When brand is complete, show compact single-line: acme-corp ◆ complete

When brand is incomplete, show full pipeline flow + → next: /gsp:{next-command}

Brands + projects exist: Show compact brand (single-line if complete) + full project pipeline flow. Then AskUserQuestion:

• Continue {project} — "pick up at {next phase}"
• New project — "start a new design project"
• New brand — "create a new brand identity"
• View progress — "see full progress dashboard"

When codebase has been scanned (.design/system/STACK.md exists), show a Summary Box using data from STACK.md and COMPONENTS.md:

  ┌──────────────────────────────────────────┐
  │  /gsp: ◆◈                               │
  │                                          │
  │  framework     Next.js 14               │
  │  styling       Tailwind + shadcn/ui     │
  │  components    47 detected              │
  │  type          existing codebase        │
  └──────────────────────────────────────────┘

Codebase signals found (any state): Weave in what you found: "I see you've got a [Next.js/React Native/etc.] project here with [Tailwind/shadcn/etc.] — I'll factor that into the design scope."

Step 2: Route based on conversation

From the greeting exchange, determine which flow to run:

• Brand identity (new) → Brand flow (Step 3) with brand_mode: "new"
• Brand identity (evolve) → Brand flow (Step 3) with brand_mode: "evolve". Detect evolve signals: user mentions existing brand, assets, guidelines, rebrand, refresh, modernize, evolve, update, redesign.
• Design project → Check for brands first. If none exist, explain they need a brand first. Offer to create one, then auto-transition to project flow.
• Full design (brand + project) → Brand flow (Step 3), with E2E flag so brand completion auto-transitions to project flow (Step 4)
• Quick project → Quick flow (Step 5)
• Continue existing work → route to /gsp:progress

Step 3: Brand flow

1. Ask for brand name (kebab-case, e.g., "acme-corp")
2. Create directory structure:

mkdir -p .design/branding/{name}/{audit,discover,strategy,identity,system}

3. Gather brand brief in 3 rounds. The brief is the single source of truth for business and persona definition — invest here.

Round 1 — Business & People:

• Company name, industry, stage
• What problem does this business solve? For whom? How differently?
• Business model (how it makes money)
• Primary persona — use AskUserQuestion to confirm or build: present an inferred persona profile (name, role, day-in-the-life, frustration, aspiration, discovery, trust signals) and let user correct. If they say "fintech for Gen Z" → infer and present a concrete persona.
• Secondary persona (if relevant)
• Mission and vision

This round is the most important. The personas should feel like real people, not demographic buckets.

Round 2 — Brand Essence & Landscape:

• Brand personality — use AskUserQuestion with 2-3 concrete personality directions:
  • Precise & exacting — "Like Stripe or Linear" / preview: "Your dashboard is ready. Zero errors, zero clutter."
  • Warm & human — "Like Mailchimp or Notion" / preview: "Hey! Your project's looking great. Here's what's next."
  • Bold & unapologetic — "Like Figma or Vercel" / preview: "Ship it. We'll make it beautiful."
  • Surprise me — craft an unexpected direction inspired by the user's industry and personas
• What the brand should NEVER feel like
• Competitive landscape — who are the main competitors? What sets this brand apart?
• Brands admired / styles to avoid

Round 3 — Constraints & confirmation:

• Existing brand assets? (logo, colors, guidelines)
• Timeline and budget constraints
• Non-negotiables
• Check background scan: If the codebase scanner has returned results, weave tech findings naturally.
• State your understanding back: "Here's what I'm hearing: [summary]." Use AskUserQuestion:
  • Looks good — "That's accurate, let's go"
  • Adjust something — "I want to change or add something"

Evolve mode additions (when brand_mode is evolve): Add to Round 3:

• Current brand age, existing guidelines
• Brand equity (what's working) and pain points (what's not)
• Evolution scope — preserve / evolve / replace

Skip or compress rounds if the user gives enough upfront. Don't over-ask.

4. Write artifacts:

• .design/branding/{name}/BRIEF.md from brand brief template
• .design/branding/{name}/STATE.md from brand state template
• .design/branding/{name}/config.json from brand config template
• .design/branding/{name}/ROADMAP.md from brand roadmap template

5. Set brand_mode in config.json based on Step 2 routing decision.

6. Route using AskUserQuestion:

• Brand-only, new → Use AskUserQuestion: "Brand brief created! Want to keep going?"

  • Continue to research — "Start brand research now" → invoke /gsp:brand-research via Skill tool
  • Stop here — "I'll come back later" → confirm files are saved, show how to resume with /gsp:start
  • What happens next? — "Explain the next phase" → explain what brand research does and how it uses the brief

• Brand-only, evolve → Use AskUserQuestion: "Brand brief created! Let's audit your current brand."

  • Continue to audit — "Audit my existing brand now" → invoke /gsp:brand-audit via Skill tool
  • Stop here — "I'll come back later" → confirm files are saved, show how to resume with /gsp:start
  • What happens next? — "Explain the audit phase" → explain what the brand audit does and why it comes before strategy

• E2E, new → "Brand brief created. Now let's scope the design project." → continue to Step 4.

• E2E, evolve → Use AskUserQuestion: "Brand brief created! Let's audit your existing brand before the design project."

  • Continue to audit — "Audit my existing brand now" → invoke /gsp:brand-audit via Skill tool
  • Stop here — "I'll come back later" → confirm files are saved, show how to resume with /gsp:start
  • What happens next? — "Explain the audit phase" → explain what the brand audit does and how it feeds into the rest of the pipeline

Step 4: Project flow

1. Show available brands:

Available brands:
  • acme-corp (complete — all 4 phases)
  • beta-labs (in progress — 2/4 phases)

If no brands exist, explain that a brand is needed first and offer to create one. If only one complete brand exists, suggest it as default. If multiple brands exist, use AskUserQuestion with one option per brand (include status in description).

2. User selects a brand.

3. Ask for project name (kebab-case, e.g., "acme-website")

4. Create directory structure:

mkdir -p .design/projects/{name}/{brief,research,design,critique,build,review,codebase,exports,references}

Detect git context

1. Run git branch --show-current to detect current branch

2. If a branch is detected, use AskUserQuestion: "I see you're on {branch} — track this as the project branch?"

   • Yes, use this branch — "Track {branch}"
   • Different branch — "I want to use a different branch name"

3. Store in config.json git.branch and STATE.md ## Git table

4. If no git repo detected, skip silently — leave fields as "—"

5. Write brand.ref:

brand: {brand-name}
path: ../../branding/{brand-name}/
consumed_at: {ISO_DATE}
identity_hash: {first 8 chars of md5 of IDENTITY.md content, or "pending" if identity not complete}

Write to .design/projects/{name}/brand.ref

6. Consume design system scan results:

• Read .design/system/STACK.md (guaranteed done by now — conversation has been going for multiple rounds)
• Note classification for config.json
• Auto-infer implementation_target from STACK.md tech stack and COMPONENTS.md component inventory

7. Gather project brief in 2 rounds:

Round 1 — What we're building:

• What are we building? (app, website, dashboard, etc.)
• Present background scan findings: "I found a {classification} {framework} project with {details}. Want to build on that?"
• Platforms (web, iOS, Android)?
• Tech stack preferences? (confirm inferred or ask)
• Implementation target — use AskUserQuestion with options based on codebase analysis (e.g., shadcn, rn-reusables, custom, css-only)
• Design scope — use AskUserQuestion:
  • Full — "Complete design: screens, components, tokens"
  • Partial — "Specific screens or flows only"
  • Tokens only — "Just design tokens, no screens"
• Key screens/flows needed?

Use inference from the codebase scan — don't re-ask what you can already see.

Round 2 — Success & gaps:

• Success criteria
• Timeline, constraints
• Any remaining gaps
• State your understanding back: "Here's what I'm hearing: [summary]." Use AskUserQuestion:
  • Looks good — "That's accurate, let's go"
  • Adjust something — "I want to change or add something"
  • Explain this — "Walk me through what you captured and why" → explain each section of the brief and how it'll be used in the next phases
  • Surprise me — "Suggest something I haven't thought of" → propose an unexpected screen, flow, or feature angle that would elevate the project based on what you know about the brand, audience, and codebase. Present it as a suggestion the user can adopt, tweak, or skip.

Skip or compress rounds if the user gives enough upfront. Don't over-ask.

8. Write artifacts:

• .design/projects/{name}/BRIEF.md from project brief template
• .design/projects/{name}/STATE.md from project state template — populate ## Git table with detected/confirmed branch (or "—")
• .design/projects/{name}/config.json from project config template — populate git.branch with detected/confirmed branch (or empty string)
• .design/projects/{name}/ROADMAP.md from project roadmap template
• .design/projects/{name}/exports/INDEX.md from exports-index template

9. Route using AskUserQuestion: "Project set up! Ready to scope what you're building?"

• Continue to scoping — "Scope the project now" → invoke /gsp:project-brief via Skill tool
• Stop here — "I'll come back later" → confirm files are saved, show how to resume with /gsp:start
• What happens next? — "Explain the scoping phase" → explain what project-brief does (screen list, component adaptations, gap analysis) and how it uses the brief

Step 5: Quick project flow

For users who want to skip branding and start designing immediately with a style preset.

5a: Style selection

Read the style presets index at ${CLAUDE_SKILL_DIR}/../../skills/gsp-style/styles/INDEX.yml and present grouped options:

  ─── pick a style ─────────────────────

  minimal       swiss-minimalist, clean-modern, scandinavian
  bold          neubrutalism, brutalist, cyberpunk
  dark          modern-dark, midnight, hacker-terminal
  editorial     editorial, magazine, newspaper
  warm          organic, earthy, handcrafted
  playful       retro-futurism, vaporwave, memphis

Use AskUserQuestion with:

• One option per mood group (showing the first 2-3 preset names as preview)
• Surprise me — "pick something unexpected for my stack"

When user picks a group, show the specific presets in that group with 1-line descriptions from INDEX.yml. Use AskUserQuestion to pick the specific preset.

If the user names a preset directly at any point, skip the group step.

"Surprise me" logic: Pick a preset weighted by codebase type from the background scan:

• Developer tools / CLI → dark or minimal presets
• Content / blog → editorial presets
• SaaS / dashboard → minimal or bold presets
• E-commerce → warm or playful presets
• No codebase detected → truly random pick

5b: Create minimal brand

1. Create brand directory:

mkdir -p .design/branding/_style-{preset}/system/

2. Invoke /gsp:style {preset} via Skill tool — this writes:

   • tokens.json (W3C design tokens)
   • Foundation chunks (color, typography, spacing, elevation, radius)
   • INDEX.md

3. Write .design/branding/_style-{preset}/config.json:

{
  "version": "0.5.0",
  "project_type": "brand",
  "brand_mode": "quick",
  "style_preset": "{preset}",
  "system_config": {
    "system_strategy": "generate"
  }
}

4. Write .design/branding/_style-{preset}/STATE.md with:
   • Phase 0 (Audit): skipped
   • Phase 1 (Discover): skipped
   • Phase 2 (Strategy): skipped
   • Phase 3 (Identity): skipped
   • Phase 4 (System): complete

5c: Transition to project

Display:

  style applied — {preset}
  ◇◇◇◇◆ brand: _style-{preset} (style-only)

  now let's scope your project.

Continue directly to Step 4 (project flow) with these modifications:

• Skip "show available brands" — auto-select _style-{preset}
• Go straight to asking for project name
• Set style_preset: "{preset}" in the project's config.json
• Set identity_hash: "style-only" in brand.ref
• Proceed with the normal 2-round project brief gathering

Upgrade path

If a user later wants full branding, they can:

1. Run /gsp:start → "Brand identity" to create a real brand
2. Full diamond produces identity + system with real tokens
3. Update the project's brand.ref to point to the new brand
4. Re-run build phases — they pick up the new tokens automatically