devflow-kit 1.8.3 → 2.0.1

package/shared/skills/knowledge-persistence/SKILL.md

@@ -1,128 +0,0 @@
----
-name: knowledge-persistence
-description: >-
-  This skill should be used when recording architectural decisions or pitfalls
-  to project knowledge files, or when loading prior decisions and known pitfalls
-  for context during investigation, specification, or review.
-user-invocable: false
-allowed-tools: Read, Write, Bash
----
-
-# Knowledge Persistence
-
-Record architectural decisions and pitfalls to `.memory/knowledge/` files. This is the single source of truth for the extraction procedure — commands reference this skill instead of inlining the steps.
-
-## Iron Law
-
-> **SINGLE SOURCE OF TRUTH**
->
-> All knowledge extraction follows this procedure exactly. Commands never inline
-> their own extraction steps — they read this skill and follow it.
-
----
-
-## File Locations
-
-```
-.memory/knowledge/
-├── decisions.md    # ADR entries (append-only)
-└── pitfalls.md     # PF entries (area-specific gotchas)
-```
-
-## File Formats
-
-### decisions.md (ADR entries)
-
-**Template header** (create if file missing):
-```
-<!-- TL;DR: 0 decisions. Key: -->
-# Architectural Decisions
-
-Append-only. Status changes allowed; deletions prohibited.
-```
-
-**Entry format**:
-```markdown
-## ADR-{NNN}: {Title}
-
-- **Date**: {YYYY-MM-DD}
-- **Status**: Accepted
-- **Context**: {Why this decision was needed}
-- **Decision**: {What was decided}
-- **Consequences**: {Tradeoffs and implications}
-- **Source**: {command and identifier, e.g. `/implement TASK-123`}
-```
-
-### pitfalls.md (PF entries)
-
-**Template header** (create if file missing):
-```
-<!-- TL;DR: 0 pitfalls. Key: -->
-# Known Pitfalls
-
-Area-specific gotchas, fragile areas, and past bugs.
-```
-
-**Entry format**:
-```markdown
-## PF-{NNN}: {Short description}
-
-- **Area**: {file paths or module names}
-- **Issue**: {What goes wrong}
-- **Impact**: {Consequences if hit}
-- **Resolution**: {How to fix or avoid}
-- **Source**: {command and identifier, e.g. `/code-review branch-name`}
-```
-
----
-
-## Extraction Procedure
-
-Follow these steps when recording decisions or pitfalls:
-
-1. **Read** the target file (`.memory/knowledge/decisions.md` or `.memory/knowledge/pitfalls.md`). If it doesn't exist, create it with the template header above.
-2. **Check capacity** — count `## ADR-` or `## PF-` headings. If >=50, log "Knowledge base at capacity — skipping new entry" and stop.
-3. **Find next ID** — find highest NNN via regex (`/^## ADR-(\d+)/` or `/^## PF-(\d+)/`), default to 0. Increment by 1.
-4. **Deduplicate** (pitfalls only) — skip if an entry with the same Area + Issue already exists.
-5. **Append** the new entry using the format above.
-6. **Update TL;DR** — rewrite the `<!-- TL;DR: ... -->` comment on line 1 to reflect the new count and key topics.
-
-## Lock Protocol
-
-When writing, use a mkdir-based lock:
-- Lock path: `.memory/.knowledge.lock`
-- Timeout: 30 seconds (fail if lock not acquired)
-- Stale recovery: if lock directory is >60 seconds old, remove it and retry
-- Release lock after write completes (remove lock directory)
-
-## Loading Knowledge for Context
-
-When a command needs prior knowledge as input (not recording):
-
-1. Read `.memory/knowledge/decisions.md` if it exists
-2. Read `.memory/knowledge/pitfalls.md` if it exists
-3. Pass content as context to downstream agents — prior decisions constrain scope, known pitfalls inform investigation
-
-If neither file exists, skip silently. No error, no empty-file creation.
-
-## Operation Budget
-
-Recording: do inline (no agent spawn), 2-3 Read/Write operations total.
-Loading: 1-2 Read operations, pass as context string.
-
----
-
-## Extended References
-
-For entry examples and status lifecycle details:
-- `references/examples.md` - Full decision and pitfall entry examples
-
----
-
-## Success Criteria
-
-- [ ] Entry appended with correct sequential ID
-- [ ] No duplicate pitfalls (same Area + Issue)
-- [ ] TL;DR comment updated with current count
-- [ ] Lock acquired before write, released after
-- [ ] Capacity limit (50) respected

package/shared/skills/knowledge-persistence/references/examples.md

@@ -1,44 +0,0 @@
-# Knowledge Persistence Examples
-
-## Decision Entry Example
-
-```markdown
-## ADR-001: Use mkdir-based locks for concurrent session serialization
-
-- **Date**: 2026-03-03
-- **Status**: Accepted
-- **Context**: Multiple Claude Code sessions can run on the same project simultaneously (different terminals, SSH, etc.). Memory writes must serialize to prevent corruption.
-- **Decision**: Use `mkdir` as an atomic lock primitive. Lock directory at `.memory/.knowledge.lock`. 30-second timeout with 60-second stale recovery.
-- **Consequences**: Simple, cross-platform, no external dependencies. Cannot detect holder PID if lock is stale — relies on age-based recovery. Sufficient for low-contention writes.
-- **Source**: `/implement #99`
-```
-
-## Pitfall Entry Example
-
-```markdown
-## PF-001: Orphaned teams variants silently skipped
-
-- **Area**: plugins/devflow-*/commands/*-teams.md, src/cli/installer
-- **Issue**: The installer iterates base `.md` files and looks up matching `-teams.md` variants. A `-teams.md` file without a corresponding base `.md` is silently ignored during installation.
-- **Impact**: Teams variant appears committed but never installs. Users on `--teams` mode silently get no command.
-- **Resolution**: Always create the base `.md` file first. CI should validate that every `-teams.md` has a matching base file.
-- **Source**: `/code-review feat/agent-teams`
-```
-
-## Status Lifecycle (Decisions Only)
-
-Decisions support status transitions:
-- `Accepted` — current, in effect
-- `Superseded by ADR-NNN` — replaced by a newer decision
-- `Deprecated` — no longer relevant, kept for history
-
-Pitfalls have no status field — they remain until manually removed.
-
-## Deduplication Logic (Pitfalls Only)
-
-Before appending a new pitfall, check existing entries:
-1. Extract `Area` and `Issue` from the new entry
-2. Compare against all existing `PF-*` entries
-3. If both Area AND Issue match an existing entry (case-insensitive substring), skip
-
-This prevents recording the same gotcha from multiple review cycles.

package/shared/skills/performance-patterns/SKILL.md

@@ -1,154 +0,0 @@
----
-name: performance-patterns
-description: This skill should be used when reviewing code for N+1 queries, memory leaks, or I/O bottlenecks.
-user-invocable: false
-allowed-tools: Read, Grep, Glob
----
-
-# Performance Patterns
-
-Domain expertise for performance optimization and bottleneck detection. Use alongside `review-methodology` for complete performance reviews.
-
-## Iron Law
-
-> **MEASURE BEFORE OPTIMIZING**
->
-> Premature optimization is the root of all evil. Profile first, then optimize. Every
-> performance claim requires benchmarks. "It feels slow" is not a metric. O(n) with small n
-> beats O(1) with huge constants. Optimize for the real bottleneck, not the imagined one.
-
----
-
-## Performance Categories
-
-### 1. Algorithmic Issues
-
-**N+1 Query Problem** - Database query inside a loop.
-
-```typescript
-// VIOLATION: 1 + N queries
-for (const user of users) {
-  user.orders = await db.orders.findByUserId(user.id);
-}
-
-// CORRECT: Batch query with Map lookup
-const orders = await db.orders.findAll({ where: { userId: userIds } });
-const ordersByUser = new Map(groupBy(orders, 'userId'));
-users.forEach(u => u.orders = ordersByUser.get(u.id) || []);
-```
-
-**O(n^2) Patterns** - Nested loops or linear search in loop.
-
-```typescript
-// VIOLATION: includes() is O(n), called n times
-items.filter(item => selected.includes(item.id));
-
-// CORRECT: Use Set for O(1) lookup
-const selectedSet = new Set(selected);
-items.filter(item => selectedSet.has(item.id));
-```
-
-### 2. Memory Issues
-
-**Memory Leaks** - Resources not cleaned up.
-
-```typescript
-// VIOLATION: Listener never removed
-window.addEventListener('resize', this.handleResize);
-
-// CORRECT: Track and cleanup
-this.cleanup = () => window.removeEventListener('resize', this.handleResize);
-```
-
-**Unbounded Caches** - Collections that grow forever.
-
-```typescript
-// VIOLATION: Cache grows indefinitely
-const cache = new Map<string, Result>();
-
-// CORRECT: LRU cache with limit
-const cache = new LRU<string, Result>({ max: 1000 });
-```
-
-### 3. I/O Issues
-
-**Blocking Operations** - Synchronous I/O in request path.
-
-```typescript
-// VIOLATION: Blocks event loop
-const config = fs.readFileSync('./config.json');
-
-// CORRECT: Async I/O
-const config = await fs.promises.readFile('./config.json');
-```
-
-**Sequential When Parallel Possible** - Independent operations run serially.
-
-```typescript
-// VIOLATION: Sequential execution
-const user = await getUser(id);
-const orders = await getOrders(id);
-
-// CORRECT: Parallel execution
-const [user, orders] = await Promise.all([getUser(id), getOrders(id)]);
-```
-
-### 4. Database Issues
-
-Missing indexes, SELECT *, missing pagination. See `references/violations.md`.
-
-### 5. Frontend Issues
-
-Unnecessary re-renders, missing virtualization, missing code splitting. See `references/violations.md`.
-
----
-
-## Extended References
-
-For comprehensive examples and detection techniques:
-
-| Reference | Content |
-|-----------|---------|
-| `references/violations.md` | Extended violation examples by category |
-| `references/patterns.md` | Correct implementation patterns |
-| `references/detection.md` | Grep commands, profiling, CI integration |
-
----
-
-## Severity Guidelines
-
-| Severity | Criteria | Examples |
-|----------|----------|----------|
-| **CRITICAL** | Severe degradation, production risk | N+1 with unbounded data, memory leaks, blocking I/O in handlers |
-| **HIGH** | Significant impact | Sequential async, SELECT *, unbounded caches, missing pagination |
-| **MEDIUM** | Moderate concern | Suboptimal algorithm (small data), missing memoization |
-| **LOW** | Minor opportunity | Micro-optimizations, premature optimization candidates |
-
----
-
-## Performance Metrics Reference
-
-| Operation | Good | Warning | Critical |
-|-----------|------|---------|----------|
-| API response | < 100ms | 100-500ms | > 500ms |
-| Database query | < 10ms | 10-100ms | > 100ms |
-| Page load (FCP) | < 1s | 1-2.5s | > 2.5s |
-| Memory per request | < 10MB | 10-50MB | > 50MB |
-| Bundle size | < 200KB | 200-500KB | > 500KB |
-
----
-
-## Quick Detection
-
-```bash
-# N+1 patterns (await in loop)
-grep -rn "for.*await\|\.forEach.*async" --include="*.ts"
-
-# Synchronous I/O
-grep -rn "readFileSync\|writeFileSync" --include="*.ts"
-
-# SELECT *
-grep -rn "SELECT \*" --include="*.ts" --include="*.sql"
-```
-
-See `references/detection.md` for comprehensive detection patterns.

package/shared/skills/performance-patterns/references/detection.md

@@ -1,351 +0,0 @@
-# Performance Detection Patterns
-
-Commands and techniques for detecting performance issues. Reference from main SKILL.md.
-
-## Static Analysis Commands
-
-### N+1 Query Detection
-
-```bash
-# Await in loop patterns
-grep -rn "for.*{" -A10 --include="*.ts" | grep -E "await|\.then"
-
-# forEach with async (fire-and-forget bug)
-grep -rn "\.forEach\s*\(\s*async" --include="*.ts"
-
-# Map with await (sequential, not parallel)
-grep -rn "\.map\s*\(\s*async.*await" --include="*.ts"
-
-# Sequelize/TypeORM lazy loading
-grep -rn "get[A-Z].*\(\)" --include="*.ts" | grep -v "\.get("
-```
-
-### Algorithmic Complexity Detection
-
-```bash
-# Nested loops
-grep -rn "for.*{" -A15 --include="*.ts" | grep -c "for.*{"
-
-# Array.includes/indexOf in loop
-grep -rn "\.includes\|\.indexOf" --include="*.ts" | grep -E "for|while|each"
-
-# Nested array methods
-grep -rn "\.filter.*\.filter\|\.map.*\.map\|\.find.*\.find" --include="*.ts"
-
-# String concatenation in loop
-grep -rn "+=.*['\"\`]" --include="*.ts" | grep -E "for|while"
-```
-
-### Database Issue Detection
-
-```bash
-# SELECT * patterns
-grep -rn "SELECT \*" --include="*.ts" --include="*.sql"
-
-# Missing LIMIT on queries
-grep -rn "findAll\|findMany" --include="*.ts" | grep -v "limit\|take"
-
-# LIKE with leading wildcard
-grep -rn "LIKE.*['\"]%" --include="*.ts" --include="*.sql"
-
-# ORDER BY without limit
-grep -rn "ORDER BY" --include="*.ts" | grep -v -i "limit"
-```
-
-### Memory Issue Detection
-
-```bash
-# Unbounded collections
-grep -rn "new Map\|new Set\|= \[\]" --include="*.ts" | grep -v "const.*="
-
-# Missing cleanup patterns
-grep -rn "addEventListener" --include="*.ts" | head -20
-grep -rn "removeEventListener" --include="*.ts" | head -20
-# Compare counts
-
-# setInterval without clear
-grep -rn "setInterval" --include="*.ts"
-grep -rn "clearInterval" --include="*.ts"
-# Compare counts
-
-# Spreading in reduce
-grep -rn "\.reduce.*\.\.\.acc\|\.reduce.*\.\.\.prev" --include="*.ts"
-```
-
-### I/O Issue Detection
-
-```bash
-# Synchronous file operations
-grep -rn "readFileSync\|writeFileSync\|existsSync\|statSync\|readdirSync" --include="*.ts"
-
-# Sequential awaits (could be parallel)
-grep -rn "await.*\n.*await.*\n.*await" --include="*.ts"
-
-# Missing error handling on fetch
-grep -rn "await fetch" --include="*.ts" | grep -v "try\|catch\|\.catch"
-```
-
-### Frontend Issue Detection
-
-```bash
-# Inline functions in JSX
-grep -rn "onClick={() =>\|onChange={() =>\|onSubmit={() =>" --include="*.tsx"
-
-# Inline objects in JSX
-grep -rn "style={{ " --include="*.tsx"
-
-# Missing useMemo/useCallback
-grep -rn "const.*=.*=>" --include="*.tsx" | grep -v "useMemo\|useCallback\|useState\|useEffect"
-
-# Index as key
-grep -rn "key={.*index\|key={\`.*index" --include="*.tsx"
-```
-
----
-
-## Profiling Techniques
-
-### Node.js Profiling
-
-**CPU Profiling**
-```bash
-# Start with profiler
-node --prof app.js
-
-# Process the log
-node --prof-process isolate-*.log > profile.txt
-
-# Or use clinic.js
-npx clinic doctor -- node app.js
-npx clinic flame -- node app.js
-```
-
-**Memory Profiling**
-```bash
-# Heap snapshot
-node --inspect app.js
-# Open chrome://inspect and take heap snapshot
-
-# Memory usage tracking
-node --expose-gc app.js
-# In code: global.gc() and process.memoryUsage()
-```
-
-**Event Loop Monitoring**
-```typescript
-// Detect blocked event loop
-const start = Date.now();
-setImmediate(() => {
-  const lag = Date.now() - start;
-  if (lag > 100) {
-    console.warn(`Event loop lag: ${lag}ms`);
-  }
-});
-```
-
-### Database Profiling
-
-**Query Analysis**
-```sql
--- PostgreSQL: Explain analyze
-EXPLAIN ANALYZE SELECT * FROM orders WHERE customer_id = 123;
-
--- MySQL: Show query plan
-EXPLAIN SELECT * FROM orders WHERE customer_id = 123;
-
--- Find slow queries (PostgreSQL)
-SELECT query, calls, total_time, mean_time
-FROM pg_stat_statements
-ORDER BY total_time DESC
-LIMIT 10;
-```
-
-**Index Analysis**
-```sql
--- PostgreSQL: Missing indexes
-SELECT schemaname, tablename, attname, null_frac, n_distinct
-FROM pg_stats
-WHERE schemaname = 'public'
-AND tablename = 'orders';
-
--- Check index usage
-SELECT indexrelname, idx_scan, idx_tup_read
-FROM pg_stat_user_indexes
-WHERE schemaname = 'public';
-```
-
-### Frontend Profiling
-
-**React DevTools Profiler**
-```tsx
-// Wrap component to measure
-import { Profiler } from 'react';
-
-function onRender(id, phase, actualDuration) {
-  console.log(`${id} ${phase}: ${actualDuration}ms`);
-}
-
-<Profiler id="MyComponent" onRender={onRender}>
-  <MyComponent />
-</Profiler>
-```
-
-**Performance API**
-```typescript
-// Measure specific operations
-performance.mark('start');
-doExpensiveOperation();
-performance.mark('end');
-performance.measure('operation', 'start', 'end');
-
-const measure = performance.getEntriesByName('operation')[0];
-console.log(`Duration: ${measure.duration}ms`);
-```
-
-**Lighthouse CLI**
-```bash
-# Run Lighthouse audit
-npx lighthouse https://example.com --output=json --output-path=./report.json
-
-# Focus on performance
-npx lighthouse https://example.com --only-categories=performance
-```
-
----
-
-## Automated Detection
-
-### ESLint Rules
-
-```json
-{
-  "rules": {
-    "no-await-in-loop": "error",
-    "no-sync": "error",
-    "react-hooks/exhaustive-deps": "warn"
-  }
-}
-```
-
-### Custom ESLint Rule (N+1 Detection)
-
-```javascript
-// eslint-rules/no-await-in-foreach.js
-module.exports = {
-  create(context) {
-    return {
-      CallExpression(node) {
-        if (
-          node.callee.property?.name === 'forEach' &&
-          node.arguments[0]?.async
-        ) {
-          context.report({
-            node,
-            message: 'Avoid async forEach - use for...of or Promise.all'
-          });
-        }
-      }
-    };
-  }
-};
-```
-
-### CI Integration
-
-```yaml
-# .github/workflows/performance.yml
-name: Performance Check
-on: [pull_request]
-
-jobs:
-  analyze:
-    runs-on: ubuntu-latest
-    steps:
-      - uses: actions/checkout@v3
-
-      - name: Check for sync I/O
-        run: |
-          if grep -rn "Sync(" --include="*.ts" src/; then
-            echo "::error::Synchronous I/O detected"
-            exit 1
-          fi
-
-      - name: Check for N+1 patterns
-        run: |
-          if grep -rn "\.forEach.*async" --include="*.ts" src/; then
-            echo "::warning::Potential N+1 pattern detected"
-          fi
-
-      - name: Bundle size check
-        run: |
-          npm run build
-          size=$(du -sb dist/ | cut -f1)
-          if [ $size -gt 500000 ]; then
-            echo "::error::Bundle too large: $size bytes"
-            exit 1
-          fi
-```
-
----
-
-## Performance Monitoring
-
-### Application Metrics
-
-```typescript
-// Track key metrics
-const metrics = {
-  requestDuration: new Histogram({
-    name: 'http_request_duration_ms',
-    help: 'Request duration in milliseconds',
-    buckets: [10, 50, 100, 200, 500, 1000]
-  }),
-
-  dbQueryDuration: new Histogram({
-    name: 'db_query_duration_ms',
-    help: 'Database query duration',
-    buckets: [1, 5, 10, 50, 100, 500]
-  }),
-
-  memoryUsage: new Gauge({
-    name: 'memory_usage_bytes',
-    help: 'Memory usage in bytes'
-  })
-};
-
-// Collect periodically
-setInterval(() => {
-  const usage = process.memoryUsage();
-  metrics.memoryUsage.set(usage.heapUsed);
-}, 10000);
-```
-
-### Alerting Thresholds
-
-| Metric | Warning | Critical |
-|--------|---------|----------|
-| P95 latency | > 200ms | > 500ms |
-| P99 latency | > 500ms | > 1000ms |
-| Error rate | > 1% | > 5% |
-| Memory growth | > 10% / hour | > 25% / hour |
-| CPU usage | > 70% | > 90% |
-
-### Performance Budget
-
-```json
-// performance-budget.json
-{
-  "timings": [
-    { "metric": "first-contentful-paint", "budget": 1500 },
-    { "metric": "time-to-interactive", "budget": 3000 },
-    { "metric": "largest-contentful-paint", "budget": 2500 }
-  ],
-  "resourceSizes": [
-    { "resourceType": "script", "budget": 200 },
-    { "resourceType": "total", "budget": 500 }
-  ],
-  "resourceCounts": [
-    { "resourceType": "third-party", "budget": 5 }
-  ]
-}
-```