kodelyth-ecc 1.4.0 → 1.5.0

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

@@ -139,6 +139,21 @@
         "id": "pre:mcp-health-check"
       }
     ],
+    "UserPromptSubmit": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/memory/auto-recall.js\"",
+            "async": false,
+            "timeout": 3
+          }
+        ],
+        "description": "Kodelyth Memory: auto-detect topic from each user prompt and inject relevant past memories before the AI responds (suppresses repeats per session)",
+        "id": "kodelyth:user-prompt:memory-auto-recall"
+      }
+    ],
     "PreCompact": [
       {
         "matcher": "*",

package/hooks/memory/auto-recall.js

@@ -0,0 +1,141 @@
+#!/usr/bin/env node
+// =============================================================================
+// Kodelyth ECC — Auto Chat Detection (Memory Auto-Recall)
+//
+// Triggered on UserPromptSubmit (every message the user sends).
+// Reads the prompt, searches memory in real-time, and injects relevant
+// matches as additional context BEFORE the AI sees the prompt.
+//
+// Behaviour:
+//   - Skips on prompts that are too short (< 12 chars) or trivial ("ok", "yes")
+//   - Skips on prompts that look like agent commands (`use foo`, `@bar`)
+//   - Skips when no memory exists yet
+//   - Suppresses repeats: never re-surfaces the same memory twice in a session
+//     (state file: ~/.kodelyth/memory/session-surfaced-<sessionId>.json)
+//   - Always exits 0 — never blocks the prompt because memory is unavailable
+// =============================================================================
+
+'use strict';
+
+const fs   = require('fs');
+const os   = require('os');
+const path = require('path');
+
+const MIN_PROMPT_CHARS    = 12;
+const MIN_TOKENS          = 2;
+const MAX_RECALLED        = 3;
+const MIN_SCORE           = 1.0;       // Higher than passive inject — we want strong signal
+const TRIVIAL_PROMPTS     = new Set(['ok', 'yes', 'no', 'thanks', 'thx', 'sure', 'go', 'cool', 'k']);
+const SKIP_PATTERN        = /^\s*(use\s+|@|\/|invoke\s+)/i;
+
+let payload = '';
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', chunk => { payload += chunk; });
+process.stdin.on('end', main);
+setTimeout(() => { if (!process.stdin.readableEnded) main(); }, 200);
+
+function main() {
+  try {
+    const data        = payload ? safeJson(payload) : {};
+    const userPrompt  = (data.prompt || data.user_prompt || data.text || '').trim();
+    const sessionId   = data.session_id || 'unknown';
+    const projectRoot = data.cwd || process.cwd();
+
+    if (!shouldRecall(userPrompt)) return done({});
+
+    // Lazy require so the hook doesn't crash if memory module breaks
+    const { recallForProject } = require(path.join(__dirname, '..', '..', 'scripts', 'memory', 'store'));
+
+    const matches = recallForProject(projectRoot, userPrompt, {
+      limit:    MAX_RECALLED * 2,   // grab extra so we can filter out repeats
+      minScore: MIN_SCORE,
+    });
+    if (matches.length === 0) return done({});
+
+    // Filter out memories already surfaced this session
+    const surfacedFile = surfacedStatePath(sessionId);
+    const surfaced     = loadSurfaced(surfacedFile);
+    const fresh        = matches.filter(m => !surfaced.has(m.id)).slice(0, MAX_RECALLED);
+    if (fresh.length === 0) return done({});
+
+    // Mark the freshly surfaced memories so they don't re-appear this session
+    for (const m of fresh) surfaced.add(m.id);
+    saveSurfaced(surfacedFile, surfaced);
+
+    const block = formatBlock(fresh, userPrompt);
+    done({
+      additionalContext: block,
+      meta: {
+        source:        'kodelyth-memory:auto-recall',
+        recalledCount: fresh.length,
+        surfacedTotal: surfaced.size,
+      },
+    });
+  } catch (err) {
+    process.stderr.write(`kodelyth-memory auto-recall: ${err.message}\n`);
+    done({});
+  }
+}
+
+function shouldRecall(prompt) {
+  if (!prompt || prompt.length < MIN_PROMPT_CHARS)        return false;
+  if (TRIVIAL_PROMPTS.has(prompt.toLowerCase().trim()))   return false;
+  if (SKIP_PATTERN.test(prompt))                          return false;
+  // Token gate — need at least N meaningful words
+  const meaningful = prompt
+    .toLowerCase()
+    .split(/\s+/)
+    .filter(w => w.length >= 4);
+  return meaningful.length >= MIN_TOKENS;
+}
+
+function formatBlock(memories, userPrompt) {
+  const lines = [];
+  lines.push('## Kodelyth Memory — relevant past solutions');
+  lines.push('');
+  lines.push(`Auto-detected from your message: "${userPrompt.slice(0, 100).replace(/\n/g, ' ')}${userPrompt.length > 100 ? '...' : ''}"`);
+  lines.push('');
+  for (const m of memories) {
+    lines.push(`- **${m.problem}**`);
+    if (m.approach) lines.push(`  Approach: ${m.approach.split('\n')[0].slice(0, 240)}`);
+    if (m.gotchas?.length) lines.push(`  Gotcha: ${m.gotchas[0].slice(0, 200)}`);
+    if (m.tags?.length) lines.push(`  Tags: ${m.tags.slice(0, 5).join(', ')}`);
+    lines.push(`  (memory id: ${m.id} · captured ${m.captured_at?.slice(0, 10)})`);
+  }
+  lines.push('');
+  lines.push('> Surface these to the user before answering only if they are genuinely relevant to the current task. If not, ignore silently — do not force-fit a memory.');
+  return lines.join('\n');
+}
+
+function surfacedStatePath(sessionId) {
+  const dir = process.env.KODELYTH_MEMORY_DIR
+    || path.join(os.homedir(), '.kodelyth', 'memory');
+  if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+  return path.join(dir, `session-surfaced-${sessionId}.json`);
+}
+
+function loadSurfaced(file) {
+  try {
+    if (!fs.existsSync(file)) return new Set();
+    return new Set(JSON.parse(fs.readFileSync(file, 'utf8')));
+  } catch {
+    return new Set();
+  }
+}
+
+function saveSurfaced(file, set) {
+  try {
+    fs.writeFileSync(file, JSON.stringify(Array.from(set)));
+  } catch {
+    /* non-fatal */
+  }
+}
+
+function safeJson(s) {
+  try { return JSON.parse(s); } catch { return {}; }
+}
+
+function done(obj) {
+  if (Object.keys(obj).length > 0) process.stdout.write(JSON.stringify(obj));
+  process.exit(0);
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "kodelyth-ecc",
-  "version": "1.4.0",
-  "description": "Production-grade AI coding toolkit — 59 agents, 188 skills, 79 commands, god-tier intent routing, local self-learning memory. Works with Claude Code, Windsurf, Cursor, Codex, Antigravity, and OpenCode.",
+  "version": "1.5.0",
+  "description": "Production-grade AI coding toolkit — 61 agents, 188 skills, 80 commands, god-tier intent routing, local self-learning memory with auto chat detection, incident response, load testing. Works with Claude Code, Windsurf, Cursor, Codex, Antigravity, and OpenCode.",
   "author": "Kodelyth <github.com/sifxprime>",
   "license": "MIT",
   "repository": {
@@ -21,6 +21,9 @@
     "llm",
     "memory",
     "self-learning",
+    "auto-recall",
+    "incident-response",
+    "load-testing",
     "kodelyth"
   ],
   "bin": {

package/rules/common/agent-intent-routing.md

@@ -134,7 +134,33 @@ Trigger if the user describes **what they're about to build** before they start.
 
 ## Priority 4 — Performance & Scale
 
-### `performance-optimizer` — Slowness / bottleneck
+### `incident-commander` — Production is down or degraded
+
+Route here FIRST for any active production incident. This takes priority over `debug-detective` when the incident is live in production.
+
+| Signal | Examples |
+|---|---|
+| Production down | "production is down", "outage", "site is down", "service unavailable" |
+| P0 / P1 | "P0", "P1", "incident", "on-call", "pagerduty fired", "alert triggered" |
+| Blast radius | "10% of users affected", "all requests failing", "error rate spiked" |
+| Active degradation | "production is throwing 500s", "latency is through the roof", "database is down" |
+| Postmortem | "postmortem", "incident review", "blameless review", "what went wrong" |
+
+**Counter-signals:** development bug (not production), staging environment, local testing — route to `debug-detective` instead.
+
+### `load-tester` — Load, stress, and capacity testing
+
+| Signal | Examples |
+|---|---|
+| Load test request | "load test", "stress test", "performance test", "capacity test" |
+| Tools | "k6", "Locust", "Artillery", "wrk", "Gatling", "hey", "ab test" |
+| Capacity planning | "how many users can we handle", "what's our breaking point", "max RPS" |
+| Pre-launch validation | "will this hold under load", "ready for launch traffic", "scale test" |
+| Soak test | "soak test", "memory leak under load", "sustained load test" |
+
+**Counter-signal:** "make this code faster" → `performance-optimizer`. Load-tester handles test design, not code optimization.
+
+### `performance-optimizer` — Slowness / bottleneck in code
 
 | Signal | Examples |
 |---|---|
@@ -284,6 +310,8 @@ Use the chain: `forker` → `sanitizer` → `packager`.
 | `migration-guide` (plan made) | `pr-test-analyzer` after PR is up |
 | `architect` (design done) | `code-architect` for the first feature |
 | `performance-optimizer` (bottleneck found) | `tdd-guide` for a perf regression test |
+| `load-tester` (bottleneck found) | `performance-optimizer` to fix the code |
+| `incident-commander` (incident resolved) | `debug-detective` for deeper root cause, then postmortem |
 
 ### Parallel suggestions
 
@@ -321,6 +349,10 @@ If the user has a multi-faceted concern, name the parallel agents:
 | "Add accessibility to this form" | `ux-reviewer` | a11y |
 | "Plan the v2 redesign" | `planner` → `architect` | Plan + design |
 | "open source this project" | `opensource-forker` | OSS chain start |
+| "production is down, getting 500s" | `incident-commander` | Active production incident |
+| "will this hold under 10k concurrent users" | `load-tester` | Capacity / load testing question |
+| "run a load test before launch" | `load-tester` | Pre-launch load validation |
+| "postmortem for yesterday's outage" | `incident-commander` | Postmortem workflow |
 
 ---