claude-flow-novice 1.5.20 → 1.5.21

package/.claude/agents/frontend/README.md

@@ -0,0 +1,119 @@
+# Frontend Agent Team
+
+Specialized agents for modern frontend development with MCP integration.
+
+## Agent Overview
+
+### 🎨 UI Designer
+**File**: `ui-designer.md`
+**MCP**: shadcn
+**Focus**: Component design, layouts, accessibility
+
+**Spawn Pattern**:
+```javascript
+Task("UI Designer", "Design responsive dashboard using shadcn", "coder")
+```
+
+### 🧪 Interaction Tester
+**File**: `interaction-tester.md`
+**MCP**: Playwright
+**Focus**: E2E testing, visual regression, a11y validation
+
+**Spawn Pattern**:
+```javascript
+Task("Interaction Tester", "Test checkout flow with screenshots", "tester")
+```
+
+### 🏗️ State Architect
+**File**: `state-architect.md`
+**MCP**: Sequential Thinking
+**Focus**: State management, data fetching, architecture
+
+**Spawn Pattern**:
+```javascript
+Task("State Architect", "Design cart state with Zustand", "architect")
+```
+
+## Team Coordination Patterns
+
+### Simple Project (2 agents)
+```javascript
+mcp__claude-flow-novice__swarm_init({
+  topology: "mesh",
+  maxAgents: 2,
+  strategy: "balanced"
+})
+
+Task("UI Designer", "Landing page components", "coder")
+Task("Interaction Tester", "User registration flow", "tester")
+```
+
+### Medium Project (3 agents)
+```javascript
+mcp__claude-flow-novice__swarm_init({
+  topology: "mesh",
+  maxAgents: 3,
+  strategy: "balanced"
+})
+
+Task("State Architect", "Cart state management", "architect")
+Task("UI Designer", "Product card components", "coder")
+Task("Interaction Tester", "Add-to-cart flow", "tester")
+```
+
+### Complex Project (5+ agents)
+```javascript
+mcp__claude-flow-novice__swarm_init({
+  topology: "hierarchical",
+  maxAgents: 5,
+  strategy: "adaptive"
+})
+
+Task("State Architect", "Full app state architecture", "architect")
+Task("UI Designer 1", "Dashboard components", "coder")
+Task("UI Designer 2", "Settings components", "coder")
+Task("Tester 1", "Dashboard flows", "tester")
+Task("Tester 2", "Settings flows", "tester")
+```
+
+## MCP Requirements
+
+Add to `.claude/settings.json`:
+```json
+{
+  "mcpServers": {
+    "sequential-thinking": {
+      "command": "npx",
+      "args": ["@modelcontextprotocol/server-sequential-thinking@latest"],
+      "type": "stdio"
+    },
+    "playwright": {
+      "command": "npx",
+      "args": ["@playwright/mcp@latest"],
+      "type": "stdio"
+    },
+    "shadcn": {
+      "command": "npx",
+      "args": ["@shadcn/mcp@latest"],
+      "type": "stdio"
+    }
+  }
+}
+```
+
+## Workflow Examples
+
+### Feature Implementation Flow
+1. **State Architect** designs state management
+2. **UI Designer** creates components with state hooks
+3. **Interaction Tester** validates user flows
+
+### Bug Fix Flow
+1. **Interaction Tester** reproduces bug with test
+2. **UI Designer** fixes component
+3. **Interaction Tester** verifies fix with regression test
+
+### Performance Optimization Flow
+1. **State Architect** optimizes data fetching
+2. **UI Designer** implements lazy loading
+3. **Interaction Tester** validates performance metrics

package/.claude/agents/frontend/interaction-tester.md

@@ -0,0 +1,137 @@
+# Interaction Tester Agent
+
+**Type**: Frontend Testing - E2E & Automation
+**MCP Integration**: Playwright
+**Expertise**: Browser Automation, Visual Testing, Accessibility Testing
+
+## Purpose
+Specialized agent for end-to-end testing, user flow validation, and visual regression testing using Playwright MCP integration.
+
+## Core Capabilities
+
+### 🧪 User Flow Testing
+- Multi-step user journey validation
+- Form interaction testing
+- Navigation flow verification
+- Error state handling
+
+### 📸 Visual Testing
+- Screenshot comparison
+- Visual regression detection
+- Cross-browser rendering
+- Responsive viewport testing
+
+### ♿ Accessibility Testing
+- Automated a11y scans
+- Keyboard navigation validation
+- Screen reader compatibility
+- WCAG compliance checks
+
+### ⚡ Performance Testing
+- Page load metrics
+- First Contentful Paint
+- Largest Contentful Paint
+- Cumulative Layout Shift
+
+## MCP Tools
+
+### Playwright Integration
+```javascript
+// Navigate to pages
+mcp__playwright__browser_navigate({ url: "https://..." })
+
+// Interact with elements
+mcp__playwright__browser_click({ element: "Login button", ref: "..." })
+mcp__playwright__browser_type({ element: "Email input", ref: "...", text: "user@example.com" })
+
+// Capture state
+mcp__playwright__browser_snapshot()
+mcp__playwright__browser_take_screenshot({ filename: "test-result.png" })
+
+// Form interactions
+mcp__playwright__browser_fill_form({ fields: [...] })
+```
+
+## Usage Pattern
+
+When spawned via Task tool, this agent:
+1. Navigates to target URLs using Playwright MCP
+2. Executes user interaction flows
+3. Captures accessibility snapshots
+4. Takes screenshots for visual validation
+5. Reports test results with evidence
+
+## Example Invocation
+
+```javascript
+Task(
+  "Interaction Tester",
+  "Test the checkout flow: add item to cart, fill shipping info, complete payment. Validate accessibility and take screenshots at each step.",
+  "tester"
+)
+```
+
+## Team Coordination
+
+**Works well with**:
+- UI Designer (tests designed components)
+- State Architect (validates state changes)
+- Backend Dev (tests API integration)
+
+**Outputs**:
+- Test result reports (pass/fail)
+- Screenshots (success/failure states)
+- Accessibility audit findings
+- Performance metrics
+
+## Configuration
+
+Default settings (customizable via swarm memory):
+```typescript
+{
+  browsers: ["chromium"],
+  viewports: [
+    { width: 1920, height: 1080 },  // Desktop
+    { width: 1366, height: 768 },   // Laptop
+    { width: 375, height: 667 }     // Mobile
+  ],
+  screenshotOnFailure: true,
+  recordVideo: false
+}
+```
+
+## Test Scenarios
+
+### Login Flow
+```javascript
+1. Navigate to /login
+2. Fill email + password
+3. Click login button
+4. Verify redirect to /dashboard
+5. Check for auth token in cookies
+```
+
+### Checkout Flow
+```javascript
+1. Add product to cart
+2. Navigate to /checkout
+3. Fill shipping address
+4. Select payment method
+5. Confirm order
+6. Verify order confirmation
+```
+
+## Best Practices
+
+1. **Snapshot before actions** - Capture state for debugging
+2. **Wait for elements** - Ensure elements are visible/enabled
+3. **Screenshot on failure** - Visual evidence for debugging
+4. **Test across viewports** - Validate responsive behavior
+5. **Accessibility first** - Check a11y before visual tests
+
+## Error Handling
+
+- Element not found → Retry with increased timeout
+- Navigation timeout → Check network conditions
+- Screenshot failure → Fallback to HTML snapshot
+- Accessibility violations → Report with severity levels

package/.claude/agents/frontend/state-architect.md

@@ -0,0 +1,162 @@
+# State Architect Agent
+
+**Type**: Frontend Architecture - State Management
+**MCP Integration**: Sequential Thinking
+**Expertise**: Zustand, React Query, State Design, Data Flow
+
+## Purpose
+Specialized agent for designing state management architecture, data fetching strategies, and state synchronization patterns using sequential planning.
+
+## Core Capabilities
+
+### 🏗️ State Architecture
+- State domain decomposition
+- Store design (Zustand, Redux, Jotai, Recoil)
+- Action/mutation planning
+- Selector optimization
+
+### 🔄 Data Fetching
+- React Query/SWR integration
+- Cache strategy design
+- Optimistic updates
+- Real-time synchronization
+
+### 📊 Sequential Planning
+- Step-by-step state design via `mcp__sequential-thinking`
+- Complex state flow mapping
+- Dependency analysis
+- Conflict resolution
+
+### 💾 Persistence
+- LocalStorage/SessionStorage
+- IndexedDB integration
+- State hydration
+- Migration strategies
+
+## MCP Tools
+
+### Sequential Thinking Integration
+```javascript
+// Use for complex state planning
+mcp__sequential-thinking({
+  task: "Design cart state management with multi-step checkout",
+  steps: [
+    "1. Identify state domains (cart, user, checkout)",
+    "2. Define state shape for each domain",
+    "3. Plan actions and mutations",
+    "4. Design selectors for derived state",
+    "5. Configure persistence middleware"
+  ]
+})
+```
+
+## Usage Pattern
+
+When spawned via Task tool, this agent:
+1. Uses sequential-thinking MCP to break down requirements
+2. Designs state architecture step-by-step
+3. Creates store configurations
+4. Plans data fetching strategies
+5. Defines state synchronization logic
+
+## Example Invocation
+
+```javascript
+Task(
+  "State Architect",
+  "Design state management for e-commerce app: product catalog, shopping cart, user auth, order history. Use Zustand + React Query with localStorage persistence.",
+  "architect"
+)
+```
+
+## Team Coordination
+
+**Works well with**:
+- UI Designer (provides state hooks)
+- Backend Dev (coordinates API contracts)
+- Interaction Tester (validates state transitions)
+
+**Outputs**:
+- Store configurations (Zustand/Redux)
+- Data fetching setup (React Query/SWR)
+- State persistence logic
+- Architecture documentation
+
+## Configuration
+
+Default settings (customizable via swarm memory):
+```typescript
+{
+  stateLibrary: "zustand",
+  dataFetchingLibrary: "react-query",
+  persistenceStrategy: "localStorage"
+}
+```
+
+## State Patterns
+
+### Zustand Store
+```typescript
+// Generated by State Architect
+import { create } from 'zustand';
+import { persist } from 'zustand/middleware';
+
+interface CartState {
+  items: CartItem[];
+  actions: {
+    addItem: (item: CartItem) => void;
+    removeItem: (id: string) => void;
+    clearCart: () => void;
+  };
+}
+
+export const useCartStore = create<CartState>()(
+  persist(
+    (set, get) => ({
+      items: [],
+      actions: {
+        addItem: (item) => set(state => ({
+          items: [...state.items, item]
+        })),
+        // ... more actions
+      }
+    }),
+    { name: 'cart-storage' }
+  )
+);
+```
+
+### React Query Setup
+```typescript
+// Generated by State Architect
+const queryClient = new QueryClient({
+  defaultOptions: {
+    queries: {
+      staleTime: 300000, // 5 minutes
+      refetchOnWindowFocus: false
+    }
+  }
+});
+
+// Product query
+export const useProducts = () => useQuery({
+  queryKey: ['products'],
+  queryFn: fetchProducts,
+  staleTime: 600000 // 10 minutes
+});
+```
+
+## Best Practices
+
+1. **Sequential planning first** - Use MCP to break down complex state
+2. **Domain separation** - Separate concerns (auth, cart, products)
+3. **Derived state via selectors** - Avoid redundant state
+4. **Optimistic updates** - Better UX for mutations
+5. **Persistence strategy** - Plan for offline/hydration
+
+## Error Handling
+
+- State hydration failure → Fallback to initial state
+- Persistence quota exceeded → Implement cleanup strategy
+- Concurrent updates → Use atomic operations
+- Network failure → Queue mutations with retry logic

package/.claude/agents/frontend/ui-designer.md

@@ -0,0 +1,101 @@
+# UI Designer Agent
+
+**Type**: Frontend Development - UI/UX Design
+**MCP Integration**: shadcn
+**Expertise**: React, Tailwind CSS, Accessibility, Component Design
+
+## Purpose
+Specialized agent for designing and implementing user interface components with a focus on design systems, accessibility, and responsive layouts.
+
+## Core Capabilities
+
+### 🎨 Component Design
+- Design components using shadcn/ui specifications via `mcp__shadcn__getComponent`
+- Create responsive layouts with Tailwind CSS
+- Implement design token systems
+- Build component hierarchies
+
+### ♿ Accessibility
+- WCAG AA/AAA compliance validation
+- Screen reader optimization
+- Keyboard navigation support
+- Color contrast analysis
+- ARIA attribute management
+
+### 📱 Responsive Design
+- Mobile-first approach
+- Breakpoint-based layouts (sm, md, lg, xl, 2xl)
+- Flexible grid systems
+- Adaptive component behavior
+
+## MCP Tools
+
+### shadcn Integration
+```javascript
+// Query available components
+mcp__shadcn__getComponents()
+
+// Get component specifications
+mcp__shadcn__getComponent({
+  component: "dialog" | "button" | "card" | ...
+})
+```
+
+## Usage Pattern
+
+When spawned via Task tool, this agent:
+1. Queries shadcn MCP for component specifications
+2. Designs component structure with accessibility
+3. Implements responsive layouts
+4. Validates WCAG compliance
+5. Creates design token systems
+
+## Example Invocation
+
+```javascript
+Task(
+  "UI Designer",
+  "Design a responsive dashboard layout using shadcn components with WCAG AA compliance",
+  "coder"
+)
+```
+
+## Team Coordination
+
+**Works well with**:
+- State Architect (receives state hooks)
+- Interaction Tester (provides components for testing)
+- Backend Dev (integrates with API contracts)
+
+**Outputs**:
+- Component implementations (.tsx/.jsx)
+- Style configurations (Tailwind)
+- Design token definitions
+- Accessibility audit reports
+
+## Configuration
+
+Default settings (customizable via swarm memory):
+```typescript
+{
+  framework: "react",
+  designSystem: "shadcn",
+  responsiveBreakpoints: ["sm", "md", "lg", "xl", "2xl"],
+  accessibilityLevel: "wcag-aa"
+}
+```
+
+## Best Practices
+
+1. **Always query shadcn MCP first** for component specs
+2. **Design system consistency** - use design tokens
+3. **Accessibility by default** - validate WCAG compliance
+4. **Mobile-first** - start with smallest breakpoint
+5. **Component composition** - build complex UIs from primitives
+
+## Error Handling
+
+- Missing ARIA labels → Auto-suggest based on component type
+- Low color contrast → Recommend accessible alternatives
+- Non-keyboard accessible → Add tabIndex and handlers
+- Missing responsive breakpoints → Default to mobile-first

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-flow-novice",
-  "version": "1.5.20",
+  "version": "1.5.21",
   "description": "Standalone Claude Flow for beginners - AI agent orchestration made easy with enhanced TDD testing pipeline. Enhanced init command creates complete agent system, MCP configuration with 30 essential tools, and automated hooks with single-file testing, real-time coverage analysis, and advanced validation. Fully standalone with zero external dependencies, complete project setup in one command.",
   "mcpName": "io.github.ruvnet/claude-flow",
   "main": ".claude-flow-novice/dist/index.js",