V Swarm

v-swarm — Vercel/Next.js Excellence Orchestration

Activation: this skill loads when /v fires or when the user asks for Vercel/Next.js work. The skill body below is the orchestration logic. Detailed knowledge lives in references/.

Lane classification

Pick exactly one lane per /v invocation. If the ask spans multiple, pick the dominant one and surface the others as follow-ups.

If unclear: ask one question, never more. Default question: "Lane — build something new, deploy what's there, audit what's live, research what to do, or fix something that's broken?"

Swarm recipes

Each lane has a recipe. Spawn agents in parallel using the superpowers:dispatching-parallel-agents skill. Never sequence agents that can run independently.

BUILD

Parallel:
  Agent: frankx-website-builder
    task: implement the requested page/component, follow CLAUDE.md voice + glassmorphic design system
  Agent: ui-ux-design-guidance
    task: review proposed UX, surface accessibility gaps, suggest interaction patterns
  Skill load: nextjs-expert + vercel:nextjs + vercel:react-best-practices
  Optional: /v0-generate for rapid prototype if user mentioned "prototype" or "draft"

Then sequential:
  - Reconcile builder output with UX feedback
  - Run pre-deploy checks (lane = AUDIT subset) on the new code path
  - Surface diff for review

DEPLOY

Pre-flight (sequential, fast):
  1. mcp__claude_ai_Vercel__list_projects → confirm correct project name
  2. mcp__claude_ai_Vercel__get_project → confirm framework, latest deployment, build settings
  3. Check git: working tree clean, branch pushed, CI green
  4. Code-review gate: pr-review-toolkit:code-reviewer against the diff
     - If gate returns FAIL → block deploy, surface the issues
     - If WARN → surface but allow with explicit user ack
     - If PASS → proceed
  5. Vercel Agent PR check: gh pr view <N> --json statusCheckRollup
     - Look for "Vercel Agent Review" check
     - SUCCESS → proceed
     - FAILURE → block, surface findings
     - NEUTRAL → proceed (no issues detected)
  6. Surface plan + pause for user confirmation if production-targeted

Action:
  7. mcp__claude_ai_Vercel__deploy_to_vercel (only if confirmed)
  OR vercel deploy --prebuilt --prod (CLI, if local-files deploy needed)
  OR rely on Git push if Vercel project is configured for auto-deploy on the branch

Post-deploy (parallel):
  - mcp__claude_ai_Vercel__get_deployment → status, URL
  - mcp__claude_ai_Vercel__get_deployment_build_logs → warnings, errors, build duration
  - Wait until status = READY (poll list_deployments if needed; never claim ship before ready)

Verify (parallel):
  - mcp__claude_ai_Vercel__get_runtime_logs → smoke check first 60s of traffic for errors
  - vercel logs <deploy-url> (CLI live tail for the first 30s)
  - Curl the deploy URL → HTTP 200 + reasonable response time
  - Spot-check 1-2 critical routes from references/deployment-checklist.md

AUDIT

Parallel:
  Agent: performance-guardian
    task: Lighthouse run + bundle analysis + CWV against the live URL
    target: LCP < 2.5s, INP < 200ms, CLS < 0.1 (per references/deployment-checklist.md)
  Agent: accessibility-auditor
    task: WCAG 2.2 sweep, keyboard nav, screen reader spot-check
  MCP: mcp__claude_ai_Vercel__get_runtime_logs
    range: last 24h
    filter: errors + warnings
  MCP: mcp__claude_ai_Vercel__get_deployment_build_logs
    target: last successful deploy
    look for: warnings, slow build steps, large bundles

Synthesize:
  - Prioritize findings by user-impact × effort
  - Output a fix list with: severity, owner-skill (which agent or skill should fix), 1-line fix
  - Cite references/best-practices-2026.md when recommending Next.js 16 patterns

RESEARCH

Parallel:
  MCP: mcp__claude_ai_Vercel__search_vercel_documentation
    query: derived from user ask
  Read: references/best-practices-2026.md (relevant section)
  Read: references/thought-leaders.md (find the right voice for this question)
  Optional: 1 WebSearch if the topic is post-knowledge-cutoff or doc gap

Synthesize:
  - Answer in: TL;DR (1 line), Why (3 bullets), Recommendation (1 paragraph), Sources
  - Sources MUST include: official Vercel/Next.js doc URL + at least one named expert with rationale
  - If you can't find authority, say so explicitly — never invent a quote

FIX

Sequential start (because debugging is iterative):
  1. Skill load: superpowers:systematic-debugging — follow it, don't shortcut
  2. Reproduce: ask for steps if not given; spin up local dev or hit prod URL
  3. MCP: get_runtime_logs (filter to error level) for the affected route
  4. MCP: get_deployment_build_logs (last build) for warnings
  5. Read the relevant code path

Then parallel:
  Agent: performance-guardian (if symptom = slow/INP regression)
    task: Lighthouse + bundle delta vs last known good
  Agent: accessibility-auditor (if symptom = a11y bug)
    task: WCAG 2.2 spot check on broken flow
  WebSearch: if symptom matches a known issue (Next.js GitHub discussions are gold)

Verify the fix:
  - Reproduce the symptom one more time before claiming fixed
  - Add a regression note if applicable (test, comment, or doc)

ELEVATE

Full audit → gap → fix → ship → teach loop. The leverage lane — every audit becomes a PR + a learning artifact. See references/elevate-playbook.md for the complete recipe.

Flags:
  --plan-only  : audit + gap-pass only, no fixes. Output markdown report.
  --teach      : force learning artifact (default on when --plan-only=false)
  --auto-fix   : skip Frank-gate, ship fixes immediately after gate-pass

Stage 1 — Audit pass (parallel):
  Agent: vercel:performance-optimizer
    task: CWV against live URL, bundle analysis, Speed Insights regressions
  Agent: performance-guardian
    task: Lighthouse run on all surfaces, prioritize LCP < 2.5s INP < 200ms CLS < 0.1
  Agent: accessibility-auditor
    task: WCAG 2.2 sweep across navigation, forms, content
  Agent: vercel:ai-architect
    task: scan for AI features — direct provider SDK use vs AI Gateway, deprecated model IDs
  MCP: mcp__claude_ai_Vercel__get_runtime_logs (last 7d, errors only)
  MCP: mcp__claude_ai_Vercel__get_deployment_build_logs (last 5 builds)

Stage 2 — Gap pass (sequential):
  Skill load: vercel:knowledge-update (ground truth as of 2026-02-27+)
  For each finding from Stage 1, check against ground truth:
    - Edge Functions used? → Fluid Compute migration
    - vercel.json without vercel.ts? → migrate to vercel.ts
    - Node 18 referenced? → Node 24 LTS
    - PPR without Cache Components? → migrate to Cache Components
    - @ai-sdk/anthropic direct vs AI Gateway? → AI Gateway routing
    - /admin/* without BotID? → wire BotID middleware
    - Dynamic routes without async params? → Next.js 16 fix
    - app/<name>.ts collision with app/<name>/page.tsx? → rename
  Produce: list of gap → fix recipe pairs

Stage 3 — Fix pass (parallel where independent):
  Agent: vercel:deployment-expert
    task: config-level fixes (vercel.json → vercel.ts, env vars, crons, Node version)
  Agent: frankx-website-builder (or frontend-design:frontend-design)
    task: component-level fixes (server/client boundary, async params, lucide imports)
  Agent: nextjs-expert
    task: App Router patterns (Cache Components, server actions, parallel routes)
  Each fix → atomic commit on a dedicated branch elevate/<repo>-<date>

Stage 4 — Ship pass (sequential):
  - Open PR with full fix bundle
  - Gate: pr-review-toolkit:code-reviewer must PASS or WARN+ack
  - Gate: Vercel Agent PR check (server-side) must not return FAILURE
  - Admin-merge past pre-existing CI debt (per standing pattern)
  - NEVER admin-merge past missing review or Agent FAILURE
  - Post-merge: verify URLs return 200, smoke-check runtime logs

Stage 5 — Teach pass (optional, default on):
  Write: docs/learning/<date>-<topic>.md
  Body: WHAT changed (3 bullets), WHY old pattern deprecated (1 paragraph),
        HOW new pattern works (code sample), WHEN to apply elsewhere (1 paragraph)
  Length: ≤ 200 words. Becomes a referenceable artifact in the FrankX OS knowledge base.

Cost target per ELEVATE run:
  - Anthropic API: $0.15-0.40 (depends on findings count)
  - Vercel costs: $0 during Agent beta + free MCP queries
  - Wall time: 5-15 minutes

Vercel MCP toolset reference

Available MCP tools, when to use each:

When to invoke other skills + commands

These already exist and should be referenced, not recreated. Use plugin-namespaced names (vercel:*) when calling vercel-plugin skills.

• nextjs-expert — deep Next.js knowledge, load when implementation depth needed
• nextjs-react-expert — React patterns inside Next.js
• vercel:nextjs — Vercel's official Next.js skill (App Router, Server Components, Cache Components)
• vercel:next-cache-components — Next.js 16 Cache Components + PPR (always load when discussing caching post-Nov 2025)
• vercel:react-best-practices — React optimization rules
• vercel:ai-sdk — AI SDK integration
• vercel:deployments-cicd — deployment + CI/CD playbook (always load for DEPLOY lane)
• vercel:knowledge-update — Vercel platform corrections (Fluid Compute, vercel.ts, Node 24 LTS, 300s default timeout). Already auto-injected at session start.
• vercel:verification — pre-ship verification gate
• v0-generate — UI prototyping via v0 MCP (command)
• frankx-ai-deploy — full deploy ceremony with quality checks (BUILD lane handoff for big features)
• nextjs-vercel-deployment agent — full-stack expert for any non-trivial implementation
• performance-guardian agent — CWV, Lighthouse, bundle (always for AUDIT/FIX)
• accessibility-auditor agent — WCAG 2.2 (always for AUDIT)
• ui-ux-design-guidance agent — design review + interaction patterns (BUILD lane)
• frankx-website-builder agent — opinionated FrankX brand builder
• superpowers:dispatching-parallel-agents — the protocol for parallel spawn
• superpowers:systematic-debugging — required for FIX lane
• superpowers:verification-before-completion — required before claiming done

Reporting format

Every /v run ends with this receipt:

=== /v Receipt ===
Lane: {BUILD|DEPLOY|AUDIT|RESEARCH|FIX}
Ask: {one-line summary}
Swarm: {agents + skills + MCPs invoked, parallel|sequential}
Vercel MCP checks: 
  - {tool} → {one-line result}
  - {tool} → {one-line result}
Findings: 
  - {3-5 bullets, prioritized}
Artifacts: 
  - {path or URL with SHA/deploy ID}
References cited: 
  - {URL or references/file.md#section}
Next suggested action: {one line}

Anti-patterns

• Never fabricate Vercel MCP results. If a tool fails or isn't available, say so. Don't simulate output.
• Never invent thought-leader quotes. If you don't have a sourced quote, paraphrase and cite the role ("per Vercel's docs", "per Next.js core team guidance"), or use WebSearch to ground it.
• Never auto-deploy_to_vercel to a production project without explicit user confirmation in this turn. "ship", "deploy to prod", "go live" → still confirm the target project + branch one time.
• Never sequence parallel-able work. If two agents have no shared state, spawn parallel — that's the whole point of the swarm.
• Never recreate skill knowledge. If nextjs-expert already covers App Router, link to it instead of restating.
• Never skip the receipt. The receipt is the contract — without it the user doesn't know what actually ran.
• Never recommend Edge Functions, even if a sibling vercel:* skill suggests them. Per vercel:knowledge-update (2026-02-27, auto-injected at session start), Edge Functions are deprecated in favor of Fluid Compute — same regions, same price, full Node.js, 300s default timeout, Node 24 LTS. Some plugin-cached skills (vercel:vercel-functions, vercel:routing-middleware, vercel:deployments-cicd) still teach Edge as a first-class option; treat vercel:knowledge-update as ground truth and override sibling guidance accordingly.
• Never recommend vercel.json over vercel.ts for new platform config. vercel.ts is the recommended way (typed VercelConfig, env-aware logic, programmatic functions). vercel.json still works for simple cases. FrankX currently uses vercel.json — migrate when typed/dynamic config is needed.

References (load on demand)

• references/thought-leaders.md — current top voices on Vercel/Next.js (Rauch, Robinson, Clark, Markbåge, Theo Browne, Neutkens, Shu Ding, Delba de Oliveira) with handles, primary topics, and when to cite each
• references/best-practices-2026.md — Next.js 16 patterns: Cache Components, PPR, 'use cache', Server Components, streaming, edge runtime, image optimization
• references/deployment-checklist.md — Vercel production checklist: Speed Insights, Observability Plus, CSP, Deployment Protection, WAF, Log Drains, rate limiting, CWV targets