ruvnet-kb-first 6.1.0 → 6.2.0

package/SKILL.md

@@ -1,13 +1,51 @@
-Updated: 2026-01-02 10:15:00 EST | Version 6.0.0
+Updated: 2026-01-02 10:35:00 EST | Version 6.2.0
 Created: 2026-01-01 15:00:00 EST
 
-# RuvNet KB-First Application Builder v6.0
+# RuvNet KB-First Application Builder v6.2
 
-## Score-Driven Architecture: Scoring IS Enforcement
+## Score-Driven Architecture: Scoring IS Enforcement + UX Excellence
 
-**Version:** 6.0.0
+**Version:** 6.2.0
 **NPM Package:** `ruvnet-kb-first`
-**Philosophy:** Every operation requires baseline scoring. Every change shows delta. Negative delta BLOCKS progress. No shortcuts.
+**Philosophy:** Every operation requires baseline scoring. Every change shows delta. Negative delta BLOCKS progress. No shortcuts. **NEW:** Applications must be excellent, not just functional.
+
+---
+
+## What's New in v6.2.0 - UX Excellence
+
+| Feature | Description |
+|---------|-------------|
+| **UX Quality Dimension** | 7th KB dimension: Visual design, emotional appeal, user flow |
+| **Phase 12: UX Quality Review** | Playwright-based end-user perspective audit |
+| **`kb_first_ux_review` Tool** | Captures screenshots, checks versioning, critical review |
+| **Version Display Check** | Verifies version in header/footer (major.minor.patch) |
+| **Cache-Busting Check** | Ensures users see latest version, not cached content |
+| **Critical Review Questions** | How good? How could it be better? Where falling down? What would excellent look like? |
+| **Playwright Auto-Install** | Offers to install Playwright if not present |
+
+### The 6 MCP Tools (v6.2)
+
+| Tool | Purpose | When to Use |
+|------|---------|-------------|
+| `kb_first_assess` | Score ALL dimensions (7 KB + 13 Phases) | **FIRST** - before any work |
+| `kb_first_plan` | Generate enhancement plan with predictions | After assess, shows gaps |
+| `kb_first_confirm` | User confirms readiness to proceed | Before execution |
+| `kb_first_execute` | Execute plan phase by phase | After confirmation |
+| `kb_first_verify` | Compare predicted vs actual, recursive until 98+ | After execution |
+| `kb_first_ux_review` | Playwright-based visual quality audit | **NEW** - for UX excellence |
+
+### UX Quality Criteria (Scored in UX Review)
+
+| Criterion | Weight | Checks |
+|-----------|--------|--------|
+| Version Display | 15% | Header/footer shows major.minor.patch |
+| Cache Management | 10% | Version change detection, user notification |
+| Visual Design Excellence | 20% | Typography, color, spacing, not generic AI look |
+| Emotional Appeal | 15% | Creates confidence, celebrates success, softens errors |
+| Loading States | 10% | Skeleton loaders, progress indicators, graceful |
+| Error Handling UX | 10% | Clear messages, actionable, no technical jargon |
+| User Flow | 10% | Intuitive navigation, clear CTAs, minimal friction |
+| Accessibility | 10% | Keyboard nav, screen reader, contrast, focus |
 
 ---
 
@@ -22,7 +60,7 @@ Created: 2026-01-01 15:00:00 EST
 | **Baseline Requirement** | Cannot start work without establishing baseline |
 | **Automatic Refresh** | Baseline resets after each gate passage |
 
-### The 4 MCP Tools
+### The Original 4 MCP Tools (v6.0)
 
 | Tool | Purpose | When to Use |
 |------|---------|-------------|

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ruvnet-kb-first",
-  "version": "6.1.0",
+  "version": "6.2.0",
   "description": "RuvNet KB-First Application Builder - Build intelligent applications on expert knowledge",
   "type": "module",
   "main": "src/index.js",

package/src/mcp-server.js

@@ -1,20 +1,22 @@
 /**
  * RuvNet KB-First MCP Server - Granular Score-Driven Architecture
- * Version 6.1.0
+ * Version 6.2.0
  *
  * PHILOSOPHY: Granular scoring drives discipline.
- * - Score each KB dimension 1-100 (completeness, depth, comprehensiveness, accuracy, freshness)
- * - Score each phase readiness 1-100
+ * - Score each KB dimension 1-100 (completeness, depth, comprehensiveness, accuracy, freshness, attribution, ux_quality)
+ * - Score each phase readiness 1-100 (including Phase 12: UX Quality Review)
  * - Generate enhancement plan based on gaps
  * - User confirms before execution
  * - Post-verify: did we hit predicted scores?
+ * - Playwright UX Review: Visual quality audit from end-user perspective
  *
- * 5 Tools:
- *   1. kb_first_assess   - Score ALL dimensions (KB quality + phase readiness)
- *   2. kb_first_plan     - Generate enhancement plan with predicted improvements
- *   3. kb_first_confirm  - User confirms readiness, locks in plan
- *   4. kb_first_execute  - Execute plan phase by phase
- *   5. kb_first_verify   - Post-verification: predicted vs actual, identify gaps
+ * 6 Tools:
+ *   1. kb_first_assess     - Score ALL dimensions (KB quality + phase readiness)
+ *   2. kb_first_plan       - Generate enhancement plan with predicted improvements
+ *   3. kb_first_confirm    - User confirms readiness, locks in plan
+ *   4. kb_first_execute    - Execute plan phase by phase
+ *   5. kb_first_verify     - Post-verification: predicted vs actual, identify gaps
+ *   6. kb_first_ux_review  - Playwright-based UX quality audit with screenshots
  *
  * Usage:
  *   npx ruvnet-kb-first mcp
@@ -26,7 +28,7 @@ import { globSync } from 'glob';
 
 const MCP_VERSION = '0.1.0';
 const SERVER_NAME = 'ruvnet-kb-first';
-const SERVER_VERSION = '6.1.0';
+const SERVER_VERSION = '6.2.0';
 
 /**
  * KB Quality Dimensions (each scored 1-100)
@@ -61,6 +63,11 @@ const KB_DIMENSIONS = {
     name: 'Attribution',
     description: 'Are sources and experts properly cited?',
     weight: 10
+  },
+  ux_quality: {
+    name: 'UX Quality',
+    description: 'Is the user experience excellent? Visual design, emotional appeal, user flow, versioning display, loading states, error handling, accessibility.',
+    weight: 15
   }
 };
 
@@ -119,6 +126,21 @@ const PHASES = {
   11: {
     name: 'Deployment',
     criteria: ['Infrastructure ready', 'Environments configured', 'CI/CD built', 'Migrations run', 'Monitoring active', 'Go-live complete']
+  },
+  12: {
+    name: 'UX Quality Review',
+    criteria: [
+      'Version displayed in header/footer (major.minor.patch)',
+      'Cache-busting implemented with version notifications',
+      'Visual design excellence (not just functional)',
+      'Emotional appeal and user psychology considered',
+      'Loading states are elegant',
+      'Error messages are helpful and actionable',
+      'User flow is intuitive and compelling',
+      'Playwright screenshots reviewed and critiqued',
+      'Accessibility verified (WCAG 2.1 AA)',
+      'Mobile responsiveness tested'
+    ]
   }
 };
 
@@ -221,6 +243,53 @@ This closes the loop and ensures you delivered what you promised.`,
         detailed: { type: 'boolean', description: 'Show detailed comparison', default: true }
       }
     }
+  },
+  {
+    name: 'kb_first_ux_review',
+    description: `Playwright-based UX Quality Audit - End-user perspective review.
+
+Walks through the application as an end user, capturing screenshots.
+Then critically reviews EACH screenshot:
+
+For each screen:
+- How good is this? (1-100 score)
+- How could we make it better? (specific recommendations)
+- Where is it falling down? (issues identified)
+- What would EXCELLENT look like? (vision for improvement)
+- Recommendations with priority
+
+Also checks critical UX requirements:
+- Version number displayed in header/footer (major.minor.patch)
+- Cache-busting with version change notifications
+- Loading states are elegant, not jarring
+- Error messages are helpful and guide user to resolution
+- Visual design creates emotional appeal, not just functional
+- User psychology leveraged for compelling flow
+
+This ensures the application isn't just functional—it's EXCELLENT.`,
+    inputSchema: {
+      type: 'object',
+      properties: {
+        appUrl: { type: 'string', description: 'URL of the running application to review' },
+        flows: {
+          type: 'array',
+          items: { type: 'string' },
+          description: 'User flows to test (e.g., ["login", "search", "checkout"])',
+          default: ['homepage', 'main_flow']
+        },
+        screenshotDir: {
+          type: 'string',
+          description: 'Directory to save screenshots',
+          default: '.ruvector/ux-review'
+        },
+        criticalReview: {
+          type: 'boolean',
+          description: 'Perform deep critical review of each screenshot',
+          default: true
+        }
+      },
+      required: ['appUrl']
+    }
   }
 ];
 
@@ -351,6 +420,50 @@ function scoreKBDimensions(cwd) {
     improvement: attributionScore < 80 ? 'Add KB citations to code files' : 'Good attribution'
   };
 
+  // UX Quality: Based on presence of UX-related artifacts
+  let uxScore = 0;
+  const packagePath = join(cwd, 'package.json');
+  const uxReviewPath = join(cwd, '.ruvector', 'ux-review');
+
+  // Check for version in package.json
+  if (existsSync(packagePath)) {
+    try {
+      const pkg = JSON.parse(readFileSync(packagePath, 'utf-8'));
+      if (pkg.version) uxScore += 15; // Versioning exists
+    } catch {}
+  }
+
+  // Check for prior UX review
+  if (existsSync(uxReviewPath)) {
+    try {
+      const reviewFiles = readdirSync(uxReviewPath);
+      if (reviewFiles.length > 0) uxScore += 25; // UX review conducted
+      if (reviewFiles.some(f => f.includes('review-report'))) uxScore += 20; // Detailed review exists
+    } catch {}
+  }
+
+  // Check for accessibility considerations
+  if (existsSync(srcDir)) {
+    try {
+      const files = globSync('**/*.{tsx,jsx,html}', { cwd: srcDir });
+      let a11yScore = 0;
+      for (const f of files) {
+        try {
+          const content = readFileSync(join(srcDir, f), 'utf-8');
+          if (content.includes('aria-') || content.includes('role=')) a11yScore += 5;
+          if (content.includes('alt=') || content.includes('loading=')) a11yScore += 3;
+        } catch {}
+      }
+      uxScore += Math.min(40, a11yScore);
+    } catch {}
+  }
+
+  scores.ux_quality = {
+    score: Math.min(100, uxScore),
+    reason: uxScore >= 60 ? 'UX review conducted, accessibility present' : 'Limited UX review artifacts',
+    improvement: uxScore < 80 ? 'Run kb_first_ux_review for Playwright-based UX audit' : 'Good UX coverage'
+  };
+
   return scores;
 }
 
@@ -941,6 +1054,296 @@ async function handleVerify(cwd, args) {
   return result;
 }
 
+/**
+ * UX Review Criteria for critical evaluation
+ */
+const UX_CRITERIA = {
+  versioning: {
+    name: 'Version Display',
+    checks: ['Header shows version', 'Footer shows version', 'Format: major.minor.patch'],
+    weight: 15
+  },
+  caching: {
+    name: 'Cache Management',
+    checks: ['Version change detection', 'User notification on updates', 'Force refresh capability'],
+    weight: 10
+  },
+  visual_design: {
+    name: 'Visual Design Excellence',
+    checks: ['Professional typography', 'Cohesive color palette', 'Proper spacing/hierarchy', 'Not generic AI aesthetic'],
+    weight: 20
+  },
+  emotional_appeal: {
+    name: 'Emotional Appeal',
+    checks: ['Creates confidence', 'Guides without confusion', 'Celebrates success states', 'Softens error states'],
+    weight: 15
+  },
+  loading_states: {
+    name: 'Loading States',
+    checks: ['Skeleton loaders present', 'Progress indicators', 'No jarring transitions', 'Graceful degradation'],
+    weight: 10
+  },
+  error_handling: {
+    name: 'Error Handling UX',
+    checks: ['Clear error messages', 'Actionable next steps', 'Recovery paths provided', 'No technical jargon'],
+    weight: 10
+  },
+  user_flow: {
+    name: 'User Flow',
+    checks: ['Intuitive navigation', 'Clear call-to-actions', 'Logical progression', 'Minimal friction'],
+    weight: 10
+  },
+  accessibility: {
+    name: 'Accessibility',
+    checks: ['Keyboard navigation', 'Screen reader compatible', 'Color contrast', 'Focus indicators'],
+    weight: 10
+  }
+};
+
+/**
+ * Detect available frontend-design skills
+ */
+function detectFrontendDesignSkills() {
+  const homeDir = process.env.HOME || process.env.USERPROFILE || '';
+  const skillsDir = join(homeDir, '.claude', 'skills');
+  const skills = {
+    preferred: null,
+    available: [],
+    recommendation: null
+  };
+
+  // Check for frontend-design-Stu (preferred)
+  if (existsSync(join(skillsDir, 'frontend-design-Stu.md'))) {
+    skills.preferred = 'frontend-design-Stu';
+    skills.available.push('frontend-design-Stu');
+  }
+
+  // Check for frontend-design
+  if (existsSync(join(skillsDir, 'frontend-design.md'))) {
+    if (!skills.preferred) {
+      skills.preferred = 'frontend-design';
+    }
+    skills.available.push('frontend-design');
+  }
+
+  // Generate recommendation if no skills found
+  if (skills.available.length === 0) {
+    skills.recommendation = {
+      message: 'No frontend-design skill installed. For UX excellence, install the Anthropic frontend-design skill.',
+      installation: 'Visit: https://github.com/anthropics/claude-code-plugins and install frontend-design plugin',
+      benefit: 'Creates distinctive, production-grade interfaces that avoid generic AI aesthetics'
+    };
+  }
+
+  return skills;
+}
+
+/**
+ * Handle UX Review with Playwright
+ */
+async function handleUXReview(cwd, args) {
+  const { appUrl, flows = ['homepage', 'main_flow'], screenshotDir = '.ruvector/ux-review', criticalReview = true } = args;
+
+  // Check for frontend-design skills
+  const designSkills = detectFrontendDesignSkills();
+
+  // Check if Playwright is installed
+  let playwrightAvailable = false;
+  try {
+    await import('playwright');
+    playwrightAvailable = true;
+  } catch {
+    // Playwright not installed
+  }
+
+  if (!playwrightAvailable) {
+    return {
+      action: 'PLAYWRIGHT_REQUIRED',
+      status: 'INSTALLATION_NEEDED',
+      message: 'Playwright is required for UX review but not installed.',
+      installation: {
+        command: 'npm install playwright && npx playwright install chromium',
+        description: 'Installs Playwright and Chromium browser for screenshot capture',
+        automated: 'Run this command, then re-run kb_first_ux_review'
+      },
+      designSkills: designSkills,
+      alternative: {
+        message: 'Alternatively, you can manually capture screenshots and place them in:',
+        directory: join(cwd, screenshotDir),
+        format: 'Name format: 01-homepage.png, 02-login.png, etc.',
+        thenRun: 'Re-run kb_first_ux_review with criticalReview=true to analyze'
+      }
+    };
+  }
+
+  // Create screenshot directory
+  const screenshotPath = join(cwd, screenshotDir);
+  if (!existsSync(screenshotPath)) {
+    mkdirSync(screenshotPath, { recursive: true });
+  }
+
+  // Capture screenshots using Playwright
+  const screenshots = [];
+  try {
+    const { chromium } = await import('playwright');
+    const browser = await chromium.launch();
+    const context = await browser.newContext({
+      viewport: { width: 1920, height: 1080 }
+    });
+    const page = await context.newPage();
+
+    // Navigate to app
+    await page.goto(appUrl, { waitUntil: 'networkidle', timeout: 30000 });
+
+    // Capture initial screenshot
+    const timestamp = Date.now();
+    const homepagePath = join(screenshotPath, `01-homepage-${timestamp}.png`);
+    await page.screenshot({ path: homepagePath, fullPage: true });
+    screenshots.push({
+      id: 1,
+      name: 'Homepage',
+      path: homepagePath,
+      url: appUrl,
+      viewport: 'desktop'
+    });
+
+    // Check for version display
+    const versionCheck = await page.evaluate(() => {
+      const body = document.body.innerText;
+      const versionPattern = /v?\d+\.\d+\.\d+/;
+      const hasVersion = versionPattern.test(body);
+      const header = document.querySelector('header')?.innerText || '';
+      const footer = document.querySelector('footer')?.innerText || '';
+      return {
+        hasVersion,
+        inHeader: versionPattern.test(header),
+        inFooter: versionPattern.test(footer),
+        foundVersion: body.match(versionPattern)?.[0] || null
+      };
+    });
+
+    // Mobile viewport screenshot
+    await page.setViewportSize({ width: 375, height: 812 });
+    await page.reload({ waitUntil: 'networkidle' });
+    const mobilePath = join(screenshotPath, `02-homepage-mobile-${timestamp}.png`);
+    await page.screenshot({ path: mobilePath, fullPage: true });
+    screenshots.push({
+      id: 2,
+      name: 'Homepage Mobile',
+      path: mobilePath,
+      url: appUrl,
+      viewport: 'mobile'
+    });
+
+    await browser.close();
+
+    // Generate critical review for each screenshot
+    const reviews = [];
+    if (criticalReview) {
+      for (const screenshot of screenshots) {
+        reviews.push({
+          screenshot: screenshot.name,
+          path: screenshot.path,
+          score: 0, // To be filled by Claude's analysis
+          evaluation: {
+            howGood: 'REQUIRES_VISUAL_ANALYSIS - Open screenshot and evaluate',
+            couldBeBetter: [],
+            fallingDown: [],
+            excellentWouldLookLike: '',
+            recommendations: []
+          },
+          criteria: Object.entries(UX_CRITERIA).map(([key, crit]) => ({
+            name: crit.name,
+            checks: crit.checks,
+            score: 0,
+            notes: 'Awaiting visual review'
+          }))
+        });
+      }
+    }
+
+    // Save review report
+    const reviewReport = {
+      timestamp: new Date().toISOString(),
+      appUrl,
+      versionCheck,
+      screenshots,
+      reviews,
+      summary: {
+        screenshotsCaptured: screenshots.length,
+        versionDisplayed: versionCheck.hasVersion,
+        versionInHeader: versionCheck.inHeader,
+        versionInFooter: versionCheck.inFooter,
+        requiresManualReview: true
+      },
+      criticalQuestions: [
+        'How good is this? (Score each screen 1-100)',
+        'How could we make it better?',
+        'Where is it falling down?',
+        'What would EXCELLENT look like?',
+        'What are the specific recommendations?'
+      ]
+    };
+
+    writeFileSync(join(screenshotPath, 'review-report.json'), JSON.stringify(reviewReport, null, 2));
+
+    return {
+      action: 'UX_REVIEW_CAPTURED',
+      status: 'SCREENSHOTS_READY',
+      appUrl,
+      versionCheck: {
+        found: versionCheck.hasVersion,
+        version: versionCheck.foundVersion,
+        inHeader: versionCheck.inHeader,
+        inFooter: versionCheck.inFooter,
+        recommendation: !versionCheck.inHeader && !versionCheck.inFooter
+          ? '⚠️ Version not displayed in header/footer - ADD version display immediately'
+          : '✓ Version displayed'
+      },
+      screenshots: screenshots.map(s => ({
+        name: s.name,
+        path: s.path,
+        viewport: s.viewport
+      })),
+      nextSteps: {
+        step1: 'Open each screenshot file and visually inspect',
+        step2: 'Score each screen 1-100 for overall UX quality',
+        step3: 'Document: What works? What fails? What would excellent look like?',
+        step4: 'Generate specific recommendations with priority (HIGH/MEDIUM/LOW)',
+        step5: 'Update review-report.json with scores and findings',
+        step6: 'Re-run kb_first_assess to update UX Quality scores'
+      },
+      criticalQuestions: reviewReport.criticalQuestions,
+      criteria: Object.entries(UX_CRITERIA).map(([key, crit]) => ({
+        name: crit.name,
+        checks: crit.checks,
+        weight: `${crit.weight}%`
+      })),
+      reportPath: join(screenshotPath, 'review-report.json'),
+      designSkills: {
+        available: designSkills.available,
+        useSkill: designSkills.preferred || null,
+        recommendation: designSkills.recommendation,
+        implementationGuidance: designSkills.preferred
+          ? `Use skill "${designSkills.preferred}" when implementing UX improvements. It creates distinctive, production-grade interfaces.`
+          : 'Install frontend-design skill for UX improvements: https://github.com/anthropics/claude-code-plugins'
+      }
+    };
+  } catch (error) {
+    return {
+      action: 'UX_REVIEW_ERROR',
+      status: 'CAPTURE_FAILED',
+      error: error.message,
+      troubleshooting: {
+        step1: 'Ensure the app is running at the specified URL',
+        step2: 'Check if Playwright browsers are installed: npx playwright install chromium',
+        step3: 'Try with a simpler URL first',
+        step4: 'Manually capture screenshots and place in: ' + screenshotPath
+      }
+    };
+  }
+}
+
 /**
  * Get improvement task based on gap
  */
@@ -983,6 +1386,8 @@ async function handleToolCall(toolName, args) {
       return await handleExecute(cwd, args);
     case 'kb_first_verify':
       return await handleVerify(cwd, args);
+    case 'kb_first_ux_review':
+      return await handleUXReview(cwd, args);
     default:
       return { error: `Unknown tool: ${toolName}` };
   }
@@ -1033,8 +1438,9 @@ async function handleMCPMessage(message) {
  */
 export async function startMCPServer(options = {}) {
   console.error(`RuvNet KB-First MCP Server v${SERVER_VERSION}`);
-  console.error('Architecture: Granular Score-Driven | Tools: 5 | Dimensions: 6 KB + 12 Phases');
-  console.error('Workflow: Assess → Plan → Confirm → Execute → Verify');
+  console.error('Architecture: Granular Score-Driven | Tools: 6 | Dimensions: 7 KB + 13 Phases');
+  console.error('Workflow: Assess → Plan → Confirm → Execute → Verify → UX Review');
+  console.error('UX Review: Playwright-based visual quality audit from end-user perspective');
 
   let buffer = '';
   process.stdin.setEncoding('utf-8');