@sylphx/flow 1.0.5 → 1.1.0

package/assets/knowledge/stacks/react-app.md

@@ -0,0 +1,232 @@
+---
+name: React Application
+description: React patterns, hooks, state management, performance, common bugs and fixes
+---
+
+# React Development
+
+## State Management Decision Tree
+```
+Used by 3+ unrelated components?
+├─ NO → useState in common ancestor
+└─ YES → Server data?
+    ├─ YES → React Query/SWR (not state!)
+    └─ NO → Complex actions?
+        ├─ YES → useReducer / Zustand
+        └─ NO → Context API
+```
+
+## Common Bugs & Fixes
+
+### Infinite useEffect Loop
+
+**Object/array deps:**
+```javascript
+// BAD
+useEffect(() => { fetch(users) }, [users])
+
+// FIX
+useEffect(() => { fetch(users) }, [userIds.join(',')])  // Primitive
+```
+
+**Unconditional state update:**
+```javascript
+// BAD
+useEffect(() => { setCount(count + 1) }, [count])
+
+// FIX
+useEffect(() => {
+  if (condition && count < max) setCount(count + 1)
+}, [count, condition, max])
+```
+
+### Stale Closure
+
+```javascript
+// BAD - uses initial count
+const [count, setCount] = useState(0)
+useEffect(() => {
+  setInterval(() => setCount(count + 1), 1000)
+}, [])
+
+// FIX: Functional update
+setInterval(() => setCount(c => c + 1), 1000)
+
+// FIX: useRef (complex cases)
+const countRef = useRef(count)
+useEffect(() => { countRef.current = count })
+useEffect(() => {
+  setInterval(() => setCount(countRef.current + 1), 1000)
+}, [])
+```
+
+### Missing Cleanup
+
+```javascript
+// BAD
+useEffect(() => {
+  subscribeToData(setData)
+}, [])
+
+// GOOD
+useEffect(() => {
+  const unsubscribe = subscribeToData(setData)
+  return () => unsubscribe()
+}, [])
+```
+
+## Performance
+
+**Optimize when:**
+- Profiler shows slowness
+- User-visible lag
+- 100+ renders/second
+
+**Profile first, optimize second.**
+
+### Unnecessary Re-renders
+
+```javascript
+// BAD
+function Parent() {
+  const config = { theme: 'dark' }
+  return <Child config={config} />
+}
+
+// GOOD
+const config = useMemo(() => ({ theme: 'dark' }), [])
+```
+
+**Order:**
+1. Fix parent
+2. useMemo/useCallback
+3. Profile
+4. React.memo (last resort)
+
+### Virtualization
+
+**When**: 500+ items, laggy scroll
+
+```javascript
+import { FixedSizeList } from 'react-window'
+<FixedSizeList height={600} itemCount={items.length} itemSize={35}>
+  {({ index, style }) => <div style={style}>{items[index]}</div>}
+</FixedSizeList>
+```
+
+### Debounce Search
+
+```javascript
+const debouncedQuery = useDebounce(query, 300)
+useEffect(() => {
+  if (debouncedQuery) searchAPI(debouncedQuery)
+}, [debouncedQuery])
+```
+
+## Data Fetching
+
+**Never** useState for server data. You lose: caching, loading, errors, refetching, race conditions.
+
+**Use React Query:**
+```javascript
+const { data, isLoading, error } = useQuery({
+  queryKey: ['users'],
+  queryFn: () => fetch('/api/users').then(r => r.json())
+})
+
+const mutation = useMutation({
+  mutationFn: (user) => fetch('/api/users', { method: 'POST', body: JSON.stringify(user) }),
+  onSuccess: () => queryClient.invalidateQueries(['users'])
+})
+```
+
+## Forms
+
+**React Hook Form** (recommended):
+```javascript
+const { register, handleSubmit, formState: { errors } } = useForm()
+
+<form onSubmit={handleSubmit(onSubmit)}>
+  <input {...register('email', {
+    required: 'Required',
+    pattern: { value: /^[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}$/i }
+  })} />
+  {errors.email && <span>{errors.email.message}</span>}
+</form>
+```
+
+**Controlled vs Uncontrolled:**
+- Controlled: Validation on change, dependent fields
+- Uncontrolled: Simple submit, file inputs
+
+## Accessibility
+
+**Critical:**
+1. Semantic HTML (`<button>` not `<div onClick>`)
+2. Alt text (meaningful or `alt=""`)
+3. Form labels (every input)
+4. Keyboard nav (Tab, Enter/Space)
+5. Focus visible
+
+**Test**: VoiceOver (Cmd+F5), Tab through app
+
+```javascript
+// BAD
+<div onClick={handleClick}>Click</div>
+
+// GOOD
+<button onClick={handleClick}>Click</button>
+```
+
+## Debug Workflow
+
+**Component not updating:**
+1. State changing? (console.log)
+2. setState called?
+3. Mutating state? (must create new)
+4. Memoized with stale props?
+
+**Performance:**
+1. Profile (React DevTools)
+2. Identify slow component
+3. Check: Unnecessary re-renders?
+4. Check: Expensive computation?
+5. Optimize bottleneck only
+
+## Production Patterns
+
+**Error Boundary:**
+```javascript
+class ErrorBoundary extends React.Component {
+  state = { hasError: false }
+  static getDerivedStateFromError() { return { hasError: true } }
+  componentDidCatch(error, info) { logError(error, info) }
+  render() {
+    return this.state.hasError ? <ErrorFallback /> : this.props.children
+  }
+}
+```
+
+**Code Splitting:**
+```javascript
+const Dashboard = lazy(() => import('./Dashboard'))
+<Suspense fallback={<Loading />}>
+  <Dashboard />
+</Suspense>
+```
+
+## Key Decisions
+
+**State unclear?** → useState, refactor later
+**Performance slow?** → Profile first
+**Form complex?** → React Hook Form
+**Data fetching?** → React Query
+**Not sure?** → Simpler option
+
+## Anti-Patterns
+
+❌ Server data in useState
+❌ Premature optimization
+❌ React.memo everywhere
+❌ Missing cleanup
+❌ Div as button

package/assets/knowledge/universal/deployment.md

@@ -0,0 +1,109 @@
+---
+name: Deployment & DevOps
+description: Docker, CI/CD, monitoring, scaling, infrastructure
+---
+
+# Deployment & DevOps
+
+## Deployment Strategies
+
+**Blue-Green**: Two environments (blue=current, green=new) → test → switch. Zero downtime, instant rollback, 2x cost.
+
+**Rolling**: Replace gradually (10% at a time). No extra infrastructure, lower risk, slower.
+
+**Canary**: Route small % to new version. Test in production, minimal risk, complex routing.
+
+**Feature Flags**: Deploy code disabled, enable via config. Decouple deploy from release, A/B testing, kill switches.
+
+## CI/CD Pipeline
+
+### Continuous Integration (On Every Commit)
+1. Run linter
+2. Run tests (unit, integration)
+3. Build application
+4. Security scanning
+5. Code quality checks
+
+**Best practices**: Fast feedback (< 10min), fail fast, keep builds green
+
+### Continuous Deployment
+**Stages**: CI passes → deploy staging → E2E tests → deploy production → health checks → rollback if failed
+
+**Tools**: GitHub Actions, GitLab CI, Jenkins, CircleCI
+
+## Containerization (Docker)
+
+### Best Practices
+- Multi-stage builds (build → slim runtime)
+- Slim/alpine images
+- Layer caching (deps before code)
+- .dockerignore
+- Don't run as root
+
+## Orchestration (Kubernetes)
+
+**Core**: Pod (containers), Deployment (replicas), Service (load balancer), Ingress (routing), ConfigMap (config), Secret (sensitive)
+
+**Scaling**:
+- Horizontal Pod Autoscaler: Scale based on CPU/memory, min/max replicas
+- Cluster Autoscaler: Add/remove nodes
+
+## Monitoring & Observability
+
+### Logs
+**Structured logging**: JSON format with level, timestamp, message, context (user_id, trace_id)
+
+**Centralized**: ELK, Datadog, CloudWatch
+**Best practices**: Log errors with context, trace IDs, don't log secrets, set retention
+
+### Metrics
+**Track**: Request rate, error rate, response time (latency), resource usage (CPU, memory, disk)
+**Tools**: Prometheus, Grafana, Datadog
+
+### Tracing
+**Distributed tracing**: Track requests across services, identify bottlenecks
+**Tools**: Jaeger, Zipkin, Datadog APM
+
+### Alerting
+**Alert on**: Error rate > threshold, response time > SLA, resource exhaustion, service down
+**Best practices**: Actionable only, include runbooks, escalation policies, on-call rotation
+
+## High Availability
+
+### Load Balancing
+**Algorithms**: Round robin (equal), least connections (least busy), IP hash (consistent)
+**Health checks**: HTTP (/_health), TCP, check every 10-30s, remove unhealthy
+
+### Database Replication
+**Primary-Replica**: Writes to primary, reads from replicas, async (eventual consistency)
+**Multi-Primary**: Write to any, conflict resolution needed, complex but highly available
+
+### Backup & Disaster Recovery
+**Backups**: Automated daily, retention (7 days, 4 weeks, 12 months), test restores, offsite/cross-region
+**RTO/RPO**: RTO (recovery time), RPO (data loss acceptable)
+
+## Security
+
+**Network**: Firewall (whitelist), private subnets for DBs, VPN for internal, DDoS protection
+**Secrets**: Never commit to git, use secret managers (AWS Secrets Manager, Vault), rotate regularly, least privilege
+**SSL/TLS**: HTTPS everywhere, auto-renewal (Let's Encrypt), strong ciphers, HSTS headers
+**Compliance**: Encryption at rest, encryption in transit, access logs, security audits
+
+## Cost Optimization
+
+**Right-sizing**: Monitor usage, scale down over-provisioned, spot/preemptible for non-critical
+**Auto-scaling**: Scale down off-peak, scale up peak
+**Reserved Instances**: 1-3 year commit for 30-70% discount (predictable workloads)
+**Storage**: Lifecycle policies (move old to cheaper), delete unused, compress backups
+
+## Common Patterns
+
+**Immutable Infrastructure**: Never modify servers, deploy new, terminate old
+**Infrastructure as Code**: Terraform, CloudFormation, Pulumi → version controlled, reproducible
+**GitOps**: Git as truth, auto-deploy on merge, drift detection (ArgoCD, Flux)
+
+## Best Practices
+
+**Documentation**: Runbooks, architecture diagrams, incident response, on-call guides
+**Change Management**: Review process, deployment windows, rollback procedures, communication
+**Incident Response**: Detect → Triage → Mitigate → Resolve → Post-mortem

package/assets/knowledge/universal/performance.md

@@ -0,0 +1,121 @@
+---
+name: Performance Optimization
+description: Profiling, caching, optimization patterns across frontend and backend
+---
+
+# Performance Optimization
+
+## Measure First
+
+**Never optimize without measuring.**
+
+### Tools
+**Frontend**: Chrome DevTools, Lighthouse, React Profiler
+**Backend**: APM (New Relic, Datadog), query explain plans
+
+### Metrics
+**Frontend**: FCP < 1.8s, LCP < 2.5s, CLS < 0.1, FID < 100ms, TTI < 3.5s
+**Backend**: Response < 200ms (p95), error rate < 1%, DB query < 100ms
+
+## Frontend Optimization
+
+### Bundle Size
+**Analyze**: webpack-bundle-analyzer
+**Reduce**: Tree-shaking, code splitting, lighter alternatives, remove unused deps
+
+### Loading Strategy
+1. Inline critical CSS
+2. Defer non-critical CSS
+3. Async non-critical JS
+4. Lazy load below-fold images
+5. Code splitting: `lazy(() => import('./Heavy'))`
+
+### Images
+- WebP format (smaller, better quality)
+- Responsive (srcset)
+- Lazy loading (loading="lazy")
+- CDN delivery
+- Optimize: compress, resize, correct format
+
+### Caching
+**Browser**: Cache-Control headers, versioned assets (hash), service worker
+**CDN**: Static assets, edge caching, geographic distribution
+
+## React Performance
+
+### Avoid Re-renders
+**Identify**: React DevTools Profiler, "Why did you render" library
+
+**Fix**: React.memo (pure components), useMemo (expensive computations), useCallback (function props), move static data outside component
+
+### Virtualization
+**Problem**: 10,000+ items
+**Solution**: react-window / react-virtualized (render only visible)
+
+### Debounce/Throttle
+- **Debounce**: Wait for user to stop (search input)
+- **Throttle**: Limit frequency (scroll handler)
+
+## Backend Performance
+
+### Database Optimization
+
+**Indexes**: Index WHERE/JOIN/ORDER BY columns, composite for multi-column, don't over-index (slows writes)
+
+**Queries**: EXPLAIN to analyze, avoid SELECT *, LIMIT for pagination, connection pooling, batch operations
+
+**N+1 Problem**: See sql.md for patterns
+
+### Caching Strategy
+
+**What**: Query results, API responses, computed values, sessions
+**Invalidation**: Time-based (TTL), event-based (on update), hybrid
+**Layers**: App memory (fastest) → Redis → DB cache → CDN
+
+### Async Processing
+
+**Background**: Email, image processing, reports, aggregation
+**Tools**: Job queues (Bull, BullMQ), message queues (RabbitMQ, Kafka), serverless
+
+### Response Time
+- Gzip compression
+- HTTP/2 multiplexing
+- Keep-alive connections
+- Parallel requests
+
+## Database Performance
+
+### Connection Management
+- Connection pooling (reuse)
+- Configure pool size
+- Monitor usage
+- Close idle connections
+
+### Query Performance
+**Slow query log**: Identify > 100ms, add indexes, rewrite, consider denormalization
+
+**Pagination**: See sql.md for cursor-based vs offset patterns
+
+### Scaling
+**Vertical**: Bigger server (limited)
+**Horizontal**: Read replicas (scale reads), sharding (partition data), DB-per-service
+
+## Monitoring
+
+**Frontend**: RUM, synthetic monitoring, Core Web Vitals, error tracking (Sentry)
+**Backend**: APM, log aggregation (ELK, Datadog), alerting, distributed tracing
+
+**Continuous**:
+1. Set budgets
+2. Monitor metrics
+3. Alert on regression
+4. Profile bottlenecks
+5. Optimize
+6. Measure impact
+
+## Common Pitfalls
+
+❌ **Premature optimization**: Optimize AFTER measuring, focus on biggest bottlenecks, 80/20 rule
+❌ **Over-caching**: Invalidation is hard, stale data bugs, memory limits → Cache stable, expensive data only
+❌ **Ignoring network**: Minimize requests, reduce payload, use HTTP/2, consider latency
+❌ **Blocking operations**: Never block event loop (Node), use async for I/O, worker threads for CPU tasks

package/assets/knowledge/universal/security.md

@@ -0,0 +1,79 @@
+---
+name: Security Best Practices
+description: OWASP, authentication, authorization, vulnerabilities, secure coding
+---
+
+# Security Best Practices
+
+## OWASP Top 10
+
+### SQL Injection
+**Never** concatenate user input into SQL
+```javascript
+// BAD: Vulnerable
+db.query(`SELECT * FROM users WHERE id = ${userId}`)
+
+// GOOD: Parameterized
+db.query('SELECT * FROM users WHERE id = $1', [userId])
+```
+
+### XSS (Cross-Site Scripting)
+- Sanitize/escape user content before rendering
+- Use CSP headers
+- Never use `dangerouslySetInnerHTML` without sanitization
+- Validate server-side, not just client
+
+### Authentication & Authorization
+- Use established libraries (Passport, NextAuth, Auth0)
+- Hash passwords (bcrypt/argon2), never plain text
+- Rate limit login endpoints
+- httpOnly, secure, sameSite cookies for tokens
+- Separate authentication (who) from authorization (what)
+
+### CSRF (Cross-Site Request Forgery)
+- CSRF tokens for state-changing ops
+- Check Origin/Referer headers
+- SameSite cookie attribute
+
+## Secrets Management
+**Never** commit secrets to git (.env in .gitignore)
+- Environment variables for secrets
+- Rotate credentials regularly
+- Use secret managers (AWS Secrets Manager, Vault)
+
+## Input Validation
+- Validate server-side (client is UX only)
+- Whitelist approach: Define allowed, reject all else
+- Sanitize file uploads (check type, size, scan)
+- Schema validation (Zod, Joi)
+
+## API Security
+- HTTPS everywhere
+- Rate limiting
+- Validate Content-Type headers
+- API keys/tokens with least privilege
+- Log security events (failed logins, unusual activity)
+
+## Common Vulnerabilities
+
+### Path Traversal
+Validate file paths, never trust user input. Use path.resolve() and verify within allowed directory.
+
+### Command Injection
+Never pass user input to shell commands. If unavoidable, use libraries that escape properly.
+
+### JWT Security
+- Verify signature on every request
+- Check expiration (exp claim)
+- Short expiration (15min) + refresh tokens
+- Store in httpOnly cookies, not localStorage
+
+## Security Checklist
+- [ ] All inputs validated/sanitized
+- [ ] Secrets in environment variables
+- [ ] HTTPS enforced
+- [ ] Rate limiting on sensitive endpoints
+- [ ] Auth + authz on protected routes
+- [ ] CORS configured
+- [ ] Security headers (CSP, X-Frame-Options)
+- [ ] Dependencies updated (npm audit)

package/assets/knowledge/universal/testing.md

@@ -0,0 +1,111 @@
+---
+name: Testing Strategies
+description: Unit, integration, e2e, TDD, mocking, test architecture
+---
+
+# Testing Strategies
+
+## Testing Pyramid
+```
+      /\
+     /E2E\      (10% - Slow, expensive, brittle)
+    /------\
+   /Integr.\   (20% - Medium speed/cost)
+  /----------\
+ /Unit Tests \ (70% - Fast, cheap, stable)
+```
+
+## Unit Testing
+
+### What to Test
+**Do**: Business logic, edge cases, error handling, pure functions
+**Don't**: Third-party libraries, implementation details, trivial code
+
+### Best Practices
+
+**AAA Pattern**: Arrange → Act → Assert
+
+**Test names**: Describe behavior (`returns 404 when user not found`)
+
+**One assertion per test** (ideally)
+
+### Mocking
+
+**When**: External APIs, databases, file system, time/date, random values
+**How**: Mock boundaries only, not internal code
+
+## Integration Testing
+
+**Test**: Multiple units together, DB interactions, API endpoints, auth flows
+
+**Database**: Use test DB, reset before each test, use transactions (rollback after)
+
+## E2E Testing
+
+**Test**: Critical user flows only (happy path + common errors)
+**Example**: Login → Create → Edit → Delete → Logout
+
+**Stability**: Use data-testid, wait for elements, retry assertions, headless in CI
+**Speed**: Run parallel, skip UI steps (use API for setup)
+
+## TDD (Test-Driven Development)
+
+### Red-Green-Refactor
+1. Write failing test
+2. Write minimal code to pass
+3. Refactor while keeping tests green
+
+**Good for**: Well-defined requirements, complex logic, bug fixes
+**Not for**: Prototypes, UI styling, simple CRUD
+
+## Testing Patterns
+
+### Parameterized Tests
+```javascript
+test.each([
+  [1, 2, 3],
+  [2, 3, 5],
+])('adds %i + %i = %i', (a, b, expected) => {
+  expect(add(a, b)).toBe(expected)
+})
+```
+
+### Test Doubles
+- **Stub**: Returns canned response
+- **Mock**: Verifies interactions
+- **Spy**: Records calls
+- **Fake**: Working implementation (in-memory DB)
+
+## Code Coverage
+
+**Metrics**: Line, branch, function, statement
+**Target**: 80%+ (critical paths 100%)
+
+**Don't chase numbers**: Coverage ≠ quality. 70% with good tests > 95% shallow tests.
+
+## React Component Testing
+
+**React Testing Library**: Test user interactions, not implementation
+
+**Query priority**: getByRole > getByLabelText > getByText > getByTestId
+
+## Performance Testing
+
+**Load Testing Metrics**: RPS, response time (p50/p95/p99), error rate, resource usage
+
+**Scenarios**: Baseline (normal), stress (peak 3x), spike (sudden surge), soak (sustained hours)
+
+**Tools**: k6, Artillery, JMeter
+
+## CI/CD Integration
+
+**On commit**: Linting, unit tests, integration tests
+**On PR**: Full suite, coverage report, benchmarks
+**On deploy**: E2E (staging), smoke tests (production)
+
+## Common Pitfalls
+
+❌ **Testing implementation** → Test public API/behavior
+❌ **Brittle tests** → Use semantic queries, independent tests, proper waits
+❌ **Slow tests** → Mock external calls, parallelize, focus on unit tests
+❌ **Flaky tests** → Investigate root cause (timing, shared state, external deps)

package/assets/output-styles/silent.md

@@ -0,0 +1,23 @@
+---
+name: Silent
+description: Execute without narration - speak only through tool calls and commits
+---
+
+# Silent Execution Style
+
+## During Execution
+
+Use tool calls only. Do not produce text responses.
+
+User sees your work through:
+- Tool call executions
+- File creation and modifications
+- Test results
+
+## At Completion
+
+Document in commit message or PR description.
+
+## Never
+
+Do not narrate actions, explain reasoning, report status, or provide summaries during execution.