kodelyth-ecc 2.18.0 → 2.19.0

package/.agent/rules/self-improvement-workflow.md

@@ -0,0 +1,141 @@
+# Self-Improvement Workflow — Compound Learning System
+
+This rule encodes the workflow used by the Claude Code team internally, extended with ECC's three-layer compound memory architecture. Every session makes Claude more aligned with how YOU think and work.
+
+---
+
+## 1. Plan Node Default
+
+Enter plan mode for ANY non-trivial task (3+ steps, architectural decisions, or anything that touches more than 2 files):
+
+- Write the plan to `tasks/todo.md` with checkable items before writing a single line of code
+- If something goes sideways mid-task: STOP, re-plan, do not keep pushing
+- Use plan mode for verification steps, not just building
+- Write detailed specs upfront — ambiguity at start = bugs at end
+- Check plan with the user before executing when scope is large
+
+## 2. Subagent Strategy
+
+The 70 ECC specialist agents exist so the main context window stays clean:
+
+- Offload research, exploration, and parallel analysis to subagents
+- For complex problems: throw more compute via agents, not more tokens in main context
+- One task per subagent — focused execution beats monolithic threads
+- Intent routing picks the right specialist automatically — trust it
+
+## 3. Self-Improvement Loop (CRITICAL)
+
+**After ANY correction from the user — no matter how small — encode it permanently.**
+
+When the user says something like "no, don't do that", "use X instead", "I told you to", "wrong approach", "stop doing X":
+
+1. **Acknowledge** the correction in one line
+2. **Apply** it immediately in the current response
+3. **Encode** it: mentally append the rule to `tasks/lessons.md` in the project root
+
+The AI MUST track corrections within a session and apply them consistently from that point forward. The `capture-correction.js` hook writes them to disk automatically at session end.
+
+### How lessons compound
+
+```
+Session 1:  User corrects "use pnpm not npm" → lesson written
+Session 2:  Claude reads lesson → never uses npm again in this project
+Session 3+: New lessons stack → Claude increasingly matches YOUR style
+Month 3:    Claude works like a team member who has been here for years
+```
+
+**Review and extend lessons** at `tasks/lessons.md` — edit them freely, they are yours.
+
+## 4. Verification Before Done
+
+Never mark a task complete without proving it works:
+
+- Run the actual code, test, or command — do not assume
+- Diff behavior between baseline and your changes when relevant
+- Ask: "Would a staff engineer approve this PR?"
+- Run tests, check logs, demonstrate correctness with evidence
+- If verification fails: fix, do not close the loop
+
+## 5. Demand Elegance (Balanced)
+
+For non-trivial changes, pause before presenting:
+
+- Ask internally: "Is there a more elegant solution?"
+- If the fix feels hacky: "Knowing everything I know now, implement the elegant solution"
+- **Skip this for simple, obvious fixes** — do not over-engineer
+- Challenge your own work before presenting it
+- Three lines of clear code beat a clever one-liner every time
+
+## 6. Autonomous Bug Fixing
+
+When given a bug report: fix it. Do not ask for hand-holding:
+
+- Point at logs, errors, and failing tests — then resolve them
+- Zero context switching required from the user
+- Go fix failing CI tests without being told how
+- Use `debug-detective` for root cause analysis (never patch symptoms)
+- Use `silent-failure-hunter` when there is no error message
+
+---
+
+## Task Management Protocol
+
+When starting any non-trivial task:
+
+1. **Plan First** — write plan to `tasks/todo.md` with checkable items
+2. **Verify Plan** — check in before starting implementation on large tasks
+3. **Track Progress** — mark items complete as you go
+4. **Explain Changes** — high-level summary at each step
+5. **Document Results** — add review section to `tasks/todo.md`
+6. **Capture Lessons** — `tasks/lessons.md` is updated automatically by the correction hook
+
+---
+
+## Cross-Platform Lesson Loading
+
+**For Claude Code:** `tasks/lessons.md` is loaded automatically via SessionStart hook before your first message.
+
+**For all other platforms (Windsurf, Cursor, Codex, Antigravity, OpenCode):**
+At the start of every session, BEFORE doing anything else:
+1. Check if `tasks/lessons.md` exists in the project root
+2. If it exists: read it and apply all rules marked with `-` as hard, mandatory constraints for this session
+3. Announce: "Loaded N lessons from tasks/lessons.md — applying for this session."
+4. If it does not exist: proceed normally
+
+**Users on non-Claude-Code platforms:** run `/lessons` as your first message on any project that has a `tasks/lessons.md`. It will load and activate all your rules instantly.
+
+---
+
+## Three-Layer Compound Memory Architecture
+
+ECC uses three compounding memory layers — together they make Claude increasingly match how you think:
+
+### Layer 1 — Project Lessons (`tasks/lessons.md`)
+- Per-project. Human-readable. Hard rules.
+- Written automatically when you correct Claude (via `capture-correction.js` Stop hook)
+- Injected at session start (via `read-lessons.js` SessionStart hook)
+- Edit freely — these are YOUR rules for this project
+- Example: "Always use pnpm. Never npm. Never yarn."
+
+### Layer 2 — Global Memory (`~/.kodelythecc/memory/`)
+- Cross-project. BM25 fuzzy search. Solution patterns.
+- Captures solutions from every session
+- Auto-recalls relevant past solutions on every prompt you type
+- Example: "Last time you had a CORS issue in Express, you added this middleware..."
+
+### Layer 3 — Intent Routing (`rules/common/agent-intent-routing.md`)
+- Always-on. 70 specialists. Zero setup.
+- Routes your message to the right expert from the first word
+- No agent names needed — just describe the problem
+
+**Combined effect**: Layer 1 knows your project rules. Layer 2 knows your past solutions. Layer 3 knows your intent. Together they eliminate the ramp-up cost of every session.
+
+---
+
+## Core Principles
+
+- **Simplicity First** — make every change as simple as possible, impact minimal code
+- **No Laziness** — find root causes, no temporary fixes, senior developer standards
+- **Minimal Impact** — changes touch only what's necessary, avoid introducing bugs
+- **Immutability** — create new objects, never mutate existing ones
+- **No Guessing** — if uncertain, ask. Never fabricate facts or behavior.

package/.agent/rules/shell-portability.md

@@ -0,0 +1,70 @@
+# Shell Portability — commands that work on the user's machine, not just yours
+
+> Always-on. Every agent that runs a shell command loads this.
+
+An agent that suggests `timeout 30 npm test` on macOS has wasted the user's turn:
+`timeout` is GNU coreutils and **is not installed on macOS by default**. The same
+goes for half the flags people reach for by habit.
+
+The rule is simple: **assume nothing about the user's OS or installed tools.**
+Detect, or use the portable form.
+
+## Verified differences
+
+Every row below was checked on a stock macOS shell. These are not theoretical.
+
+| You reach for | Breaks on | Portable form |
+|---|---|---|
+| `timeout 30 cmd` | **macOS** — not installed | run without it, or `command -v timeout \|\| gtimeout` |
+| `stat -c %s f` | **macOS/BSD** | `stat -f %z f` on BSD; `wc -c < f` works everywhere |
+| `sed -i 's/a/b/' f` | **macOS/BSD** — needs an arg | `sed -i '' 's/a/b/' f` on BSD; or write to a temp and `mv` |
+| `grep -P '\d'` | **macOS/BSD** — no PCRE | `grep -E '[0-9]'` |
+| `readlink -f` | older BSD | `cd "$(dirname "$f")" && pwd -P` |
+| `rg` | **any OS** — ripgrep is not preinstalled | `grep -rn` |
+| `date -d` | **macOS/BSD** | `date -j` on BSD, or do date math in the language |
+| `find -printf` | **macOS/BSD** | `find ... -exec stat ...` or `-print0 \| xargs` |
+
+## Before running a tool that may be absent
+
+```bash
+command -v rg >/dev/null 2>&1 || echo "ripgrep not installed — using grep"
+```
+
+Prefer a single command that works everywhere over a clever one that works on
+yours. `grep -rn "pattern" .` is slower than `rg pattern` and it runs on every
+machine on earth.
+
+## Windows
+
+Windows users on PowerShell have neither `grep`, `sed`, nor `find` in the Unix
+sense. When a task can be done by the language runtime instead of the shell,
+**do it in the runtime** — `node -e`, `python -c` — which behaves identically on
+all three platforms.
+
+```bash
+# Fragile: three different behaviours on three platforms
+find . -name "*.js" -newermt "1 day ago"
+
+# Portable: one behaviour everywhere Node runs
+node -e "…"
+```
+
+## Paths
+
+- Never hardcode `/` as a separator in code — use the language's path join.
+- Never assume `$HOME` exists in a spawned process; on Windows it is `%USERPROFILE%`.
+- Quote every path variable: `"$file"`, not `$file`. Spaces in paths are normal
+  on macOS and Windows.
+
+## When the user reports "works on my machine"
+
+This table is the first thing to check, before deeper debugging. A surprising
+share of "the command did nothing" reports are a BSD/GNU flag difference, and
+`env-debugger` should reach for this rule immediately.
+
+## Checklist before suggesting a shell command
+
+- [ ] Does the binary exist on macOS, Linux, and Windows by default?
+- [ ] Are the flags the same across BSD and GNU?
+- [ ] Are all paths quoted?
+- [ ] Could the language runtime do this identically on all three instead?

package/.agent/rules/smart-debug.md

@@ -0,0 +1,241 @@
+---
+name: smart-debug
+description: Systematic debugging methodology — powered by Kodelyth. A step-by-step framework to diagnose any bug confidently across any language or framework. Prevents guess-and-check debugging, traces errors to their root cause, and produces a fix backed by evidence.
+origin: Kodelyth
+---
+
+# Smart Debug — Systematic Debugging Methodology
+
+A structured approach to debugging that works for any language, framework, or error type. Powered by Kodelyth.
+
+## When to Use
+
+- You have a bug that isn't obviously caused by the last change you made
+- You've tried a fix and it didn't work (or broke something else)
+- The error message is cryptic or misleading
+- The bug is intermittent or environment-specific
+- You're not sure where in the codebase the problem originates
+
+## How It Works
+
+Smart Debug applies the same process a seasoned senior engineer uses — but makes it explicit and repeatable. The core idea: **symptoms are not root causes**. Every step narrows the search space until you know exactly why the bug exists.
+
+## The 5-Step Framework
+
+### Step 1 — Characterize the Bug
+
+Before touching any code, answer these questions:
+
+```
+1. What is the exact error message or symptom? (copy it verbatim)
+2. Is it consistent or intermittent?
+3. What triggers it? (specific action, data input, timing, environment)
+4. When did it start? (after a code change, deployment, dependency update?)
+5. Where does it appear? (local only, staging, prod, specific browser/OS?)
+```
+
+This step alone eliminates 30% of debugging time by ruling out non-issues.
+
+### Step 2 — Read the Error, Not Just the Message
+
+Error messages have structure. Parse them:
+
+```
+[Error Type]: [Message]
+  at [function] ([file]:[line]:[column])
+  at [caller] ([file]:[line]:[column])
+  ...
+```
+
+**Read from the bottom of the stack trace up.** The bottom is the root call; the top is where it crashed.
+
+Find the **first line that references your own code** — that is your entry point.
+
+```bash
+# Common error classifications:
+TypeError           → wrong type passed, null/undefined accessed
+ReferenceError      → variable not defined or out of scope
+SyntaxError         → code can't be parsed (often a typo or missing bracket)
+RangeError          → value out of allowed range (infinite recursion, etc.)
+NetworkError / 4xx  → bad request — check what you're sending
+NetworkError / 5xx  → server crash — check server logs
+CORS Error          → origin policy mismatch — check headers
+Promise rejection   → async error not caught — check the chain above
+```
+
+### Step 3 — Form ONE Hypothesis
+
+Before running any code, state a hypothesis:
+
+```
+Hypothesis: The bug happens because [specific, technical reason].
+Evidence for this: [what in the code or logs suggests this].
+How to test: [what I will check or change to confirm/deny].
+```
+
+Only work one hypothesis at a time. If your test disproves it, form a new hypothesis — do not patch and pray.
+
+### Step 4 — Gather Evidence
+
+Check each source of truth in order:
+
+**A. The error site**
+```bash
+# Read 30 lines around the crash location
+# Understand what data was expected vs what arrived
+```
+
+**B. Recent changes**
+```bash
+git log --oneline -10 -- path/to/affected/file
+git diff HEAD~3 -- path/to/affected/file
+```
+
+**C. Data flowing in**
+```bash
+# Add a temporary log just before the crash
+console.log('DEBUG value at crash point:', variableName)
+# What does it actually contain vs what you expected?
+```
+
+**D. All callers**
+```bash
+grep -rn "functionName\|ClassName" src/
+# Is anyone calling this incorrectly?
+```
+
+**E. Dependencies / environment**
+```bash
+# Has a package version changed?
+git diff HEAD~10 package-lock.json | grep '"version"'
+
+# Is an env variable missing?
+echo $MY_VARIABLE
+```
+
+### Step 5 — Fix and Verify
+
+Once you've confirmed the root cause:
+
+1. **Make the minimal fix** — change only what's needed to address the root cause
+2. **Explain why it works** — if you can't explain it, you don't understand it yet
+3. **Test the fix** — reproduce the original symptom, confirm it's gone
+4. **Test adjacent behavior** — did the fix break anything nearby?
+5. **Add a regression test** — so this bug can never silently return
+
+```typescript
+// Before fix (document what was wrong)
+// BUG: user.profile could be undefined when user is a guest account
+const name = user.profile.name  // crashes for guest users
+
+// After fix (document why this is correct)
+// FIXED: optional chaining handles guest accounts (profile is null for guests)
+const name = user.profile?.name ?? 'Guest'
+```
+
+## Language-Specific Debugging Tips
+
+### TypeScript / JavaScript
+
+```typescript
+// Check for undefined at runtime even when types say it's safe
+console.log(typeof value, value)
+
+// Trace async errors to their source
+async function riskyOp() {
+  try {
+    return await fetch(url)
+  } catch (e) {
+    console.error('[riskyOp] failed:', e.message, { url })
+    throw e  // re-throw so caller knows it failed
+  }
+}
+
+// Find stale closure bugs
+useEffect(() => {
+  console.log('effect ran with:', { count, userId }) // log deps
+}, [count, userId])
+```
+
+### Python
+
+```python
+# Print full traceback, not just the last line
+import traceback
+try:
+    risky_call()
+except Exception as e:
+    traceback.print_exc()
+
+# Check types at runtime
+print(type(value), repr(value))
+
+# Isolate in a REPL
+python3 -c "from module import func; print(func(test_input))"
+```
+
+### Go
+
+```go
+// Always check error values
+result, err := someOperation()
+if err != nil {
+    log.Printf("someOperation failed: %v (input: %+v)", err, input)
+    return nil, fmt.Errorf("someOperation: %w", err)
+}
+
+// Use fmt.Sprintf for complex struct inspection
+fmt.Printf("value: %+v\n", myStruct)
+```
+
+### SQL / Database
+
+```sql
+-- Run the query manually with the exact values from the bug
+-- EXPLAIN ANALYZE to see query plan
+EXPLAIN ANALYZE SELECT * FROM users WHERE id = 123;
+
+-- Check for NULL propagation
+SELECT COALESCE(column_name, 'DEFAULT') FROM table;
+
+-- Check constraint violations
+SELECT * FROM pg_constraint WHERE conname = 'constraint_name';
+```
+
+## Common Root Causes by Symptom
+
+| Symptom | Most likely root cause |
+|---|---|
+| Works locally, fails in prod | Missing env variable, different data, different dependency version |
+| Works first time, fails after | State mutation, missing cleanup, memory leak |
+| Fails only for specific users | Permission issue, data-specific edge case, locale/timezone |
+| Intermittent failure | Race condition, network timeout, cache miss |
+| Broke after a "safe" refactor | Changed behavior, not just structure — test coverage gap |
+| Type error on a "correct" type | Async data not yet loaded, API response shape changed |
+| Infinite loop / stack overflow | Circular dependency, missing base case, recursive state update |
+
+## Red Flags That Mean You Haven't Found the Root Cause
+
+- Your fix is "just try X and see"
+- You changed multiple things at once
+- You can't explain *why* the fix works
+- The bug appears to be "gone" but you're not sure how
+- You're patching the symptom (e.g., `|| ''`) without understanding why the value was missing
+
+If any of these apply, go back to Step 3.
+
+## Rubber Duck Checklist
+
+When you're stuck, explain the bug out loud (or in writing) as if to someone with no context:
+
+1. What should happen?
+2. What actually happens?
+3. At what exact point does reality diverge from expectation?
+4. What is the data state at that point?
+5. What code runs between "expected" and "actual"?
+
+The act of articulating the problem often reveals the solution.
+
+---
+
+> Powered by Kodelyth — trace first, fix second, never guess.

package/.agent/rules/testing.md

@@ -0,0 +1,65 @@
+---
+paths:
+  - "**/*.rb"
+  - "**/*_spec.rb"
+  - "**/spec/**"
+---
+# Ruby Testing
+
+> This file extends [common/testing.md](../common/testing.md) with Ruby specific content.
+
+## Framework
+
+Use **RSpec** as the testing framework. Use **FactoryBot** for fixtures.
+
+## Structure
+
+```ruby
+# frozen_string_literal: true
+
+RSpec.describe CreateUserService do
+  subject(:service) { described_class.new(params) }
+
+  let(:params) { { name: "Alice", email: "alice@example.com" } }
+
+  describe "#call" do
+    context "with valid params" do
+      it "creates a user" do
+        expect { service.call }.to change(User, :count).by(1)
+      end
+    end
+
+    context "with invalid params" do
+      let(:params) { { name: "", email: "bad" } }
+
+      it "raises an error" do
+        expect { service.call }.to raise_error(ActiveRecord::RecordInvalid)
+      end
+    end
+  end
+end
+```
+
+## Coverage
+
+```bash
+COVERAGE=true bundle exec rspec
+```
+
+Use **SimpleCov** for coverage reporting. Target 90%+ for new code.
+
+## Factories
+
+```ruby
+FactoryBot.define do
+  factory :user do
+    sequence(:email) { |n| "user#{n}@example.com" }
+    name { Faker::Name.name }
+    status { :active }
+  end
+end
+```
+
+## Reference
+
+See skill: `ruby-testing` for detailed RSpec patterns, shared examples, and Rails request specs.