Initial commit

2025-11-30 09:05:19 +08:00
commit 09fec2555b
96 changed files with 24269 additions and 0 deletions
--- a/skills/rapid-fullstack/PROTOTYPE.regex
+++ b/skills/rapid-fullstack/PROTOTYPE.regex
@@ -0,0 +1,31 @@
+# Regex patterns to auto-trigger rapid-fullstack skill
+
+# Direct prototyping requests
+(?i)(build|create|make|develop|prototype)\s+(a\s+)?(web\s?app|webapp|full[\s-]?stack\s+app|full[\s-]?stack\s+application)
+
+# MVP and prototype mentions
+(?i)(mvp|prototype|proof[\s-]of[\s-]concept|poc)\s+(for|of|with)
+
+# Backend + Frontend together
+(?i)(backend|api)\s+(and|with|\+)\s+(frontend|ui|interface)
+
+# Quick app building
+(?i)(quick|rapid|fast)\s+(web|fullstack|full[\s-]stack)\s+(app|application|project|prototype)
+
+# Testing/debugging full stack
+(?i)(test|debug|fix)\s+(the\s+)?(webapp|web\s+app|full[\s-]?stack|backend\s+and\s+frontend)
+
+# "Help me build" patterns
+(?i)help\s+(me\s+)?(build|create|make)\s+(a\s+)?.*(webapp|web\s+app|application|full[\s-]?stack)
+
+# Server + Client mentions
+(?i)(server|backend)\s+and\s+(client|frontend)
+
+# React/Vue/etc + API mentions
+(?i)(react|vue|svelte|angular)\s+(with|and|\+)\s+(api|backend|fastapi|flask|express|node)
+
+# Database + Frontend mentions
+(?i)(database|sqlite|postgres)\s+(with|and|\+)\s+(frontend|ui|react|vue)
+
+# WEBAPP in all caps (user often uses this)
+(?i)webapp
--- a/skills/rapid-fullstack/RESEARCH_GUIDE.md
+++ b/skills/rapid-fullstack/RESEARCH_GUIDE.md
@@ -0,0 +1,308 @@
+# Library Research Guide
+
+Quick reference for researching and selecting libraries during prototyping.
+
+## Search Strategy Flowchart
+
+```
+Need feature X?
+    ↓
+1. Can I build it in < 30 lines?
+   → YES: Don't use library
+   → NO: Continue to step 2
+    ↓
+2. Search for solutions
+   - WebSearch: "best [feature] library [framework] 2025"
+   - Exa Code: "[framework] [feature] implementation examples"
+    ↓
+3. Found 2-3 candidates?
+   → Compare them (see criteria below)
+    ↓
+4. Test the top choice
+   → Works in < 15 min? Use it
+   → Too complex/broken? Try next option
+    ↓
+5. Still nothing good?
+   → Build it yourself
+   → Or simplify the requirement
+```
+
+## Evaluation Criteria
+
+### Quick Check (2 min per library)
+```bash
+# For npm packages
+npm info <package-name>
+
+Look for:
+✅ Last publish: < 6 months ago
+✅ Weekly downloads: > 10k (for popular features)
+✅ Dependencies: < 10 (fewer is better)
+✅ License: MIT or Apache 2.0
+✅ TypeScript: Built-in types or @types/ available
+
+❌ Warning signs:
+- Last publish > 1 year ago
+- Many open issues, few closed
+- "deprecated" in description
+- Requires lots of peer dependencies
+```
+
+### Deep Check (5 min if quick check passes)
+```bash
+# Check GitHub
+1. Stars: > 1k for common features
+2. Issues:
+   - Response rate (maintainer active?)
+   - Closed/Open ratio (> 2:1 good)
+3. Last commit: < 3 months ideal
+4. Contributors: > 5 (not single-maintainer)
+5. Examples/demos: Exist and work?
+```
+
+### Bundle Size Check
+```
+Visit: https://bundlephobia.com/package/<package-name>
+
+Acceptable sizes for prototypes:
+- Utilities: < 10kb
+- UI components: < 50kb
+- Full editors: < 500kb
+- Anything else: Question if you need it
+```
+
+## Common Feature Searches
+
+### Rich Text / Markdown Editor
+```bash
+# Search queries
+"react markdown editor wysiwyg 2025"
+"best markdown editor component [framework]"
+"lightweight rich text editor [framework]"
+
+# What to look for
+- Live preview support
+- Custom toolbar options
+- Export/import formats
+- Syntax highlighting
+
+# Alternatives to consider
+- Full WYSIWYG editor (heavy)
+- Markdown editor with preview (medium)
+- Plain textarea with preview (light)
+- CodeMirror / Monaco (code-focused)
+```
+
+### Diff Viewer
+```bash
+# Search queries
+"visual diff component [framework]"
+"side by side diff viewer [framework]"
+"git diff ui component"
+
+# What to look for
+- Split/unified view toggle
+- Line highlighting
+- Syntax highlighting
+- Word-level diffs
+
+# Fallback
+- Use a diffing algorithm library
+- Render with custom CSS
+```
+
+### State Management
+```bash
+# Search queries
+"[framework] state management 2025"
+"zustand vs redux vs context"
+"when to use state management library"
+
+# Decision tree
+- Simple app (< 5 components) → useState/useReducer
+- Medium app (5-20 components) → Context API or Zustand
+- Complex app (20+ components) → Redux Toolkit or Recoil
+
+# For prototypes: Start simple, add later if needed
+```
+
+### Form Handling
+```bash
+# Search queries
+"[framework] form library 2025"
+"react hook form vs formik"
+"form validation library"
+
+# Decision tree
+- Simple forms (1-3 fields) → Vanilla HTML + state
+- Medium forms (4-10 fields) → Controlled components
+- Complex forms (10+ fields, validation) → React Hook Form / Formik
+
+# For prototypes: Keep it vanilla, add library if > 10 fields
+```
+
+### Data Fetching
+```bash
+# Search queries
+"[framework] data fetching library"
+"react query vs swr vs apollo"
+"best way to fetch data [framework]"
+
+# Decision tree
+- Simple REST API → fetch / axios
+- Need caching/refetching → React Query / SWR
+- GraphQL → Apollo Client / urql
+
+# For prototypes: Start with fetch, add library if you need:
+  - Automatic refetching
+  - Cache management
+  - Optimistic updates
+```
+
+### Styling
+```bash
+# Search queries
+"[framework] css framework 2025"
+"tailwind vs styled-components vs css modules"
+"css-in-js vs css modules"
+
+# Decision tree
+- Prototype (speed matters) → Vanilla CSS or inline styles
+- Need consistency → CSS Modules or Tailwind
+- Component library → Styled Components / Emotion
+- Design system → Material-UI / Ant Design
+
+# For prototypes: Vanilla CSS first, add framework if needed
+```
+
+## Search Query Templates
+
+### General Pattern
+```
+"best [feature-type] library for [framework] [year]"
+"[specific-library] vs [alternative] comparison"
+"[feature-type] implementation [framework] example"
+"lightweight [feature-type] component [framework]"
+```
+
+### For Code Examples
+Use exa-code search:
+```
+"[framework] [feature] implementation example"
+"how to use [library-name] with [framework]"
+"[feature] tutorial [framework]"
+```
+
+### For Comparisons
+```
+"[library-a] vs [library-b] [year]"
+"[library-name] alternatives"
+"[library-name] reddit" (real user opinions)
+"[library-name] bundle size"
+```
+
+## Red Flags
+
+### In Search Results
+- Many "how to fix" articles
+- Lots of open issues on GitHub
+- Tutorials only from > 2 years ago
+- No clear documentation site
+- Only works with specific versions
+
+### In Documentation
+- No getting started guide
+- No examples
+- Assumes lots of prior knowledge
+- Inconsistent API
+- Breaking changes in minor versions
+
+### In Issues/Community
+- Maintainer unresponsive
+- Many unanswered questions
+- Lots of "this doesn't work" issues
+- People asking for alternatives
+- Security issues ignored
+
+## Decision Making
+
+### Use native/simple if:
+```javascript
+// ❌ Don't import library for
+- Date formatting (Intl.DateTimeFormat)
+- HTTP requests (fetch API)
+- Simple state (useState/useReducer)
+- Basic validation (HTML5 + regex)
+- Simple animations (CSS transitions)
+```
+
+### Use library if:
+```javascript
+// ✅ Consider library for
+- Complex parsing (markdown, CSV)
+- Diffing algorithms
+- Rich text editing
+- Code highlighting
+- Complex animations
+- Data visualization
+```
+
+## Research Time Budgets
+
+- **Quick feature** (< 30 min to build): 0 min research → build it
+- **Medium feature** (30 min - 2 hours): 10 min research → decide
+- **Complex feature** (> 2 hours): 20 min research → pick best tool
+
+If research takes > 20 minutes, you're overthinking it:
+- Pick the most popular option
+- Try it for 15 minutes
+- If it doesn't work, try alternative
+
+## Example Research Session
+
+**Scenario**: Need visual diff for markdown editor
+
+**Step 1: Initial search** (3 min)
+```bash
+WebSearch: "react visual diff component side by side"
+Results:
+- react-diff-viewer (6.2k stars)
+- react-diff-view (3.1k stars)
+- monaco-diff-editor (part of Monaco)
+```
+
+**Step 2: Quick comparison** (5 min)
+```bash
+npm info react-diff-viewer
+# Last publish: 8 months ago (okay)
+# Downloads: 45k/week (popular)
+# Dependencies: 4 (good)
+
+npm info react-diff-view
+# Last publish: 1 year ago (warning)
+# Downloads: 8k/week (less popular)
+# Dependencies: 3 (good)
+
+Monaco: Heavy (500kb+), overkill for simple diff
+```
+
+**Step 3: Check examples** (2 min)
+- react-diff-viewer: Has live demo, looks good
+- react-diff-view: Examples look more complex
+
+**Decision**: Try react-diff-viewer first (most popular, good docs)
+
+**Step 4: Test** (10 min)
+```bash
+npm install react-diff-viewer
+# Create test component
+# Works in 10 min → Keep it
+```
+
+**Total time**: 20 minutes from "need diff viewer" to "working implementation"
+
+## Remember
+
+> "Perfect is the enemy of good. Pick something reasonable and move forward. You can always swap libraries later if needed."
+
+The goal is **working software**, not the perfect tech stack. Spend 80% of time building, 20% researching.
--- a/skills/rapid-fullstack/SKILL.md
+++ b/skills/rapid-fullstack/SKILL.md
@@ -0,0 +1,421 @@
+# Rapid Full-Stack Prototyping
+
+Build working full-stack web apps quickly (1-4 hours). Design first, code second, test third.
+
+## When to Use
+- User says "WEBAPP", "PROTOTYPE", "full-stack app", or "build a web application"
+- Need both backend API + frontend UI
+- Want speed + quality
+
+## What You'll Build
+- **Stack**: React + Vite + RESTful API (FastAPI/Express) + SQLite
+- **Timeline**: 1-4 hours from idea to working app
+- **Output**: Polished, functional prototype with keyboard shortcuts and clean UI
+
+## The 3-Step Process
+
+### Step 1: Design (5-10 min)
+Create a text-based design showing:
+
+```
+UI LAYOUT:
+[Header with Logo, Nav, Actions]
+[Main Content - Left Sidebar | Center Panel | Right Info]
+[Footer with Status]
+
+USER INTERACTIONS:
+1. Click "New" → Opens editor
+2. Type text → Updates state
+3. Press ⌘S → Saves via API
+4. Click "History" → Opens panel
+
+DATA MODELS:
+- Item: {id, content, created_at}
+- Revision: {id, item_id, content, timestamp}
+
+API ENDPOINTS:
+GET  /api/items          → List all
+POST /api/items          → Create new
+GET  /api/items/:id      → Get one
+PUT  /api/items/:id      → Update
+GET  /api/history/:id    → Get revisions
+```
+
+### Step 2: Get Approval (30 sec)
+Show the design → User says "looks good" → Start coding
+
+### Step 3: Build (1-3 hours)
+Use this stack (don't ask, just use):
+- **Frontend**: React + Vite
+- **Backend**: FastAPI (Python) or Express (Node)
+- **Database**: SQLite
+- **State**: useState + useEffect
+
+Build in order:
+1. Backend skeleton (30 min)
+2. Core features (1-2 hours)
+3. Polish + keyboard shortcuts (30 min)
+4. Test with WEBTEST
+
+---
+
+## Rules for Claude
+
+✅ **DO:**
+- Design mock UI before any code
+- Use React + RESTful API (default)
+- Start coding immediately after approval
+- Add keyboard shortcuts (⌘S, ⌘/, etc.)
+
+❌ **DON'T:**
+- Ask user to choose frameworks
+- Skip the design phase
+- Spend 30+ min researching simple features
+- Build custom solutions for standard problems
+
+## Core Principles
+
+1. **Design Before Code** - Mock UI + interactions first, then build
+2. **Use What You Know** - Familiar tools > "perfect" tools you don't know
+3. **Single Source of Truth** - One state for each piece of data, sync explicitly
+4. **Right Tool for Job** - Fighting a component's design? Wrong component
+5. **Test Early** - Automated tests + real user feedback before launch
+
+## Default Stack (Use This)
+
+```
+Frontend:  React + Vite
+Backend:   FastAPI (Python) or Express (Node)
+Database:  SQLite
+State:     useState + useEffect
+Styling:   Vanilla CSS
+```
+
+**Why?** Fast setup, familiar patterns, good docs, zero config database.
+
+**When to deviate:**
+- User explicitly requests different stack → use their choice
+- User needs SEO/SSR → use Next.js instead of Vite
+- User says "no code" → suggest Bubble/Retool (explain trade-offs)
+
+## Choosing Libraries
+
+**When to add a library:**
+- ✅ Would take > 1 hour to build from scratch
+- ✅ Well-maintained (updated in last 6 months)
+- ✅ You need > 30% of its features
+
+**When to build it yourself:**
+- ✅ Can be done in < 30 lines of code
+- ✅ Only need 10% of library features
+- ✅ Fighting the library's design
+
+**Quick research (spend max 15 min):**
+```bash
+# 1. Search
+WebSearch: "best [feature] library react 2025"
+
+# 2. Check npm
+npm info [package-name]
+# Look at: downloads/week, last publish, dependencies count
+
+# 3. Test
+# Try basic example - works in 15 min? Keep it. Doesn't? Try next option.
+```
+
+**Examples:**
+```javascript
+// ❌ Don't need library for:
+fetch()              // axios is overkill
+<textarea />         // don't force WYSIWYG when plain text works
+Intl.DateTimeFormat  // moment.js is heavy
+
+// ✅ Use library for:
+<MarkdownEditor />   // complex parsing + preview
+<DiffViewer />       // diff algorithm is non-trivial
+<CodeEditor />       // syntax highlighting + LSP
+```
+
+## Project Structure
+
+```
+project/
+├── backend/
+│   ├── server.py          # FastAPI app
+│   └── requirements.txt   # Python deps
+├── frontend/
+│   ├── src/
+│   │   ├── App.jsx       # Main component
+│   │   ├── App.css       # Styles
+│   │   └── main.jsx      # Entry point
+│   ├── package.json
+│   └── vite.config.js    # Vite config with proxy
+├── launcher-script        # CLI to start both servers
+├── install.sh            # Setup script
+└── README.md             # Documentation
+```
+
+## Build Workflow
+
+### Phase 0: Design (15-30 min)
+See "The 3-Step Process" above - create text-based design with UI layout, interactions, data models, and API endpoints. Show to user → get approval → start coding.
+
+### Phase 1: Backend + Frontend Skeleton (30 min)
+
+**Backend:**
+```python
+# Define models → Create CRUD endpoints → Test with curl
+# FastAPI example:
+@app.get("/api/items")
+async def list_items(): ...
+
+@app.post("/api/items")
+async def create_item(item: Item): ...
+```
+
+**Frontend:**
+```bash
+npm create vite@latest my-app -- --template react
+cd my-app && npm install
+# Configure vite.config.js proxy to backend
+# Test connection with /api/health endpoint
+```
+
+### Phase 2: Core Features (1-2 hours)
+- Build one feature at a time
+- useState for local state, useEffect for side effects
+- Single source of truth (one canonical state, sync others from it)
+- Test each feature before moving to next
+
+### Phase 3: Polish (30 min)
+```javascript
+// Add keyboard shortcuts
+useEffect(() => {
+  const handleKeyDown = (e) => {
+    if (e.metaKey) {
+      if (e.key === 's') { e.preventDefault(); save(); }
+      if (e.key === '/') { e.preventDefault(); showHelp(); }
+    }
+  };
+  window.addEventListener('keydown', handleKeyDown);
+  return () => window.removeEventListener('keydown', handleKeyDown);
+}, []);
+```
+
+- Add help modal (⌘/)
+- Add button active states
+- Add status feedback ("✓ Saved")
+- Add tooltips with keyboard shortcuts
+
+### Phase 4: Test (Use WEBTEST)
+```bash
+# Run automated tests
+WEBTEST  # Triggers testing-webapps skill
+
+# Manual checks:
+# - All buttons work
+# - Data persists after save
+# - No console errors
+# - Keyboard shortcuts work
+```
+
+## Common Mistakes
+
+### 1. Multiple Sources of Truth
+```javascript
+// ❌ Bad: Three states for same data
+const [editorContent, setEditorContent] = useState('');
+const [diffContent, setDiffContent] = useState('');
+const [previewContent, setPreviewContent] = useState('');
+
+// ✅ Good: One source, sync to views
+const [content, setContent] = useState('');
+useEffect(() => {
+  editorRef.current?.setContent(content);
+}, [viewMode, content]);
+```
+
+### 2. Fighting Component Design
+```javascript
+// ❌ Bad: Complex CSS to hide UI elements
+.editor .toolbar { display: none !important; }
+.editor .tabs { visibility: hidden !important; }
+
+// ✅ Good: Use simpler component
+<textarea value={content} onChange={e => setContent(e.target.value)} />
+```
+
+### 3. Hardcoded Config
+```javascript
+// ❌ Bad
+target: 'http://127.0.0.1:8765'
+
+// ✅ Good
+const port = process.env.VITE_BACKEND_PORT || '8765';
+target: `http://127.0.0.1:${port}`
+```
+
+### 4. CORS Issues
+```python
+# ✅ FastAPI CORS setup
+from fastapi.middleware.cors import CORSMiddleware
+
+app.add_middleware(
+    CORSMiddleware,
+    allow_origins=["http://localhost:5173"],
+    allow_methods=["*"],
+    allow_headers=["*"],
+)
+```
+
+## Code Patterns
+
+### Button States
+```css
+.btn { background: #007bff; transition: 0.2s; }
+.btn:hover { background: #0056b3; }
+.btn.active { background: #28a745; box-shadow: 0 2px 4px rgba(0,0,0,0.2); }
+```
+
+### Status Feedback
+```javascript
+const save = async () => {
+  try {
+    await saveToBackend();
+    setStatus('✓ Saved');
+    setTimeout(() => setStatus(''), 2000);
+  } catch (error) {
+    setStatus('❌ Error');
+  }
+};
+```
+
+### Help Modal
+```jsx
+{helpOpen && (
+  <div className="modal" onClick={() => setHelpOpen(false)}>
+    <div className="content" onClick={e => e.stopPropagation()}>
+      <h3>⌨️ Shortcuts</h3>
+      <kbd>⌘ S</kbd> Save
+      <kbd>⌘ /</kbd> Help
+    </div>
+  </div>
+)}
+```
+
+## Launcher Script
+
+Create a simple script to start both servers:
+
+```python
+#!/usr/bin/env python3
+import subprocess, webbrowser, time
+
+# Start backend
+backend = subprocess.Popen(
+    ["uvicorn", "server:app", "--port", "8000"],
+    cwd="./backend"
+)
+
+# Start frontend
+frontend = subprocess.Popen(
+    ["npm", "run", "dev"],
+    cwd="./frontend"
+)
+
+time.sleep(2)
+webbrowser.open("http://localhost:5173")
+
+try:
+    backend.wait()
+except KeyboardInterrupt:
+    backend.terminate()
+    frontend.terminate()
+```
+
+Make executable: `chmod +x launcher`
+
+## Quick Reference
+
+### Testing Checklist
+```bash
+# Automated
+WEBTEST  # Use testing-webapps skill
+
+# Manual
+- [ ] All buttons work
+- [ ] Keyboard shortcuts (⌘S, ⌘/)
+- [ ] Data persists
+- [ ] No console errors
+```
+
+### When to Add a Feature
+1. Solves real problem? ✓
+2. Can be done simply? ✓
+3. Fits core purpose? ✓
+
+If any = no → defer it
+
+### When to Refactor
+- Code duplicated 3+ times
+- Fighting component design
+- Adding features getting harder
+
+### View Modes Pattern
+```jsx
+const [viewMode, setViewMode] = useState('edit');
+const [content, setContent] = useState('');
+
+{viewMode === 'edit' && <Editor value={content} onChange={setContent} />}
+{viewMode === 'diff' && <DiffView content={content} previous={prev} />}
+{viewMode === 'preview' && <Preview content={content} />}
+```
+
+### Debugging
+1. Console errors (browser + terminal)
+2. Network tab (API responses)
+3. React DevTools (state flow)
+4. Use right component for the job?
+
+### Success Criteria
+- ✅ Core features work end-to-end
+- ✅ Keyboard shortcuts (⌘S, ⌘/)
+- ✅ No console errors
+- ✅ Data persists
+- ✅ Clean UI, no glitches
+
+## Real Example: mdedit (3 hours total)
+
+**Stack**: React + Vite + FastAPI + SQLite
+**Features**: 4 view modes, version history, visual diff, keyboard shortcuts
+
+**Key Decisions** (38 min research):
+- FastAPI > Flask (type hints, async)
+- SQLite > Postgres (zero config)
+- Toast UI Editor for rich editing, but **textarea for diff mode** (fighting component = wrong tool)
+- react-diff-viewer (GitHub-style, simple)
+- marked for preview (lightweight)
+
+**Lesson**: Don't fight components with CSS. Use simpler alternatives when needed.
+
+---
+
+## Key Reminders
+
+**Design → Code → Test**
+- Mock UI + interactions first
+- Use defaults (React + RESTful)
+- WEBTEST when done
+
+**Red Flags:**
+- Complex CSS hiding → wrong component
+- Multiple states for same data → refactor
+- Fighting a library → use different one
+- > 30 min on one bug → rethink approach
+
+**Best Prototypes Are:**
+1. Fast (1-4 hours)
+2. Simple (easy to change)
+3. Polished (shortcuts + help)
+4. Tested (no errors)
+