@martinffx/atelier 0.1.0

package/skills/code-perf/references/common-bottlenecks.md

@@ -0,0 +1,124 @@
+# Common Performance Bottlenecks
+
+## N+1 Query Problem
+
+### Symptom
+Many database queries when one should suffice.
+
+### Diagnosis
+```sql
+-- Enable query logging
+-- See N+1 queries in logs
+```
+
+### Solution
+
+**Before:**
+```python
+for user in users:
+    print(user.profile.name)  # Each = query
+```
+
+**After:**
+```python
+# Eager load
+users = db.query(users).options(joinedload(User.profile)).all()
+
+# Or batch
+profiles = ProfileService.get_many([u.id for u in users])
+```
+
+---
+
+## Memory Leaks
+
+### Symptom
+RSS grows over time, never回收es.
+
+### Diagnosis
+- Chrome DevTools Memory tab
+- heap snapshots before/after
+
+### Common Causes
+
+1. **Unclosed connections**
+2. **Growing caches** (no eviction)
+3. **Event listeners** (not removed)
+4. **Closures holding references**
+5. **Global variables**
+
+### Solution
+```javascript
+// Clear cache
+cache.clear();
+
+// Remove listener
+element.removeEventListener('click', handler);
+
+// Use weak refs
+const ref = new WeakRef(obj);
+```
+
+---
+
+## Blocking I/O
+
+### Symptom
+Thread/process blocked, can't handle other requests.
+
+### Solution
+
+```javascript
+// Before: blocking
+const data = fs.readFileSync('file.txt');
+
+// After: async
+const data = await fs.promises.readFile('file.txt');
+```
+
+---
+
+## Unnecessary Work
+
+### Symptom
+CPU high, doing redundant computation.
+
+### Examples
+
+1. **Validation twice** - in frontend and backend
+2. **Same calculation multiple times**
+3. **Processing data not needed**
+
+### Solution
+```javascript
+// Cache expensive computations
+const memoize = fn => {
+  const cache = new Map();
+  return (...args) => {
+    const key = JSON.stringify(args);
+    return cache.get(key) ?? fn(...args);
+  };
+};
+```
+
+---
+
+## Large Data Serialization
+
+### Symptom
+Slow JSON serialization of large objects.
+
+### Solution
+
+```javascript
+// Pagination
+const page = req.query.page || 1;
+const limit = 20;
+const users = await db.users.findMany({
+  take: limit,
+  skip: (page - 1) * limit
+});
+
+// Streams for large files
+stream.pipe(JSON.stringify());
+```

package/skills/code-perf/references/optimization-patterns.md

@@ -0,0 +1,167 @@
+# Optimization Patterns
+
+## Caching
+
+### When
+- Same data requested multiple times
+- Expensive computation
+- External API calls
+
+### Patterns
+
+**In-memory:**
+```javascript
+const cache = new Map();
+
+async function getUser(id) {
+  if (cache.has(id)) return cache.get(id);
+  const user = await db.find(id);
+  cache.set(id, user);
+  return user;
+}
+```
+
+**With TTL:**
+```javascript
+function withTTL(cache, ttl) {
+  return {
+    get(key) {
+      const item = cache.get(key);
+      if (item && Date.now() - item.timestamp < ttl) {
+        return item.value;
+      }
+      return null;
+    },
+    set(key, value) {
+      cache.set(key, { value, timestamp: Date.now() });
+    }
+  };
+}
+```
+
+**Distributed (Redis):**
+```javascript
+async function getCached(key, fetcher, ttl = 300) {
+  const cached = await redis.get(key);
+  if (cached) return JSON.parse(cached);
+  
+  const value = await fetcher();
+  await redis.set(key, JSON.stringify(value), 'EX', ttl);
+  return value;
+}
+```
+
+---
+
+## Lazy Loading
+
+### When
+- Large data sets
+- Heavy imports
+- Optional features
+
+### Patterns
+
+**Pagination:**
+```javascript
+async function getUsers(page = 1, limit = 20) {
+  return db.users.findMany({
+    take: limit,
+    skip: (page - 1) * limit,
+    orderBy: { createdAt: 'desc' }
+  });
+}
+```
+
+**Code splitting:**
+```javascript
+// Before: import everything
+import * as heavy from './heavy';
+
+// After: dynamic import
+const heavy = await import('./heavy');
+```
+
+**Virtual scrolling:**
+```javascript
+// Only render visible items
+<VirtualList items={users} height={400} itemHeight={40} />
+```
+
+---
+
+## Connection Pooling
+
+### When
+- Database connections
+- HTTP clients
+- WebSocket connections
+
+### Patterns
+
+```javascript
+import { Pool } from 'pg';
+
+const pool = new Pool({
+  max: 20,
+  idleTimeoutMillis: 30000,
+  connectionTimeoutMillis: 2000,
+});
+
+// Use throughout
+const result = await pool.query('SELECT * FROM users');
+```
+
+---
+
+## Batch Operations
+
+### When
+- Multiple inserts/updates
+- Multiple API calls
+
+### Patterns
+
+**Bulk insert:**
+```javascript
+// Before: N queries
+for (const item of items) {
+  await db.insert(item);
+}
+
+// After: 1 query
+await db.insertMany(items);
+```
+
+**Batch API calls:**
+```javascript
+// Use Promise.all with limit
+async function batch(items, fn, limit = 10) {
+  const results = [];
+  for (let i = 0; i < items.length; i += limit) {
+    const batch = items.slice(i, i + limit);
+    results.push(...await Promise.all(batch.map(fn)));
+  }
+  return results;
+}
+```
+
+---
+
+## Memoization
+
+```javascript
+function memoize(fn) {
+  const cache = new Map();
+  return (...args) => {
+    const key = JSON.stringify(args);
+    if (cache.has(key)) return cache.get(key);
+    const result = fn(...args);
+    cache.set(key, result);
+    return result;
+  };
+}
+
+// Usage
+const fib = memoize(n => n <= 1 ? n : fib(n-1) + fib(n-2));
+```

package/skills/code-perf/references/profiling-tools.md

@@ -0,0 +1,126 @@
+# Profiling Tools
+
+## Node.js
+
+### Built-in
+
+```bash
+# CPU profile
+node --prof app.js
+# Creates isolate-*.log
+
+# Analyze
+node --prof-process isolate-*.log
+
+# Memory
+node --inspect app.js
+# Open chrome://inspect
+```
+
+### clinic.js
+
+```bash
+npm install -g clinic
+
+# CPU + event loop
+clinic doctor -- node app.js
+
+# CPU flame graph
+clinic flame -- node app.js
+
+# Memory flame graph
+clinic泡沫 -- node app.js
+```
+
+---
+
+## Python
+
+### cProfile
+
+```bash
+# Profile
+python -m cProfile -o profile.prof app.py
+
+# Analyze (sorted by cumulative)
+python -m cProfile -s cumulative app.py
+
+# Analyze (sorted by time)
+python -m cProfile -s tottime app.py
+
+# Interactive
+python -m cProfile -m app.py
+```
+
+### line-profiler
+
+```bash
+pip install line_profiler
+
+# Add @profile decorator
+@profile
+def slow_function():
+    ...
+
+# Run
+kernprof -l -v app.py
+```
+
+---
+
+## Go
+
+### pprof
+
+```bash
+# CPU profile
+go test -cpuprofile=cpu.prof -bench=.
+go tool pprof cpu.prof
+
+# Memory profile
+go test -memprofile=mem.prof -bench=.
+go tool pprof mem.prof
+
+# Web UI
+go tool pprof -http=:8080 cpu.prof
+```
+
+### Built-in
+
+```bash
+# Runtime stats
+import runtime
+
+func printStats() {
+  var m runtime.MemStats
+  runtime.ReadMemStats(&m)
+  println(m.Alloc, m.TotalAlloc, m.Mallocs)
+}
+```
+
+---
+
+## Browser
+
+### Chrome DevTools
+
+1. Open DevTools (F12)
+2. Performance tab
+3. Click Record
+4. Perform action
+5. Click Stop
+6. Analyze flame graph
+
+### What to Look For
+
+- Long tasks (50ms+)
+- Large paint/layout
+- Expensive JS functions
+- Memory growth over time
+
+### Memory Tab
+
+- Take heap snapshot
+- Compare snapshots
+- Find detached DOM trees
+- Track memory growth

package/skills/code-review/SKILL.md

@@ -0,0 +1,78 @@
+---
+name: code-review
+description: Multi-agent code review with parallel specialized reviewers, architecture validation, and challenge validation. Use `rq` to request a review of diffs (defaults to main branch), `rs` to respond to review findings. Triggers on "review this", "review my code", "code review", "check for bugs", "audit this", when examining PRs, pull requests, branches, or diffs. Always asks user before applying fixes.
+argument-hint: "rq [branch] | rs"
+user-invocable: true
+---
+
+# Code Review Skill
+
+Multi-agent code analysis with parallel reviewers and challenge validation.
+
+Uses explicit subagent dispatch patterns from [code-subagents](../code-subagents/SKILL.md).
+
+## Prerequisites
+
+- **Required**: git
+
+## Arguments
+
+### Command Routing
+
+| Invocation | Behavior |
+|------------|----------|
+| *(no arguments)* | Review diff to main branch |
+| `rq` | Review diff to main branch |
+| `rq main` | Review diff to main branch |
+| `rq develop` | Review diff to develop branch |
+| `feat/foo` | Review diff to feat/foo (bare branch = rq) |
+| `rs` | Respond to review findings (interview mode) |
+
+## Subagent Architecture
+
+### rq (Request Review) Subagents
+
+| Step | Subagent | Uses | Parallel | Purpose |
+|------|----------|------|----------|---------|
+| 1 | Triage | `scout` agent | No | Detect context, select reviewers, identify skills to load |
+| 2 | Reviewers | `general` subagent | Yes (per reviewer) | Specialty analysis (loads detected skills) |
+| 3 | Synthesis | `general` subagent | No | Deduplicate findings |
+| 4 | Architect | `architect` agent | No | Architecture review |
+| 5 | Challenge | `oracle` agent | No | Validate findings with sequential-thinking |
+
+### rs (Respond to Review)
+
+No subagents. Interactive interview mode — see [rs.md](./references/rs.md).
+
+## Dispatch Patterns
+
+Follows [code-subagents](../code-subagents/SKILL.md) patterns:
+- **Parallel dispatch** for independent reviewers
+- **Sequential dispatch** for dependent steps
+- **Fresh subagent per task** — no context pollution
+- **Skill loading pre-step** before each analysis phase
+- **Error handling**: Log failures, continue with partial results
+
+## Agent Dispatch
+
+| Agent | Used In Step |
+|-------|--------------|
+| `scout` | Triage (context retrieval, file analysis) |
+| `architect` | Architect (architecture review) |
+| `oracle` | Challenge (validate findings, sequential-thinking) |
+| `general` | Reviewers, Synthesis |
+
+See [agents/](../agents/) for agent definitions.
+
+## References
+
+| Reference | Purpose |
+|-----------|---------|
+| [rq.md](./references/rq.md) | Request review workflow - detailed steps with prompts |
+| [rs.md](./references/rs.md) | Respond to review workflow - interview mode |
+| [reviewers.md](./references/reviewers.md) | Reviewer definitions and prompts |
+| [output.md](./references/output.md) | Output format specification |
+## Workflow Routing
+
+- No arguments, `rq`, or bare branch → [rq.md](./references/rq.md)
+- `rs` → [rs.md](./references/rs.md)

package/skills/code-review/references/output.md

@@ -0,0 +1,200 @@
+# Output Format
+
+## Structured Summary
+
+```markdown
+# Code Review: {module/files}
+
+## Summary
+{2-3 sentence overview of changes and overall quality}
+
+## Statistics
+- Files reviewed: N
+- Findings: N Critical, N High, N Medium, N Low
+- Pre-existing: N | Introduced: N
+
+## Critical (Fix before merge)
+
+### {Finding Title}
+
+- **Location**: `file:line`
+- **Severity**: Critical
+- **Pre-existing**: No
+- **Issue**: {What's wrong}
+- **Impact**: {Why this matters}
+- **Reasoning**:
+  <details>
+  <summary>Extended reasoning</summary>
+  {Detailed explanation of why this was flagged}
+  </details>
+- **Suggestion**: {How to fix}
+
+## High Priority
+
+### {Finding Title}
+{Same structure}
+
+## Medium Priority
+{Same structure}
+
+## Low Priority
+{Same structure}
+
+## Positive Findings
+
+- {What the code does well}
+- {Smart patterns to keep}
+- {Good practices observed}
+```
+
+---
+
+## Inline Finding Format
+
+For each finding, provide inline comment style:
+
+```
+[{file}:{line}] {Finding Title}
+Severity: {Critical/High/Medium/Low}
+Pre-existing: {Yes/No}
+Issue: {Brief description}
+Reasoning: {Why this matters}
+Suggestion: {Fix}
+```
+
+---
+
+## Severity Definitions
+
+| Severity | When to use | Examples |
+|----------|------------|----------|
+| Critical | Security vulnerability, data loss risk, crash possible | SQL injection, auth bypass, unhandled exception that crashes |
+| High | Bug causing wrong behavior, significant performance issue | Logic error, N+1 at scale, broken error handling |
+| Medium | Code smell, maintainability issue, minor bug | Missing validation, excess complexity, unclear naming |
+| Low | Style preference, optional improvement, educational | Naming inconsistency, missing docs, minor refactor |
+
+---
+
+## Pre-existing vs Introduced
+
+| Type | Definition | How to detect |
+|------|------------|---------------|
+| Pre-existing | Bug existed before this PR | Git blame shows code unchanged |
+| Introduced | Bug introduced by this PR | Code added/modified in diff |
+
+**Marking pre-existing:**
+- Check if the line was modified in the current diff
+- If unchanged but flagged, mark as pre-existing
+- Pre-existing findings are informational, not blocking
+
+---
+
+## Extended Reasoning
+
+Each finding includes a collapsible section with:
+
+1. **Why flagged**: What triggered the finding (pattern, heuristic, context)
+2. **Verification**: How it was validated (static analysis, pattern match, context)
+3. **Evidence**: Code snippets, references, or examples
+4. **Alternative view**: If uncertain, what else to consider
+
+Example:
+```markdown
+<details>
+<summary>Extended reasoning</summary>
+
+**Why flagged**: The `query` parameter is directly interpolated into SQL string without parameterization.
+
+**Verification**: Pattern match detected: `f"SELECT * FROM {table}"` - Python f-string in SQL context.
+
+**Evidence**: 
+```python
+query = f"SELECT * FROM users WHERE id = {user_id}"  # Line 42
+```
+
+**Alternative view**: If using a query builder or ORM, check if it handles escaping internally.
+</details>
+```
+
+---
+
+## Example Output
+
+```markdown
+# Code Review: src/auth/login.ts
+
+## Summary
+Implements OAuth login flow with token refresh. Generally well-structured with proper error handling. One security concern around token storage and a performance issue with token validation on every request.
+
+## Statistics
+- Files reviewed: 1
+- Findings: 1 Critical, 1 High, 0 Medium, 2 Low
+- Pre-existing: 1 | Introduced: 3
+
+## Critical (Fix before merge)
+
+### Token stored in localStorage
+
+- **Location**: `src/auth/login.ts:45`
+- **Severity**: Critical
+- **Pre-existing**: No
+- **Issue**: Access token stored in localStorage, vulnerable to XSS
+- **Impact**: Any XSS vulnerability exposes user tokens
+- **Reasoning**:
+  <details>
+  <summary>Extended reasoning</summary>
+  
+  **Why flagged**: localStorage is accessible to any JavaScript on the page.
+  
+  **Verification**: Direct localStorage API usage detected.
+  
+  **Evidence**:
+  ```typescript
+  localStorage.setItem('accessToken', token); // Line 45
+  ```
+  
+  **Alternative view**: If using httpOnly cookies is not possible, consider short-lived tokens with refresh rotation.
+  </details>
+- **Suggestion**: Use httpOnly cookies or secure session storage
+
+## High Priority
+
+### Token validation on every request
+
+- **Location**: `src/auth/middleware.ts:12`
+- **Severity**: High
+- **Pre-existing**: Yes
+- **Issue**: Token validated against auth server on every request
+- **Impact**: Adds 50-200ms latency per request
+
+## Low Priority
+
+### Missing JSDoc on public function
+
+- **Location**: `src/auth/login.ts:23`
+- **Severity**: Low
+- **Pre-existing**: No
+- **Issue**: `validateToken` lacks documentation
+
+### Inconsistent naming: userId vs user_id
+
+- **Location**: `src/auth/login.ts:67`
+- **Severity**: Low
+- **Pre-existing**: Yes
+- **Issue**: Mixed snake_case and camelCase in same file
+
+## Positive Findings
+
+- Clean separation of OAuth flow into dedicated functions
+- Proper error handling with typed error classes
+- Token refresh logic handles edge cases well
+```
+
+---
+
+## Implementation Notes
+
+1. **Skills to load** are determined by Triage based on detected language/framework
+2. **Pre-existing detection** requires git blame check (not just diff)
+3. **Extended reasoning** should be collapsible in markdown renderers
+4. **Positive findings** help balance the review tone