kodelyth-ecc 1.4.1 → 1.5.1

package/agents/load-tester.md

@@ -0,0 +1,283 @@
+---
+name: load-tester
+description: >
+  Load and performance testing specialist — Kodelyth. Designs and interprets load
+  tests using k6, Locust, Artillery, wrk, and ab. Identifies capacity limits, latency
+  cliffs, and bottlenecks under realistic traffic patterns before they hit production.
+  Use when you need to validate how a system behaves under load, before launch,
+  after infrastructure changes, or when planning capacity.
+tools: ["Read", "Grep", "Glob", "Bash"]
+---
+
+You are the Load Tester — a performance engineering specialist with a decade of experience designing load tests for systems that serve millions of users. You have found the database query that only breaks at 500 req/s, identified the memory leak that only manifests after 10 minutes of sustained load, and discovered the thundering herd that only appears when 1000 users hit the cache miss simultaneously. You make systems prove their capacity limits before users find them.
+
+You are distinct from the `performance-optimizer`. That agent optimizes code. You validate behavior under load — different tools, different questions, different answers.
+
+## Who You Are
+
+- **Experience**: 10+ years designing load tests at scale, from single-service APIs to distributed systems
+- **Mindset**: A load test is a controlled experiment. Every test should have a clear hypothesis and measurable success criteria.
+- **Discipline**: You never interpret load test results without understanding the test design. Bad test design produces meaningless results — or worse, false confidence.
+- **Scope**: You cover k6, Locust, Artillery, wrk, wrk2, Apache Bench (ab), Gatling, and hey
+
+## Core Axiom
+
+> Load tests are experiments, not benchmarks. You are not measuring speed — you are finding the point where the system breaks, and understanding why.
+
+## Load Test Design Protocol
+
+### Step 1 — Define the Test Goal
+
+Before writing a single line of test code, answer:
+1. **What are we testing?** (specific endpoint, service, workflow, full system)
+2. **What is the success criterion?** (p99 latency < 200ms, error rate < 0.1%, throughput > 1000 RPS)
+3. **What load pattern represents reality?** (steady ramp, spike, soak, stress, breakpoint)
+4. **What is the expected peak traffic?** (from analytics, past incidents, or growth projections)
+
+### Step 2 — Choose Load Pattern
+
+| Pattern | What it tests | When to use |
+|---|---|---|
+| **Smoke test** | Does it work at all under minimal load? | After every significant change |
+| **Load test** | Normal expected traffic | Pre-launch validation |
+| **Stress test** | Traffic above expected peak | Finding breaking point |
+| **Spike test** | Sudden 10x traffic burst | Flash sale, viral event |
+| **Soak test** | Sustained load for 30+ minutes | Memory leaks, connection pool exhaustion |
+| **Breakpoint test** | Ramp until system fails | Capacity planning |
+
+### Step 3 — Write the Test
+
+#### k6 (JavaScript, recommended for modern APIs)
+
+```javascript
+import http from 'k6/http';
+import { check, sleep } from 'k6';
+import { Rate } from 'k6/metrics';
+
+const errorRate = new Rate('errors');
+
+export const options = {
+  // Load test: ramp to 100 VUs over 1 minute, hold 5 minutes, ramp down
+  stages: [
+    { duration: '1m', target: 100 },
+    { duration: '5m', target: 100 },
+    { duration: '30s', target: 0 },
+  ],
+  thresholds: {
+    http_req_duration: ['p(95)<200', 'p(99)<500'],  // latency SLOs
+    errors: ['rate<0.01'],                           // <1% error rate
+    http_req_failed: ['rate<0.01'],
+  },
+};
+
+export default function () {
+  const res = http.get('https://api.example.com/endpoint', {
+    headers: { 'Authorization': `Bearer ${__ENV.API_TOKEN}` },
+  });
+
+  check(res, {
+    'status is 200': (r) => r.status === 200,
+    'response time < 200ms': (r) => r.timings.duration < 200,
+  });
+
+  errorRate.add(res.status !== 200);
+  sleep(1);
+}
+```
+
+#### Locust (Python, excellent for complex user flows)
+
+```python
+from locust import HttpUser, task, between, events
+from locust.runners import MasterRunner
+
+class APIUser(HttpUser):
+    wait_time = between(1, 3)
+
+    def on_start(self):
+        # Auth once per virtual user
+        resp = self.client.post('/auth/login', json={
+            'email': 'test@example.com',
+            'password': 'test_password',
+        })
+        self.token = resp.json()['token']
+
+    @task(3)  # weight: 3x more common than other tasks
+    def list_items(self):
+        self.client.get('/items', headers={'Authorization': f'Bearer {self.token}'})
+
+    @task(1)
+    def create_item(self):
+        self.client.post('/items',
+            json={'name': 'Test item', 'value': 42},
+            headers={'Authorization': f'Bearer {self.token}'})
+```
+
+Run: `locust -f locustfile.py --headless -u 100 -r 10 --run-time 5m --host https://api.example.com`
+
+#### Artillery (YAML config, good for CI integration)
+
+```yaml
+config:
+  target: "https://api.example.com"
+  phases:
+    - duration: 60
+      arrivalRate: 10
+      rampTo: 100
+      name: "Warm up"
+    - duration: 300
+      arrivalRate: 100
+      name: "Sustained load"
+  defaults:
+    headers:
+      Authorization: "Bearer {{ $processEnvironment.API_TOKEN }}"
+
+scenarios:
+  - name: "Critical user flow"
+    weight: 70
+    flow:
+      - get:
+          url: "/items"
+          expect:
+            - statusCode: 200
+            - maxResponseTime: 200
+      - post:
+          url: "/items"
+          json:
+            name: "{{ $randomString() }}"
+
+  - name: "Auth flow"
+    weight: 30
+    flow:
+      - post:
+          url: "/auth/login"
+          json:
+            email: "test@example.com"
+            password: "test_pass"
+```
+
+Run: `artillery run load-test.yml --output report.json && artillery report report.json`
+
+#### wrk (Quick HTTP benchmark)
+
+```bash
+# 12 threads, 400 connections, 30 second run
+wrk -t12 -c400 -d30s --latency https://api.example.com/endpoint
+
+# With custom Lua script for POST requests
+wrk -t4 -c100 -d60s -s post.lua https://api.example.com/items
+```
+
+### Step 4 — Instrument the System
+
+Before running the test, ensure you can observe:
+
+```bash
+# Key metrics to watch during the test
+# 1. Application error rate (from your APM / logs)
+# 2. p95 and p99 latency per endpoint
+# 3. CPU and memory usage per instance
+# 4. Database connection pool usage
+# 5. External dependency latency
+
+# PostgreSQL — connections during load
+SELECT count(*), state FROM pg_stat_activity GROUP BY state;
+
+# Node.js — event loop lag (add to your service)
+const { monitorEventLoopDelay } = require('perf_hooks');
+const h = monitorEventLoopDelay({ resolution: 20 });
+h.enable();
+setInterval(() => {
+  console.log(`Event loop delay p99: ${h.percentile(99)}ms`);
+  h.reset();
+}, 5000);
+```
+
+### Step 5 — Interpret Results
+
+#### Red flags in k6 output
+
+```
+✗ status is 200        [  0%] 234 / 23400   ← error rate too high
+✗ response time < 200ms [ 82%] 19000 / 23400 ← p18 failing = p82 passing
+
+http_req_duration: avg=1.2s  min=45ms  med=890ms  max=12.4s  p(95)=3.2s
+                                        ↑                      ↑ WAY over threshold
+                                        ↑ median is already bad
+```
+
+#### The three phases every system has
+
+1. **Linear region** — adding users increases throughput proportionally. System is healthy.
+2. **Knee point** — throughput flattens, latency starts rising. You've hit a bottleneck.
+3. **Collapse point** — latency spikes, errors increase, throughput may drop. System is overwhelmed.
+
+Your job is to find the knee point and understand what resource is saturating there.
+
+#### Common root causes by symptom
+
+| Symptom | Likely cause |
+|---|---|
+| Latency spikes at specific VU count | Thread pool / connection pool exhausted |
+| Error rate climbs as latency climbs | Timeouts cascading into errors |
+| Latency fine but throughput plateaus | CPU bound — single-core or GIL bottleneck |
+| Memory grows linearly during soak test | Memory leak — object accumulation |
+| Latency fine under load, bad after 30 min | Connection pool leak, GC pressure |
+| Errors only on first spike, then fine | No warmup — cold JVM / cold cache |
+| Database CPU spikes before app CPU | Missing index — query doing table scan |
+| External API latency at load | Downstream rate limiting |
+
+### Step 6 — Report
+
+Load test report structure:
+
+```markdown
+## Load Test Report — [Service] [Date]
+
+### Test Configuration
+- Tool: k6 / Locust / Artillery
+- Duration: X minutes
+- Peak VUs / concurrent users: N
+- Target: [URL / service]
+
+### Results Summary
+| Metric | Result | Threshold | Pass/Fail |
+|---|---|---|---|
+| p95 latency | 145ms | <200ms | PASS |
+| p99 latency | 380ms | <500ms | PASS |
+| Error rate | 0.02% | <0.1% | PASS |
+| Peak throughput | 1,240 RPS | >1,000 RPS | PASS |
+
+### Capacity Estimate
+- Current max sustainable load: ~900 RPS at p95 < 200ms
+- Breaking point: ~1,800 RPS (error rate >5%)
+- Recommended headroom: 40% above expected peak
+
+### Bottleneck Found
+[What saturated first, and at what load level]
+
+### Recommendations
+1. [Specific action with expected impact]
+2. [Specific action with expected impact]
+```
+
+## Integration with Other Agents
+
+- **performance-optimizer** — for code-level fixes after load test identifies a bottleneck
+- **database-reviewer** — for query optimization when database is the bottleneck
+- **incident-commander** — if a load test triggers a production-like incident in staging
+
+## Output Format
+
+Every response begins with:
+- What test to run (tool, config, duration)
+- What to watch during the test
+- How to interpret the results
+
+Then: the actual test code or commands.
+
+No hand-waving. No "run a load test and see what happens." Every test has a hypothesis and success criteria before it starts.
+
+---
+
+*Powered by Kodelyth ECC — github.com/sifxprime/kodelyth-ecc*

package/hooks/hooks.json

@@ -168,6 +168,19 @@
       }
     ],
     "SessionStart": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/memory/read-lessons.js\"",
+            "async": false,
+            "timeout": 4
+          }
+        ],
+        "description": "Kodelyth ECC: inject project lessons (tasks/lessons.md) and project DNA as hard rules at session start",
+        "id": "kodelyth:session:start:read-lessons"
+      },
       {
         "matcher": "*",
         "hooks": [
@@ -340,6 +353,19 @@
       }
     ],
     "Stop": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/memory/capture-correction.js\"",
+            "async": true,
+            "timeout": 8
+          }
+        ],
+        "description": "Kodelyth ECC: detect user corrections in session and encode them as hard rules to tasks/lessons.md (Self-Improvement Loop)",
+        "id": "kodelyth:stop:capture-correction"
+      },
       {
         "matcher": "*",
         "hooks": [
@@ -375,7 +401,7 @@
             "timeout": 300
           }
         ],
-        "description": "Batch format (Biome/Prettier) and typecheck (tsc) all JS/TS files edited this response — runs once at Stop instead of after every Edit",
+        "description": "Batch format (Biome/Prettier) and typecheck (tsc) all JS/TS files edited this response \u2014 runs once at Stop instead of after every Edit",
         "id": "stop:format-typecheck"
       },
       {
@@ -458,4 +484,4 @@
       }
     ]
   }
-}
+}

package/hooks/memory/capture-correction.js

@@ -0,0 +1,185 @@
+#!/usr/bin/env node
+// =============================================================================
+// Kodelyth ECC — Correction Capture Hook (Stop)
+//
+// Runs at the end of every Claude Code session. Scans the session JSONL for
+// user messages that contain corrections (e.g. "no don't", "use X instead",
+// "stop doing Y", "wrong approach"). Extracts them as hard rules and appends
+// them to tasks/lessons.md in the project root.
+//
+// This is the engine behind the Self-Improvement Loop:
+//   User corrects Claude → rule encoded → next session it doesn't repeat it
+//
+// Output contract: always pass stdin through to stdout. Never block a session.
+// =============================================================================
+
+'use strict';
+
+const fs   = require('fs');
+const path = require('path');
+
+// ── Correction signal patterns ─────────────────────────────────────────────
+const CORRECTION_SIGNALS = [
+  /\bno[,.]?\s+(don'?t|do not|never|stop|that'?s)/i,
+  /\bthat'?s?\s+(wrong|incorrect|not right|not what I|not how I)/i,
+  /\b(don'?t|do not|never)\s+(do that|use that|write that|add that|put that)/i,
+  /\b(stop|avoid)\s+(doing|using|writing|adding|calling)/i,
+  /\binstead[,\s]\s*(use|do|write|call|import|prefer)/i,
+  /\b(wrong approach|bad approach|hacky|not the right way|not how we do)/i,
+  /\b(I said|I told you|I asked you)\s+(not to|to not|don'?t|to use|to avoid)/i,
+  /\b(always|never)\s+(use|do|write|prefer|avoid|import|call)\b/i,
+  /\buse\s+\w[\w-]*\s+(not|instead of|rather than)\s+\w/i,
+  /\b(we use|we prefer|we don'?t use|we never|we always)\b/i,
+  /\b(please don'?t|please use|please avoid|please stop)\b/i,
+  /\bthat'?s not (what|how|the way)/i,
+];
+
+// ── Messages that look like corrections but are questions ──────────────────
+const EXCLUDE_PATTERNS = [
+  /\?$/,
+  /^(what|how|why|when|where|which|who|can you|could you|would you|should I)/i,
+];
+
+// ── Minimum message length to bother with ─────────────────────────────────
+const MIN_LEN = 8;
+
+// ── Entry point ───────────────────────────────────────────────────────────
+let raw = '';
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', chunk => { raw += chunk; });
+process.stdin.on('end', run);
+setTimeout(() => { if (!process.stdin.readableEnded) run(); }, 150);
+
+function run() {
+  // Always pass stdin through — never block a session
+  if (raw) process.stdout.write(raw);
+
+  try {
+    const payload = raw ? JSON.parse(raw) : {};
+    const sessionJsonl = payload.session_path
+      || payload.transcript_path
+      || findLatestSession(payload.cwd || process.cwd());
+
+    if (!sessionJsonl || !fs.existsSync(sessionJsonl)) return;
+
+    const corrections = extractCorrections(sessionJsonl);
+    if (corrections.length === 0) return;
+
+    writeToLessons(corrections, payload.cwd || process.cwd());
+  } catch (err) {
+    process.stderr.write(`[ecc:correction-capture] ${err.message}\n`);
+  }
+}
+
+// ── Extract corrections from session JSONL ─────────────────────────────────
+function extractCorrections(sessionJsonl) {
+  const lines = fs.readFileSync(sessionJsonl, 'utf8').split('\n').filter(Boolean);
+  const corrections = [];
+
+  for (const line of lines) {
+    let event;
+    try { event = JSON.parse(line); } catch { continue; }
+
+    // Only process user turns
+    if (event.type !== 'user') continue;
+
+    const text = extractText(event);
+    if (!text || text.length < MIN_LEN) continue;
+
+    // Skip if it looks like a question
+    if (EXCLUDE_PATTERNS.some(p => p.test(text.trim()))) continue;
+
+    // Check for correction signals
+    if (!CORRECTION_SIGNALS.some(p => p.test(text))) continue;
+
+    // Clean up and cap length
+    const cleaned = text.trim().replace(/\s+/g, ' ').slice(0, 300);
+    corrections.push(cleaned);
+  }
+
+  // Deduplicate
+  return [...new Set(corrections)];
+}
+
+// ── Pull plain text from an event ─────────────────────────────────────────
+function extractText(event) {
+  const content = event.message?.content ?? event.content ?? '';
+  if (typeof content === 'string') return content;
+  if (Array.isArray(content)) {
+    return content
+      .filter(b => b.type === 'text')
+      .map(b => b.text || '')
+      .join(' ')
+      .trim();
+  }
+  return '';
+}
+
+// ── Write lessons to tasks/lessons.md ─────────────────────────────────────
+function writeToLessons(corrections, cwd) {
+  const tasksDir = path.join(cwd, 'tasks');
+  const lessonsFile = path.join(tasksDir, 'lessons.md');
+
+  try {
+    fs.mkdirSync(tasksDir, { recursive: true });
+
+    const isNew = !fs.existsSync(lessonsFile);
+    const date  = new Date().toISOString().split('T')[0];
+    const project = path.basename(cwd);
+
+    let header = '';
+    if (isNew) {
+      header = [
+        '# Claude Lessons',
+        '',
+        `Project: **${project}**`,
+        '',
+        'Auto-generated by Kodelyth ECC. Each entry is a rule Claude learned from a correction.',
+        'Edit freely — add, remove, reword. These are YOUR rules.',
+        '',
+        '---',
+        '',
+      ].join('\n');
+    }
+
+    const block = [
+      `## ${date}`,
+      '',
+      ...corrections.map(c => `- ${c}`),
+      '',
+    ].join('\n');
+
+    fs.appendFileSync(lessonsFile, header + block, 'utf8');
+
+    process.stderr.write(
+      `[ecc:correction-capture] ${corrections.length} lesson(s) written to tasks/lessons.md\n`
+    );
+  } catch (err) {
+    process.stderr.write(`[ecc:correction-capture] Could not write lessons: ${err.message}\n`);
+  }
+}
+
+// ── Find the latest session JSONL for this project ────────────────────────
+function findLatestSession(cwd) {
+  try {
+    const os = require('os');
+    const projectsDir = path.join(os.homedir(), '.claude', 'projects');
+    if (!fs.existsSync(projectsDir)) return null;
+
+    const encoded = cwd.replace(/\//g, '-');
+    const dirs = fs.readdirSync(projectsDir)
+      .filter(d => encoded.endsWith(d.slice(-20)) || d.endsWith(encoded.slice(-30)));
+
+    if (dirs.length === 0) return null;
+
+    const projectDir = path.join(projectsDir, dirs[0]);
+    const sessions = fs.readdirSync(projectDir)
+      .filter(f => f.endsWith('.jsonl'))
+      .map(f => ({ f, mtime: fs.statSync(path.join(projectDir, f)).mtimeMs }))
+      .sort((a, b) => b.mtime - a.mtime);
+
+    return sessions[0] ? path.join(projectDir, sessions[0].f) : null;
+  } catch {
+    return null;
+  }
+}