PMDevSolutions · PAMulligan · Jun 29, 2026 · Jun 29, 2026
diff --git 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
@@ -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,12 +369,12 @@ 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)
 - ux-researcher (research only)
 
 ---
 
-**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
@@ -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
@@ -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*