@c0x12c/spartan-ai-toolkit 1.7.1 → 1.8.0

package/.claude-plugin/marketplace.json

@@ -8,9 +8,9 @@
   "plugins": [
     {
       "name": "spartan-ai-toolkit",
-      "description": "5 workflows, 56 commands, 12 rules, 22 skills, 7 agents — organized in 11 packs with dependencies",
+      "description": "5 workflows, 68 commands, 21 rules, 28 skills, 9 agents — organized in 12 packs with dependencies",
       "source": "./toolkit",
-      "version": "1.7.1"
+      "version": "1.8.0"
     }
   ]
 }

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "spartan-ai-toolkit",
-  "version": "1.7.1",
-  "description": "Engineering discipline layer for Claude Code — 5 workflows, 56 commands, 12 rules, 22 skills, 7 agents organized in 11 packs",
+  "version": "1.8.0",
+  "description": "Engineering discipline layer for Claude Code — 5 workflows, 68 commands, 21 rules, 28 skills, 9 agents organized in 12 packs",
   "author": {
     "name": "Khoa Tran",
     "url": "https://github.com/spartan-stratos"

package/VERSION

@@ -1 +1 @@
-1.7.1
+1.8.0

package/agents/design-critic.md

@@ -34,6 +34,18 @@ This is your #1 job. Does this design look like every other AI-generated page?
 - [ ] Copy is specific to the project domain (not generic marketing fluff)
 - [ ] Would you remember this design tomorrow? (If no, it's too generic)
 
+### Design Token Compliance (ZERO tolerance if tokens exist)
+
+Check `.planning/design/system/tokens.md` and `.planning/design-config.md`:
+
+- [ ] **EVERY** color in the design matches the token list EXACTLY (not "close enough")
+- [ ] **EVERY** font reference matches the project font EXACTLY (not a substitute)
+- [ ] Spacing values align with the token scale (no arbitrary numbers)
+- [ ] Border radius matches token definitions
+- [ ] Shadow levels match token definitions
+
+**Hard fail:** If even ONE color or font doesn't match the tokens → NEEDS CHANGES. The whole point of tokens is consistency. No exceptions.
+
 ### Brand Compliance (If design-config exists)
 
 - [ ] Colors match the design-config palette exactly (not approximations)

package/claude-md/25-ux-design.md

@@ -0,0 +1,56 @@
+
+---
+
+## UX Design Workflow
+
+**Stack:** Platform-agnostic UX research and design — works for web, mobile, or any digital product.
+
+**The full design pipeline:**
+```
+/spartan:ux                     ← smart router: asks what you need
+/spartan:ux research            ← Phase 1: User discovery
+/spartan:ux define              ← Phase 2: Problem definition
+/spartan:ux ideate              ← Phase 3: Solution exploration
+/spartan:ux system              ← Design system setup (tokens + components)
+/spartan:ux prototype           ← Phase 4: Screen design + Design Gate
+/spartan:ux test                ← Phase 5: Usability testing plan
+/spartan:ux handoff             ← Phase 6: Developer handoff spec
+/spartan:ux qa                  ← Phase 7: Design QA checklist
+/spartan:ux audit               ← Mid-stream: scan what exists, find gaps
+```
+
+### 3 Maturity Tracks
+
+| Track | Phases | Time | When to use |
+|-------|--------|------|-------------|
+| **Quick** | prototype → handoff | 1-2 hours | Small UI change, single component |
+| **Standard** | research → define → prototype → test → handoff | 1-3 days | Real feature with users |
+| **Full** | All 7 phases | 1-3 weeks | New product, major redesign |
+
+### Design Artifacts Location
+
+```
+.planning/design/
+├── research/          ← User interviews, competitors, insights
+├── definition/        ← Personas, journey map, problem brief
+├── ideation/          ← Ideas, user flows
+├── system/            ← Design tokens, component inventory
+└── screens/           ← Per-feature screen designs
+```
+
+### Design Token Enforcement
+
+Once design tokens exist, ALL downstream commands enforce them:
+- `/spartan:build` injects tokens into agent prompts
+- `/spartan:fe-review` checks token compliance (Stage 8)
+- `/spartan:next-feature` scaffolds with project tokens
+- `design-critic` agent hard-fails on token mismatches
+
+### Works With Other Workflows
+
+| You're running... | UX integration |
+|-------------------|---------------|
+| `/spartan:build frontend` | Checks for design tokens, nudges if missing |
+| `/spartan:spec` (UI feature) | Checks for user research, suggests if missing |
+| `/spartan:fe-review` | Checks code against design tokens |
+| `/spartan:design` | Alias for `/spartan:ux prototype` |

package/commands/spartan/build.md

@@ -31,6 +31,19 @@ EPIC (multi-feature — auto-detected):
 **Full path:** For bigger work, you call `/spartan:spec`, `/spartan:design`, `/spartan:plan` as sub-steps.
 **Epic path:** If the feature name matches an epic with 2+ specs ready, build all features together — one branch, one PR.
 
+### Stages That MUST NOT Be Skipped
+
+| Stage | When it runs | Can skip? |
+|-------|-------------|-----------|
+| Stage 1 (Spec) | Always | NO — every feature needs a scope |
+| Stage 2 (Design) | Frontend/UI work | NO — must ask user (skip only if pure data change) |
+| Stage 3 (Plan) | Always | NO — every feature needs a plan |
+| Stage 4 (Implement) | Always | NO |
+| Stage 5 (Review) | Always | **NEVER** — this is the most commonly skipped stage. You MUST spawn the review agent. |
+| Stage 6 (Ship) | Always | NO |
+
+**If you finish Stage 4 and are about to commit/PR without running Stage 5 — STOP. You are skipping review. Go back and run it.**
+
 ---
 
 ## Step 0: Detect Mode & Stack (silent — no questions)
@@ -71,9 +84,12 @@ ls .memory/decisions/ .memory/patterns/ .memory/knowledge/ .memory/blockers/ 2>/
 
 # Check for existing artifacts
 ls .planning/specs/*.md 2>/dev/null
-ls .planning/designs/*.md 2>/dev/null
+ls .planning/designs/*.md .planning/design/screens/*.md 2>/dev/null
 ls .planning/plans/*.md 2>/dev/null
 
+# Check for design tokens
+ls .planning/design/system/tokens.md .planning/design-config.md 2>/dev/null
+
 # Check for epic
 ls .planning/epics/*.md 2>/dev/null
 
@@ -195,7 +211,7 @@ If user picks B → continue to Plan.
 
 If user picks C → read the Figma reference and use it as the design source.
 
-**Auto mode on?** → Still ask this question. Design skipping is the user's call, not yours. The only exception: if the ONLY UI change is a single field addition to an existing component (e.g., adding a column to a table), skip silently.
+**Auto mode on?** → Still ask this question. Design skipping is the user's call, not yours. The only exception: if the change is purely data (adding a column to an existing table, no new screens or layouts), skip silently. If there's ANY new component, screen, modal, or layout change — you MUST ask.
 
 ---
 
@@ -318,17 +334,35 @@ ls .planning/designs/*.md 2>/dev/null
 - **pages-dev** — pages + routing + integration (blocked by components-dev)
 
 **Design doc handoff (MANDATORY for frontend/UI agents):**
-If a design doc exists at `.planning/designs/`, EVERY frontend/UI agent MUST get this in its prompt:
+If a design doc exists at `.planning/designs/` or `.planning/design/screens/`, EVERY frontend/UI agent MUST get this in its prompt:
 ```
-Design doc: .planning/designs/{feature}.md — read this FIRST.
+Design doc: .planning/design/screens/{feature}.md — read this FIRST.
 Follow the screen designs, component specs, and visual details exactly.
 Do NOT invent your own layout or design. The design was already reviewed and approved.
 ```
 
+**Design token enforcement (MANDATORY for frontend/UI work):**
+```bash
+ls .planning/design/system/tokens.md .planning/design-config.md 2>/dev/null
+```
+If design tokens exist, read them and inject into EVERY frontend/UI agent prompt:
+```
+DESIGN TOKENS — BINDING CONSTRAINTS:
+Read .planning/design/system/tokens.md (or .planning/design-config.md).
+You MUST use these exact values. Do NOT use Tailwind defaults or generic colors.
+- Use token color names, not hex values or bg-blue-500
+- Use the project font, not Inter/Arial/system-ui
+- Use the spacing scale, not arbitrary padding/margin
+- Use the project border radius, not rounded-lg
+Every color, font, and spacing value in your code must come from the token list.
+```
+
 5. Monitor progress. When all agents finish, merge worktrees and run full test suite.
 
 6. `TeamDelete` to clean up.
 
+7. **MANDATORY: Continue to Stage 5 (Review) NOW.** Do NOT stop here. Do NOT ask "Want me to commit?" or "Should I create a PR?" — implementation is done but review hasn't happened yet. Go straight to Gate 3 → Stage 5.
+
 **If Agent Teams is NOT enabled** (env var not set), continue with sequential execution below.
 
 ### Sequential execution (default)
@@ -392,14 +426,22 @@ npm test && npm run build
 ./gradlew test && npm test && npm run build
 ```
 
-**GATE 3 — Implementation complete.**
+**GATE 3 — Implementation complete. Review is NEXT.**
 > "All [N] tasks done. [X] tests passing. Starting review."
 >
 > **Auto mode on?** → Go straight to review.
+>
+> **CRITICAL: You MUST run Stage 5 (Review) after this gate. No exceptions. Do NOT commit, do NOT create a PR, do NOT ask the user what to do next. The next step is ALWAYS the review agent.**
 
 ---
 
-## Stage 5: Review (agent-based — mandatory)
+## Stage 5: Review (agent-based — MANDATORY, NEVER SKIP)
+
+> **CRITICAL: This stage MUST run for every build. No exceptions.**
+> - Not optional. Not skippable. Not deferrable.
+> - Do NOT ask the user "Want me to skip review?" or "Should I review?"
+> - Do NOT commit or create a PR before this stage completes.
+> - If you catch yourself about to skip this stage, STOP and run it.
 
 **This is NOT a self-review.** Spawn a separate review agent to get a fresh perspective. The reviewer finds issues, you fix them, repeat until clean.
 
@@ -753,7 +795,8 @@ If a previous session was interrupted (context overflow, user stopped, etc.), th
 - **Gates are mandatory.** Even small features go through all stages. The stages are fast for small work — that's fine.
 - **TDD by default.** Write the test first. Override only when test-first doesn't make sense for that specific task.
 - **One commit per task.** Don't batch. Each task = one commit with a clear message.
-- **Review is always an agent.** Never self-review. Always spawn a separate review agent for a fresh perspective. Fix issues until the reviewer says PASS.
+- **Review is ALWAYS an agent. NEVER skip.** This is the #1 rule. After implementation finishes — whether via Agent Teams or sequential — you MUST spawn the review agent (Stage 5). Never self-review. Never skip review. Never ask the user if they want to skip. Never commit or create a PR without review. Fix issues until the reviewer says PASS.
+- **Design gate runs for frontend work.** If the feature has UI work (new components, screens, modals, layouts), you MUST trigger the design question in Stage 2. Only skip for pure data changes (adding a field to an existing table/component).
 - **Security check always runs.** Whether backend or frontend, security patterns get checked during review.
 - **Frontend checks for backend needs.** If a new page needs data that doesn't exist yet, say so at Stage 3 and add backend tasks first.
 - **Don't over-plan.** If the whole thing is 1-2 files and 30 minutes of work, don't force it into this workflow. Just do it. This workflow is for features that need structure — at least 2-3 tasks.

package/commands/spartan/design.md

@@ -1,229 +1,23 @@
 ---
 name: spartan:design
-description: Design workflow — project config, design doc, designer + critic review, Design Gate
+description: "Alias for /spartan:ux prototype — design workflow with Design Gate"
 argument-hint: "[feature name]"
-preamble-tier: 4
+preamble-tier: 1
 ---
 
 # Design: {{ args[0] | default: "unnamed feature" }}
 
-You are running the **Design workflow** — create a design document for a feature with UI work. Uses a dual-agent approach: you (designer) + `design-critic` agent.
+> **This command has moved to `/spartan:ux prototype`.** Running it now.
 
-```
-Epic → Spec → ► [Design] → Plan → Build → Review
-                    ↑
-               Design Gate
-```
+Run `/spartan:ux prototype {{ args[0] }}` internally. Pass all arguments through.
 
-The design doc gets saved to `.planning/designs/{{ args[0] | default: "feature-name" }}.md`.
-
----
-
-## Step 0: Check Prerequisites
-
-### Find the spec
-```bash
-ls .planning/specs/{{ args[0] | default: "feature-name" }}.md 2>/dev/null
-```
-
-If spec exists, read it. The design must match the spec's requirements.
-If no spec, ask:
-> "No spec found. Want to:"
-> - A) Write the spec first → `/spartan:spec {{ args[0] }}`
-> - B) Give me a quick brief and I'll design from that
-
-### Find design config
-```bash
-ls .planning/design-config.md .claude/design-config.md 2>/dev/null
-```
-
-If no design config exists, ask:
-> "No design config found. This file sets your project's colors, fonts, and brand identity."
-> - A) Create one now — I'll ask you a few questions
-> - B) Skip it — I'll use generic design guidelines
-
-If user picks A, run the **Design Config Setup** (see below).
-
-### Load the design-workflow skill
-Read the `design-workflow` skill for anti-AI-generic guidelines. Apply these throughout.
-
----
-
-## Design Config Setup (only if no config exists)
-
-Ask these questions **one at a time**:
-
-1. **"What's the app/product name?"**
-2. **"Light theme, dark theme, or both?"**
-3. **"What's the primary brand color?"** (e.g., "violet #8B5CF6", "amber #F59E0B")
-4. **"What font do you use?"** (default: Inter if unsure)
-5. **"Any reference apps for the look and feel?"** (e.g., "Linear, Vercel Dashboard")
-6. **"What should it NOT look like?"** (anti-references)
-
-Save to `.planning/design-config.md` using the `design-config.md` template.
-
----
-
-## Step 1: Design Brief
-
-Fill in the brief from the spec and user input:
-
-```markdown
-### What are we designing?
-[From spec's UI Changes section or user's description]
-
-### Who's the user?
-[From spec's User Stories or design-config]
-
-### Goal
-[From spec's Goal section]
-
-### Platform
-[Desktop / Mobile / Both — ask if not clear]
-```
-
----
-
-## Step 2: User Flows
-
-Map every user story from the spec to a concrete flow:
-
-```markdown
-### Flow 1: [name]
-**Trigger**: [what starts it]
-
-| Step | User Action | System Response | Screen |
-|------|-------------|-----------------|--------|
-| 1 | [action] | [response] | [screen] |
-```
-
-Include edge case flows: empty data, error, loading, timeout.
-
----
-
-## Step 3: Screen Design
-
-For each screen:
-
-1. **Screen inventory** — list all screens with their states
-2. **Component list** — what components each screen needs
-3. **Wireframes** — ASCII wireframes showing layout structure
-4. **Responsive behavior** — how layout changes at mobile/tablet/desktop
-
-If design-config exists, use its colors, fonts, and design personality. Don't invent new values.
-
----
-
-## Step 4: Visual Design Details
-
-Add these sections if the project has a design config:
-
-### Section Zones
-Plan background alternation for visual rhythm:
-```markdown
-| Section | Background | Mood |
-|---------|-----------|------|
-| Hero | [from design-config palette] | Dramatic entry |
-| Content | [slightly different bg] | Subtle shift |
-```
-
-### Motion Plan
-What moves and when:
-```markdown
-| Element | Animation | Trigger | Duration |
-|---------|-----------|---------|----------|
-| Section content | Fade up | Scroll into view | 0.6s |
-| Cards | Stagger fade | Scroll into view | 0.6s + 0.15s |
-```
-
-### Component Specs
-For key components, detail props, states, and interactions:
-```markdown
-| Prop | Type | Required | Description |
-|------|------|----------|-------------|
-| [name] | [type] | [yes/no] | [what it does] |
-```
-
----
-
-## Step 5: Accessibility Checklist
-
-Before sending to critic, verify:
-
-- [ ] Color contrast meets WCAG AA (4.5:1 for text, 3:1 for large text)
-- [ ] All interactive elements keyboard accessible
-- [ ] Focus order follows visual layout
-- [ ] Animations respect `prefers-reduced-motion`
-- [ ] Touch targets at least 44x44px on mobile
-- [ ] No information conveyed by color alone
-
----
-
-## Step 6: Self-Check (Before Calling Critic)
-
-Run through these checks yourself:
-
-1. **Does it look like a real app, or a generic AI template?**
-2. **Is there clear visual hierarchy?** Can you tell what's most important?
-3. **Does the accent color draw the eye to CTAs?**
-4. **Is there enough whitespace?**
-5. **Does the text use specific language, not generic marketing fluff?**
-6. **Does it match the design personality from design-config?**
-
-Fix anything that fails before calling the critic.
-
----
-
-## Step 7: Spawn Design Critic
-
-Spawn the `design-critic` agent as a subagent. Give it:
-
-1. **The design document** you just wrote
-2. **The design-config** (if exists)
-3. **The spec** (if exists)
-4. **Your self-check results** from Step 6
-
-**Prompt for the critic:**
-> "Review this design for the Design Gate. Design doc: [content]. Design-config: [path or 'none']. Spec: [path or 'none']. Check for AI-generic patterns, brand compliance, accessibility, and responsive behavior. Give your verdict: ACCEPT or NEEDS CHANGES."
-
-### Discussion
-Same rules as `/spartan:gate-review`:
-- If critic says ACCEPT → Design Gate passed
-- If critic says NEEDS CHANGES → fix issues, re-submit
-- Max 3 rounds of back-and-forth
-- Escalate to user if stuck
-
----
-
-## Step 8: Save and Confirm
-
-Save the design doc to `.planning/designs/{{ args[0] | default: "feature-name" }}.md`.
-
-```markdown
-**Date**: [today]
-**Status**: approved
-**Spec**: .planning/specs/{{ args[0] }}.md
-**Designer**: Claude (main agent)
-**Critic**: design-critic agent
-**Verdict**: PASSED — both agents accept
-```
-
-Then tell the user:
-
-> "Design saved to `.planning/designs/{{ args[0] }}.md` — Design Gate passed."
->
-> **Next steps:**
-> - Ready to plan? → `/spartan:plan {{ args[0] }}`
-> - Want to build a prototype first? → Ask and I'll generate HTML
-> - Need changes? → Run `/spartan:design {{ args[0] }}` again
-
----
-
-## Rules
-
-- **Read the design-config first.** If it exists, every color and font must come from it. No inventing.
-- **Anti-AI-generic is the top priority.** If the design looks like every other AI-generated page, it fails.
-- **All states must be covered.** Loading, empty, error, success — not just the happy path.
-- **Responsive is not optional.** Every screen must work at mobile, tablet, and desktop.
-- **Critic must accept.** Single-agent design is just `/spartan:build` with a UI. The dual-agent review is what makes this command valuable.
-- **Auto mode on?** → Skip confirmations but still run the full critic review.
+The full UX design workflow is now at `/spartan:ux` with sub-commands:
+- `/spartan:ux research` — user discovery
+- `/spartan:ux define` — problem definition
+- `/spartan:ux ideate` — solution exploration
+- `/spartan:ux system` — design system setup
+- `/spartan:ux prototype` — screen design + Design Gate (this is what `/spartan:design` used to do)
+- `/spartan:ux test` — usability testing plan
+- `/spartan:ux handoff` — developer handoff
+- `/spartan:ux qa` — design QA checklist
+- `/spartan:ux audit` — gap analysis

package/commands/spartan/fe-review.md

@@ -127,6 +127,33 @@ done
 
 ---
 
+## Stage 8: Design Token Compliance
+
+**Only runs if `.planning/design/system/tokens.md` or `.planning/design-config.md` exists.**
+
+Read the design tokens file first. Then check every changed frontend file:
+
+- [ ] Colors use token names or CSS variables, not hardcoded hex or Tailwind defaults
+  - Search for: raw hex values (#xxx), `bg-blue-*`, `bg-purple-*`, `text-gray-*`
+  - Each match: is this value in the token list? If not → flag as **critical**
+- [ ] Font family matches design config, not generic fallbacks
+  - Search for: `font-sans`, `Inter`, `Roboto`, `Arial`, `system-ui`
+  - If project font is different → flag as **critical**
+- [ ] Spacing uses the token scale, not arbitrary values
+  - Random values like `p-[13px]` or `mt-[7px]` → flag as **warning**
+- [ ] Border radius matches token definitions
+- [ ] New components reference the design system, not reinventing styles
+
+```bash
+# Quick scan for hardcoded colors (should be tokens)
+git diff main...HEAD -- "*.tsx" "*.ts" "*.css" | grep -E '#[0-9a-fA-F]{3,8}|bg-(blue|red|green|purple|pink|indigo|violet)-[0-9]' | head -20
+
+# Quick scan for generic fonts
+git diff main...HEAD -- "*.tsx" "*.ts" "*.css" | grep -E "font-sans|Inter|Roboto|Arial|system-ui" | head -10
+```
+
+---
+
 ## Output Format
 
 ```markdown

package/commands/spartan/figma-to-code.md

@@ -13,6 +13,22 @@ You are converting a Figma design into production React/Next.js code using **Fig
 
 ---
 
+## Phase 0: Check for existing design tokens (silent)
+
+```bash
+ls .planning/design/system/tokens.md .planning/design-config.md 2>/dev/null
+```
+
+If design tokens already exist, read them FIRST. When extracting from Figma:
+- **MERGE** Figma colors with existing tokens — don't create a second conflicting token set
+- Use existing token NAMES (e.g., `--color-primary`) even if Figma uses different hex values
+- If Figma colors differ from tokens, flag the mismatch and ask the user which to keep
+- Any NEW tokens from Figma get added to the existing file, not written to a separate one
+
+If NO tokens exist, proceed normally — extract from Figma and create new tokens.
+
+---
+
 ## Phase 1: Extract Design Data (single MCP call)
 
 Call Figma MCP to get the screen data:

package/commands/spartan/next-feature.md

@@ -24,6 +24,21 @@ Ask the user:
 
 ---
 
+## Step 1.5: Check for design tokens (silent)
+
+```bash
+ls .planning/design/system/tokens.md .planning/design-config.md 2>/dev/null
+```
+
+If design tokens exist, read them. All scaffolded components MUST use project tokens:
+- Use project colors in default styles, not Tailwind defaults
+- Use project font in any typography
+- Import from the project's design token file if it exists (e.g., `@/lib/design-tokens`)
+
+If NO tokens exist, scaffold with clean, unstyled components. Use `bg-neutral-*` placeholder styles that are obviously temporary. Don't use `bg-blue-500` or other Tailwind color defaults.
+
+---
+
 ## Step 2: Map the directory structure
 
 Based on answers, propose this structure under `app/` or `components/`:

package/commands/spartan/pr-ready.md

@@ -27,16 +27,18 @@ If uncommitted changes exist → commit or stash before continuing.
 ## Step 2: Rebase onto Main
 
 ```bash
-# Fetch latest
+# Fetch latest and detect default branch
 git fetch origin
+DEFAULT_BRANCH=$(git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's@^refs/remotes/origin/@@')
+[ -z "$DEFAULT_BRANCH" ] && DEFAULT_BRANCH=$(git rev-parse --verify origin/master >/dev/null 2>&1 && echo master || echo main)
 
-# See what's new on main
-git log HEAD..origin/main --oneline
+# See what's new on the default branch
+git log HEAD..origin/$DEFAULT_BRANCH --oneline
 ```
 
-If main has new commits:
+If the default branch has new commits:
 ```bash
-git rebase origin/main
+git rebase origin/$DEFAULT_BRANCH
 ```
 
 **Conflict resolution:**

package/commands/spartan/update.md

@@ -18,16 +18,34 @@ echo "Current version: $LOCAL_VER"
 echo "Repo path: $REPO_PATH"
 ```
 
-If `REPO_PATH` is empty or the directory doesn't exist, ask the user where they cloned `spartan-ai-toolkit`:
-"I don't know where the Spartan repo is. Where did you clone it? (e.g., `~/spartan-ai-toolkit`)"
+If `REPO_PATH` is empty or the directory doesn't exist, try to find it:
+
+```bash
+# Common locations
+for dir in ~/spartan-ai-toolkit ~/Documents/Code/Spartan/spartan-ai-toolkit ~/Code/spartan-ai-toolkit; do
+  [ -d "$dir/toolkit" ] && echo "Found: $dir" && break
+done
+```
+
+If still not found, ask the user: "Where did you clone spartan-ai-toolkit?"
 
 ---
 
-## Step 2: Check for updates
+## Step 2: Detect default branch and check for updates
 
 ```bash
-cd "$REPO_PATH" && git fetch origin main --quiet 2>/dev/null
-REMOTE_VER=$(git show origin/main:toolkit/VERSION 2>/dev/null || echo "unknown")
+cd "$REPO_PATH"
+
+# Detect the default branch (master or main)
+DEFAULT_BRANCH=$(git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's@^refs/remotes/origin/@@')
+if [ -z "$DEFAULT_BRANCH" ]; then
+  # Fallback: check which branch exists
+  git rev-parse --verify origin/master >/dev/null 2>&1 && DEFAULT_BRANCH="master" || DEFAULT_BRANCH="main"
+fi
+echo "Default branch: $DEFAULT_BRANCH"
+
+git fetch origin "$DEFAULT_BRANCH" --quiet 2>/dev/null
+REMOTE_VER=$(git show "origin/$DEFAULT_BRANCH:toolkit/VERSION" 2>/dev/null || echo "unknown")
 echo "Local:  $LOCAL_VER"
 echo "Remote: $REMOTE_VER"
 ```
@@ -56,7 +74,7 @@ Show the user their current packs and ask:
 ## Step 4: Pull and reinstall
 
 ```bash
-cd "$REPO_PATH" && git pull origin main
+cd "$REPO_PATH" && git pull origin "$DEFAULT_BRANCH"
 ```
 
 Then run the setup script with saved packs: