diff --git a/.claude/AGENT-NAMING-GUIDE.md b/.claude/AGENT-NAMING-GUIDE.md new file mode 100644 index 0000000..548e170 --- /dev/null +++ b/.claude/AGENT-NAMING-GUIDE.md @@ -0,0 +1,83 @@ +# Agent Naming Guide + +This guide helps you choose the right agent when more than one agent shares the same name. Name collisions happen when an installed Claude Code plugin ships an agent whose name matches another plugin's agent — or a local agent in `.claude/agents/`. + +> **The `plugin/agent` references below are illustrative, not a claim about what is installed.** This template's own agents live in `.claude/agents/`; any additional agents come from whatever plugins you have installed (see `.claude/PLUGINS-REFERENCE.md` for the plugins this project documents). There is **no** local `code-reviewer` agent in this template. Verify what is actually available with `/plugin list` before assuming a specific `plugin/agent` exists. + +## Resolving "code-reviewer" (and similar) collisions + +If you have multiple plugins installed that each provide a similarly-named agent (for example, a `code-reviewer`), prefer the one most specific to your task. The common review situations are: + +### General development review +For bug detection, security smells, code smells, and best-practice checks during active development. Favor a fast, read-only reviewer. + +### Pull-request / merge review +For PR-specific analysis: cross-file impact, integration concerns, and merge readiness before shipping. Favor a comprehensive reviewer that can run tests and check dependencies. + +### Plan-alignment review +For verifying that an implementation matches an agreed plan or architecture: requirement traceability and completeness. Favor a reviewer that can read both the plan and the diff. + +**Quick rule:** match the agent to the moment — general coding vs. PR/merge vs. plan verification — and pick the most specific reviewer your installed plugins provide. + +## Quick Decision Tree + +``` +Need to review code? +│ +├─ Is there an implementation plan? ────> plan-alignment reviewer +│ +├─ Is this for a PR/merge? ────────────> PR / merge reviewer +│ +└─ General development review ─────────> general-purpose reviewer +``` + +## Other Name Collisions + +The same "prefer the most specific" principle applies whenever agents overlap: + +### Code simplifiers / refactorers +If more than one refactoring agent is available, use the one intended to run **after** a review — it refactors the flagged code while preserving behavior. + +### Test agents +This template ships a local **test-writer-fixer** (writes tests, runs them, fixes failures). If a plugin also provides a test-coverage analyzer, treat them as complementary: active fixing vs. passive analysis. + +### Frontend agents +This template ships a local **frontend-developer** (Wix section composition, `global.css`, Velo frontend code). If a plugin also provides a UI/UX design agent, design first, then implement. + +## Overlapping Local Agents (not collisions — role boundaries) + +Several of this template's own Wix agents sound interchangeable but have deliberate boundaries. Match the agent to the pipeline stage: + +### wix-site-builder vs figma-wix-converter (and the other converters) +- **figma-wix-converter / canva-wix-converter / indesign-to-wix** decide *what* the site should be: they extract tokens and structure from the design source and **compile a BuildPlan**. They never touch the Wix editor. +- **wix-site-builder** decides nothing: it **executes** the BuildPlan against a real site (API first, Playwright-driven editor automation as fallback). +- Rule of thumb: "convert this design" → a converter; "apply/build/resume" → wix-site-builder. + +### wix-site-builder vs visual-qa-agent +- **wix-site-builder** verifies each step as it executes (Layers tree + screenshots) — build-time evidence. +- **visual-qa-agent** compares the finished, **published** site against the source design — release-time evidence and FidelityReport input. +- If the site is live and the question is "does it match the design?", it's visual-qa-agent. + +### wix-structure-validator vs wix-token-auditor +- **wix-structure-validator** checks plan/page *structure*: step shape, phase ordering, headings, dangling references. +- **wix-token-auditor** checks *token compliance*: stray hex/px, `--vsp-*` resolution, palette compression, ramp overflow. +- They are complementary gates; converters run both. + +### frontend-developer vs ui-designer vs wix-app-developer +- **ui-designer** shapes the design system (token registry → ThemePlan) and section recipes. +- **frontend-developer** turns those into concrete BuildPlan steps and `global.css`/Velo frontend code. +- **wix-app-developer** owns backend/custom code: web modules, HTTP functions, data hooks, and reusable Wix CLI apps/Blocks. + +### wix-headless-developer vs everything else +- Headless is a different architecture: Wix as API backend, frontend owned elsewhere. If the deliverable is a Wix-rendered site, stay with the pipeline agents; if it's a Next.js/Astro app reading Wix data, it's wix-headless-developer. + +## When in Doubt + +1. Run `/plugin list` to see which plugins — and therefore which plugin agents — are actually installed. +2. Check the decision tree above. +3. Prefer the more specific agent for your task (e.g., a PR reviewer for PRs). +4. Ask Claude Code: "Which agent should I use for [task]?" + +--- + +**Last Updated:** 2026-07-06 diff --git a/.claude/CUSTOM-AGENTS-GUIDE.md b/.claude/CUSTOM-AGENTS-GUIDE.md new file mode 100644 index 0000000..dee1e9b --- /dev/null +++ b/.claude/CUSTOM-AGENTS-GUIDE.md @@ -0,0 +1,401 @@ +# Custom Agents Reference Guide + +**Last Updated:** 2026-07-06 +**Total Custom Agents:** 54 +**Location:** `.claude/agents/` + +This guide categorizes all custom agents by relevance to Vespasian's design-to-Wix pipeline. + +--- + +## Wix Site Building - Highly Relevant ✅ + +These agents directly support the design-in → live-Wix-site-out pipeline: + +### **wix-site-builder** (NEW) +- **Purpose:** Executes BuildPlans against a real Wix site +- **Use for:** Applying compiled plans — API steps via `packages/wix-driver`, editor steps by driving the Wix Studio editor through the Playwright MCP (screenshot-grounded), phase checkpoints and resume, CAPTCHA/2FA escalation +- **Wix relevance:** Critical - the execution engine of the entire pipeline +- **Backed by:** `packages/wix-driver/` and `vespasian apply` + +### **figma-wix-converter** +- **Purpose:** Autonomous Figma-to-Wix conversion +- **Use for:** Extracting design systems and page structure from Figma via the Figma MCP, translating tokens into a ThemePlan + `global.css`, compiling a BuildPlan +- **Wix relevance:** Critical - primary engine of the Figma pipeline +- **Backed by:** `scripts/figma-wix/` and the `figma-to-wix-autonomous-workflow` skill + +### **canva-wix-converter** +- **Purpose:** Convert Canva HTML/CSS exports into Wix sites +- **Use for:** Parsing design tokens from Canva CSS, mapping exported HTML to Wix Studio composition, compiling a BuildPlan +- **Wix relevance:** Critical - alternate design-source entry point +- **Backed by:** `scripts/canva-wix/` and the `canva-to-wix-autonomous-workflow` skill + +### **indesign-to-wix** +- **Purpose:** Convert an Adobe InDesign document (`.idml` or PDF) into a Wix site +- **Use for:** Orchestrating the `@vespasian/pipeline` InDesign stages (parse → map tokens → plan), reviewing the pipeline report, and proposing concrete follow-ups (unmapped frames, font fallbacks, alt text). Non-destructive — dry-runs first, targets dev sites +- **Wix relevance:** Critical - turns print/layout sources into live sites +- **Backed by:** `packages/pipeline/`, `bin/vespasian.mjs`, and `scripts/indesign-wix/` +- **Pairs with:** the `indesign-conversion` skill + +### **wix-structure-validator** +- **Purpose:** BuildPlan and published-page structure validation +- **Use for:** Validating plan JSON shape, phase ordering, token references, heading hierarchy, and published-DOM structure vs the plan +- **Wix relevance:** Critical - the gate between compilation and execution +- **Backed by:** `scripts/wix-structure-validator/validate-structure.sh` + +### **wix-token-auditor** +- **Purpose:** Design token compliance auditing +- **Use for:** Detecting stray hex/px values, validating `--vsp-*` references, palette-slot compression maps, ramp overflow (`.vsp-*`) tracking for the FidelityReport +- **Wix relevance:** High - enforces design system discipline across ThemePlan + global.css +- **Backed by:** `scripts/design-token-auditor/audit-tokens.sh` + +### **wix-environment-manager** +- **Purpose:** Manages the Vespasian-to-Wix connection +- **Use for:** WIX_* env verification, API key/reachability checks, target-site selection (`vespasian site create|use|list`), editor-session freshness, consent state, dry-run mode +- **Wix relevance:** Critical - eliminates connection friction (no Docker, no local server) +- **Backed by:** `scripts/wix-environment-manager/check-environment.sh` + +### **visual-qa-agent** +- **Purpose:** Visual regression testing, design comparison, and cross-browser verification +- **Use for:** Comparing the LIVE Wix site against Figma/Canva/InDesign source designs at the three Studio breakpoints across Chromium, Firefox, and WebKit; feeding the FidelityReport +- **Wix relevance:** Critical - the QA phase of every apply; its Playwright toolset doubles as the editor-automation verification loop +- **Requires:** Playwright MCP (`./scripts/setup-playwright.sh`) + Figma MCP + +### **asset-cataloger** +- **Purpose:** Image/asset semantic mapping and validation +- **Use for:** Viewing hash-named staged images, creating semantic mappings, recording Wix Media Manager IDs after upload, validating correct image usage in plan steps +- **Wix relevance:** Critical - prevents wrong-image-assignment errors; anchors media-first architecture + +### **accessibility-auditor** +- **Purpose:** WCAG 2.1 AA compliance auditing +- **Use for:** Color contrast (from ThemePlan slots), heading hierarchy, ARIA labels, alt text, keyboard navigation, Lighthouse audits against the published site +- **Wix relevance:** Critical - published sites must be accessible + +### **content-seeder** +- **Purpose:** Wix CMS content generation +- **Use for:** Creating CMS collections and items via the Data API (dry-run aware), populating Repeater/dynamic-page bindings, post-seed verification +- **Wix relevance:** High - fully populated sites for testing and demos + +### **security-audit-agent** +- **Purpose:** Dependency vulnerability scanning and security auditing +- **Use for:** pnpm/npm audits across the workspace, Wix credential-hygiene review (API keys, session state), Velo/HTTP-function code review, report generation, auto-creating issues for critical CVEs +- **Wix relevance:** Critical - account-level API keys and editor sessions are high-value targets + +### **seo-schema-agent** +- **Purpose:** SEO and structured data auditing +- **Use for:** Heading hierarchy, meta/OG tags (per-page SEO editor steps), Schema.org via custom embeds, robots/llms.txt via the seoFiles API, image SEO +- **Wix relevance:** High - routes every fix through the channel Wix actually offers + +### **deployment-agent** +- **Purpose:** Safe publishing of Wix sites +- **Use for:** Pre-publish validation gate, `vespasian publish` orchestration, structured logs, notifications, honest rollback handling (re-apply last-known-good plan; Wix has no revert API) +- **Wix relevance:** Critical - production-grade release discipline +- **Backed by:** `scripts/wix-deployment/` and `.claude/config/deployment/` + +### **wix-stores-agent** +- **Purpose:** Wix Stores e-commerce setup and catalog work +- **Use for:** Installing the Wix Stores app, importing products via the Stores/Catalog APIs, verifying shop/cart/checkout pages, shipping/tax/payment configuration, token-compliant store styling +- **Wix relevance:** Critical - turns a built site into a working store + +### **wix-app-developer** +- **Purpose:** Custom code on Wix sites and reusable Wix apps +- **Use for:** Velo page/backend code, wix-data hooks, HTTP functions, Secrets Manager discipline, Wix CLI apps / Blocks widgets for cross-site reuse +- **Wix relevance:** High - everything beyond stock elements and installed apps + +### **wix-headless-developer** +- **Purpose:** Wix Headless setup and decoupled-frontend integration +- **Use for:** OAuth client setup, Wix SDK wiring in Next.js/Astro frontends, CMS/commerce data fetching, debugging the frontend↔Wix seams +- **Wix relevance:** High - the decoupled alternative to Wix-rendered sites + +### **frontend-developer** +- **Purpose:** Wix frontend implementation +- **Use for:** Composing sections/elements as BuildPlan steps, Studio grid layouts across the three breakpoints, `global.css` extensions, Velo frontend code +- **Wix relevance:** High - turns designs into executable composition + +### **ui-designer** +- **Purpose:** Design systems and section composition for Wix +- **Use for:** Shaping the token registry → ThemePlan (palette slots, 9-slot ramp, `--vsp-space-*` scale), section recipes, Figma-to-Wix translation decisions +- **Wix relevance:** High - designs within what Wix can actually express + +### **test-writer-fixer** +- **Purpose:** Write tests, run them, fix failures +- **Use for:** `node --test` suites for `packages/pipeline` and `packages/wix-driver`, bats for shell scripts, Playwright checks — all dry-run, no real network calls +- **Wix relevance:** High - pipeline quality depends on test coverage + +### **performance-benchmarker** +- **Purpose:** Performance testing and profiling +- **Use for:** Lighthouse against the published site, image optimization before Media upload, embed/Velo/global.css cost analysis +- **Wix relevance:** Critical - performance of the published site is a key concern + +### **migration-specialist** +- **Purpose:** Safe incremental migrations onto and within Wix +- **Use for:** WordPress/other-CMS → Wix migrations, Classic Editor → Studio rebuilds, content imports into Wix CMS, Velo/Wix API updates +- **Wix relevance:** High - migrations are a primary adoption path + +### **backend-architect** +- **Purpose:** Backend architecture and APIs +- **Use for:** Velo backend design, HTTP functions, CMS collection modeling, external integrations +- **Wix relevance:** Moderate-High - adapted with Wix code surfaces + +### **ux-researcher** +- **Purpose:** User experience research and testing +- **Use for:** Site usability testing, conversion-flow optimization +- **Wix relevance:** High - built sites must be user-friendly + +--- + +## Wix Development - Moderately Relevant ⚠️ + +These agents can be useful but aren't Wix-specific: + +### **api-tester** +- **Purpose:** API testing and validation +- **Use for:** Testing Wix REST API integrations, HTTP functions, and webhook endpoints +- **Wix relevance:** Moderate - useful for custom integrations and headless builds + +### **test-results-analyzer** +- **Purpose:** Analyze test data and trends +- **Use for:** CI/CD test result analysis for pipeline releases +- **Wix relevance:** Moderate - complements test-writer-fixer + +### **docusaurus-expert** +- **Purpose:** Documentation site creation +- **Use for:** Pipeline documentation, developer guides +- **Wix relevance:** Moderate - if documenting complex setups + +### **workflow-optimizer** +- **Purpose:** Development process improvement +- **Use for:** Optimizing design-to-site workflows +- **Wix relevance:** Moderate - applicable to any development + +### **analytics-reporter** +- **Purpose:** Metrics and reporting +- **Use for:** Site performance metrics, usage analytics +- **Wix relevance:** Moderate - useful for site analytics + +--- + +## Generic/Cross-Domain Agents (27 total) + +These agents are domain-agnostic and useful across all project types. + +### Meta/Ops (7) +| Agent | Purpose | +|-------|---------| +| agent-expert | Creating and designing specialized Claude Code agents | +| command-expert | Creating Claude Code slash commands | +| studio-coach | Development coaching and mentoring | +| studio-producer | Project production and coordination | +| project-shipper | Getting projects to release | +| sprint-prioritizer | Sprint planning and prioritization | +| experiment-tracker | Tracking A/B tests and experiments | + +### Business (5) +| Agent | Purpose | +|-------|---------| +| brand-guardian | Brand consistency and guidelines | +| finance-tracker | Financial tracking and budgeting | +| legal-compliance-checker | Legal and compliance review | +| support-responder | Customer support responses | +| feedback-synthesizer | Synthesizing user feedback | + +### Marketing/Social (8) +| Agent | Purpose | +|-------|---------| +| content-creator | Content creation and copywriting | +| growth-hacker | Growth strategies and experiments | +| instagram-curator | Instagram content strategy | +| reddit-community-builder | Reddit community engagement | +| tiktok-strategist | TikTok content strategy | +| twitter-engager | Twitter/X engagement | +| visual-storyteller | Visual content and storytelling | +| trend-researcher | Trend research and analysis | + +### Engineering (4) +| Agent | Purpose | +|-------|---------| +| devops-automator | CI/CD, infrastructure automation | +| infrastructure-maintainer | Server and infrastructure maintenance | +| tool-evaluator | Evaluating development tools | +| joker | Tech humor and team morale | + +### Adapted for Wix (3) +| Agent | Purpose | Adaptation | +|-------|---------|------------| +| ai-engineer | AI/ML feature integration | Generic (no changes needed) | +| backend-architect | Backend architecture and APIs | Added Velo, HTTP functions, wix-data, Secrets Manager | +| migration-specialist | Platform migrations | Rewritten for CMS→Wix and Classic→Studio migrations | + +--- + +## Using Custom Agents + +Custom agents are invoked through Claude Code's Task tool: + +``` +User: "Can you help optimize the site's performance?" +Claude: [Uses Task tool with subagent_type="performance-benchmarker"] +``` + +Agents are automatically selected based on task context, or you can explicitly request: + +``` +User: "Use the wix-site-builder agent to apply this plan" +``` + +--- + +## How Agents Work with Vespasian Skills + +This template includes 10 custom skills that complement the agents. + +### Skills vs Agents + +| Type | Purpose | When Triggered | Example | +|------|---------|----------------|---------| +| **Skills** | Systematic workflows and best practices | Keyword detection in conversation | "convert this Figma design" triggers `figma-to-wix-autonomous-workflow` | +| **Agents** | Specialized task execution | Task tool invocation | wix-site-builder executes a BuildPlan | + +### Agent-Skill Integration + +**wix-site-builder agent** + skills: +- Works with `wix-playwright-driver` for editor-automation patterns (session, consent, probe, recovery) +- Works with `wix-media-first-architecture` for asset handling (upload via API first, reference from the editor) +- Works with `wix-cli-workflows` for Wix CLI + REST recipes + +**Converter agents** (figma/canva/indesign) + skills: +- Execute their paired pipeline skills' autonomous phases +- Work with `wix-site-development` for composition reference +- Work with `visual-qa-verification` for post-apply checks + +**test-writer-fixer agent** + skills: +- Works with `vespasian-testing-workflows` for `node --test`/bats/dry-run setup +- Works with `vespasian-hook-integration` for agent-hook wiring + +### Complete Vespasian Development Stack + +``` +Vespasian Skills (10) + ↓ Provide workflows and best practices +Agents (54) + ↓ Execute specialized tasks +Plugins (6) + ↓ Provide tooling and memory +Automation Scripts + ↓ Run structure/token/security checks +``` + +**Skills Documentation:** See `.claude/skills/README.md` for complete catalog + +--- + +## Current Architecture Status + +**Plugins:** ✅ Already optimized (5 user + 1 local) +**Custom Agents:** 54 total (27 Wix-focused + 27 generic cross-domain) + +--- + +## Quick Reference: When to Use Which Agent + +| Task | Agent | Alternative | +|------|-------|-------------| +| **Apply a BuildPlan to Wix** | **wix-site-builder** | - | +| **Convert a Figma design** | **figma-wix-converter** | ui-designer (design decisions first) | +| **Convert a Canva export** | **canva-wix-converter** | - | +| **Convert an InDesign doc** | **indesign-to-wix** | - | +| **Validate a plan / structure** | **wix-structure-validator** | wix-token-auditor | +| **Token compliance** | **wix-token-auditor** | wix-structure-validator | +| **Check env / auth / session** | **wix-environment-manager** | - | +| **Compare live site vs design** | **visual-qa-agent** | - | +| **Identify/map images** | **asset-cataloger** | - | +| **Seed CMS content** | **content-seeder** | wix-site-builder (Data phase) | +| **Accessibility audit** | **accessibility-auditor** | - | +| **SEO audit** | **seo-schema-agent** | - | +| **Publish / release** | **deployment-agent** | - | +| **Set up a store** | **wix-stores-agent** | - | +| **Custom code (Velo/apps)** | **wix-app-developer** | frontend-developer (page composition) | +| **Headless frontend** | **wix-headless-developer** | backend-architect (integration design) | +| Build a section/composition | frontend-developer | ui-designer (design first) | +| Site performance | performance-benchmarker | analytics-reporter (metrics) | +| Write pipeline tests | test-writer-fixer | - | +| Design the token system | ui-designer | ux-researcher (research first) | +| Test APIs/webhooks | api-tester | - | +| Security/dependency audit | security-audit-agent | legal-compliance-checker | +| Migrate a site to Wix | migration-specialist | - | +| Create an agent | agent-expert | command-expert (for commands) | +| Backend API design | backend-architect | wix-app-developer (Wix-specific) | +| CI/CD automation | devops-automator | infrastructure-maintainer | +| Brand consistency | brand-guardian | content-creator | +| Social media content | content-creator | platform-specific agents | +| AI/ML features | ai-engineer | - | +| Sprint planning | sprint-prioritizer | project-shipper | + +--- + +## Design-to-Wix Conversion Pipeline + +The core agents form an automated quality pipeline for design-to-Wix conversions: + +``` +Design source (Figma / Canva / InDesign) + ↓ +figma-wix-converter / canva-wix-converter / indesign-to-wix + (extract tokens + structure → ThemePlan + global.css → BuildPlan) + ↓ +asset-cataloger (maps images semantically; tracks Media Manager IDs) + ↓ +wix-structure-validator (validates the BuildPlan) + ↓ +wix-token-auditor (ensures 100% token usage) + ↓ +wix-environment-manager (verifies API key, site, editor session) + ↓ +wix-site-builder (executes: provision → media → data → editor → code → + properties → publish) + ↓ (content-seeder assists the Data phase) +visual-qa-agent (live site vs design at 3 Studio breakpoints → FidelityReport) + ↓ +accessibility-auditor (WCAG compliance on the published site) + ↓ +seo-schema-agent (SEO best practices) + ↓ +deployment-agent (gated production publish) +``` + +--- + +## Agent Hook Configurations + +Agents with automated hooks: + +### Shared Quality Hooks (shared scripts) +These scripts are shared across multiple agents: +- `scripts/wix-structure-validator/validate-structure.sh` — Used by: wix-structure-validator, figma-wix-converter, canva-wix-converter, indesign-to-wix, seo-schema-agent, frontend-developer +- `scripts/design-token-auditor/audit-tokens.sh` — Used by: wix-token-auditor, ui-designer, figma-wix-converter, canva-wix-converter, indesign-to-wix, frontend-developer, performance-benchmarker +- `scripts/wix-environment-manager/check-environment.sh` — Used by: wix-environment-manager, wix-site-builder (SubagentStart preflight) + +### Output Protection Hooks +- `scripts/shared/validate-output-location.sh` — Keeps artifacts in `.vespasian/`, `.claude/`, and `packages/` (applied to the converter agents, validators, frontend-developer, ui-designer, asset-cataloger, seo-schema-agent, test-writer-fixer) + +### Per-Agent Hooks +| Agent | Hook Type | Script | Purpose | +|-------|-----------|--------|---------| +| wix-structure-validator | PostToolUse | validate-structure.sh | Plan shape, ordering, token references | +| wix-token-auditor | PostToolUse | audit-tokens.sh | Hardcoded value detection | +| content-seeder | Stop | verify-pages.sh | Seeded-content verification | +| wix-environment-manager | SubagentStart | check-environment.sh | Env/API/session status check | +| wix-site-builder | SubagentStart | check-environment.sh | Preflight before any build work | +| figma-wix-converter | PostToolUse (mcp__figma.*) | log-figma-access.sh | Figma access audit trail | +| figma-wix-converter | Stop | generate-comparison-report.sh | Attribute comparison report | +| canva-wix-converter | Stop | generate-comparison-report.sh | Conversion comparison report | + +### Research/Audit-Only Agents (no hooks needed) +These agents are research/audit-only and don't need automated hooks: +- accessibility-auditor (runs Lighthouse on demand) +- visual-qa-agent (captures screenshots on demand) +- ux-researcher (research only) + +--- + +**Architecture Assessment:** 54 custom agents provide comprehensive development coverage — 27 Wix-focused agents for design-source conversion (Figma/Canva/InDesign), plan execution, visual QA, asset management, environment management, structure validation, accessibility, token compliance, content seeding, SEO, security, publishing, e-commerce, custom code, and headless integration, plus 27 generic cross-domain agents for business, marketing, engineering, and meta/ops tasks. diff --git a/.claude/PLUGINS-REFERENCE.md b/.claude/PLUGINS-REFERENCE.md new file mode 100644 index 0000000..a12206d --- /dev/null +++ b/.claude/PLUGINS-REFERENCE.md @@ -0,0 +1,135 @@ +# Claude Code Plugins Quick Reference + +**Installed Plugins:** 4 user plugins + 1 local plugin +**Status:** Lean, Wix-pipeline-optimized configuration + +## Currently Installed Plugins + +**User Plugins (4):** +- `episodic-memory` - Conversation search and persistent memory (**load-bearing**: the conversion skills checkpoint through it) +- `commit-commands` - Git workflow automation +- `github` - GitHub integration +- `superpowers` - Advanced development workflows (**load-bearing**: the conversion skills plan/execute through `superpowers:writing-plans` / `superpowers:executing-plans`) + +**Local Plugins (1):** +- `ai-taskmaster` - Task management and planning + +**Removed in the Wix fork:** +- `php-lsp` - PHP language server. Vespasian contains no PHP; the plugin is dead weight and should be uninstalled (`/plugin uninstall php-lsp`). Optional replacement if you want richer code intelligence in `packages/gui` (TypeScript): a `typescript-lsp` plugin — not installed by default because the workspace is mostly plain ESM JavaScript and `node --check`/ESLint cover it. + +--- + +## episodic-memory Plugin + +### Purpose +Persistent memory across sessions — and the checkpoint store for long autonomous conversions. + +### Vespasian Use Cases +- **Conversion checkpoints (critical):** the figma/canva workflow skills save a checkpoint every 3 pages (`/episodic-memory:save "Figma-to-Wix checkpoint: {slug}, {X} of {N} pages"`) so a multi-hour conversion survives interruption. Resumption searches for the checkpoint and jumps straight back into the page loop; apply-phase interruptions resume via the executor's own `.vespasian/checkpoints/` instead. +- Recalling past design decisions: "how did we map that client's palette last time?" + +### Common Commands +``` +/episodic-memory:save "..." # save a memory/checkpoint +/episodic-memory:search "..." # find past checkpoints/decisions +``` + +**Do not uninstall** — the autonomous workflows depend on it. + +--- + +## superpowers Plugin + +### Purpose +Structured planning and uninterrupted plan execution. + +### Vespasian Use Cases +- `superpowers:writing-plans` — Phase 1 of every conversion: the implementation plan the user approves. +- `superpowers:executing-plans` — Phase 2: autonomous execution with no "should I continue?" prompts, through token extraction, artifact emission, `vespasian plan`, dry-run, and apply. + +**Do not uninstall** — the autonomous workflows depend on it. + +--- + +## github Plugin + +### Purpose +GitHub integration for version control, pull requests, and issue management. + +### Authentication Setup +**Required:** GitHub Personal Access Token (PAT) + +1. Go to: https://github.com/settings/tokens/new +2. Select scopes: `repo`, `workflow` +3. Generate the token and configure it in Claude Code when prompted + +### Common Commands +```bash +gh repo view # repository info +gh pr create --title "feat: compile CMS collections into the data phase" \ + --body "Adds wix-data collection steps to the BuildPlan compiler" +gh pr list +gh issue create --title "429 backoff too aggressive on media polling" +gh auth status +``` + +### Vespasian Workflow Example +```bash +git checkout -b feat/media-file-ready-poll +# ... edit packages/wix-driver/src/rest/media.js + tests ... +pnpm --filter @vespasian/wix-driver test +/commit +/commit-push-pr # PR with test plan; CI runs the dry-run plan gate +``` + +--- + +## commit-commands Plugin + +### Purpose +Structured git commits and PR automation. + +### Common Commands +``` +/commit # conventional, structured commit (release-please reads these) +/commit-push-pr # commit + push + PR in one flow +/clean_gone # prune branches whose remotes are gone +``` + +### Notes for This Repo +- Conventional commits are required — release-please derives versions from them. **Never hand-bump versions.** +- The inline PostToolUse hooks fire around commits: pre-commit-guard (token discipline in translate output) and the plan-size bundle-guard. +- Never commit `.env`, `.vespasian/` state (session cookies live there), or real `*.yml` deployment configs. + +--- + +## ai-taskmaster Plugin (local) + +### Purpose +Task management and planning for multi-step work. + +### Vespasian Use Cases +- Tracking multi-page conversion progress at the task level +- Sequencing pipeline work: parse → tokens → plan → apply → QA + +--- + +## Plugin Management + +``` +/plugin list # list installed plugins +/plugin install # install +/plugin uninstall # uninstall (do this for php-lsp if still present) +``` + +## MCP Servers (related, configured in .mcp.json — not plugins) + +| Server | Role | +|---|---| +| `figma-desktop` / `figma` | Design ingestion (tokens, structure, baselines) | +| `playwright` | QA screenshots + the consent-gated Wix editor automation plane | +| Wix MCP (optional, not configured by default) | Wix ships an official remote MCP (mcp.wix.com) exposing API operations; see `.claude/SETUP-COMPLETE.md` for how to add it | + +--- + +**Last Updated:** 2026-07-06 diff --git a/.claude/SETUP-COMPLETE.md b/.claude/SETUP-COMPLETE.md new file mode 100644 index 0000000..c6dda03 --- /dev/null +++ b/.claude/SETUP-COMPLETE.md @@ -0,0 +1,120 @@ +# Vespasian Setup: Post-Install Checklist + +Work through this after cloning the repo and running `pnpm install`. When every box is checked you can convert a design into a live Wix Studio site. + +--- + +## 1. Toolchain + +- [ ] Node.js ≥ 20 (`node --version`) +- [ ] pnpm 9.x (`pnpm --version`) +- [ ] Workspace installed: `pnpm install` +- [ ] Shell-test libraries fetched: `git submodule update --init` (vendored bats under `tests/libs/`) +- [ ] CLI answers: `node bin/vespasian.mjs --help` +- [ ] Optional: the official Wix CLI for the code channel (`npm i -g @wix/cli`) + +No Docker, no PHP, no composer, no WP-CLI — those belonged to the WordPress ancestor (Flavian). + +## 2. Wix Account & Credentials + +- [ ] A Wix account with a **Studio workspace** (Studio is the only supported editor flavor in v1) +- [ ] An **account-level API key** from [manage.wix.com/account/api-keys](https://manage.wix.com/account/api-keys) +- [ ] `.env` created (never committed) with: + +```bash +WIX_API_KEY=... # required +WIX_ACCOUNT_ID=... # required +# WIX_SITE_ID=... # optional; written by `vespasian site create|use` +# WIX_METASITE_ID=... # optional; cached for dashboard/editor URLs +``` + +- [ ] Environment sanity check: `./scripts/wix-environment-manager/check-environment.sh` (env vars + API reachability + editor-session freshness) + +## 3. Editor Automation (optional, consent-gated) + +Only needed for editor-channel operations (pages, theme panels, canvas composition, font upload, per-page SEO). Skip if you are only rehearsing with dry-run. + +- [ ] Preferably a dedicated **Wix-native email/password login** (not Google SSO) with access to the target sites +- [ ] Run the one-time headed login and accept the consent prompt: + +```bash +vespasian login --editor +``` + +- [ ] Session saved at `.vespasian/session/state.json` (gitignored — never commit it) +- [ ] Understand the posture: editor automation is a Wix ToS gray area; it runs headed at human pace on your own account, CAPTCHAs/2FA always escalate to you, and session expiry is a designed pause. Details: `.claude/skills/wix-playwright-driver/SKILL.md` + +Optional env knobs: `WIX_EDITOR_STORAGE_STATE`, `WIX_EDITOR_HEADLESS`, `WIX_EDITOR_SLOWMO_MS` (`WIX_EDITOR_TOTP_SECRET` is reserved — TOTP re-auth is not implemented in v0.1). + +## 4. MCP Servers + +`.mcp.json` ships three servers — enable them in your local settings (`enabledMcpjsonServers` in `.claude/settings.local.json`): + +- [ ] `figma-desktop` (needs the Figma desktop app with Dev Mode) or `figma` (remote fallback) +- [ ] `playwright` — QA screenshots and the editor plane. For editor work, launch it with the saved session and headed: `npx @playwright/mcp@latest --storage-state .vespasian/session/state.json` + +**Optional — official Wix MCP:** Wix operates a remote MCP server (`https://mcp.wix.com`) exposing API operations. It is deliberately NOT in `.mcp.json` (Vespasian's REST client covers the same surface deterministically), but you can add it yourself: + +```json +"wix": { "type": "http", "url": "https://mcp.wix.com/mcp", "description": "Official Wix MCP (optional)" } +``` + +Remember to also add `"wix"` to `enabledMcpjsonServers`, or it silently stays disabled. + +## 5. First Pipeline Run (dry-run — no Wix account touched) + +- [ ] Rehearse apply against the bundled example plan: + +```bash +VESPASIAN_DRY_RUN=1 vespasian apply .claude/templates/pipeline/example-buildplan.json --dry-run +``` + +- [ ] Run an InDesign fixture end-to-end (parse → tokens → plan): + +```bash +node scripts/indesign-wix/smoke-test.mjs +``` + +- [ ] Test suites green: + +```bash +pnpm -r test +./tests/libs/bats-core/bin/bats tests/unit/ # needs the §1 submodule step +``` + +## 6. First Real Site (optional) + +```bash +vespasian site create "My First Site" # asserts Studio editor, caches WIX_SITE_ID +vespasian pipeline indesign ./brochure.idml --slug brochure +vespasian apply .vespasian/plans/brochure/plan.json --dry-run # always rehearse first +vespasian apply .vespasian/plans/brochure/plan.json +vespasian publish +vespasian qa # published-site screenshots (+ --expect theme-var checks) +``` + +The pipeline prints the exact apply path in its `next:` hint — copy it from there if you changed +`--slug`/`--plan`. The FidelityReport is written by `vespasian apply`. + +Figma/Canva conversions run through Claude Code conversationally — "Convert this Figma design to a Wix site" — see `.claude/skills/figma-to-wix-autonomous-workflow/`. + +## 7. Guardrails Active After Setup + +| Guardrail | Where | +|---|---| +| Blocks writes to WordPress-era dirs (`themes/`, `wp-content/`, ...) | `.claude/hooks/validate-output-location.sh` (PreToolUse) | +| Token-discipline + plan-size + QA reminders | 6 inline hooks in `.claude/settings.json` | +| Output-structure CI check | `.claude/validation/enforce-output-structure.sh` | +| Agent/skill config validation | `./scripts/validate-agent-configs.sh` | +| Deployment publish gates | `.claude/config/deployment/*.yml` (copy from `*.example.yml`) | + +## 8. Inventory + +- **Plugins:** 5 (episodic-memory, superpowers, github, commit-commands, ai-taskmaster) — `.claude/PLUGINS-REFERENCE.md`. If `php-lsp` is still installed from the WordPress era, uninstall it. +- **Skills:** 10 — `.claude/skills/README.md` +- **Commands:** 2 (`/lint`, `/test`) — `.claude/commands/` +- **Agents:** see `.claude/CUSTOM-AGENTS-GUIDE.md` for the current catalog (key Wix agents: figma-wix-converter, canva-wix-converter, indesign-to-wix, wix-site-builder, visual-qa-agent) + +--- + +**You are set up when:** `check-environment.sh` passes, the dry-run apply succeeds, and (if you need editor automation) `vespasian login --editor` has a fresh consented session. diff --git a/.claude/agents/accessibility-auditor.md b/.claude/agents/accessibility-auditor.md new file mode 100644 index 0000000..866d7ad --- /dev/null +++ b/.claude/agents/accessibility-auditor.md @@ -0,0 +1,215 @@ +--- +name: accessibility-auditor +description: WCAG 2.1 AA compliance auditor for published Wix sites. Runs Lighthouse accessibility audits against the live site, checks color contrast from the ThemePlan, heading hierarchy, ARIA labels, alt text, and keyboard navigation. +tools: Read, Write, Bash, Grep, Glob, TodoWrite, TaskOutput, AskUserQuestion, mcp__playwright__browser_navigate, mcp__playwright__browser_take_screenshot, mcp__playwright__browser_snapshot, mcp__playwright__browser_evaluate, mcp__playwright__browser_resize, mcp__playwright__browser_press_key, mcp__playwright__browser_tabs +model: opus +permissionMode: bypassPermissions +--- + +You are a WCAG 2.1 AA accessibility compliance specialist for Wix sites built by the Vespasian pipeline. You audit the published site (and the plan artifacts behind it) for accessibility violations using both automated tools and manual review. + +## Primary Responsibilities + +### 1. Automated Accessibility Audit (Lighthouse) + +Run Lighthouse accessibility audits on every published page: + +``` +For each page URL on the published site: +1. Navigate to page via Playwright MCP (browser_navigate) +2. Run Lighthouse via lhci — `pnpm lighthouse:run` (configured in lighthouserc.json, pointed at the published URL) — and read the accessibility category +3. Capture score and individual audit results +4. Record failures with element selectors +``` + +**Target score:** 95+ on every page + +### 2. Color Contrast Validation + +**Extract the ThemePlan palette slots and `global.css` `--vsp-*` color variables and check all combinations:** +- Text color on background color: Must meet WCAG AA (4.5:1 for normal text, 3:1 for large text) +- Button text on button background +- Link color on background +- Heading color on background + +**Check combinations used by actual plan steps, then verify computed styles on the rendered page:** +``` +For each section: + - Which palette slot / --vsp-* variable styles the text? + - Which styles the background? + - Calculate contrast ratio (browser_evaluate for computed values on the live page) + - Flag if below 4.5:1 (normal text) or 3:1 (large text >=18px or >=14px bold) +``` + +**Common contrast issues on Wix builds:** +- Light gray text on white backgrounds +- White text on light-colored section overlays +- Palette compression pushing two distinct source colors onto one low-contrast slot +- Placeholder text contrast in forms +- Disabled button contrast + +### 3. Heading Hierarchy Audit + +**Per-page heading structure:** +``` +Page: front-page + h1: "Ancient Baltimore Lodge 234" (hero) + h2: "What is Masonry" (section) + h2: "Support our building fund" (CTA) + h2: "Our gatherings" (gallery) + h2: "Upcoming events" (events) +``` + +**Rules:** +- Exactly one h1 per page +- No skipped levels (h1 → h3 without h2) +- Headings in logical order +- Site header/footer heading levels don't conflict with page content +- Navigation should NOT use heading elements for menu items +- Wix theme text styles (H1–H6) control BOTH the semantic tag and the look — verify the rendered tag, not just the visual size + +### 4. Image Alt Text Audit + +**Scan the BuildPlan's image-placement steps and the rendered pages for alt text:** +- Every image element must have an `alt` attribute in the rendered DOM +- Alt text must be descriptive (not "image", "photo", "img_123") +- Decorative images should use `alt=""` (explicitly marked decorative in the plan) +- Section background media: check for alternative text content within the section + +**Report:** +```markdown +| Page | Image (media name/ID) | Alt Text | Status | +|------|----------------------|----------|--------| +| home | members-group-photo | "Members gathered together" | PASS | +| home | building.png | "image" | FAIL - too generic | +| gallery | event1.png | "" | WARN - empty, is it decorative? | +``` + +### 5. Keyboard Navigation Audit + +**Test via Playwright MCP:** +- Tab through the entire page +- Verify all interactive elements are reachable +- Check focus indicators are visible +- Verify skip-to-content link exists +- Test dropdown/mobile menu keyboard access +- Verify modal/dialog focus trapping (if any) + +**Wix-specific keyboard issues:** +- Menu element keyboard accessibility (including the mobile hamburger menu) +- Button focus styles surviving theme overrides in `global.css` +- Link focus visibility on dark backgrounds +- Form field focus indicators (Wix Forms elements) +- Lightbox/popup focus trapping and Escape-to-close + +### 6. ARIA & Semantic HTML Audit + +**Check the rendered pages (browser_snapshot / browser_evaluate) for:** + +**Landmark roles:** +- `
` or `role="banner"` present +- `