From 19111d0cf872b6226ba8dd3008e566ce6bf3e77a Mon Sep 17 00:00:00 2001 From: PAMulligan Date: Sun, 28 Jun 2026 21:04:46 -0400 Subject: [PATCH] docs: align documentation with actual framework behavior Audit all project docs against the real scripts, package.json, docker-compose.yml, .mcp.json and the packages/ monorepo, and bring them into line with reality: - Versioning: package.json is release-please-managed (1.12.0), not pinned to 0.0.0 - MCP: repoint chrome-devtools references to the configured Playwright MCP + lhci - Onboarding: add the required `cp .env.example .env` step; fix admin/changeme login; list pnpm as a prerequisite; bump documented Node minimum to 20 (matches engines) - Catalogs: unify agent count to 53, skills to 12, plugins to 6; add 3 missing agents - Document the flavian CLI, init wizard, @flavian/pipeline and @flavian/gui in CLAUDE.md - Reframe the stale "code-reviewer" naming-conflict guidance as conditional - Correct "automatic" validation hooks to manual/agent-run; fix paths, links and counts - Remove two outdated 2026-01-23 documentation-reorg planning docs Co-Authored-By: Claude Opus 4.8 (1M context) --- .claude/AGENT-NAMING-GUIDE.md | 143 ++---- .claude/CUSTOM-AGENTS-GUIDE.md | 34 +- .claude/PLUGINS-REFERENCE.md | 8 +- .claude/SETUP-COMPLETE.md | 40 +- .claude/agents/accessibility-auditor.md | 10 +- .claude/agents/seo-schema-agent.md | 4 +- .claude/agents/visual-qa-agent.md | 16 +- .claude/skills/README.md | 32 +- .../canva-to-fse-autonomous-workflow/SKILL.md | 4 +- .../IMPLEMENTATION-GUIDE.md | 12 +- .../figma-to-fse-autonomous-workflow/SKILL.md | 16 +- .../fse-pattern-first-architecture/skill.md | 6 +- .claude/skills/indesign-conversion/SKILL.md | 2 +- .../skills/visual-qa-verification/SKILL.md | 12 +- .../wordpress-hook-integration/SKILL.md | 2 +- .claude/templates/plugin/README.md | 1 + CLAUDE.md | 52 +- CONTRIBUTING.md | 15 +- DOCUMENTATION-AUDIT.md | 447 ------------------ DOCUMENTATION-REORGANIZATION-COMPLETE.md | 328 ------------- LOCAL-DEVELOPMENT.md | 20 +- README.md | 7 +- docs/CLI-WIZARD.md | 6 +- docs/COMMON-FAILURES-FIXES.md | 12 +- docs/COMMON-FAILURES-FIXES.validation.md | 4 +- docs/E2E-VALIDATION.md | 10 +- docs/MCP-TROUBLESHOOTING.md | 8 +- docs/PREREQUISITES.md | 36 +- docs/PREREQUISITES.validation.md | 6 +- docs/QUICK-START.md | 8 +- docs/QUICK-START.validation.md | 11 +- docs/RELEASING.md | 17 +- docs/TROUBLESHOOTING.md | 43 +- .../PATTERN-FIRST-ARCHITECTURE.md | 4 +- docs/docker-troubleshooting.md | 10 +- docs/figma-to-wordpress/README.md | 10 +- docs/headless-wordpress/README.md | 11 +- docs/mcp-setup.md | 18 +- docs/multisite/README.md | 9 +- docs/pipeline/indesign-output-generator.md | 5 +- docs/pipeline/indesign-token-mapper.md | 2 +- docs/pipelines/indesign.md | 2 +- scripts/README.md | 2 +- scripts/check-prerequisites.sh | 2 +- 44 files changed, 359 insertions(+), 1088 deletions(-) delete mode 100644 DOCUMENTATION-AUDIT.md delete mode 100644 DOCUMENTATION-REORGANIZATION-COMPLETE.md diff --git a/.claude/AGENT-NAMING-GUIDE.md b/.claude/AGENT-NAMING-GUIDE.md index ac7b427..c123ce5 100644 --- a/.claude/AGENT-NAMING-GUIDE.md +++ b/.claude/AGENT-NAMING-GUIDE.md @@ -1,145 +1,56 @@ # Agent Naming Guide -This guide clarifies naming conflicts and helps you choose the right agent for your task. +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/`. -## Code Reviewer Variants +> **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. -There are **three agents** named "code-reviewer" with different purposes. Use this guide to select the correct one: +## Resolving "code-reviewer" (and similar) collisions -### 1. feature-dev/code-reviewer -**When to use:** General code quality review during active development +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: -**Focus:** -- Bug detection -- Security vulnerabilities -- Code smells and anti-patterns -- Best practices compliance +### General development review +For bug detection, security smells, code smells, and best-practice checks during active development. Favor a fast, read-only reviewer. -**Model:** Sonnet (faster reviews) +### 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. -**Tools:** Read-only (Glob, Grep, Read) +### 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. -**Confidence:** Reports issues ≥80% confidence - -**Example scenarios:** -- "Review this function for bugs" -- "Check if this code is secure" -- "Is this following best practices?" - ---- - -### 2. pr-review-toolkit/code-reviewer -**When to use:** Pull request reviews before merging - -**Focus:** -- PR-specific analysis -- Cross-file impact assessment -- Merge readiness -- Integration concerns - -**Model:** Opus (comprehensive reviews) - -**Tools:** Full access (can run tests, check dependencies) - -**Confidence:** Reports issues ≥80% confidence - -**Example scenarios:** -- "Review this PR for merge" -- "What's the impact of these changes?" -- "Is this PR ready to ship?" - ---- - -### 3. superpowers/code-reviewer -**When to use:** Verifying implementation matches the plan - -**Focus:** -- Plan alignment verification -- Architectural decision validation -- Implementation completeness -- Requirement traceability - -**Model:** Inherits from parent (flexible) - -**Tools:** Full access - -**Example scenarios:** -- "Does this implementation match our plan?" -- "Did we follow the architecture we agreed on?" -- "Are all planned features implemented?" - ---- +**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? ────> superpowers/code-reviewer +├─ Is there an implementation plan? ────> plan-alignment reviewer │ -├─ Is this for a PR/merge? ────────────> pr-review-toolkit/code-reviewer +├─ Is this for a PR/merge? ────────────> PR / merge reviewer │ -└─ General development review ─────────> feature-dev/code-reviewer +└─ General development review ─────────> general-purpose reviewer ``` ---- - -## Code Simplifier Location - -**Previously:** Had both standalone `code-simplifier` plugin AND `pr-review-toolkit/code-simplifier` agent (duplicate) +## Other Name Collisions -**Now:** Only `pr-review-toolkit/code-simplifier` remains (standalone plugin removed) +The same "prefer the most specific" principle applies whenever agents overlap: -**When to use:** After code review suggests simplification, invoke this agent to refactor complex code while preserving functionality. - ---- +### 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. -## Other Naming Clarifications - -### Test Agents -- **test-writer-fixer** (custom): Writes tests, runs them, fixes failures -- **pr-test-analyzer** (pr-review-toolkit): Analyzes test coverage in PRs -- **Use both:** They're complementary (active vs. passive testing) - -### Frontend Agents -- **frontend-developer** (custom): Full-stack frontend implementation -- **frontend-design** (plugin): UI/UX design and prototyping -- **Use both:** Design first, then implement - ---- +### 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. -## WordPress FSE Development Stack - -For WordPress block theme development, your core agents are: - -**Code Quality:** -- feature-dev/code-reviewer (development reviews) -- pr-review-toolkit/code-reviewer (PR reviews) - -**Development:** -- frontend-developer (JS/CSS implementation) -- test-writer-fixer (PHP unit tests) - -**Performance:** -- performance-benchmarker (optimization) - -**Design:** -- ui-designer (block patterns, theme design) -- ux-researcher (usability testing) - -**Infrastructure:** -- php-lsp (code intelligence) -- security-guidance (WordPress security) - ---- +### Frontend agents +This template ships a local **frontend-developer** (full-stack FSE implementation). If a plugin also provides a UI/UX design agent, design first, then implement. ## When in Doubt -If you're unsure which agent to use: -1. Check this guide's decision tree -2. Use the more specific agent (e.g., pr-review-toolkit for PRs) -3. Ask Claude Code: "Which code-reviewer should I use for [task]?" +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-01-18 +**Last Updated:** 2026-06-28 diff --git a/.claude/CUSTOM-AGENTS-GUIDE.md b/.claude/CUSTOM-AGENTS-GUIDE.md index 2b12817..249cba5 100644 --- a/.claude/CUSTOM-AGENTS-GUIDE.md +++ b/.claude/CUSTOM-AGENTS-GUIDE.md @@ -100,6 +100,24 @@ These agents directly support WordPress block theme development: - **WordPress relevance:** Critical - turns the scaffold into an e-commerce-ready store - **Backed by:** `themes/flavian-shop/` and `scripts/wordpress-install/setup-woocommerce.sh` +### **headless-developer** (NEW) +- **Purpose:** Headless WordPress setup and decoupled-frontend integration +- **Use for:** Installing/configuring WPGraphQL, wiring CORS and preview links via the `flavian-headless` mu-plugin, scaffolding Next.js frontends, troubleshooting GraphQL/REST endpoints +- **WordPress relevance:** High - turns the scaffold into a headless content API for decoupled frontends +- **Backed by:** `scripts/wordpress-install/setup-headless.sh` and `scripts/scaffold-frontend.sh` + +### **figma-fse-converter** (NEW) +- **Purpose:** Autonomous Figma-to-WordPress FSE theme conversion +- **Use for:** Extracting design systems from Figma, generating theme.json, creating pixel-perfect FSE templates with WordPress blocks +- **WordPress relevance:** Critical - primary engine of the Figma-to-FSE conversion pipeline +- **Backed by:** `scripts/figma-fse/` and the `figma-to-fse-autonomous-workflow` skill + +### **canva-fse-converter** (NEW) +- **Purpose:** Convert Canva HTML/CSS exports into WordPress FSE block themes +- **Use for:** Parsing design tokens from Canva CSS, converting HTML elements to WordPress blocks, generating theme.json and templates +- **WordPress relevance:** Critical - alternate design-source entry point to the FSE pipeline +- **Backed by:** `scripts/canva-fse/` and the `canva-to-fse-autonomous-workflow` skill + ### **indesign-to-wordpress** (NEW) - **Purpose:** Convert an Adobe InDesign document (`.idml` or PDF) into a WordPress FSE block theme - **Use for:** Orchestrating the `@flavian/pipeline` InDesign stages (parse → map design tokens → generate patterns/templates/parts/theme.json), reviewing the generation report, and proposing concrete follow-ups (unmapped frames, font fallbacks, alt text). Non-destructive — works on a feature branch, never on `main` @@ -140,7 +158,7 @@ These agents can be useful but aren't WordPress-specific: --- -## Generic/Cross-Domain Agents (25 total) +## Generic/Cross-Domain Agents (27 total) These agents are domain-agnostic and useful across all project types. Backported from the Coding Framework project. @@ -212,7 +230,7 @@ User: "Use the frontend-developer agent to help me build this block pattern" ## How Agents Work with WordPress Skills -**NEW:** This template includes 8 custom WordPress development skills that complement the agents. +**NEW:** This template includes 12 custom WordPress development skills that complement the agents. ### Skills vs Agents @@ -242,9 +260,9 @@ User: "Use the frontend-developer agent to help me build this block pattern" ### Complete WordPress Development Stack ``` -WordPress Skills (8) +WordPress Skills (12) ↓ Provide workflows and best practices -Agents (45) +Agents (53) ↓ Execute specialized tasks Plugins (6) ↓ Provide tooling and memory @@ -259,7 +277,7 @@ Automation Scripts (4) ## Current Architecture Status **Plugins:** ✅ Already optimized (5 user + 1 local) -**Custom Agents:** 45 total (20 WordPress-focused + 25 generic cross-domain) +**Custom Agents:** 53 total (26 WordPress-focused + 27 generic cross-domain) --- @@ -328,7 +346,7 @@ Ready for release ## Agent Hook Configurations -Agents with automated hooks (17 of 20): +Agents with automated hooks (18 of the 26 WordPress-focused agents): ### WordPress Core Quality Hooks (shared scripts) These scripts are shared across multiple agents: @@ -351,7 +369,7 @@ These scripts are shared across multiple agents: | seo-schema-agent | PostToolUse | validate-block-markup.sh | Block markup and heading hierarchy | | asset-cataloger | PreToolUse | validate-theme-location.sh | Blocks wp-content/ writes | -### Agents Without Hooks (3) +### 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) @@ -359,4 +377,4 @@ These agents are research/audit-only and don't need automated hooks: --- -**Architecture Assessment:** 49 custom agents provide comprehensive development coverage — 24 WordPress-specific agents for visual QA, asset management, environment management, markup validation, accessibility, token compliance, content seeding, and SEO, plus 25 generic cross-domain agents for business, marketing, engineering, and meta/ops tasks. +**Architecture Assessment:** 53 custom agents provide comprehensive development coverage — 26 WordPress-focused agents for design-source conversion (Figma/Canva/InDesign), visual QA, asset management, environment management, markup validation, accessibility, token compliance, content seeding, SEO, security, deployment, e-commerce, 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 index 5be7950..ce5b311 100644 --- a/.claude/PLUGINS-REFERENCE.md +++ b/.claude/PLUGINS-REFERENCE.md @@ -489,7 +489,7 @@ If you see agents named "code-reviewer" from different plugins, refer to `.claud ## 🎯 WordPress Development Skills (NEW) **Installed:** 2026-01-18 -**Total Skills:** 8 comprehensive WordPress workflows +**Total Skills:** 12 comprehensive WordPress workflows This template includes custom WordPress development skills that complement the plugins and agents. @@ -550,6 +550,10 @@ This template includes custom WordPress development skills that complement the p - WP-CLI automation with safe workflows and backups - Triggers: "scaffold theme", "wp command", "database export" +12. **indesign-conversion** + - Orchestrator for converting Adobe InDesign documents (`.idml` or PDF) to FSE block themes + - Triggers: "InDesign to WordPress", "IDML", "convert InDesign", "print to web" + ### Skills vs Plugins | Type | Purpose | Invocation | Example | @@ -587,4 +591,4 @@ wordpress-testing-workflows skill guides: **Last Updated:** 2026-01-18 **Template Version:** 1.0.0 **Architecture Status:** ✅ Optimized and Windows-compatible -**WordPress Skills:** ✅ 8 comprehensive workflows installed +**WordPress Skills:** ✅ 12 comprehensive workflows installed diff --git a/.claude/SETUP-COMPLETE.md b/.claude/SETUP-COMPLETE.md index 55d5b45..63362f7 100644 --- a/.claude/SETUP-COMPLETE.md +++ b/.claude/SETUP-COMPLETE.md @@ -1,11 +1,12 @@ # Claude Code Plugins Setup - Complete ✅ **Setup Date:** 2026-01-18 +**Last Reviewed:** 2026-06-28 — reflects current config (6 plugins, 53 agents, 12 skills, 4 commands) **Status:** All plugins installed and configured --- -## ✅ Installed Plugins +## ✅ Installed Plugins (6 Total) ### 1. php-lsp (PHP Language Server) - **Status:** Installed @@ -25,6 +26,24 @@ - **Prerequisite:** Git configured - **Next Step:** Test with `/commit` command +### 4. episodic-memory (Conversation Memory) +- **Status:** Installed +- **Purpose:** Conversation search and recall across sessions +- **Prerequisite:** None +- **Next Step:** Search prior conversations as you work + +### 5. superpowers (Advanced Workflows) +- **Status:** Installed +- **Purpose:** Advanced development workflows and tooling +- **Prerequisite:** None +- **Next Step:** Invoke superpowers workflows as needed + +### 6. ai-taskmaster (Task Management — local) +- **Status:** Installed +- **Purpose:** Task management and planning +- **Prerequisite:** None +- **Next Step:** Track tasks for your project + --- ## 🔧 Permission Updates @@ -88,7 +107,7 @@ which intelephense ``` **2. Test Autocomplete in WordPress File** -- Open: `wp-content/themes/*/functions.php` (or create test file) +- Open: `themes/*/functions.php` (or create test file) - Type: `wp_enqueue_` - **Expected:** Autocomplete suggestions appear with WordPress functions - **Expected:** Hover shows function documentation @@ -168,9 +187,12 @@ git add . **Expected Output:** ``` Installed plugins: -- php-lsp -- github +- episodic-memory - commit-commands +- github +- php-lsp +- superpowers +- ai-taskmaster ``` --- @@ -243,7 +265,7 @@ See `.claude/PLUGINS-REFERENCE.md` > "WordPress FSE Development Workflows" ### WordPress Development Setup 1. Install WordPress locally (if not already) -2. Create or clone FSE theme in `wp-content/themes/` +2. Create or clone FSE theme in `themes/` (root-level — never `wp-content/themes/` during development) 3. Test PHP LSP in theme files 4. Set up GitHub repository for theme 5. Configure development workflow with new plugins @@ -253,7 +275,7 @@ See `.claude/PLUGINS-REFERENCE.md` > "WordPress FSE Development Workflows" # 1. Start new feature git checkout -b feature/new-block-pattern -# 2. Develop in wp-content/themes/your-theme/ +# 2. Develop in themes/your-theme/ # - PHP LSP provides autocomplete # - Real-time error detection @@ -278,8 +300,8 @@ git pull - [x] GitHub integration installed - [x] Git workflows automated - [x] WordPress CLI available -- [x] Custom agents configured (49 agents) -- [x] Custom commands available (test, lint, create-blog-article) +- [x] Custom agents configured (53 agents) +- [x] Custom commands available (create-blog-article, lint, test, scaffold-block) - [x] Permissions properly scoped ### ⏭️ To Configure @@ -319,4 +341,4 @@ Your environment is now optimized for: **Setup completed successfully! Ready for WordPress FSE development.** -*Last updated: 2026-01-18* +*Last updated: 2026-06-28* diff --git a/.claude/agents/accessibility-auditor.md b/.claude/agents/accessibility-auditor.md index 2c30be6..2efe73d 100644 --- a/.claude/agents/accessibility-auditor.md +++ b/.claude/agents/accessibility-auditor.md @@ -1,7 +1,7 @@ --- name: accessibility-auditor description: WCAG 2.1 AA compliance auditor for WordPress FSE themes. Runs Lighthouse accessibility audits, checks color contrast, heading hierarchy, ARIA labels, alt text, and keyboard navigation. -tools: Read, Write, Bash, Grep, Glob, TodoWrite, TaskOutput, AskUserQuestion, mcp__chrome-devtools__navigate_page, mcp__chrome-devtools__take_screenshot, mcp__chrome-devtools__lighthouse_audit, mcp__chrome-devtools__evaluate_script, mcp__chrome-devtools__list_pages, mcp__chrome-devtools__new_page, mcp__chrome-devtools__select_page, mcp__chrome-devtools__press_key +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 --- @@ -16,8 +16,8 @@ Run Lighthouse accessibility audits on every page: ``` For each page URL: -1. Navigate to page via Chrome DevTools MCP -2. Run lighthouse_audit with category: "accessibility" +1. Navigate to page via Playwright MCP (browser_navigate) +2. Run Lighthouse via lhci — `pnpm lighthouse:run` (configured in lighthouserc.json) — and read the accessibility category 3. Capture score and individual audit results 4. Record failures with element selectors ``` @@ -86,7 +86,7 @@ Page: front-page ### 5. Keyboard Navigation Audit -**Test via Chrome DevTools MCP:** +**Test via Playwright MCP:** - Tab through the entire page - Verify all interactive elements are reachable - Check focus indicators are visible @@ -183,7 +183,7 @@ WCAG Standard: 2.1 AA 5. Check color contrast for all used combinations 6. Check ARIA labels and semantic HTML 7. If WordPress is running: - a. Run Lighthouse accessibility audit per page + a. Run the Lighthouse accessibility audit per page (lhci: `pnpm lighthouse:run`) b. Test keyboard navigation c. Check rendered focus indicators 8. Generate comprehensive report diff --git a/.claude/agents/seo-schema-agent.md b/.claude/agents/seo-schema-agent.md index ea179cd..7305809 100644 --- a/.claude/agents/seo-schema-agent.md +++ b/.claude/agents/seo-schema-agent.md @@ -1,7 +1,7 @@ --- name: seo-schema-agent description: Audits WordPress FSE themes for SEO best practices including heading hierarchy, meta tags, structured data, Open Graph, semantic HTML, and sitemap-friendly structure. -tools: Read, Write, Bash, Grep, Glob, TodoWrite, TaskOutput, WebSearch, mcp__chrome-devtools__navigate_page, mcp__chrome-devtools__evaluate_script, mcp__chrome-devtools__take_screenshot +tools: Read, Write, Bash, Grep, Glob, TodoWrite, TaskOutput, WebSearch, mcp__playwright__browser_navigate, mcp__playwright__browser_evaluate, mcp__playwright__browser_take_screenshot model: opus permissionMode: bypassPermissions hooks: @@ -61,7 +61,7 @@ WordPress FSE handles meta through: - SEO plugins (Yoast, Rank Math, etc.) - Theme.json `templateParts` area definitions -**Verify in rendered HTML (via Chrome DevTools):** +**Verify in rendered HTML (via Playwright MCP):** ```html [Page Title] - [Site Name] diff --git a/.claude/agents/visual-qa-agent.md b/.claude/agents/visual-qa-agent.md index 65efbb4..d6d0d8d 100644 --- a/.claude/agents/visual-qa-agent.md +++ b/.claude/agents/visual-qa-agent.md @@ -1,7 +1,7 @@ --- name: visual-qa-agent -description: Visual regression testing and design comparison agent. Renders WordPress pages via Chrome DevTools and Playwright, captures Figma designs, and produces structured visual diff reports with cross-browser testing. -tools: Read, Write, Bash, Grep, Glob, AskUserQuestion, TaskOutput, TodoWrite, mcp__chrome-devtools__navigate_page, mcp__chrome-devtools__take_screenshot, mcp__chrome-devtools__resize_page, mcp__chrome-devtools__list_pages, mcp__chrome-devtools__new_page, mcp__chrome-devtools__select_page, mcp__chrome-devtools__evaluate_script, mcp__chrome-devtools__lighthouse_audit, mcp__playwright__browser_navigate, mcp__playwright__browser_take_screenshot, mcp__playwright__browser_resize, mcp__playwright__browser_snapshot, mcp__playwright__browser_close, mcp__playwright__browser_wait_for, mcp__playwright__browser_tab_new, mcp__playwright__browser_tab_list, mcp__figma__get_screenshot, mcp__figma__get_design_context, mcp__figma__get_metadata, mcp__figma-desktop__get_screenshot, mcp__figma-desktop__get_design_context, mcp__figma-desktop__get_metadata +description: Visual regression testing and design comparison agent. Renders WordPress pages via the Playwright MCP, captures Figma designs, and produces structured visual diff reports with cross-browser testing. +tools: Read, Write, Bash, Grep, Glob, AskUserQuestion, TaskOutput, TodoWrite, mcp__playwright__browser_navigate, mcp__playwright__browser_take_screenshot, mcp__playwright__browser_resize, mcp__playwright__browser_snapshot, mcp__playwright__browser_close, mcp__playwright__browser_wait_for, mcp__playwright__browser_tab_new, mcp__playwright__browser_tab_list, mcp__figma__get_screenshot, mcp__figma__get_design_context, mcp__figma__get_metadata, mcp__figma-desktop__get_screenshot, mcp__figma-desktop__get_design_context, mcp__figma-desktop__get_metadata model: opus permissionMode: bypassPermissions --- @@ -12,7 +12,7 @@ You are a visual QA specialist for WordPress FSE block themes. You compare rende ### 1. Page Rendering & Screenshot Capture -**WordPress side — Chrome DevTools MCP (primary):** +**WordPress side — Playwright MCP (Chromium, primary):** - Navigate to each page URL on the local WordPress instance - Capture full-page screenshots at four breakpoints: - Extra-large: 1920px wide @@ -35,7 +35,7 @@ You are a visual QA specialist for WordPress FSE block themes. You compare rende **Cross-browser testing workflow:** ``` -1. Test all pages in Chromium via Chrome DevTools (primary, includes Lighthouse) +1. Test all pages in Chromium via Playwright MCP (primary); run Lighthouse separately via lhci (`pnpm lighthouse:run`) 2. Test all pages in Firefox via Playwright MCP 3. Test all pages in WebKit via Playwright MCP 4. Compare across browsers — flag rendering differences @@ -161,7 +161,7 @@ After fixes are applied: ``` 1. Receive: Theme name, WordPress URL, Figma file key + node IDs 2. Discover: Use Figma get_metadata to map pages to node IDs -3. For each page (Chromium via Chrome DevTools): +3. For each page (Chromium via Playwright MCP): a. Screenshot Figma design (4 breakpoints if available) b. Screenshot WordPress render (4 breakpoints) c. Compare and catalog differences @@ -187,8 +187,8 @@ After fixes are applied: - `wp-environment-manager` agent (ensures WordPress is running) **Requires:** -- Chrome DevTools MCP for primary Chromium testing and Lighthouse audits -- Playwright MCP (`@playwright/mcp`) for Firefox and WebKit testing +- Playwright MCP (`@playwright/mcp`) for Chromium, Firefox, and WebKit testing +- lhci (`pnpm lighthouse:run`, configured in lighthouserc.json) for Lighthouse audits - Run `./scripts/setup-playwright.sh` to install browser engines ## Rules @@ -206,7 +206,7 @@ After fixes are applied: - WordPress not accessible → Report blocker, suggest running `wp-environment-manager` - Figma MCP unavailable → Try both desktop and remote MCP servers -- Playwright MCP unavailable → Fall back to Chrome DevTools only, note browsers not tested +- Playwright MCP unavailable → Report the blocker and note which browsers were not tested - Browser engine not installed → Run `./scripts/setup-playwright.sh` to install - Page returns 404 → Check if page exists with WP-CLI, report missing page - Screenshot fails → Retry once, then report the failure diff --git a/.claude/skills/README.md b/.claude/skills/README.md index e1a96d1..20d23a8 100644 --- a/.claude/skills/README.md +++ b/.claude/skills/README.md @@ -11,60 +11,60 @@ This directory contains custom WordPress development skills for Claude Code, opt - Triggers: "convert Figma", "Figma to WordPress", "FSE conversion" - Role: Main workflow skill that coordinates all other skills - **indesign-conversion** +2. **indesign-conversion** - Convert an Adobe InDesign document (`.idml` or PDF) into an FSE block theme - Triggers: "InDesign to WordPress", "IDML", "convert InDesign", "print to web" - Role: Drives the `@flavian/pipeline` InDesign pipeline; pairs with the `indesign-to-wordpress` agent -2. **fse-block-theme-development** +3. **fse-block-theme-development** - theme.json syntax, template hierarchy, and FSE structure - Triggers: "create block theme", "add template", "theme.json" - Complements: frontend-developer agent, ui-designer agent -3. **fse-pattern-first-architecture** +4. **fse-pattern-first-architecture** - Enforces PHP patterns for images (not inline HTML) - Triggers: auto-triggered when creating FSE templates with images - Role: Architecture enforcement during conversion -4. **block-pattern-creation** +5. **block-pattern-creation** - Pattern registration, structure, and reusable UI patterns - Triggers: "create pattern", "register pattern", "pattern category" - Complements: fse-block-theme-development skill, ui-designer agent -5. **wordpress-security-hardening** +6. **wordpress-security-hardening** - Security validation during theme generation - Triggers: "security review", "sanitize input", "escape output", "nonce verification" - Complements: security-scan.sh script ### Pipeline Support Skills (Priority 2) -6. **visual-qa-verification** *(NEW)* +7. **visual-qa-verification** *(NEW)* - Post-conversion verification: screenshots, responsive checks, Lighthouse, accessibility - Triggers: "verify theme", "visual QA", "compare to Figma", "check screenshots" - - Complements: visual-qa-agent, accessibility-auditor agent, chrome-devtools MCP + - Complements: visual-qa-agent, accessibility-auditor agent, Playwright MCP -7. **wordpress-internationalization** +8. **wordpress-internationalization** - i18n/l10n for themes and plugins, including FSE pattern generation - Triggers: "translate", "i18n", "generate pattern", "create pattern" - Complements: figma-fse-converter agent, theme/plugin development workflows -8. **wordpress-hook-integration** +9. **wordpress-hook-integration** - Creating and managing Claude Code agent hooks - Triggers: "create hook", "agent hook", "PreToolUse", "PostToolUse" - Documents the 3 actual hooks in `.claude/hooks/` ### Supporting Skills -9. **wp-cli-workflows** - - WP-CLI commands for local testing (theme activation, content seeding, cache flush) - - Triggers: "scaffold theme", "create plugin", "export database", "search-replace" +10. **wp-cli-workflows** + - WP-CLI commands for local testing (theme activation, content seeding, cache flush) + - Triggers: "scaffold theme", "create plugin", "export database", "search-replace" -10. **wordpress-testing-workflows** +11. **wordpress-testing-workflows** - PHPUnit test creation and execution for WordPress - Triggers: "write tests", "run phpunit", "test coverage", "integration tests" - Complements: test-writer-fixer agent -11. **canva-to-fse-autonomous-workflow** +12. **canva-to-fse-autonomous-workflow** - Orchestrator for the Canva-to-FSE conversion pipeline (parallel entry point to Figma) - Triggers: "convert Canva", "Canva to WordPress", "Canva HTML export" - Role: Alternate entry point when design source is Canva rather than Figma @@ -103,7 +103,7 @@ Verified Theme Ready for WordPress ## Integration with Custom Agents -Each skill works with the 49 custom agents in this template: +Each skill works with the 53 custom agents in this template: - **figma-fse-converter** + figma-to-fse-autonomous-workflow + fse-pattern-first-architecture - **frontend-developer** + fse-block-theme-development @@ -140,4 +140,4 @@ Skills are version-controlled and updated when: --- **Last Updated:** 2026-03-06 -**Total Skills:** 11 +**Total Skills:** 12 diff --git a/.claude/skills/canva-to-fse-autonomous-workflow/SKILL.md b/.claude/skills/canva-to-fse-autonomous-workflow/SKILL.md index 08d30ad..a13a9e3 100644 --- a/.claude/skills/canva-to-fse-autonomous-workflow/SKILL.md +++ b/.claude/skills/canva-to-fse-autonomous-workflow/SKILL.md @@ -73,14 +73,14 @@ Before creating or modifying ANY theme files, verify: 2. [ ] NO files being created in `wp-content/themes/` (NEVER use this path) 3. [ ] Theme name slug is valid (lowercase, hyphens only, no spaces) -**Auto-validation script:** `scripts/canva-fse/validate-theme-location.sh` will block incorrect paths. +**Auto-validation:** the registered PreToolUse hook `.claude/hooks/validate-theme-location.sh` blocks incorrect paths (a copy also lives at `scripts/canva-fse/validate-theme-location.sh`). **Why root-level?** - Clean development structure (no nested wp-content) - Easier version control - Testing copies files to WordPress `wp-content/` separately -**Deployment Note:** During testing, files are copied from `themes/` to WordPress `wp-content/themes/`. See TESTING-GUIDE.md for deployment procedures. +**Deployment Note:** During testing, files are copied from `themes/` to WordPress `wp-content/themes/`. See [TESTING-GUIDE.md](../figma-to-fse-autonomous-workflow/TESTING-GUIDE.md) for deployment procedures. ## Fallback Design Tokens (Default Design System) diff --git a/.claude/skills/figma-to-fse-autonomous-workflow/IMPLEMENTATION-GUIDE.md b/.claude/skills/figma-to-fse-autonomous-workflow/IMPLEMENTATION-GUIDE.md index 33aa31d..77bee55 100644 --- a/.claude/skills/figma-to-fse-autonomous-workflow/IMPLEMENTATION-GUIDE.md +++ b/.claude/skills/figma-to-fse-autonomous-workflow/IMPLEMENTATION-GUIDE.md @@ -158,7 +158,7 @@ async function createThemeJsonFoundation(figmaFileKey, themeName) { async function extractDesignSystem(nodeId, fileKey) { try { // Try desktop MCP first (more reliable) - const variables = await mcp__figma_desktop__get_variable_defs({ + const variables = await mcp__figma-desktop__get_variable_defs({ nodeId: nodeId, fileKey: fileKey }); @@ -569,7 +569,7 @@ async function generateThemeJson(figmaVariables, themeName) { ```javascript async function surveyTemplates(figmaFileKey) { // 1. Use get_metadata to get file structure - const metadata = await mcp__figma_desktop__get_metadata({ + const metadata = await mcp__figma-desktop__get_metadata({ nodeId: "0:1", // Root page fileKey: figmaFileKey }); @@ -586,7 +586,7 @@ async function surveyTemplates(figmaFileKey) { // 4. Capture screenshot of each template const templateData = []; for (const template of templates) { - const screenshot = await mcp__figma_desktop__get_screenshot({ + const screenshot = await mcp__figma-desktop__get_screenshot({ nodeId: template.nodeId, fileKey: figmaFileKey }); @@ -652,7 +652,7 @@ function figmaNameToWpTemplate(figmaName) { async function extractTemplateStructure(nodeId, fileKey) { try { // Try get_design_context first (most detailed) - const designContext = await mcp__figma_desktop__get_design_context({ + const designContext = await mcp__figma-desktop__get_design_context({ nodeId: nodeId, fileKey: fileKey, clientLanguages: "html,css", @@ -678,7 +678,7 @@ async function extractTemplateStructure(nodeId, fileKey) { ```javascript async function extractFromScreenshot(nodeId, fileKey) { // Get screenshot - const screenshot = await mcp__figma_desktop__get_screenshot({ + const screenshot = await mcp__figma-desktop__get_screenshot({ nodeId: nodeId, fileKey: fileKey }); @@ -1025,7 +1025,7 @@ async function autonomousExecution(plan) { ### Pattern 1: Figma MCP Unreachable ``` -Try: mcp__figma_desktop__* (local) +Try: mcp__figma-desktop__* (local) Catch: Connection refused → Try: mcp__figma__* (remote) → Catch: Both fail diff --git a/.claude/skills/figma-to-fse-autonomous-workflow/SKILL.md b/.claude/skills/figma-to-fse-autonomous-workflow/SKILL.md index 5a15a86..a8fbb03 100644 --- a/.claude/skills/figma-to-fse-autonomous-workflow/SKILL.md +++ b/.claude/skills/figma-to-fse-autonomous-workflow/SKILL.md @@ -62,7 +62,7 @@ Before creating or modifying ANY theme files, verify: 2. [ ] NO files being created in `wp-content/themes/` (NEVER use this path) 3. [ ] Theme name slug is valid (lowercase, hyphens only, no spaces) -**Auto-validation script:** `scripts/figma-fse/validate-theme-location.sh` will block incorrect paths. +**Auto-validation:** the registered PreToolUse hook `.claude/hooks/validate-theme-location.sh` blocks incorrect paths (a copy also lives at `scripts/figma-fse/validate-theme-location.sh`). **Why root-level?** - Clean development structure (no nested wp-content) @@ -545,8 +545,8 @@ If failures occur: Log them but complete remaining templates. 2. **For EACH page template, run the verification loop:** ``` For each page (home, about, contact, etc.): - a. Navigate browser to page URL (chrome-devtools MCP: navigate_page) - b. Take full-page screenshot (chrome-devtools MCP: take_screenshot fullPage=true) + a. Navigate browser to page URL (mcp__playwright__browser_navigate) + b. Take full-page screenshot (mcp__playwright__browser_take_screenshot fullPage=true) c. Get Figma screenshot of same page (figma MCP: get_screenshot) d. View both screenshots side-by-side (Read tool on screenshot file) e. Compare section-by-section: @@ -921,21 +921,21 @@ After each template: ## Quality Gates -**Automated checks run during/after conversion:** +**Checks the agent runs during/after conversion** (invoked manually — these scripts exist but are NOT auto-registered in `.claude/settings.json`): -### Post-Template Hook +### Post-Template Script File: `.claude/hooks/figma-fse-post-template.sh` -Runs after each template creation: +The agent runs this after each template creation (if present): - Validate block syntax - Check for hardcoded hex colors - Verify theme.json token references - Scan for security issues -### Completion Hook +### Completion Script File: `.claude/hooks/figma-fse-completion.sh` -Runs when all templates complete: +The agent runs this when all templates complete (if present): - Generate comparison report - Run full security scan - Check coding standards diff --git a/.claude/skills/fse-pattern-first-architecture/skill.md b/.claude/skills/fse-pattern-first-architecture/skill.md index 4f9e72e..1082660 100644 --- a/.claude/skills/fse-pattern-first-architecture/skill.md +++ b/.claude/skills/fse-pattern-first-architecture/skill.md @@ -260,17 +260,17 @@ If you catch yourself: --- -## Validation Hook +## Validation Script This skill is enforced by: ```bash scripts/figma-fse/validate-pattern-architecture.sh ``` -Called automatically by `figma-fse-converter` agent's PostToolUse hook. +Run manually, or invoked by the `figma-fse-converter` agent during conversion. It is not registered as an automatic PostToolUse hook in `.claude/settings.json`. --- **Last Updated:** 2026-01-23 **Status:** ✅ Production Ready -**Enforcement:** Automatic via PostToolUse hooks +**Enforcement:** Manual / agent-run via `validate-pattern-architecture.sh` diff --git a/.claude/skills/indesign-conversion/SKILL.md b/.claude/skills/indesign-conversion/SKILL.md index b244b20..44d177f 100644 --- a/.claude/skills/indesign-conversion/SKILL.md +++ b/.claude/skills/indesign-conversion/SKILL.md @@ -91,7 +91,7 @@ node packages/pipeline/bin/generate-theme.mjs ir.json --out-dir themes/brochure ## Common gotchas - **CMYK/LAB → sRGB shifts.** Print color spaces don't map 1:1 to screen. The mapper converts and flags any out-of-gamut swatch in the report; expect brand colors to look slightly different on screen and confirm them with the designer. -- **Missing / substituted fonts.** InDesign fonts that aren't web-safe fall back via `config/font-map.json` (often a Google font). The report lists every fallback — confirm each, or self-host the real font and update the font map. +- **Missing / substituted fonts.** InDesign fonts that aren't web-safe fall back via `packages/pipeline/config/font-map.json` (often a Google font). The report lists every fallback — confirm each, or self-host the real font and update the font map. - **Oversized print images.** Print assets are often huge (300 DPI, CMYK). Resize/recompress for web and convert CMYK images to sRGB before importing, or they'll bloat the page and render with muddy color. - **PDF fidelity.** A PDF parse always carries warnings — text reconstructed from glyphs, synthesized styles, dropped vector art. Prefer `.idml`; treat PDF output as a starting point that needs review. - **Empty alt text.** Generated images have `alt=""`. Add meaningful alt text (the agent proposes some from surrounding story text) before shipping. diff --git a/.claude/skills/visual-qa-verification/SKILL.md b/.claude/skills/visual-qa-verification/SKILL.md index 58120c5..674afc1 100644 --- a/.claude/skills/visual-qa-verification/SKILL.md +++ b/.claude/skills/visual-qa-verification/SKILL.md @@ -63,11 +63,11 @@ Take screenshots at standard breakpoints and compare against the Figma source. | Wide | 1440px | Design canvas (Figma default) | | Extra-large | 1920px | Full HD monitors / large displays | -**Using Chrome DevTools MCP (Chromium — primary):** +**Using Playwright MCP (Chromium — primary):** ``` -1. Navigate to local WordPress URL -2. Take screenshot at each breakpoint (resize page, then screenshot) +1. Navigate to local WordPress URL (mcp__playwright__browser_navigate) +2. Take screenshot at each breakpoint (mcp__playwright__browser_resize, then mcp__playwright__browser_take_screenshot) 3. Compare visually against Figma source (get_screenshot from Figma MCP) ``` @@ -139,9 +139,9 @@ Run Lighthouse to catch performance and accessibility issues. | Best Practices | 90 | 100 | | SEO | 90 | 100 | -**Using Chrome DevTools MCP:** +**Using the Lighthouse CI CLI:** ``` -Run lighthouse_audit on the theme's front page +pnpm lighthouse:run # runs lhci autorun against lighthouserc.json ``` **Common issues in converted themes:** @@ -224,7 +224,7 @@ This skill works with: - **visual-qa-agent** — Performs visual comparison - **accessibility-auditor agent** — Runs accessibility checks - **figma-fse-completion.sh hook** — Structural validation (complements visual QA) -- **chrome-devtools MCP** — Screenshots, Lighthouse, responsive testing +- **Playwright MCP** — Screenshots and responsive testing (Lighthouse via `pnpm lighthouse:run`) - **figma MCP** — Source design screenshots for comparison ## Verification Report Template diff --git a/.claude/skills/wordpress-hook-integration/SKILL.md b/.claude/skills/wordpress-hook-integration/SKILL.md index 6ba88c1..47534b5 100644 --- a/.claude/skills/wordpress-hook-integration/SKILL.md +++ b/.claude/skills/wordpress-hook-integration/SKILL.md @@ -209,7 +209,7 @@ This skill enables: - **Per-template validation** via figma-fse-post-template.sh - **Conversion completion reports** via figma-fse-completion.sh -Works with all 49 custom agents in this template. +Works with all 53 custom agents in this template. --- diff --git a/.claude/templates/plugin/README.md b/.claude/templates/plugin/README.md index d6dba53..46ec39a 100644 --- a/.claude/templates/plugin/README.md +++ b/.claude/templates/plugin/README.md @@ -16,6 +16,7 @@ suffix stripped, and the following tokens replaced: | `{{PLUGIN_CLASS}}` | StudlyCase of slug (`flavian-starter` → `FlavianStarter`) | | `{{PLUGIN_CONST}}` | UPPER_SNAKE of slug (`FLAVIAN_STARTER`) | | `{{PLUGIN_NS}}` | `--namespace`, default `Flavian\Plugins\` | +| `{{PLUGIN_NS_JSON}}` | JSON-escaped `{{PLUGIN_NS}}` (backslashes doubled), used in composer.json / block.json | | `{{TEXT_DOMAIN}}` | always equals the slug | | `{{AUTHOR}}` | `--author`, default = `git config user.name` or `Anonymous` | | `{{VERSION}}` | always `0.1.0` | diff --git a/CLAUDE.md b/CLAUDE.md index 299bf11..63a6a73 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -4,13 +4,14 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co ## Project Overview -This is a **Claude Code-integrated WordPress development template** providing a clean `wp-content` directory structure with WordPress-specific development tools and scripts. +This is a **Claude Code-integrated WordPress development template** providing a clean, root-level WordPress content layout (`themes/`, `plugins/`, and `mu-plugins/` live at the project root) with WordPress-specific development tools and scripts. The template is designed for: - WordPress FSE (Full Site Editing) block theme development - Custom WordPress plugin development - WordPress security, performance, and accessibility auditing - Integration with Claude Code for WordPress development workflows +- Automated design-to-WordPress pipelines (Figma · Canva · InDesign) via the `flavian` CLI and Claude Code ## ⚠️ CRITICAL: File Location Requirements @@ -281,7 +282,7 @@ This project uses a lean, WordPress-optimized plugin configuration with 6 plugin ### Custom Agents (53 Total) -53 specialized agents: 28 WordPress-focused development agents plus 25 generic cross-domain agents (meta/ops, business, marketing/social, engineering). Key WordPress agents include `frontend-developer`, `plugin-developer`, `test-writer-fixer`, `ui-designer`, `figma-fse-converter`, `canva-fse-converter`, `indesign-to-wordpress`, `security-audit-agent`, `deployment-agent`, `woocommerce-agent`, `headless-developer`. Key generic agents include `agent-expert`, `backend-architect`, `migration-specialist`, `content-creator`, `devops-automator`. +53 specialized agents spanning WordPress-focused development and generic cross-domain work (meta/ops, business, marketing/social, engineering). Key WordPress agents include `frontend-developer`, `plugin-developer`, `test-writer-fixer`, `ui-designer`, `figma-fse-converter`, `canva-fse-converter`, `indesign-to-wordpress`, `security-audit-agent`, `deployment-agent`, `woocommerce-agent`, `headless-developer`. Key generic agents include `agent-expert`, `backend-architect`, `migration-specialist`, `content-creator`, `devops-automator`. See the catalog for the full WordPress/generic breakdown. Agents are invoked automatically based on task context. @@ -291,14 +292,11 @@ Agents are invoked automatically based on task context. ### Agent Naming Conflicts -**⚠️ Important:** Multiple agents share the name "code-reviewer" +**⚠️ Note:** If you install additional Claude Code plugins beyond the bundled set, more than one may provide a similarly-named agent (for example, a `code-reviewer`). -Use this guide to select the right one: -- **feature-dev/code-reviewer** - General development code reviews -- **pr-review-toolkit/code-reviewer** - Pull request reviews before merge -- **superpowers/code-reviewer** - Plan alignment verification +**Quick rule:** When names collide, pick the agent most specific to your task — a PR-focused reviewer before merge, a plan-alignment reviewer for verifying work against a plan, or a general reviewer otherwise. -**Quick rule:** Use the most specific agent for your context (PR → pr-review-toolkit, plan verification → superpowers, general → feature-dev) +The bundled 6-plugin set (see `.claude/PLUGINS-REFERENCE.md`) does not itself ship duplicate agent names; this guidance applies only once you add plugins that do. **Full guide:** See `.claude/AGENT-NAMING-GUIDE.md` @@ -463,7 +461,7 @@ Result: themes/[theme-name]/ ready for WordPress - All plugins serve WordPress development **Agent Philosophy:** -- 53 custom agents available (28 WordPress-focused + 25 generic cross-domain) +- 53 custom agents available (WordPress-focused + generic cross-domain; see CUSTOM-AGENTS-GUIDE.md for the breakdown) - Agents invoked contextually by Claude Code - No action required - automatic selection @@ -475,6 +473,10 @@ Result: themes/[theme-name]/ ready for WordPress - `README.md` - User guide and quick start - `IMPLEMENTATION.md` - Technical implementation details - `EXAMPLES.md` - FSE template syntax examples +- `docs/CLI-WIZARD.md` - The `flavian` CLI and interactive setup wizard +- `docs/pipelines/indesign.md` - InDesign (.idml/PDF) → FSE pipeline (CLI) +- `docs/GUI.md` - Cross-platform desktop GUI (`@flavian/gui`) +- `docs/RELEASING.md` - Release-please versioning and release flow - `.claude/PLUGINS-REFERENCE.md` - Plugin commands and detailed usage - `.claude/CUSTOM-AGENTS-GUIDE.md` - Complete agent catalog - `.claude/AGENT-NAMING-GUIDE.md` - Agent name disambiguation @@ -484,7 +486,7 @@ Result: themes/[theme-name]/ ready for WordPress **Troubleshooting:** - `docs/TROUBLESHOOTING.md` - General troubleshooting guide -- `docs/docker-troubleshooting.md` - Docker & container issues (15 common problems) +- `docs/docker-troubleshooting.md` - Docker & container issues (incl. Apple Silicon / M-series) - `docs/COMMON-FAILURES-FIXES.md` - Figma-to-WordPress workflow issues - `docs/MCP-TROUBLESHOOTING.md` - MCP server debugging - `docs/E2E-VALIDATION.md` - End-to-end validation procedures @@ -501,6 +503,34 @@ wp plugin list # List plugins wp db export backup.sql # Backup database ``` +**Flavian CLI & setup wizard:** +```bash +pnpm install # install workspace deps (pnpm 9.x) +pnpm run init # interactive setup wizard: writes .env, scaffolds a + # starter theme, optional WooCommerce, makes an initial commit +pnpm run init -- --yes --name=my-site --theme=blank # non-interactive +node bin/flavian.mjs --help # the `flavian` CLI entry point +``` +Full guide: `docs/CLI-WIZARD.md`. + +**Design-to-WordPress pipelines:** +```bash +# InDesign (.idml preferred, or PDF) → FSE theme, via the CLI +node bin/flavian.mjs pipeline indesign --output themes/ +pnpm pipeline:ingest # ingest stage (packages/pipeline) +pnpm pipeline:stage-assets # asset-staging stage +# Figma / Canva conversions are driven through Claude Code — see docs/figma-to-wordpress/ and docs/canva-to-wordpress/ +``` +Full guide: `docs/pipelines/indesign.md`. + +**Desktop GUI (`@flavian/gui`):** +```bash +pnpm gui:dev # run the cross-platform desktop GUI from source +pnpm gui:build # build the renderer +pnpm gui:package # build a distributable installer +``` +Full guide: `docs/GUI.md`. + **Git Workflows (via commit-commands):** ```bash /commit # Structured commit @@ -637,5 +667,5 @@ Full guide: `docs/blocks/README.md`. Tests: `tests/unit/scaffold-block.bats`. --- -**Last Updated:** 2026-05-06 +**Last Updated:** 2026-06-28 **Architecture Status:** ✅ Lean, WordPress-optimized configuration (6 plugins + 53 agents) \ No newline at end of file diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a5f8d2b..184ebde 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -93,18 +93,19 @@ releases. ## Versioning -The `version` field in `package.json` is intentionally pinned to `0.0.0` and is -**not** the repository version — **do not edit it by hand**. The source of truth -for the released version is the latest `vX.Y.Z` git tag together with -[`.release-please-manifest.json`](.release-please-manifest.json). +Do not hand-edit the `version` field in `package.json` — release-please keeps +it in sync automatically. The source of truth for the released version is +[`.release-please-manifest.json`](.release-please-manifest.json) together with the +latest `vX.Y.Z` git tag. Versioning is automated by [release-please](https://github.com/googleapis/release-please). The [Conventional Commit](#commit-message-format) types above drive the semver bump; release-please opens a **Release PR** that updates the manifest and `CHANGELOG.md`, and merging that PR creates the `vX.Y.Z` tag and GitHub Release. -Because the project uses release-please's `simple` release type, the bump is -recorded in `.release-please-manifest.json` rather than `package.json` — which -is exactly why `package.json` stays at `0.0.0`. +The project uses release-please's `simple` release type, so the bump is recorded +in `.release-please-manifest.json` and then mirrored into the `version` field of +both `package.json` and `packages/gui/package.json` via the `extra-files` entry +in [`release-please-config.json`](release-please-config.json). See [docs/RELEASING.md](docs/RELEASING.md) for the full flow, the version-bump rules, and overrides (e.g. the `Release-As:` footer). diff --git a/DOCUMENTATION-AUDIT.md b/DOCUMENTATION-AUDIT.md deleted file mode 100644 index e5f6aa1..0000000 --- a/DOCUMENTATION-AUDIT.md +++ /dev/null @@ -1,447 +0,0 @@ -# Documentation Organization Audit & Recommendations - -**Date:** 2026-01-23 -**Project:** Claude Code WordPress Template -**Purpose:** Reorganize documentation to eliminate redundancy and improve clarity - ---- - -## Executive Summary - -**Current State:** -- 65+ documentation files across 8 directories -- Significant redundancy (Figma-to-FSE documented in 14 files) -- Unclear documentation hierarchy -- Mixing of template docs, internal dev docs, and historical reports -- Root directory cluttered with 5 markdown files - -**Recommendations:** -1. Consolidate Figma-to-FSE documentation (14 files → 3-4 files) -2. Establish clear documentation hierarchy -3. Archive historical reports and plans -4. Fix .gitignore to properly track/ignore files -5. Create single entry point for template users - ---- - -## Critical Issues - -### Issue 1: Figma-to-FSE Documentation Sprawl - -**Problem:** Same information documented in 14+ files - -**Current Structure:** -``` -Root Level: -├── FIGMA-TO-FSE-AUTOMATION.md # Pattern-first overview -└── IMPLEMENTATION-SUMMARY.md # Improvement status - -.claude/skills/figma-to-fse-autonomous-workflow/: -├── SKILL.md # Main skill (22KB) -├── README.md # Skill overview -├── IMPLEMENTATION-GUIDE.md # Setup instructions -├── TESTING-GUIDE.md # Validation procedures -├── AUTONOMOUS-EXECUTION.md # Workflow details -└── TEMPLATE-EXAMPLES.md # Examples - -.claude/skills/fse-pattern-first-architecture/: -└── skill.md # Pattern-first approach - -.claude/agents/: -├── figma-fse-converter.md # Agent definition -└── (PATTERN-FIRST-ARCHITECTURE.md moved to docs/architecture/) - -.claude/reports/: -├── figma-fse-implementation-plan.md # Phase breakdown -├── figma-fse-comparison.md # Comparison analysis -└── rcvmd-conversion-report.md # Conversion results - -.claude/plans/: -└── figma-fse-rcvmd-conversion.md # Conversion plan -``` - -**Redundancy Analysis:** -- Pattern-first architecture: Documented 4 times -- Setup/implementation: Documented 3 times -- Testing/validation: Documented 2 times -- Examples: Spread across multiple files - -**Recommendation:** Consolidate to 3 files - -``` -docs/figma-to-wordpress/: -├── README.md # User guide + quick start -├── IMPLEMENTATION.md # Technical implementation details -└── EXAMPLES.md # Template examples - -archive/figma-development/: # Historical docs -├── implementation-plan.md # Original planning -├── comparison.md # Analysis from development -└── rcvmd-conversion.md # March Medical case study -``` - ---- - -### Issue 2: Plugin/Agent/Skill Documentation Duplication - -**Problem:** Same information in 3-4 different files - -#### Plugin Documentation (3 locations): -1. `CLAUDE.md` - Lists 5 plugins + descriptions -2. `.claude/SETUP-COMPLETE.md` - Setup verification -3. `.claude/PLUGINS-REFERENCE.md` - Command reference - -**Recommendation:** -- Keep `.claude/PLUGINS-REFERENCE.md` as single source of truth -- CLAUDE.md should reference it, not duplicate -- Move SETUP-COMPLETE.md to `archive/setup/` - -#### Agent Documentation (2 locations + 27 files): -1. `CLAUDE.md` - Lists 24 agents -2. `.claude/CUSTOM-AGENTS-GUIDE.md` - Same 24 agents -3. `.claude/agents/*.md` - Individual definitions (27 files) - -**Recommendation:** -- Keep `.claude/CUSTOM-AGENTS-GUIDE.md` as catalog -- Keep individual agent files (functional requirement) -- Remove agent list from CLAUDE.md, just reference guide - -#### Skill Documentation (2 locations + 10 files): -1. `CLAUDE.md` - Lists 8 WordPress skills -2. `.claude/skills/README.md` - Same 8 skills -3. Individual SKILL.md files in subdirectories - -**Recommendation:** -- Keep `.claude/skills/README.md` as catalog -- Keep individual skill files (functional requirement) -- Remove skill list from CLAUDE.md, just reference catalog - ---- - -### Issue 3: Root Directory Clutter - -**Current Root-Level Markdown Files:** -``` -├── README.md # Project overview -├── CLAUDE.md # Claude Code guidance (400+ lines) -├── FIGMA-TO-FSE-AUTOMATION.md # Figma automation overview -├── IMPLEMENTATION-SUMMARY.md # Status document -└── LOCAL-DEVELOPMENT.md # Docker setup -``` - -**Problem:** Unclear hierarchy, too many entry points - -**Recommendation:** Streamline to 2 entry points - -``` -Root: -├── README.md # Main entry point for template users -└── CLAUDE.md # Claude Code automation reference - -docs/: -├── LOCAL-DEVELOPMENT.md # Docker setup guide -└── figma-to-wordpress/ # Figma conversion docs - ├── README.md - ├── IMPLEMENTATION.md - └── EXAMPLES.md - -archive/: -└── development/ - ├── IMPLEMENTATION-SUMMARY.md # Historical status - └── figma-development/ # Historical reports -``` - ---- - -### Issue 4: Unclear Documentation Hierarchy - -**Problem:** No clear path for different user types - -**Current:** User doesn't know where to start -**Needed:** Clear entry points for: -1. Template users (want to use template) -2. Developers (want to modify template) -3. Claude Code automation (how to use automation features) - -**Recommendation:** Create clear hierarchy - -``` -README.md (Template Users) -├── Quick Start -├── Requirements -├── Features Overview -└── Links to detailed docs - ├── docs/LOCAL-DEVELOPMENT.md - ├── docs/figma-to-wordpress/ - └── CLAUDE.md - -CLAUDE.md (Claude Code Reference) -├── Project Overview -├── Critical Requirements (root-level folders) -├── Development Scripts -├── WordPress Standards -└── References (not duplicating): - ├── Plugins: see .claude/PLUGINS-REFERENCE.md - ├── Agents: see .claude/CUSTOM-AGENTS-GUIDE.md - ├── Skills: see .claude/skills/README.md - └── Figma: see docs/figma-to-wordpress/ - -.claude/ (Functional Files) -├── agents/ # Agent definitions (required by system) -├── skills/ # Skill definitions (required by system) -├── commands/ # Command definitions (required by system) -├── hooks/ # Hook scripts (functional) -├── validation/ # Validation scripts (functional) -├── PLUGINS-REFERENCE.md # Plugin command reference -├── CUSTOM-AGENTS-GUIDE.md # Agent catalog -└── AGENT-NAMING-GUIDE.md # Agent disambiguation -``` - ---- - -### Issue 5: Reports & Plans Mixed with Active Documentation - -**Current:** -``` -.claude/reports/: -├── figma-fse-implementation-plan.md -├── figma-fse-comparison.md -└── rcvmd-conversion-report.md - -.claude/plans/: -└── figma-fse-rcvmd-conversion.md -``` - -**Problem:** Historical/development artifacts mixed with active documentation - -**Recommendation:** Archive development history - -``` -archive/figma-development/: -├── implementation-plan.md # Planning document -├── comparison.md # Analysis during development -├── rcvmd-conversion-plan.md # March Medical plan -└── rcvmd-conversion-report.md # March Medical results -``` - -Keep `.claude/reports/` and `.claude/plans/` empty or remove them. - ---- - -## .gitignore Issues - -### Current .gitignore Analysis - -**Line 3-7 Problem:** -```gitignore -.claude/* # Ignore everything -!.claude/agents/ # Un-ignore agents -!.claude/skills/ # Un-ignore skills -!.claude/validation/ # Un-ignore validation -!.claude/*.md # Un-ignore markdown files -``` - -**Missing Un-ignore Patterns:** -- `.claude/commands/` - Should be tracked (functional requirement) -- `.claude/hooks/` - Should be tracked (functional requirement) - -**Currently Ignored but Present:** -- `.claude/logs/` - Correctly ignored (temporary) -- `.claude/reports/` - Should be removed (see Issue 5) -- `.claude/plans/` - Should be removed (see Issue 5) - -### Recommended .gitignore Changes - -**Add these un-ignore patterns:** -```gitignore -.claude/* -!.claude/agents/ -!.claude/skills/ -!.claude/commands/ # ADD THIS -!.claude/hooks/ # ADD THIS -!.claude/validation/ -!.claude/*.md -``` - -**Explicitly ignore (redundant but clear):** -```gitignore -# Claude Code temporary/user-specific files -.claude/logs/ -.claude/settings.local.json -.claude/reports/ # Remove directory first -.claude/plans/ # Remove directory first -``` - -### Additional Gitignore Recommendations - -**Consider adding:** -```gitignore -# Documentation archive (if keeping historical docs) -/archive/ - -# Docker development files (if sensitive) -.env -docker-compose.override.yml - -# Theme/plugin development artifacts -themes/*/node_modules/ -themes/*/.DS_Store -plugins/*/node_modules/ -plugins/*/.DS_Store -``` - ---- - -## Proposed Reorganization Plan - -### Phase 1: Create New Structure (Non-Breaking) - -1. **Create documentation directories:** - ```bash - mkdir -p docs/figma-to-wordpress - mkdir -p archive/figma-development - mkdir -p archive/setup - ``` - -2. **Consolidate Figma documentation:** - - Create `docs/figma-to-wordpress/README.md` (user guide) - - Create `docs/figma-to-wordpress/IMPLEMENTATION.md` (technical) - - Create `docs/figma-to-wordpress/EXAMPLES.md` (examples) - - Move reports to `archive/figma-development/` - - Move plans to `archive/figma-development/` - -3. **Move historical documentation:** - - `IMPLEMENTATION-SUMMARY.md` → `archive/development/` - - `.claude/SETUP-COMPLETE.md` → `archive/setup/` - -4. **Update .gitignore:** - - Add `!.claude/commands/` - - Add `!.claude/hooks/` - - Add `archive/` to ignored paths (if desired) - -### Phase 2: Clean Up Redundancy - -1. **Streamline CLAUDE.md:** - - Remove plugin list (reference PLUGINS-REFERENCE.md) - - Remove agent list (reference CUSTOM-AGENTS-GUIDE.md) - - Remove skill list (reference .claude/skills/README.md) - - Keep only WordPress standards and critical requirements - - Target: 200 lines (currently 400+) - -2. **Remove root-level files:** - - `FIGMA-TO-FSE-AUTOMATION.md` → Consolidated into docs/ - - `IMPLEMENTATION-SUMMARY.md` → archive/ - -3. **Clean up .claude/ directories:** - - Remove `.claude/reports/` (after archiving) - - Remove `.claude/plans/` (after archiving) - -### Phase 3: Update Cross-References - -1. **Update README.md** to reference new structure -2. **Update CLAUDE.md** to reference new locations -3. **Update skill files** that reference moved documentation -4. **Test all documentation links** - ---- - -## Recommended Final Structure - -``` -project-root/ -├── README.md # Main entry point (template users) -├── CLAUDE.md # Claude Code reference (~200 lines) -├── LOCAL-DEVELOPMENT.md # Or move to docs/ -├── .gitignore # Updated with proper patterns -│ -├── docs/ -│ ├── LOCAL-DEVELOPMENT.md # Docker setup (if moved) -│ └── figma-to-wordpress/ -│ ├── README.md # User guide + quick start -│ ├── IMPLEMENTATION.md # Technical details -│ └── EXAMPLES.md # Template examples -│ -├── .claude/ -│ ├── agents/ # 27 agent definition files -│ ├── skills/ # Skill definitions -│ │ ├── README.md # Skills catalog -│ │ └── [8 skill directories] -│ ├── commands/ # Command definitions -│ ├── hooks/ # Hook scripts (tracked) -│ ├── validation/ # Validation scripts -│ ├── logs/ # Temporary (gitignored) -│ ├── settings.local.json # User-specific (gitignored) -│ ├── PLUGINS-REFERENCE.md # Plugin command reference -│ ├── CUSTOM-AGENTS-GUIDE.md # Agent catalog -│ └── AGENT-NAMING-GUIDE.md # Disambiguation -│ -├── archive/ # Historical documentation -│ ├── setup/ -│ │ └── SETUP-COMPLETE.md -│ ├── development/ -│ │ └── IMPLEMENTATION-SUMMARY.md -│ └── figma-development/ -│ ├── implementation-plan.md -│ ├── comparison.md -│ ├── rcvmd-conversion-plan.md -│ └── rcvmd-conversion-report.md -│ -├── themes/ # Development themes (tracked) -├── plugins/ # Development plugins (tracked) -├── mu-plugins/ # Development mu-plugins (tracked) -└── scripts/ # WordPress validation scripts - └── README.md -``` - ---- - -## Implementation Priority - -### High Priority (Do First): -1. ✅ Fix .gitignore (add commands, hooks) -2. ✅ Consolidate Figma docs (14 files → 3 files) -3. ✅ Archive reports and plans -4. ✅ Streamline CLAUDE.md (remove duplicated lists) - -### Medium Priority: -5. Move IMPLEMENTATION-SUMMARY.md to archive -6. Move SETUP-COMPLETE.md to archive -7. Update cross-references in remaining docs -8. Test all documentation links - -### Low Priority: -9. Move LOCAL-DEVELOPMENT.md to docs/ -10. Create comprehensive index in README.md -11. Add documentation contribution guidelines - ---- - -## Expected Benefits - -**After Reorganization:** -- **Clarity:** Single source of truth for each topic -- **Maintainability:** Updates only needed in one place -- **Onboarding:** Clear entry points for different users -- **Cleanliness:** Root directory streamlined to 2-3 files -- **Version Control:** Proper tracking of functional files -- **History:** Development artifacts preserved but separated - -**Metrics:** -- Root markdown files: 5 → 2-3 -- Figma documentation files: 14 → 3 -- CLAUDE.md length: 400+ lines → ~200 lines -- Redundant information: High → Minimal - ---- - -## Questions for Template Owner - -1. **Archive directory:** Should `archive/` be tracked in git or gitignored? -2. **Historical reports:** Keep or delete rcvmd-conversion reports? -3. **LOCAL-DEVELOPMENT.md:** Keep in root or move to `docs/`? -4. **Agent pruning:** Remove 16 non-WordPress agents from template? -5. **Setup documentation:** Keep SETUP-COMPLETE.md for reference or archive? - ---- - -**Next Steps:** Review recommendations and approve Phase 1 implementation. diff --git a/DOCUMENTATION-REORGANIZATION-COMPLETE.md b/DOCUMENTATION-REORGANIZATION-COMPLETE.md deleted file mode 100644 index 17a8977..0000000 --- a/DOCUMENTATION-REORGANIZATION-COMPLETE.md +++ /dev/null @@ -1,328 +0,0 @@ -# Documentation Reorganization - Complete - -**Date:** 2026-01-23 -**Status:** ✅ Phase 1 Complete - ---- - -## Summary - -Successfully reorganized documentation from 65+ files with significant redundancy down to a clean, hierarchical structure with clear entry points for different user types. - ---- - -## What Changed - -### 1. ✅ Figma-to-FSE Documentation Consolidated - -**Before:** 14 files scattered across multiple directories -**After:** 3 organized files in `docs/figma-to-wordpress/` - -**Consolidation:** -``` -Removed from root: -├── FIGMA-TO-FSE-AUTOMATION.md → Consolidated -└── IMPLEMENTATION-SUMMARY.md → Archived - -Archived from .claude/: -├── reports/figma-fse-implementation-plan.md → archive/figma-development/ -├── reports/figma-fse-comparison.md → archive/figma-development/ -├── reports/rcvmd-conversion-report.md → archive/figma-development/ -└── plans/figma-fse-rcvmd-conversion.md → archive/figma-development/ - -New consolidated structure: -docs/figma-to-wordpress/ -├── README.md (8KB) # User guide + quick start -├── IMPLEMENTATION.md (12KB) # Technical implementation -└── EXAMPLES.md (7KB) # FSE template examples - -Skill files remain (functional requirement): -.claude/skills/figma-to-fse-autonomous-workflow/ -├── SKILL.md (22KB) -├── IMPLEMENTATION-GUIDE.md (40KB) -├── TEMPLATE-EXAMPLES.md (20KB) -├── AUTONOMOUS-EXECUTION.md (20KB) -├── TESTING-GUIDE.md (18KB) -└── README.md (6KB) -``` - -**Result:** -- 14 files → 3 user-facing docs + 6 skill files (functional) -- Clear separation: User docs vs. Agent/skill implementation -- Single source of truth for each topic - ---- - -### 2. ✅ Streamlined CLAUDE.md - -**Before:** 400+ lines with detailed plugin/agent/skill lists -**After:** ~350 lines, reference-based approach - -**Changes:** - -#### Plugin Section (Lines 268-279) -**Before:** 21 lines with detailed plugin descriptions and commands -**After:** 11 lines with summary + reference to PLUGINS-REFERENCE.md - -#### Agents Section (Lines 283-289) -**Before:** 27 lines listing all 24 agents individually -**After:** 6 lines with summary + reference to CUSTOM-AGENTS-GUIDE.md - -#### Skills Section (Lines 308-318) -**Before:** 67 lines listing all 8 skills with triggers and locations -**After:** 10 lines with summary + reference to .claude/skills/README.md - -**Added:** -- Figma-to-WordPress automation section in workflow guide (lines 373-394) -- Updated Documentation Structure section (lines 413-423) - -**Removed redundancy:** ~85 lines of duplicated information - ---- - -### 3. ✅ Fixed .gitignore - -**Added tracking for functional directories:** -```gitignore -.claude/* -!.claude/agents/ -!.claude/skills/ -!.claude/commands/ # ← ADDED -!.claude/hooks/ # ← ADDED -!.claude/validation/ -!.claude/*.md - -# Explicitly ignore temporary files -.claude/logs/ -.claude/settings.local.json -``` - -**Result:** Commands and hooks now properly tracked in version control - ---- - -### 4. ✅ Created Archive Structure - -**Historical documentation moved to archive:** -``` -archive/ -├── figma-development/ -│ ├── implementation-plan.md (from .claude/reports/) -│ ├── comparison.md (from .claude/reports/) -│ ├── rcvmd-conversion-plan.md (from .claude/plans/) -│ └── rcvmd-conversion-report.md (from .claude/reports/) -└── development/ - └── IMPLEMENTATION-SUMMARY.md (from root) -``` - -**Empty directories removed:** -- `.claude/reports/` (all files moved to archive) -- `.claude/plans/` (all files moved to archive) - ---- - -### 5. ✅ Updated Cross-References - -**README.md:** -- Added `docs/figma-to-wordpress/` reference -- Updated Claude Code Documentation section with new structure - -**CLAUDE.md:** -- Updated Documentation Structure section -- Added Figma automation workflow guide -- Referenced new docs locations - -**Result:** All documentation cross-references updated and accurate - ---- - -## New Documentation Structure - -### Root Directory (Clean) -``` -project-root/ -├── README.md # Main entry point -├── CLAUDE.md # Claude Code reference (~350 lines) -├── LOCAL-DEVELOPMENT.md # Docker setup -└── DOCUMENTATION-AUDIT.md # Audit report (for reference) -``` - -### Organized Documentation -``` -docs/ -└── figma-to-wordpress/ - ├── README.md # User guide - ├── IMPLEMENTATION.md # Technical details - └── EXAMPLES.md # Template examples - -archive/ -├── figma-development/ # Historical Figma reports -└── development/ # Historical dev notes -``` - -### Functional Files (.claude/) -``` -.claude/ -├── agents/ # 27 agent definition files -├── skills/ # Skill definitions + README -├── commands/ # Command definitions -├── hooks/ # Hook scripts (NOW TRACKED) -├── validation/ # Validation scripts -├── logs/ # Temporary (gitignored) -├── settings.local.json # User-specific (gitignored) -├── PLUGINS-REFERENCE.md # Plugin command reference -├── CUSTOM-AGENTS-GUIDE.md # Agent catalog -└── AGENT-NAMING-GUIDE.md # Disambiguation -``` - ---- - -## File Count Changes - -| Category | Before | After | Change | -|----------|--------|-------|--------| -| Root markdown files | 5 | 3 | -40% | -| Figma user docs | 14 files | 3 files | -79% | -| CLAUDE.md length | 400+ lines | ~350 lines | -12% | -| Redundant info | High | Minimal | -95% | -| Active docs | 65+ | 45 | -31% | -| Archived docs | 0 | 5 | +5 | - ---- - -## Benefits Achieved - -### ✅ Clarity -- Single source of truth for each topic -- Clear entry points: README → CLAUDE.md → Specialized docs -- No duplication between files - -### ✅ Maintainability -- Updates only needed in one place -- References instead of duplication -- Historical docs preserved separately - -### ✅ Onboarding -- Template users: Start with README -- Developers: Use CLAUDE.md + specialized docs -- Claude Code: Reference-based guidance - -### ✅ Cleanliness -- Root directory: 5 files → 3 files -- No redundant Figma documentation -- Proper version control (commands, hooks tracked) - ---- - -## User Entry Points - -### 1. Template Users -**Start:** README.md -- Quick start instructions -- Directory structure explanation -- Links to detailed documentation - -### 2. Figma-to-WordPress Users -**Start:** docs/figma-to-wordpress/README.md -- Quick start guide -- Usage examples -- Features and benefits -- Links to technical details - -### 3. WordPress Developers -**Start:** CLAUDE.md -- WordPress development standards -- Critical requirements (root-level folders) -- Development scripts and workflows -- References to plugin/agent/skill catalogs - -### 4. Claude Code Automation -**Start:** CLAUDE.md → Reference files -- PLUGINS-REFERENCE.md for commands -- CUSTOM-AGENTS-GUIDE.md for agent selection -- .claude/skills/README.md for skill catalog -- docs/figma-to-wordpress/ for Figma automation - ---- - -## Questions Resolved - -### Q: Should archive/ be tracked in git? -**Decision:** Yes, tracked for now (may gitignore later if desired) - -### Q: Keep March Medical (rcvmd) conversion reports? -**Decision:** Kept in archive/figma-development/ (historical reference) - -### Q: Move LOCAL-DEVELOPMENT.md to docs/? -**Decision:** Keep in root for now (frequently accessed) - -### Q: Remove 16 non-WordPress agents? -**Decision:** Deferred (user can decide later, documented in CUSTOM-AGENTS-GUIDE.md) - ---- - -## Verification Checklist - -### Documentation Structure -- [x] Root directory streamlined (5 → 3 markdown files) -- [x] Figma docs consolidated (14 → 3 files) -- [x] CLAUDE.md streamlined (~85 lines removed) -- [x] Cross-references updated (README, CLAUDE.md) -- [x] Archive created (5 historical files) - -### Version Control -- [x] .gitignore updated (commands, hooks tracked) -- [x] Temporary files explicitly ignored -- [x] Functional directories properly tracked - -### Content Quality -- [x] No broken links between docs -- [x] Clear entry points for each user type -- [x] Single source of truth for each topic -- [x] Historical context preserved (archive) - -### File Organization -- [x] docs/figma-to-wordpress/ created -- [x] archive/ structure created -- [x] Old files removed from root -- [x] Old files archived properly - ---- - -## Next Steps (Optional) - -### Potential Future Improvements -1. Add `archive/` to .gitignore (if historical docs not needed in repo) -2. Remove 16 non-WordPress agents (if not needed) -3. Create CONTRIBUTING.md with documentation guidelines -4. Add README files to each .claude/ subdirectory -5. Create visual documentation structure diagram - -### Maintenance -1. Update docs when new features added -2. Keep CLAUDE.md as quick reference (don't let it grow) -3. Move completed project docs to archive -4. Review documentation annually for relevance - ---- - -## Metrics - -### Time Investment -- Analysis: 30 minutes -- Consolidation: 45 minutes -- Updates: 30 minutes -- Verification: 15 minutes -**Total:** ~2 hours - -### Quality Improvement -- Redundancy: 95% reduction -- File count: 31% reduction -- CLAUDE.md: 12% shorter -- User experience: Significantly improved (clear entry points) - ---- - -**Status:** ✅ Phase 1 Complete - Documentation Reorganization Successful - -**Last Updated:** 2026-01-23 diff --git a/LOCAL-DEVELOPMENT.md b/LOCAL-DEVELOPMENT.md index a59cef6..093de70 100644 --- a/LOCAL-DEVELOPMENT.md +++ b/LOCAL-DEVELOPMENT.md @@ -1,30 +1,36 @@ # Local WordPress Development with Docker -## Quick Start (4 steps) +## Quick Start (6 steps) -**1. Build the Docker image (first time only):** +**1. Create your `.env` file (first time only):** +```bash +cp .env.example .env # or run: pnpm run init +``` +> Docker reads the database credentials from `.env` and has no built-in defaults, so the containers fail to start without it. + +**2. Build the Docker image (first time only):** ```bash ./wordpress-local.sh build ``` -**2. Start WordPress:** +**3. Start WordPress:** ```bash ./wordpress-local.sh start ``` -**3. Install WordPress (first time only):** +**4. Install WordPress (first time only):** ```bash ./wordpress-local.sh install ``` -**4. Activate your theme:** +**5. Activate your theme:** ```bash ./wordpress-local.sh activate-theme your-theme ``` -**5. Open in browser:** +**6. Open in browser:** - **Site:** http://localhost:8080 -- **Admin:** http://localhost:8080/wp-admin (admin/admin) +- **Admin:** http://localhost:8080/wp-admin (admin/changeme) - **Database:** http://localhost:8081 (phpMyAdmin) --- diff --git a/README.md b/README.md index 22a344a..11f5fce 100644 --- a/README.md +++ b/README.md @@ -21,7 +21,7 @@ Typical runtime: 5–30 minutes. No manual `theme.json` authoring. ## Desktop GUI (experimental) -Prefer not to use a terminal? A cross-platform **desktop GUI** (v3.0.0, epic #100) wraps the whole workflow behind a graphical interface — five screens: **Prerequisites**, **Setup wizard**, **WordPress (Docker)**, **Convert design** (Figma/Canva/InDesign), and **Visual QA**. It's a thin orchestration layer over the existing scripts and pipelines — it invokes them, it doesn't replace them. Run it from source with `pnpm gui:dev` (or build an installer with `pnpm gui:package`). See **[docs/GUI.md](docs/GUI.md)**. +Prefer not to use a terminal? A cross-platform **desktop GUI** wraps the whole workflow behind a graphical interface — five screens: **Prerequisites**, **Setup wizard**, **WordPress (Docker)**, **Convert design** (Figma/Canva/InDesign), and **Visual QA**. It's a thin orchestration layer over the existing scripts and pipelines — it invokes them, it doesn't replace them. Run it from source with `pnpm gui:dev` (or build an installer with `pnpm gui:package`). See **[docs/GUI.md](docs/GUI.md)**. ## Prerequisites @@ -29,7 +29,8 @@ Prefer not to use a terminal? A cross-platform **desktop GUI** (v3.0.0, epic #10 |---|---|---| | **[Claude Code](https://claude.ai/code)** | The conversion engine | `npm install -g @anthropic-ai/claude-code` | | **[Docker Desktop](https://www.docker.com/products/docker-desktop/)** | Local WordPress (WordPress + MySQL + phpMyAdmin) | [docker.com/download](https://www.docker.com/products/docker-desktop/) | -| **[Node.js](https://nodejs.org/) 18+** | Playwright MCP for visual QA | [nodejs.org](https://nodejs.org/) | +| **[Node.js](https://nodejs.org/) 20+** | Tooling: pnpm, setup wizard, pipelines, Playwright MCP | [nodejs.org](https://nodejs.org/) | +| **[pnpm](https://pnpm.io/) 9.x** | Package manager (workspace scripts, init wizard, GUI/pipeline) | `corepack enable` (bundled with Node) | | **[Git](https://git-scm.com/)** | Version control | [git-scm.com](https://git-scm.com/) | | **[Figma Professional+](https://www.figma.com/pricing/)** | Dev Mode — required to extract design tokens (skip if using Canva input only) | [figma.com](https://www.figma.com/) | @@ -79,7 +80,7 @@ Site at http://localhost:8080 · Admin at /wp-admin · Database UI at :8081. **More docs:** [docs/QUICK-START.md](docs/QUICK-START.md) · [LOCAL-DEVELOPMENT.md](LOCAL-DEVELOPMENT.md) · [docs/docker-troubleshooting.md](docs/docker-troubleshooting.md) -> **Versioning:** `package.json` declares `0.0.0` on purpose — the real version lives in git tags + `.release-please-manifest.json`. See [Versioning](CONTRIBUTING.md#versioning) in CONTRIBUTING.md. +> **Versioning:** the source of truth is git tags + `.release-please-manifest.json`; release-please mirrors that version into `package.json` (currently `1.12.0`) — don't bump it by hand. See [Versioning](CONTRIBUTING.md#versioning) in CONTRIBUTING.md.
Alternative: use as a wp-content directory in an existing WordPress install diff --git a/docs/CLI-WIZARD.md b/docs/CLI-WIZARD.md index de745e4..5c9c513 100644 --- a/docs/CLI-WIZARD.md +++ b/docs/CLI-WIZARD.md @@ -45,7 +45,7 @@ node scripts/init.mjs | `flavian-shop` | The bundled WooCommerce-ready theme, copied and renamed to your slug | | `canva` | A **working** FSE theme converted from a Canva HTML/CSS export (requires `--canva-export`). See [Canva starter](#canva-starter) | | `figma` | No theme generated. Writes `docs/NEXT-STEPS.md` pointing at the `figma-to-fse-autonomous-workflow` skill | -| `indesign` | Placeholder only — the InDesign-to-FSE pipeline is not yet implemented | +| `indesign` | Wizard starter is a placeholder (no theme generated). The standalone InDesign→FSE pipeline *does* ship separately — run `flavian pipeline indesign` (see `packages/pipeline/`) | ## Non-interactive flags @@ -213,7 +213,9 @@ runs this on every push/PR that touches the wizard code. ## Known limitations -- The InDesign starter is a placeholder; no pipeline ships yet. +- The InDesign *wizard starter* is a placeholder — it scaffolds no theme. (The + standalone InDesign→FSE pipeline does ship: `flavian pipeline indesign`, backed + by `packages/pipeline/`.) - Re-running the wizard against an existing `themes//` directory fails cleanly — there's no in-place upgrade path. - Verification is static-only. Docker isn't booted; if Docker is missing or diff --git a/docs/COMMON-FAILURES-FIXES.md b/docs/COMMON-FAILURES-FIXES.md index c035699..0d0ee8d 100644 --- a/docs/COMMON-FAILURES-FIXES.md +++ b/docs/COMMON-FAILURES-FIXES.md @@ -223,7 +223,7 @@ Node.js is not installed or not in system PATH. ```bash node -v ``` - Expected: Version number (v18.0.0 or higher) + Expected: Version number (v20.0.0 or higher) 2. If not installed, install Node.js: - Windows: Download from https://nodejs.org/ or use `winget install OpenJS.NodeJS.LTS` @@ -1030,7 +1030,7 @@ Design tokens were not extracted correctly, or templates use wrong color slugs. **Prevention** - Verify design token extraction before template generation -- Run token compliance check: `./scripts/figma-fse/extract-design-tokens.sh` +- Run the token-compliance auditor (`scripts/theme-token-auditor/audit-tokens.sh`) over templates/patterns - Never use hardcoded colors in templates --- @@ -1373,9 +1373,11 @@ Templates or patterns contain hardcoded values instead of theme.json token refer **Fix** -1. Run token compliance check: +1. Run the token-compliance auditor. It's a PostToolUse hook that reads a file + path from stdin (`tool_input.file_path`), so feed it each template/pattern: ```bash - ./scripts/figma-fse/extract-design-tokens.sh themes/[theme-name]/theme.json + echo '{"tool_input":{"file_path":"themes/[theme-name]/templates/front-page.html"}}' \ + | ./scripts/theme-token-auditor/audit-tokens.sh ``` 2. Find hardcoded values in templates: @@ -1864,7 +1866,7 @@ How to recover from major issues. - [Figma-to-WordPress README](./figma-to-wordpress/README.md) - Overview of conversion workflow - [Implementation Guide](./figma-to-wordpress/IMPLEMENTATION.md) - Technical implementation details - [Pattern-First Architecture](./architecture/PATTERN-FIRST-ARCHITECTURE.md) - Image handling in FSE themes -- [Testing Guide](./.claude/skills/figma-to-fse-autonomous-workflow/TESTING-GUIDE.md) - Step-by-step testing procedures +- [Testing Guide](../.claude/skills/figma-to-fse-autonomous-workflow/TESTING-GUIDE.md) - Step-by-step testing procedures --- diff --git a/docs/COMMON-FAILURES-FIXES.validation.md b/docs/COMMON-FAILURES-FIXES.validation.md index adcb26f..e21d4ba 100644 --- a/docs/COMMON-FAILURES-FIXES.validation.md +++ b/docs/COMMON-FAILURES-FIXES.validation.md @@ -160,7 +160,7 @@ Each issue must score at least 4/5 on actionability: ### Command Completeness All commands MUST: -- [x] Use absolute paths (not relative) +- [x] Use project-relative paths (e.g. `./scripts/…`, `themes/[theme-name]/…`) - [x] Include placeholder syntax for variable parts (e.g., `[theme-name]`) - [x] Work on Windows (Git Bash) and Linux/macOS - [x] Include expected output descriptions @@ -197,7 +197,7 @@ Before the guide is considered complete, verify: ### Quality - [x] Each issue scores 4+ on actionability -- [x] All commands are absolute paths +- [x] All commands use project-relative paths - [x] Cross-references present and working ### Usability diff --git a/docs/E2E-VALIDATION.md b/docs/E2E-VALIDATION.md index 970b563..a56ea37 100644 --- a/docs/E2E-VALIDATION.md +++ b/docs/E2E-VALIDATION.md @@ -25,7 +25,7 @@ Before starting validation: - [ ] Docker Desktop running - [ ] Theme exists in `themes//` -- [ ] Node.js 18+ installed (for Playwright) +- [ ] Node.js 20+ installed (for Playwright) - [ ] Playwright installed (`npm install -g playwright && npx playwright install`) --- @@ -207,7 +207,7 @@ Enable WordPress debugging to catch PHP errors: ```bash # Enter WordPress container -docker-compose exec wordpress bash +docker compose exec wordpress bash # Add debug constants to wp-config.php (inside container) wp config set WP_DEBUG true --raw --allow-root @@ -220,10 +220,10 @@ exit ```bash # View debug log -docker-compose exec wordpress cat /var/www/html/wp-content/debug.log 2>/dev/null || echo "No debug.log (good - no errors)" +docker compose exec wordpress cat /var/www/html/wp-content/debug.log 2>/dev/null || echo "No debug.log (good - no errors)" # Check for fatal errors -docker-compose exec wordpress grep -i "fatal\|error\|warning" /var/www/html/wp-content/debug.log 2>/dev/null | head -20 || echo "PASS: No PHP errors found" +docker compose exec wordpress grep -i "fatal\|error\|warning" /var/www/html/wp-content/debug.log 2>/dev/null | head -20 || echo "PASS: No PHP errors found" ``` **Expected output:** @@ -728,7 +728,7 @@ See `scripts/validate-theme-e2e.sh` for full automation of these checks. ### Getting Help - **Debug log location:** `/var/www/html/wp-content/debug.log` (in container) -- **View logs:** `docker-compose exec wordpress cat /var/www/html/wp-content/debug.log` +- **View logs:** `docker compose exec wordpress cat /var/www/html/wp-content/debug.log` - **Troubleshooting guide:** See `docs/TROUBLESHOOTING.md` - **Common failures:** See `docs/COMMON-FAILURES-FIXES.md` diff --git a/docs/MCP-TROUBLESHOOTING.md b/docs/MCP-TROUBLESHOOTING.md index d215a0b..6e61334 100644 --- a/docs/MCP-TROUBLESHOOTING.md +++ b/docs/MCP-TROUBLESHOOTING.md @@ -78,7 +78,7 @@ This project uses the following MCP servers (defined in `.mcp.json`): - Capture screenshots - Execute JavaScript on pages - Test across Chromium, Firefox, WebKit -- Requires: Node.js 18+, Playwright browsers installed +- Requires: Node.js 20+, Playwright browsers installed ### How Claude Code Uses MCP @@ -929,7 +929,7 @@ The Playwright MCP server command failed to execute. ```bash node -v ``` - Required: v18.0.0 or higher + Required: v20.0.0 or higher 2. Install Node.js if needed: - Windows: `winget install OpenJS.NodeJS.LTS` @@ -963,7 +963,7 @@ The Playwright MCP server command failed to execute. ``` **Prevention** -- Maintain Node.js 18+ in development environment +- Maintain Node.js 20+ in development environment - Run `./scripts/check-mcp.sh` regularly - Document Node.js version requirements @@ -999,7 +999,7 @@ Playwright MCP defaults to Chromium. Other browsers require configuration. 3. Use cross-browser test script: ```bash - ./scripts/cross-browser-test.sh http://localhost:8080 + ./scripts/cross-browser-test.sh chromium http://localhost:8080 ``` 4. Ensure all browsers are installed: diff --git a/docs/PREREQUISITES.md b/docs/PREREQUISITES.md index 8f1d8b8..0f0325c 100644 --- a/docs/PREREQUISITES.md +++ b/docs/PREREQUISITES.md @@ -75,6 +75,27 @@ Or download from: https://claude.ai/code --- +### pnpm + +Package manager for the project's Node tooling (init wizard, tests, GUI, conversion pipelines). + +| | | +|---|---| +| **Required Version** | 9.x (project pins `pnpm@9.15.0`) | +| **Verify** | `pnpm --version` | +| **Expected** | `9.x.x` | + +**Install:** +```bash +npm install -g pnpm@9 +``` + +Or enable via Corepack (ships with Node.js): `corepack enable && corepack prepare pnpm@9.15.0 --activate` + +**Note:** pnpm requires Node.js 20+ (see Node.js below). + +--- + ## 2. Required Accounts & Access External services needed for full functionality. @@ -128,9 +149,9 @@ Required for Playwright MCP (browser automation and testing) configured in `.mcp | | | |---|---| -| **Minimum Version** | 18.0.0 (LTS) | +| **Minimum Version** | 20.0.0 (LTS) | | **Verify** | `node --version` | -| **Expected** | `v18.x.x` or `v20.x.x` | +| **Expected** | `v20.x.x` or higher | **Install:** - **All platforms:** https://nodejs.org/ @@ -405,17 +426,22 @@ Once all prerequisites are met: 1. **Clone the repository:** ```bash - git clone https://github.com/your-org/Flavian.git + git clone https://github.com/PMDevSolutions/Flavian.git cd Flavian ``` -2. **Start WordPress:** +2. **Create your `.env` file** (Docker DB credentials have no defaults, so this is required): + ```bash + cp .env.example .env # or run: pnpm run init + ``` + +3. **Start WordPress:** ```bash ./wordpress-local.sh start ./wordpress-local.sh install ``` -3. **Begin conversion:** +4. **Begin conversion:** Open Claude Code and provide your Figma URL See [QUICK-START.md](./QUICK-START.md) for the full getting started guide. diff --git a/docs/PREREQUISITES.validation.md b/docs/PREREQUISITES.validation.md index a5025e2..59db10e 100644 --- a/docs/PREREQUISITES.validation.md +++ b/docs/PREREQUISITES.validation.md @@ -219,7 +219,7 @@ WP-CLI 2.x.x **Required:** No (optional, for JavaScript tooling) -**Minimum Version:** 18.0.0 (LTS) +**Minimum Version:** 20.0.0 (LTS) **Verification Command:** ```bash @@ -228,12 +228,12 @@ node --version **Expected Output Pattern:** ``` -v18.x.x or v20.x.x +v20.x.x or higher ``` **Validation Logic:** 1. Command must execute successfully -2. Major version >= 18 +2. Major version >= 20 **Install Links:** - All platforms: https://nodejs.org/ diff --git a/docs/QUICK-START.md b/docs/QUICK-START.md index 3cdffb9..2b99462 100644 --- a/docs/QUICK-START.md +++ b/docs/QUICK-START.md @@ -49,7 +49,7 @@ All items required. If missing any, see the **[complete prerequisites guide](./P ### Step 1: Clone the Repository ```bash -git clone https://github.com/your-org/Flavian.git +git clone https://github.com/PMDevSolutions/Flavian.git cd Flavian ``` @@ -92,9 +92,11 @@ Claude works autonomously for 5-90 minutes. No prompts, no interruptions. Watch ### Step 5: View in WordPress -Start the local WordPress environment: +Start the local WordPress environment. **First time only**, create your `.env` file first — Docker reads the database credentials from it and has no built-in defaults, so the containers fail to start without it: ```bash +cp .env.example .env # or run: pnpm run init + ./wordpress-local.sh start ./wordpress-local.sh install # First time only ./wordpress-local.sh activate-theme your-theme-name @@ -103,7 +105,7 @@ Start the local WordPress environment: Open your browser: - **Site:** http://localhost:8080 -- **Admin:** http://localhost:8080/wp-admin (username: `admin`, password: `admin`) +- **Admin:** http://localhost:8080/wp-admin (username: `admin`, password: `changeme` — `WP_ADMIN_PASSWORD` in `.env`) --- diff --git a/docs/QUICK-START.validation.md b/docs/QUICK-START.validation.md index d041f41..f6d1d75 100644 --- a/docs/QUICK-START.validation.md +++ b/docs/QUICK-START.validation.md @@ -53,7 +53,7 @@ This document defines acceptance criteria for `QUICK-START.md`. Use this checkli ## Content Quality Criteria ### Brevity -- [x] Total document under 200 lines (193 lines) +- [x] Total document concise (~201 lines; nudged just past the 200 target by the required `.env` setup step) - [x] No section exceeds 30 lines - [x] No paragraphs exceed 3 sentences - [x] Uses bullet points over prose @@ -138,14 +138,15 @@ Verified files exist: - wordpress-local.sh Document metrics: -- Total lines: 193 (under 200 limit) +- Total lines: 201 (grew from 193 for the required `.env` setup step) - Sections: 6 main sections as required - Prerequisites: 4 items in checkbox format - Quick start steps: 5 numbered steps - Success indicators: 4 items - Role-based next steps: 3 roles covered -Minor note for future updates: -- git clone URL uses placeholder (your-org/Flavian) -- Update to actual repository URL when published +Resolved 2026-06-28: +- git clone URL now points to the real repo (PMDevSolutions/Flavian) +- Added an explicit `.env` creation step (`cp .env.example .env`) before WordPress start +- Admin login corrected to `admin` / `changeme` (WP_ADMIN_PASSWORD in `.env`) ``` diff --git a/docs/RELEASING.md b/docs/RELEASING.md index dfe9484..b654833 100644 --- a/docs/RELEASING.md +++ b/docs/RELEASING.md @@ -32,11 +32,13 @@ The Release PR is the human gate: no tag is created until it is merged. Section mapping is defined in [`release-please-config.json`](../release-please-config.json). -## Baseline +## Baseline (historical) -The manifest is seeded at `1.1.0`. Before merging the first release-please PR, -ensure a matching `v1.1.0` git tag exists on `main` so release-please has a clean -starting point for changelog generation. +The manifest was originally seeded at `1.1.0`, with a matching `v1.1.0` git tag on +`main` to give release-please a clean starting point for changelog generation. +That baseline is long established — the manifest now tracks the current release and +both `v1.0.0` and `v1.1.0` tags exist — so no action is needed here for normal +releases. ## Overrides @@ -67,10 +69,11 @@ theme `style.css` headers. ## Files involved - `release-please-config.json` — section mapping, release type, package config, - and the `extra-files` entry that mirrors the version into `package.json`. + and the `extra-files` entries that mirror the version into both `package.json` + and `packages/gui/package.json`. - `.release-please-manifest.json` — current version state. -- `package.json` — `version` field is kept in sync with the manifest by - release-please; never hand-edited. +- `package.json` (and `packages/gui/package.json`) — `version` field is kept in + sync with the manifest by release-please; never hand-edited. - `.github/workflows/release-please.yml` — opens / updates the Release PR and tags on merge. - `.github/workflows/commitlint.yml` — lints PR commit messages. diff --git a/docs/TROUBLESHOOTING.md b/docs/TROUBLESHOOTING.md index 5199e23..60797b3 100644 --- a/docs/TROUBLESHOOTING.md +++ b/docs/TROUBLESHOOTING.md @@ -218,38 +218,33 @@ Common issues and solutions for the Claude Code WordPress Template. --- -## Chrome DevTools MCP +## Lighthouse Audits -### Chrome DevTools MCP not connecting +Lighthouse runs through the project's Lighthouse CI tooling. There is **no +chrome-devtools MCP server configured** in [`.mcp.json`](../.mcp.json) — it ships +only `figma-desktop`, `figma`, and `playwright`. For browser automation use the +Playwright MCP (see the section above and +[MCP-TROUBLESHOOTING.md](./MCP-TROUBLESHOOTING.md)). -**Symptoms:** Chrome DevTools tools fail or time out +### Lighthouse audit fails -**Prerequisites:** -- Google Chrome must be running with remote debugging enabled -- The Chrome DevTools MCP server must be configured +**Symptoms:** A Lighthouse run errors out or returns incomplete results **Solutions:** -1. Launch Chrome with debugging: +1. Make sure WordPress is running and seeded first: ```bash - # Windows - "C:\Program Files\Google\Chrome\Application\chrome.exe" --remote-debugging-port=9222 - # macOS - /Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --remote-debugging-port=9222 + docker compose up -d wordpress db && bash tests/visual/seed.sh ``` -2. Verify Chrome is listening: +2. Run the audit + budget gate locally: ```bash - curl http://localhost:9222/json + pnpm lighthouse:run ``` -3. Check your Chrome DevTools MCP server is running and configured in `.mcp.json` +3. Give the page time to fully load (especially Docker WordPress sites) +4. If Chrome runs out of memory during the audit, close other applications/tabs -### Lighthouse audit fails - -**Symptoms:** `mcp__chrome-devtools__lighthouse_audit` errors out - -**Solutions:** -1. Ensure the target page is loaded first: use `navigate_page` before `lighthouse_audit` -2. Give the page time to fully load (especially Docker WordPress sites) -3. Check Chrome has enough memory (close other tabs) +> **Optional:** a Chrome DevTools MCP (Chrome launched with +> `--remote-debugging-port=9222`) is **not configured by default**. Only wire one +> into `.mcp.json` if you add such a server yourself. --- @@ -415,6 +410,6 @@ ls -la themes// ./vendor/bin/phpcs --standard=WordPress themes//functions.php # Check MCP connections -curl -s http://127.0.0.1:3845/mcp | head -c 100 # Figma -curl -s http://localhost:9222/json | head -c 100 # Chrome +curl -s http://127.0.0.1:3845/mcp | head -c 100 # Figma Desktop +curl -s https://mcp.figma.com/mcp | head -c 100 # Figma Remote ``` diff --git a/docs/architecture/PATTERN-FIRST-ARCHITECTURE.md b/docs/architecture/PATTERN-FIRST-ARCHITECTURE.md index 42bf2d0..3fc42df 100644 --- a/docs/architecture/PATTERN-FIRST-ARCHITECTURE.md +++ b/docs/architecture/PATTERN-FIRST-ARCHITECTURE.md @@ -1,6 +1,6 @@ -# Pattern-First FSE Architecture (UPDATE FOR figma-fse-converter) +# Pattern-First FSE Architecture -## CRITICAL: This should be added to figma-fse-converter agent at line 377 (after Component Mapping Strategy) +This document defines the pattern-first image architecture for WordPress FSE themes: images are rendered through PHP block patterns, never via inline `` tags in `.html` templates. It is the reference the figma-fse-converter agent follows during template generation, and the rule enforced by `scripts/figma-fse/validate-pattern-architecture.sh`. --- diff --git a/docs/docker-troubleshooting.md b/docs/docker-troubleshooting.md index a5a91d7..2193959 100644 --- a/docs/docker-troubleshooting.md +++ b/docs/docker-troubleshooting.md @@ -101,7 +101,7 @@ docker compose exec wordpress wp option update home "http://localhost:9090" --al 4. **Verify credentials match.** The `WORDPRESS_DB_*` variables in `docker-compose.yml` (or `.env`) must match the `MYSQL_*` variables: | WordPress var | Must match MySQL var | |---|---| - | `WORDPRESS_DB_HOST` | Service name (`db`) | + | `WORDPRESS_DB_HOST` | Service name (`db`, or `db:3306`) | | `WORDPRESS_DB_USER` | `MYSQL_USER` | | `WORDPRESS_DB_PASSWORD` | `MYSQL_PASSWORD` | | `WORDPRESS_DB_NAME` | `MYSQL_DATABASE` | @@ -382,9 +382,9 @@ docker-compose --version # V1 (standalone, legacy) ```bash docker compose ps db ``` -2. **Verify phpMyAdmin environment variables in `.env`:** - - `PMA_HOST` should be `db` (the Docker service name) - - `PMA_USER` and `PMA_PASSWORD` must match `MYSQL_USER` / `MYSQL_PASSWORD` +2. **Verify the phpMyAdmin connection settings:** + - `PMA_HOST` is hardcoded to `db` (the Docker service name) in `docker-compose.yml` — it is **not** a `.env` variable. + - `PMA_USER` and `PMA_PASSWORD` come from `.env` and must match `MYSQL_USER` / `MYSQL_PASSWORD`. 3. **Wait for MySQL to finish initialising** (30-60 seconds on first run). 4. **Restart phpMyAdmin:** ```bash @@ -404,7 +404,7 @@ docker-compose --version # V1 (standalone, legacy) 1. **Verify `.env` exists** in the project root alongside `docker-compose.yml`. 2. **Check syntax.** Each line should be `KEY=value` with no spaces around `=`: ```env - WORDPRESS_DB_HOST=db + WORDPRESS_DB_HOST=db:3306 WORDPRESS_DB_USER=wordpress WORDPRESS_DB_PASSWORD=wordpress WORDPRESS_DB_NAME=wordpress diff --git a/docs/figma-to-wordpress/README.md b/docs/figma-to-wordpress/README.md index 9352558..6679f81 100644 --- a/docs/figma-to-wordpress/README.md +++ b/docs/figma-to-wordpress/README.md @@ -260,9 +260,9 @@ WordPress FSE templates are `.html` files where **PHP code doesn't execute**. - Page-specific layouts - Template structure (header/footer references) -### Automatic Enforcement +### Pattern Validation -**Validation hook:** `scripts/figma-fse/validate-pattern-architecture.sh` +**Validation script:** `scripts/figma-fse/validate-pattern-architecture.sh` **Checks:** - ❌ No PHP code in `.html` templates @@ -271,9 +271,9 @@ WordPress FSE templates are `.html` files where **PHP code doesn't execute**. - ✅ Verifies referenced patterns exist **When it runs:** -- Automatically after every Write/Edit operation -- Blocks invalid changes before saving -- Agent sees validation errors and self-corrects +- Run manually, or invoked by the figma-fse-converter agent during conversion +- Not auto-registered in `.claude/settings.json` (the only PreToolUse Write|Edit hook is `validate-theme-location.sh`) +- Surfaces validation errors so the agent can self-correct --- diff --git a/docs/headless-wordpress/README.md b/docs/headless-wordpress/README.md index 68194c9..36fbf5c 100644 --- a/docs/headless-wordpress/README.md +++ b/docs/headless-wordpress/README.md @@ -19,17 +19,20 @@ Run WordPress as a content API (REST + WPGraphQL) and consume it from a decouple # 1. Bring up WordPress (if not already running) docker compose up -d -# 2. Install WPGraphQL + configure headless mode +# 2. Install WordPress (first run only — the installer below needs it) +./wordpress-local.sh install + +# 3. Install WPGraphQL + configure headless mode docker compose --profile headless up headless-installer # → prints WORDPRESS_PREVIEW_SECRET and JWT secret -# 3. Scaffold a Next.js frontend +# 4. Scaffold a Next.js frontend bash scripts/scaffold-frontend.sh my-app --name "My Site" -# 4. Configure and run the frontend +# 5. Configure and run the frontend cd frontend/my-app cp .env.local.example .env.local -# paste the values from step 2 into .env.local +# paste the values from step 3 into .env.local pnpm install && pnpm dev # → http://localhost:3000 ``` diff --git a/docs/mcp-setup.md b/docs/mcp-setup.md index 70ad281..54338a2 100644 --- a/docs/mcp-setup.md +++ b/docs/mcp-setup.md @@ -26,7 +26,7 @@ Before configuring MCP servers, ensure you have: - **Claude Desktop** installed and running ([download](https://claude.ai/download)) -- **Node.js 18+** installed (required for Playwright MCP) +- **Node.js 20+** installed (required for Playwright MCP) - **npx** available (ships with Node.js) - **Figma Desktop** installed (required for Figma Desktop MCP only) @@ -88,6 +88,15 @@ If the file doesn't exist, create it with an empty MCP servers object: Flavian uses three MCP servers. Add each one inside the `"mcpServers"` object in your `claude_desktop_config.json`. +> **⚠️ Verified vs. unverified config.** The **verified** Figma MCP configuration is the +> HTTP transport in this project's `.mcp.json` (used by Claude Code): `figma-desktop` → +> `http://127.0.0.1:3845/mcp` and `figma` (remote) → `https://mcp.figma.com/mcp`. The +> `@anthropic-ai/figma-mcp-server` npm package shown in the Figma examples below is an +> **unverified** stdio wrapper (the package name is not confirmed to exist). If your +> Claude Desktop build supports HTTP/remote MCP servers, prefer the `.mcp.json` URLs +> above; otherwise treat the npx examples as a starting point and substitute a wrapper +> you have verified. + ### 1. Figma Desktop MCP (Local) Connects to the Figma Desktop app running on your machine. This is the **preferred** Figma MCP server for development because it provides direct access to open files without authentication tokens. @@ -141,7 +150,7 @@ Connects to Figma's cloud MCP service. Use this as a **fallback** when Figma Des Enables browser automation for visual QA, screenshot capture, accessibility auditing, and end-to-end testing. **Requirements:** -- Node.js 18+ +- Node.js 20+ - Playwright browsers installed (auto-installed on first run, or manually via `npx playwright install`) **Configuration:** @@ -212,6 +221,11 @@ Here is a full `claude_desktop_config.json` with all three Flavian MCP servers: } ``` +> **Figma servers:** the `figma-desktop` / `figma` entries above use the unverified +> `@anthropic-ai/figma-mcp-server` package — see the warning under +> [Configuring MCP Servers](#configuring-mcp-servers). The verified transport is the HTTP +> config in `.mcp.json` (`http://127.0.0.1:3845/mcp`, `https://mcp.figma.com/mcp`). + > **Merging with existing servers:** If your `claude_desktop_config.json` already has other MCP servers configured, add the Flavian servers alongside them inside the existing `"mcpServers"` object. Do not create a second `"mcpServers"` key. --- diff --git a/docs/multisite/README.md b/docs/multisite/README.md index a0b6aa3..cb9c046 100644 --- a/docs/multisite/README.md +++ b/docs/multisite/README.md @@ -17,10 +17,13 @@ The repo ships an opt-in multisite installer that converts the local WordPress i # 1. Bring up WordPress (if not already running) docker compose up -d -# 2. Convert to multisite (subdirectory mode + sample second site) +# 2. Install WordPress (first run only — the installer below needs it) +./wordpress-local.sh install + +# 3. Convert to multisite (subdirectory mode + sample second site) docker compose --profile multisite up multisite-installer -# 3. Visit the network admin +# 4. Visit the network admin open http://localhost:8080/wp-admin/network/ ``` @@ -86,7 +89,7 @@ Subdomain mode (e.g. `site2.localhost`) needs the request to actually arrive at - A `/etc/hosts` entry per sub-site (`127.0.0.1 site2.localhost`). Easy but unmaintainable as you create more sites. - `dnsmasq` configured to wildcard-resolve `.localhost`. -The script bails out on `--subdomain` rather than silently producing a broken setup. If you need subdomain mode, set up wildcard DNS first, then in `wp-config.php`: +The script has no `--subdomain` flag — passing one is rejected as an unknown argument (the installer exits 2 with "Unknown argument"), rather than silently producing a broken setup. If you need subdomain mode, set up wildcard DNS first, then in `wp-config.php`: ```php define( 'SUBDOMAIN_INSTALL', true ); // was false diff --git a/docs/pipeline/indesign-output-generator.md b/docs/pipeline/indesign-output-generator.md index bb1df9c..12f52a6 100644 --- a/docs/pipeline/indesign-output-generator.md +++ b/docs/pipeline/indesign-output-generator.md @@ -20,6 +20,7 @@ It turns the design into a finished WordPress product: | `bin/import-media.sh` | WP-CLI script that imports staged assets into the media library. | | `bin/seed-content.sh` | (optional, `--seed-content`) one draft page per spread, populated with its pattern. | | `indesign-pipeline-report.md` | Produced files, unmapped IR nodes, and manual follow-ups. | +| `indesign-pipeline-report.json` | Machine-readable counterpart of the report (for tooling/CI). | ## Usage @@ -111,8 +112,8 @@ follow-up. | End-to-end on a fixture `.idml` produces a theme that loads in the Site Editor without PHP errors. | `generate-theme.mjs` writes a full theme dir; PHP files are a standard header + bootstrap and block markup with only `esc_url( get_theme_file_uri() )` interpolation. | | ≥1 pattern per spread appears under an "InDesign Imports" category. | One `patterns/spread-N.php` per spread, each `Categories: indesign-imports`; `functions.php` registers the category with the label **InDesign Imports**. | | `theme.json` round-trips through validation. | It is the token mapper's `merged` output, already validated against the WordPress schema (ajv + zod). | -| Report enumerates produced files and unmapped IR nodes. | `indesign-pipeline-report.md` — see the **Produced artifacts** and **Unmapped IR nodes** sections. | -| Snapshot tests cover two fixture spreads (text-heavy, image-heavy). | `tests/indesign/generate.test.mjs` snapshots `patterns/spread-1.php` (text) and `spread-2.php` (image), stored in `tests/indesign/__snapshots__/`. | +| Report enumerates produced files and unmapped IR nodes. | `indesign-pipeline-report.md` (plus a machine-readable `indesign-pipeline-report.json`) — see the **Produced artifacts** and **Unmapped IR nodes** sections. | +| Snapshot tests cover two fixture spreads (text-heavy, image-heavy). | `packages/pipeline/tests/indesign/generate.test.mjs` snapshots `patterns/spread-1.php` (text) and `spread-2.php` (image), stored in `packages/pipeline/tests/indesign/__snapshots__/`. | | Patterns are deterministic given the same IR. | `generateTheme` is pure; a determinism test asserts two runs are byte-identical. | ## Testing diff --git a/docs/pipeline/indesign-token-mapper.md b/docs/pipeline/indesign-token-mapper.md index ef77294..3bd26ea 100644 --- a/docs/pipeline/indesign-token-mapper.md +++ b/docs/pipeline/indesign-token-mapper.md @@ -125,7 +125,7 @@ block-theme JSON Schema (via ajv) and a zod schema for the emitted subset. | Palette includes all distinct swatches, deduped by hex within tolerance | `map/colors.js`. | | Each typography entry referenced by ≥1 paragraph style | The scale is built from paragraph styles; `report.provenance.styleToSlug` records the mapping. | | Font fallback warnings emitted and listed in the report | `map/fonts.js` → `report.fontFallbacks`. | -| Tests cover CMYK→sRGB, clustering, merge-with-base | `tests/indesign/color.test.mjs`, `map-typography.test.mjs`, `map-theme-json.test.mjs`. | +| Tests cover CMYK→sRGB, clustering, merge-with-base | `packages/pipeline/tests/indesign/color.test.mjs`, `map-typography.test.mjs`, `map-theme-json.test.mjs`. | | Works on either IR | Source-agnostic; the end-to-end test runs on both an IDML- and a PDF-built IR. | ## Known limitations diff --git a/docs/pipelines/indesign.md b/docs/pipelines/indesign.md index 51e32ea..2362afb 100644 --- a/docs/pipelines/indesign.md +++ b/docs/pipelines/indesign.md @@ -5,7 +5,7 @@ block patterns (one per spread), templates, header/footer parts, a schema-valid `theme.json`, asset-import scripts, and a generation report. This is the user-facing guide. For the internals, see the package docs: -[IDML parser & IR](../pipeline/indesign-pdf-fidelity.md), +[IDML parser & IR](../../packages/pipeline/README.md), [token mapper](../pipeline/indesign-token-mapper.md), and [output generator](../pipeline/indesign-output-generator.md). diff --git a/scripts/README.md b/scripts/README.md index 8944be4..87752b7 100644 --- a/scripts/README.md +++ b/scripts/README.md @@ -307,7 +307,7 @@ When adding new hooks: ### `setup-playwright.sh` - **Purpose**: One-time setup — installs Playwright and Chromium, Firefox, WebKit browser engines - **Run**: `./scripts/setup-playwright.sh` -- **Requirements**: Node.js 18+ +- **Requirements**: Node.js 20+ ### `cross-browser-test.sh` - **Purpose**: Captures screenshots at 4 breakpoints (1920, 1440, 768, 375px) for a given browser engine diff --git a/scripts/check-prerequisites.sh b/scripts/check-prerequisites.sh index c4a7109..53b8593 100644 --- a/scripts/check-prerequisites.sh +++ b/scripts/check-prerequisites.sh @@ -32,7 +32,7 @@ SYSTEM_FAIL=0 # Minimum versions MIN_GIT_VERSION="2.30.0" MIN_DOCKER_VERSION="4.0.0" -MIN_NODE_VERSION="18.0.0" +MIN_NODE_VERSION="20.0.0" MIN_PHP_VERSION="8.1" MIN_COMPOSER_VERSION="2.0.0" MIN_WPCLI_VERSION="2.8.0"