@c0x12c/spartan-ai-toolkit 1.7.2 → 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.2"
+      "version": "1.8.0"
     }
   ]
 }

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "spartan-ai-toolkit",
-  "version": "1.7.2",
-  "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.2
+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

@@ -84,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
 
@@ -331,13 +334,29 @@ 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.

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/`: