get-shit-pretty 0.2.0 → 0.4.0

package/commands/gsp/design.md

@@ -10,15 +10,17 @@ allowed-tools:
   - Glob
 ---
 <context>
-Phase 4 of the GSP design pipeline. Uses the UI/UX Pattern Master prompt to design core screens following Apple HIG and the project's design system.
+Phase 3 of the GSP project diamond. Uses the UI/UX Pattern Master prompt to design core screens following Apple HIG and the brand's design system.
+
+Works with the dual-diamond architecture: reads brand system from `.design/branding/{brand}/system/` via `brand.ref`, reads/writes project assets in `.design/projects/{project}/`.
 </context>
 
 <objective>
 Design core UI/UX screens and interaction flows.
 
-**Input:** `.design/system/SYSTEM.md` + `.design/BRIEF.md`
-**Output:** `.design/screens/SCREENS.md`
-**Agent:** `gsp-ui-designer`
+**Input:** Research + brief + brand system + project BRIEF.md
+**Output:** `{project}/design/` (screen chunks + shared/ + INDEX.md) + exports/INDEX.md update
+**Agent:** `gsp-designer`
 </objective>
 
 <execution_context>
@@ -28,69 +30,82 @@ Design core UI/UX screens and interaction flows.
 </execution_context>
 
 <process>
+## Step 0: Resolve project and brand
+
+Scan `.design/projects/` for project directories. If only one project exists, use it. If multiple, ask the user which project to work on.
+
+Set `PROJECT_PATH` = `.design/projects/{project}`
+
+Read `{PROJECT_PATH}/brand.ref` to resolve brand path:
+- Set `BRAND_PATH` = `.design/branding/{brand}`
+
 ## Step 1: Load context
 
-Read:
-- `.design/BRIEF.md` — app type, audience, goals
-- `.design/system/SYSTEM.md` — design system to use
-- `.design/brand/IDENTITY.md` — brand personality
-- `.design/config.json` — get `implementation_target`
+Read `{PROJECT_PATH}/config.json` — get `implementation_target`, `design_scope`.
+Read `{PROJECT_PATH}/BRIEF.md` — app type, audience, goals.
 
-If SYSTEM.md doesn't exist, tell the user to run `/gsp:system` first.
+### Brand system (chunk-first)
 
-## Step 2: Scan codebase for existing components
+Read `{BRAND_PATH}/system/INDEX.md`. If it exists, load all foundation chunks + selective component chunks.
 
-When `implementation_target` is `shadcn`, `rn-reusables`, `existing`, or `code` (anything except `figma`):
+Fallback: read `{BRAND_PATH}/system/SYSTEM.md` (legacy monolith). Log: "⚠️ Legacy system format detected — consider re-running /gsp:brand-system for chunk output."
 
-Scan the codebase for existing layouts and components:
-- Look for `components/`, `src/components/`, `components/ui/`, `lib/components/`
-- Look for shadcn `components/ui/` or RN Reusables `components/ui/`
-- Look for Expo `app/` layouts, Next.js `app/` layouts, or other layout files
-- Look for page/screen files to understand existing structure
+If neither exists, tell the user to run `/gsp:brand-system` first.
 
-Build an **Existing Components** inventory summarizing what's already built and reusable.
+### Brand context (selective)
 
-Pass this inventory to the agent so screen designs can reference existing components.
+Read `{BRAND_PATH}/identity/INDEX.md`. If it exists, load `color-system.md` and `typography.md`.
+Fallback: read `{BRAND_PATH}/identity/IDENTITY.md`.
 
-## Step 3: Spawn UI designer
+### Brief (chunk-first)
 
-Spawn the `gsp-ui-designer` agent with:
-- All prior artifacts
-- The UI/UX Pattern Master prompt (03)
-- The design output template
-- The Apple HIG patterns reference
-- The `implementation_target` value
-- The existing components inventory (if gathered in Step 2)
+Read `{PROJECT_PATH}/brief/INDEX.md`. If it exists, load `scope.md` and `target-adaptations.md`.
 
-The agent should deliver:
-1. User personas with goals and pain points
-2. Information architecture
-3. Navigation pattern and gesture definitions
-4. 8 core screens with wireframes, components, interactions
-5. All states: empty, error, loading
-6. Accessibility specs (WCAG, VoiceOver, Dynamic Type)
-7. Micro-interactions and animations
-8. Responsive behavior across breakpoints
-9. **Component Plan** (when target is not `figma`)
-10. Designer's notes
+If brief doesn't exist, proceed without it (brief is informative, not blocking).
 
-## Step 4: Write output
+### Research (chunk-first)
 
-Write screens to `.design/screens/SCREENS.md`.
+Read `{PROJECT_PATH}/research/INDEX.md`. If it exists, load `ux-patterns.md`, `recommendations.md`, and `reference-specs.md`.
 
-## Step 5: Update state
+If research doesn't exist, proceed without it (research is informative, not blocking).
 
-Update `.design/STATE.md`:
-- Set Phase 4 (Design) status to `complete`
-- Record completion date
+## Step 1.5: Scope check
+
+**If `design_scope` is `tokens`:**
+1. Update `{PROJECT_PATH}/STATE.md` — set Phase 3 (Design) status to `skipped`
+2. Display: "Design phase skipped — design scope is `tokens`."
+3. Route: "Run `/gsp:build`."
+4. Stop here.
+
+**If `design_scope` is `partial`:**
+Read BRIEF.md "Target screens" to get the specific screen list.
 
-## Step 6: Route next
+## Step 2: Load existing components inventory
 
-Display screen summary (screen count, key flows) and end with:
+When `implementation_target` is not `figma`:
+- **If `{PROJECT_PATH}/codebase/INVENTORY.md` exists**, read it. Pass to the agent.
+- **If not**, fall back to scanning the codebase.
+
+## Step 3: Spawn designer
+
+Spawn the `gsp-designer` agent with all prior artifacts, the UI/UX Pattern Master prompt (03), design output template, Apple HIG patterns reference, implementation_target, design_scope, target screens (when partial), and existing components inventory.
+
+**Output path:** `{PROJECT_PATH}/design/`
+
+The agent writes chunks directly:
+- `design/screen-{NN}-{name}.md` (one per screen)
+- `design/shared/` (personas, IA, navigation, micro-interactions, responsive, component-plan)
+- `design/INDEX.md`
+- Updates `{PROJECT_PATH}/exports/INDEX.md` (design section)
+
+## Step 4: Update state
+
+Update `{PROJECT_PATH}/STATE.md`:
+- Set Phase 3 (Design) status to `complete`
+- Record completion date
 
-**When `implementation_target` is `skip`:**
-"Run `/gsp:review` for design critique and accessibility audit."
+## Step 5: Route next
 
-**Otherwise:**
-"Run `/gsp:spec` to generate implementation specifications."
+"Run `/gsp:critique` for design critique and accessibility audit."
 </process>
+</output>

package/commands/gsp/discover.md

@@ -0,0 +1,17 @@
+---
+name: gsp:discover
+description: Brand discovery (alias for /gsp:brand-research)
+allowed-tools:
+  - Read
+---
+<process>
+Display:
+```
+🎨 GSP — Redirecting...
+
+/gsp:discover now redirects to /gsp:brand-research.
+Brand commands now use the brand- prefix for clarity.
+```
+
+Tell the user to run `/gsp:brand-research` instead.
+</process>

package/commands/gsp/doctor.md

@@ -0,0 +1,319 @@
+---
+name: gsp:doctor
+description: Diagnose project health — check structure, config, outputs, and brand drift
+allowed-tools:
+  - Read
+  - Glob
+  - Grep
+  - Bash
+---
+<context>
+Diagnostic tool for GSP design projects. Runs health checks across all brands in `.design/branding/` and all projects in `.design/projects/`. Reports health issues with actionable fix suggestions.
+
+No agents needed — this is pure pattern matching and file inspection.
+</context>
+
+<objective>
+Run a health check on the current `.design/` directory and print a terminal diagnostic.
+
+**Input:** `.design/` directory (all brands, projects, artifacts, config, state)
+**Output:** Terminal-only diagnostic — no files written
+
+**Checks:** project structure, phase ordering, stale outputs, config drift, missing chunks, broken references, review status, brand drift, upgrade detection
+</objective>
+
+<process>
+## Step 0: Find design directory
+
+Check for `.design/` in the current directory.
+
+If not found:
+```
+🩺 GSP Doctor — No project found
+   No .design/ directory detected. Run /gsp:new to start.
+```
+Stop here.
+
+## Step 1: Detect structure type
+
+**New dual-diamond structure:** `.design/branding/` or `.design/projects/` exists
+**Legacy flat structure:** `.design/config.json` exists at root (not inside branding/ or projects/)
+**Empty:** `.design/` exists but has neither
+
+For legacy: run legacy checks (same as v0.3.0 doctor). For new: run multi-instance checks below.
+
+## Step 2: Scan all instances
+
+**Brands:** List all directories in `.design/branding/` that have a `config.json` with `project_type: "brand"`
+**Projects:** List all directories in `.design/projects/` that have a `config.json` with `project_type: "design"`
+
+For each instance, read:
+- `config.json` — configuration
+- `STATE.md` — phase progress
+- `BRIEF.md` — brief
+- `brand.ref` — brand reference (projects only)
+
+## Step 3: Run checks per instance
+
+### Per-Brand Checks (5-phase)
+
+**Check B1: Brand Structure**
+Required: config.json, STATE.md, BRIEF.md
+Required dirs: discover/, strategy/, verbal/, identity/, system/
+Missing → FAIL
+
+**Check B2: Brand Phase Ordering**
+No phase complete if earlier phase is pending (discover < strategy < verbal < identity < system).
+Exception: strategy can proceed without discover.
+
+**Check B3: Brand Completeness**
+If all 5 phases complete, check:
+- `identity/INDEX.md` exists (chunk format)
+- `identity/palettes.json` exists (WARN if missing)
+- `system/INDEX.md` exists (chunk format)
+- `system/tokens.json` exists (WARN if missing)
+- If monolith exists without INDEX.md → WARN: "Legacy monolith format"
+
+**Check B4: Legacy Monolith Detection**
+For each brand phase directory (discover, strategy, verbal, identity, system):
+- If monolith exists but no INDEX.md → WARN: "Legacy format in {phase}/ — re-run /gsp:brand-{phase} for chunk output"
+
+### Per-Project Checks (6-phase)
+
+**Check P1: Project Structure**
+
+**What it catches:** Missing core files, incomplete setup.
+
+Required: config.json, STATE.md, BRIEF.md, brand.ref
+Required dirs: brief/, research/, design/, critique/, build/, review/
+
+Required when `codebase_type` is NOT `greenfield`:
+- codebase/INVENTORY.md
+
+Check each exists:
+- All present → PASS
+- INVENTORY.md missing for non-greenfield → WARN: "Codebase inventory missing. Re-run `/gsp:new` or create `codebase/INVENTORY.md` manually."
+- Core files missing → FAIL: list which are missing, suggest `/gsp:new`
+
+Legacy detection: if system/, screens/, specs/, plan/ dirs exist → WARN: "Legacy structure detected — project uses old phase layout"
+
+**Check P2: Brand Reference**
+Read brand.ref → check brand exists in `.design/branding/{name}/`
+Check brand system is complete (system phase = complete)
+WARN if brand referenced but system not complete
+
+**Check P3: Brand Drift**
+Read `identity_hash` from brand.ref
+If brand identity/IDENTITY.md exists, compute current hash (first 8 chars of md5)
+If hashes differ → WARN: "Brand identity has changed since project consumed it. Consider re-running `/gsp:brief`."
+If identity_hash is "pending" → INFO: "Brand identity wasn't complete when project was created."
+
+**Check P4: Phase Ordering**
+
+**What it catches:** Phases completed out of order, skipped prerequisites.
+
+Read STATE.md phase table. Check ordering rules:
+brief < research < design < critique < build < review
+
+1. No phase should be `complete` if an earlier required phase is still `pending` (not `skipped` or `complete`)
+2. Valid skip scenarios (not violations):
+   - design skipped when `design_scope` is `tokens`
+   - research can proceed without brief
+3. build complete but critique pending → WARN: "Build completed without critique. Run `/gsp:critique` to audit."
+4. Any other out-of-order completion → FAIL with specifics
+
+All phases in order (or validly skipped) → PASS
+
+**Check P5: Stale Outputs**
+
+**What it catches:** Output content that doesn't match current config expectations.
+
+Only check phases that are `complete`. All paths relative to the project instance directory.
+
+**When `system_strategy` is `extend`:**
+- Check if brand's `system/` output contains "Component Audit" or "KEEP" or "RESTYLE" or "REFACTOR" or "REPLACE"
+- If none found → WARN: "Strategy is `extend` but system output lacks component audit table. Re-run `/gsp:brand-patterns`."
+
+**When `implementation_target` is `shadcn`:**
+- If brief phase is complete, check brief/ output for "shadcn" or "npx shadcn"
+- If not found → WARN: "Target is `shadcn` but brief doesn't reference shadcn components."
+
+**When `implementation_target` is `rn-reusables`:**
+- If brief phase is complete, check brief/ output for "reusables" or "NativeWind"
+- If not found → WARN: "Target is `rn-reusables` but brief doesn't reference RN Reusables."
+
+**When `design_scope` is `tokens`:**
+- design phase should be `skipped`, not `complete`
+- If `complete` → WARN: "Scope is `tokens` but design phase ran as full. Outputs may be unnecessary."
+
+No stale outputs detected → PASS
+
+**Check P6: Config Drift**
+
+**What it catches:** Config says one thing, outputs reflect another.
+
+**Check `system_strategy` alignment:**
+- Config says `extend` but brand system output contains "## Components" with 30+ component specs (no audit table) → WARN: "Config says `extend` but system looks like a full `generate`. Config may be out of sync."
+- Config says `generate` but brand system output contains "Component Audit" → WARN: "Config says `generate` but system contains extend-style audit."
+
+**Check `codebase_type` alignment:**
+- Config says `existing` or `boilerplate` but no INVENTORY.md → WARN (already caught by P1, don't double-count)
+- Config says `greenfield` but INVENTORY.md exists → INFO: "Config says `greenfield` but INVENTORY.md exists. Not an issue, but config may be stale."
+
+**Check `design_scope` alignment:**
+- Config says `tokens` but design/ has full screen designs → WARN: "Scope is `tokens` but design/ has full screen designs."
+- Config says `partial` — check BRIEF.md for "Target screens" section. If missing → WARN: "Scope is `partial` but BRIEF.md doesn't specify target screens."
+
+No drift detected → PASS
+
+**Check P7: Missing Chunks**
+
+**What it catches:** Chunk directories missing, INDEX.md references broken.
+
+For each completed project phase (brief, research, design, critique, build, review):
+- Check for `{phase}/INDEX.md` — if missing → WARN: "Phase {phase} is complete but has no INDEX.md. Re-run `/gsp:{command}` to generate chunks."
+
+**If exports/INDEX.md exists, check for broken references:**
+- Read INDEX.md, extract all file paths from markdown links
+- Check each referenced file exists
+
+Broken INDEX.md references → WARN: list broken paths
+INDEX.md has unpopulated BEGIN/END sections for completed phases → WARN: "INDEX.md has empty sections for completed phases."
+
+No chunks expected yet (no phases complete) → PASS
+All chunks present and references valid → PASS
+
+Legacy path detection: if `screens/` exists instead of `design/` → WARN
+
+**Check P8: Broken References**
+
+**What it catches:** Cross-file references that point to non-existent content.
+
+**design/ → brand system:**
+If both exist, extract component names referenced in design chunks (look for patterns like "Uses: {ComponentName}" or component references). Check each exists in the brand's system output.
+
+Components referenced in designs but not in system → WARN: "Design references components not defined in brand system: {list}. Re-run `/gsp:brand-patterns` to add them, or update designs."
+
+**critique/ → design/:**
+If both exist, extract screen references from critique chunks. Check each referenced screen exists in design/.
+
+Screens referenced in critique but not in designs → WARN: "Critique references screens not in design/: {list}."
+
+No broken references → PASS
+
+**Check P9: Review Status**
+
+**What it catches:** Stuck review loops, unaddressed critical issues.
+
+Read STATE.md review loop table:
+- Count review iterations
+- If > 3 iterations → WARN: "Review has looped {N} times. Consider addressing root causes or accepting current state."
+
+If critique phase status is `needs-revision`:
+- Check if any later phase (build, review) is `complete` → FAIL: "Build/Review completed while critique still needs revision."
+
+If critique/ contains chunks with "Critical" severity items:
+- If critique phase status is `complete` (not `needs-revision`) → INFO: "Critique has critical items but phase is marked complete. Verify issues were addressed."
+
+No review issues → PASS
+
+**Check P10: Upgrade Detection**
+
+**What it catches:** Project created with older GSP version, missing features now available.
+
+**Config version check:**
+- If `version` field exists in config.json, note it
+- If version is older than current (0.4.0) → WARN: "Config version is {version}, current GSP is 0.4.0. Some features may not be active."
+- If no `version` field → INFO: "Config has no version stamp. Project may predate versioned configs."
+
+**Chunk format check:**
+- If any phase is complete but has no INDEX.md and no chunk files → WARN: "Project may predate chunked exports. Consider re-running phases to get chunked output."
+
+**palettes.json check:**
+- If brand's identity phase is complete, check for `identity/palettes.json`
+- If missing → INFO: "No tints.dev palettes found. Re-run `/gsp:brand-identity` to generate OKLCH color palettes."
+
+No upgrade concerns → PASS
+
+### Cross-Instance Checks
+
+**Check X1: Multiple projects, same brand**
+If multiple projects reference the same brand, and brand has changed since any project consumed it → WARN with list of affected projects.
+
+## Step 4: Calculate health score
+
+Score per instance (100 points each):
+- Each FAIL: -15 points
+- Each WARN: -5 points
+- Each INFO: -0 points
+- Minimum: 0
+
+Overall score: average of all instance scores.
+
+## Step 5: Display diagnostic
+
+```
+🩺 GSP Doctor — Project Health Check
+═══════════════════════════════════════
+
+Brands: {N} found
+Projects: {N} found
+
+Overall Health: {SCORE}/100 {emoji}
+{health bar}
+
+─── Brand: {name} ─────────────────────
+  Phases: {N}/5 complete
+  ✅ B1. Structure .............. PASS
+  ✅ B2. Phase Ordering ......... PASS
+  ⚠️  B3. Completeness .......... WARN
+
+─── Project: {name} (brand: {brand}) ──
+  Phases: {N}/6 complete
+  ✅ P1. Structure .............. PASS
+  ✅ P2. Brand Reference ........ PASS
+  ⚠️  P3. Brand Drift ........... WARN
+  ✅ P4. Phase Ordering ......... PASS
+  ✅ P5. Stale Outputs .......... PASS
+  ✅ P6. Config Drift ........... PASS
+  ✅ P7. Missing Chunks ......... PASS
+  ✅ P8. Broken References ...... PASS
+  ✅ P9. Review Status .......... PASS
+  ✅ P10. Upgrade Detection ..... PASS
+
+─── Cross-Instance ────────────────────
+  ✅ X1. Brand Consistency ...... PASS
+
+─── Issues Found ──────────────────────
+
+FAIL:
+  • [acme-website/P1] Missing brand.ref
+    → Fix: Re-run /gsp:new to set up project with brand reference
+
+WARN:
+  • [acme-corp/B3] No palettes.json found
+    → Fix: Re-run /gsp:brand-identity to generate OKLCH palettes
+
+INFO:
+  • [acme-corp/P10] Config version is 0.3.0, current GSP is 0.4.0
+    → Fix: Re-run /gsp:new to upgrade config
+
+─── Summary ───────────────────────────
+
+{If score >= 90:} "Project is healthy. Ship it! 🚀"
+{If score >= 70:} "Project has minor issues. Address warnings when convenient."
+{If score >= 50:} "Project needs attention. Fix the warnings above."
+{If score < 50:}  "Project has significant issues. Address failures first."
+```
+
+Health emoji: 90-100: 💚, 70-89: 💛, 50-69: 🟠, 0-49: ❤️
+Health bar: 20-char using █ and ░.
+
+## Important Notes
+
+- **Read-only** — do NOT modify any files
+- **No agents** — run all checks directly, this is deterministic pattern matching
+- **Terminal only** — no file output, all results printed to terminal
+- **Be specific** — every issue names the exact file and suggests the exact command to fix it
+- **Don't over-report** — if the same issue is caught by multiple checks, only report it once (in the most specific check)
+</process>

package/commands/gsp/help.md

@@ -17,52 +17,99 @@ Output the following reference exactly:
 
 ```
 🎨 GSP — Get Shit Pretty
-Command Reference
+Command Reference (v0.4.0 — Dual Diamond)
 ═══════════════════════════════════════
 
-PROJECT SETUP
-  /gsp:new-project     Initialize design brief through guided Q&A
+GETTING STARTED
+  /gsp:new             Smart entry — start a brand or project
   /gsp:help            Show this command reference
-  /gsp:progress        Check project status — "How pretty are we?"
+  /gsp:update          Update GSP to latest version
+  /gsp:progress        Check progress — "How pretty are we?"
+  /gsp:doctor          Diagnose health across brands + projects
 
-DESIGN PIPELINE (run in order)
-  /gsp:research        Phase 1 — Trend analysis & competitive landscape
-  /gsp:brand           Phase 2 — Brand identity (strategy, logo, color, type)
-  /gsp:system          Phase 3 — Design system foundations + tokens
-  /gsp:design          Phase 4 — UI/UX screens & interaction flows
-  /gsp:spec            Phase 5 — Implementation specifications
-  /gsp:review          Phase 6 — Design critique + accessibility audit
-  /gsp:build           Phase 7 — Design-to-code translation
-  /gsp:launch          Phase 8 — Marketing campaign assets
+BRANDING DIAMOND (5 commands, 6 phases)
+  /gsp:brand-audit     Phase 0 — Audit: assess existing brand, produce evolution map (optional)
+  /gsp:brand-research  Phase 1 — Research: competitive audit, personas, SWOT, trends
+  /gsp:brand-strategy  Phase 2 — Strategy: archetype, positioning, personality (interactive)
+  /gsp:brand-identity  Phases 3-4 — Identity: verbal + visual identity
+  /gsp:brand-patterns  Phase 5 — Patterns: design system, tokens + brand preview
 
-PIPELINE FLOW
-  new-project → research → brand → system → design → spec → review → build → launch
-                                                        ↑                |
-                                                        └── loop back ───┘
-                                                       (if critical issues)
+  Granular re-runs:
+    /gsp:brand-verbal    Phase 3 only — Voice, tone spectrum, messaging, naming
 
-PROJECT STRUCTURE
+PROJECT DIAMOND (6 phases)
+  /gsp:brief           Phase 1 — Project scoping, adaptations, gap analysis
+  /gsp:research        Phase 2 — UX patterns, competitor UX, technical research, reference specs
+  /gsp:design          Phase 3 — UI/UX screens & interaction flows
+  /gsp:critique        Phase 4 — Design critique + accessibility audit
+  /gsp:build           Phase 5 — Design-to-code translation
+  /gsp:review          Phase 6 — Deliverable validation + acceptance
+
+OPTIONAL
+  /gsp:launch          Marketing campaign assets (on request)
+
+E2E FLOW (5 + 6 phases + optional)
+  [brand-audit] → brand-research → brand-strategy → brand-identity → brand-patterns → brief → research → design → critique → build → review
+  |_ optional _|  |___________________ branding diamond __________________________|  |_____________ project diamond ___________________|
+  Optional: launch (after review)
+
+WORKFLOW
+  Treat each project as a bounded issue (or set of issues) and a PR.
+  Ship small, ship complete. Break large projects into focused deliverables.
+
+ALIASES (backwards compatible)
+  /gsp:new-project     → redirects to /gsp:new
+  /gsp:brand           → redirects to /gsp:brand-identity
+  /gsp:brand-discover  → redirects to /gsp:brand-research
+  /gsp:brand-system    → redirects to /gsp:brand-patterns
+  /gsp:discover        → redirects to /gsp:brand-research
+  /gsp:strategy        → redirects to /gsp:brand-strategy
+  /gsp:verbal          → redirects to /gsp:brand-verbal
+  /gsp:identity        → redirects to /gsp:brand-identity
+  /gsp:system          → redirects to /gsp:brand-patterns
+  /gsp:spec            → redirects to /gsp:brief
+  /gsp:plan            → redirects to /gsp:brief
+
+DIRECTORY STRUCTURE
   .design/
-  ├── BRIEF.md                    Design brief
-  ├── ROADMAP.md                  Phase plan
-  ├── STATE.md                    Progress tracking
-  ├── config.json                 Preferences
-  ├── research/TRENDS.md          Trend analysis
-  ├── brand/IDENTITY.md           Brand identity
-  ├── system/SYSTEM.md            Design system
-  ├── system/tokens.json          Design tokens
-  ├── screens/SCREENS.md          UI/UX screens
-  ├── specs/SPECS.md              Implementation specifications
-  ├── review/CRITIQUE.md          Design critique
-  ├── review/ACCESSIBILITY.md     WCAG audit
-  ├── build/CODE.md               Implementation guide
-  ├── build/components/           Code components
-  └── launch/CAMPAIGN.md          Marketing assets
+  ├── branding/
+  │   └── {brand-name}/
+  │       ├── BRIEF.md              Brand brief
+  │       ├── STATE.md              Brand progress
+  │       ├── config.json           Brand config
+  │       ├── audit/               Audit chunks + INDEX.md (evolve mode only)
+  │       ├── discover/             Research chunks + INDEX.md
+  │       ├── strategy/             Strategy chunks + INDEX.md
+  │       ├── verbal/               Verbal chunks + INDEX.md
+  │       ├── identity/             Identity chunks + palettes.json + INDEX.md
+  │       ├── system/               Foundations + components + tokens.json + INDEX.md
+  │       └── preview.html          Brand preview (generated by brand-patterns)
+  └── projects/
+      └── {project-name}/
+          ├── BRIEF.md              Project brief
+          ├── STATE.md              Project progress
+          ├── config.json           Project config
+          ├── brand.ref             → brand reference
+          ├── brief/                Scope + adaptations + INDEX.md
+          ├── research/             UX patterns + competitor UX + tech research + specs + INDEX.md
+          ├── design/               Screen chunks + shared/ + INDEX.md
+          ├── critique/             Critique + accessibility chunks + INDEX.md
+          ├── build/CODE.md         Implementation guide
+          ├── build/components/     Code components
+          ├── review/               Acceptance report + issues + INDEX.md
+          ├── launch/               Campaign chunks + INDEX.md (optional)
+          └── exports/INDEX.md      Master chunk index
 
 TIPS
-  • Run phases in order — each builds on the previous
-  • /gsp:review loops back if critical issues are found
-  • /gsp:progress shows your prettiness meter
-  • You can skip phases if you already have the artifacts
+  • Start with /gsp:new — it detects what exists and routes you
+  • Multiple brands and projects can coexist
+  • Projects reference a brand via brand.ref
+  • /gsp:brand-identity handles both verbal + visual — skips what's done
+  • /gsp:brand-verbal re-runs phase 3 only if you need to revise voice
+  • /gsp:critique loops back if critical issues found
+  • /gsp:doctor checks brand drift across projects
+  • /gsp:progress shows prettiness across all instances
+  • /gsp:launch is optional — run when you need marketing assets
+  • Treat projects as issues + PRs — bounded scope = higher quality
 ```
 </process>

package/commands/gsp/identity.md

@@ -0,0 +1,18 @@
+---
+name: gsp:identity
+description: Visual identity (alias for /gsp:brand-identity)
+allowed-tools:
+  - Read
+---
+<process>
+Display:
+```
+🎨 GSP — Redirecting...
+
+/gsp:identity now redirects to /gsp:brand-identity in GSP 0.4.0.
+Brand commands now use the brand- prefix for clarity.
+```
+
+Tell the user to run `/gsp:brand-identity` instead.
+</process>
+</output>