zhongwei/gh-madappgang-claude-code-plugins-frontend
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
Zhongwei Li
2025-11-30 08:38:57 +08:00
commit 74b7e35182
34 changed files with 20806 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

132
commands/api-docs.md Normal file
View File

@@ -0,0 +1,132 @@
---
description: Analyze API documentation for endpoints, data types, and request/response formats
allowed-tools: Task, Read, Bash
---
## Mission
Provide comprehensive API documentation analysis for the Tenant Management Portal API by leveraging the api-analyst agent. Answer questions about endpoints, data structures, authentication, and usage patterns.
## User Query
{{ARGS}}
## Workflow
### STEP 1: Parse User Query
Analyze the user's question to determine what they need:
- **Endpoint information**: Specific API routes, methods, parameters
- **Data type clarification**: TypeScript interfaces, field types, validation rules
- **Authentication/Authorization**: How to authenticate requests, required headers
- **Error handling**: Expected error responses, status codes
- **Integration guidance**: How to integrate with the API, example requests
- **General overview**: High-level API structure and available resources
### STEP 2: Launch API Documentation Analyzer
Use the Task tool with `subagent_type: "frontend:api-analyst"` and provide a detailed prompt:
```
The user is asking: {{ARGS}}
Please analyze the Tenant Management Portal API documentation to answer this query.
Provide:
1. **Relevant Endpoints**: List all endpoints related to the query with HTTP methods
2. **Request Format**: Show request body/query parameters with types
3. **Response Format**: Show response structure with data types
4. **TypeScript Types**: Generate TypeScript interfaces for request/response
5. **Authentication**: Specify any auth requirements
6. **Examples**: Include example requests/responses
7. **Error Handling**: List possible error responses
8. **Usage Notes**: Any important considerations or best practices
Context:
- This is for a React + TypeScript frontend application
- We use TanStack Query for data fetching
- We need type-safe API integration
- Current mock API will be replaced with real API calls
```
### STEP 3: Format and Present Results
After the agent returns its analysis:
1. **Structure the output clearly** with section headers
2. **Include code examples** in TypeScript
3. **Highlight important notes** about authentication, validation, etc.
4. **Provide actionable guidance** for implementation
## Expected Output Format
The agent should provide documentation analysis structured like:
```markdown
# API Documentation: [Topic]
## Endpoints
### [HTTP METHOD] /api/[resource]
- **Purpose**: [Description]
- **Authentication**: [Required/Optional + method]
- **Request Parameters**: [Details]
- **Response**: [Structure]
## TypeScript Types
\`\`\`typescript
interface [Resource] {
id: string;
// ... fields with types
}
interface [ResourceRequest] {
// ... request body structure
}
\`\`\`
## Example Usage
\`\`\`typescript
// Example request with TanStack Query
const { data } = useQuery({
queryKey: ['resource', params],
queryFn: () => api.getResource(params)
})
\`\`\`
## Error Responses
- **400 Bad Request**: [When this occurs]
- **401 Unauthorized**: [When this occurs]
- **404 Not Found**: [When this occurs]
## Implementation Notes
- [Important considerations]
- [Best practices]
```
## Special Cases
### Vague Query
If the query is general (e.g., "show me the API"), provide an overview of all major resource groups and suggest specific queries.
### Multiple Endpoints
If multiple endpoints are relevant, prioritize by:
1. Exact match to query
2. Most commonly used
3. Related operations (CRUD set)
### Missing Documentation
If documentation is incomplete or unclear, note this explicitly and provide best-effort analysis based on available information.
## Notes
- Always use the latest API documentation from the OpenAPI spec
- Prefer TypeScript types over generic JSON examples
- Include practical usage examples with TanStack Query when relevant
- Highlight any breaking changes or deprecations
- Consider the frontend context (React + TypeScript) when providing guidance

219
commands/cleanup-artifacts.md Normal file
View File

@@ -0,0 +1,219 @@
---
description: Intelligently clean up temporary artifacts and development files from the project
allowed-tools: Task, AskUserQuestion, Bash, Read, Glob, Grep
---
## Mission
Analyze the current project state, identify temporary artifacts and development files, then run the cleaner agent to clean them up safely while preserving important implementation code and documentation.
## Workflow
### STEP 1: Analyze Current Project State
1. **Gather Project Context**:
- Run `git status` to see current state
- Run `git diff --stat` to see what's been modified
- Use Glob to find common artifact patterns:
* Test files: `**/*.test.{ts,tsx,js,jsx}`
* Spec files: `**/*.spec.{ts,tsx,js,jsx}`
* Temporary documentation: `AI-DOCS/**/*-TEMP.md`, `AI-DOCS/**/*-WIP.md`
* Development scripts: `scripts/dev-*.{ts,js}`, `scripts/temp-*.{ts,js}`
* Build artifacts: `dist/**/*`, `build/**/*`, `.cache/**/*`
* Coverage reports: `coverage/**/*`
* Log files: `**/*.log`, `**/*.log.*`
* Editor files: `**/.DS_Store`, `**/*.swp`, `**/*.swo`
2. **Identify Current Task**:
- Check for AI-DOCS/ folder to understand recent work
- Look for recent commits to understand context
- Analyze modified files to determine what's being worked on
3. **Categorize Files**:
- **Artifacts to Clean**: Temporary files that can be safely removed
- **Files to Preserve**: Implementation code, final tests, user-facing docs, configs
- **Uncertain Files**: Files that might need user input
### STEP 2: Present Findings to User
Present a clear summary:
```
# Cleanup Analysis
## Current Project State
- Git Status: [clean/modified/staged]
- Recent Work: [description based on git log and AI-DOCS]
- Modified Files: [count and summary]
## Artifacts Found
### Will Clean (if approved):
- Temporary test files: [count] files
- Development artifacts: [count] files
- Intermediate documentation: [count] files
- Build artifacts: [count] files
- [Other categories found]
### Will Preserve:
- Implementation code: [list key files]
- Final tests: [list]
- User-facing documentation: [list]
- Configuration files: [list]
### Uncertain (need your input):
- [List any files where classification is unclear]
```
### STEP 3: User Approval Gate
Use AskUserQuestion to ask:
**Question**: "Ready to clean up these artifacts? All important implementation code and docs will be preserved."
**Options**:
- "Yes, clean up all artifacts" - Proceed with full cleanup
- "Yes, but let me review uncertain files first" - Show uncertain files and get specific approval
- "No, skip cleanup for now" - Cancel the operation
### STEP 4: Launch Project Cleaner
If user approves:
1. **Prepare Context for Agent**:
- Document current project state
- List files categorized for cleanup
- Specify files to preserve
- Include any user-specific instructions for uncertain files
2. **Launch cleaner Agent**:
- Use Task tool with `subagent_type: frontend:cleaner`
- Provide comprehensive context:
```
You are cleaning up artifacts from: [task description]
Current project state:
- [Summary of git status and recent work]
Please remove the following categories of temporary artifacts:
- [List categories from Step 1]
IMPORTANT - Preserve these files/categories:
- [List files to preserve]
User preferences for uncertain files:
- [Any specific guidance from user]
Provide a detailed summary of:
1. Files removed (by category)
2. Space saved
3. Files preserved
4. Any files skipped with reasons
```
3. **Monitor Cleanup**:
- Agent performs cleanup following the plan
- Agent provides detailed report
### STEP 5: Present Cleanup Results
After cleanup completes, present results:
```
# Cleanup Complete ✅
## Summary
- Total files removed: [count]
- Total space saved: [size]
- Files preserved: [count]
- Duration: [time]
## Details by Category
- Temporary test files: [count] removed
- Development artifacts: [count] removed
- Intermediate documentation: [count] removed
- Build artifacts: [count] removed
- [Other categories]
## Preserved
- Implementation code: [count] files
- Final tests: [count] files
- Documentation: [count] files
## Recommendations
- [Any suggestions for further cleanup]
- [Any patterns noticed that could be gitignored]
```
## Safety Rules
### Files That Should NEVER Be Cleaned:
- Source code files: `src/**/*.{ts,tsx,js,jsx,css,html}`
- Package files: `package.json`, `package-lock.json`, `yarn.lock`, `pnpm-lock.yaml`
- Configuration files: `tsconfig.json`, `vite.config.ts`, `.env`, etc.
- Git files: `.git/**/*`, `.gitignore`, `.gitattributes`
- Final tests: Tests explicitly marked as final or in standard test directories
- User documentation: `README.md`, `CHANGELOG.md`, final docs in `docs/`
- CI/CD: `.github/**/*`, `.gitlab-ci.yml`, etc.
### Confirmation Required For:
- Files larger than 1MB (unless clearly artifacts like logs)
- Files in root directory (unless clearly temporary)
- Any files with "KEEP", "FINAL", "PROD" in the name
- Files modified in the last hour (unless user specifically requested cleanup)
### Default Cleanup Targets:
- Files with "temp", "tmp", "test", "wip", "draft" in the name
- Build directories: `dist/`, `build/`, `.cache/`
- Test coverage: `coverage/`
- Log files: `*.log`
- OS artifacts: `.DS_Store`, `Thumbs.db`
- Editor artifacts: `*.swp`, `*.swo`, `.vscode/` (unless committed)
- Node modules cache: `.npm/`, `.yarn/cache/` (not node_modules itself)
## Error Handling
- If cleaner encounters any errors, pause and report to user
- If uncertain about any file, err on the side of caution (don't delete)
- Provide option to undo cleanup if files were accidentally removed (via git if tracked)
## Usage Examples
### Example 1: After Feature Completion
```
User just finished implementing a feature with tests and reviews.
Command analyzes:
- Finds temporary test files from dev iterations
- Finds WIP documentation from planning phase
- Finds build artifacts from testing
User approves → Cleanup removes ~50 temporary files
```
### Example 2: General Project Maintenance
```
User runs cleanup to tidy up project.
Command analyzes:
- Finds old log files
- Finds test coverage reports from last week
- Finds .DS_Store files throughout project
User approves → Cleanup removes minor artifacts
```
### Example 3: Post-Implementation
```
User completed /implement command and is happy with results.
Command analyzes:
- Finds AI-DOCS/implementation-plan-DRAFT.md
- Finds temporary test files
- Finds development scripts used during implementation
User approves → Comprehensive cleanup of all dev artifacts
```
## Notes
- This command can be run at any time, not just after /implement
- It's safe to run frequently - nothing important will be removed without confirmation
- The cleaner agent is conservative and will ask before removing uncertain files
- All git-tracked files that are removed can be restored via git
- For maximum safety, ensure important work is committed before running cleanup
- The command learns from project patterns - if you frequently keep certain file types, it will remember

1581
commands/implement-ui.md Normal file
View File

File diff suppressed because it is too large Load Diff

2748
commands/implement.md Normal file
View File

File diff suppressed because it is too large Load Diff

832
commands/import-figma.md Normal file
View File

@@ -0,0 +1,832 @@
---
description: Intelligently clean up temporary artifacts and development files from the project
allowed-tools: Task, TodoWrite, Read, Write, Edit, Glob, Bash, AskUserQuestion, mcp__figma__get_design_context
---
# Import Figma Make Component
Automates importing UI components from **Figma Make** projects into your React project with validation and iterative fixing.
**Important:** This command works with **Figma Make** projects (URLs with `/make/` path), not regular Figma design files. Make projects contain actual working React/TypeScript code that can be imported directly.
## Prerequisites
- **Figma Make project URL** must be in CLAUDE.md under "Design Resources"
- Component must exist in your Make project
- Development server should be running: `pnpm dev`
- Figma MCP server must be authenticated (run `/configure-mcp` if needed)
- **MCP Resources support** must be available (required for fetching Make files)
## Getting the Figma Make URL
**Need help getting Figma Make URLs?** See the complete guide: [docs/figma-integration-guide.md](../../../docs/figma-integration-guide.md)
### Quick Instructions
1. **Create or open a Make project** in Figma (figma.com/make)
2. **Select the component** you want to export in your Make project
3. **Copy the URL** from the browser address bar
4. **Ensure the URL includes `/make/` in the path**
Expected URL format:
```
https://www.figma.com/make/{projectId}/{projectName}?node-id={nodeId}
```
**Real Example:**
```
https://www.figma.com/make/DfMjRj4FzWcDHHIGRsypcM/Implement-Screen-in-Shadcn?node-id=0-1&t=GZmiQgdDkZ6PjFRG-1
```
Add this URL to your `CLAUDE.md` under the "Design Resources" section:
```markdown
## Design Resources
**Figma Make Project**: https://www.figma.com/make/DfMjRj4FzWcDHHIGRsypcM/Implement-Screen-in-Shadcn?node-id=0-1&t=GZmiQgdDkZ6PjFRG-1
```
**Important:** The URL must contain `/make/` not `/file/` or `/design/` - only Make projects have importable code.
## Workflow Overview
This command will:
1. Read CLAUDE.md and extract Figma Make project URL
2. Fetch component files from Make using **MCP Resources**
3. List available files from Make project
4. Select component code to import
5. Analyze and adapt component code for your project structure
6. Check for name collisions and prompt user if needed
7. Install any missing dependencies via pnpm
8. Create component file in appropriate location
9. Create test route at /playground/{component-name}
10. Invoke tester agent for validation
11. Apply fixes if validation fails (up to 5 iterations)
12. Update CLAUDE.md with component mapping
13. Present comprehensive summary
**What makes this different:** Unlike traditional Figma design imports, Make projects contain real working code. The MCP Resources integration fetches actual React/TypeScript implementations with styles, interactions, and behaviors already defined.
## Implementation Instructions
### STEP 0: Discover Project Structure
Before doing anything else, discover the project structure dynamically:
1. **Get current working directory** using Bash `pwd` command
2. **Find components directory** using Glob pattern `**/components/**/*.tsx` (exclude node_modules)
3. **Find routes directory** using Glob pattern `**/routes/**/*.tsx` (exclude node_modules)
4. **Analyze discovered paths** to determine:
- Where components are stored (e.g., `src/components/`)
- Where UI components are stored (e.g., `src/components/ui/`)
- Where routes are stored (e.g., `src/routes/`)
- Whether a playground directory exists in routes
Example discovery logic:
```typescript
// Get project root
const projectRoot = await Bash({ command: 'pwd' })
// Find existing components
const componentFiles = await Glob({ pattern: 'src/components/**/*.tsx' })
const uiComponentFiles = await Glob({ pattern: 'src/components/ui/**/*.tsx' })
const routeFiles = await Glob({ pattern: 'src/routes/**/*.tsx' })
// Determine paths based on discoveries
const hasComponentsDir = componentFiles.length > 0
const hasUiDir = uiComponentFiles.length > 0
const hasRoutesDir = routeFiles.length > 0
// Set paths based on what exists
const componentsBasePath = hasComponentsDir ? 'src/components' : 'components'
const uiComponentsPath = hasUiDir ? 'src/components/ui' : 'src/components'
const routesBasePath = hasRoutesDir ? 'src/routes' : 'routes'
const playgroundPath = `${routesBasePath}/playground`
```
5. **Store discovered paths** in variables for use throughout the command
6. **Detect package manager**:
- Check for `pnpm-lock.yaml` → use pnpm
- Check for `package-lock.json` → use npm
- Check for `yarn.lock` → use yarn
- Default to pnpm if none found
7. **Check for path aliases**:
- Read tsconfig.json to check for `paths` configuration
- Look for `@/*` or `~/*` aliases
- Store whether aliases exist and what prefix to use
### Constants and Setup
```typescript
const MAX_ITERATIONS = 5
// All paths will be determined dynamically in STEP 0:
// - projectRoot
// - componentsBasePath
// - uiComponentsPath
// - routesBasePath
// - playgroundPath
// - claudeMdPath
// - packageManager ('pnpm' | 'npm' | 'yarn')
// - pathAlias ({ exists: boolean, prefix: string })
```
### STEP 1: Initialize Todo Tracking
Use TodoWrite to create a comprehensive task list for tracking progress:
```typescript
TodoWrite({
todos: [
{ content: 'Discover project structure', status: 'completed', activeForm: 'Discovering project structure' },
{ content: 'Read CLAUDE.md and extract Figma URL', status: 'in_progress', activeForm: 'Reading CLAUDE.md and extracting Figma URL' },
{ content: 'Fetch component from Figma', status: 'pending', activeForm: 'Fetching component from Figma' },
{ content: 'Analyze and adapt component code', status: 'pending', activeForm: 'Analyzing and adapting component code' },
{ content: 'Check for name collisions', status: 'pending', activeForm: 'Checking for name collisions' },
{ content: 'Install required dependencies', status: 'pending', activeForm: 'Installing required dependencies' },
{ content: 'Create component file', status: 'pending', activeForm: 'Creating component file' },
{ content: 'Create test route', status: 'pending', activeForm: 'Creating test route' },
{ content: 'Run validation tests', status: 'pending', activeForm: 'Running validation tests' },
{ content: 'Update CLAUDE.md with mapping', status: 'pending', activeForm: 'Updating CLAUDE.md with mapping' },
{ content: 'Present summary to user', status: 'pending', activeForm: 'Presenting summary to user' }
]
})
```
### STEP 2: Read and Parse CLAUDE.md
1. **Locate CLAUDE.md** using Glob pattern: `**/CLAUDE.md` (search from project root)
- If not found, check common locations: `./CLAUDE.md`, `./docs/CLAUDE.md`, `./.claude/CLAUDE.md`
- If still not found, create it in project root with template structure
2. **Read CLAUDE.md file**
3. **Extract Figma URL** from "Design Resources" section
4. **Parse file key and node ID** from URL
5. **Handle errors** if URL is missing or malformed
Expected Figma URL format:
```
**Figma Make URL**: https://www.figma.com/make/{fileKey}/{fileName}?node-id={nodeId}
```
Error handling:
- If Figma URL not found, instruct user to add it to CLAUDE.md with format example
- If URL format invalid, provide correct format and ask user to fix it
Once successfully parsed:
- Extract `fileKey` from URL
- Extract `nodeId` and convert format from `123-456` to `123:456`
- Update todo: mark "Read CLAUDE.md" as completed, mark "Fetch component" as in_progress
### STEP 3: Fetch Component from Figma
Use the Figma MCP tool to fetch component design context:
```typescript
mcp__figma__get_design_context({
fileKey: fileKey,
nodeId: nodeId,
clientFrameworks: 'react',
clientLanguages: 'typescript'
})
```
Extract the `code` field from the response, which contains the component implementation.
Error handling:
- If component not found: Verify URL, node ID, and access permissions
- If unauthorized: Check Figma authentication status
- If API error: Display error message and suggest retrying
Once component code is fetched successfully:
- Store the code in a variable for adaptation
- Update todo: mark "Fetch component" as completed, mark "Analyze and adapt" as in_progress
### STEP 4: Analyze and Adapt Component Code
#### 4.1 Extract Component Name
Parse the component code to find the exported component name using regex:
```regex
/export\s+(?:function|const)\s+([A-Z][a-zA-Z0-9]*)/
```
If component name cannot be extracted, throw error explaining that the component must have a PascalCase exported name.
#### 4.2 Adapt Imports
Apply these import transformations to adapt Figma code to our project structure:
1. **Utils import**: `from "./utils"` → `from "@/lib/utils"`
2. **Component imports**: `from "./button"` → `from "@/components/ui/button"`
3. **React namespace imports**: Add `type` keyword: `import type * as React from "react"`
#### 4.3 Ensure cn() Import
If the component uses the `cn()` utility function but doesn't import it:
- Find the React import line
- Insert `import { cn } from "@/lib/utils"` right after the React import
#### 4.4 Determine Component Location
Use this logic to determine where to save the component (using discovered paths from STEP 0):
```typescript
const usesRadixUI = code includes "@radix-ui"
const uiPrimitives = ['Button', 'Input', 'Card', 'Badge', 'Avatar', 'Alert', 'Checkbox',
'Select', 'Dialog', 'Dropdown', 'Menu', 'Popover', 'Tooltip',
'Toast', 'Tabs', 'Table', 'Form', 'Label', 'Switch', 'Slider', 'Progress']
const isPrimitive = componentName matches any uiPrimitives
if (usesRadixUI || isPrimitive) {
// UI primitive component → use discovered uiComponentsPath
const kebabName = toKebabCase(componentName)
componentPath = `${projectRoot}/${uiComponentsPath}/${kebabName}.tsx`
} else {
// Feature component → use discovered componentsBasePath
componentPath = `${projectRoot}/${componentsBasePath}/${componentName}.tsx`
}
```
Convert PascalCase to kebab-case: `UserCard` → `user-card`
**Important**: Use the paths discovered in STEP 0, don't hardcode `src/components/`
Once adaptation is complete:
- Update todo: mark "Analyze and adapt" as completed, mark "Check for name collisions" as in_progress
### STEP 5: Check for Name Collisions
#### 5.1 Check if Component Exists
Use Glob to check if a file already exists at the determined component path.
#### 5.2 If Collision Found, Ask User
Use AskUserQuestion to prompt the user:
```typescript
AskUserQuestion({
questions: [{
question: `A component named "${componentName}" already exists at ${componentPath}. What would you like to do?`,
header: "Name Collision",
multiSelect: false,
options: [
{ label: "Overwrite existing", description: "Replace the existing component with the new one from Figma" },
{ label: "Create versioned copy", description: `Save as ${componentName}V2.tsx (or next available version)` },
{ label: "Cancel import", description: "Abort the import process without making changes" }
]
}]
})
```
#### 5.3 Handle User Decision
- **Cancel import**: Throw error to stop execution
- **Overwrite existing**: Continue with same componentPath (file will be replaced)
- **Create versioned copy**:
- Find next available version number (V2, V3, ..., up to V99)
- Update componentPath to versioned name
- Update component name in the code to match versioned name
Once collision is resolved:
- Update todo: mark "Check for name collisions" as completed, mark "Install required dependencies" as in_progress
### STEP 6: Install Required Dependencies
#### 6.1 Extract Required Packages
Parse all import statements from the adapted code:
```regex
/^import\s+.*$/gm
```
For each import line, extract the module name from `from "..."`
Filter to only external packages (exclude):
- Imports starting with `@/` (our project)
- Imports starting with `.` (relative imports)
- `react` and `react-dom` (always installed)
Common packages that might be needed:
- `@radix-ui/*`
- `class-variance-authority`
- `lucide-react`
- `cmdk`
- `embla-carousel-react`
- `recharts`
#### 6.2 Check What's Already Installed
Read package.json and check both `dependencies` and `devDependencies` sections.
Filter the required packages list to only those not already installed.
#### 6.3 Install Missing Dependencies
If there are packages to install:
```bash
cd {projectRoot} && {packageManager} add {package1} {package2} ...
```
Use the detected package manager from STEP 0 (pnpm/npm/yarn).
Use Bash tool with timeout of 60000ms (1 minute).
Error handling:
- If installation fails, provide clear error message with manual installation command
- Suggest user runs `pnpm add {packages}` manually and then re-runs /import-figma
Once dependencies are installed (or confirmed already installed):
- Update todo: mark "Install required dependencies" as completed, mark "Create component file" as in_progress
### STEP 7: Create Component File
#### 7.1 Write Component File
Use Write tool to create the component file with the adapted code at the determined componentPath.
#### 7.2 Apply Code Formatting
Check which formatter is configured:
- Look for `biome.json` → use Biome
- Look for `.eslintrc*` → use ESLint
- Look for `.prettierrc*` → use Prettier
Run the appropriate formatter:
```bash
# If Biome exists:
cd {projectRoot} && {packageManager} run lint:fix {componentPath}
# If ESLint exists:
cd {projectRoot} && {packageManager} run lint {componentPath} --fix
# If Prettier exists:
cd {projectRoot} && {packageManager} run format {componentPath}
```
If formatting fails, log warning but continue (non-critical).
Once component file is created:
- Update todo: mark "Create component file" as completed, mark "Create test route" as in_progress
### STEP 8: Create Test Route
#### 8.1 Determine Test Route Path
Use the discovered routes path from STEP 0:
```typescript
const kebabName = toKebabCase(componentName) // UserCard -> user-card
// Check if playground directory exists
const playgroundExists = await Glob({ pattern: `${playgroundPath}/**` })
// Create playground directory if it doesn't exist
if (playgroundExists.length === 0) {
await Bash({ command: `mkdir -p ${projectRoot}/${playgroundPath}` })
}
const testRoutePath = `${projectRoot}/${playgroundPath}/${kebabName}.tsx`
```
**Important**: Use the `playgroundPath` discovered in STEP 0, don't hardcode `src/routes/playground/`
#### 8.2 Analyze Component Props
Check if component has props by looking for interface/type definitions:
```regex
/(?:interface|type)\s+\w+Props\s*=?\s*{([^}]+)}/
```
#### 8.3 Generate Test Route Content
Create a test route that:
- Imports the component correctly (use discovered paths, not hardcoded @/ aliases)
- Uses TanStack Router's `createFileRoute`
- Renders the component in an isolated playground environment
- Includes heading, description, and test sections
- Uses dummy data if component has props (add TODO comment for user to customize)
**Determine import path dynamically**:
```typescript
// Calculate relative import path from test route to component
// Example: if component is in src/components/ui/button.tsx
// and test route is in src/routes/playground/button.tsx
// then import path is "../../components/ui/button"
const importPath = calculateRelativePath(testRoutePath, componentPath)
// OR use project's alias if it exists (@/ or ~/)
const hasPathAlias = await checkForPathAlias() // Check tsconfig.json or vite.config
const importStatement = hasPathAlias
? `import { ${componentName} } from "@/${componentsBasePath}/${componentName}"`
: `import { ${componentName} } from "${importPath}"`
```
Template structure (with dynamic import):
```typescript
import { createFileRoute } from "@tanstack/react-router"
${importStatement}
export const Route = createFileRoute("/playground/${kebabName}")({
component: PlaygroundComponent,
})
function PlaygroundComponent() {
// Sample data if component has props
return (
<div className="min-h-screen bg-background p-8">
<div className="mx-auto max-w-4xl space-y-8">
<div>
<h1 className="text-3xl font-bold mb-2">${componentName} Playground</h1>
<p className="text-muted-foreground">Testing playground for ${componentName} imported from Figma</p>
</div>
<div className="space-y-6">
<section className="space-y-4">
<h2 className="text-xl font-semibold">Default Variant</h2>
<div className="p-6 border rounded-lg bg-card">
<${componentName} />
</div>
</section>
</div>
</div>
</div>
)
}
```
**Important**: Don't hardcode `@/components/` - use the discovered path or calculate relative import
#### 8.4 Write and Format Test Route
- Use Write tool to create the test route file
- Run Biome formatting on the test route file
Once test route is created:
- Update todo: mark "Create test route" as completed, mark "Run validation tests" as in_progress
### STEP 9: Run Validation Tests
This is a critical step that uses an iterative validation loop with the tester agent.
#### 9.1 Initialize Loop Variables
```typescript
iteration = 0
testPassed = false
testResult = ''
```
#### 9.2 Validation Loop (Max 5 Iterations)
While `iteration < MAX_ITERATIONS` and `!testPassed`:
**A. Invoke tester Agent**
Use Task tool to invoke the tester agent with comprehensive testing instructions:
```typescript
Task({
subagent_type: 'frontend:tester',
description: `Test ${componentName} component`,
prompt: `Test the ${componentName} component at /playground/${kebabName}
## Component Details
- **Name**: ${componentName}
- **Location**: ${componentPath.replace(projectRoot + '/', '')}
- **Test Route**: /playground/${kebabName}
- **Test URL**: http://localhost:5173/playground/${kebabName}
Note: Use relative paths in the test instructions, not absolute paths
## Test Scenarios
1. **Navigation Test**
- Navigate to http://localhost:5173/playground/${kebabName}
- Verify page loads without errors
2. **Console Check**
- Open browser DevTools console
- Verify no errors or warnings
- Check for missing imports or type errors
3. **Visual Rendering**
- Verify component renders correctly
- Check spacing, colors, typography
- Ensure no layout issues
4. **Interaction Testing** (if applicable)
- Test any buttons, inputs, or interactive elements
- Verify event handlers work correctly
5. **Responsive Testing**
- Test at mobile (375px), tablet (768px), desktop (1440px)
- Verify layout adapts correctly
## Pass Criteria
- ✓ No console errors
- ✓ Component renders without crashes
- ✓ Visual appearance is acceptable
- ✓ All interactions work as expected
## Report Format
Please provide:
1. **Overall Status**: PASS or FAIL
2. **Errors Found**: List any console errors
3. **Visual Issues**: Describe rendering problems (if any)
4. **Recommendations**: Suggest fixes if issues found
This is iteration ${iteration + 1} of ${MAX_ITERATIONS}.`
})
```
**B. Parse Test Result**
Check if the test result contains "Overall Status" with "PASS" (case-insensitive).
If PASS:
- Set `testPassed = true`
- Break out of loop
If FAIL and not at max iterations yet:
- Continue to fix strategy
**C. Apply Automated Fixes**
Identify common error patterns and attempt to fix them automatically:
**Fix Pattern 1: Missing Imports**
If error contains `"Cannot find module"` or `"Failed to resolve import"`:
- Extract the missing module name
- If it's a relative import (`./{name}`), convert to absolute: `@/components/ui/{name}`
- Use Edit tool to replace the import path
**Fix Pattern 2: Missing cn Import**
If error contains `"cn is not defined"` or `"Cannot find name 'cn'"`:
- Read the component file
- Check if cn is already imported
- If not, add `import { cn } from "@/lib/utils"` after React import
- Use Write tool to update file
**Fix Pattern 3: Wrong Import Path**
If error suggests component not found:
- Check if the imported component exists in a different location
- Try alternative paths: `@/components/ui/{name}`, `@/components/{Name}`, etc.
- Use Edit tool to fix the import
**Fix Pattern 4: Missing Dependency**
If error mentions a missing package:
- Use pnpm to install the package
- Rebuild if necessary
**Fix Pattern 5: Type Errors**
If error mentions missing properties or type mismatches:
- Consider extending the component props interface
- Add React.ComponentProps extension if needed
After applying fixes:
- Reformat the file with Biome
- Increment iteration counter
- Loop back to invoke tester again
#### 9.3 Max Iterations Exceeded
If `iteration >= MAX_ITERATIONS` and `!testPassed`:
Use AskUserQuestion to prompt the user:
```typescript
AskUserQuestion({
questions: [{
question: `The ${componentName} component still has validation issues after ${MAX_ITERATIONS} fix attempts. What would you like to do?`,
header: "Validation Failed",
multiSelect: false,
options: [
{ label: "Continue trying", description: "Attempt more fix iterations (may not resolve issues)" },
{ label: "Keep as-is", description: "Save component despite issues for manual fixing later" },
{ label: "Rollback changes", description: "Delete the imported component and test route" }
]
}]
})
```
Handle user decision:
- **Continue trying**: Reset MAX_ITERATIONS and continue loop
- **Keep as-is**: Break loop and continue to next step (component saved with issues)
- **Rollback changes**: Delete component file and test route using Bash `rm` command, then throw error
Once validation is complete (either passed or user decided to keep/continue):
- Update todo: mark "Run validation tests" as completed, mark "Update CLAUDE.md with mapping" as in_progress
### STEP 10: Update CLAUDE.md with Mapping
#### 10.1 Prepare Mapping Entry
```typescript
const today = new Date().toISOString().split('T')[0] // YYYY-MM-DD format
const status = testPassed ? '✓ Validated' : '⚠ Needs Review'
```
#### 10.2 Check if Mappings Section Exists
Read CLAUDE.md and check if it contains "## Figma Component Mappings"
**If section doesn't exist:**
Add the complete section to the end of CLAUDE.md:
```markdown
## Figma Component Mappings
Imported components from Figma with their file locations and node IDs:
| Component Name | File Path | Figma Node ID | Import Date | Status |
|----------------|-----------|---------------|-------------|--------|
| {componentName} | {relativePath} | {nodeId} | {today} | {status} |
**Note**: This registry is automatically maintained by the `/import-figma` command.
```
**If section exists:**
Find the table and append a new row:
```markdown
| {componentName} | {relativePath} | {nodeId} | {today} | {status} |
```
Use Edit tool to insert the new row.
Important: Use relative path (remove PROJECT_ROOT from path) for readability.
Once CLAUDE.md is updated:
- Update todo: mark "Update CLAUDE.md with mapping" as completed, mark "Present summary to user" as in_progress
### STEP 11: Present Summary to User
Generate and present a comprehensive summary of the import operation.
#### Summary Structure:
```markdown
# Figma Import Summary: {ComponentName}
## Status: {STATUS} {EMOJI}
### Component Details
- **Name**: {componentName}
- **Location**: {componentPath}
- **Type**: {UI Component or Feature Component}
- **Import Date**: {today}
### Test Route
- **URL**: http://localhost:5173/playground/{kebab-name}
- **File**: {testRoutePath}
### Dependencies
{If packages installed}
**Installed ({count} packages)**:
- {package1}
- {package2}
...
{Otherwise}
No new dependencies required.
### Validation Results
**Test Status**: {PASS ✓ or FAIL ✗}
**Iterations**: {iteration} of {MAX_ITERATIONS}
{If passed}
✓ All tests passed
✓ No console errors
✓ Component renders correctly
{If failed}
⚠ Validation completed with issues
Please review the component at /playground/{kebab-name} and fix any remaining issues manually.
**Test Output**:
{testResult}
### Next Steps
{If passed}
1. Visit /playground/{kebab-name} to view the component
2. Review the component code at {componentPath}
3. Integrate into your application as needed
{If failed}
1. Visit /playground/{kebab-name} to review the component
2. Check browser console for any errors
3. Manually fix issues in {componentPath}
4. Test thoroughly before production use
### Files Modified
- Created: {componentPath}
- Created: {testRoutePath}
- Updated: CLAUDE.md (component mapping added)
{If dependencies installed}
- Updated: package.json (dependencies)
- Updated: pnpm-lock.yaml (lockfile)
```
#### Final Todo Update
Mark "Present summary to user" as completed.
All 10 steps should now be marked as completed in the todo list.
---
## Error Handling Reference
Throughout execution, handle these common errors gracefully:
1. **CLAUDE.md not found**: Provide instructions to create it with Figma URL
2. **Figma URL missing**: Show exact format needed and where to add it
3. **Invalid Figma URL**: Explain correct format with example
4. **Figma API errors**: Check authentication, access, and retry
5. **Component not found**: Verify node ID and file access
6. **Name collision**: Always ask user (covered in Step 5)
7. **Dependency installation failure**: Provide manual installation command
8. **Write failures**: Check file permissions and paths
9. **Validation failures**: Use iterative fixing (covered in Step 9)
10. **Max iterations exceeded**: Always ask user (covered in Step 9)
## Helper Functions for Dynamic Path Resolution
### toKebabCase(str)
Convert PascalCase to kebab-case:
```typescript
function toKebabCase(str: string): string {
return str.replace(/([a-z])([A-Z])/g, '$1-$2').toLowerCase()
}
// Example: UserCard → user-card
```
### discoverProjectStructure()
Returns object with all discovered paths:
```typescript
{
projectRoot: '/absolute/path/to/project',
componentsBasePath: 'src/components',
uiComponentsPath: 'src/components/ui',
routesBasePath: 'src/routes',
playgroundPath: 'src/routes/playground',
hasPathAlias: true, // @/ exists in tsconfig
claudeMdPath: '/absolute/path/to/CLAUDE.md'
}
```
### calculateRelativePath(from, to)
Calculate relative import path between two files:
```typescript
// from: /project/src/routes/playground/button.tsx
// to: /project/src/components/ui/button.tsx
// returns: ../../components/ui/button
```
### checkForPathAlias()
Check if project uses path alias (@/ or ~/) by reading tsconfig.json or vite.config:
```typescript
// Returns: { exists: true, prefix: '@/' } or { exists: false, prefix: null }
```
## Important Notes
- **DO NOT hardcode any paths** - always use discovered paths from STEP 0
- **All file paths must be absolute** when using tools (construct using projectRoot + relativePath)
- **Use package manager from project** - detect pnpm/npm/yarn by checking lock files
- Apply Biome formatting after all file creation/edits
- Keep user informed via TodoWrite updates throughout
- Use Task tool only for tester agent (no other agents)
- Maximum 5 validation iterations before asking user
- Always provide clear, actionable error messages
- Preserve user control via AskUserQuestion for critical decisions
- **Adapt to project conventions** - use existing import patterns, component structure, etc.
## Testing Checklist
Before marking complete, verify:
- [ ] Component file created at correct location
- [ ] Test route accessible at /playground/{name}
- [ ] No console errors in browser
- [ ] Component renders without crashing
- [ ] CLAUDE.md updated with mapping entry
- [ ] Summary presented to user
- [ ] All todos marked as completed
---
**Command complete when all 10 steps are successfully executed and summary is presented to user.**

842
commands/review.md Normal file
View File

@@ -0,0 +1,842 @@
---
description: Multi-model code review orchestrator with parallel execution and consensus analysis
allowed-tools: Task, AskUserQuestion, Bash, Read, TodoWrite, Glob, Grep
---
<role>
<identity>Multi-Model Code Review Orchestrator</identity>
<expertise>
- Parallel multi-model AI coordination for 3-5x speedup
- Consensus analysis and issue prioritization across diverse AI perspectives
- Cost-aware external model management via Claudish proxy mode
- Graceful degradation and error recovery (works with/without external models)
- Git-based code change analysis (unstaged changes, commits, specific files)
</expertise>
<mission>
Orchestrate comprehensive multi-model code review workflow with parallel execution,
consensus analysis, and actionable insights prioritized by reviewer agreement.
Provide developers with high-confidence feedback by aggregating reviews from multiple
AI models, highlighting issues flagged by majority consensus while maintaining cost
transparency and enabling graceful fallback to embedded Claude reviewer.
</mission>
</role>
<user_request>
$ARGUMENTS
</user_request>
<instructions>
<critical_constraints>
<orchestrator_role>
You are an ORCHESTRATOR, not an IMPLEMENTER or REVIEWER.
**✅ You MUST:**
- Use Task tool to delegate ALL reviews to senior-code-reviewer agent
- Use Bash to run git commands (status, diff, log)
- Use Read/Glob/Grep to understand context
- Use TodoWrite to track workflow progress (all 5 phases)
- Use AskUserQuestion for user approval gates
- Execute external reviews in PARALLEL (single message, multiple Task calls)
**❌ You MUST NOT:**
- Write or edit ANY code files directly
- Perform reviews yourself
- Write review files yourself (delegate to senior-code-reviewer)
- Run reviews sequentially (always parallel for external models)
</orchestrator_role>
<cost_transparency>
Before running external models, MUST show estimated costs and get user approval.
Display cost breakdown per model with INPUT/OUTPUT token separation and total
estimated cost range (min-max based on review complexity).
</cost_transparency>
<graceful_degradation>
If Claudish unavailable or no external models selected, proceed with embedded
Claude Sonnet reviewer only. Command must always provide value.
</graceful_degradation>
<parallel_execution_requirement>
CRITICAL: Execute ALL external model reviews in parallel using multiple Task
invocations in a SINGLE message. This achieves 3-5x speedup vs sequential.
Example pattern:
[One message with:]
Task: senior-code-reviewer PROXY_MODE: model-1 ...
---
Task: senior-code-reviewer PROXY_MODE: model-2 ...
---
Task: senior-code-reviewer PROXY_MODE: model-3 ...
This is the KEY INNOVATION that makes multi-model review practical (5-10 min
vs 15-30 min). See Key Design Innovation section in knowledge base.
</parallel_execution_requirement>
<todowrite_requirement>
You MUST use the TodoWrite tool to create and maintain a todo list throughout
your orchestration workflow.
**Before starting**, create a todo list with all workflow phases:
1. PHASE 1: Ask user what to review
2. PHASE 1: Gather review target
3. PHASE 2: Present model selection options
4. PHASE 2: Show estimated costs and get approval
5. PHASE 3: Execute embedded review
6. PHASE 3: Execute ALL external reviews in parallel
7. PHASE 4: Read all review files
8. PHASE 4: Analyze consensus and consolidate feedback
9. PHASE 4: Write consolidated report
10. PHASE 5: Present final results to user
**Update continuously**:
- Mark tasks as "in_progress" when starting
- Mark tasks as "completed" immediately after finishing
- Add new tasks if additional work discovered
- Keep only ONE task as "in_progress" at a time
</todowrite_requirement>
</critical_constraints>
<workflow>
<step number="0">Initialize TodoWrite with 10 workflow tasks before starting</step>
<step number="1">PHASE 1: Determine review target and gather context</step>
<step number="2">PHASE 2: Select AI models and show cost estimate</step>
<step number="3">PHASE 3: Execute ALL reviews in parallel</step>
<step number="4">PHASE 4: Consolidate reviews with consensus analysis</step>
<step number="5">PHASE 5: Present consolidated results</step>
</workflow>
</instructions>
<orchestration>
<allowed_tools>
- Task (delegate to senior-code-reviewer agent)
- Bash (git commands, Claudish availability checks)
- Read (read review files)
- Glob (expand file patterns)
- Grep (search for patterns)
- TodoWrite (track workflow progress)
- AskUserQuestion (user approval gates)
</allowed_tools>
<forbidden_tools>
- Write (reviewers write files, not orchestrator)
- Edit (reviewers edit files, not orchestrator)
</forbidden_tools>
<delegation_rules>
<rule scope="embedded_review">
Embedded (local) review → senior-code-reviewer agent (NO PROXY_MODE)
</rule>
<rule scope="external_review">
External model review → senior-code-reviewer agent (WITH PROXY_MODE: {model_id})
</rule>
<rule scope="consolidation">
Orchestrator performs consolidation (reads files, analyzes consensus, writes report)
</rule>
</delegation_rules>
<phases>
<phase number="1" name="Review Target Selection">
<objective>
Determine what code to review (unstaged/files/commits) and gather review context
</objective>
<steps>
<step>Mark PHASE 1 tasks as in_progress in TodoWrite</step>
<step>Ask user what to review (3 options: unstaged/files/commits)</step>
<step>Gather review target based on user selection:
- Option 1: Run git diff for unstaged changes
- Option 2: Use Glob and Read for specific files
- Option 3: Run git diff for commit range
</step>
<step>Summarize changes and get user confirmation</step>
<step>Write review context to ai-docs/code-review-context.md including:
- Review target type
- Files under review with line counts
- Summary of changes
- Full git diff or file contents
- Review instructions
</step>
<step>Mark PHASE 1 tasks as completed in TodoWrite</step>
<step>Mark PHASE 2 tasks as in_progress in TodoWrite</step>
</steps>
<quality_gate>
User confirmed review target, context file written successfully
</quality_gate>
<error_handling>
If no changes found, offer alternatives (commits/files) or exit gracefully.
If user cancels, exit with clear message about where to restart.
</error_handling>
</phase>
<phase number="2" name="Model Selection and Cost Approval">
<objective>
Select AI models for review and show estimated costs with input/output breakdown
</objective>
<steps>
<step>Check Claudish CLI availability: npx claudish --version</step>
<step>If Claudish available, check OPENROUTER_API_KEY environment variable</step>
<step>Query available models dynamically from Claudish:
- Run: npx claudish --list-models --json
- Parse JSON output to extract model information (id, name, category, pricing)
- Filter models suitable for code review (coding, reasoning, vision categories)
- Build model selection options from live data
</step>
<step>If Claudish unavailable or query fails, use embedded fallback list:
- x-ai/grok-code-fast-1 (xAI Grok - fast coding)
- google/gemini-2.5-flash (Google Gemini - fast and affordable)
- openai/gpt-5.1-codex (OpenAI GPT-5.1 Codex - advanced analysis)
- deepseek/deepseek-chat (DeepSeek - reasoning specialist)
- Custom model ID option
- Claude Sonnet 4.5 embedded (always available, FREE)
</step>
<step>Present model selection with up to 9 external + 1 embedded using dynamic data</step>
<step>If external models selected, calculate and display estimated costs:
- INPUT tokens: code lines × 1.5 (context + instructions)
- OUTPUT tokens: 2000-4000 (varies by review complexity)
- Show per-model breakdown with INPUT cost + OUTPUT cost range
- Show total estimated cost range (min-max)
- Document: "Output tokens cost 3-5x more than input tokens"
- Explain cost factors: review depth, model verbosity, code complexity
</step>
<step>Get user approval to proceed with costs</step>
<step>Mark PHASE 2 tasks as completed in TodoWrite</step>
<step>Mark PHASE 3 tasks as in_progress in TodoWrite</step>
</steps>
<quality_gate>
At least 1 model selected, user approved costs (if applicable)
</quality_gate>
<error_handling>
- Claudish unavailable: Offer embedded only, show setup instructions
- API key missing: Show setup instructions, offer embedded only
- User rejects cost: Offer to change selection or cancel
- All selection options fail: Exit gracefully
</error_handling>
</phase>
<phase number="3" name="Parallel Multi-Model Review">
<objective>
Execute ALL reviews in parallel (embedded + external) for 3-5x speedup
</objective>
<steps>
<step>If embedded selected, launch embedded review:
- Use Task tool to delegate to senior-code-reviewer (NO PROXY_MODE)
- Input file: ai-docs/code-review-context.md
- Output file: ai-docs/code-review-local.md
</step>
<step>Mark embedded review task as completed when done</step>
<step>If external models selected, launch ALL in PARALLEL:
- Construct SINGLE message with multiple Task invocations
- Use separator "---" between Task blocks
- Each Task: senior-code-reviewer with PROXY_MODE: {model_id}
- Each Task: unique output file (ai-docs/code-review-{model}.md)
- All Tasks: same input file (ai-docs/code-review-context.md)
- CRITICAL: All tasks execute simultaneously (not sequentially)
</step>
<step>Track progress with real-time updates showing which reviews are complete:
Show user which reviews are complete as they finish:
```
⚡ Parallel Reviews In Progress (5-10 min estimated):
- ✓ Local (Claude Sonnet) - COMPLETE
- ⏳ Grok (x-ai/grok-code-fast-1) - IN PROGRESS
- ⏳ Gemini Flash (google/gemini-2.5-flash) - IN PROGRESS
- ⏹ DeepSeek (deepseek/deepseek-chat) - PENDING
Estimated time remaining: ~3 minutes
```
Update as each review completes. Use BashOutput to monitor if needed.
</step>
<step>Handle failures gracefully: Log and continue with successful reviews</step>
<step>Mark PHASE 3 tasks as completed in TodoWrite</step>
<step>Mark PHASE 4 tasks as in_progress in TodoWrite</step>
</steps>
<quality_gate>
At least 1 review completed successfully (embedded OR external)
</quality_gate>
<error_handling>
- Some reviews fail: Continue with successful ones, note failures
- ALL reviews fail: Show detailed error message, save context file, exit gracefully
</error_handling>
</phase>
<phase number="4" name="Consolidate Reviews">
<objective>
Analyze all reviews, identify consensus using simplified keyword-based algorithm,
create consolidated report with confidence levels
</objective>
<steps>
<step>Read all review files using Read tool (ai-docs/code-review-*.md)</step>
<step>Mark read task as completed in TodoWrite</step>
<step>Parse issues from each review (critical/medium/low severity)</step>
<step>Normalize issue descriptions for comparison:
- Extract category (Security/Performance/Type Safety/etc.)
- Extract location (file, line range)
- Extract keywords from description
</step>
<step>Group similar issues using simplified algorithm (v1.0):
- Compare category (must match)
- Compare location (must match)
- Compare keywords (Jaccard similarity: overlap/union)
- Calculate confidence level (high/medium/low)
- Use conservative threshold: Only group if score &gt; 0.6 AND confidence = high
- Fallback: Preserve as separate items if confidence low
- Philosophy: Better to have duplicates than incorrectly merge different issues
</step>
<step>Calculate consensus levels for each issue group:
- Unanimous (100% agreement) - VERY HIGH confidence
- Strong Consensus (67-99% agreement) - HIGH confidence
- Majority (50-66% agreement) - MEDIUM confidence
- Divergent (single reviewer) - LOW confidence
</step>
<step>Create model agreement matrix showing which models flagged which issues</step>
<step>Generate actionable recommendations prioritized by consensus level</step>
<step>Write consolidated report to ai-docs/code-review-consolidated.md including:
- Executive summary with overall verdict
- Unanimous issues (100% agreement) - MUST FIX
- Strong consensus issues (67-99%) - RECOMMENDED TO FIX
- Majority issues (50-66%) - CONSIDER FIXING
- Divergent issues (single reviewer) - OPTIONAL
- Code strengths acknowledged by multiple reviewers
- Model agreement matrix
- Actionable recommendations
- Links to individual review files
</step>
<step>Mark PHASE 4 tasks as completed in TodoWrite</step>
<step>Mark PHASE 5 task as in_progress in TodoWrite</step>
</steps>
<quality_gate>
Consolidated report written with consensus analysis and priorities
</quality_gate>
<error_handling>
If cannot read review files, log error and show what is available
</error_handling>
</phase>
<phase number="5" name="Present Results">
<objective>
Present consolidated results to user with actionable next steps
</objective>
<steps>
<step>Generate brief user summary (NOT full consolidated report):
- Reviewers: Model count and names
- Total cost: Actual cost if external models used
- Overall verdict: PASSED/REQUIRES_IMPROVEMENT/FAILED
- Top 5 most important issues (by consensus level)
- Code strengths (acknowledged by multiple reviewers)
- Link to detailed consolidated report
- Links to individual review files
- Clear next steps and recommendations
</step>
<step>Present summary to user (under 50 lines)</step>
<step>Mark PHASE 5 task as completed in TodoWrite</step>
</steps>
<quality_gate>
User receives clear, actionable summary with prioritized issues
</quality_gate>
<error_handling>
Always present something to user, even if limited. Never leave user without feedback.
</error_handling>
</phase>
</phases>
</orchestration>
<knowledge>
<key_design_innovation name="Parallel Execution Architecture">
**The Performance Breakthrough**
Problem: Running multiple external model reviews sequentially takes 15-30 minutes
Solution: Execute ALL external reviews in parallel using Claude Code multi-task pattern
Result: 3-5x speedup (5 minutes vs 15 minutes for 3 models)
**How Parallel Execution Works**
Claude Code Task tool supports multiple task invocations in a SINGLE message,
executing them all in parallel:
```
[Single message with multiple Task calls - ALL execute simultaneously]
Task: senior-code-reviewer
PROXY_MODE: x-ai/grok-code-fast-1
Review the code changes via Grok model.
INPUT FILE (read yourself):
- ai-docs/code-review-context.md
OUTPUT FILE (write review here):
- ai-docs/code-review-grok.md
RETURN: Brief verdict only.
---
Task: senior-code-reviewer
PROXY_MODE: google/gemini-2.5-flash
Review the code changes via Gemini Flash model.
INPUT FILE (read yourself):
- ai-docs/code-review-context.md
OUTPUT FILE (write review here):
- ai-docs/code-review-gemini-flash.md
RETURN: Brief verdict only.
---
Task: senior-code-reviewer
PROXY_MODE: deepseek/deepseek-chat
Review the code changes via DeepSeek model.
INPUT FILE (read yourself):
- ai-docs/code-review-context.md
OUTPUT FILE (write review here):
- ai-docs/code-review-deepseek.md
RETURN: Brief verdict only.
```
**Performance Comparison**
Sequential Execution (OLD WAY - DO NOT USE):
- Model 1: 5 minutes (start at T+0, finish at T+5)
- Model 2: 5 minutes (start at T+5, finish at T+10)
- Model 3: 5 minutes (start at T+10, finish at T+15)
- Total Time: 15 minutes
Parallel Execution (THIS IMPLEMENTATION):
- Model 1: 5 minutes (start at T+0, finish at T+5)
- Model 2: 5 minutes (start at T+0, finish at T+5)
- Model 3: 5 minutes (start at T+0, finish at T+5)
- Total Time: max(5, 5, 5) = 5 minutes
Speedup: 15 min → 5 min = 3x faster
**Implementation Requirements**
1. Single Message Pattern: All Task invocations MUST be in ONE message
2. Task Separation: Use --- separator between Task blocks
3. Independent Tasks: Each task must be self-contained (no dependencies)
4. Output Files: Each task writes to different file (no conflicts)
5. Wait for All: Orchestrator waits for ALL tasks to complete before Phase 4
**Why This Is Critical**
This parallel execution pattern is the KEY INNOVATION that makes multi-model
review practical:
- Without it: 15-30 minutes for 3-6 models (users won't wait)
- With it: 5-10 minutes for same review (acceptable UX)
</key_design_innovation>
<cost_estimation name="Input/Output Token Separation">
**Cost Calculation Methodology**
External AI models charge differently for input vs output tokens:
- Input tokens: Code context + review instructions (relatively cheap)
- Output tokens: Generated review analysis (3-5x more expensive than input)
**Estimation Formula**:
```
// INPUT TOKENS: Code context + review instructions + system prompt
const estimatedInputTokens = codeLines * 1.5;
// OUTPUT TOKENS: Review is primarily output (varies by complexity)
// Simple reviews: ~1500 tokens
// Medium reviews: ~2500 tokens
// Complex reviews: ~4000 tokens
const estimatedOutputTokensMin = 2000; // Conservative estimate
const estimatedOutputTokensMax = 4000; // Upper bound for complex reviews
const inputCost = (estimatedInputTokens / 1000000) * pricing.input;
const outputCostMin = (estimatedOutputTokensMin / 1000000) * pricing.output;
const outputCostMax = (estimatedOutputTokensMax / 1000000) * pricing.output;
return {
inputCost,
outputCostMin,
outputCostMax,
totalMin: inputCost + outputCostMin,
totalMax: inputCost + outputCostMax
};
```
**User-Facing Cost Display**:
```
💰 Estimated Review Costs
Code Size: ~350 lines (estimated ~525 input tokens per review)
External Models Selected: 3
| Model | Input Cost | Output Cost (Range) | Total (Range) |
|-------|-----------|---------------------|---------------|
| x-ai/grok-code-fast-1 | $0.08 | $0.15 - $0.30 | $0.23 - $0.38 |
| google/gemini-2.5-flash | $0.05 | $0.10 - $0.20 | $0.15 - $0.25 |
| deepseek/deepseek-chat | $0.05 | $0.10 - $0.20 | $0.15 - $0.25 |
Total Estimated Cost: $0.53 - $0.88
Embedded Reviewer: Claude Sonnet 4.5 (FREE - included)
Cost Breakdown:
- Input tokens (code context): Fixed per review (~$0.05-$0.08 per model)
- Output tokens (review analysis): Variable by complexity (~2000-4000 tokens)
- Output tokens cost 3-5x more than input tokens
Note: Actual costs may vary based on review depth, code complexity, and model
verbosity. Higher-quality models may generate more detailed reviews (higher
output tokens).
```
**Why Ranges Matter**:
- Simple code = shorter review = lower output tokens = minimum cost
- Complex code = detailed review = higher output tokens = maximum cost
- Users understand variability upfront, no surprises
</cost_estimation>
<consensus_algorithm name="Simplified Keyword-Based Matching">
**Algorithm Version**: v1.0 (production-ready, conservative)
**Future Improvement**: ML-based grouping deferred to v2.0
**Strategy**:
- Conservative grouping with confidence-based fallback
- Only group issues if high confidence (score &gt; 0.6 AND confidence = high)
- If confidence low, preserve as separate items
- Philosophy: Better to have duplicates than incorrectly merge different issues
**Similarity Calculation**:
Factor 1: Category must match (hard requirement)
- If different categories → score = 0, confidence = high (definitely different)
Factor 2: Location must match (hard requirement)
- If different locations → score = 0, confidence = high (definitely different)
Factor 3: Keyword overlap (soft requirement)
- Extract keywords from descriptions (remove stop words, min length 4)
- Calculate Jaccard similarity: overlap / union
- Assess confidence based on keyword count and overlap:
* Too few keywords (&lt;3) → confidence = low (unreliable comparison)
* No overlap → confidence = high (definitely different)
* Very high overlap (&gt;0.8) → confidence = high (definitely similar)
* Very low overlap (&lt;0.4) → confidence = high (definitely different)
* Ambiguous range (0.4-0.8) → confidence = medium
**Grouping Logic**:
```
for each issue:
find similar issues:
similarity = calculateSimilarity(issue1, issue2)
if similarity.score &gt; 0.6 AND similarity.confidence == 'high':
group together
else if similarity.confidence == 'low':
preserve as separate item (don't group)
```
**Consensus Levels**:
- Unanimous (100% agreement) - VERY HIGH confidence
- Strong Consensus (67-99% agreement) - HIGH confidence
- Majority (50-66% agreement) - MEDIUM confidence
- Divergent (single reviewer) - LOW confidence
</consensus_algorithm>
<recommended_models>
**Model Selection Strategy**:
This command queries Claudish dynamically using `claudish --list-models --json` to
get the latest curated model recommendations. This ensures models stay current with
OpenRouter's ecosystem without hardcoded lists.
**Dynamic Query Process**:
1. Run: `npx claudish --list-models --json`
2. Parse JSON to extract: id, name, category, pricing
3. Filter for code review: coding, reasoning, vision categories
4. Present to user with current pricing and descriptions
**Fallback Models** (if Claudish unavailable):
- x-ai/grok-code-fast-1 - xAI Grok (fast coding, good value)
- google/gemini-2.5-flash - Gemini Flash (fast and affordable)
- openai/gpt-5.1-codex - GPT-5.1 Codex (advanced analysis)
- deepseek/deepseek-chat - DeepSeek (reasoning specialist)
- Claude Sonnet 4.5 embedded (always available, FREE)
**Model Selection Best Practices**:
- Start with 2-3 external models for diversity
- Always include embedded reviewer (FREE, provides baseline)
- Consider budget-friendly options (check Claudish for FREE models like Polaris Alpha)
- Custom models: Use OpenRouter format (provider/model-name)
**See Also**: `skills/claudish-integration/SKILL.md` for integration patterns
</recommended_models>
</knowledge>
<examples>
<example name="Happy Path: Multi-Model Review with Parallel Execution">
<scenario>
User wants to review unstaged changes with 3 external models + embedded
</scenario>
<user_request>/review</user_request>
<execution>
**PHASE 1: Review Target Selection**
- Ask: "What to review?" → User: "1" (unstaged changes)
- Run: git status, git diff
- Summarize: 5 files changed, +160 -38 lines
- Ask: "Proceed?" → User: "Yes"
- Write: ai-docs/code-review-context.md
**PHASE 2: Model Selection and Cost Approval**
- Check: Claudish available ✅, API key set ✅
- Ask: "Select models" → User: "1,2,4,8" (Grok, Gemini Flash, DeepSeek, Embedded)
- Calculate costs:
* Input tokens: 160 lines × 1.5 = 240 tokens × 3 models
* Output tokens: 2000-4000 per model
* Grok: $0.08 input + $0.15-0.30 output = $0.23-0.38
* Gemini Flash: $0.05 input + $0.10-0.20 output = $0.15-0.25
* DeepSeek: $0.05 input + $0.10-0.20 output = $0.15-0.25
* Total: $0.53-0.88
- Show cost breakdown with input/output separation
- Ask: "Proceed with $0.53-0.88 cost?" → User: "Yes"
**PHASE 3: Parallel Multi-Model Review**
- Launch embedded review → Task: senior-code-reviewer (NO PROXY_MODE)
- Wait for embedded to complete → ✅
- Launch 3 external reviews IN PARALLEL (single message, 3 Tasks):
* Task: senior-code-reviewer PROXY_MODE: x-ai/grok-code-fast-1
* Task: senior-code-reviewer PROXY_MODE: google/gemini-2.5-flash
* Task: senior-code-reviewer PROXY_MODE: deepseek/deepseek-chat
- Track: ✅✅✅✅ All complete (~5 min for parallel vs 15 min sequential)
**PHASE 4: Consolidate Reviews**
- Read: 4 review files (embedded + 3 external)
- Parse: Issues from each review
- Normalize: Extract categories, locations, keywords
- Group similar issues: Use keyword-based algorithm with confidence
- Analyze consensus:
* 2 issues: Unanimous (100% - all 4 reviewers)
* 3 issues: Strong consensus (75% - 3 of 4 reviewers)
* 4 issues: Majority (50% - 2 of 4 reviewers)
* 5 issues: Divergent (25% - 1 reviewer only)
- Create model agreement matrix
- Write: ai-docs/code-review-consolidated.md
**PHASE 5: Present Results**
- Generate summary with top 5 issues (prioritized by consensus)
- Show: 2 unanimous critical issues → MUST FIX
- Show: 3 strong consensus issues → RECOMMENDED TO FIX
- Link: Detailed consolidated report
- Link: Individual review files
- Recommend: Fix 2 unanimous issues first, then re-run review
</execution>
<result>
User receives comprehensive multi-model review in ~5 minutes (parallel execution)
with clear priorities based on reviewer consensus. Total cost: ~$0.70 (within
estimated range). User trust maintained through cost transparency.
</result>
</example>
<example name="Graceful Degradation: Embedded Only">
<scenario>
Claudish not available, user opts for embedded reviewer only
</scenario>
<user_request>/review</user_request>
<execution>
**PHASE 1: Review Target Selection**
- User specifies: "Review src/services/*.ts"
- Glob: Find matching files (5 files)
- Read: File contents
- Write: ai-docs/code-review-context.md
**PHASE 2: Model Selection and Cost Approval**
- Check: Claudish not available ❌
- Show: "Claudish not found. Options: Install / Embedded Only / Cancel"
- User: "Embedded Only"
- Selected: Embedded reviewer only (no cost)
**PHASE 3: Parallel Multi-Model Review**
- Launch embedded review → Task: senior-code-reviewer
- Complete: ✅
**PHASE 4: Consolidate Reviews**
- Read: 1 review file (embedded only)
- Note: "Single reviewer (embedded only). Consensus analysis N/A."
- Write: ai-docs/code-review-consolidated.md (simpler format, no consensus)
**PHASE 5: Present Results**
- Present: Issues from embedded review (no consensus levels)
- Note: "Single reviewer. For multi-model validation, install Claudish and retry."
- Link: Embedded review file
- Recommend: Address critical issues found by embedded reviewer
</execution>
<result>
Command still provides value with embedded reviewer only. User receives
actionable feedback even without external models. Workflow completes
successfully with graceful degradation.
</result>
</example>
<example name="Error Recovery: No Changes Found">
<scenario>
User requests review but working directory is clean
</scenario>
<user_request>/review</user_request>
<execution>
**PHASE 1: Review Target Selection**
- Ask: "What to review?" → User: "1" (unstaged)
- Run: git status → No changes found
- Show: "No unstaged changes. Options: Recent commits / Files / Exit"
- User: "Recent commits"
- Ask: "Commit range?" → User: "HEAD~3..HEAD"
- Run: git diff HEAD~3..HEAD
- Summarize: 8 files changed across 3 commits
- Ask: "Proceed?" → User: "Yes"
- Write: ai-docs/code-review-context.md
[... PHASE 2-5 continue normally with commits as review target ...]
</execution>
<result>
Command recovers from "no changes" error by offering alternatives. User
selects recent commits instead and workflow continues successfully.
</result>
</example>
</examples>
<error_recovery>
<strategy scenario="No changes found">
<recovery>
Offer alternatives (review commits/files) or exit gracefully. Don't fail.
Present clear options and let user decide next action.
</recovery>
</strategy>
<strategy scenario="Claudish not available">
<recovery>
Show setup instructions with two paths: install Claudish or use npx (no install).
Offer embedded-only option as fallback. Don't block workflow.
</recovery>
</strategy>
<strategy scenario="API key not set">
<recovery>
Show setup instructions (get key from OpenRouter, set environment variable).
Wait for user to set key, or offer embedded-only option. Don't block workflow.
</recovery>
</strategy>
<strategy scenario="Some external reviews fail">
<recovery>
Continue with successful reviews. Note failures in consolidated report with
details (which model, what error). Adjust consensus calculations for actual
reviewer count. Don't fail entire workflow.
</recovery>
</strategy>
<strategy scenario="All reviews fail">
<recovery>
Show detailed error message with failure reasons for each reviewer. Save
context file for manual review. Provide troubleshooting steps (check network,
verify API key, check rate limits). Exit gracefully with clear guidance.
</recovery>
</strategy>
<strategy scenario="User cancels at approval gate">
<recovery>
Exit gracefully with message: "Review cancelled. Run /review again to restart."
Preserve context file if already created. Clear and friendly exit.
</recovery>
</strategy>
<strategy scenario="Invalid custom model ID">
<recovery>
Validate format (provider/model-name). If invalid, explain format and show
examples. Link to OpenRouter models page. Ask for corrected ID or offer to
cancel custom selection.
</recovery>
</strategy>
</error_recovery>
<success_criteria>
<criterion>✅ At least 1 review completed (embedded or external)</criterion>
<criterion>✅ Consolidated report generated with consensus analysis (if multiple reviewers)</criterion>
<criterion>✅ User receives actionable feedback prioritized by confidence</criterion>
<criterion>✅ Cost transparency maintained (show estimates with input/output breakdown before charging)</criterion>
<criterion>✅ Parallel execution achieves 3-5x speedup on external reviews</criterion>
<criterion>✅ Graceful degradation works (embedded-only path functional)</criterion>
<criterion>✅ Clear error messages and recovery options for all failure scenarios</criterion>
<criterion>✅ TodoWrite tracking shows progress through all 5 phases</criterion>
<criterion>✅ Consensus algorithm uses simplified keyword-based approach with confidence levels</criterion>
</success_criteria>
<formatting>
<communication_style>
- Be clear and concise in user-facing messages
- Use visual indicators for clarity (checkmarks, alerts, progress)
- Show real-time progress indicators for long-running operations (parallel reviews)
* Format: "Review 1/3 complete: Grok (✓), Gemini (⏳), DeepSeek (⏹)"
* Update as each review completes to keep users informed during 5-10 min execution
* Use status symbols: ✓ (complete), ⏳ (in progress), ⏹ (pending)
- Provide context and rationale for recommendations
- Make costs and trade-offs transparent (input/output token breakdown)
- Present brief summaries (under 50 lines) for user, link to detailed reports
</communication_style>
<deliverables>
<file name="ai-docs/code-review-context.md">
Review context with diff/files and instructions for reviewers
</file>
<file name="ai-docs/code-review-local.md">
Embedded Claude Sonnet review (if embedded selected)
</file>
<file name="ai-docs/code-review-{model}.md">
External model review (one file per external model, sanitized filename)
</file>
<file name="ai-docs/code-review-consolidated.md">
Consolidated report with consensus analysis, priorities, and recommendations
</file>
</deliverables>
<user_summary_format>
Present brief summary (under 50 lines) with:
- Reviewer count and models used
- Overall verdict (PASSED/REQUIRES_IMPROVEMENT/FAILED)
- Top 5 most important issues prioritized by consensus
- Code strengths acknowledged by multiple reviewers
- Links to detailed consolidated report and individual reviews
- Clear next steps and recommendations
- Cost breakdown with actual cost (if external models used)
</user_summary_format>
</formatting>

911
commands/validate-ui.md Normal file
View File

@@ -0,0 +1,911 @@
---
description: Multi-agent orchestrated UI design validation with iterative fixes and optional external AI expert review
---
## Architecture Note
This command implements the **UI Issue Debug Flow** from the ultra-efficient frontend development architecture. It focuses specifically on validating and fixing visual/layout/design issues.
For comprehensive information about:
- User validation loops
- Issue-specific debug flows (UI, Functional, Mixed)
- Main thread orchestration principles
- Context-efficient agent delegation
See: `docs/USER_VALIDATION_FLOW.md`
This validation workflow is also used within the `/implement` command's Phase 5 User Validation Loop when users report UI issues.
---
## Task
**Multi-agent orchestration command** - coordinate between designer agent (reviews UI fidelity), ui-developer agent (fixes UI issues), and optional external AI models (GPT-5 Codex, Grok) for independent expert review via Claudish CLI to iteratively validate and fix UI implementation against design references.
### Phase 1: Gather User Inputs
Ask the user directly for the following information:
**Ask user to provide:**
1. **Design reference** (Figma URL, local file path, or remote URL)
- Example Figma: `https://figma.com/design/abc123/...?node-id=136-5051`
- Example remote: `http://localhost:5173/users`
- Example local: `/Users/you/Downloads/design.png`
2. **Component description** (what are you validating?)
- Example: "user profile page", "main dashboard", "product card component"
3. **Use external AI expert review?** (yes or no)
- "yes" to enable external AI model review (GPT-5 Codex via Claudish CLI) on each iteration
- "no" to use only Claude Sonnet designer review
**Auto-detect reference type from user's input:**
- Contains "figma.com" → Figma design
- Starts with "http://localhost" or "http://127.0.0.1" → Remote URL (live component)
- Otherwise → Local file path (screenshot)
### Phase 2: Parse Inputs and Find Implementation
Parse the user's text responses:
- Extract design reference (user's answer to question 1)
- Extract component description (user's answer to question 2)
- Extract external AI review preference (user's answer to question 3: "yes" or "no")
Auto-detect reference type from the reference string:
- Contains "figma.com" → Figma design
- Starts with "http://localhost" or "http://127.0.0.1" → Remote URL (live component)
- Otherwise → Local file path (screenshot)
Validate inputs:
- Check reference is not empty
- Check component description is not empty
- If either is empty: Ask user to provide that information
Validate reference:
- If Figma detected: Parse URL to extract fileKey and nodeId, verify format
- If Remote URL detected: Verify URL format is valid
- If Local file detected: Verify file path exists and is readable
Find implementation files based on description:
- Use the description to search for relevant files in the codebase
- Search strategies:
- Convert description to likely component names (e.g., "user profile page" → "UserProfile", "UserProfilePage")
- Search for matching files in src/components/, src/routes/, src/pages/
- Use Glob to find files like `**/User*Profile*.tsx`, `**/user*profile*.tsx`
- Use Grep to search for component exports matching the description
- If multiple files found: Choose most relevant or ask user to clarify
- If no files found: Ask user to provide file path manually
Store the found implementation file(s) for use in validation loop.
If any validation fails, re-ask for that specific input with clarification.
### Phase 3: Multi-Agent Iteration Loop
Run up to **10 iterations** of the following sequence:
#### Step 3.1: Launch Designer Agent(s) for Parallel Design Validation
**IMPORTANT**: If external AI review is enabled, launch TWO designer agents IN PARALLEL using a SINGLE message with TWO Task tool calls (one normal, one with PROXY_MODE for external AI).
**Designer Agent** (always runs):
Pass inputs to designer agent using the Task tool:
```
Review the [Component Name] implementation against the design reference and provide a detailed design fidelity report.
**CRITICAL**: Be PRECISE and CRITICAL. Do not try to make everything look good. Your job is to identify EVERY discrepancy between the design reference and implementation, no matter how small. Focus on accuracy and design fidelity.
**Design Reference**: [Figma URL | file path | remote URL]
**Component Description**: [user description, e.g., "user profile page"]
**Implementation File(s)**: [found file paths, e.g., "src/components/UserProfile.tsx"]
**Application URL**: [e.g., "http://localhost:5173" or staging URL]
**Your Tasks:**
1. Fetch the design reference:
- If Figma: Use Figma MCP to fetch the design screenshot
- If Remote URL: Use chrome-devtools MCP to take screenshot of the URL
- If Local file: Read the provided file path
2. Capture implementation screenshot:
- Navigate to application URL
- Use Chrome DevTools MCP to capture implementation screenshot
- Use same viewport size as reference for fair comparison
3. Read implementation files to understand code structure
4. Perform comprehensive design review comparing:
- Colors & theming
- Typography
- Spacing & layout
- Visual elements (borders, shadows, icons)
- Responsive design
- Accessibility (WCAG 2.1 AA)
- Interactive states
5. Document ALL discrepancies with specific values
6. Categorize issues by severity (CRITICAL/MEDIUM/LOW)
7. Provide actionable fixes with code snippets
8. Calculate design fidelity score
**REMEMBER**: Be PRECISE and CRITICAL. Identify ALL discrepancies. Do not be lenient.
Return detailed design review report.
```
**External AI Designer Review** (if enabled):
If user selected "Yes" for external AI review, launch designer agent WITH PROXY_MODE IN PARALLEL with the normal designer agent:
Use Task tool with `subagent_type: frontend:designer` and start the prompt with:
```
PROXY_MODE: design-review
Review the [Component Name] implementation against the design reference and provide a detailed design fidelity report.
**CRITICAL**: Be PRECISE and CRITICAL. Do not try to make everything look good. Your job is to identify EVERY discrepancy between the design reference and implementation, no matter how small. Focus on accuracy and design fidelity.
**Design Reference**: [Figma URL | file path | remote URL]
**Component Description**: [user description, e.g., "user profile page"]
**Implementation File(s)**: [found file paths, e.g., "src/components/UserProfile.tsx"]
**Application URL**: [e.g., "http://localhost:5173" or staging URL]
**Your Tasks:**
[Same validation tasks as Designer Agent above - full design review with same criteria]
VALIDATION CRITERIA:
1. **Colors & Theming**
- Brand colors accuracy (primary, secondary, accent)
- Text color hierarchy (headings, body, muted)
- Background colors and gradients
- Border and divider colors
- Hover/focus/active state colors
2. **Typography**
- Font families (heading vs body)
- Font sizes (all text elements)
- Font weights (regular, medium, semibold, bold)
- Line heights and letter spacing
- Text alignment
3. **Spacing & Layout**
- Component padding (all sides)
- Element margins and gaps
- Grid/flex spacing
- Container max-widths
- Alignment (center, left, right, space-between)
4. **Visual Elements**
- Border radius (rounded corners)
- Border widths and styles
- Box shadows (elevation levels)
- Icons (size, color, positioning)
- Images (aspect ratios, object-fit)
- Dividers and separators
5. **Responsive Design**
- Mobile breakpoint behavior (< 640px)
- Tablet breakpoint behavior (640px - 1024px)
- Desktop breakpoint behavior (> 1024px)
- Layout shifts and reflows
- Touch target sizes (minimum 44x44px)
6. **Accessibility (WCAG 2.1 AA)**
- Color contrast ratios (text: 4.5:1, large text: 3:1)
- Focus indicators
- ARIA attributes
- Semantic HTML
- Keyboard navigation
TECH STACK:
- React 19 with TypeScript
- Tailwind CSS 4
- Design System: [shadcn/ui, MUI, custom, or specify if detected]
INSTRUCTIONS:
Compare the design reference and implementation carefully.
Provide a comprehensive design validation report categorized as:
- CRITICAL: Must fix (design fidelity errors, accessibility violations, wrong colors)
- MEDIUM: Should fix (spacing issues, typography mismatches, minor design deviations)
- LOW: Nice to have (polish, micro-interactions, suggestions)
For EACH finding provide:
1. Category (colors/typography/spacing/layout/visual-elements/responsive/accessibility)
2. Severity (critical/medium/low)
3. Specific issue description with exact values
4. Expected design specification
5. Current implementation
6. Recommended fix with specific Tailwind CSS classes or hex values
7. Rationale (why this matters for design fidelity)
Calculate a design fidelity score:
- Colors: X/10
- Typography: X/10
- Spacing: X/10
- Layout: X/10
- Accessibility: X/10
- Responsive: X/10
Overall: X/60
Provide overall assessment: PASS ✅ | NEEDS IMPROVEMENT ⚠️ | FAIL ❌
REMEMBER: Be PRECISE and CRITICAL. Identify ALL discrepancies. Do not be lenient.
You will forward this to Codex AI which will capture the design reference screenshot and implementation screenshot to compare them.
```
**Wait for BOTH agents to complete** (designer and designer-codex, if enabled).
#### Step 3.2: Consolidate Design Review Results
After both agents complete, consolidate their findings:
**If only designer ran:**
- Use designer's report as-is
**If both designer and designer-codex ran:**
- Compare findings from both agents
- Identify common issues (flagged by both) → Highest priority
- Identify issues found by only one agent → Review for inclusion
- Create consolidated issue list with:
- Issue description
- Severity (use highest severity if both flagged)
- Source (designer, designer-codex, or both)
- Recommended fix
**Consolidation Strategy:**
- Issues flagged by BOTH agents → CRITICAL (definitely needs fixing)
- Issues flagged by ONE agent with severity CRITICAL → CRITICAL (trust the expert)
- Issues flagged by ONE agent with severity MEDIUM → MEDIUM (probably needs fixing)
- Issues flagged by ONE agent with severity LOW → LOW (nice to have)
Create a consolidated design review report that includes:
```markdown
# Consolidated Design Review (Iteration X)
## Sources
- ✅ Designer Agent (human-style design expert)
[If Codex enabled:]
- ✅ Designer-Codex Agent (external Codex AI expert)
## Issues Found
### CRITICAL Issues (Must Fix)
[List issues with severity CRITICAL from either agent]
- [Issue description]
- Source: [designer | designer-codex | both]
- Expected: [specific value]
- Actual: [specific value]
- Fix: [specific code change]
### MEDIUM Issues (Should Fix)
[List issues with severity MEDIUM from either agent]
### LOW Issues (Nice to Have)
[List issues with severity LOW from either agent]
## Design Fidelity Scores
- Designer: [score]/60
[If Codex enabled:]
- Designer-Codex: [score]/60
- Average: [average]/60
## Overall Assessment
[PASS ✅ | NEEDS IMPROVEMENT ⚠️ | FAIL ❌]
Based on consensus from [1 or 2] design validation agent(s).
```
#### Step 3.3: Launch UI Developer Agent to Apply Fixes
Use Task tool with `subagent_type: frontend:ui-developer`:
```
Fix the UI implementation issues identified in the consolidated design review from multiple validation sources.
**Component**: [Component Name]
**Implementation File(s)**: [found file paths, e.g., "src/components/UserProfile.tsx"]
**CONSOLIDATED DESIGN REVIEW** (From Multiple Independent Sources):
[Paste complete consolidated design review report from Step 3.2]
This consolidated report includes findings from:
- Designer Agent (human-style design expert)
[If Codex enabled:]
- Designer-Codex Agent (external Codex AI expert)
Issues flagged by BOTH agents are highest priority and MUST be fixed.
**Your Task:**
1. Read all implementation files
2. Address CRITICAL issues first (especially those flagged by both agents), then MEDIUM, then LOW
3. Apply fixes using modern React/TypeScript/Tailwind best practices:
- Fix colors using correct Tailwind classes or exact hex values
- Fix spacing using proper Tailwind scale (p-4, p-6, etc.)
- Fix typography (font sizes, weights, line heights)
- Fix layout issues (max-width, alignment, grid/flex)
- Fix accessibility (ARIA, contrast, keyboard nav)
- Fix responsive design (mobile-first breakpoints)
4. Use Edit tool to modify files
5. Run quality checks (typecheck, lint, build)
6. Provide implementation summary indicating:
- Which issues were fixed
- Which sources (designer, designer-codex, or both) flagged each issue
- Files modified
- Changes made
DO NOT re-validate. Only apply the fixes.
```
Wait for ui-developer agent to return summary of applied changes.
#### Step 3.4: Check Loop Status
After ui-developer agent completes:
- Increment iteration count
- If designer assessment is NOT "PASS" AND iteration < 10:
* Go back to Step 3.1 (re-run designer agent)
- If designer assessment is "PASS" OR iteration = 10:
* Log: "Automated validation complete. Proceeding to user validation."
* Exit loop and proceed to Phase 3.5 (User Manual Validation)
Track and display progress: "Iteration X/10 complete"
### Phase 3.5: MANDATORY User Manual Validation Gate
**IMPORTANT**: This step is MANDATORY before generating the final report. Never skip this step.
Even when designer agent claims "PASS", the user must manually verify the implementation against the real design reference.
**Present to user:**
```
🎯 Automated Validation Complete - User Verification Required
After [iteration_count] iterations, the designer agent has completed its review.
**Validation Summary:**
- Component: [component_description]
- Iterations completed: [iteration_count] / 10
- Last designer assessment: [PASS ✅ / NEEDS IMPROVEMENT ⚠️ / FAIL ❌]
- Final design fidelity score: [score] / 60
- Issues remaining (automated): [count]
However, automated validation can miss subtle issues. Please manually verify the implementation:
**What to Check:**
1. Open the application at: [app_url or remote URL]
2. View the component: [component_description]
3. Compare against design reference: [design_reference]
4. Check for:
- Colors match exactly (backgrounds, text, borders)
- Spacing and layout are pixel-perfect
- Typography (fonts, sizes, weights, line heights) match
- Visual elements (shadows, borders, icons) match
- Interactive states work correctly (hover, focus, active, disabled)
- Responsive design works on mobile, tablet, desktop
- Accessibility features work properly (keyboard nav, ARIA)
- Overall visual fidelity matches the design
Please manually test the implementation and let me know:
```
Use AskUserQuestion to ask:
```
Does the implementation match the design reference?
Please manually test the UI and compare it to the design.
Options:
1. "Yes - Looks perfect, matches design exactly" → Approve and generate report
2. "No - I found issues" → Provide feedback to continue fixing
```
**If user selects "Yes - Looks perfect":**
- Log: "✅ User approved! Implementation verified by human review."
- Proceed to Phase 4 (Generate Final Report)
**If user selects "No - I found issues":**
- Ask user to provide specific feedback:
```
Please describe the issues you found. You can provide:
1. **Screenshot** - Path to a screenshot showing the issue(s)
2. **Text Description** - Detailed description of what's wrong
Example descriptions:
- "The header background color is too light - should be #1a1a1a not #333333"
- "Button spacing is wrong - there should be 24px between buttons not 16px"
- "Font size on mobile is too small - headings should be 24px not 18px"
- "The card shadow is missing - should have shadow-lg"
- "Profile avatar should be 64px not 48px"
- "Text alignment is off-center, should be centered"
What issues did you find?
```
- Collect user's feedback (text or screenshot path)
- Store feedback as `user_feedback`
- Check if we've exceeded max total iterations (10 automated + 5 user feedback rounds = 15 total):
* If exceeded: Ask user if they want to continue or accept current state
* If not exceeded: Proceed with user feedback fixes
- Log: "⚠️ User found issues. Launching UI Developer to address user feedback."
- Use Task tool with appropriate fixing agent (ui-developer or ui-developer-codex):
```
Fix the UI implementation issues identified by the USER during manual testing.
**CRITICAL**: These issues were found by a human reviewer, not automated validation.
The user manually tested the implementation and found real problems.
**Component**: [component_description]
**Design Reference**: [design_reference]
**Implementation File(s)**: [found file paths]
**Application URL**: [app_url or remote URL]
**USER FEEDBACK** (Human Manual Testing):
[Paste user's complete feedback - text description or screenshot analysis]
[If screenshot provided:]
**User's Screenshot**: [screenshot_path]
Please read the screenshot to understand the visual issues the user is pointing out.
**Your Task:**
1. Fetch design reference (Figma MCP / Chrome DevTools / Read file)
2. Read all implementation files
3. Carefully review the user's specific feedback
4. Address EVERY issue the user mentioned:
- If user mentioned colors: Fix to exact hex values or Tailwind classes
- If user mentioned spacing: Fix to exact pixel values mentioned
- If user mentioned typography: Fix font sizes, weights, line heights
- If user mentioned layout: Fix alignment, max-width, grid/flex issues
- If user mentioned visual elements: Fix shadows, borders, border-radius
- If user mentioned interactive states: Fix hover, focus, active, disabled
- If user mentioned responsive: Fix mobile, tablet, desktop breakpoints
- If user mentioned accessibility: Fix ARIA, contrast, keyboard navigation
5. Use Edit tool to modify files
6. Use modern React/TypeScript/Tailwind best practices:
- React 19 patterns
- Tailwind CSS 4 (utility-first, no @apply, static classes only)
- Mobile-first responsive design
- WCAG 2.1 AA accessibility
7. Run quality checks (typecheck, lint, build)
8. Provide detailed implementation summary explaining:
- Each user issue addressed
- Exact changes made
- Files modified
- Any trade-offs or decisions made
**IMPORTANT**: User feedback takes priority over designer agent feedback.
The user has manually tested and seen real issues that automated validation missed.
Return detailed fix summary when complete.
```
- Wait for fixing agent to complete
- After fixes applied:
* Log: "User-reported issues addressed. Re-running designer validation."
* Increment `user_feedback_round` counter
* Re-run designer agent (Step 3.1) to validate fixes
* Loop back to Phase 3.5 (User Manual Validation) to verify with user again
* Continue until user approves
**End of Phase 3.5 (User Manual Validation Gate)**
### Phase 4: Generate Final Report
After loop completes (10 iterations OR designer reports no issues):
1. Create temp directory: `/tmp/ui-validation-[timestamp]/`
2. Save iteration history to `report.md`:
```markdown
# UI Validation Report
## Validating: [user description, e.g., "user profile page"]
## Implementation: [file path(s)]
## Automated Iterations: [count]/10
## User Feedback Rounds: [count]
## Third-Party Review: [Enabled/Disabled]
## User Manual Validation: ✅ APPROVED
## Iteration History:
### Iteration 1 (Automated)
**Designer Review Report:**
[issues found]
[If Codex enabled:]
**Codex Expert Review:**
[expert opinion]
**UI Developer Changes:**
[fixes applied]
### Iteration 2 (Automated)
...
### User Validation Round 1
**User Feedback:**
[user's description or screenshot reference]
**Issues Reported by User:**
- [Issue 1]
- [Issue 2]
...
**UI Developer Fixes:**
[fixes applied based on user feedback]
**Designer Re-validation:**
[designer assessment after user-requested fixes]
### User Validation Round 2
...
## Final Status:
**Automated Validation**: [PASS ✅ / NEEDS IMPROVEMENT ⚠️ / FAIL ❌]
**User Manual Validation**: ✅ APPROVED
**Overall**: Success - Implementation matches design reference
## Summary:
- Total automated iterations: [count]
- Total user feedback rounds: [count]
- Issues found by automation: X
- Issues found by user: Y
- Total issues fixed: Z
- User approval: ✅ "Looks perfect, matches design exactly"
```
3. Save final screenshots:
- `reference.png` (original design screenshot from Figma/URL/file)
- `implementation-final.png` (final implementation screenshot from app URL)
4. Generate `comparison.html` with side-by-side visual comparison:
- **MUST display both screenshots side-by-side** (not text)
- Left side: `reference.png` (design reference)
- Right side: `implementation-final.png` (final implementation)
- Include zoom/pan controls for detailed inspection
- Show validation summary below screenshots
- Format:
```html
<!DOCTYPE html>
<html>
<head>
<title>UI Validation - Side-by-Side Comparison</title>
<style>
.comparison-container { display: flex; gap: 20px; }
.screenshot-panel { flex: 1; }
.screenshot-panel img { width: 100%; border: 1px solid #ccc; }
.screenshot-panel h3 { text-align: center; }
</style>
</head>
<body>
<h1>UI Validation: [component_description]</h1>
<div class="comparison-container">
<div class="screenshot-panel">
<h3>Design Reference</h3>
<img src="reference.png" alt="Design Reference">
</div>
<div class="screenshot-panel">
<h3>Final Implementation</h3>
<img src="implementation-final.png" alt="Final Implementation">
</div>
</div>
<div class="summary">
[Include validation summary with user approval]
</div>
</body>
</html>
```
### Phase 5: Present Results to User
Display summary:
- Total automated iterations run
- Total user feedback rounds
- User manual validation status: ✅ APPROVED
- Final status (success/needs review)
- Path to detailed report
- Link to comparison HTML
Present:
```
✅ UI Validation Complete!
**Validation Summary:**
- Component: [component_description]
- Automated iterations: [count] / 10
- User feedback rounds: [count]
- User manual validation: ✅ APPROVED
**Results:**
- Issues found by automation: [count]
- Issues found by user: [count]
- Total issues fixed: [count]
- Final designer assessment: [PASS/NEEDS IMPROVEMENT/FAIL]
- **User approval**: ✅ "Looks perfect, matches design exactly"
**Report Location:**
- Detailed report: /tmp/ui-validation-[timestamp]/report.md
- Side-by-side comparison: /tmp/ui-validation-[timestamp]/comparison.html
The implementation has been validated and approved by human review!
```
Ask user for next action:
- "View detailed report" → Open report directory
- "View git diff" → Show git diff of changes
- "Accept and commit changes" → Commit with validation report
- "Done" → Exit
### Implementation Notes
**Command Responsibilities (Orchestration Only):**
- Ask user for 3 pieces of information (text prompts)
1. Design reference (Figma URL, remote URL, or local file path)
2. Component description
3. Use Codex helper? (yes/no)
- Parse user's text responses
- Auto-detect reference type (Figma/Remote URL/Local file)
- Validate reference (file exists, URL format)
- Find implementation files from description using Glob/Grep
- Track iteration count (1-10)
- Orchestrate the multi-agent loop:
- Launch designer agent
- Optionally launch ui-developer-codex proxy for expert review
- Launch ui-developer agent
- Repeat up to 10 times
- Generate final report with iteration history
- Save screenshots and comparison HTML
- Present results to user
- Handle next action choice
**Designer Agent Responsibilities:**
- Fetch design reference screenshot (Figma MCP or Chrome DevTools)
- Capture implementation screenshot via Chrome DevTools
- Read implementation files to understand code structure
- Perform comprehensive design review:
- Colors & theming
- Typography
- Spacing & layout
- Visual elements
- Responsive design
- Accessibility (WCAG 2.1 AA)
- Interactive states
- Return detailed design review report with:
- Specific issues found with exact values
- Actionable fixes with code snippets
- Severity categorization (CRITICAL/MEDIUM/LOW)
- File paths and line numbers
- Design fidelity score
- **DOES NOT apply fixes - only reviews and reports**
**UI Developer Codex Agent Responsibilities (Optional Proxy):**
- Receive designer's review report from orchestrator
- Forward complete prompt to Codex AI via mcp__codex-cli__ask-codex
- Return Codex's expert analysis verbatim
- Provides independent third-party validation
- **Does NOT do any preparation - pure proxy**
**UI Developer Agent Responsibilities:**
- Receive designer feedback (and optional Codex review)
- Read implementation files
- Apply fixes using modern React/TypeScript/Tailwind best practices:
- Fix colors with correct Tailwind classes
- Fix spacing with proper scale
- Fix typography
- Fix layout issues
- Fix accessibility issues
- Fix responsive design
- Use Edit tool to modify files
- Run quality checks (typecheck, lint, build)
- Provide implementation summary
- **DOES NOT re-validate - only implements fixes**
**Key Principles:**
1. Command orchestrates the loop, does NOT do the work
2. Designer ONLY reviews design fidelity and reports, does NOT fix
3. UI Developer ONLY implements fixes, does NOT validate
4. UI Developer Codex (optional) provides expert third-party review
5. Loop continues until 10 iterations OR designer reports no issues (PASS)
6. **MANDATORY: User manual validation required after automated loop completes**
7. User can provide feedback with screenshots or text descriptions
8. User feedback triggers additional fixing rounds until user approves
### Example User Flow
```
User: /validate-ui
Command: "Please provide the following information:"
Command: "1. Design reference (Figma URL, local file path, or remote URL):"
User: "https://figma.com/design/abc123.../node-id=136-5051"
Command: "2. Component description (what are you validating?):"
User: "user profile page"
Command: "3. Use Codex agent helper? (yes/no):"
User: "yes"
Command: [Parses responses]
Command: [Auto-detects: Figma design ✓]
Command: [Searches codebase for "user profile page"]
Command: [Finds: src/components/UserProfile.tsx]
Command: "✓ Reference type: Figma (auto-detected)"
Command: "✓ Component: user profile page"
Command: "✓ Found implementation: src/components/UserProfile.tsx"
Command: "✓ Codex agent helper: Enabled"
Command: "Starting validation loop (max 10 iterations)..."
━━━ Iteration 1/10 ━━━
Command: [Launches designer agent]
Designer: [Performs design review, returns report with 5 issues]
Command: [Launches ui-developer-codex proxy]
Codex: [Provides expert recommendations via proxy]
Command: [Launches ui-developer agent]
UI Developer: [Applies fixes, returns summary]
Command: "Iteration 1/10 complete. 5 issues addressed."
━━━ Iteration 2/10 ━━━
Command: [Re-runs designer agent]
Designer: [Finds 2 remaining issues]
Command: [Launches ui-developer-codex]
Codex: [Provides recommendations]
Command: [Launches ui-developer]
UI Developer: [Applies fixes]
Command: "Iteration 2/10 complete. 2 more issues addressed."
━━━ Iteration 3/10 ━━━
Command: [Re-runs designer agent]
Designer: [Reports: "Assessment: PASS - No issues found, implementation matches design"]
Command: "Automated validation passed! Proceeding to user manual validation."
Command: [Exits automated loop - 3 iterations completed]
━━━ User Manual Validation ━━━
Command: "🎯 Automated Validation Passed - User Verification Required"
Command: [Explains what to check and asks user to verify]
User: [Tests the UI manually, compares to Figma design]
User: "No - I found issues"
Command: "Please describe the issues you found."
User: "The button text color is too light on the blue background - hard to read. Should be white #ffffff not gray #cccccc. Also the spacing between the header and content is too tight - should be 32px not 16px."
Command: [Stores user feedback]
Command: "⚠️ User found 2 issues. Launching UI Developer."
Command: [Launches ui-developer with user's specific feedback]
UI Developer: [Fixes the text color to #ffffff and spacing to 32px, runs quality checks]
UI Developer: "Fixed button text color and header spacing as requested."
Command: "User-reported issues addressed. Re-running designer validation."
Command: [Launches designer agent]
Designer: [Validates fixes, reports: "PASS - Issues resolved"]
Command: "I've addressed all the issues you reported. Please verify the fixes."
User: "Yes - Looks perfect, matches design exactly"
Command: "✅ User approved! Implementation verified by human review."
━━━ Final Report ━━━
Command: [Creates /tmp/ui-validation-20251104-235623/]
Command: [Saves report.md, screenshots, comparison.html]
Command: [Displays summary]
"✅ UI Validation Complete!
**Validation Summary:**
- Component: user profile page
- Automated iterations: 3 / 10
- User feedback rounds: 1
- User manual validation: ✅ APPROVED
**Results:**
- Issues found by automation: 7
- Issues found by user: 2
- Total issues fixed: 9
- Final designer assessment: PASS ✅
- **User approval**: ✅ "Looks perfect, matches design exactly"
**Report Location:**
- Detailed report: /tmp/ui-validation-20251104-235623/report.md
- Side-by-side comparison: /tmp/ui-validation-20251104-235623/comparison.html
The implementation has been validated and approved by human review!"
Command: [Asks for next action]
```
### Arguments
$ARGUMENTS - Optional: Can provide design reference path, Figma URL, or component name directly to skip some questions
### Quick Reference
**Command does (Orchestration):**
- ✅ Ask user 3 questions via text prompts
- ✅ Parse responses and auto-detect reference type
- ✅ Find implementation files from description
- ✅ Track iteration count (1-10)
- ✅ Launch designer agent (each iteration)
- ✅ Launch ui-developer-codex proxy (if enabled)
- ✅ Launch ui-developer agent (each iteration)
- ✅ Generate final report
- ✅ Present results
**Designer Agent does:**
- ✅ Fetch design reference screenshots (Figma/remote/local)
- ✅ Capture implementation screenshots
- ✅ Perform comprehensive design review
- ✅ Compare and identify all UI discrepancies
- ✅ Categorize by severity (CRITICAL/MEDIUM/LOW)
- ✅ Calculate design fidelity score
- ✅ Provide actionable fixes with code snippets
- ✅ Return detailed design review report
- ❌ Does NOT apply fixes
**UI Developer Codex Agent does (Optional Proxy):**
- ✅ Receive complete prompt from orchestrator
- ✅ Forward to Codex AI via mcp__codex-cli__ask-codex
- ✅ Return Codex's expert analysis verbatim
- ✅ Provide third-party validation
- ❌ Does NOT prepare context (pure proxy)
**UI Developer Agent does:**
- ✅ Receive designer feedback (+ optional Codex review)
- ✅ Apply fixes using React/TypeScript/Tailwind best practices
- ✅ Fix colors, spacing, typography, layout, accessibility
- ✅ Update Tailwind CSS classes
- ✅ Run quality checks (typecheck, lint, build)
- ✅ Return implementation summary
- ❌ Does NOT re-validate
**Loop Flow:**
```
1. Designer → Design Review Report
2. (Optional) UI Developer Codex → Expert Opinion (via Codex AI)
3. UI Developer → Apply Fixes
4. Repeat steps 1-3 up to 10 times
5. Generate final report
```
### Important Details
**Early Exit:**
- If designer reports "Assessment: PASS" at any iteration, exit loop immediately
- Display total iterations used (e.g., "Complete after 3/10 iterations")
**Error Handling:**
- If agent fails 3 times consecutively: Exit loop and report to user
- Log errors but continue iterations when possible
**MCP Usage:**
- Figma MCP: Fetch design screenshots (once at start)
- Chrome DevTools MCP: Capture implementation screenshots (every iteration)
- Codex CLI MCP: Expert review (every iteration if enabled)
**Best Practices:**
- Keep validator reports concise but specific
- Include file paths and line numbers
- Prioritize issues by severity
- Track issues found vs fixed in final report