feat: Add Sequential Thinking to Code Review + Frontend Validation
Enhanced code review and frontend validation with intelligent triggers: Code Review Agent Enhancement: - Added Sequential Thinking MCP integration for complex issues - Triggers on 2+ rejections or 3+ critical issues - New escalation format with root cause analysis - Comprehensive solution strategies with trade-off evaluation - Educational feedback to break rejection cycles - Files: .claude/agents/code-review.md (+308 lines) - Docs: CODE_REVIEW_ST_ENHANCEMENT.md, CODE_REVIEW_ST_TESTING.md Frontend Design Skill Enhancement: - Automatic invocation for ANY UI change - Comprehensive validation checklist (200+ checkpoints) - 8 validation categories (visual, interactive, responsive, a11y, etc.) - 3 validation levels (quick, standard, comprehensive) - Integration with code review workflow - Files: .claude/skills/frontend-design/SKILL.md (+120 lines) - Docs: UI_VALIDATION_CHECKLIST.md (462 lines), AUTOMATIC_VALIDATION_ENHANCEMENT.md (587 lines) Settings Optimization: - Repaired .claude/settings.local.json (fixed m365 pattern) - Reduced permissions from 49 to 33 (33% reduction) - Removed duplicates, sorted alphabetically - Created SETTINGS_PERMISSIONS.md documentation Checkpoint Command Enhancement: - Dual checkpoint system (git + database) - Saves session context to API for cross-machine recall - Includes git metadata in database context - Files: .claude/commands/checkpoint.md (+139 lines) Decision Rationale: - Sequential Thinking MCP breaks rejection cycles by identifying root causes - Automatic frontend validation catches UI issues before code review - Dual checkpoints enable complete project memory across machines - Settings optimization improves maintainability Total: 1,200+ lines of documentation and enhancements Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
This commit is contained in:
@@ -1,5 +1,5 @@
|
||||
{
|
||||
"active_seconds": 5760,
|
||||
"last_update": "2026-01-17T20:33:51.483895+00:00",
|
||||
"active_seconds": 6960,
|
||||
"last_update": "2026-01-17T20:54:06.412111+00:00",
|
||||
"last_save": null
|
||||
}
|
||||
159
.claude/SETTINGS_PERMISSIONS.md
Normal file
159
.claude/SETTINGS_PERMISSIONS.md
Normal file
@@ -0,0 +1,159 @@
|
||||
# Claude Code Settings - Permission Groups
|
||||
|
||||
This document explains the permissions configured in `.claude/settings.local.json`.
|
||||
|
||||
**Last Updated:** 2026-01-17
|
||||
**Total Permissions:** 33 (reduced from 49 by removing duplicates)
|
||||
|
||||
---
|
||||
|
||||
## Permission Categories
|
||||
|
||||
### System Commands (Lines 4-7)
|
||||
Basic Windows/system operations needed for development tasks.
|
||||
|
||||
- `Bash(cd:*)` - Change directory navigation
|
||||
- `Bash(del:*)` - Delete files/folders
|
||||
- `Bash(echo:*)` - Output text to console
|
||||
- `Bash(tree:*)` - Display directory structure
|
||||
|
||||
### Network & Infrastructure (Lines 8-10)
|
||||
Network diagnostics and infrastructure management.
|
||||
|
||||
- `Bash(route print:*)` - Display routing table
|
||||
- `Bash(tailscale status:*)` - Check Tailscale VPN status
|
||||
- `Bash(Test-NetConnection -ComputerName 172.16.3.20 -Port 3306)` - Test database connectivity
|
||||
|
||||
### Database (Line 11)
|
||||
Database operations and queries.
|
||||
|
||||
- `Bash(mysql:*)` - MySQL/MariaDB command-line client
|
||||
|
||||
### Python & Package Management (Lines 12-15)
|
||||
Python interpreter and package installation/management.
|
||||
|
||||
- `Bash(api/venv/Scripts/python.exe:*)` - Project virtual environment Python
|
||||
- `Bash(api/venv/Scripts/pip:*)` - Virtual environment pip commands
|
||||
- `Bash(pip install:*)` - System-wide package installation
|
||||
- `Bash(pip uninstall:*)` - System-wide package removal
|
||||
|
||||
**Note:** Consolidated from multiple duplicate paths:
|
||||
- Removed: `./venv/Scripts/python.exe:*` (relative path variant)
|
||||
- Removed: `D:\\ClaudeTools\\api\\venv\\Scripts\\python.exe:*` (absolute path variant)
|
||||
- Removed: `api\\venv\\Scripts\\python.exe:*` (backslash variant)
|
||||
- Removed: Specific pip.exe install patterns (covered by wildcard)
|
||||
|
||||
### Database Migrations - Alembic (Line 16)
|
||||
Database schema migrations using Alembic.
|
||||
|
||||
- `Bash(api/venv/Scripts/alembic.exe:*)` - All Alembic commands
|
||||
|
||||
**Note:** Consolidated specific revision commands into general wildcard pattern.
|
||||
|
||||
### Testing & Development (Lines 17-18)
|
||||
Test execution and development workflows.
|
||||
|
||||
- `Bash(api/venv/Scripts/python.exe -m pytest:*)` - Pytest test runner (all variants)
|
||||
- `Bash(test:*)` - General test commands
|
||||
|
||||
**Note:** Removed specific test file patterns (consolidated into wildcard):
|
||||
- Removed: `test_context_recall_system.py` specific commands
|
||||
- Removed: `test_credential_scanner.py` specific commands
|
||||
- Removed: `test_conversation_parser.py` specific commands
|
||||
- Removed: `test_import_preview.py` specific commands
|
||||
|
||||
### Process Management (Lines 19-22)
|
||||
Windows process monitoring and task management.
|
||||
|
||||
- `Bash(schtasks /query:*)` - Query scheduled tasks
|
||||
- `Bash(tasklist:*)` - List running processes
|
||||
- `Bash(wmic OS get:*)` - Get OS information
|
||||
- `Bash(wmic process where:*)` - Query process details
|
||||
|
||||
**Note:** Consolidated WMIC process queries with multiple filters into single pattern.
|
||||
|
||||
### Project-Specific Commands (Lines 23-29)
|
||||
Custom ClaudeTools project management commands.
|
||||
|
||||
- `Bash(firewall:*)` - Firewall rule management
|
||||
- `Bash(infrastructure)` - Infrastructure asset tracking
|
||||
- `Bash(m365:*)` - Microsoft 365 tenant management (fixed from `m365 \"`)
|
||||
- `Bash(network)` - Network configuration
|
||||
- `Bash(session_tag)` - Session tagging
|
||||
- `Bash(site)` - Site/location management
|
||||
- `Bash(task)` - Task management
|
||||
|
||||
**Note:** Fixed `m365` pattern from `"Bash(m365 \")"` to `"Bash(m365:*)"` for consistency.
|
||||
|
||||
### Scripts & Utilities (Lines 30-36)
|
||||
Miscellaneous utilities and helper scripts.
|
||||
|
||||
- `Bash(bash scripts:*)` - Execute project scripts
|
||||
- `Bash(cmd /c:*)` - Windows command processor execution
|
||||
- `Bash(findstr:*)` - Windows text search utility
|
||||
- `Bash(openssl rand:*)` - OpenSSL random generation
|
||||
- `Bash(reg query:*)` - Windows registry queries
|
||||
- `Bash(source:*)` - Source shell scripts
|
||||
- `Bash(tee:*)` - Tee command for output splitting
|
||||
|
||||
**Note:** Generalized script patterns:
|
||||
- `bash scripts:*` covers all scripts including `upgrade-to-offline-mode.sh`
|
||||
- `cmd /c:*` covers batch files like `check_old_database.bat`
|
||||
- `reg query:*` covers all registry queries including PuTTY sessions
|
||||
|
||||
---
|
||||
|
||||
## Optimization Summary
|
||||
|
||||
**Improvements Made:**
|
||||
1. Reduced permissions from 49 to 33 (33% reduction)
|
||||
2. Removed duplicate Python/pip paths with different formats
|
||||
3. Consolidated overly specific commands into wildcard patterns
|
||||
4. Alphabetically sorted within each category
|
||||
5. Standardized path format (forward slashes preferred)
|
||||
6. Fixed semantic issues (m365 pattern)
|
||||
|
||||
**Duplicates Removed:**
|
||||
- 4 duplicate Python executable paths (different path formats)
|
||||
- 2 duplicate pip installation patterns
|
||||
- 8 specific test command patterns (consolidated into pytest wildcard)
|
||||
- 2 specific alembic revision commands (consolidated into wildcard)
|
||||
- 2 duplicate WMIC process queries
|
||||
- 1 specific bash script (covered by general pattern)
|
||||
- 1 specific batch file (covered by cmd /c pattern)
|
||||
|
||||
**Patterns Generalized:**
|
||||
- All pytest commands: `*-m pytest:*` covers all test files
|
||||
- All alembic commands: `alembic.exe:*` covers all operations
|
||||
- All bash scripts: `bash scripts:*` covers all project scripts
|
||||
- All registry queries: `reg query:*` covers all HKEY paths
|
||||
|
||||
---
|
||||
|
||||
## Maintenance Tips
|
||||
|
||||
**Adding New Permissions:**
|
||||
1. Check if existing wildcard patterns already cover the command
|
||||
2. Place new permission in appropriate category
|
||||
3. Keep alphabetical order within category
|
||||
4. Prefer wildcards over specific commands
|
||||
5. Use forward slashes for paths (Windows accepts both)
|
||||
|
||||
**Pattern Syntax:**
|
||||
- `:*` = wildcard for any arguments
|
||||
- Use exact match when security requires specificity
|
||||
- Avoid overly broad patterns that could be security risks
|
||||
|
||||
**Security Considerations:**
|
||||
- Keep database connection test specific (line 10) - don't generalize
|
||||
- Review wildcard patterns periodically
|
||||
- Remove unused permissions
|
||||
- Test after changes to ensure functionality
|
||||
|
||||
---
|
||||
|
||||
## Related Files
|
||||
|
||||
- **Settings File:** `.claude/settings.local.json`
|
||||
- **Project Docs:** `.claude/CLAUDE.md`
|
||||
- **Coding Guidelines:** `.claude/CODING_GUIDELINES.md`
|
||||
356
.claude/agents/CODE_REVIEW_ST_ENHANCEMENT.md
Normal file
356
.claude/agents/CODE_REVIEW_ST_ENHANCEMENT.md
Normal file
@@ -0,0 +1,356 @@
|
||||
# Code Review Agent - Sequential Thinking Enhancement
|
||||
|
||||
**Enhancement Date:** 2026-01-17
|
||||
**Status:** COMPLETED
|
||||
|
||||
---
|
||||
|
||||
## Summary
|
||||
|
||||
Enhanced the Code Review Agent to use Sequential Thinking MCP for complex review challenges and repeated rejections. This improves review quality, breaks rejection cycles, and provides better educational feedback to the Coding Agent.
|
||||
|
||||
---
|
||||
|
||||
## What Changed
|
||||
|
||||
### 1. New Section: "When to Use Sequential Thinking MCP"
|
||||
|
||||
**Location:** `.claude/agents/code-review.md` (after "Decision Matrix")
|
||||
|
||||
**Added:**
|
||||
- Trigger conditions for invoking Sequential Thinking
|
||||
- Step-by-step workflow for ST-based reviews
|
||||
- Complete example of ST analysis in action
|
||||
- Benefits and anti-patterns
|
||||
|
||||
### 2. Trigger Conditions
|
||||
|
||||
**Sequential Thinking is triggered when ANY of these occur:**
|
||||
|
||||
#### Tough Challenges (Complexity Detection)
|
||||
- 3+ critical security/performance/logic issues
|
||||
- Multiple interrelated issues affecting each other
|
||||
- Architectural problems with unclear solutions
|
||||
- Complex trade-off decisions
|
||||
- Unclear root causes
|
||||
|
||||
#### Repeated Rejections (Pattern Detection)
|
||||
- Code rejected 2+ times
|
||||
- Same types of issues recurring
|
||||
- Coding Agent stuck in a pattern
|
||||
- Incremental fixes not addressing root problems
|
||||
|
||||
### 3. Enhanced Escalation Format
|
||||
|
||||
**New Format:** "Enhanced Escalation (After Sequential Thinking)"
|
||||
|
||||
**Includes:**
|
||||
- Root cause analysis
|
||||
- Why previous attempts failed
|
||||
- Comprehensive solution strategy
|
||||
- Alternative approaches considered
|
||||
- Pattern recognition & prevention
|
||||
- Educational context
|
||||
|
||||
**Old Format:** Still used for simple first rejections
|
||||
|
||||
### 4. Quick Decision Tree
|
||||
|
||||
Added simple flowchart at end of document:
|
||||
1. Count rejections → 2+ = ST
|
||||
2. Assess complexity → 3+ critical = ST
|
||||
3. Standard review → minor = fix, major = escalate
|
||||
4. ST used → enhanced format
|
||||
|
||||
### 5. Summary Section
|
||||
|
||||
Added prominent section at top of document highlighting the new ST capability.
|
||||
|
||||
---
|
||||
|
||||
## Files Modified
|
||||
|
||||
1. **`.claude/agents/code-review.md`**
|
||||
- Added Sequential Thinking section (150+ lines)
|
||||
- Enhanced escalation format (90+ lines)
|
||||
- Quick decision tree (20 lines)
|
||||
- Updated success criteria (10 lines)
|
||||
- Summary section (15 lines)
|
||||
|
||||
2. **`.claude/agents/CODE_REVIEW_ST_TESTING.md`** (NEW)
|
||||
- Test scenarios demonstrating ST usage
|
||||
- Expected behaviors for different scenarios
|
||||
- Testing checklist
|
||||
- Success metrics
|
||||
|
||||
3. **`.claude/agents/CODE_REVIEW_ST_ENHANCEMENT.md`** (NEW - this file)
|
||||
- Summary of changes
|
||||
- Usage guide
|
||||
- Benefits
|
||||
|
||||
---
|
||||
|
||||
## How It Works
|
||||
|
||||
### Standard Flow (No ST)
|
||||
|
||||
```
|
||||
Code Submitted → Review → Simple Issues → Fix Directly → Approve
|
||||
↓
|
||||
Major Issues → Standard Escalation
|
||||
```
|
||||
|
||||
### Enhanced Flow (With ST)
|
||||
|
||||
```
|
||||
Code Submitted → Review → 2+ Rejections OR 3+ Critical Issues
|
||||
↓
|
||||
Sequential Thinking Analysis
|
||||
↓
|
||||
Root Cause Identification
|
||||
↓
|
||||
Trade-off Evaluation
|
||||
↓
|
||||
Enhanced Escalation Format
|
||||
↓
|
||||
Comprehensive Solution + Education
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Example Trigger Scenarios
|
||||
|
||||
### Scenario 1: Repeated Rejection (TRIGGERS ST)
|
||||
|
||||
```
|
||||
Rejection 1: SQL injection
|
||||
Rejection 2: Weak password hashing
|
||||
→ TRIGGER: Pattern indicates authentication not treated as security-critical
|
||||
→ ST Analysis: Root cause is mental model problem
|
||||
→ Enhanced Feedback: Complete auth pattern with threat model
|
||||
```
|
||||
|
||||
### Scenario 2: Multiple Critical Issues (TRIGGERS ST)
|
||||
|
||||
```
|
||||
Code has:
|
||||
- SQL injection
|
||||
- N+1 query problem (2 levels deep)
|
||||
- Missing indexes
|
||||
- Inefficient Python filtering
|
||||
|
||||
→ TRIGGER: 4 critical issues, multiple interrelated
|
||||
→ ST Analysis: Misunderstanding of database query optimization
|
||||
→ Enhanced Feedback: JOIN queries, performance analysis, complete rewrite
|
||||
```
|
||||
|
||||
### Scenario 3: Architectural Trade-offs (TRIGGERS ST)
|
||||
|
||||
```
|
||||
Code needs refactoring but multiple approaches possible:
|
||||
- Microservices vs Monolith
|
||||
- REST vs GraphQL
|
||||
- Sync vs Async
|
||||
|
||||
→ TRIGGER: Unclear which approach fits requirements
|
||||
→ ST Analysis: Evaluate trade-offs systematically
|
||||
→ Enhanced Feedback: Comparison matrix, recommended approach with rationale
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Benefits
|
||||
|
||||
### 1. Breaks Rejection Cycles
|
||||
- Root cause analysis instead of symptom fixing
|
||||
- Comprehensive feedback addresses all related issues
|
||||
- Educational context shifts mental models
|
||||
|
||||
### 2. Better Code Quality
|
||||
- Identifies architectural issues, not just syntax
|
||||
- Evaluates trade-offs systematically
|
||||
- Provides industry-standard patterns
|
||||
|
||||
### 3. Improved Learning
|
||||
- Explains WHY, not just WHAT
|
||||
- Threat models for security issues
|
||||
- Performance analysis for optimization issues
|
||||
- Complete examples with best practices
|
||||
|
||||
### 4. Token Efficiency
|
||||
- Fewer rejection cycles = less total tokens
|
||||
- ST tokens invested upfront save many rounds of back-and-forth
|
||||
- Comprehensive feedback reduces clarification questions
|
||||
|
||||
### 5. Documentation
|
||||
- ST thought process is preserved
|
||||
- Future reviews can reference patterns
|
||||
- Builds institutional knowledge
|
||||
|
||||
---
|
||||
|
||||
## Usage Guide for Code Reviewer
|
||||
|
||||
### Step 1: Receive Code for Review
|
||||
|
||||
Track mentally: "Is this the 2nd+ rejection?"
|
||||
|
||||
### Step 2: Assess Complexity
|
||||
|
||||
Count critical issues. Are there 3+? Are they interrelated?
|
||||
|
||||
### Step 3: Decision Point
|
||||
|
||||
**IF:** 2+ rejections OR 3+ critical issues OR complex trade-offs
|
||||
**THEN:** Use Sequential Thinking MCP
|
||||
|
||||
**ELSE:** Standard review process
|
||||
|
||||
### Step 4: Use Sequential Thinking (If Triggered)
|
||||
|
||||
```
|
||||
Use mcp__sequential-thinking__sequentialthinking tool
|
||||
|
||||
Thought 1-4: Problem Analysis
|
||||
- What are ALL the issues?
|
||||
- How do they relate?
|
||||
- What's root cause vs symptoms?
|
||||
- Why did Coding Agent make these choices?
|
||||
|
||||
Thought 5-8: Solution Strategy
|
||||
- What are possible approaches?
|
||||
- What are trade-offs?
|
||||
- Which approach fits best?
|
||||
- What are implementation steps?
|
||||
|
||||
Thought 9-12: Prevention Analysis
|
||||
- Why did this happen?
|
||||
- What guidance prevents recurrence?
|
||||
- Are specs ambiguous?
|
||||
- Should guidelines be updated?
|
||||
|
||||
Thought 13-15: Comprehensive Feedback
|
||||
- How to explain clearly?
|
||||
- What examples to provide?
|
||||
- What's acceptance criteria?
|
||||
```
|
||||
|
||||
### Step 5: Use Enhanced Escalation Format
|
||||
|
||||
Include ST insights in structured format:
|
||||
- Root cause analysis
|
||||
- Comprehensive solution strategy
|
||||
- Educational context
|
||||
- Pattern recognition
|
||||
|
||||
### Step 6: Document Insights
|
||||
|
||||
ST analysis is preserved for:
|
||||
- Future similar issues
|
||||
- Pattern recognition
|
||||
- Guideline updates
|
||||
- Learning resources
|
||||
|
||||
---
|
||||
|
||||
## Testing
|
||||
|
||||
See: `.claude/agents/CODE_REVIEW_ST_TESTING.md` for:
|
||||
- Test scenarios
|
||||
- Expected behaviors
|
||||
- Testing checklist
|
||||
- Success metrics
|
||||
|
||||
---
|
||||
|
||||
## Configuration
|
||||
|
||||
**No configuration needed.** The Code Review Agent now has these guidelines built-in.
|
||||
|
||||
**Required MCP:** Sequential Thinking MCP must be configured in `.mcp.json`
|
||||
|
||||
**Verify MCP Available:**
|
||||
```bash
|
||||
# Check MCP servers
|
||||
cat .mcp.json | grep sequential-thinking
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Success Metrics
|
||||
|
||||
Track these to validate enhancement effectiveness:
|
||||
|
||||
1. **Rejection Cycle Reduction**
|
||||
- Before: Average 3-4 rejections for complex issues
|
||||
- After: Target 1-2 rejections (ST on 2nd breaks cycle)
|
||||
|
||||
2. **Review Quality**
|
||||
- Root causes identified vs symptoms
|
||||
- Comprehensive solutions vs incremental fixes
|
||||
- Educational feedback vs directive commands
|
||||
|
||||
3. **Token Efficiency**
|
||||
- ST tokens invested upfront
|
||||
- Fewer total review cycles
|
||||
- Overall token reduction expected
|
||||
|
||||
4. **Code Quality**
|
||||
- Fewer security vulnerabilities
|
||||
- Better architectural decisions
|
||||
- More maintainable solutions
|
||||
|
||||
---
|
||||
|
||||
## Future Enhancements
|
||||
|
||||
Potential improvements:
|
||||
|
||||
1. **Track Rejection Patterns**
|
||||
- Log common rejection reasons
|
||||
- Build pattern library
|
||||
- Proactive guidance
|
||||
|
||||
2. **ST Insights Database**
|
||||
- Store ST analysis results
|
||||
- Reference in future reviews
|
||||
- Build knowledge base
|
||||
|
||||
3. **Automated Complexity Detection**
|
||||
- Static analysis integration
|
||||
- Complexity scoring
|
||||
- Auto-trigger ST threshold
|
||||
|
||||
4. **Feedback Loop**
|
||||
- Track which ST analyses were most helpful
|
||||
- Refine trigger conditions
|
||||
- Optimize feedback format
|
||||
|
||||
---
|
||||
|
||||
## Related Files
|
||||
|
||||
- **Agent Config:** `.claude/agents/code-review.md`
|
||||
- **Testing Guide:** `.claude/agents/CODE_REVIEW_ST_TESTING.md`
|
||||
- **MCP Config:** `.mcp.json`
|
||||
- **Coding Guidelines:** `.claude/CODING_GUIDELINES.md`
|
||||
- **Workflow Docs:** `.claude/CODE_WORKFLOW.md`
|
||||
|
||||
---
|
||||
|
||||
## Rollback
|
||||
|
||||
If needed, revert to previous version:
|
||||
|
||||
```bash
|
||||
git diff HEAD~1 .claude/agents/code-review.md
|
||||
git checkout HEAD~1 .claude/agents/code-review.md
|
||||
```
|
||||
|
||||
**Note:** Keep testing guide and enhancement doc for future reference.
|
||||
|
||||
---
|
||||
|
||||
**Last Updated:** 2026-01-17
|
||||
**Status:** COMPLETED & READY FOR USE
|
||||
**Enhanced By:** Claude Code
|
||||
389
.claude/agents/CODE_REVIEW_ST_TESTING.md
Normal file
389
.claude/agents/CODE_REVIEW_ST_TESTING.md
Normal file
@@ -0,0 +1,389 @@
|
||||
# Code Review Agent - Sequential Thinking Testing
|
||||
|
||||
This document demonstrates the enhanced Code Review Agent with Sequential Thinking MCP integration.
|
||||
|
||||
**Last Updated:** 2026-01-17
|
||||
|
||||
---
|
||||
|
||||
## Test Scenarios
|
||||
|
||||
### Scenario 1: Simple Issue (No ST Required)
|
||||
|
||||
**Code Submitted:**
|
||||
```python
|
||||
def calculate_tax(amount):
|
||||
return amount * 0.08
|
||||
```
|
||||
|
||||
**Issues:**
|
||||
- Missing type hints
|
||||
- No docstring
|
||||
- Magic number (0.08)
|
||||
|
||||
**Expected Behavior:** Code reviewer fixes directly, approves
|
||||
**ST Triggered:** NO (simple, first review)
|
||||
|
||||
**Review Result:**
|
||||
```python
|
||||
def calculate_tax(amount: Decimal) -> Decimal:
|
||||
"""Calculate sales tax on given amount.
|
||||
|
||||
Args:
|
||||
amount: Pre-tax amount
|
||||
|
||||
Returns:
|
||||
Tax amount (8% rate)
|
||||
"""
|
||||
TAX_RATE = Decimal("0.08")
|
||||
return amount * TAX_RATE
|
||||
```
|
||||
|
||||
**Status:** APPROVED (after minor fixes)
|
||||
|
||||
---
|
||||
|
||||
### Scenario 2: First Rejection (Standard Escalation)
|
||||
|
||||
**Code Submitted:**
|
||||
```python
|
||||
def login(username, password):
|
||||
user = db.query(f"SELECT * FROM users WHERE name='{username}'")
|
||||
if user and user.password == password:
|
||||
return True
|
||||
return False
|
||||
```
|
||||
|
||||
**Issues:**
|
||||
- SQL injection vulnerability
|
||||
- Plaintext password comparison
|
||||
|
||||
**Expected Behavior:** Standard escalation format
|
||||
**ST Triggered:** NO (only 1 critical issue per category, first review)
|
||||
|
||||
**Review Result:**
|
||||
```markdown
|
||||
## Code Review - Requires Revision
|
||||
|
||||
**Specification Compliance:** FAIL
|
||||
**Security:** CRITICAL ISSUES
|
||||
|
||||
### CRITICAL: SQL Injection
|
||||
- **Location:** login function, line 2
|
||||
- **Problem:** String interpolation in SQL query
|
||||
- **Impact:** Database compromise possible
|
||||
- **Required Fix:** Use parameterized queries
|
||||
|
||||
### CRITICAL: Plaintext Password
|
||||
- **Location:** login function, line 3
|
||||
- **Problem:** Direct password comparison
|
||||
- **Impact:** Passwords should be hashed (bcrypt)
|
||||
- **Required Fix:** Hash passwords, use secure comparison
|
||||
|
||||
**Checklist:**
|
||||
- [ ] Parameterized SQL queries
|
||||
- [ ] Bcrypt password hashing
|
||||
```
|
||||
|
||||
**Status:** ESCALATED (standard format)
|
||||
|
||||
---
|
||||
|
||||
### Scenario 3: Second Rejection (ST TRIGGERED)
|
||||
|
||||
**Code Resubmitted After Fix:**
|
||||
```python
|
||||
def login(username, password):
|
||||
user = db.query("SELECT * FROM users WHERE name=?", username)
|
||||
if user and bcrypt.checkpw(password, user.password):
|
||||
session['user'] = username
|
||||
return True
|
||||
return False
|
||||
```
|
||||
|
||||
**Issues:**
|
||||
- Session management insecure (no token, no expiry)
|
||||
- No rate limiting (brute force possible)
|
||||
- Username might not exist (error handling)
|
||||
|
||||
**Expected Behavior:** ST TRIGGERED (2nd rejection)
|
||||
**ST Analysis:**
|
||||
|
||||
```
|
||||
Thought 1: This is the second rejection. First was SQL injection + plaintext
|
||||
passwords. Now session management issues. Pattern: treating authentication
|
||||
as simple data retrieval rather than security-critical component.
|
||||
|
||||
Thought 2: Root cause is mental model problem. Coding Agent fixing surface
|
||||
issues but missing the security-first mindset required for authentication.
|
||||
|
||||
Thought 3: Need comprehensive authentication pattern, not incremental fixes.
|
||||
|
||||
Thought 4: Should provide complete example with security threat model
|
||||
explanation to shift mental model.
|
||||
|
||||
Thought 5: Include: parameterized queries (done), bcrypt (done), session
|
||||
tokens (missing), rate limiting (missing), input validation (missing),
|
||||
timing-safe comparison (missing).
|
||||
|
||||
Thought 6: Enhanced escalation format with educational context needed.
|
||||
```
|
||||
|
||||
**Review Result:**
|
||||
```markdown
|
||||
## Code Review - Requires Revision (Complex Issues Analyzed)
|
||||
|
||||
**Review Iteration:** 2 (USING SEQUENTIAL THINKING ANALYSIS)
|
||||
**Reason:** 2nd rejection - pattern indicates mental model mismatch
|
||||
|
||||
## Root Cause Analysis
|
||||
|
||||
**Surface Issues:**
|
||||
- Insecure session management
|
||||
- No brute force protection
|
||||
- Missing input validation
|
||||
|
||||
**Root Cause:**
|
||||
Authentication is being treated as a CRUD operation (create/read user)
|
||||
rather than a security-critical component with an active threat model.
|
||||
|
||||
**Why Previous Attempts Failed:**
|
||||
Incremental security fixes without understanding the holistic security
|
||||
requirements for authentication systems.
|
||||
|
||||
## Comprehensive Solution Strategy
|
||||
|
||||
**Recommended Approach:**
|
||||
Implement complete authentication system with defense-in-depth:
|
||||
- JWT tokens (not simple sessions)
|
||||
- Rate limiting (prevent brute force)
|
||||
- Input validation (prevent injection beyond SQL)
|
||||
- Timing-safe comparison (prevent timing attacks)
|
||||
- Audit logging (security monitoring)
|
||||
|
||||
**Why This Approach:**
|
||||
- Addresses all OWASP authentication risks
|
||||
- Provides defense-in-depth
|
||||
- Industry standard pattern
|
||||
|
||||
**Complete Example:**
|
||||
```python
|
||||
from datetime import datetime, timedelta
|
||||
import jwt
|
||||
import bcrypt
|
||||
from functools import wraps
|
||||
from typing import Optional
|
||||
|
||||
# Rate limiting decorator
|
||||
def rate_limit(max_attempts=5, window_minutes=15):
|
||||
attempts = {}
|
||||
def decorator(func):
|
||||
@wraps(func)
|
||||
def wrapper(username, *args, **kwargs):
|
||||
now = datetime.now()
|
||||
if username in attempts:
|
||||
count, first = attempts[username]
|
||||
if (now - first) < timedelta(minutes=window_minutes):
|
||||
if count >= max_attempts:
|
||||
raise Exception("Rate limit exceeded")
|
||||
attempts[username] = (count + 1, first)
|
||||
else:
|
||||
attempts[username] = (1, now)
|
||||
else:
|
||||
attempts[username] = (1, now)
|
||||
return func(username, *args, **kwargs)
|
||||
return wrapper
|
||||
return decorator
|
||||
|
||||
@rate_limit(max_attempts=5, window_minutes=15)
|
||||
def login(username: str, password: str) -> Optional[str]:
|
||||
"""Authenticate user and return JWT token.
|
||||
|
||||
Security measures:
|
||||
- Parameterized queries (SQL injection prevention)
|
||||
- Bcrypt password hashing (credential theft protection)
|
||||
- Rate limiting (brute force prevention)
|
||||
- Input validation (injection prevention)
|
||||
- JWT tokens (secure session management)
|
||||
- Timing-safe comparison (timing attack prevention)
|
||||
|
||||
Args:
|
||||
username: User's username (validated)
|
||||
password: User's plaintext password
|
||||
|
||||
Returns:
|
||||
JWT token string if authenticated, None otherwise
|
||||
|
||||
Raises:
|
||||
ValueError: If inputs are invalid
|
||||
Exception: If rate limit exceeded
|
||||
"""
|
||||
# Input validation
|
||||
if not username or not isinstance(username, str):
|
||||
raise ValueError("Invalid username")
|
||||
if len(username) > 50:
|
||||
raise ValueError("Username too long")
|
||||
if not password or len(password) < 8:
|
||||
raise ValueError("Invalid password")
|
||||
|
||||
# Parameterized query (SQL injection prevention)
|
||||
user = db.query(
|
||||
"SELECT id, username, password_hash FROM users WHERE username = ?",
|
||||
params=(username,)
|
||||
)
|
||||
|
||||
# Timing-safe comparison to prevent timing attacks
|
||||
if not user:
|
||||
# Run bcrypt anyway to prevent timing leak
|
||||
bcrypt.checkpw(b"dummy", bcrypt.hashpw(b"dummy", bcrypt.gensalt()))
|
||||
return None
|
||||
|
||||
# Bcrypt comparison (secure password verification)
|
||||
if not bcrypt.checkpw(password.encode(), user.password_hash):
|
||||
return None
|
||||
|
||||
# Generate JWT token (secure session management)
|
||||
token = jwt.encode({
|
||||
'user_id': user.id,
|
||||
'username': user.username,
|
||||
'exp': datetime.utcnow() + timedelta(hours=24),
|
||||
'iat': datetime.utcnow()
|
||||
}, SECRET_KEY, algorithm='HS256')
|
||||
|
||||
# Audit logging (security monitoring)
|
||||
audit_log.info(f"User {username} logged in", extra={
|
||||
'user_id': user.id,
|
||||
'ip': request.remote_addr,
|
||||
'timestamp': datetime.utcnow()
|
||||
})
|
||||
|
||||
return token
|
||||
```
|
||||
|
||||
## Educational Context
|
||||
|
||||
**Key Concept: Defense in Depth**
|
||||
Authentication is an attack surface. Every decision has security implications.
|
||||
Multiple layers of defense ensure that if one fails, others protect the system.
|
||||
|
||||
**Security Threat Model for Authentication:**
|
||||
1. SQL Injection → Parameterized queries
|
||||
2. Credential theft → Password hashing
|
||||
3. Brute force → Rate limiting
|
||||
4. Session hijacking → JWT with expiry
|
||||
5. Timing attacks → Constant-time comparison
|
||||
6. Injection attacks → Input validation
|
||||
7. Forensics → Audit logging
|
||||
|
||||
**Why It Matters:**
|
||||
Authentication failures lead to complete system compromise. A single
|
||||
vulnerability can bypass all other security measures.
|
||||
|
||||
**Reference Patterns:**
|
||||
- OWASP Authentication Cheatsheet
|
||||
- JWT Best Practices
|
||||
- Bcrypt/Argon2 for password hashing
|
||||
```
|
||||
|
||||
**Status:** ESCALATED (enhanced format with ST analysis)
|
||||
|
||||
---
|
||||
|
||||
### Scenario 4: Complex Multiple Issues (ST TRIGGERED)
|
||||
|
||||
**Code Submitted:**
|
||||
```python
|
||||
def process_orders(user_id):
|
||||
orders = []
|
||||
user = db.query(f"SELECT * FROM users WHERE id={user_id}")
|
||||
for order in db.query("SELECT * FROM orders"):
|
||||
if order.user_id == user_id:
|
||||
items = []
|
||||
for item in db.query("SELECT * FROM items"):
|
||||
if item.order_id == order.id:
|
||||
items.append(item)
|
||||
orders.append({'order': order, 'items': items})
|
||||
return orders
|
||||
```
|
||||
|
||||
**Issues:**
|
||||
- SQL injection (user_id)
|
||||
- N+1 query problem (orders loop)
|
||||
- N+1 query problem (items loop)
|
||||
- Missing indexes implied
|
||||
- Inefficient filtering in Python
|
||||
- No error handling
|
||||
- No type hints
|
||||
|
||||
**Expected Behavior:** ST TRIGGERED (3+ critical issues, interrelated)
|
||||
**ST Analysis:**
|
||||
|
||||
```
|
||||
Thought 1: Multiple issues: SQL injection + N+1 queries (2 levels) +
|
||||
inefficient filtering. These are interrelated - fixing one affects others.
|
||||
|
||||
Thought 2: Root cause: fundamental misunderstanding of database query
|
||||
optimization. Treating database like in-memory collection.
|
||||
|
||||
Thought 3: Can't fix incrementally. Need to teach JOIN queries and
|
||||
query optimization principles.
|
||||
|
||||
Thought 4: If I just say "use JOIN", they might not understand why or
|
||||
how to structure it properly.
|
||||
|
||||
Thought 5: Need to show the performance impact (N+1 = 1000 orders * 100 items
|
||||
= 100,000 queries vs 1 JOIN query), explain query planning, and provide
|
||||
complete rewrite.
|
||||
|
||||
Thought 6: Also opportunity to teach about ORM vs raw SQL trade-offs.
|
||||
```
|
||||
|
||||
**Review Result:** [Enhanced escalation format with performance analysis,
|
||||
query optimization education, and complete JOIN example]
|
||||
|
||||
**Status:** ESCALATED (enhanced format with ST analysis)
|
||||
|
||||
---
|
||||
|
||||
## Testing Checklist
|
||||
|
||||
When testing the enhanced code reviewer:
|
||||
|
||||
- [ ] Test simple issues (no ST, direct fix)
|
||||
- [ ] Test first rejection (standard escalation)
|
||||
- [ ] Test second rejection (ST triggered, enhanced format)
|
||||
- [ ] Test 3+ critical issues (ST triggered, complexity)
|
||||
- [ ] Test architectural issues (ST for trade-off analysis)
|
||||
- [ ] Verify enhanced format includes root cause analysis
|
||||
- [ ] Verify comprehensive examples in feedback
|
||||
- [ ] Verify educational context in complex cases
|
||||
|
||||
---
|
||||
|
||||
## Expected Behavior Summary
|
||||
|
||||
| Scenario | Rejection Count | Issue Complexity | ST Triggered? | Format Used |
|
||||
|----------|----------------|------------------|---------------|-------------|
|
||||
| Simple formatting | 0 | Low | NO | Direct fix |
|
||||
| First security issue | 0 | Medium | NO | Standard escalation |
|
||||
| Second rejection | 2 | Medium | YES | Enhanced escalation |
|
||||
| 3+ critical issues | 0-1 | High | YES | Enhanced escalation |
|
||||
| Architectural trade-offs | 0-1 | High | YES | Enhanced escalation |
|
||||
| Complex interrelated | 0-1 | Very High | YES | Enhanced escalation |
|
||||
|
||||
---
|
||||
|
||||
## Success Metrics
|
||||
|
||||
Enhanced code reviewer should:
|
||||
|
||||
1. **Reduce rejection cycles** - ST analysis breaks patterns faster
|
||||
2. **Provide better education** - Comprehensive examples teach patterns
|
||||
3. **Identify root causes** - Not just symptoms
|
||||
4. **Make better architectural decisions** - Trade-off analysis with ST
|
||||
5. **Save tokens overall** - Fewer rejections = less total token usage
|
||||
|
||||
---
|
||||
|
||||
**Last Updated:** 2026-01-17
|
||||
**Status:** Ready for Testing
|
||||
@@ -41,6 +41,26 @@ NO code reaches the user or production without your approval.
|
||||
|
||||
---
|
||||
|
||||
## NEW: Sequential Thinking for Complex Reviews
|
||||
|
||||
**Enhanced Capability:** You now have access to Sequential Thinking MCP for systematically analyzing tough challenges.
|
||||
|
||||
**When to Use:**
|
||||
- Code rejected 2+ times (break the rejection cycle)
|
||||
- 3+ critical security/performance/logic issues
|
||||
- Complex architectural problems with unclear solutions
|
||||
- Multiple interrelated issues affecting each other
|
||||
|
||||
**Benefits:**
|
||||
- Root cause analysis vs symptom fixing
|
||||
- Trade-off evaluation for architectural decisions
|
||||
- Comprehensive feedback that breaks rejection patterns
|
||||
- Educational guidance for Coding Agent
|
||||
|
||||
**See:** "When to Use Sequential Thinking MCP" section below for complete guidelines.
|
||||
|
||||
---
|
||||
|
||||
## Identity
|
||||
You are the Code Review Agent - a meticulous senior engineer who ensures all code meets specifications, follows best practices, and is production-ready. You have the authority to make minor corrections but escalate significant issues back to the Coding Agent.
|
||||
|
||||
@@ -260,10 +280,181 @@ def get_user(user_id: int) -> Optional[User]:
|
||||
)
|
||||
```
|
||||
|
||||
## When to Use Sequential Thinking MCP
|
||||
|
||||
**CRITICAL: For complex issues or repeated rejections, use the Sequential Thinking MCP to analyze problems systematically.**
|
||||
|
||||
### Trigger Conditions
|
||||
|
||||
Use Sequential Thinking when ANY of these conditions are met:
|
||||
|
||||
#### 1. Tough Challenges (Complexity Detection)
|
||||
Invoke Sequential Thinking when you encounter:
|
||||
|
||||
**Multiple Critical Issues:**
|
||||
- 3+ critical security vulnerabilities in the same code
|
||||
- Multiple interrelated issues that affect each other
|
||||
- Security + Performance + Logic errors combined
|
||||
- Cascading failures where fixing one issue creates another
|
||||
|
||||
**Architectural Complexity:**
|
||||
- Wrong design pattern but unclear what the right one is
|
||||
- Multiple valid approaches with unclear trade-offs
|
||||
- Complex refactoring needed affecting > 20 lines
|
||||
- Architectural decision requires weighing pros/cons
|
||||
- System design issues (coupling, cohesion, separation of concerns)
|
||||
|
||||
**Unclear Root Cause:**
|
||||
- Bug symptoms present but root cause uncertain
|
||||
- Performance issue but bottleneck location unclear
|
||||
- Race condition suspected but hard to pinpoint
|
||||
- Memory leak but source not obvious
|
||||
- Multiple possible explanations for the same problem
|
||||
|
||||
**Complex Trade-offs:**
|
||||
- Security vs Performance decisions
|
||||
- Simplicity vs Extensibility choices
|
||||
- Short-term fix vs Long-term solution
|
||||
- Multiple stakeholder concerns to balance
|
||||
- Technical debt considerations
|
||||
|
||||
**Example Tough Challenge:**
|
||||
```python
|
||||
# Code has SQL injection, N+1 queries, missing indexes,
|
||||
# race conditions, and violates SOLID principles
|
||||
# Multiple issues are interrelated - fixing one affects others
|
||||
# TRIGGER: Use Sequential Thinking to analyze systematically
|
||||
```
|
||||
|
||||
#### 2. Repeated Rejections (Quality Pattern Detection)
|
||||
|
||||
**Rejection Tracking:** Keep mental note of how many times code has been sent back to Coding Agent in the current review cycle.
|
||||
|
||||
**Trigger on 2+ Rejections:**
|
||||
- Code has been rejected and resubmitted 2 or more times
|
||||
- Same types of issues keep appearing
|
||||
- Coding Agent seems stuck in a pattern
|
||||
- Incremental fixes aren't addressing root problems
|
||||
|
||||
**What This Indicates:**
|
||||
- Coding Agent may not understand the core issue
|
||||
- Requirements might be ambiguous
|
||||
- Specification might be incomplete
|
||||
- Approach needs fundamental rethinking
|
||||
- Pattern of misunderstanding needs to be broken
|
||||
|
||||
**Example Repeated Rejection:**
|
||||
```
|
||||
Rejection 1: SQL injection fixed with escaping (wrong approach)
|
||||
Rejection 2: Changed to parameterized query but wrong syntax
|
||||
TRIGGER: Use Sequential Thinking to analyze why the pattern persists
|
||||
and develop a comprehensive solution strategy
|
||||
```
|
||||
|
||||
### How to Use Sequential Thinking for Code Review
|
||||
|
||||
When triggered, use the MCP tool to:
|
||||
|
||||
**Step 1: Problem Analysis**
|
||||
```
|
||||
Thought 1: What are ALL the issues in this code?
|
||||
Thought 2: How do these issues relate to each other?
|
||||
Thought 3: What's the root cause vs symptoms?
|
||||
Thought 4: Why did the Coding Agent make these choices?
|
||||
```
|
||||
|
||||
**Step 2: Solution Strategy**
|
||||
```
|
||||
Thought 5: What are the possible approaches to fix this?
|
||||
Thought 6: What are the trade-offs of each approach?
|
||||
Thought 7: Which approach best fits the requirements?
|
||||
Thought 8: What are the implementation steps?
|
||||
```
|
||||
|
||||
**Step 3: Prevention Analysis**
|
||||
```
|
||||
Thought 9: Why did this pass the Coding Agent initially?
|
||||
Thought 10: What guidance would prevent this in the future?
|
||||
Thought 11: Are there spec ambiguities to clarify?
|
||||
Thought 12: Should we update coding guidelines?
|
||||
```
|
||||
|
||||
**Step 4: Comprehensive Feedback**
|
||||
```
|
||||
Thought 13: How do I explain this clearly to Coding Agent?
|
||||
Thought 14: What examples or patterns should I provide?
|
||||
Thought 15: What's the acceptance criteria for resubmission?
|
||||
```
|
||||
|
||||
### Example: Sequential Thinking in Action
|
||||
|
||||
**Scenario:** Third rejection of authentication code
|
||||
|
||||
```markdown
|
||||
USING SEQUENTIAL THINKING MCP:
|
||||
|
||||
Thought 1: Code has been rejected 3 times. First for SQL injection,
|
||||
second for weak password hashing, third for missing rate limiting.
|
||||
All are security issues but seem disconnected.
|
||||
|
||||
Thought 2: Wait - these aren't disconnected. They all stem from the
|
||||
Coding Agent treating authentication as a simple CRUD operation rather
|
||||
than a security-critical component.
|
||||
|
||||
Thought 3: The root issue is a mental model problem. The agent is
|
||||
thinking "store and retrieve user" not "secure authentication system."
|
||||
|
||||
Thought 4: I need to reframe the entire requirement. Instead of
|
||||
listing fixes, I should provide a comprehensive authentication pattern
|
||||
that addresses all security concerns holistically.
|
||||
|
||||
Thought 5: Best approach: Provide a complete, secure authentication
|
||||
example with explanations of WHY each security measure matters. Show
|
||||
the threat model, not just the code fixes.
|
||||
|
||||
Thought 6: Include: parameterized queries (SQL injection), bcrypt
|
||||
hashing (credential theft), rate limiting (brute force), session
|
||||
management (hijacking), input validation (injection), timing-safe
|
||||
comparison (timing attacks).
|
||||
|
||||
Thought 7: Also need to explain the security mindset: authentication
|
||||
is an attack surface, every decision has security implications,
|
||||
defense in depth is required.
|
||||
|
||||
Thought 8: This requires complete rewrite with security-first design.
|
||||
Send comprehensive guidance, not just a list of fixes.
|
||||
```
|
||||
|
||||
**Result:** Comprehensive feedback that breaks the rejection cycle by addressing the root mental model issue rather than surface symptoms.
|
||||
|
||||
### Benefits of Sequential Thinking for Reviews
|
||||
|
||||
1. **Breaks Rejection Cycles:** Identifies why repeated attempts fail
|
||||
2. **Holistic Solutions:** Addresses root causes, not just symptoms
|
||||
3. **Better Feedback:** Provides comprehensive, educational guidance
|
||||
4. **Pattern Recognition:** Identifies recurring issues for future prevention
|
||||
5. **Trade-off Analysis:** Makes better architectural decisions
|
||||
6. **Documentation:** Thought process is documented for learning
|
||||
|
||||
### When NOT to Use Sequential Thinking
|
||||
|
||||
Don't waste tokens on Sequential Thinking for:
|
||||
- Single, straightforward issue (e.g., one typo, one missing type hint)
|
||||
- First rejection with clear, simple fixes
|
||||
- Minor formatting or style issues
|
||||
- Issues with obvious solutions
|
||||
- Standard, well-documented patterns
|
||||
|
||||
**Rule of Thumb:** If you can write the fix in < 2 minutes and explain it in one sentence, skip Sequential Thinking.
|
||||
|
||||
---
|
||||
|
||||
## Escalation Format
|
||||
|
||||
When sending code back to Coding Agent:
|
||||
|
||||
### Standard Escalation (Simple Issues)
|
||||
|
||||
```markdown
|
||||
## Code Review - Requires Revision
|
||||
|
||||
@@ -293,6 +484,101 @@ When sending code back to Coding Agent:
|
||||
- [ ] [specific item to verify]
|
||||
```
|
||||
|
||||
### Enhanced Escalation (After Sequential Thinking)
|
||||
|
||||
When you've used Sequential Thinking MCP, include your analysis:
|
||||
|
||||
```markdown
|
||||
## Code Review - Requires Revision (Complex Issues Analyzed)
|
||||
|
||||
**Review Iteration:** [Number] (USING SEQUENTIAL THINKING ANALYSIS)
|
||||
**Reason for Deep Analysis:** [Multiple critical issues / 2+ rejections / Complex trade-offs]
|
||||
|
||||
---
|
||||
|
||||
## Root Cause Analysis
|
||||
|
||||
**Surface Issues:**
|
||||
- [List of symptoms observed in code]
|
||||
|
||||
**Root Cause:**
|
||||
[What Sequential Thinking revealed as the fundamental problem]
|
||||
|
||||
**Why Previous Attempts Failed:**
|
||||
[Pattern identified through Sequential Thinking - e.g., "mental model mismatch"]
|
||||
|
||||
---
|
||||
|
||||
## Issues Found:
|
||||
|
||||
### CRITICAL: [Issue Category]
|
||||
- **Location:** [file:line or function name]
|
||||
- **Problem:** [what's wrong]
|
||||
- **Root Cause:** [why this happened - from ST analysis]
|
||||
- **Impact:** [why it matters]
|
||||
- **Required Fix:** [what needs to change]
|
||||
- **Example:** [code snippet if helpful]
|
||||
|
||||
[Repeat for all critical issues]
|
||||
|
||||
---
|
||||
|
||||
## Comprehensive Solution Strategy
|
||||
|
||||
**Recommended Approach:**
|
||||
[The approach identified through Sequential Thinking trade-off analysis]
|
||||
|
||||
**Why This Approach:**
|
||||
- [Benefit 1 from ST analysis]
|
||||
- [Benefit 2 from ST analysis]
|
||||
- [Addresses root cause, not just symptoms]
|
||||
|
||||
**Alternative Approaches Considered:**
|
||||
- [Alternative 1]: [Why rejected - from ST analysis]
|
||||
- [Alternative 2]: [Why rejected - from ST analysis]
|
||||
|
||||
**Implementation Steps:**
|
||||
1. [Step identified through ST]
|
||||
2. [Step identified through ST]
|
||||
3. [Step identified through ST]
|
||||
|
||||
**Complete Example:**
|
||||
```[language]
|
||||
[Comprehensive code example showing correct pattern]
|
||||
[Include comments explaining WHY each choice matters]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Pattern Recognition & Prevention
|
||||
|
||||
**This Issue Indicates:**
|
||||
[Insight from ST about what the coding pattern reveals]
|
||||
|
||||
**To Prevent Recurrence:**
|
||||
- [Guideline 1 from ST analysis]
|
||||
- [Guideline 2 from ST analysis]
|
||||
- [Mental model shift needed]
|
||||
|
||||
**Updated Acceptance Criteria:**
|
||||
- [ ] [Enhanced criterion from ST analysis]
|
||||
- [ ] [Enhanced criterion from ST analysis]
|
||||
- [ ] [Demonstrates understanding of root issue]
|
||||
|
||||
---
|
||||
|
||||
## Educational Context
|
||||
|
||||
**Key Concept:**
|
||||
[The fundamental principle that was missed - from ST]
|
||||
|
||||
**Why It Matters:**
|
||||
[Threat model, performance implications, or architectural reasoning from ST]
|
||||
|
||||
**Reference Patterns:**
|
||||
[Links to documentation or examples of correct pattern]
|
||||
```
|
||||
|
||||
## Approval Format
|
||||
|
||||
When code passes review:
|
||||
@@ -481,6 +767,29 @@ Code is approved when:
|
||||
- ✅ Production-ready quality
|
||||
- ✅ All critical/major issues resolved
|
||||
|
||||
## Quick Decision Tree
|
||||
|
||||
**On receiving code for review:**
|
||||
|
||||
1. **Count rejections:** Is this 2+ rejection?
|
||||
- YES → Use Sequential Thinking MCP
|
||||
- NO → Continue to step 2
|
||||
|
||||
2. **Assess complexity:** Are there 3+ critical issues OR complex architectural problems OR unclear root cause?
|
||||
- YES → Use Sequential Thinking MCP
|
||||
- NO → Continue with standard review
|
||||
|
||||
3. **Standard review:** Are issues minor (formatting, type hints, docstrings)?
|
||||
- YES → Fix directly, approve
|
||||
- NO → Escalate with standard format
|
||||
|
||||
4. **If using Sequential Thinking:** Use enhanced escalation format with root cause analysis and comprehensive solution strategy
|
||||
|
||||
---
|
||||
|
||||
**Remember**: You are the quality gatekeeper. Minor cosmetic issues you fix. Major functional, security, or architectural issues get escalated with detailed, actionable feedback. Code doesn't ship until it's right.
|
||||
**Remember**:
|
||||
- You are the quality gatekeeper
|
||||
- Minor cosmetic issues: fix yourself
|
||||
- Major issues (first rejection): escalate with standard format
|
||||
- Complex/repeated issues: use Sequential Thinking + enhanced format
|
||||
- Code doesn't ship until it's right
|
||||
|
||||
@@ -13,6 +13,7 @@
|
||||
- **Context Recall System** with cross-machine persistent memory
|
||||
- **JWT Authentication** on all endpoints
|
||||
- **AES-256-GCM Encryption** for credentials
|
||||
- **3 MCP Servers** configured (GitHub, Filesystem, Sequential Thinking)
|
||||
|
||||
---
|
||||
|
||||
@@ -30,9 +31,15 @@ D:\ClaudeTools/
|
||||
│ └── utils/ # Crypto & compression utilities
|
||||
├── migrations/ # Alembic database migrations
|
||||
├── .claude/ # Claude Code hooks & config
|
||||
│ ├── commands/ # Commands (sync, create-spec, checkpoint)
|
||||
│ ├── skills/ # Skills (frontend-design)
|
||||
│ ├── templates/ # Templates (app spec, prompts)
|
||||
│ ├── hooks/ # Auto-inject/save context
|
||||
│ └── context-recall-config.env # Configuration
|
||||
└── scripts/ # Setup & test scripts
|
||||
├── mcp-servers/ # MCP server implementations
|
||||
│ └── feature-management/ # Feature tracking MCP server
|
||||
├── scripts/ # Setup & test scripts
|
||||
└── projects/ # Project workspaces
|
||||
```
|
||||
|
||||
---
|
||||
@@ -244,9 +251,11 @@ POST /api/credentials
|
||||
## Important Files
|
||||
|
||||
**Session State:** `SESSION_STATE.md` - Complete project history and status
|
||||
|
||||
**Documentation:**
|
||||
- `.claude/CONTEXT_RECALL_QUICK_START.md` - Context recall usage
|
||||
- `CONTEXT_RECALL_SETUP.md` - Full setup guide
|
||||
- `AUTOCODER_INTEGRATION.md` - AutoCoder resources guide
|
||||
- `TEST_PHASE5_RESULTS.md` - Phase 5 test results
|
||||
- `TEST_CONTEXT_RECALL_RESULTS.md` - Context recall test results
|
||||
|
||||
@@ -261,6 +270,13 @@ POST /api/credentials
|
||||
- `test_context_recall_system.py` - Context recall tests (53 total)
|
||||
- `test_context_compression_quick.py` - Compression tests (10/10 passing)
|
||||
|
||||
**AutoCoder Resources:**
|
||||
- `.claude/commands/create-spec.md` - Create app specification
|
||||
- `.claude/commands/checkpoint.md` - Create development checkpoint
|
||||
- `.claude/skills/frontend-design/` - Frontend design skill
|
||||
- `.claude/templates/` - Prompt templates (4 templates)
|
||||
- `mcp-servers/feature-management/` - Feature tracking MCP server
|
||||
|
||||
---
|
||||
|
||||
## Recent Work (from SESSION_STATE.md)
|
||||
@@ -359,6 +375,29 @@ alembic upgrade head
|
||||
|
||||
---
|
||||
|
||||
## MCP Servers
|
||||
|
||||
**Model Context Protocol servers extend Claude Code's capabilities.**
|
||||
|
||||
**Configured Servers:**
|
||||
- **GitHub MCP** - Repository and PR management (requires token)
|
||||
- **Filesystem MCP** - Enhanced file operations (D:\ClaudeTools access)
|
||||
- **Sequential Thinking MCP** - Structured problem-solving
|
||||
|
||||
**Configuration:** `.mcp.json` (project-scoped)
|
||||
**Documentation:** `MCP_SERVERS.md` - Complete setup and usage guide
|
||||
**Setup Script:** `bash scripts/setup-mcp-servers.sh`
|
||||
|
||||
**Quick Start:**
|
||||
1. Add GitHub token to `.mcp.json` (optional)
|
||||
2. Restart Claude Code completely
|
||||
3. Test: "Use sequential thinking to analyze X"
|
||||
4. Test: "List Python files in the api directory"
|
||||
|
||||
**Note:** GitHub MCP is for GitHub.com - Gitea integration requires custom solution (see MCP_SERVERS.md)
|
||||
|
||||
---
|
||||
|
||||
## Next Steps (Optional Phase 7)
|
||||
|
||||
**Remaining entities (from original spec):**
|
||||
@@ -390,12 +429,23 @@ alembic upgrade head
|
||||
**Start API:** `uvicorn api.main:app --reload`
|
||||
**API Docs:** `http://localhost:8000/api/docs` (local) or `http://172.16.3.30:8001/api/docs` (RMM)
|
||||
**Setup Context Recall:** `bash scripts/setup-context-recall.sh`
|
||||
**Setup MCP Servers:** `bash scripts/setup-mcp-servers.sh`
|
||||
**Test System:** `bash scripts/test-context-recall.sh`
|
||||
**Database:** `172.16.3.30:3306/claudetools` (RMM Server)
|
||||
**Virtual Env:** `api\venv\Scripts\activate`
|
||||
**Coding Guidelines:** `.claude/CODING_GUIDELINES.md`
|
||||
**MCP Documentation:** `MCP_SERVERS.md`
|
||||
**AutoCoder Integration:** `AUTOCODER_INTEGRATION.md`
|
||||
|
||||
**Available Commands:**
|
||||
- `/sync` - Cross-machine context synchronization
|
||||
- `/create-spec` - Create app specification
|
||||
- `/checkpoint` - Create development checkpoint
|
||||
|
||||
**Available Skills:**
|
||||
- `/frontend-design` - Modern frontend design patterns
|
||||
|
||||
---
|
||||
|
||||
**Last Updated:** 2026-01-17 (Database migrated to RMM server)
|
||||
**Last Updated:** 2026-01-17 (AutoCoder resources integrated)
|
||||
**Project Progress:** 95% Complete (Phase 6 of 7 done)
|
||||
|
||||
179
.claude/commands/checkpoint.md
Normal file
179
.claude/commands/checkpoint.md
Normal file
@@ -0,0 +1,179 @@
|
||||
---
|
||||
description: Create commit with detailed comment and save session context to database
|
||||
---
|
||||
|
||||
Please create a comprehensive checkpoint that captures BOTH git changes AND session context with the following steps:
|
||||
|
||||
## Part 1: Git Checkpoint
|
||||
|
||||
1. **Initialize Git if needed**: Run `git init` if git has not been instantiated for the project yet.
|
||||
|
||||
2. **Analyze all changes**:
|
||||
|
||||
- Run `git status` to see all tracked and untracked files
|
||||
- Run `git diff` to see detailed changes in tracked files
|
||||
- Run `git log -5 --oneline` to understand the commit message style of this repository
|
||||
|
||||
3. **Stage everything**:
|
||||
|
||||
- Add ALL tracked changes (modified and deleted files)
|
||||
- Add ALL untracked files (new files)
|
||||
- Use `git add -A` or `git add .` to stage everything
|
||||
|
||||
4. **Create a detailed commit message**:
|
||||
|
||||
- **First line**: Write a clear, concise summary (50-72 chars) describing the primary change
|
||||
- Use imperative mood (e.g., "Add feature" not "Added feature")
|
||||
- Examples: "feat: add user authentication", "fix: resolve database connection issue", "refactor: improve API route structure"
|
||||
- **Body**: Provide a detailed description including:
|
||||
- What changes were made (list of key modifications)
|
||||
- Why these changes were made (purpose/motivation)
|
||||
- Any important technical details or decisions
|
||||
- Breaking changes or migration notes if applicable
|
||||
- **Footer**: Include co-author attribution as shown in the Git Safety Protocol
|
||||
|
||||
5. **Execute the commit**: Create the commit with the properly formatted message following this repository's conventions.
|
||||
|
||||
## Part 2: Database Context Save
|
||||
|
||||
6. **Save session context to database**:
|
||||
|
||||
After the commit is complete, save the session context to the ClaudeTools database for cross-machine recall.
|
||||
|
||||
**API Endpoint**: `POST http://172.16.3.30:8001/api/conversation-contexts`
|
||||
|
||||
**Payload Structure**:
|
||||
```json
|
||||
{
|
||||
"project_id": "<project-uuid>",
|
||||
"context_type": "checkpoint",
|
||||
"title": "Checkpoint: <commit-summary>",
|
||||
"dense_summary": "<comprehensive-session-summary>",
|
||||
"relevance_score": 8.0,
|
||||
"tags": ["<extracted-tags>"],
|
||||
"metadata": {
|
||||
"git_commit": "<commit-hash>",
|
||||
"git_branch": "<branch-name>",
|
||||
"files_changed": ["<file-list>"],
|
||||
"commit_message": "<full-commit-message>"
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
**Authentication**: Use JWT token from `.claude/context-recall-config.env`
|
||||
|
||||
**How to construct the payload**:
|
||||
|
||||
a. **Project ID**: Get from git config or environment
|
||||
```bash
|
||||
PROJECT_ID=$(git config --local claude.projectid 2>/dev/null)
|
||||
```
|
||||
|
||||
b. **Title**: Use commit summary line
|
||||
```
|
||||
"Checkpoint: feat: Add Sequential Thinking to Code Review Agent"
|
||||
```
|
||||
|
||||
c. **Dense Summary**: Create compressed summary including:
|
||||
- What was accomplished (from commit message body)
|
||||
- Key files modified (from git diff --name-only)
|
||||
- Important decisions or technical details
|
||||
- Context for future sessions
|
||||
|
||||
Example:
|
||||
```
|
||||
Enhanced code-review.md with Sequential Thinking MCP integration.
|
||||
|
||||
Changes:
|
||||
- Added trigger conditions for 2+ rejections and 3+ critical issues
|
||||
- Created enhanced escalation format with root cause analysis
|
||||
- Added UI_VALIDATION_CHECKLIST.md (462 lines)
|
||||
- Updated frontend-design skill for automatic invocation
|
||||
|
||||
Files: .claude/agents/code-review.md, .claude/skills/frontend-design/SKILL.md,
|
||||
.claude/skills/frontend-design/UI_VALIDATION_CHECKLIST.md
|
||||
|
||||
Decision: Use Sequential Thinking MCP for complex review issues to break
|
||||
rejection cycles and provide comprehensive feedback.
|
||||
|
||||
Commit: a1b2c3d on branch main
|
||||
```
|
||||
|
||||
d. **Tags**: Extract relevant tags from context (4-8 tags)
|
||||
```json
|
||||
["code-review", "sequential-thinking", "frontend-validation", "ui", "documentation"]
|
||||
```
|
||||
|
||||
e. **Metadata**: Include git info for reference
|
||||
```json
|
||||
{
|
||||
"git_commit": "a1b2c3d4e5f",
|
||||
"git_branch": "main",
|
||||
"files_changed": [
|
||||
".claude/agents/code-review.md",
|
||||
".claude/skills/frontend-design/SKILL.md"
|
||||
],
|
||||
"commit_message": "feat: Add Sequential Thinking to Code Review Agent\n\n..."
|
||||
}
|
||||
```
|
||||
|
||||
**Implementation**:
|
||||
```bash
|
||||
# Load config
|
||||
source .claude/context-recall-config.env
|
||||
|
||||
# Get git info
|
||||
COMMIT_HASH=$(git rev-parse --short HEAD)
|
||||
BRANCH=$(git rev-parse --abbrev-ref HEAD)
|
||||
COMMIT_MSG=$(git log -1 --pretty=%B)
|
||||
FILES=$(git diff --name-only HEAD~1 | tr '\n' ',' | sed 's/,$//')
|
||||
|
||||
# Create payload and POST to API
|
||||
curl -X POST http://172.16.3.30:8001/api/conversation-contexts \
|
||||
-H "Authorization: Bearer $JWT_TOKEN" \
|
||||
-H "Content-Type: application/json" \
|
||||
-d '{
|
||||
"project_id": "'$CLAUDE_PROJECT_ID'",
|
||||
"context_type": "checkpoint",
|
||||
"title": "Checkpoint: <commit-summary>",
|
||||
"dense_summary": "<comprehensive-summary>",
|
||||
"relevance_score": 8.0,
|
||||
"tags": ["<tags>"],
|
||||
"metadata": {
|
||||
"git_commit": "'$COMMIT_HASH'",
|
||||
"git_branch": "'$BRANCH'",
|
||||
"files_changed": ["'$FILES'"],
|
||||
"commit_message": "'$COMMIT_MSG'"
|
||||
}
|
||||
}'
|
||||
```
|
||||
|
||||
7. **Verify both checkpoints**:
|
||||
- Confirm git commit succeeded (git log -1)
|
||||
- Confirm database save succeeded (check API response)
|
||||
- Report both statuses to user
|
||||
|
||||
## Benefits of Dual Checkpoint
|
||||
|
||||
**Git Checkpoint:**
|
||||
- Code versioning
|
||||
- Change history
|
||||
- Rollback capability
|
||||
|
||||
**Database Context:**
|
||||
- Cross-machine recall
|
||||
- Semantic search
|
||||
- Session continuity
|
||||
- Context for future work
|
||||
|
||||
**Together:** Complete project memory across time and machines
|
||||
|
||||
## IMPORTANT
|
||||
|
||||
- Do NOT skip any files - include everything
|
||||
- Make the commit message descriptive enough that someone reviewing the git log can understand what was accomplished
|
||||
- Follow the project's existing commit message conventions (check git log first)
|
||||
- Include the Claude Code co-author attribution in the commit message
|
||||
- Ensure database context save includes enough detail for future recall
|
||||
- Use relevance_score 8.0 for checkpoints (important milestones)
|
||||
- Extract meaningful tags (4-8 tags) for search/filtering
|
||||
578
.claude/commands/create-spec.md
Normal file
578
.claude/commands/create-spec.md
Normal file
@@ -0,0 +1,578 @@
|
||||
---
|
||||
description: Create an app spec for autonomous coding (project)
|
||||
---
|
||||
|
||||
# PROJECT DIRECTORY
|
||||
|
||||
This command **requires** the project directory as an argument via `$ARGUMENTS`.
|
||||
|
||||
**Example:** `/create-spec generations/my-app`
|
||||
|
||||
**Output location:** `$ARGUMENTS/prompts/app_spec.txt` and `$ARGUMENTS/prompts/initializer_prompt.md`
|
||||
|
||||
If `$ARGUMENTS` is empty, inform the user they must provide a project path and exit.
|
||||
|
||||
---
|
||||
|
||||
# GOAL
|
||||
|
||||
Help the user create a comprehensive project specification for a long-running autonomous coding process. This specification will be used by AI coding agents to build their application across multiple sessions.
|
||||
|
||||
This tool works for projects of any size - from simple utilities to large-scale applications.
|
||||
|
||||
---
|
||||
|
||||
# YOUR ROLE
|
||||
|
||||
You are the **Spec Creation Assistant** - an expert at translating project ideas into detailed technical specifications. Your job is to:
|
||||
|
||||
1. Understand what the user wants to build (in their own words)
|
||||
2. Ask about features and functionality (things anyone can describe)
|
||||
3. **Derive** the technical details (database, API, architecture) from their requirements
|
||||
4. Generate the specification files that autonomous coding agents will use
|
||||
|
||||
**IMPORTANT: Cater to all skill levels.** Many users are product owners or have functional knowledge but aren't technical. They know WHAT they want to build, not HOW to build it. You should:
|
||||
|
||||
- Ask questions anyone can answer (features, user flows, what screens exist)
|
||||
- **Derive** technical details (database schema, API endpoints, architecture) yourself
|
||||
- Only ask technical questions if the user wants to be involved in those decisions
|
||||
|
||||
**Use conversational questions** to gather information. For questions with clear options, present them as numbered choices that the user can select from. For open-ended exploration, use natural conversation.
|
||||
|
||||
---
|
||||
|
||||
# CONVERSATION FLOW
|
||||
|
||||
There are two paths through this process:
|
||||
|
||||
**Quick Path** (recommended for most users): You describe what you want, agent derives the technical details
|
||||
**Detailed Path**: You want input on technology choices, database design, API structure, etc.
|
||||
|
||||
**CRITICAL: This is a CONVERSATION, not a form.**
|
||||
|
||||
- Ask questions for ONE phase at a time
|
||||
- WAIT for the user to respond before moving to the next phase
|
||||
- Acknowledge their answers before continuing
|
||||
- Do NOT bundle multiple phases into one message
|
||||
|
||||
---
|
||||
|
||||
## Phase 1: Project Overview
|
||||
|
||||
Start with simple questions anyone can answer:
|
||||
|
||||
1. **Project Name**: What should this project be called?
|
||||
2. **Description**: In your own words, what are you building and what problem does it solve?
|
||||
3. **Target Audience**: Who will use this?
|
||||
|
||||
**IMPORTANT: Ask these questions and WAIT for the user to respond before continuing.**
|
||||
Do NOT immediately jump to Phase 2. Let the user answer, acknowledge their responses, then proceed.
|
||||
|
||||
---
|
||||
|
||||
## Phase 2: Involvement Level
|
||||
|
||||
Ask the user about their involvement preference:
|
||||
|
||||
> "How involved do you want to be in technical decisions?
|
||||
>
|
||||
> 1. **Quick Mode (Recommended)** - You describe what you want, I'll handle database, API, and architecture
|
||||
> 2. **Detailed Mode** - You want input on technology choices and architecture decisions
|
||||
>
|
||||
> Which would you prefer?"
|
||||
|
||||
**If Quick Mode**: Skip to Phase 3, then go to Phase 4 (Features). You will derive technical details yourself.
|
||||
**If Detailed Mode**: Go through all phases, asking technical questions.
|
||||
|
||||
## Phase 3: Technology Preferences
|
||||
|
||||
**For Quick Mode users**, also ask about tech preferences:
|
||||
|
||||
> "Any technology preferences, or should I choose sensible defaults?
|
||||
>
|
||||
> 1. **Use defaults (Recommended)** - React, Node.js, SQLite - solid choices for most apps
|
||||
> 2. **I have preferences** - I'll specify my preferred languages/frameworks"
|
||||
|
||||
**For Detailed Mode users**, ask specific tech questions about frontend, backend, database, etc.
|
||||
|
||||
## Phase 4: Features (THE MAIN PHASE)
|
||||
|
||||
This is where you spend most of your time. Ask questions in plain language that anyone can answer.
|
||||
|
||||
**Start broad with open conversation:**
|
||||
|
||||
> "Walk me through your app. What does a user see when they first open it? What can they do?"
|
||||
|
||||
**Then ask about key feature areas:**
|
||||
|
||||
> "Let me ask about a few common feature areas:
|
||||
>
|
||||
> 1. **User Accounts** - Do users need to log in / have accounts? (Yes with profiles, No anonymous use, or Maybe optional)
|
||||
> 2. **Mobile Support** - Should this work well on mobile phones? (Yes fully responsive, Desktop only, or Basic mobile)
|
||||
> 3. **Search** - Do users need to search or filter content? (Yes, No, or Basic only)
|
||||
> 4. **Sharing** - Any sharing or collaboration features? (Yes, No, or Maybe later)"
|
||||
|
||||
**Then drill into the "Yes" answers with open conversation:**
|
||||
|
||||
**4a. The Main Experience**
|
||||
|
||||
- What's the main thing users do in your app?
|
||||
- Walk me through a typical user session
|
||||
|
||||
**4b. User Accounts** (if they said Yes)
|
||||
|
||||
- What can they do with their account?
|
||||
- Any roles or permissions?
|
||||
|
||||
**4c. What Users Create/Manage**
|
||||
|
||||
- What "things" do users create, save, or manage?
|
||||
- Can they edit or delete these things?
|
||||
- Can they organize them (folders, tags, categories)?
|
||||
|
||||
**4d. Settings & Customization**
|
||||
|
||||
- What should users be able to customize?
|
||||
- Light/dark mode? Other display preferences?
|
||||
|
||||
**4e. Search & Finding Things** (if they said Yes)
|
||||
|
||||
- What do they search for?
|
||||
- What filters would be helpful?
|
||||
|
||||
**4f. Sharing & Collaboration** (if they said Yes)
|
||||
|
||||
- What can be shared?
|
||||
- View-only or collaborative editing?
|
||||
|
||||
**4g. Any Dashboards or Analytics?**
|
||||
|
||||
- Does the user see any stats, reports, or metrics?
|
||||
|
||||
**4h. Domain-Specific Features**
|
||||
|
||||
- What else is unique to your app?
|
||||
- Any features we haven't covered?
|
||||
|
||||
**4i. Security & Access Control (if app has authentication)**
|
||||
|
||||
Ask about user roles:
|
||||
|
||||
> "Who are the different types of users?
|
||||
>
|
||||
> 1. **Just regular users** - Everyone has the same permissions
|
||||
> 2. **Users + Admins** - Regular users and administrators with extra powers
|
||||
> 3. **Multiple roles** - Several distinct user types (e.g., viewer, editor, manager, admin)"
|
||||
|
||||
**If multiple roles, explore in conversation:**
|
||||
|
||||
- What can each role see?
|
||||
- What can each role do?
|
||||
- Are there pages only certain roles can access?
|
||||
- What happens if someone tries to access something they shouldn't?
|
||||
|
||||
**Also ask about authentication:**
|
||||
|
||||
- How do users log in? (email/password, social login, SSO)
|
||||
- Password requirements? (for security testing)
|
||||
- Session timeout? Auto-logout after inactivity?
|
||||
- Any sensitive operations requiring extra confirmation?
|
||||
|
||||
**4j. Data Flow & Integration**
|
||||
|
||||
- What data do users create vs what's system-generated?
|
||||
- Are there workflows that span multiple steps or pages?
|
||||
- What happens to related data when something is deleted?
|
||||
- Are there any external systems or APIs to integrate with?
|
||||
- Any import/export functionality?
|
||||
|
||||
**4k. Error & Edge Cases**
|
||||
|
||||
- What should happen if the network fails mid-action?
|
||||
- What about duplicate entries (e.g., same email twice)?
|
||||
- Very long text inputs?
|
||||
- Empty states (what shows when there's no data)?
|
||||
|
||||
**Keep asking follow-up questions until you have a complete picture.** For each feature area, understand:
|
||||
|
||||
- What the user sees
|
||||
- What actions they can take
|
||||
- What happens as a result
|
||||
- Who is allowed to do it (permissions)
|
||||
- What errors could occur
|
||||
|
||||
## Phase 4L: Derive Feature Count (DO NOT ASK THE USER)
|
||||
|
||||
After gathering all features, **you** (the agent) should tally up the testable features. Do NOT ask the user how many features they want - derive it from what was discussed.
|
||||
|
||||
**Typical ranges for reference:**
|
||||
|
||||
- **Simple apps** (todo list, calculator, notes): ~20-50 features
|
||||
- **Medium apps** (blog, task manager with auth): ~100 features
|
||||
- **Advanced apps** (e-commerce, CRM, full SaaS): ~150-200 features
|
||||
|
||||
These are just reference points - your actual count should come from the requirements discussed.
|
||||
|
||||
**How to count features:**
|
||||
For each feature area discussed, estimate the number of discrete, testable behaviors:
|
||||
|
||||
- Each CRUD operation = 1 feature (create, read, update, delete)
|
||||
- Each UI interaction = 1 feature (click, drag, hover effect)
|
||||
- Each validation/error case = 1 feature
|
||||
- Each visual requirement = 1 feature (styling, animation, responsive behavior)
|
||||
|
||||
**Present your estimate to the user:**
|
||||
|
||||
> "Based on what we discussed, here's my feature breakdown:
|
||||
>
|
||||
> - [Category 1]: ~X features
|
||||
> - [Category 2]: ~Y features
|
||||
> - [Category 3]: ~Z features
|
||||
> - ...
|
||||
>
|
||||
> **Total: ~N features**
|
||||
>
|
||||
> Does this seem right, or should I adjust?"
|
||||
|
||||
Let the user confirm or adjust. This becomes your `feature_count` for the spec.
|
||||
|
||||
## Phase 5: Technical Details (DERIVED OR DISCUSSED)
|
||||
|
||||
**For Quick Mode users:**
|
||||
Tell them: "Based on what you've described, I'll design the database, API, and architecture. Here's a quick summary of what I'm planning..."
|
||||
|
||||
Then briefly outline:
|
||||
|
||||
- Main data entities you'll create (in plain language: "I'll create tables for users, projects, documents, etc.")
|
||||
- Overall app structure ("sidebar navigation with main content area")
|
||||
- Any key technical decisions
|
||||
|
||||
Ask: "Does this sound right? Any concerns?"
|
||||
|
||||
**For Detailed Mode users:**
|
||||
Walk through each technical area:
|
||||
|
||||
**5a. Database Design**
|
||||
|
||||
- What entities/tables are needed?
|
||||
- Key fields for each?
|
||||
- Relationships?
|
||||
|
||||
**5b. API Design**
|
||||
|
||||
- What endpoints are needed?
|
||||
- How should they be organized?
|
||||
|
||||
**5c. UI Layout**
|
||||
|
||||
- Overall structure (columns, navigation)
|
||||
- Key screens/pages
|
||||
- Design preferences (colors, themes)
|
||||
|
||||
**5d. Implementation Phases**
|
||||
|
||||
- What order to build things?
|
||||
- Dependencies?
|
||||
|
||||
## Phase 6: Success Criteria
|
||||
|
||||
Ask in simple terms:
|
||||
|
||||
> "What does 'done' look like for you? When would you consider this app complete and successful?"
|
||||
|
||||
Prompt for:
|
||||
|
||||
- Must-have functionality
|
||||
- Quality expectations (polished vs functional)
|
||||
- Any specific requirements
|
||||
|
||||
## Phase 7: Review & Approval
|
||||
|
||||
Present everything gathered:
|
||||
|
||||
1. **Summary of the app** (in plain language)
|
||||
2. **Feature count**
|
||||
3. **Technology choices** (whether specified or derived)
|
||||
4. **Brief technical plan** (for their awareness)
|
||||
|
||||
First ask in conversation if they want to make changes.
|
||||
|
||||
**Then ask for final confirmation:**
|
||||
|
||||
> "Ready to generate the specification files?
|
||||
>
|
||||
> 1. **Yes, generate files** - Create app_spec.txt and update prompt files
|
||||
> 2. **I have changes** - Let me add or modify something first"
|
||||
|
||||
---
|
||||
|
||||
# FILE GENERATION
|
||||
|
||||
**Note: This section is for YOU (the agent) to execute. Do not burden the user with these technical details.**
|
||||
|
||||
## Output Directory
|
||||
|
||||
The output directory is: `$ARGUMENTS/prompts/`
|
||||
|
||||
Once the user approves, generate these files:
|
||||
|
||||
## 1. Generate `app_spec.txt`
|
||||
|
||||
**Output path:** `$ARGUMENTS/prompts/app_spec.txt`
|
||||
|
||||
Create a new file using this XML structure:
|
||||
|
||||
```xml
|
||||
<project_specification>
|
||||
<project_name>[Project Name]</project_name>
|
||||
|
||||
<overview>
|
||||
[2-3 sentence description from Phase 1]
|
||||
</overview>
|
||||
|
||||
<technology_stack>
|
||||
<frontend>
|
||||
<framework>[Framework]</framework>
|
||||
<styling>[Styling solution]</styling>
|
||||
[Additional frontend config]
|
||||
</frontend>
|
||||
<backend>
|
||||
<runtime>[Runtime]</runtime>
|
||||
<database>[Database]</database>
|
||||
[Additional backend config]
|
||||
</backend>
|
||||
<communication>
|
||||
<api>[API style]</api>
|
||||
[Additional communication config]
|
||||
</communication>
|
||||
</technology_stack>
|
||||
|
||||
<prerequisites>
|
||||
<environment_setup>
|
||||
[Setup requirements]
|
||||
</environment_setup>
|
||||
</prerequisites>
|
||||
|
||||
<feature_count>[derived count from Phase 4L]</feature_count>
|
||||
|
||||
<security_and_access_control>
|
||||
<user_roles>
|
||||
<role name="[role_name]">
|
||||
<permissions>
|
||||
- [Can do X]
|
||||
- [Can see Y]
|
||||
- [Cannot access Z]
|
||||
</permissions>
|
||||
<protected_routes>
|
||||
- /admin/* (admin only)
|
||||
- /settings (authenticated users)
|
||||
</protected_routes>
|
||||
</role>
|
||||
[Repeat for each role]
|
||||
</user_roles>
|
||||
<authentication>
|
||||
<method>[email/password | social | SSO]</method>
|
||||
<session_timeout>[duration or "none"]</session_timeout>
|
||||
<password_requirements>[if applicable]</password_requirements>
|
||||
</authentication>
|
||||
<sensitive_operations>
|
||||
- [Delete account requires password confirmation]
|
||||
- [Financial actions require 2FA]
|
||||
</sensitive_operations>
|
||||
</security_and_access_control>
|
||||
|
||||
<core_features>
|
||||
<[category_name]>
|
||||
- [Feature 1]
|
||||
- [Feature 2]
|
||||
- [Feature 3]
|
||||
</[category_name]>
|
||||
[Repeat for all feature categories]
|
||||
</core_features>
|
||||
|
||||
<database_schema>
|
||||
<tables>
|
||||
<[table_name]>
|
||||
- [field1], [field2], [field3]
|
||||
- [additional fields]
|
||||
</[table_name]>
|
||||
[Repeat for all tables]
|
||||
</tables>
|
||||
</database_schema>
|
||||
|
||||
<api_endpoints_summary>
|
||||
<[category]>
|
||||
- [VERB] /api/[path]
|
||||
- [VERB] /api/[path]
|
||||
</[category]>
|
||||
[Repeat for all categories]
|
||||
</api_endpoints_summary>
|
||||
|
||||
<ui_layout>
|
||||
<main_structure>
|
||||
[Layout description]
|
||||
</main_structure>
|
||||
[Additional UI sections as needed]
|
||||
</ui_layout>
|
||||
|
||||
<design_system>
|
||||
<color_palette>
|
||||
[Colors]
|
||||
</color_palette>
|
||||
<typography>
|
||||
[Font preferences]
|
||||
</typography>
|
||||
</design_system>
|
||||
|
||||
<implementation_steps>
|
||||
<step number="1">
|
||||
<title>[Phase Title]</title>
|
||||
<tasks>
|
||||
- [Task 1]
|
||||
- [Task 2]
|
||||
</tasks>
|
||||
</step>
|
||||
[Repeat for all phases]
|
||||
</implementation_steps>
|
||||
|
||||
<success_criteria>
|
||||
<functionality>
|
||||
[Functionality criteria]
|
||||
</functionality>
|
||||
<user_experience>
|
||||
[UX criteria]
|
||||
</user_experience>
|
||||
<technical_quality>
|
||||
[Technical criteria]
|
||||
</technical_quality>
|
||||
<design_polish>
|
||||
[Design criteria]
|
||||
</design_polish>
|
||||
</success_criteria>
|
||||
</project_specification>
|
||||
```
|
||||
|
||||
## 2. Update `initializer_prompt.md`
|
||||
|
||||
**Output path:** `$ARGUMENTS/prompts/initializer_prompt.md`
|
||||
|
||||
If the output directory has an existing `initializer_prompt.md`, read it and update the feature count.
|
||||
If not, copy from `.claude/templates/initializer_prompt.template.md` first, then update.
|
||||
|
||||
**CRITICAL: You MUST update the feature count placeholder:**
|
||||
|
||||
1. Find the line containing `**[FEATURE_COUNT]**` in the "REQUIRED FEATURE COUNT" section
|
||||
2. Replace `[FEATURE_COUNT]` with the exact number agreed upon in Phase 4L (e.g., `25`)
|
||||
3. The result should read like: `You must create exactly **25** features using the...`
|
||||
|
||||
**Example edit:**
|
||||
```
|
||||
Before: **CRITICAL:** You must create exactly **[FEATURE_COUNT]** features using the `feature_create_bulk` tool.
|
||||
After: **CRITICAL:** You must create exactly **25** features using the `feature_create_bulk` tool.
|
||||
```
|
||||
|
||||
**Verify the update:** After editing, read the file again to confirm the feature count appears correctly. If `[FEATURE_COUNT]` still appears in the file, the update failed and you must try again.
|
||||
|
||||
**Note:** You may also update `coding_prompt.md` if the user requests changes to how the coding agent should work. Include it in the status file if modified.
|
||||
|
||||
## 3. Write Status File (REQUIRED - Do This Last)
|
||||
|
||||
**Output path:** `$ARGUMENTS/prompts/.spec_status.json`
|
||||
|
||||
**CRITICAL:** After you have completed ALL requested file changes, write this status file to signal completion to the UI. This is required for the "Continue to Project" button to appear.
|
||||
|
||||
Write this JSON file:
|
||||
|
||||
```json
|
||||
{
|
||||
"status": "complete",
|
||||
"version": 1,
|
||||
"timestamp": "[current ISO 8601 timestamp, e.g., 2025-01-15T14:30:00.000Z]",
|
||||
"files_written": [
|
||||
"prompts/app_spec.txt",
|
||||
"prompts/initializer_prompt.md"
|
||||
],
|
||||
"feature_count": [the feature count from Phase 4L]
|
||||
}
|
||||
```
|
||||
|
||||
**Include ALL files you modified** in the `files_written` array. If the user asked you to also modify `coding_prompt.md`, include it:
|
||||
|
||||
```json
|
||||
{
|
||||
"status": "complete",
|
||||
"version": 1,
|
||||
"timestamp": "2025-01-15T14:30:00.000Z",
|
||||
"files_written": [
|
||||
"prompts/app_spec.txt",
|
||||
"prompts/initializer_prompt.md",
|
||||
"prompts/coding_prompt.md"
|
||||
],
|
||||
"feature_count": 35
|
||||
}
|
||||
```
|
||||
|
||||
**IMPORTANT:**
|
||||
- Write this file LAST, after all other files are successfully written
|
||||
- Only write it when you consider ALL requested work complete
|
||||
- The UI polls this file to detect completion and show the Continue button
|
||||
- If the user asks for additional changes after you've written this, you may update it again when the new changes are complete
|
||||
|
||||
---
|
||||
|
||||
# AFTER FILE GENERATION: NEXT STEPS
|
||||
|
||||
Once files are generated, tell the user what to do next:
|
||||
|
||||
> "Your specification files have been created in `$ARGUMENTS/prompts/`!
|
||||
>
|
||||
> **Files created:**
|
||||
> - `$ARGUMENTS/prompts/app_spec.txt`
|
||||
> - `$ARGUMENTS/prompts/initializer_prompt.md`
|
||||
>
|
||||
> The **Continue to Project** button should now appear. Click it to start the autonomous coding agent!
|
||||
>
|
||||
> **If you don't see the button:** Type `/exit` or click **Exit to Project** in the header.
|
||||
>
|
||||
> **Important timing expectations:**
|
||||
>
|
||||
> - **First session:** The agent generates features in the database. This takes several minutes.
|
||||
> - **Subsequent sessions:** Each coding iteration takes 5-15 minutes depending on complexity.
|
||||
> - **Full app:** Building all [X] features will take many hours across multiple sessions.
|
||||
>
|
||||
> **Controls:**
|
||||
>
|
||||
> - Press `Ctrl+C` to pause the agent at any time
|
||||
> - Run `start.bat` (Windows) or `./start.sh` (Mac/Linux) to resume where you left off"
|
||||
|
||||
Replace `[X]` with their feature count.
|
||||
|
||||
---
|
||||
|
||||
# IMPORTANT REMINDERS
|
||||
|
||||
- **Meet users where they are**: Not everyone is technical. Ask about what they want, not how to build it.
|
||||
- **Quick Mode is the default**: Most users should be able to describe their app and let you handle the technical details.
|
||||
- **Derive, don't interrogate**: For non-technical users, derive database schema, API endpoints, and architecture from their feature descriptions. Don't ask them to specify these.
|
||||
- **Use plain language**: Instead of "What entities need CRUD operations?", ask "What things can users create, edit, or delete?"
|
||||
- **Be thorough on features**: This is where to spend time. Keep asking follow-up questions until you have a complete picture.
|
||||
- **Derive feature count, don't guess**: After gathering requirements, tally up testable features yourself and present the estimate. Don't use fixed tiers or ask users to guess.
|
||||
- **Validate before generating**: Present a summary including your derived feature count and get explicit approval before creating files.
|
||||
|
||||
---
|
||||
|
||||
# BEGIN
|
||||
|
||||
Start by greeting the user warmly. Ask ONLY the Phase 1 questions:
|
||||
|
||||
> "Hi! I'm here to help you create a detailed specification for your app.
|
||||
>
|
||||
> Let's start with the basics:
|
||||
>
|
||||
> 1. What do you want to call this project?
|
||||
> 2. In your own words, what are you building?
|
||||
> 3. Who will use it - just you, or others too?"
|
||||
|
||||
**STOP HERE and wait for their response.** Do not ask any other questions yet. Do not use AskUserQuestion yet. Just have a conversation about their project basics first.
|
||||
|
||||
After they respond, acknowledge what they said, then move to Phase 2.
|
||||
@@ -0,0 +1,588 @@
|
||||
# Frontend Design Skill - Automatic Validation Enhancement
|
||||
|
||||
**Enhancement Date:** 2026-01-17
|
||||
**Status:** COMPLETED
|
||||
|
||||
---
|
||||
|
||||
## Summary
|
||||
|
||||
Enhanced the frontend-design skill to be automatically invoked whenever ANY action affects a UI element. This ensures all UI changes are validated for visual correctness, functionality, responsive behavior, and accessibility before being finalized.
|
||||
|
||||
---
|
||||
|
||||
## What Changed
|
||||
|
||||
### 1. Updated Skill Metadata
|
||||
|
||||
**File:** `.claude/skills/frontend-design/SKILL.md`
|
||||
|
||||
**Description Updated:**
|
||||
- Added "MANDATORY AUTOMATIC INVOCATION" to skill description
|
||||
- Clarified that skill must be invoked whenever ANY action affects UI
|
||||
- Made validation a core function alongside creation
|
||||
|
||||
**Before:**
|
||||
```
|
||||
Use this skill when the user asks to build web components...
|
||||
```
|
||||
|
||||
**After:**
|
||||
```
|
||||
MANDATORY AUTOMATIC INVOCATION: Use this skill whenever ANY action
|
||||
affects a UI element to validate visual correctness, functionality,
|
||||
and user experience. Also use when the user asks to build...
|
||||
```
|
||||
|
||||
### 2. New Section: "CRITICAL: Automatic Invocation Triggers"
|
||||
|
||||
**Location:** After introduction, before "Design Thinking" section
|
||||
|
||||
**Added 120+ lines covering:**
|
||||
- When to invoke this skill (mandatory triggers)
|
||||
- Purpose of automatic invocation
|
||||
- Validation workflow (5-step process)
|
||||
- Examples of automatic invocation
|
||||
- Integration with other agents
|
||||
- Rule of thumb
|
||||
|
||||
### 3. Created Comprehensive Validation Checklist
|
||||
|
||||
**New File:** `.claude/skills/frontend-design/UI_VALIDATION_CHECKLIST.md`
|
||||
|
||||
**Contents:**
|
||||
- 8 validation categories (200+ checkpoints)
|
||||
- 3 validation workflows (quick, standard, comprehensive)
|
||||
- Validation report formats
|
||||
- Common issues to watch for
|
||||
- Decision matrix (pass, warn, or block)
|
||||
|
||||
---
|
||||
|
||||
## Automatic Invocation Triggers
|
||||
|
||||
### MANDATORY Triggers
|
||||
|
||||
The skill MUST be invoked for:
|
||||
|
||||
**1. UI Creation**
|
||||
- Creating new web pages, components, or interfaces
|
||||
- Building dashboards, forms, or layouts
|
||||
- Designing landing pages or marketing sites
|
||||
- Generating HTML/CSS/React/Vue code
|
||||
|
||||
**2. UI Modification**
|
||||
- Changing styles, colors, fonts, or layouts
|
||||
- Updating component appearance or behavior
|
||||
- Refactoring frontend code
|
||||
- Adding animations or interactions
|
||||
|
||||
**3. UI Validation**
|
||||
- After ANY code change that affects UI
|
||||
- After updating styles or markup
|
||||
- After adding features to UI components
|
||||
- After refactoring frontend code
|
||||
- After fixing UI bugs
|
||||
|
||||
### Rule of Thumb
|
||||
|
||||
**If the change appears in a browser, invoke this skill to validate it.**
|
||||
|
||||
---
|
||||
|
||||
## Validation Workflow
|
||||
|
||||
When invoked for UI validation:
|
||||
|
||||
```markdown
|
||||
1. REVIEW: What UI elements were changed?
|
||||
2. ASSESS: How should they appear/behave?
|
||||
3. VALIDATE:
|
||||
- Visual appearance (layout, colors, fonts, spacing)
|
||||
- Interactive behavior (hover, click, focus states)
|
||||
- Responsive behavior (mobile, tablet, desktop)
|
||||
- Accessibility (keyboard nav, screen readers)
|
||||
4. REPORT:
|
||||
- [OK] Working correctly
|
||||
- [WARNING] Minor issues detected
|
||||
- [ERROR] Critical issues found
|
||||
5. FIX: If issues found, provide corrected code
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Validation Categories (8 Total)
|
||||
|
||||
### 1. Visual Appearance
|
||||
- Layout & structure (positioning, grid/flex, z-index)
|
||||
- Typography (fonts, sizes, hierarchy)
|
||||
- Colors & contrast (WCAG compliance)
|
||||
- Spacing & rhythm (padding, margins, whitespace)
|
||||
- Visual effects (shadows, borders, backgrounds)
|
||||
|
||||
### 2. Interactive Behavior
|
||||
- Click/tap interactions (buttons, links, forms)
|
||||
- Hover states (feedback, cursor changes)
|
||||
- Focus states (keyboard navigation)
|
||||
- Active states (pressed/loading)
|
||||
- Disabled states (visual indication)
|
||||
|
||||
### 3. Responsive Behavior
|
||||
- Breakpoints (6 ranges from 320px to 1920px+)
|
||||
- Adaptive layout (reflow, no horizontal scroll)
|
||||
- Responsive typography (scaling, line length)
|
||||
- Mobile-specific (touch targets, gestures, keyboard)
|
||||
|
||||
### 4. Animations & Transitions
|
||||
- Animation quality (smoothness, timing, easing)
|
||||
- Performance (GPU acceleration, no jank)
|
||||
- Transition states (enter, exit, loading)
|
||||
- Scroll animations (parallax, sticky, progress)
|
||||
|
||||
### 5. Accessibility
|
||||
- Keyboard navigation (tab order, shortcuts)
|
||||
- Screen reader support (semantic HTML, ARIA)
|
||||
- Visual accessibility (contrast, focus, resize)
|
||||
- Alternative content (alt text, captions)
|
||||
|
||||
### 6. Performance
|
||||
- Load performance (critical CSS, font loading, lazy loading)
|
||||
- Runtime performance (no layout shifts, smooth scrolling)
|
||||
- Resource optimization (image compression, minification)
|
||||
|
||||
### 7. Cross-Browser Compatibility
|
||||
- Modern browsers (Chrome, Firefox, Safari, Mobile)
|
||||
- Fallbacks (graceful degradation, polyfills)
|
||||
|
||||
### 8. Content & Copy
|
||||
- Text quality (no typos, proper capitalization)
|
||||
- Internationalization (RTL, long text handling)
|
||||
|
||||
---
|
||||
|
||||
## Three Validation Levels
|
||||
|
||||
### Quick Validation (1-2 minutes)
|
||||
**For:** Minor changes (color updates, spacing tweaks)
|
||||
|
||||
**Checks:**
|
||||
- Visual check at 1-2 breakpoints
|
||||
- Verify hover/focus states
|
||||
- Quick accessibility scan
|
||||
- Report: [OK] or [WARNING]
|
||||
|
||||
### Standard Validation (3-5 minutes)
|
||||
**For:** Component modifications, feature additions
|
||||
|
||||
**Checks:**
|
||||
- Visual check at all breakpoints
|
||||
- Test all interactive states
|
||||
- Keyboard navigation test
|
||||
- Basic performance check
|
||||
- Report: [OK], [WARNING], or [ERROR]
|
||||
|
||||
### Comprehensive Validation (10-15 minutes)
|
||||
**For:** New components, major refactors
|
||||
|
||||
**Checks:**
|
||||
- Complete visual review (all 8 categories)
|
||||
- Full interaction testing
|
||||
- Cross-browser testing
|
||||
- Accessibility audit
|
||||
- Performance profiling
|
||||
- Report: Detailed findings with fixes
|
||||
|
||||
---
|
||||
|
||||
## Examples of Automatic Invocation
|
||||
|
||||
### Example 1: Adding a Button
|
||||
|
||||
```
|
||||
User: "Add a submit button to the form"
|
||||
Assistant: [Adds button code]
|
||||
→ TRIGGER: Invoke frontend-design skill
|
||||
→ VALIDATE: Button appears correctly, hover states work, accessible
|
||||
→ REPORT: "[OK] Submit button added and validated"
|
||||
```
|
||||
|
||||
### Example 2: Styling Update
|
||||
|
||||
```
|
||||
User: "Change the header background to blue"
|
||||
Assistant: [Updates CSS]
|
||||
→ TRIGGER: Invoke frontend-design skill
|
||||
→ VALIDATE: Blue renders correctly, contrast is readable, responsive
|
||||
→ REPORT: "[OK] Header background updated and validated"
|
||||
```
|
||||
|
||||
### Example 3: Component Refactor
|
||||
|
||||
```
|
||||
User: "Refactor the navigation component"
|
||||
Assistant: [Refactors code]
|
||||
→ TRIGGER: Invoke frontend-design skill
|
||||
→ VALIDATE: Navigation still works, styles intact, mobile menu functions
|
||||
→ REPORT: "[OK] Navigation refactored and validated"
|
||||
OR
|
||||
"[WARNING] Mobile menu broken - fixing..."
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Integration with Other Agents
|
||||
|
||||
### Coordination with Code Review Agent
|
||||
|
||||
**Code Review Agent:**
|
||||
- Checks code quality (readability, maintainability)
|
||||
- Checks security (XSS, injection vulnerabilities)
|
||||
- Checks performance (algorithmic complexity)
|
||||
|
||||
**Frontend Design Skill:**
|
||||
- Checks visual correctness (layout, colors, fonts)
|
||||
- Checks UX functionality (interactions, responsiveness)
|
||||
- Checks accessibility (WCAG compliance)
|
||||
|
||||
**Both must approve before UI changes are finalized.**
|
||||
|
||||
### Coordination with Testing Agent
|
||||
|
||||
**Testing Agent:**
|
||||
- Runs automated tests (unit, integration, e2e)
|
||||
- Validates functionality programmatically
|
||||
- Checks for regressions
|
||||
|
||||
**Frontend Design Skill:**
|
||||
- Validates visual/UX manually
|
||||
- Checks design quality and aesthetics
|
||||
- Ensures accessibility compliance
|
||||
|
||||
**Complementary validation approaches.**
|
||||
|
||||
---
|
||||
|
||||
## Decision Matrix
|
||||
|
||||
### PASS - Approve Changes
|
||||
- All critical validations passed
|
||||
- No major issues detected
|
||||
- Minor observations noted but don't block
|
||||
- Ready for code review/testing
|
||||
|
||||
**Report Format:**
|
||||
```markdown
|
||||
## UI Validation: PASSED
|
||||
|
||||
**Component:** Button Component
|
||||
**Changes:** Added hover animation
|
||||
|
||||
**Validation Results:**
|
||||
- [OK] Visual appearance correct
|
||||
- [OK] Interactive behavior working
|
||||
- [OK] Responsive at all breakpoints
|
||||
- [OK] Accessibility requirements met
|
||||
```
|
||||
|
||||
### WARN - Approve with Notes
|
||||
- Minor issues detected
|
||||
- Issues fixed during validation
|
||||
- Recommendations for improvement
|
||||
- Can proceed but note improvements
|
||||
|
||||
**Report Format:**
|
||||
```markdown
|
||||
## UI Validation: WARNINGS
|
||||
|
||||
**Component:** Navigation Menu
|
||||
**Changes:** Updated styles
|
||||
|
||||
**Validation Results:**
|
||||
- [OK] Visual appearance correct
|
||||
- [WARNING] Minor transition timing issue
|
||||
- [OK] Responsive at all breakpoints
|
||||
- [OK] Accessibility requirements met
|
||||
|
||||
**Issues Found:**
|
||||
1. Hover transition too slow (500ms → 200ms) - FIXED
|
||||
```
|
||||
|
||||
### BLOCK - Require Fixes
|
||||
- Critical functionality broken
|
||||
- Accessibility violations (WCAG A/AA)
|
||||
- Visual appearance significantly wrong
|
||||
- Responsive layout broken
|
||||
- Performance severely degraded
|
||||
|
||||
**Report Format:**
|
||||
```markdown
|
||||
## UI Validation: ERRORS
|
||||
|
||||
**Component:** Login Form
|
||||
**Changes:** Added validation
|
||||
|
||||
**Validation Results:**
|
||||
- [ERROR] Interactive behavior broken
|
||||
- [ERROR] Accessibility violations
|
||||
- [WARNING] Responsive issues on mobile
|
||||
|
||||
**Critical Issues:**
|
||||
1. CRITICAL: Submit button not clickable
|
||||
2. CRITICAL: No keyboard accessibility
|
||||
3. MAJOR: Mobile layout broken
|
||||
|
||||
**Status:** BLOCKED - fixes required
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Benefits
|
||||
|
||||
### 1. Consistent Quality
|
||||
- Every UI change is validated
|
||||
- No "ship and hope" for visual changes
|
||||
- Quality gate before code review
|
||||
|
||||
### 2. Catch Issues Early
|
||||
- Visual bugs caught before testing phase
|
||||
- Accessibility issues identified immediately
|
||||
- Responsive problems detected upfront
|
||||
|
||||
### 3. Better User Experience
|
||||
- Interactions work correctly
|
||||
- Responsive behavior validated
|
||||
- Accessibility ensured
|
||||
|
||||
### 4. Reduced Rework
|
||||
- Issues fixed during development
|
||||
- Fewer back-and-forth with designers
|
||||
- Less QA rejection
|
||||
|
||||
### 5. Learning & Improvement
|
||||
- Validation reports document common issues
|
||||
- Patterns emerge for prevention
|
||||
- Team learns best practices
|
||||
|
||||
---
|
||||
|
||||
## Common Issues Detected
|
||||
|
||||
### Most Frequent Issues
|
||||
|
||||
1. **Missing hover states** - Interactive elements without feedback
|
||||
2. **Insufficient contrast** - Text/background fails WCAG
|
||||
3. **Broken mobile layouts** - Responsive breakpoints not tested
|
||||
4. **No keyboard accessibility** - Focus states missing
|
||||
5. **Slow animations** - Performance issues on mobile
|
||||
6. **Missing alt text** - Accessibility violations
|
||||
7. **Text overflow** - Long content breaks layout
|
||||
8. **Click targets too small** - Mobile usability issues
|
||||
|
||||
### Prevention Strategies
|
||||
|
||||
**From Validation Insights:**
|
||||
- Always add hover/focus states together
|
||||
- Test contrast ratios during color selection
|
||||
- Mobile-first development approach
|
||||
- Include keyboard testing in workflow
|
||||
- Use CSS transforms for animations
|
||||
- Alt text checklist for all images
|
||||
- Text overflow handling by default
|
||||
- Minimum 44x44px touch targets
|
||||
|
||||
---
|
||||
|
||||
## Usage Guide
|
||||
|
||||
### For Developers Using Main Claude
|
||||
|
||||
**After ANY UI change:**
|
||||
|
||||
1. **Expect automatic validation** - Frontend skill will be invoked
|
||||
2. **Review validation report** - Check for [OK], [WARNING], or [ERROR]
|
||||
3. **Address issues if found** - Apply fixes or ask for help
|
||||
4. **Get final approval** - Both frontend and code review must pass
|
||||
|
||||
### For Main Claude (Coordinator)
|
||||
|
||||
**When UI code is modified:**
|
||||
|
||||
1. **Recognize UI change** - Any HTML/CSS/JSX/styling code
|
||||
2. **Invoke frontend-design skill** - Use Skill tool
|
||||
3. **Receive validation report** - Parse results
|
||||
4. **Act on findings:**
|
||||
- [OK] → Proceed to code review
|
||||
- [WARNING] → Note issues, proceed
|
||||
- [ERROR] → Fix issues before proceeding
|
||||
|
||||
**Example Coordination:**
|
||||
```
|
||||
User: "Add dark mode toggle"
|
||||
Main Claude: [Writes dark mode code]
|
||||
Main Claude: [Invokes frontend-design skill]
|
||||
Frontend Skill: [Validates - finds contrast issue]
|
||||
Frontend Skill: [Fixes contrast issue]
|
||||
Frontend Skill: [Returns PASS report]
|
||||
Main Claude: [Proceeds to code review]
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Files Modified/Created
|
||||
|
||||
### Modified Files
|
||||
|
||||
1. **`.claude/skills/frontend-design/SKILL.md`**
|
||||
- Updated metadata description
|
||||
- Added "CRITICAL: Automatic Invocation Triggers" section (120+ lines)
|
||||
- Added validation workflow
|
||||
- Added examples and integration notes
|
||||
|
||||
### Created Files
|
||||
|
||||
2. **`.claude/skills/frontend-design/UI_VALIDATION_CHECKLIST.md`** (NEW)
|
||||
- 8 validation categories
|
||||
- 200+ checkpoint items
|
||||
- 3 validation workflows
|
||||
- Report formats
|
||||
- Common issues guide
|
||||
|
||||
3. **`.claude/skills/frontend-design/AUTOMATIC_VALIDATION_ENHANCEMENT.md`** (NEW - this file)
|
||||
- Enhancement documentation
|
||||
- Usage guide
|
||||
- Benefits and metrics
|
||||
- Integration details
|
||||
|
||||
---
|
||||
|
||||
## Configuration
|
||||
|
||||
**No configuration needed.** The frontend-design skill now has automatic invocation built into its guidelines.
|
||||
|
||||
**Skill Location:** `.claude/skills/frontend-design/`
|
||||
|
||||
**Verify Skill Available:**
|
||||
```bash
|
||||
# Check skill exists
|
||||
ls .claude/skills/frontend-design/SKILL.md
|
||||
|
||||
# View skill metadata
|
||||
head -n 10 .claude/skills/frontend-design/SKILL.md
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Success Metrics
|
||||
|
||||
Track these to validate enhancement effectiveness:
|
||||
|
||||
### Quality Metrics
|
||||
- **UI bugs caught pre-release** - Should increase
|
||||
- **Accessibility violations** - Should decrease to near zero
|
||||
- **QA rejection rate** - Should decrease
|
||||
- **User-reported UI issues** - Should decrease
|
||||
|
||||
### Process Metrics
|
||||
- **Time to fix UI issues** - Faster (caught earlier)
|
||||
- **Rework cycles** - Fewer (issues caught first time)
|
||||
- **Validation coverage** - Higher (automatic invocation)
|
||||
|
||||
### User Satisfaction
|
||||
- **Designer feedback** - Better alignment with designs
|
||||
- **User feedback** - Fewer UI complaints
|
||||
- **Accessibility compliance** - WCAG AA or higher
|
||||
|
||||
---
|
||||
|
||||
## Testing Recommendations
|
||||
|
||||
### Test Scenario 1: Simple CSS Change
|
||||
|
||||
```
|
||||
User: "Make the button text bold"
|
||||
Expected: Quick validation (1-2 min), PASS report
|
||||
```
|
||||
|
||||
### Test Scenario 2: New Component
|
||||
|
||||
```
|
||||
User: "Create a card component with image, title, and description"
|
||||
Expected: Standard validation (3-5 min), comprehensive report
|
||||
```
|
||||
|
||||
### Test Scenario 3: Broken Layout
|
||||
|
||||
```
|
||||
User: "Add flexbox to the grid layout"
|
||||
[Code has error that breaks layout]
|
||||
Expected: Comprehensive validation, ERROR report with fixes
|
||||
```
|
||||
|
||||
### Test Scenario 4: Accessibility Issue
|
||||
|
||||
```
|
||||
User: "Add icon-only buttons to the toolbar"
|
||||
[Code missing ARIA labels]
|
||||
Expected: BLOCK report for accessibility violations
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Future Enhancements
|
||||
|
||||
Potential improvements:
|
||||
|
||||
1. **Automated Screenshot Capture**
|
||||
- Take screenshots at key breakpoints
|
||||
- Visual regression testing
|
||||
- Before/after comparisons
|
||||
|
||||
2. **Lighthouse Integration**
|
||||
- Automatic Lighthouse audits
|
||||
- Performance scoring
|
||||
- Accessibility scoring
|
||||
|
||||
3. **Design Token Validation**
|
||||
- Verify CSS variables used correctly
|
||||
- Check against design system
|
||||
- Flag hardcoded values
|
||||
|
||||
4. **AI-Powered Visual Comparison**
|
||||
- Compare to design mockups
|
||||
- Detect visual differences
|
||||
- Flag unexpected changes
|
||||
|
||||
5. **Validation Metrics Dashboard**
|
||||
- Track validation pass/fail rates
|
||||
- Common issues trending
|
||||
- Team performance metrics
|
||||
|
||||
---
|
||||
|
||||
## Rollback
|
||||
|
||||
If needed, revert to previous version:
|
||||
|
||||
```bash
|
||||
git diff HEAD~1 .claude/skills/frontend-design/SKILL.md
|
||||
git checkout HEAD~1 .claude/skills/frontend-design/SKILL.md
|
||||
```
|
||||
|
||||
**Note:** Keep checklist and enhancement docs for future reference.
|
||||
|
||||
---
|
||||
|
||||
## Related Files
|
||||
|
||||
- **Skill Config:** `.claude/skills/frontend-design/SKILL.md`
|
||||
- **Validation Checklist:** `.claude/skills/frontend-design/UI_VALIDATION_CHECKLIST.md`
|
||||
- **Code Review Agent:** `.claude/agents/code-review.md`
|
||||
- **Testing Agent:** `.claude/agents/testing.md`
|
||||
- **Coding Guidelines:** `.claude/CODING_GUIDELINES.md`
|
||||
|
||||
---
|
||||
|
||||
**Last Updated:** 2026-01-17
|
||||
**Status:** COMPLETED & READY FOR USE
|
||||
**Enhanced By:** Claude Code
|
||||
**User Requirement:** "Any time any action affects a UI item, call frontend to validate the UI is working/appearing/behaving correctly."
|
||||
177
.claude/skills/frontend-design/LICENSE.txt
Normal file
177
.claude/skills/frontend-design/LICENSE.txt
Normal file
@@ -0,0 +1,177 @@
|
||||
|
||||
Apache License
|
||||
Version 2.0, January 2004
|
||||
http://www.apache.org/licenses/
|
||||
|
||||
TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
|
||||
|
||||
1. Definitions.
|
||||
|
||||
"License" shall mean the terms and conditions for use, reproduction,
|
||||
and distribution as defined by Sections 1 through 9 of this document.
|
||||
|
||||
"Licensor" shall mean the copyright owner or entity authorized by
|
||||
the copyright owner that is granting the License.
|
||||
|
||||
"Legal Entity" shall mean the union of the acting entity and all
|
||||
other entities that control, are controlled by, or are under common
|
||||
control with that entity. For the purposes of this definition,
|
||||
"control" means (i) the power, direct or indirect, to cause the
|
||||
direction or management of such entity, whether by contract or
|
||||
otherwise, or (ii) ownership of fifty percent (50%) or more of the
|
||||
outstanding shares, or (iii) beneficial ownership of such entity.
|
||||
|
||||
"You" (or "Your") shall mean an individual or Legal Entity
|
||||
exercising permissions granted by this License.
|
||||
|
||||
"Source" form shall mean the preferred form for making modifications,
|
||||
including but not limited to software source code, documentation
|
||||
source, and configuration files.
|
||||
|
||||
"Object" form shall mean any form resulting from mechanical
|
||||
transformation or translation of a Source form, including but
|
||||
not limited to compiled object code, generated documentation,
|
||||
and conversions to other media types.
|
||||
|
||||
"Work" shall mean the work of authorship, whether in Source or
|
||||
Object form, made available under the License, as indicated by a
|
||||
copyright notice that is included in or attached to the work
|
||||
(an example is provided in the Appendix below).
|
||||
|
||||
"Derivative Works" shall mean any work, whether in Source or Object
|
||||
form, that is based on (or derived from) the Work and for which the
|
||||
editorial revisions, annotations, elaborations, or other modifications
|
||||
represent, as a whole, an original work of authorship. For the purposes
|
||||
of this License, Derivative Works shall not include works that remain
|
||||
separable from, or merely link (or bind by name) to the interfaces of,
|
||||
the Work and Derivative Works thereof.
|
||||
|
||||
"Contribution" shall mean any work of authorship, including
|
||||
the original version of the Work and any modifications or additions
|
||||
to that Work or Derivative Works thereof, that is intentionally
|
||||
submitted to Licensor for inclusion in the Work by the copyright owner
|
||||
or by an individual or Legal Entity authorized to submit on behalf of
|
||||
the copyright owner. For the purposes of this definition, "submitted"
|
||||
means any form of electronic, verbal, or written communication sent
|
||||
to the Licensor or its representatives, including but not limited to
|
||||
communication on electronic mailing lists, source code control systems,
|
||||
and issue tracking systems that are managed by, or on behalf of, the
|
||||
Licensor for the purpose of discussing and improving the Work, but
|
||||
excluding communication that is conspicuously marked or otherwise
|
||||
designated in writing by the copyright owner as "Not a Contribution."
|
||||
|
||||
"Contributor" shall mean Licensor and any individual or Legal Entity
|
||||
on behalf of whom a Contribution has been received by Licensor and
|
||||
subsequently incorporated within the Work.
|
||||
|
||||
2. Grant of Copyright License. Subject to the terms and conditions of
|
||||
this License, each Contributor hereby grants to You a perpetual,
|
||||
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
|
||||
copyright license to reproduce, prepare Derivative Works of,
|
||||
publicly display, publicly perform, sublicense, and distribute the
|
||||
Work and such Derivative Works in Source or Object form.
|
||||
|
||||
3. Grant of Patent License. Subject to the terms and conditions of
|
||||
this License, each Contributor hereby grants to You a perpetual,
|
||||
worldwide, non-exclusive, no-charge, royalty-free, irrevocable
|
||||
(except as stated in this section) patent license to make, have made,
|
||||
use, offer to sell, sell, import, and otherwise transfer the Work,
|
||||
where such license applies only to those patent claims licensable
|
||||
by such Contributor that are necessarily infringed by their
|
||||
Contribution(s) alone or by combination of their Contribution(s)
|
||||
with the Work to which such Contribution(s) was submitted. If You
|
||||
institute patent litigation against any entity (including a
|
||||
cross-claim or counterclaim in a lawsuit) alleging that the Work
|
||||
or a Contribution incorporated within the Work constitutes direct
|
||||
or contributory patent infringement, then any patent licenses
|
||||
granted to You under this License for that Work shall terminate
|
||||
as of the date such litigation is filed.
|
||||
|
||||
4. Redistribution. You may reproduce and distribute copies of the
|
||||
Work or Derivative Works thereof in any medium, with or without
|
||||
modifications, and in Source or Object form, provided that You
|
||||
meet the following conditions:
|
||||
|
||||
(a) You must give any other recipients of the Work or
|
||||
Derivative Works a copy of this License; and
|
||||
|
||||
(b) You must cause any modified files to carry prominent notices
|
||||
stating that You changed the files; and
|
||||
|
||||
(c) You must retain, in the Source form of any Derivative Works
|
||||
that You distribute, all copyright, patent, trademark, and
|
||||
attribution notices from the Source form of the Work,
|
||||
excluding those notices that do not pertain to any part of
|
||||
the Derivative Works; and
|
||||
|
||||
(d) If the Work includes a "NOTICE" text file as part of its
|
||||
distribution, then any Derivative Works that You distribute must
|
||||
include a readable copy of the attribution notices contained
|
||||
within such NOTICE file, excluding those notices that do not
|
||||
pertain to any part of the Derivative Works, in at least one
|
||||
of the following places: within a NOTICE text file distributed
|
||||
as part of the Derivative Works; within the Source form or
|
||||
documentation, if provided along with the Derivative Works; or,
|
||||
within a display generated by the Derivative Works, if and
|
||||
wherever such third-party notices normally appear. The contents
|
||||
of the NOTICE file are for informational purposes only and
|
||||
do not modify the License. You may add Your own attribution
|
||||
notices within Derivative Works that You distribute, alongside
|
||||
or as an addendum to the NOTICE text from the Work, provided
|
||||
that such additional attribution notices cannot be construed
|
||||
as modifying the License.
|
||||
|
||||
You may add Your own copyright statement to Your modifications and
|
||||
may provide additional or different license terms and conditions
|
||||
for use, reproduction, or distribution of Your modifications, or
|
||||
for any such Derivative Works as a whole, provided Your use,
|
||||
reproduction, and distribution of the Work otherwise complies with
|
||||
the conditions stated in this License.
|
||||
|
||||
5. Submission of Contributions. Unless You explicitly state otherwise,
|
||||
any Contribution intentionally submitted for inclusion in the Work
|
||||
by You to the Licensor shall be under the terms and conditions of
|
||||
this License, without any additional terms or conditions.
|
||||
Notwithstanding the above, nothing herein shall supersede or modify
|
||||
the terms of any separate license agreement you may have executed
|
||||
with Licensor regarding such Contributions.
|
||||
|
||||
6. Trademarks. This License does not grant permission to use the trade
|
||||
names, trademarks, service marks, or product names of the Licensor,
|
||||
except as required for reasonable and customary use in describing the
|
||||
origin of the Work and reproducing the content of the NOTICE file.
|
||||
|
||||
7. Disclaimer of Warranty. Unless required by applicable law or
|
||||
agreed to in writing, Licensor provides the Work (and each
|
||||
Contributor provides its Contributions) on an "AS IS" BASIS,
|
||||
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
|
||||
implied, including, without limitation, any warranties or conditions
|
||||
of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
|
||||
PARTICULAR PURPOSE. You are solely responsible for determining the
|
||||
appropriateness of using or redistributing the Work and assume any
|
||||
risks associated with Your exercise of permissions under this License.
|
||||
|
||||
8. Limitation of Liability. In no event and under no legal theory,
|
||||
whether in tort (including negligence), contract, or otherwise,
|
||||
unless required by applicable law (such as deliberate and grossly
|
||||
negligent acts) or agreed to in writing, shall any Contributor be
|
||||
liable to You for damages, including any direct, indirect, special,
|
||||
incidental, or consequential damages of any character arising as a
|
||||
result of this License or out of the use or inability to use the
|
||||
Work (including but not limited to damages for loss of goodwill,
|
||||
work stoppage, computer failure or malfunction, or any and all
|
||||
other commercial damages or losses), even if such Contributor
|
||||
has been advised of the possibility of such damages.
|
||||
|
||||
9. Accepting Warranty or Additional Liability. While redistributing
|
||||
the Work or Derivative Works thereof, You may choose to offer,
|
||||
and charge a fee for, acceptance of support, warranty, indemnity,
|
||||
or other liability obligations and/or rights consistent with this
|
||||
License. However, in accepting such obligations, You may act only
|
||||
on Your own behalf and on Your sole responsibility, not on behalf
|
||||
of any other Contributor, and only if You agree to indemnify,
|
||||
defend, and hold each Contributor harmless for any liability
|
||||
incurred by, or claims asserted against, such Contributor by reason
|
||||
of your accepting any such warranty or additional liability.
|
||||
|
||||
END OF TERMS AND CONDITIONS
|
||||
163
.claude/skills/frontend-design/SKILL.md
Normal file
163
.claude/skills/frontend-design/SKILL.md
Normal file
@@ -0,0 +1,163 @@
|
||||
---
|
||||
name: frontend-design
|
||||
description: Create distinctive, production-grade frontend interfaces with high design quality. MANDATORY AUTOMATIC INVOCATION: Use this skill whenever ANY action affects a UI element to validate visual correctness, functionality, and user experience. Also use when the user asks to build web components, pages, artifacts, posters, or applications (examples include websites, landing pages, dashboards, React components, HTML/CSS layouts, or when styling/beautifying any web UI). Generates creative, polished code and UI design that avoids generic AI aesthetics.
|
||||
license: Complete terms in LICENSE.txt
|
||||
---
|
||||
|
||||
This skill guides creation of distinctive, production-grade frontend interfaces that avoid generic "AI slop" aesthetics. Implement real working code with exceptional attention to aesthetic details and creative choices.
|
||||
|
||||
The user provides frontend requirements: a component, page, application, or interface to build. They may include context about the purpose, audience, or technical constraints.
|
||||
|
||||
## CRITICAL: Automatic Invocation Triggers
|
||||
|
||||
**This skill MUST be invoked automatically whenever ANY action affects a UI element.**
|
||||
|
||||
### When to Invoke This Skill
|
||||
|
||||
**MANDATORY Triggers - Invoke this skill for:**
|
||||
|
||||
1. **UI Creation**
|
||||
- Creating new web pages, components, or interfaces
|
||||
- Building dashboards, forms, or layouts
|
||||
- Designing landing pages or marketing sites
|
||||
- Generating HTML/CSS/React/Vue code
|
||||
|
||||
2. **UI Modification**
|
||||
- Changing styles, colors, fonts, or layouts
|
||||
- Updating component appearance or behavior
|
||||
- Refactoring frontend code
|
||||
- Adding animations or interactions
|
||||
|
||||
3. **UI Validation (CRITICAL)**
|
||||
- **After ANY code change that affects UI**
|
||||
- After updating styles or markup
|
||||
- After adding features to UI components
|
||||
- After refactoring frontend code
|
||||
- After fixing UI bugs
|
||||
|
||||
### Purpose of Automatic Invocation
|
||||
|
||||
**When invoked for validation, this skill:**
|
||||
|
||||
1. **Verifies Visual Correctness**
|
||||
- Layout renders as expected
|
||||
- Spacing and alignment are correct
|
||||
- Colors and fonts display properly
|
||||
- Responsive behavior works
|
||||
|
||||
2. **Checks Functionality**
|
||||
- Interactive elements work (buttons, forms, links)
|
||||
- Animations trigger correctly
|
||||
- State changes reflect visually
|
||||
- Event handlers fire properly
|
||||
|
||||
3. **Validates User Experience**
|
||||
- Navigation flows logically
|
||||
- Feedback is clear (hover states, loading indicators)
|
||||
- Accessibility features work
|
||||
- Mobile/responsive layout functions
|
||||
|
||||
4. **Ensures Design Quality**
|
||||
- Visual hierarchy is clear
|
||||
- Aesthetic direction is maintained
|
||||
- No generic AI patterns introduced
|
||||
- Polished, production-ready appearance
|
||||
|
||||
### Validation Workflow
|
||||
|
||||
When invoked for UI validation after changes:
|
||||
|
||||
```markdown
|
||||
1. REVIEW: What UI elements were changed?
|
||||
2. ASSESS: How should they appear/behave?
|
||||
3. VALIDATE:
|
||||
- Visual appearance (layout, colors, fonts, spacing)
|
||||
- Interactive behavior (hover, click, focus states)
|
||||
- Responsive behavior (mobile, tablet, desktop)
|
||||
- Accessibility (keyboard nav, screen readers)
|
||||
4. REPORT:
|
||||
- [OK] Working correctly
|
||||
- [WARNING] Minor issues detected
|
||||
- [ERROR] Critical issues found
|
||||
5. FIX: If issues found, provide corrected code
|
||||
```
|
||||
|
||||
### Examples of Automatic Invocation
|
||||
|
||||
**Example 1: After Adding Button**
|
||||
```
|
||||
User: "Add a submit button to the form"
|
||||
Assistant: [Adds button code]
|
||||
→ TRIGGER: Invoke frontend-design skill
|
||||
→ VALIDATE: Button appears correctly, hover states work, accessible
|
||||
→ REPORT: "[OK] Submit button added and validated"
|
||||
```
|
||||
|
||||
**Example 2: After Styling Update**
|
||||
```
|
||||
User: "Change the header background to blue"
|
||||
Assistant: [Updates CSS]
|
||||
→ TRIGGER: Invoke frontend-design skill
|
||||
→ VALIDATE: Blue renders correctly, contrast is readable, responsive
|
||||
→ REPORT: "[OK] Header background updated and validated"
|
||||
```
|
||||
|
||||
**Example 3: After Component Refactor**
|
||||
```
|
||||
User: "Refactor the navigation component"
|
||||
Assistant: [Refactors code]
|
||||
→ TRIGGER: Invoke frontend-design skill
|
||||
→ VALIDATE: Navigation still works, styles intact, mobile menu functions
|
||||
→ REPORT: "[OK] Navigation refactored and validated" OR "[WARNING] Mobile menu broken - fixing..."
|
||||
```
|
||||
|
||||
### Integration with Other Agents
|
||||
|
||||
**Coordination with Code Review Agent:**
|
||||
- Code Review Agent checks code quality/security
|
||||
- Frontend Skill checks visual/UX correctness
|
||||
- Both must approve before UI changes are final
|
||||
|
||||
**Coordination with Testing Agent:**
|
||||
- Testing Agent runs automated tests
|
||||
- Frontend Skill validates visual/UX manually
|
||||
- Complementary validation approaches
|
||||
|
||||
### Rule of Thumb
|
||||
|
||||
**If the change appears in a browser, invoke this skill to validate it.**
|
||||
|
||||
---
|
||||
|
||||
## Design Thinking
|
||||
|
||||
Before coding, understand the context and commit to a BOLD aesthetic direction:
|
||||
- **Purpose**: What problem does this interface solve? Who uses it?
|
||||
- **Tone**: Pick an extreme: brutally minimal, maximalist chaos, retro-futuristic, organic/natural, luxury/refined, playful/toy-like, editorial/magazine, brutalist/raw, art deco/geometric, soft/pastel, industrial/utilitarian, etc. There are so many flavors to choose from. Use these for inspiration but design one that is true to the aesthetic direction.
|
||||
- **Constraints**: Technical requirements (framework, performance, accessibility).
|
||||
- **Differentiation**: What makes this UNFORGETTABLE? What's the one thing someone will remember?
|
||||
|
||||
**CRITICAL**: Choose a clear conceptual direction and execute it with precision. Bold maximalism and refined minimalism both work - the key is intentionality, not intensity.
|
||||
|
||||
Then implement working code (HTML/CSS/JS, React, Vue, etc.) that is:
|
||||
- Production-grade and functional
|
||||
- Visually striking and memorable
|
||||
- Cohesive with a clear aesthetic point-of-view
|
||||
- Meticulously refined in every detail
|
||||
|
||||
## Frontend Aesthetics Guidelines
|
||||
|
||||
Focus on:
|
||||
- **Typography**: Choose fonts that are beautiful, unique, and interesting. Avoid generic fonts like Arial and Inter; opt instead for distinctive choices that elevate the frontend's aesthetics; unexpected, characterful font choices. Pair a distinctive display font with a refined body font.
|
||||
- **Color & Theme**: Commit to a cohesive aesthetic. Use CSS variables for consistency. Dominant colors with sharp accents outperform timid, evenly-distributed palettes.
|
||||
- **Motion**: Use animations for effects and micro-interactions. Prioritize CSS-only solutions for HTML. Use Motion library for React when available. Focus on high-impact moments: one well-orchestrated page load with staggered reveals (animation-delay) creates more delight than scattered micro-interactions. Use scroll-triggering and hover states that surprise.
|
||||
- **Spatial Composition**: Unexpected layouts. Asymmetry. Overlap. Diagonal flow. Grid-breaking elements. Generous negative space OR controlled density.
|
||||
- **Backgrounds & Visual Details**: Create atmosphere and depth rather than defaulting to solid colors. Add contextual effects and textures that match the overall aesthetic. Apply creative forms like gradient meshes, noise textures, geometric patterns, layered transparencies, dramatic shadows, decorative borders, custom cursors, and grain overlays.
|
||||
|
||||
NEVER use generic AI-generated aesthetics like overused font families (Inter, Roboto, Arial, system fonts), cliched color schemes (particularly purple gradients on white backgrounds), predictable layouts and component patterns, and cookie-cutter design that lacks context-specific character.
|
||||
|
||||
Interpret creatively and make unexpected choices that feel genuinely designed for the context. No design should be the same. Vary between light and dark themes, different fonts, different aesthetics. NEVER converge on common choices (Space Grotesk, for example) across generations.
|
||||
|
||||
**IMPORTANT**: Match implementation complexity to the aesthetic vision. Maximalist designs need elaborate code with extensive animations and effects. Minimalist or refined designs need restraint, precision, and careful attention to spacing, typography, and subtle details. Elegance comes from executing the vision well.
|
||||
|
||||
Remember: Claude is capable of extraordinary creative work. Don't hold back, show what can truly be created when thinking outside the box and committing fully to a distinctive vision.
|
||||
462
.claude/skills/frontend-design/UI_VALIDATION_CHECKLIST.md
Normal file
462
.claude/skills/frontend-design/UI_VALIDATION_CHECKLIST.md
Normal file
@@ -0,0 +1,462 @@
|
||||
# Frontend UI Validation Checklist
|
||||
|
||||
**Purpose:** Use this checklist when frontend-design skill is invoked to validate UI changes.
|
||||
|
||||
**Last Updated:** 2026-01-17
|
||||
|
||||
---
|
||||
|
||||
## When to Use This Checklist
|
||||
|
||||
**MANDATORY:** After ANY code change that affects UI elements:
|
||||
- Creating new UI components
|
||||
- Modifying existing styles or markup
|
||||
- Adding features to frontend code
|
||||
- Refactoring frontend components
|
||||
- Fixing UI bugs
|
||||
|
||||
---
|
||||
|
||||
## Validation Categories
|
||||
|
||||
### 1. Visual Appearance
|
||||
|
||||
**Layout & Structure:**
|
||||
- [ ] Elements render in correct positions
|
||||
- [ ] Grid/flexbox layouts work as expected
|
||||
- [ ] Z-index stacking is correct
|
||||
- [ ] No unexpected overlaps or gaps
|
||||
- [ ] Aspect ratios are maintained
|
||||
- [ ] Images load and display correctly
|
||||
|
||||
**Typography:**
|
||||
- [ ] Fonts load and display correctly
|
||||
- [ ] Font sizes are appropriate (readability)
|
||||
- [ ] Line height provides good readability
|
||||
- [ ] Text alignment is intentional
|
||||
- [ ] No text overflow or truncation issues
|
||||
- [ ] Headings have proper hierarchy
|
||||
|
||||
**Colors & Contrast:**
|
||||
- [ ] Colors match design specifications
|
||||
- [ ] Sufficient contrast for readability (WCAG AA minimum)
|
||||
- [ ] Color themes (light/dark) work correctly
|
||||
- [ ] CSS variables applied consistently
|
||||
- [ ] Gradients render smoothly
|
||||
- [ ] Transparency/opacity levels correct
|
||||
|
||||
**Spacing & Rhythm:**
|
||||
- [ ] Padding is consistent and intentional
|
||||
- [ ] Margins create proper visual separation
|
||||
- [ ] Whitespace enhances readability
|
||||
- [ ] Vertical rhythm is maintained
|
||||
- [ ] No cramped or overly sparse areas
|
||||
- [ ] Spacing scales appropriately
|
||||
|
||||
**Visual Effects:**
|
||||
- [ ] Shadows render correctly (no performance issues)
|
||||
- [ ] Border-radius values are consistent
|
||||
- [ ] Background images/patterns display properly
|
||||
- [ ] Filters (blur, grayscale, etc.) work as expected
|
||||
- [ ] Decorative elements enhance, don't distract
|
||||
- [ ] No visual glitches or rendering artifacts
|
||||
|
||||
---
|
||||
|
||||
### 2. Interactive Behavior
|
||||
|
||||
**Click/Tap Interactions:**
|
||||
- [ ] Buttons respond to clicks
|
||||
- [ ] Links navigate correctly
|
||||
- [ ] Forms submit properly
|
||||
- [ ] Checkboxes/radios toggle
|
||||
- [ ] Dropdowns open/close
|
||||
- [ ] Click targets are appropriately sized (minimum 44x44px)
|
||||
|
||||
**Hover States:**
|
||||
- [ ] Hover effects trigger on desktop
|
||||
- [ ] Cursor changes appropriately (pointer, text, etc.)
|
||||
- [ ] Visual feedback is clear
|
||||
- [ ] Transitions are smooth
|
||||
- [ ] No flickering or jank
|
||||
- [ ] Tooltips appear when expected
|
||||
|
||||
**Focus States:**
|
||||
- [ ] Focus indicators visible (keyboard navigation)
|
||||
- [ ] Focus order is logical
|
||||
- [ ] Focus trap works in modals/dialogs
|
||||
- [ ] Skip links function correctly
|
||||
- [ ] Focus doesn't get lost
|
||||
- [ ] Custom focus styles meet contrast requirements
|
||||
|
||||
**Active States:**
|
||||
- [ ] Pressed/active states provide feedback
|
||||
- [ ] Buttons show active state during click
|
||||
- [ ] Form inputs show active state when selected
|
||||
- [ ] Loading states appear during async operations
|
||||
|
||||
**Disabled States:**
|
||||
- [ ] Disabled elements are visually distinct
|
||||
- [ ] Disabled elements don't respond to interaction
|
||||
- [ ] Cursor indicates disabled state
|
||||
- [ ] Tooltips explain why disabled (if applicable)
|
||||
|
||||
---
|
||||
|
||||
### 3. Responsive Behavior
|
||||
|
||||
**Breakpoints:**
|
||||
- [ ] Desktop (1920px+) layout works
|
||||
- [ ] Laptop (1366px-1919px) layout works
|
||||
- [ ] Tablet landscape (1024px-1365px) layout works
|
||||
- [ ] Tablet portrait (768px-1023px) layout works
|
||||
- [ ] Mobile landscape (568px-767px) layout works
|
||||
- [ ] Mobile portrait (320px-567px) layout works
|
||||
|
||||
**Adaptive Layout:**
|
||||
- [ ] Content reflows appropriately
|
||||
- [ ] No horizontal scrolling (unless intentional)
|
||||
- [ ] Touch targets are finger-sized on mobile (44x44px min)
|
||||
- [ ] Navigation adapts (hamburger menu, etc.)
|
||||
- [ ] Images scale/crop appropriately
|
||||
- [ ] Text remains readable at all sizes
|
||||
|
||||
**Responsive Typography:**
|
||||
- [ ] Font sizes scale appropriately
|
||||
- [ ] Line length stays readable (45-75 characters)
|
||||
- [ ] Headings scale proportionally
|
||||
- [ ] No text overflow at any breakpoint
|
||||
|
||||
**Mobile-Specific:**
|
||||
- [ ] Touch gestures work (swipe, pinch, etc.)
|
||||
- [ ] No hover-dependent interactions
|
||||
- [ ] Virtual keyboard doesn't obscure inputs
|
||||
- [ ] Mobile browser chrome accounted for
|
||||
- [ ] Fixed elements don't interfere with scrolling
|
||||
|
||||
---
|
||||
|
||||
### 4. Animations & Transitions
|
||||
|
||||
**Animation Quality:**
|
||||
- [ ] Animations run smoothly (60fps)
|
||||
- [ ] No janky or stuttering motion
|
||||
- [ ] Timing feels natural (not too slow/fast)
|
||||
- [ ] Easing curves are appropriate
|
||||
- [ ] Animation-delay creates stagger effect (if intended)
|
||||
|
||||
**Performance:**
|
||||
- [ ] Animations use transform/opacity (GPU-accelerated)
|
||||
- [ ] No layout thrashing
|
||||
- [ ] Will-change used appropriately (if needed)
|
||||
- [ ] Animations don't block interactions
|
||||
- [ ] Reduce motion preference respected
|
||||
|
||||
**Transition States:**
|
||||
- [ ] Enter animations work
|
||||
- [ ] Exit animations work
|
||||
- [ ] State transitions are smooth
|
||||
- [ ] Loading spinners/skeletons appear
|
||||
- [ ] No flash of unstyled content (FOUC)
|
||||
|
||||
**Scroll Animations:**
|
||||
- [ ] Scroll-triggered animations fire correctly
|
||||
- [ ] Parallax effects are subtle, not nauseating
|
||||
- [ ] Sticky elements stick at right position
|
||||
- [ ] Scroll progress indicators update
|
||||
- [ ] Smooth scroll behavior works
|
||||
|
||||
---
|
||||
|
||||
### 5. Accessibility
|
||||
|
||||
**Keyboard Navigation:**
|
||||
- [ ] All interactive elements are keyboard accessible
|
||||
- [ ] Tab order is logical
|
||||
- [ ] Enter/Space activate buttons/links
|
||||
- [ ] Escape closes modals/dropdowns
|
||||
- [ ] Arrow keys navigate menus/lists (if applicable)
|
||||
- [ ] No keyboard traps
|
||||
|
||||
**Screen Reader Support:**
|
||||
- [ ] Semantic HTML used (header, nav, main, article, etc.)
|
||||
- [ ] ARIA labels on icons/buttons without text
|
||||
- [ ] ARIA live regions for dynamic content
|
||||
- [ ] Form inputs have associated labels
|
||||
- [ ] Error messages are announced
|
||||
- [ ] Skip links present
|
||||
|
||||
**Visual Accessibility:**
|
||||
- [ ] Color contrast meets WCAG AA (4.5:1 text, 3:1 UI)
|
||||
- [ ] Color isn't the only indicator (use icons/text too)
|
||||
- [ ] Focus indicators are highly visible
|
||||
- [ ] Text can be resized to 200% without breaking layout
|
||||
- [ ] No content hidden by fixed elements
|
||||
|
||||
**Alternative Content:**
|
||||
- [ ] Images have descriptive alt text
|
||||
- [ ] Decorative images have empty alt=""
|
||||
- [ ] Icons have labels or tooltips
|
||||
- [ ] Videos have captions/transcripts
|
||||
- [ ] Complex graphics have text alternatives
|
||||
|
||||
---
|
||||
|
||||
### 6. Performance
|
||||
|
||||
**Load Performance:**
|
||||
- [ ] Critical CSS inlined (if applicable)
|
||||
- [ ] Fonts load efficiently (font-display: swap)
|
||||
- [ ] Images lazy-loaded (below fold)
|
||||
- [ ] No render-blocking resources
|
||||
- [ ] First contentful paint is fast (<2s)
|
||||
|
||||
**Runtime Performance:**
|
||||
- [ ] No layout shifts (CLS near 0)
|
||||
- [ ] Smooth scrolling (no jank)
|
||||
- [ ] Animations run at 60fps
|
||||
- [ ] No memory leaks
|
||||
- [ ] Event handlers don't block main thread
|
||||
|
||||
**Resource Optimization:**
|
||||
- [ ] Images optimized (WebP, compression)
|
||||
- [ ] CSS is minified (in production)
|
||||
- [ ] JavaScript is minified (in production)
|
||||
- [ ] Unused CSS removed
|
||||
- [ ] Critical resources preloaded
|
||||
|
||||
---
|
||||
|
||||
### 7. Cross-Browser Compatibility
|
||||
|
||||
**Modern Browsers:**
|
||||
- [ ] Chrome/Edge (latest)
|
||||
- [ ] Firefox (latest)
|
||||
- [ ] Safari (latest)
|
||||
- [ ] Mobile Safari (iOS)
|
||||
- [ ] Chrome Mobile (Android)
|
||||
|
||||
**Fallbacks:**
|
||||
- [ ] Graceful degradation for older browsers
|
||||
- [ ] Feature detection (not browser sniffing)
|
||||
- [ ] Polyfills loaded if needed
|
||||
- [ ] CSS fallbacks for modern features (grid, flexbox)
|
||||
- [ ] No JavaScript errors in console
|
||||
|
||||
---
|
||||
|
||||
### 8. Content & Copy
|
||||
|
||||
**Text Quality:**
|
||||
- [ ] No typos or grammatical errors
|
||||
- [ ] Placeholder text replaced with real content
|
||||
- [ ] Proper capitalization (title case, sentence case)
|
||||
- [ ] Consistent voice and tone
|
||||
- [ ] Microcopy is helpful and clear
|
||||
|
||||
**Internationalization:**
|
||||
- [ ] Text doesn't break layout in longer languages
|
||||
- [ ] RTL support if needed
|
||||
- [ ] Date/number formatting appropriate
|
||||
- [ ] No hardcoded strings (use i18n keys)
|
||||
|
||||
---
|
||||
|
||||
## Validation Workflow
|
||||
|
||||
### Quick Validation (Simple Changes)
|
||||
|
||||
For minor changes like color updates or spacing tweaks:
|
||||
|
||||
1. Visual check at 1-2 breakpoints
|
||||
2. Verify hover/focus states
|
||||
3. Quick accessibility scan
|
||||
4. Report: [OK] or [WARNING]
|
||||
|
||||
**Time:** 1-2 minutes
|
||||
|
||||
### Standard Validation (Component Changes)
|
||||
|
||||
For component modifications or feature additions:
|
||||
|
||||
1. Visual check at all breakpoints
|
||||
2. Test all interactive states
|
||||
3. Keyboard navigation test
|
||||
4. Basic performance check
|
||||
5. Report: [OK], [WARNING], or [ERROR]
|
||||
|
||||
**Time:** 3-5 minutes
|
||||
|
||||
### Comprehensive Validation (New Features)
|
||||
|
||||
For new components or major refactors:
|
||||
|
||||
1. Complete visual review (all categories above)
|
||||
2. Full interaction testing
|
||||
3. Cross-browser testing
|
||||
4. Accessibility audit
|
||||
5. Performance profiling
|
||||
6. Report: Detailed findings with fixes
|
||||
|
||||
**Time:** 10-15 minutes
|
||||
|
||||
---
|
||||
|
||||
## Validation Report Format
|
||||
|
||||
### Success Report
|
||||
|
||||
```markdown
|
||||
## UI Validation: PASSED
|
||||
|
||||
**Component:** [Component name]
|
||||
**Changes:** [Brief description]
|
||||
|
||||
**Validation Results:**
|
||||
- [OK] Visual appearance correct
|
||||
- [OK] Interactive behavior working
|
||||
- [OK] Responsive at all breakpoints
|
||||
- [OK] Accessibility requirements met
|
||||
|
||||
**Notes:** [Any observations or recommendations]
|
||||
```
|
||||
|
||||
### Warning Report
|
||||
|
||||
```markdown
|
||||
## UI Validation: WARNINGS
|
||||
|
||||
**Component:** [Component name]
|
||||
**Changes:** [Brief description]
|
||||
|
||||
**Validation Results:**
|
||||
- [OK] Visual appearance correct
|
||||
- [WARNING] Minor hover state issue detected
|
||||
- [OK] Responsive at all breakpoints
|
||||
- [OK] Accessibility requirements met
|
||||
|
||||
**Issues Found:**
|
||||
1. **Minor: Hover state transition**
|
||||
- **Problem:** Transition is too slow (500ms)
|
||||
- **Fix:** Reduce to 200ms for better UX
|
||||
- **Fixed:** Yes
|
||||
|
||||
**Status:** Issues resolved, ready to proceed
|
||||
```
|
||||
|
||||
### Error Report
|
||||
|
||||
```markdown
|
||||
## UI Validation: ERRORS
|
||||
|
||||
**Component:** [Component name]
|
||||
**Changes:** [Brief description]
|
||||
|
||||
**Validation Results:**
|
||||
- [OK] Visual appearance correct
|
||||
- [ERROR] Interactive behavior broken
|
||||
- [WARNING] Responsive issues on mobile
|
||||
- [ERROR] Accessibility violations
|
||||
|
||||
**Critical Issues:**
|
||||
1. **CRITICAL: Button click handler not working**
|
||||
- **Problem:** Event listener not attached
|
||||
- **Impact:** Form cannot be submitted
|
||||
- **Fix Required:** Add onClick handler
|
||||
|
||||
2. **CRITICAL: Missing keyboard accessibility**
|
||||
- **Problem:** Modal cannot be closed with Escape
|
||||
- **Impact:** Keyboard users trapped
|
||||
- **Fix Required:** Add keydown listener
|
||||
|
||||
**Status:** BLOCKED - fixes required before proceeding
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Common Issues to Watch For
|
||||
|
||||
### Layout Issues
|
||||
- Flexbox/grid container missing
|
||||
- Z-index conflicts
|
||||
- Overflow hidden cutting off content
|
||||
- Fixed positioning causing mobile issues
|
||||
|
||||
### Typography Issues
|
||||
- Font not loading (fallback showing)
|
||||
- Line-height too tight/loose
|
||||
- Text overflow not handled
|
||||
- Inconsistent font weights
|
||||
|
||||
### Color Issues
|
||||
- Insufficient contrast
|
||||
- Theme not applied consistently
|
||||
- CSS variable not defined
|
||||
- Color only indicator (accessibility)
|
||||
|
||||
### Interaction Issues
|
||||
- Event handler not attached
|
||||
- Hover state persisting on mobile
|
||||
- Focus outline removed without replacement
|
||||
- Click target too small
|
||||
|
||||
### Responsive Issues
|
||||
- Breakpoint gaps (768.5px edge cases)
|
||||
- Images not scaling
|
||||
- Text wrapping awkwardly
|
||||
- Mobile menu not working
|
||||
|
||||
### Animation Issues
|
||||
- Animating width/height (use transform)
|
||||
- No will-change on expensive animations
|
||||
- Animations running on page load (jarring)
|
||||
- Reduce motion not respected
|
||||
|
||||
### Accessibility Issues
|
||||
- Missing alt text
|
||||
- No keyboard focus indicators
|
||||
- Color contrast too low
|
||||
- ARIA labels missing
|
||||
|
||||
---
|
||||
|
||||
## Decision Matrix: Pass, Warn, or Block
|
||||
|
||||
### PASS - Approve Changes
|
||||
- All critical validations passed
|
||||
- No major issues detected
|
||||
- Minor observations noted but don't block
|
||||
- Ready for code review/testing
|
||||
|
||||
### WARN - Approve with Notes
|
||||
- Minor issues detected
|
||||
- Issues fixed during validation
|
||||
- Recommendations for improvement
|
||||
- Can proceed but note improvements
|
||||
|
||||
### BLOCK - Require Fixes
|
||||
- Critical functionality broken
|
||||
- Accessibility violations (WCAG A/AA)
|
||||
- Visual appearance significantly wrong
|
||||
- Responsive layout broken
|
||||
- Performance severely degraded
|
||||
|
||||
---
|
||||
|
||||
## Integration with Other Tools
|
||||
|
||||
**Works alongside:**
|
||||
- Code Review Agent (checks code quality)
|
||||
- Testing Agent (runs automated tests)
|
||||
- Browser DevTools (performance profiling)
|
||||
- Lighthouse (accessibility/performance audits)
|
||||
- Screen readers (NVDA, JAWS, VoiceOver)
|
||||
|
||||
**Reports to:**
|
||||
- Main Claude (coordination)
|
||||
- Code Review Agent (combined approval)
|
||||
- User (final validation)
|
||||
|
||||
---
|
||||
|
||||
**Remember:** This skill is invoked AUTOMATICALLY for ANY UI change. Quick validations keep velocity high while ensuring quality.
|
||||
331
.claude/templates/app_spec.template.txt
Normal file
331
.claude/templates/app_spec.template.txt
Normal file
@@ -0,0 +1,331 @@
|
||||
<!--
|
||||
Project Specification Template
|
||||
==============================
|
||||
|
||||
This is a placeholder template. Replace with your actual project specification.
|
||||
|
||||
You can either:
|
||||
1. Use the /create-spec command to generate this interactively with Claude
|
||||
2. Manually edit this file following the structure below
|
||||
|
||||
See existing projects in generations/ for examples of complete specifications.
|
||||
-->
|
||||
|
||||
<project_specification>
|
||||
<project_name>YOUR_PROJECT_NAME</project_name>
|
||||
|
||||
<overview>
|
||||
Describe your project in 2-3 sentences. What are you building? What problem
|
||||
does it solve? Who is it for? Include key features and design goals.
|
||||
</overview>
|
||||
|
||||
<technology_stack>
|
||||
<frontend>
|
||||
<framework>React with Vite</framework>
|
||||
<styling>Tailwind CSS</styling>
|
||||
<state_management>React hooks and context</state_management>
|
||||
<routing>React Router for navigation</routing>
|
||||
<port>3000</port>
|
||||
</frontend>
|
||||
<backend>
|
||||
<runtime>Node.js with Express</runtime>
|
||||
<database>SQLite with better-sqlite3</database>
|
||||
<port>3001</port>
|
||||
</backend>
|
||||
<communication>
|
||||
<api>RESTful endpoints</api>
|
||||
</communication>
|
||||
</technology_stack>
|
||||
|
||||
<prerequisites>
|
||||
<environment_setup>
|
||||
- Node.js 18+ installed
|
||||
- npm or pnpm package manager
|
||||
- Any API keys or external services needed
|
||||
</environment_setup>
|
||||
</prerequisites>
|
||||
|
||||
<core_features>
|
||||
<!--
|
||||
List features grouped by category. Each feature should be:
|
||||
- Specific and testable
|
||||
- Independent where possible
|
||||
- Written as a capability ("User can...", "System displays...")
|
||||
-->
|
||||
|
||||
<authentication>
|
||||
- User registration with email/password
|
||||
- User login with session management
|
||||
- User logout
|
||||
- Password reset flow
|
||||
- Profile management
|
||||
</authentication>
|
||||
|
||||
<main_functionality>
|
||||
<!-- Replace with your app's primary features -->
|
||||
- Create new items
|
||||
- View list of items with pagination
|
||||
- Edit existing items
|
||||
- Delete items with confirmation
|
||||
- Search and filter items
|
||||
</main_functionality>
|
||||
|
||||
<user_interface>
|
||||
- Responsive layout (mobile, tablet, desktop)
|
||||
- Dark/light theme toggle
|
||||
- Loading states and skeletons
|
||||
- Error handling with user feedback
|
||||
- Toast notifications for actions
|
||||
</user_interface>
|
||||
|
||||
<data_management>
|
||||
- Data validation on forms
|
||||
- Auto-save drafts
|
||||
- Export data functionality
|
||||
- Import data functionality
|
||||
</data_management>
|
||||
|
||||
<!-- Add more feature categories as needed -->
|
||||
</core_features>
|
||||
|
||||
<database_schema>
|
||||
<tables>
|
||||
<users>
|
||||
- id (PRIMARY KEY)
|
||||
- email (UNIQUE, NOT NULL)
|
||||
- password_hash (NOT NULL)
|
||||
- name
|
||||
- avatar_url
|
||||
- preferences (JSON)
|
||||
- created_at, updated_at
|
||||
</users>
|
||||
|
||||
<!-- Add more tables for your domain entities -->
|
||||
<items>
|
||||
- id (PRIMARY KEY)
|
||||
- user_id (FOREIGN KEY -> users.id)
|
||||
- title (NOT NULL)
|
||||
- description
|
||||
- status (enum: draft, active, archived)
|
||||
- created_at, updated_at
|
||||
</items>
|
||||
|
||||
<!-- Add additional tables as needed -->
|
||||
</tables>
|
||||
</database_schema>
|
||||
|
||||
<api_endpoints_summary>
|
||||
<authentication>
|
||||
- POST /api/auth/register
|
||||
- POST /api/auth/login
|
||||
- POST /api/auth/logout
|
||||
- GET /api/auth/me
|
||||
- PUT /api/auth/profile
|
||||
- POST /api/auth/forgot-password
|
||||
- POST /api/auth/reset-password
|
||||
</authentication>
|
||||
|
||||
<items>
|
||||
- GET /api/items (list with pagination, search, filters)
|
||||
- POST /api/items (create)
|
||||
- GET /api/items/:id (get single)
|
||||
- PUT /api/items/:id (update)
|
||||
- DELETE /api/items/:id (delete)
|
||||
</items>
|
||||
|
||||
<!-- Add more endpoint categories as needed -->
|
||||
</api_endpoints_summary>
|
||||
|
||||
<ui_layout>
|
||||
<main_structure>
|
||||
Describe the overall layout structure:
|
||||
- Header with navigation and user menu
|
||||
- Sidebar for navigation (collapsible on mobile)
|
||||
- Main content area
|
||||
- Footer (optional)
|
||||
</main_structure>
|
||||
|
||||
<sidebar>
|
||||
- Logo/brand at top
|
||||
- Navigation links
|
||||
- Quick actions
|
||||
- User profile at bottom
|
||||
</sidebar>
|
||||
|
||||
<main_content>
|
||||
- Page header with title and actions
|
||||
- Content area with cards/lists/forms
|
||||
- Pagination or infinite scroll
|
||||
</main_content>
|
||||
|
||||
<modals_overlays>
|
||||
- Confirmation dialogs
|
||||
- Form modals for create/edit
|
||||
- Settings modal
|
||||
- Help/keyboard shortcuts reference
|
||||
</modals_overlays>
|
||||
</ui_layout>
|
||||
|
||||
<design_system>
|
||||
<color_palette>
|
||||
- Primary: #3B82F6 (blue)
|
||||
- Secondary: #10B981 (green)
|
||||
- Accent: #F59E0B (amber)
|
||||
- Background: #FFFFFF (light), #1A1A1A (dark)
|
||||
- Surface: #F5F5F5 (light), #2A2A2A (dark)
|
||||
- Text: #1F2937 (light), #E5E5E5 (dark)
|
||||
- Border: #E5E5E5 (light), #404040 (dark)
|
||||
- Error: #EF4444
|
||||
- Success: #10B981
|
||||
- Warning: #F59E0B
|
||||
</color_palette>
|
||||
|
||||
<typography>
|
||||
- Font family: Inter, system-ui, -apple-system, sans-serif
|
||||
- Headings: font-semibold
|
||||
- Body: font-normal, leading-relaxed
|
||||
- Code: JetBrains Mono, Consolas, monospace
|
||||
</typography>
|
||||
|
||||
<components>
|
||||
<buttons>
|
||||
- Primary: colored background, white text, rounded
|
||||
- Secondary: border style, hover fill
|
||||
- Ghost: transparent, hover background
|
||||
- Icon buttons: square with hover state
|
||||
</buttons>
|
||||
|
||||
<inputs>
|
||||
- Rounded borders with focus ring
|
||||
- Clear placeholder text
|
||||
- Error states with red border
|
||||
- Disabled state styling
|
||||
</inputs>
|
||||
|
||||
<cards>
|
||||
- Subtle border or shadow
|
||||
- Rounded corners (8px)
|
||||
- Hover state for interactive cards
|
||||
</cards>
|
||||
</components>
|
||||
|
||||
<animations>
|
||||
- Smooth transitions (150-300ms)
|
||||
- Fade in for new content
|
||||
- Slide animations for modals/sidebars
|
||||
- Loading spinners
|
||||
- Skeleton loaders
|
||||
</animations>
|
||||
</design_system>
|
||||
|
||||
<key_interactions>
|
||||
<!-- Describe the main user flows -->
|
||||
<user_flow_1>
|
||||
1. User arrives at landing page
|
||||
2. Clicks "Get Started" or "Sign Up"
|
||||
3. Fills registration form
|
||||
4. Receives confirmation
|
||||
5. Redirected to main dashboard
|
||||
</user_flow_1>
|
||||
|
||||
<user_flow_2>
|
||||
1. User clicks "Create New"
|
||||
2. Form modal opens
|
||||
3. User fills in details
|
||||
4. Clicks save
|
||||
5. Item appears in list with success toast
|
||||
</user_flow_2>
|
||||
|
||||
<!-- Add more key interactions as needed -->
|
||||
</key_interactions>
|
||||
|
||||
<implementation_steps>
|
||||
<step number="1">
|
||||
<title>Project Setup and Database</title>
|
||||
<tasks>
|
||||
- Initialize frontend with Vite + React
|
||||
- Set up Express backend
|
||||
- Create SQLite database with schema
|
||||
- Configure CORS and middleware
|
||||
- Set up environment variables
|
||||
</tasks>
|
||||
</step>
|
||||
|
||||
<step number="2">
|
||||
<title>Authentication System</title>
|
||||
<tasks>
|
||||
- Implement user registration
|
||||
- Build login/logout flow
|
||||
- Add session management
|
||||
- Create protected routes
|
||||
- Build user profile page
|
||||
</tasks>
|
||||
</step>
|
||||
|
||||
<step number="3">
|
||||
<title>Core Features</title>
|
||||
<tasks>
|
||||
- Build main CRUD operations
|
||||
- Implement list views with pagination
|
||||
- Add search and filtering
|
||||
- Create form validation
|
||||
- Handle error states
|
||||
</tasks>
|
||||
</step>
|
||||
|
||||
<step number="4">
|
||||
<title>UI Polish and Responsiveness</title>
|
||||
<tasks>
|
||||
- Implement responsive design
|
||||
- Add dark/light theme
|
||||
- Create loading states
|
||||
- Add animations and transitions
|
||||
- Implement toast notifications
|
||||
</tasks>
|
||||
</step>
|
||||
|
||||
<step number="5">
|
||||
<title>Testing and Refinement</title>
|
||||
<tasks>
|
||||
- Test all user flows
|
||||
- Fix edge cases
|
||||
- Optimize performance
|
||||
- Ensure accessibility
|
||||
- Final UI polish
|
||||
</tasks>
|
||||
</step>
|
||||
</implementation_steps>
|
||||
|
||||
<success_criteria>
|
||||
<functionality>
|
||||
- All features work as specified
|
||||
- No console errors in browser
|
||||
- Proper error handling throughout
|
||||
- Data persists correctly in database
|
||||
</functionality>
|
||||
|
||||
<user_experience>
|
||||
- Intuitive navigation and workflows
|
||||
- Responsive on all device sizes
|
||||
- Fast load times (< 2s)
|
||||
- Clear feedback for all actions
|
||||
- Accessible (keyboard navigation, ARIA labels)
|
||||
</user_experience>
|
||||
|
||||
<technical_quality>
|
||||
- Clean, maintainable code structure
|
||||
- Consistent coding style
|
||||
- Proper separation of concerns
|
||||
- Secure authentication
|
||||
- Input validation and sanitization
|
||||
</technical_quality>
|
||||
|
||||
<design_polish>
|
||||
- Consistent visual design
|
||||
- Smooth animations
|
||||
- Professional appearance
|
||||
- Both themes fully implemented
|
||||
- No layout issues or overflow
|
||||
</design_polish>
|
||||
</success_criteria>
|
||||
</project_specification>
|
||||
443
.claude/templates/coding_prompt.template.md
Normal file
443
.claude/templates/coding_prompt.template.md
Normal file
@@ -0,0 +1,443 @@
|
||||
## YOUR ROLE - CODING AGENT
|
||||
|
||||
You are continuing work on a long-running autonomous development task.
|
||||
This is a FRESH context window - you have no memory of previous sessions.
|
||||
|
||||
### STEP 1: GET YOUR BEARINGS (MANDATORY)
|
||||
|
||||
Start by orienting yourself:
|
||||
|
||||
```bash
|
||||
# 1. See your working directory
|
||||
pwd
|
||||
|
||||
# 2. List files to understand project structure
|
||||
ls -la
|
||||
|
||||
# 3. Read the project specification to understand what you're building
|
||||
cat app_spec.txt
|
||||
|
||||
# 4. Read progress notes from previous sessions
|
||||
cat claude-progress.txt
|
||||
|
||||
# 5. Check recent git history
|
||||
git log --oneline -20
|
||||
```
|
||||
|
||||
Then use MCP tools to check feature status:
|
||||
|
||||
```
|
||||
# 6. Get progress statistics (passing/total counts)
|
||||
Use the feature_get_stats tool
|
||||
|
||||
# 7. Get the next feature to work on
|
||||
Use the feature_get_next tool
|
||||
```
|
||||
|
||||
Understanding the `app_spec.txt` is critical - it contains the full requirements
|
||||
for the application you're building.
|
||||
|
||||
### STEP 2: START SERVERS (IF NOT RUNNING)
|
||||
|
||||
If `init.sh` exists, run it:
|
||||
|
||||
```bash
|
||||
chmod +x init.sh
|
||||
./init.sh
|
||||
```
|
||||
|
||||
Otherwise, start servers manually and document the process.
|
||||
|
||||
### STEP 3: VERIFICATION TEST (CRITICAL!)
|
||||
|
||||
**MANDATORY BEFORE NEW WORK:**
|
||||
|
||||
The previous session may have introduced bugs. Before implementing anything
|
||||
new, you MUST run verification tests.
|
||||
|
||||
Run 1-2 of the features marked as passing that are most core to the app's functionality to verify they still work.
|
||||
|
||||
To get passing features for regression testing:
|
||||
|
||||
```
|
||||
Use the feature_get_for_regression tool (returns up to 3 random passing features)
|
||||
```
|
||||
|
||||
For example, if this were a chat app, you should perform a test that logs into the app, sends a message, and gets a response.
|
||||
|
||||
**If you find ANY issues (functional or visual):**
|
||||
|
||||
- Mark that feature as "passes": false immediately
|
||||
- Add issues to a list
|
||||
- Fix all issues BEFORE moving to new features
|
||||
- This includes UI bugs like:
|
||||
- White-on-white text or poor contrast
|
||||
- Random characters displayed
|
||||
- Incorrect timestamps
|
||||
- Layout issues or overflow
|
||||
- Buttons too close together
|
||||
- Missing hover states
|
||||
- Console errors
|
||||
|
||||
### STEP 4: CHOOSE ONE FEATURE TO IMPLEMENT
|
||||
|
||||
#### TEST-DRIVEN DEVELOPMENT MINDSET (CRITICAL)
|
||||
|
||||
Features are **test cases** that drive development. This is test-driven development:
|
||||
|
||||
- **If you can't test a feature because functionality doesn't exist → BUILD IT**
|
||||
- You are responsible for implementing ALL required functionality
|
||||
- Never assume another process will build it later
|
||||
- "Missing functionality" is NOT a blocker - it's your job to create it
|
||||
|
||||
**Example:** Feature says "User can filter flashcards by difficulty level"
|
||||
- WRONG: "Flashcard page doesn't exist yet" → skip feature
|
||||
- RIGHT: "Flashcard page doesn't exist yet" → build flashcard page → implement filter → test feature
|
||||
|
||||
Get the next feature to implement:
|
||||
|
||||
```
|
||||
# Get the highest-priority pending feature
|
||||
Use the feature_get_next tool
|
||||
```
|
||||
|
||||
Once you've retrieved the feature, **immediately mark it as in-progress**:
|
||||
|
||||
```
|
||||
# Mark feature as in-progress to prevent other sessions from working on it
|
||||
Use the feature_mark_in_progress tool with feature_id=42
|
||||
```
|
||||
|
||||
Focus on completing one feature perfectly and completing its testing steps in this session before moving on to other features.
|
||||
It's ok if you only complete one feature in this session, as there will be more sessions later that continue to make progress.
|
||||
|
||||
#### When to Skip a Feature (EXTREMELY RARE)
|
||||
|
||||
**Skipping should almost NEVER happen.** Only skip for truly external blockers you cannot control:
|
||||
|
||||
- **External API not configured**: Third-party service credentials missing (e.g., Stripe keys, OAuth secrets)
|
||||
- **External service unavailable**: Dependency on service that's down or inaccessible
|
||||
- **Environment limitation**: Hardware or system requirement you cannot fulfill
|
||||
|
||||
**NEVER skip because:**
|
||||
|
||||
| Situation | Wrong Action | Correct Action |
|
||||
|-----------|--------------|----------------|
|
||||
| "Page doesn't exist" | Skip | Create the page |
|
||||
| "API endpoint missing" | Skip | Implement the endpoint |
|
||||
| "Database table not ready" | Skip | Create the migration |
|
||||
| "Component not built" | Skip | Build the component |
|
||||
| "No data to test with" | Skip | Create test data or build data entry flow |
|
||||
| "Feature X needs to be done first" | Skip | Build feature X as part of this feature |
|
||||
|
||||
If a feature requires building other functionality first, **build that functionality**. You are the coding agent - your job is to make the feature work, not to defer it.
|
||||
|
||||
If you must skip (truly external blocker only):
|
||||
|
||||
```
|
||||
Use the feature_skip tool with feature_id={id}
|
||||
```
|
||||
|
||||
Document the SPECIFIC external blocker in `claude-progress.txt`. "Functionality not built" is NEVER a valid reason.
|
||||
|
||||
### STEP 5: IMPLEMENT THE FEATURE
|
||||
|
||||
Implement the chosen feature thoroughly:
|
||||
|
||||
1. Write the code (frontend and/or backend as needed)
|
||||
2. Test manually using browser automation (see Step 6)
|
||||
3. Fix any issues discovered
|
||||
4. Verify the feature works end-to-end
|
||||
|
||||
### STEP 6: VERIFY WITH BROWSER AUTOMATION
|
||||
|
||||
**CRITICAL:** You MUST verify features through the actual UI.
|
||||
|
||||
Use browser automation tools:
|
||||
|
||||
- Navigate to the app in a real browser
|
||||
- Interact like a human user (click, type, scroll)
|
||||
- Take screenshots at each step
|
||||
- Verify both functionality AND visual appearance
|
||||
|
||||
**DO:**
|
||||
|
||||
- Test through the UI with clicks and keyboard input
|
||||
- Take screenshots to verify visual appearance
|
||||
- Check for console errors in browser
|
||||
- Verify complete user workflows end-to-end
|
||||
|
||||
**DON'T:**
|
||||
|
||||
- Only test with curl commands (backend testing alone is insufficient)
|
||||
- Use JavaScript evaluation to bypass UI (no shortcuts)
|
||||
- Skip visual verification
|
||||
- Mark tests passing without thorough verification
|
||||
|
||||
### STEP 6.5: MANDATORY VERIFICATION CHECKLIST (BEFORE MARKING ANY TEST PASSING)
|
||||
|
||||
**You MUST complete ALL of these checks before marking any feature as "passes": true**
|
||||
|
||||
#### Security Verification (for protected features)
|
||||
|
||||
- [ ] Feature respects user role permissions
|
||||
- [ ] Unauthenticated access is blocked (redirects to login)
|
||||
- [ ] API endpoint checks authorization (returns 401/403 appropriately)
|
||||
- [ ] Cannot access other users' data by manipulating URLs
|
||||
|
||||
#### Real Data Verification (CRITICAL - NO MOCK DATA)
|
||||
|
||||
- [ ] Created unique test data via UI (e.g., "TEST_12345_VERIFY_ME")
|
||||
- [ ] Verified the EXACT data I created appears in UI
|
||||
- [ ] Refreshed page - data persists (proves database storage)
|
||||
- [ ] Deleted the test data - verified it's gone everywhere
|
||||
- [ ] NO unexplained data appeared (would indicate mock data)
|
||||
- [ ] Dashboard/counts reflect real numbers after my changes
|
||||
|
||||
#### Navigation Verification
|
||||
|
||||
- [ ] All buttons on this page link to existing routes
|
||||
- [ ] No 404 errors when clicking any interactive element
|
||||
- [ ] Back button returns to correct previous page
|
||||
- [ ] Related links (edit, view, delete) have correct IDs in URLs
|
||||
|
||||
#### Integration Verification
|
||||
|
||||
- [ ] Console shows ZERO JavaScript errors
|
||||
- [ ] Network tab shows successful API calls (no 500s)
|
||||
- [ ] Data returned from API matches what UI displays
|
||||
- [ ] Loading states appeared during API calls
|
||||
- [ ] Error states handle failures gracefully
|
||||
|
||||
### STEP 6.6: MOCK DATA DETECTION SWEEP
|
||||
|
||||
**Run this sweep AFTER EVERY FEATURE before marking it as passing:**
|
||||
|
||||
#### 1. Code Pattern Search
|
||||
|
||||
Search the codebase for forbidden patterns:
|
||||
|
||||
```bash
|
||||
# Search for mock data patterns
|
||||
grep -r "mockData\|fakeData\|sampleData\|dummyData\|testData" --include="*.js" --include="*.ts" --include="*.jsx" --include="*.tsx"
|
||||
grep -r "// TODO\|// FIXME\|// STUB\|// MOCK" --include="*.js" --include="*.ts" --include="*.jsx" --include="*.tsx"
|
||||
grep -r "hardcoded\|placeholder" --include="*.js" --include="*.ts" --include="*.jsx" --include="*.tsx"
|
||||
```
|
||||
|
||||
**If ANY matches found related to your feature - FIX THEM before proceeding.**
|
||||
|
||||
#### 2. Runtime Verification
|
||||
|
||||
For ANY data displayed in UI:
|
||||
|
||||
1. Create NEW data with UNIQUE content (e.g., "TEST_12345_DELETE_ME")
|
||||
2. Verify that EXACT content appears in the UI
|
||||
3. Delete the record
|
||||
4. Verify it's GONE from the UI
|
||||
5. **If you see data that wasn't created during testing - IT'S MOCK DATA. Fix it.**
|
||||
|
||||
#### 3. Database Verification
|
||||
|
||||
Check that:
|
||||
|
||||
- Database tables contain only data you created during tests
|
||||
- Counts/statistics match actual database record counts
|
||||
- No seed data is masquerading as user data
|
||||
|
||||
#### 4. API Response Verification
|
||||
|
||||
For API endpoints used by this feature:
|
||||
|
||||
- Call the endpoint directly
|
||||
- Verify response contains actual database data
|
||||
- Empty database = empty response (not pre-populated mock data)
|
||||
|
||||
### STEP 7: UPDATE FEATURE STATUS (CAREFULLY!)
|
||||
|
||||
**YOU CAN ONLY MODIFY ONE FIELD: "passes"**
|
||||
|
||||
After thorough verification, mark the feature as passing:
|
||||
|
||||
```
|
||||
# Mark feature #42 as passing (replace 42 with the actual feature ID)
|
||||
Use the feature_mark_passing tool with feature_id=42
|
||||
```
|
||||
|
||||
**NEVER:**
|
||||
|
||||
- Delete features
|
||||
- Edit feature descriptions
|
||||
- Modify feature steps
|
||||
- Combine or consolidate features
|
||||
- Reorder features
|
||||
|
||||
**ONLY MARK A FEATURE AS PASSING AFTER VERIFICATION WITH SCREENSHOTS.**
|
||||
|
||||
### STEP 8: COMMIT YOUR PROGRESS
|
||||
|
||||
Make a descriptive git commit:
|
||||
|
||||
```bash
|
||||
git add .
|
||||
git commit -m "Implement [feature name] - verified end-to-end
|
||||
|
||||
- Added [specific changes]
|
||||
- Tested with browser automation
|
||||
- Marked feature #X as passing
|
||||
- Screenshots in verification/ directory
|
||||
"
|
||||
```
|
||||
|
||||
### STEP 9: UPDATE PROGRESS NOTES
|
||||
|
||||
Update `claude-progress.txt` with:
|
||||
|
||||
- What you accomplished this session
|
||||
- Which test(s) you completed
|
||||
- Any issues discovered or fixed
|
||||
- What should be worked on next
|
||||
- Current completion status (e.g., "45/200 tests passing")
|
||||
|
||||
### STEP 10: END SESSION CLEANLY
|
||||
|
||||
Before context fills up:
|
||||
|
||||
1. Commit all working code
|
||||
2. Update claude-progress.txt
|
||||
3. Mark features as passing if tests verified
|
||||
4. Ensure no uncommitted changes
|
||||
5. Leave app in working state (no broken features)
|
||||
|
||||
---
|
||||
|
||||
## TESTING REQUIREMENTS
|
||||
|
||||
**ALL testing must use browser automation tools.**
|
||||
|
||||
Available tools:
|
||||
|
||||
**Navigation & Screenshots:**
|
||||
|
||||
- browser_navigate - Navigate to a URL
|
||||
- browser_navigate_back - Go back to previous page
|
||||
- browser_take_screenshot - Capture screenshot (use for visual verification)
|
||||
- browser_snapshot - Get accessibility tree snapshot (structured page data)
|
||||
|
||||
**Element Interaction:**
|
||||
|
||||
- browser_click - Click elements (has built-in auto-wait)
|
||||
- browser_type - Type text into editable elements
|
||||
- browser_fill_form - Fill multiple form fields at once
|
||||
- browser_select_option - Select dropdown options
|
||||
- browser_hover - Hover over elements
|
||||
- browser_drag - Drag and drop between elements
|
||||
- browser_press_key - Press keyboard keys
|
||||
|
||||
**Debugging & Monitoring:**
|
||||
|
||||
- browser_console_messages - Get browser console output (check for errors)
|
||||
- browser_network_requests - Monitor API calls and responses
|
||||
- browser_evaluate - Execute JavaScript (USE SPARINGLY - debugging only, NOT for bypassing UI)
|
||||
|
||||
**Browser Management:**
|
||||
|
||||
- browser_close - Close the browser
|
||||
- browser_resize - Resize browser window (use to test mobile: 375x667, tablet: 768x1024, desktop: 1280x720)
|
||||
- browser_tabs - Manage browser tabs
|
||||
- browser_wait_for - Wait for text/element/time
|
||||
- browser_handle_dialog - Handle alert/confirm dialogs
|
||||
- browser_file_upload - Upload files
|
||||
|
||||
**Key Benefits:**
|
||||
|
||||
- All interaction tools have **built-in auto-wait** - no manual timeouts needed
|
||||
- Use `browser_console_messages` to detect JavaScript errors
|
||||
- Use `browser_network_requests` to verify API calls succeed
|
||||
|
||||
Test like a human user with mouse and keyboard. Don't take shortcuts by using JavaScript evaluation.
|
||||
|
||||
---
|
||||
|
||||
## FEATURE TOOL USAGE RULES (CRITICAL - DO NOT VIOLATE)
|
||||
|
||||
The feature tools exist to reduce token usage. **DO NOT make exploratory queries.**
|
||||
|
||||
### ALLOWED Feature Tools (ONLY these):
|
||||
|
||||
```
|
||||
# 1. Get progress stats (passing/in_progress/total counts)
|
||||
feature_get_stats
|
||||
|
||||
# 2. Get the NEXT feature to work on (one feature only)
|
||||
feature_get_next
|
||||
|
||||
# 3. Mark a feature as in-progress (call immediately after feature_get_next)
|
||||
feature_mark_in_progress with feature_id={id}
|
||||
|
||||
# 4. Get up to 3 random passing features for regression testing
|
||||
feature_get_for_regression
|
||||
|
||||
# 5. Mark a feature as passing (after verification)
|
||||
feature_mark_passing with feature_id={id}
|
||||
|
||||
# 6. Skip a feature (moves to end of queue) - ONLY when blocked by dependency
|
||||
feature_skip with feature_id={id}
|
||||
|
||||
# 7. Clear in-progress status (when abandoning a feature)
|
||||
feature_clear_in_progress with feature_id={id}
|
||||
```
|
||||
|
||||
### RULES:
|
||||
|
||||
- Do NOT try to fetch lists of all features
|
||||
- Do NOT query features by category
|
||||
- Do NOT list all pending features
|
||||
|
||||
**You do NOT need to see all features.** The feature_get_next tool tells you exactly what to work on. Trust it.
|
||||
|
||||
---
|
||||
|
||||
## EMAIL INTEGRATION (DEVELOPMENT MODE)
|
||||
|
||||
When building applications that require email functionality (password resets, email verification, notifications, etc.), you typically won't have access to a real email service or the ability to read email inboxes.
|
||||
|
||||
**Solution:** Configure the application to log emails to the terminal instead of sending them.
|
||||
|
||||
- Password reset links should be printed to the console
|
||||
- Email verification links should be printed to the console
|
||||
- Any notification content should be logged to the terminal
|
||||
|
||||
**During testing:**
|
||||
|
||||
1. Trigger the email action (e.g., click "Forgot Password")
|
||||
2. Check the terminal/server logs for the generated link
|
||||
3. Use that link directly to verify the functionality works
|
||||
|
||||
This allows you to fully test email-dependent flows without needing external email services.
|
||||
|
||||
---
|
||||
|
||||
## IMPORTANT REMINDERS
|
||||
|
||||
**Your Goal:** Production-quality application with all tests passing
|
||||
|
||||
**This Session's Goal:** Complete at least one feature perfectly
|
||||
|
||||
**Priority:** Fix broken tests before implementing new features
|
||||
|
||||
**Quality Bar:**
|
||||
|
||||
- Zero console errors
|
||||
- Polished UI matching the design specified in app_spec.txt
|
||||
- All features work end-to-end through the UI
|
||||
- Fast, responsive, professional
|
||||
- **NO MOCK DATA - all data from real database**
|
||||
- **Security enforced - unauthorized access blocked**
|
||||
- **All navigation works - no 404s or broken links**
|
||||
|
||||
**You have unlimited time.** Take as long as needed to get it right. The most important thing is that you
|
||||
leave the code base in a clean state before terminating the session (Step 10).
|
||||
|
||||
---
|
||||
|
||||
Begin by running Step 1 (Get Your Bearings).
|
||||
274
.claude/templates/coding_prompt_yolo.template.md
Normal file
274
.claude/templates/coding_prompt_yolo.template.md
Normal file
@@ -0,0 +1,274 @@
|
||||
<!-- YOLO MODE PROMPT - Keep synchronized with coding_prompt.template.md -->
|
||||
<!-- Last synced: 2026-01-01 -->
|
||||
|
||||
## YOLO MODE - Rapid Prototyping (Testing Disabled)
|
||||
|
||||
**WARNING:** This mode skips all browser testing and regression tests.
|
||||
Features are marked as passing after lint/type-check succeeds.
|
||||
Use for rapid prototyping only - not for production-quality development.
|
||||
|
||||
---
|
||||
|
||||
## YOUR ROLE - CODING AGENT (YOLO MODE)
|
||||
|
||||
You are continuing work on a long-running autonomous development task.
|
||||
This is a FRESH context window - you have no memory of previous sessions.
|
||||
|
||||
### STEP 1: GET YOUR BEARINGS (MANDATORY)
|
||||
|
||||
Start by orienting yourself:
|
||||
|
||||
```bash
|
||||
# 1. See your working directory
|
||||
pwd
|
||||
|
||||
# 2. List files to understand project structure
|
||||
ls -la
|
||||
|
||||
# 3. Read the project specification to understand what you're building
|
||||
cat app_spec.txt
|
||||
|
||||
# 4. Read progress notes from previous sessions
|
||||
cat claude-progress.txt
|
||||
|
||||
# 5. Check recent git history
|
||||
git log --oneline -20
|
||||
```
|
||||
|
||||
Then use MCP tools to check feature status:
|
||||
|
||||
```
|
||||
# 6. Get progress statistics (passing/total counts)
|
||||
Use the feature_get_stats tool
|
||||
|
||||
# 7. Get the next feature to work on
|
||||
Use the feature_get_next tool
|
||||
```
|
||||
|
||||
Understanding the `app_spec.txt` is critical - it contains the full requirements
|
||||
for the application you're building.
|
||||
|
||||
### STEP 2: START SERVERS (IF NOT RUNNING)
|
||||
|
||||
If `init.sh` exists, run it:
|
||||
|
||||
```bash
|
||||
chmod +x init.sh
|
||||
./init.sh
|
||||
```
|
||||
|
||||
Otherwise, start servers manually and document the process.
|
||||
|
||||
### STEP 3: CHOOSE ONE FEATURE TO IMPLEMENT
|
||||
|
||||
Get the next feature to implement:
|
||||
|
||||
```
|
||||
# Get the highest-priority pending feature
|
||||
Use the feature_get_next tool
|
||||
```
|
||||
|
||||
Once you've retrieved the feature, **immediately mark it as in-progress**:
|
||||
|
||||
```
|
||||
# Mark feature as in-progress to prevent other sessions from working on it
|
||||
Use the feature_mark_in_progress tool with feature_id=42
|
||||
```
|
||||
|
||||
Focus on completing one feature in this session before moving on to other features.
|
||||
It's ok if you only complete one feature in this session, as there will be more sessions later that continue to make progress.
|
||||
|
||||
#### When to Skip a Feature (EXTREMELY RARE)
|
||||
|
||||
**Skipping should almost NEVER happen.** Only skip for truly external blockers you cannot control:
|
||||
|
||||
- **External API not configured**: Third-party service credentials missing (e.g., Stripe keys, OAuth secrets)
|
||||
- **External service unavailable**: Dependency on service that's down or inaccessible
|
||||
- **Environment limitation**: Hardware or system requirement you cannot fulfill
|
||||
|
||||
**NEVER skip because:**
|
||||
|
||||
| Situation | Wrong Action | Correct Action |
|
||||
|-----------|--------------|----------------|
|
||||
| "Page doesn't exist" | Skip | Create the page |
|
||||
| "API endpoint missing" | Skip | Implement the endpoint |
|
||||
| "Database table not ready" | Skip | Create the migration |
|
||||
| "Component not built" | Skip | Build the component |
|
||||
| "No data to test with" | Skip | Create test data or build data entry flow |
|
||||
| "Feature X needs to be done first" | Skip | Build feature X as part of this feature |
|
||||
|
||||
If a feature requires building other functionality first, **build that functionality**. You are the coding agent - your job is to make the feature work, not to defer it.
|
||||
|
||||
If you must skip (truly external blocker only):
|
||||
|
||||
```
|
||||
Use the feature_skip tool with feature_id={id}
|
||||
```
|
||||
|
||||
Document the SPECIFIC external blocker in `claude-progress.txt`. "Functionality not built" is NEVER a valid reason.
|
||||
|
||||
### STEP 4: IMPLEMENT THE FEATURE
|
||||
|
||||
Implement the chosen feature thoroughly:
|
||||
|
||||
1. Write the code (frontend and/or backend as needed)
|
||||
2. Ensure proper error handling
|
||||
3. Follow existing code patterns in the codebase
|
||||
|
||||
### STEP 5: VERIFY WITH LINT AND TYPE CHECK (YOLO MODE)
|
||||
|
||||
**In YOLO mode, verification is done through static analysis only.**
|
||||
|
||||
Run the appropriate lint and type-check commands for your project:
|
||||
|
||||
**For TypeScript/JavaScript projects:**
|
||||
```bash
|
||||
npm run lint
|
||||
npm run typecheck # or: npx tsc --noEmit
|
||||
```
|
||||
|
||||
**For Python projects:**
|
||||
```bash
|
||||
ruff check .
|
||||
mypy .
|
||||
```
|
||||
|
||||
**If lint/type-check passes:** Proceed to mark the feature as passing.
|
||||
|
||||
**If lint/type-check fails:** Fix the errors before proceeding.
|
||||
|
||||
### STEP 6: UPDATE FEATURE STATUS
|
||||
|
||||
**YOU CAN ONLY MODIFY ONE FIELD: "passes"**
|
||||
|
||||
After lint/type-check passes, mark the feature as passing:
|
||||
|
||||
```
|
||||
# Mark feature #42 as passing (replace 42 with the actual feature ID)
|
||||
Use the feature_mark_passing tool with feature_id=42
|
||||
```
|
||||
|
||||
**NEVER:**
|
||||
|
||||
- Delete features
|
||||
- Edit feature descriptions
|
||||
- Modify feature steps
|
||||
- Combine or consolidate features
|
||||
- Reorder features
|
||||
|
||||
### STEP 7: COMMIT YOUR PROGRESS
|
||||
|
||||
Make a descriptive git commit:
|
||||
|
||||
```bash
|
||||
git add .
|
||||
git commit -m "Implement [feature name] - YOLO mode
|
||||
|
||||
- Added [specific changes]
|
||||
- Lint/type-check passing
|
||||
- Marked feature #X as passing
|
||||
"
|
||||
```
|
||||
|
||||
### STEP 8: UPDATE PROGRESS NOTES
|
||||
|
||||
Update `claude-progress.txt` with:
|
||||
|
||||
- What you accomplished this session
|
||||
- Which feature(s) you completed
|
||||
- Any issues discovered or fixed
|
||||
- What should be worked on next
|
||||
- Current completion status (e.g., "45/200 features passing")
|
||||
|
||||
### STEP 9: END SESSION CLEANLY
|
||||
|
||||
Before context fills up:
|
||||
|
||||
1. Commit all working code
|
||||
2. Update claude-progress.txt
|
||||
3. Mark features as passing if lint/type-check verified
|
||||
4. Ensure no uncommitted changes
|
||||
5. Leave app in working state
|
||||
|
||||
---
|
||||
|
||||
## FEATURE TOOL USAGE RULES (CRITICAL - DO NOT VIOLATE)
|
||||
|
||||
The feature tools exist to reduce token usage. **DO NOT make exploratory queries.**
|
||||
|
||||
### ALLOWED Feature Tools (ONLY these):
|
||||
|
||||
```
|
||||
# 1. Get progress stats (passing/in_progress/total counts)
|
||||
feature_get_stats
|
||||
|
||||
# 2. Get the NEXT feature to work on (one feature only)
|
||||
feature_get_next
|
||||
|
||||
# 3. Mark a feature as in-progress (call immediately after feature_get_next)
|
||||
feature_mark_in_progress with feature_id={id}
|
||||
|
||||
# 4. Mark a feature as passing (after lint/type-check succeeds)
|
||||
feature_mark_passing with feature_id={id}
|
||||
|
||||
# 5. Skip a feature (moves to end of queue) - ONLY when blocked by dependency
|
||||
feature_skip with feature_id={id}
|
||||
|
||||
# 6. Clear in-progress status (when abandoning a feature)
|
||||
feature_clear_in_progress with feature_id={id}
|
||||
```
|
||||
|
||||
### RULES:
|
||||
|
||||
- Do NOT try to fetch lists of all features
|
||||
- Do NOT query features by category
|
||||
- Do NOT list all pending features
|
||||
|
||||
**You do NOT need to see all features.** The feature_get_next tool tells you exactly what to work on. Trust it.
|
||||
|
||||
---
|
||||
|
||||
## EMAIL INTEGRATION (DEVELOPMENT MODE)
|
||||
|
||||
When building applications that require email functionality (password resets, email verification, notifications, etc.), you typically won't have access to a real email service or the ability to read email inboxes.
|
||||
|
||||
**Solution:** Configure the application to log emails to the terminal instead of sending them.
|
||||
|
||||
- Password reset links should be printed to the console
|
||||
- Email verification links should be printed to the console
|
||||
- Any notification content should be logged to the terminal
|
||||
|
||||
**During testing:**
|
||||
|
||||
1. Trigger the email action (e.g., click "Forgot Password")
|
||||
2. Check the terminal/server logs for the generated link
|
||||
3. Use that link directly to verify the functionality works
|
||||
|
||||
This allows you to fully test email-dependent flows without needing external email services.
|
||||
|
||||
---
|
||||
|
||||
## IMPORTANT REMINDERS (YOLO MODE)
|
||||
|
||||
**Your Goal:** Rapidly prototype the application with all features implemented
|
||||
|
||||
**This Session's Goal:** Complete at least one feature
|
||||
|
||||
**Quality Bar (YOLO Mode):**
|
||||
|
||||
- Code compiles without errors (lint/type-check passing)
|
||||
- Follows existing code patterns
|
||||
- Basic error handling in place
|
||||
- Features are implemented according to spec
|
||||
|
||||
**Note:** Browser testing and regression testing are SKIPPED in YOLO mode.
|
||||
Features may have bugs that would be caught by manual testing.
|
||||
Use standard mode for production-quality verification.
|
||||
|
||||
**You have unlimited time.** Take as long as needed to implement features correctly.
|
||||
The most important thing is that you leave the code base in a clean state before
|
||||
terminating the session (Step 9).
|
||||
|
||||
---
|
||||
|
||||
Begin by running Step 1 (Get Your Bearings).
|
||||
523
.claude/templates/initializer_prompt.template.md
Normal file
523
.claude/templates/initializer_prompt.template.md
Normal file
@@ -0,0 +1,523 @@
|
||||
## YOUR ROLE - INITIALIZER AGENT (Session 1 of Many)
|
||||
|
||||
You are the FIRST agent in a long-running autonomous development process.
|
||||
Your job is to set up the foundation for all future coding agents.
|
||||
|
||||
### FIRST: Read the Project Specification
|
||||
|
||||
Start by reading `app_spec.txt` in your working directory. This file contains
|
||||
the complete specification for what you need to build. Read it carefully
|
||||
before proceeding.
|
||||
|
||||
---
|
||||
|
||||
## REQUIRED FEATURE COUNT
|
||||
|
||||
**CRITICAL:** You must create exactly **[FEATURE_COUNT]** features using the `feature_create_bulk` tool.
|
||||
|
||||
This number was determined during spec creation and must be followed precisely. Do not create more or fewer features than specified.
|
||||
|
||||
---
|
||||
|
||||
### CRITICAL FIRST TASK: Create Features
|
||||
|
||||
Based on `app_spec.txt`, create features using the feature_create_bulk tool. The features are stored in a SQLite database,
|
||||
which is the single source of truth for what needs to be built.
|
||||
|
||||
**Creating Features:**
|
||||
|
||||
Use the feature_create_bulk tool to add all features at once:
|
||||
|
||||
```
|
||||
Use the feature_create_bulk tool with features=[
|
||||
{
|
||||
"category": "functional",
|
||||
"name": "Brief feature name",
|
||||
"description": "Brief description of the feature and what this test verifies",
|
||||
"steps": [
|
||||
"Step 1: Navigate to relevant page",
|
||||
"Step 2: Perform action",
|
||||
"Step 3: Verify expected result"
|
||||
]
|
||||
},
|
||||
{
|
||||
"category": "style",
|
||||
"name": "Brief feature name",
|
||||
"description": "Brief description of UI/UX requirement",
|
||||
"steps": [
|
||||
"Step 1: Navigate to page",
|
||||
"Step 2: Take screenshot",
|
||||
"Step 3: Verify visual requirements"
|
||||
]
|
||||
}
|
||||
]
|
||||
```
|
||||
|
||||
**Notes:**
|
||||
- IDs and priorities are assigned automatically based on order
|
||||
- All features start with `passes: false` by default
|
||||
- You can create features in batches if there are many (e.g., 50 at a time)
|
||||
|
||||
**Requirements for features:**
|
||||
|
||||
- Feature count must match the `feature_count` specified in app_spec.txt
|
||||
- Reference tiers for other projects:
|
||||
- **Simple apps**: ~150 tests
|
||||
- **Medium apps**: ~250 tests
|
||||
- **Complex apps**: ~400+ tests
|
||||
- Both "functional" and "style" categories
|
||||
- Mix of narrow tests (2-5 steps) and comprehensive tests (10+ steps)
|
||||
- At least 25 tests MUST have 10+ steps each (more for complex apps)
|
||||
- Order features by priority: fundamental features first (the API assigns priority based on order)
|
||||
- All features start with `passes: false` automatically
|
||||
- Cover every feature in the spec exhaustively
|
||||
- **MUST include tests from ALL 20 mandatory categories below**
|
||||
|
||||
---
|
||||
|
||||
## MANDATORY TEST CATEGORIES
|
||||
|
||||
The feature_list.json **MUST** include tests from ALL of these categories. The minimum counts scale by complexity tier.
|
||||
|
||||
### Category Distribution by Complexity Tier
|
||||
|
||||
| Category | Simple | Medium | Complex |
|
||||
| -------------------------------- | ------- | ------- | -------- |
|
||||
| A. Security & Access Control | 5 | 20 | 40 |
|
||||
| B. Navigation Integrity | 15 | 25 | 40 |
|
||||
| C. Real Data Verification | 20 | 30 | 50 |
|
||||
| D. Workflow Completeness | 10 | 20 | 40 |
|
||||
| E. Error Handling | 10 | 15 | 25 |
|
||||
| F. UI-Backend Integration | 10 | 20 | 35 |
|
||||
| G. State & Persistence | 8 | 10 | 15 |
|
||||
| H. URL & Direct Access | 5 | 10 | 20 |
|
||||
| I. Double-Action & Idempotency | 5 | 8 | 15 |
|
||||
| J. Data Cleanup & Cascade | 5 | 10 | 20 |
|
||||
| K. Default & Reset | 5 | 8 | 12 |
|
||||
| L. Search & Filter Edge Cases | 8 | 12 | 20 |
|
||||
| M. Form Validation | 10 | 15 | 25 |
|
||||
| N. Feedback & Notification | 8 | 10 | 15 |
|
||||
| O. Responsive & Layout | 8 | 10 | 15 |
|
||||
| P. Accessibility | 8 | 10 | 15 |
|
||||
| Q. Temporal & Timezone | 5 | 8 | 12 |
|
||||
| R. Concurrency & Race Conditions | 5 | 8 | 15 |
|
||||
| S. Export/Import | 5 | 6 | 10 |
|
||||
| T. Performance | 5 | 5 | 10 |
|
||||
| **TOTAL** | **150** | **250** | **400+** |
|
||||
|
||||
---
|
||||
|
||||
### A. Security & Access Control Tests
|
||||
|
||||
Test that unauthorized access is blocked and permissions are enforced.
|
||||
|
||||
**Required tests (examples):**
|
||||
|
||||
- Unauthenticated user cannot access protected routes (redirect to login)
|
||||
- Regular user cannot access admin-only pages (403 or redirect)
|
||||
- API endpoints return 401 for unauthenticated requests
|
||||
- API endpoints return 403 for unauthorized role access
|
||||
- Session expires after configured inactivity period
|
||||
- Logout clears all session data and tokens
|
||||
- Invalid/expired tokens are rejected
|
||||
- Each role can ONLY see their permitted menu items
|
||||
- Direct URL access to unauthorized pages is blocked
|
||||
- Sensitive operations require confirmation or re-authentication
|
||||
- Cannot access another user's data by manipulating IDs in URL
|
||||
- Password reset flow works securely
|
||||
- Failed login attempts are handled (no information leakage)
|
||||
|
||||
### B. Navigation Integrity Tests
|
||||
|
||||
Test that every button, link, and menu item goes to the correct place.
|
||||
|
||||
**Required tests (examples):**
|
||||
|
||||
- Every button in sidebar navigates to correct page
|
||||
- Every menu item links to existing route
|
||||
- All CRUD action buttons (Edit, Delete, View) go to correct URLs with correct IDs
|
||||
- Back button works correctly after each navigation
|
||||
- Deep linking works (direct URL access to any page with auth)
|
||||
- Breadcrumbs reflect actual navigation path
|
||||
- 404 page shown for non-existent routes (not crash)
|
||||
- After login, user redirected to intended destination (or dashboard)
|
||||
- After logout, user redirected to login page
|
||||
- Pagination links work and preserve current filters
|
||||
- Tab navigation within pages works correctly
|
||||
- Modal close buttons return to previous state
|
||||
- Cancel buttons on forms return to previous page
|
||||
|
||||
### C. Real Data Verification Tests
|
||||
|
||||
Test that data is real (not mocked) and persists correctly.
|
||||
|
||||
**Required tests (examples):**
|
||||
|
||||
- Create a record via UI with unique content → verify it appears in list
|
||||
- Create a record → refresh page → record still exists
|
||||
- Create a record → log out → log in → record still exists
|
||||
- Edit a record → verify changes persist after refresh
|
||||
- Delete a record → verify it's gone from list AND database
|
||||
- Delete a record → verify it's gone from related dropdowns
|
||||
- Filter/search → results match actual data created in test
|
||||
- Dashboard statistics reflect real record counts (create 3 items, count shows 3)
|
||||
- Reports show real aggregated data
|
||||
- Export functionality exports actual data you created
|
||||
- Related records update when parent changes
|
||||
- Timestamps are real and accurate (created_at, updated_at)
|
||||
- Data created by User A is not visible to User B (unless shared)
|
||||
- Empty state shows correctly when no data exists
|
||||
|
||||
### D. Workflow Completeness Tests
|
||||
|
||||
Test that every workflow can be completed end-to-end through the UI.
|
||||
|
||||
**Required tests (examples):**
|
||||
|
||||
- Every entity has working Create operation via UI form
|
||||
- Every entity has working Read/View operation (detail page loads)
|
||||
- Every entity has working Update operation (edit form saves)
|
||||
- Every entity has working Delete operation (with confirmation dialog)
|
||||
- Every status/state has a UI mechanism to transition to next state
|
||||
- Multi-step processes (wizards) can be completed end-to-end
|
||||
- Bulk operations (select all, delete selected) work
|
||||
- Cancel/Undo operations work where applicable
|
||||
- Required fields prevent submission when empty
|
||||
- Form validation shows errors before submission
|
||||
- Successful submission shows success feedback
|
||||
- Backend workflow (e.g., user→customer conversion) has UI trigger
|
||||
|
||||
### E. Error Handling Tests
|
||||
|
||||
Test graceful handling of errors and edge cases.
|
||||
|
||||
**Required tests (examples):**
|
||||
|
||||
- Network failure shows user-friendly error message, not crash
|
||||
- Invalid form input shows field-level errors
|
||||
- API errors display meaningful messages to user
|
||||
- 404 responses handled gracefully (show not found page)
|
||||
- 500 responses don't expose stack traces or technical details
|
||||
- Empty search results show "no results found" message
|
||||
- Loading states shown during all async operations
|
||||
- Timeout doesn't hang the UI indefinitely
|
||||
- Submitting form with server error keeps user data in form
|
||||
- File upload errors (too large, wrong type) show clear message
|
||||
- Duplicate entry errors (e.g., email already exists) are clear
|
||||
|
||||
### F. UI-Backend Integration Tests
|
||||
|
||||
Test that frontend and backend communicate correctly.
|
||||
|
||||
**Required tests (examples):**
|
||||
|
||||
- Frontend request format matches what backend expects
|
||||
- Backend response format matches what frontend parses
|
||||
- All dropdown options come from real database data (not hardcoded)
|
||||
- Related entity selectors (e.g., "choose category") populated from DB
|
||||
- Changes in one area reflect in related areas after refresh
|
||||
- Deleting parent handles children correctly (cascade or block)
|
||||
- Filters work with actual data attributes from database
|
||||
- Sort functionality sorts real data correctly
|
||||
- Pagination returns correct page of real data
|
||||
- API error responses are parsed and displayed correctly
|
||||
- Loading spinners appear during API calls
|
||||
- Optimistic updates (if used) rollback on failure
|
||||
|
||||
### G. State & Persistence Tests
|
||||
|
||||
Test that state is maintained correctly across sessions and tabs.
|
||||
|
||||
**Required tests (examples):**
|
||||
|
||||
- Refresh page mid-form - appropriate behavior (data kept or cleared)
|
||||
- Close browser, reopen - session state handled correctly
|
||||
- Same user in two browser tabs - changes sync or handled gracefully
|
||||
- Browser back after form submit - no duplicate submission
|
||||
- Bookmark a page, return later - works (with auth check)
|
||||
- LocalStorage/cookies cleared - graceful re-authentication
|
||||
- Unsaved changes warning when navigating away from dirty form
|
||||
|
||||
### H. URL & Direct Access Tests
|
||||
|
||||
Test direct URL access and URL manipulation security.
|
||||
|
||||
**Required tests (examples):**
|
||||
|
||||
- Change entity ID in URL - cannot access others' data
|
||||
- Access /admin directly as regular user - blocked
|
||||
- Malformed URL parameters - handled gracefully (no crash)
|
||||
- Very long URL - handled correctly
|
||||
- URL with SQL injection attempt - rejected/sanitized
|
||||
- Deep link to deleted entity - shows "not found", not crash
|
||||
- Query parameters for filters are reflected in UI
|
||||
- Sharing a URL with filters preserves those filters
|
||||
|
||||
### I. Double-Action & Idempotency Tests
|
||||
|
||||
Test that rapid or duplicate actions don't cause issues.
|
||||
|
||||
**Required tests (examples):**
|
||||
|
||||
- Double-click submit button - only one record created
|
||||
- Rapid multiple clicks on delete - only one deletion occurs
|
||||
- Submit form, hit back, submit again - appropriate behavior
|
||||
- Multiple simultaneous API calls - server handles correctly
|
||||
- Refresh during save operation - data not corrupted
|
||||
- Click same navigation link twice quickly - no issues
|
||||
- Submit button disabled during processing
|
||||
|
||||
### J. Data Cleanup & Cascade Tests
|
||||
|
||||
Test that deleting data cleans up properly everywhere.
|
||||
|
||||
**Required tests (examples):**
|
||||
|
||||
- Delete parent entity - children removed from all views
|
||||
- Delete item - removed from search results immediately
|
||||
- Delete item - statistics/counts updated immediately
|
||||
- Delete item - related dropdowns updated
|
||||
- Delete item - cached views refreshed
|
||||
- Soft delete (if applicable) - item hidden but recoverable
|
||||
- Hard delete - item completely removed from database
|
||||
|
||||
### K. Default & Reset Tests
|
||||
|
||||
Test that defaults and reset functionality work correctly.
|
||||
|
||||
**Required tests (examples):**
|
||||
|
||||
- New form shows correct default values
|
||||
- Date pickers default to sensible dates (today, not 1970)
|
||||
- Dropdowns default to correct option (or placeholder)
|
||||
- Reset button clears to defaults, not just empty
|
||||
- Clear filters button resets all filters to default
|
||||
- Pagination resets to page 1 when filters change
|
||||
- Sorting resets when changing views
|
||||
|
||||
### L. Search & Filter Edge Cases
|
||||
|
||||
Test search and filter functionality thoroughly.
|
||||
|
||||
**Required tests (examples):**
|
||||
|
||||
- Empty search shows all results (or appropriate message)
|
||||
- Search with only spaces - handled correctly
|
||||
- Search with special characters (!@#$%^&\*) - no errors
|
||||
- Search with quotes - handled correctly
|
||||
- Search with very long string - handled correctly
|
||||
- Filter combinations that return zero results - shows message
|
||||
- Filter + search + sort together - all work correctly
|
||||
- Filter persists after viewing detail and returning to list
|
||||
- Clear individual filter - works correctly
|
||||
- Search is case-insensitive (or clearly case-sensitive)
|
||||
|
||||
### M. Form Validation Tests
|
||||
|
||||
Test all form validation rules exhaustively.
|
||||
|
||||
**Required tests (examples):**
|
||||
|
||||
- Required field empty - shows error, blocks submit
|
||||
- Email field with invalid email formats - shows error
|
||||
- Password field - enforces complexity requirements
|
||||
- Numeric field with letters - rejected
|
||||
- Date field with invalid date - rejected
|
||||
- Min/max length enforced on text fields
|
||||
- Min/max values enforced on numeric fields
|
||||
- Duplicate unique values rejected (e.g., duplicate email)
|
||||
- Error messages are specific (not just "invalid")
|
||||
- Errors clear when user fixes the issue
|
||||
- Server-side validation matches client-side
|
||||
- Whitespace-only input rejected for required fields
|
||||
|
||||
### N. Feedback & Notification Tests
|
||||
|
||||
Test that users get appropriate feedback for all actions.
|
||||
|
||||
**Required tests (examples):**
|
||||
|
||||
- Every successful save/create shows success feedback
|
||||
- Every failed action shows error feedback
|
||||
- Loading spinner during every async operation
|
||||
- Disabled state on buttons during form submission
|
||||
- Progress indicator for long operations (file upload)
|
||||
- Toast/notification disappears after appropriate time
|
||||
- Multiple notifications don't overlap incorrectly
|
||||
- Success messages are specific (not just "Success")
|
||||
|
||||
### O. Responsive & Layout Tests
|
||||
|
||||
Test that the UI works on different screen sizes.
|
||||
|
||||
**Required tests (examples):**
|
||||
|
||||
- Desktop layout correct at 1920px width
|
||||
- Tablet layout correct at 768px width
|
||||
- Mobile layout correct at 375px width
|
||||
- No horizontal scroll on any standard viewport
|
||||
- Touch targets large enough on mobile (44px min)
|
||||
- Modals fit within viewport on mobile
|
||||
- Long text truncates or wraps correctly (no overflow)
|
||||
- Tables scroll horizontally if needed on mobile
|
||||
- Navigation collapses appropriately on mobile
|
||||
|
||||
### P. Accessibility Tests
|
||||
|
||||
Test basic accessibility compliance.
|
||||
|
||||
**Required tests (examples):**
|
||||
|
||||
- Tab navigation works through all interactive elements
|
||||
- Focus ring visible on all focused elements
|
||||
- Screen reader can navigate main content areas
|
||||
- ARIA labels on icon-only buttons
|
||||
- Color contrast meets WCAG AA (4.5:1 for text)
|
||||
- No information conveyed by color alone
|
||||
- Form fields have associated labels
|
||||
- Error messages announced to screen readers
|
||||
- Skip link to main content (if applicable)
|
||||
- Images have alt text
|
||||
|
||||
### Q. Temporal & Timezone Tests
|
||||
|
||||
Test date/time handling.
|
||||
|
||||
**Required tests (examples):**
|
||||
|
||||
- Dates display in user's local timezone
|
||||
- Created/updated timestamps accurate and formatted correctly
|
||||
- Date picker allows only valid date ranges
|
||||
- Overdue items identified correctly (timezone-aware)
|
||||
- "Today", "This Week" filters work correctly for user's timezone
|
||||
- Recurring items generate at correct times (if applicable)
|
||||
- Date sorting works correctly across months/years
|
||||
|
||||
### R. Concurrency & Race Condition Tests
|
||||
|
||||
Test multi-user and race condition scenarios.
|
||||
|
||||
**Required tests (examples):**
|
||||
|
||||
- Two users edit same record - last save wins or conflict shown
|
||||
- Record deleted while another user viewing - graceful handling
|
||||
- List updates while user on page 2 - pagination still works
|
||||
- Rapid navigation between pages - no stale data displayed
|
||||
- API response arrives after user navigated away - no crash
|
||||
- Concurrent form submissions from same user handled
|
||||
|
||||
### S. Export/Import Tests (if applicable)
|
||||
|
||||
Test data export and import functionality.
|
||||
|
||||
**Required tests (examples):**
|
||||
|
||||
- Export all data - file contains all records
|
||||
- Export filtered data - only filtered records included
|
||||
- Import valid file - all records created correctly
|
||||
- Import duplicate data - handled correctly (skip/update/error)
|
||||
- Import malformed file - error message, no partial import
|
||||
- Export then import - data integrity preserved exactly
|
||||
|
||||
### T. Performance Tests
|
||||
|
||||
Test basic performance requirements.
|
||||
|
||||
**Required tests (examples):**
|
||||
|
||||
- Page loads in <3s with 100 records
|
||||
- Page loads in <5s with 1000 records
|
||||
- Search responds in <1s
|
||||
- Infinite scroll doesn't degrade with many items
|
||||
- Large file upload shows progress
|
||||
- Memory doesn't leak on long sessions
|
||||
- No console errors during normal operation
|
||||
|
||||
---
|
||||
|
||||
## ABSOLUTE PROHIBITION: NO MOCK DATA
|
||||
|
||||
The feature_list.json must include tests that **actively verify real data** and **detect mock data patterns**.
|
||||
|
||||
**Include these specific tests:**
|
||||
|
||||
1. Create unique test data (e.g., "TEST_12345_VERIFY_ME")
|
||||
2. Verify that EXACT data appears in UI
|
||||
3. Refresh page - data persists
|
||||
4. Delete data - verify it's gone
|
||||
5. If data appears that wasn't created during test - FLAG AS MOCK DATA
|
||||
|
||||
**The agent implementing features MUST NOT use:**
|
||||
|
||||
- Hardcoded arrays of fake data
|
||||
- `mockData`, `fakeData`, `sampleData`, `dummyData` variables
|
||||
- `// TODO: replace with real API`
|
||||
- `setTimeout` simulating API delays with static data
|
||||
- Static returns instead of database queries
|
||||
|
||||
---
|
||||
|
||||
**CRITICAL INSTRUCTION:**
|
||||
IT IS CATASTROPHIC TO REMOVE OR EDIT FEATURES IN FUTURE SESSIONS.
|
||||
Features can ONLY be marked as passing (via the `feature_mark_passing` tool with the feature_id).
|
||||
Never remove features, never edit descriptions, never modify testing steps.
|
||||
This ensures no functionality is missed.
|
||||
|
||||
### SECOND TASK: Create init.sh
|
||||
|
||||
Create a script called `init.sh` that future agents can use to quickly
|
||||
set up and run the development environment. The script should:
|
||||
|
||||
1. Install any required dependencies
|
||||
2. Start any necessary servers or services
|
||||
3. Print helpful information about how to access the running application
|
||||
|
||||
Base the script on the technology stack specified in `app_spec.txt`.
|
||||
|
||||
### THIRD TASK: Initialize Git
|
||||
|
||||
Create a git repository and make your first commit with:
|
||||
|
||||
- init.sh (environment setup script)
|
||||
- README.md (project overview and setup instructions)
|
||||
- Any initial project structure files
|
||||
|
||||
Note: Features are stored in the SQLite database (features.db), not in a JSON file.
|
||||
|
||||
Commit message: "Initial setup: init.sh, project structure, and features created via API"
|
||||
|
||||
### FOURTH TASK: Create Project Structure
|
||||
|
||||
Set up the basic project structure based on what's specified in `app_spec.txt`.
|
||||
This typically includes directories for frontend, backend, and any other
|
||||
components mentioned in the spec.
|
||||
|
||||
### OPTIONAL: Start Implementation
|
||||
|
||||
If you have time remaining in this session, you may begin implementing
|
||||
the highest-priority features. Get the next feature with:
|
||||
|
||||
```
|
||||
Use the feature_get_next tool
|
||||
```
|
||||
|
||||
Remember:
|
||||
- Work on ONE feature at a time
|
||||
- Test thoroughly before marking as passing
|
||||
- Commit your progress before session ends
|
||||
|
||||
### ENDING THIS SESSION
|
||||
|
||||
Before your context fills up:
|
||||
|
||||
1. Commit all work with descriptive messages
|
||||
2. Create `claude-progress.txt` with a summary of what you accomplished
|
||||
3. Verify features were created using the feature_get_stats tool
|
||||
4. Leave the environment in a clean, working state
|
||||
|
||||
The next agent will continue from here with a fresh context window.
|
||||
|
||||
---
|
||||
|
||||
**Remember:** You have unlimited time across many sessions. Focus on
|
||||
quality over speed. Production-ready is the goal.
|
||||
Reference in New Issue
Block a user