Skip to content

Development Workflow

How the TCG Commerce Operations Platform is built. This page covers the AI-assisted development methodology — specifically the Claude Code skills stack and the region-by-region build cadence used from Phase 5 onward — and the architectural anti-patterns those skills must respect.

The methodology is documented here (not implicit) because it's load-bearing: the dashboard's quality gates, the design-system canon (MASTER.md), and the per-region audit discipline are all consequences of these tooling choices. New collaborators should understand the workflow before touching UI code.

Why this exists

Generative AI defaults to a "statistical-average" aesthetic — "AI slop". Without a design reference system, every session drifts toward the same generic SaaS template, and multi-PR work becomes a patchwork of inconsistent fragments. We adopt explicit tooling to prevent this:

"This isn't a capability problem; it's a structural one: AI generating interfaces lack a design reference system." — Thomas Yao, UI/UX Pro Max & Impeccable

The two skills below give us that reference system upfront and enforce it after.

The skill stack

Four Claude Code skill plugins, ranked by load-bearing:

1. ui-ux-pro-max (foundation, mandatory)

Generates a complete design system at project inception. Inputs: industry context, target users, brand. Outputs: pattern, style, color palette, typography pairing, anti-patterns, pre-delivery checklist. Persisted to apps/dashboard/design-system/MASTER.md — the design "north star" every subsequent session reads before building.

  • When: at Phase 5 PR C kickoff (one-time per project). Iterate conversationally until the output resonates with the brand.
  • Output: committed MASTER.md, gitignored regeneration artifacts.
  • Source: github.com/nextlevelbuilder/ui-ux-pro-max-skill

2. impeccable (audit + refinement, mandatory)

Provides the audit/refinement loop with 13 slash commands: /teach-impeccable (one-time), /audit, /critique, /typeset, /arrange, /colorize, /normalize, /distill, /bolder, /animate, /adapt, /harden, /polish. Run per region during dashboard implementation.

  • When: every UI region in PRs C → F. Bookend each region build with /audit and /polish; reach for the middle commands based on what /audit flags.
  • Caveat: Impeccable encodes Paul Bakaus's design opinions (rejects bounce animations, neon-on-dark, single-font monotony). Project-specific overrides go in .impeccable.md at repo root.
  • Source: github.com/pbakaus/impeccable

3. vercel-plugin (general guidance, partial use)

Bundles vercel:nextjs, vercel:shadcn, vercel:react-best-practices, vercel:ai-sdk, plus the implicit Web Interface Guidelines reviewer. Useful for general Next.js / shadcn / React advice.

  • When: ad-hoc, when implementing a screen needs framework-level guidance.
  • Critical exclusions: see Anti-patterns below — most Vercel-product skills are inert or actively harmful for our stack (we deploy to Cloudflare Workers, not Vercel; Medusa is the auth source, not Clerk/Auth0).
  • Source: github.com/vercel/vercel-plugin

4. Anthropic frontend-design skill (optional, belt-and-braces)

Conceptual direction layer. Composes with the three above for complete coverage.

  • When: if Pro Max + Impeccable feel insufficient on a specific surface (rare).
  • Status: optional — not installed by default.

Per-region build cadence

The strongest discipline rule: never generate entire pages at once. Build one region at a time, audit between regions.

For each region (header, side-nav, filter bar, table row, detail card, action cluster, etc.):

1. Build the region (TDD: Playwright spec or component test first, then impl)
2. /audit [region]      — technical quality, 5 dimensions, P0–P3 severity
3. /critique [region]   — UX heuristics review (Nielsen 10)
4. Targeted fixes:
     /typeset    — fonts, hierarchy, sizing, line spacing
     /arrange    — layout monotony, inconsistent spacing
     /colorize   — strategic color in mono designs
     /normalize  — align inconsistent components to MASTER.md
     /distill    — remove visual noise
     /bolder     — raise contrast / impact when needed
     /animate    — purposeful transitions, motion-preference-aware
     /adapt      — cross-device responsive checks
     /harden     — error handling + edge cases
5. /polish [region]     — final pass before commit
6. Commit (test + impl + audit notes if anything material surfaced)

/audit and /polish are bookends; the middle commands are reach-for-when-needed based on what /audit flags.

Per-PR engagement intensity

PR Engagement Why
Phase 5 PR C — Skeleton + auth bridge Foundation-critical. Generate MASTER.md here. Build login + AppShell as audited regions. Locks visual language for everything downstream.
Phase 5 PR D — Orders + exception queue High. First operator surfaces. Per-region: filter bar → table row → detail card → action cluster → JSON-tree. Heavy /audit + /critique.
Phase 5 PR E — Inventory + variant editor Maximum. The variant editor is novel UX (cartesian-product editor for 30+ TCG variants). Plan calls it the highest-risk surface. Lean hard on /critique (Nielsen heuristics) and /distill (cartesian-product editor will tend toward complexity).
Phase 5 PR F — Staff management + branding High — final polish phase. Full /polish sweep + /distill cleanup. The "feels like a product" PR.
Phase 5 PR G — Cloudflare Workers deploy + findings None. Infra/docs only.

Anti-patterns

Locked architectural decisions that the skill output must respect. Future Claude sessions will not violate these because they're documented in repo-root CLAUDE.md files, but they're recorded here for human readers too.

Auth replacement

The TCG platform's identity source is Medusa core (authenticate("user", ["session", "bearer"]), emailpass provider, connect.sid cookie). Phase 5 PR B locked this with the staff module + user_role table linked 1:1 to Medusa's user.

Do not introduce:

  • vercel:auth (Clerk / Descope / Auth0 paths from the Vercel plugin)
  • NextAuth.js / Auth.js
  • BetterAuth / Lucia

Each replaces Medusa as the identity source and invalidates Phase 5 PR B's architecture. The dashboard's auth bridge is a thin consumer (~60 LOC: POST /auth/user/emailpass → JWT → POST /auth/session → Set-Cookie); don't expand it into a parallel auth system.

Deploy target

The dashboard deploys to Cloudflare Workers via @opennextjs/cloudflare, not Vercel.

Do not use: vercel:deploy, vercel:vercel-cli, vercel:env-vars, vercel:deployments-cicd, vercel:bootstrap, vercel:next-forge — these all assume a Vercel-linked project.

The vercel:nextjs and vercel:shadcn skills are useful for general framework guidance (they don't assume Vercel deploy).

Component / form / table / cache libraries

The off-the-shelf stack is locked in phase-5-implementation.md:

  • Component library: shadcn/ui (lean default — MASTER.md confirms or overrides at PR C kickoff)
  • Forms: React Hook Form + Zod
  • Tables: TanStack Table v8
  • Client cache: TanStack Query v5
  • Server fetch: Next.js server actions + the medusaFetch wrapper
  • JSON viewer: react-json-tree
  • Toasts: sonner
  • Dates: date-fns

Don't introduce parallel implementations. If a screen needs more than one of these provides, extend the existing primitive — don't fork to a different library.

Other Vercel-product skills

vercel:vercel-firewall, vercel:runtime-cache, vercel:vercel-functions, vercel:vercel-storage, vercel:vercel-sandbox, vercel:ai-gateway, vercel:turbopack, vercel:vercel-agent, vercel:workflow, vercel:routing-middleware, vercel:chat-sdk, vercel:marketplace, vercel:next-cache-components — inert for our stack. Skip unless prototyping something Vercel-specific.

Setup

For collaborators cloning either repo, see:

  • Homelab vault (this repo, ExzenTCG-Homelab): root CLAUDE.md lists the required plugins; .claude/settings.json declares enabledPlugins so Claude Code prompts on first open.
  • Application repo (ExzenTCG/tcg-platform): root CLAUDE.md + scripts/setup-claude-plugins.sh (manual fallback printer).

Required plugins (one-time install per machine):

/plugin marketplace add nextlevelbuilder/ui-ux-pro-max-skill
/plugin install ui-ux-pro-max@ui-ux-pro-max-skill

/plugin marketplace add pbakaus/impeccable
/plugin install impeccable@impeccable

/plugin marketplace add vercel/vercel-plugin
/plugin install vercel-plugin@vercel

/reload-plugins

/plugin list should show all three loaded.

References