kodelyth-ecc 2.19.0 → 2.20.0

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

@@ -1,141 +0,0 @@
-# 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

@@ -1,70 +0,0 @@
-# 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

@@ -1,241 +0,0 @@
----
-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

@@ -1,65 +0,0 @@
----
-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.