kodelyth-ecc 2.19.0 → 2.20.0

package/.gemini/skills/kodelyth-memory/SKILL.md

@@ -1,136 +0,0 @@
----
-name: kodelyth-memory
-description: Local self-learning memory for AI coding sessions. Captures what works, recalls it next time, shapes context for prompt-cache savings. Zero dependencies, zero telemetry, model-agnostic.
----
-
-# Kodelyth Memory — Skill
-
-## When to use
-
-- **At session start** when the task touches a domain the user has worked in before (auth, payments, database, deployment, API integration)
-- **When the user says "that worked"** or signals success after struggle — capture the lesson
-- **When the user asks "have I done this before?"** or seems to be repeating past work
-- **When starting a new feature** in a project with existing memory
-
-## How it works
-
-```
-┌─────────────────┐    capture    ┌─────────────────┐    inject    ┌─────────────────┐
-│  Past session   │ ─────────────→│  ~/.kodelythecc/   │─────────────→│  Next session   │
-│  (you solved X) │               │  memory/        │              │  (X comes up)   │
-└─────────────────┘               └─────────────────┘              └─────────────────┘
-                                          │
-                                          │  BM25 keyword + tag retrieval
-                                          │  No embeddings, no network
-                                          ↓
-                                  Cache-friendly context block
-                                  (stable prefix → cheap re-reads)
-```
-
-## Storage layout
-
-All under `~/.kodelythecc/memory/` (override with `KODELYTH_MEMORY_DIR`):
-
-| File | Purpose |
-|---|---|
-| `memories.jsonl` | Append-only log — every captured memory |
-| `index.json` | Inverted BM25 index for fast retrieval |
-| `patterns.json` | User-level recurring patterns (auto-derived) |
-| `projects/<hash>.json` | Per-project shortcut indexes |
-
-## Why BM25 instead of embeddings
-
-| Embeddings (OpenAI/local) | BM25 (what we use) |
-|---|---|
-| Semantic match — finds related ideas with no shared words | Keyword + tag match |
-| Requires either network calls or 50MB+ local model | Pure JS, ~3KB |
-| Adds 200-2000ms latency per query | Sub-millisecond |
-| Cost per session | Free forever |
-| Privacy: leaks query text to provider | Stays local |
-
-For coding memory, the things you want to recall **almost always share vocabulary** with the trigger — file paths, library names, error strings, framework terms. BM25 nails this. We deliberately chose worse semantic match for vastly better latency, privacy, and cost.
-
-## CLI cheatsheet
-
-```bash
-# Add a memory manually
-node scripts/memory/cli.js remember "Stripe webhook signature failed in production" \
-  --approach "Switched body parser from json to raw, validated with constructEvent" \
-  --tags payments,stripe,webhooks \
-  --language typescript
-
-# Search
-node scripts/memory/cli.js search "stripe webhook"
-
-# Show what would be injected at session start
-node scripts/memory/cli.js inject --query "add stripe payments"
-
-# Extract memory candidates from a Claude Code session log
-node scripts/memory/cli.js extract ~/.claude/projects/<project>/<session>.jsonl
-
-# List all memories
-node scripts/memory/cli.js list
-
-# Storage stats
-node scripts/memory/cli.js stats
-
-# Forget one
-node scripts/memory/cli.js forget <id>
-```
-
-## Slash command
-
-In Claude Code:
-
-```
-/memory                          # Show stats and recent memories
-/memory recall <query>           # Search and surface matches
-/memory remember <title>         # Capture a new memory (interactive)
-/memory forget <id>              # Delete one
-/memory review-session           # Extract candidates from current session
-```
-
-## Cache-friendly injection
-
-The injected context block is structured for prompt cache reuse:
-
-```
-[STABLE PREFIX — cached after first call, ~10% cost on subsequent calls]
-  ## Your recurring patterns (built from N sessions)
-  ## Recent solutions in this project
-  ## Detected stack: typescript, next, postgres
-
-[VARIABLE SUFFIX — varies per query]
-  ## Relevant to your current task: "<query>"
-```
-
-For Anthropic models the cache TTL is 5 minutes — typing back-to-back during a coding session keeps the prefix warm. For OpenAI models the prefix is automatically cached when ≥1024 tokens. Other models (Gemini, Llama, Mistral) do not currently cache, so for them the benefit is purely the recall quality, not cost reduction.
-
-## Honest limits
-
-- **Not "the model learns"** — the model is unchanged. We're just feeding it better context.
-- **Per-machine by default** — sync via Dropbox/iCloud/git on `~/.kodelythecc/memory/` if needed.
-- **Cloud-AI platforms** (Windsurf, Antigravity, partial Cursor) — session data is server-side. Auto-extract from past sessions doesn't work there. Manual `/memory remember` still does.
-- **Privacy** — every byte stays on your disk. Verify with `ls -la ~/.kodelythecc/memory/`.
-
-## Anti-patterns
-
-| Don't | Do |
-|---|---|
-| Auto-capture every conversation | Capture only when user signals success |
-| Inject all memories on every session | Inject relevant + recent + patterns only |
-| Capture without showing user the draft | Always confirm before storing |
-| Recall the same memory twice in one session | Track surfaced memories per session |
-| Treat memory as ground truth | Memory is a hint — current task may differ |
-
-## Files in this skill
-
-- `agents/kodelyth-memory.md` — the agent persona and protocols
-- `scripts/memory/store.js` — storage + BM25 retrieval
-- `scripts/memory/inject.js` — cache-friendly context block builder
-- `scripts/memory/extract.js` — heuristic learning extractor for session logs
-- `scripts/memory/cli.js` — command-line entry point
-- `hooks/memory/capture-stop.js` — Stop hook that runs extractor on session end
-- `hooks/memory/inject-start.js` — SessionStart hook that runs `inject`
-- `commands/memory.md` — `/memory` slash command
-- `rules/common/memory-protocol.md` — when AI should query memory mid-session

package/.gemini/skills/kodelyth-quickstart/SKILL.md

@@ -1,214 +0,0 @@
----
-name: kodelyth-quickstart
-description: Friendly getting-started guide — powered by Kodelyth. A plain-language introduction to Kodelyth ECC for new users. Explains what agents, skills, commands, and hooks are in simple terms, and guides you to the right tool for your task. Read this first.
-origin: Kodelyth
----
-
-# Kodelyth Quickstart — Getting Started with Kodelyth ECC
-
-Welcome. This guide explains Kodelyth ECC (ECC) in plain language so you can start using it confidently in the first 10 minutes.
-
-> Powered by Kodelyth — making AI tooling friendly from the first interaction.
-
-## What Is This?
-
-Kodelyth ECC is a **plugin that makes Claude Code smarter**. It adds:
-
-- **Agents** — specialists you delegate tasks to (like hiring a contractor for a specific job)
-- **Skills** — domain knowledge loaded into Claude's context (like giving Claude a textbook to reference)
-- **Commands** — shortcuts to trigger common workflows (like macros)
-- **Hooks** — automatic actions that run before/after Claude does things (like background safety checks)
-
-You don't need to use all of them. Start with what solves your current problem.
-
-## The 4 Things You Need to Know
-
-### 1. Agents — Specialists for Specific Jobs
-
-Agents are like calling a specialist instead of doing it yourself. You delegate a task to an agent and it handles it end-to-end.
-
-**When to use an agent**: when you have a specific, defined task that matches an expert's domain.
-
-```
-# To use an agent, just say:
-"use code-reviewer"
-"use planner"
-"use debug-detective"
-```
-
-**Kodelyth agents added to this repo:**
-
-| Agent | What it does |
-|---|---|
-| `kodelyth-advisor` | Not sure what to use? Ask this agent — it guides you to the right tool |
-| `debug-detective` | Traces bugs to their root cause step by step — never guesses |
-| `ux-reviewer` | Reviews frontend code for UX and accessibility issues |
-
-**Other useful built-in agents:**
-
-| Agent | When to use it |
-|---|---|
-| `planner` | Before starting a complex feature |
-| `code-reviewer` | After writing or changing code |
-| `security-reviewer` | When code touches auth, payments, or user data |
-| `refactor-cleaner` | When code has grown messy |
-| `build-error-resolver` | When a build or compile is failing |
-| `tdd-guide` | When you want to write tests properly |
-| `performance-optimizer` | When something is slow |
-
----
-
-### 2. Skills — Domain Knowledge on Demand
-
-Skills load expert knowledge into Claude's context for a specific topic. They're not agents — they don't do a task for you. They give Claude the right context to do it well.
-
-**When to use a skill**: when you're working in a specific language, framework, or domain and want Claude to follow best practices for it.
-
-```
-# To use a skill, type the skill name as a command:
-/python-patterns
-/golang-patterns
-/postgres-patterns
-/docker-patterns
-/coding-standards
-```
-
-**Kodelyth skills added to this repo:**
-
-| Skill | What it covers |
-|---|---|
-| `/kodelyth-quickstart` | This guide — plain-language intro to ECC |
-| `/smart-debug` | Systematic debugging framework for any language |
-
-**Other useful built-in skills:**
-
-| Skill | When to use it |
-|---|---|
-| `/coding-standards` | General code quality rules (naming, structure, etc.) |
-| `/python-patterns` | Python best practices |
-| `/golang-patterns` | Go best practices |
-| `/typescript-patterns` | TypeScript/React best practices |
-| `/postgres-patterns` | Database query and schema patterns |
-| `/docker-patterns` | Container and Docker Compose patterns |
-| `/security-review` | Security audit guidance |
-| `/api-design` | REST API design conventions |
-
----
-
-### 3. Commands — Workflow Shortcuts
-
-Commands trigger multi-step workflows with a single slash command.
-
-**When to use commands**: for repeatable workflows you do often.
-
-```
-/tdd          → Start test-driven development workflow
-/plan         → Create an implementation plan
-/code-review  → Trigger a quality review
-/build-fix    → Fix a broken build
-/e2e          → Generate and run E2E tests
-/learn        → Extract reusable patterns from this session
-```
-
----
-
-### 4. Hooks — Automatic Background Protection
-
-Hooks run automatically — you don't invoke them. They silently protect you from common mistakes.
-
-**What's running in the background right now:**
-
-| Hook | What it does |
-|---|---|
-| Session start | Loads context from your last session |
-| Pre-commit check | Catches `console.log`, secrets, and bad commit messages |
-| Quality gate | Runs type checks and formatting after you edit files |
-| Git push reminder | Prompts you to review before pushing |
-| Cost tracker | Logs token usage per session |
-| Desktop notify | Sends a macOS notification when Claude finishes a long task |
-
-You don't need to do anything — hooks are already active.
-
----
-
-## Your First 5 Minutes — A Practical Path
-
-**Step 1: Get guidance on what to use**
-```
-use kodelyth-advisor
-```
-Tell it what you're building. It will recommend the right agents and skills.
-
-**Step 2: Load the right skill for your stack**
-```
-/python-patterns          # if you're working in Python
-/typescript-patterns      # if you're working in TypeScript/React
-/golang-patterns          # if you're working in Go
-/coding-standards         # if you want general best practices
-```
-
-**Step 3: Plan your feature before coding**
-```
-use planner
-```
-Describe what you want to build. The planner will produce a phased implementation plan.
-
-**Step 4: After you write code, review it**
-```
-use code-reviewer
-```
-This catches security issues, code quality problems, and missing tests before they become problems.
-
-**Step 5: If something breaks, debug it systematically**
-```
-use debug-detective
-/smart-debug
-```
-Tell the agent the symptom. It will trace the bug to its root cause.
-
-**Bonus: See your AI workspace at a glance**
-```
-npx kodelyth-ecc dashboard
-```
-Opens the local observability dashboard at `http://127.0.0.1:5747`. Inspect memory captures, BM25 search across past solutions, evolve proposals, the full skill and agent catalog, swarm sessions, and token-budget snapshots — all local, zero telemetry.
-
----
-
-## Common Questions
-
-**Q: What's the difference between an agent and a skill?**
-An agent *does* something (takes actions, reads files, writes code). A skill *informs* Claude (loads reference knowledge into context). Use agents for tasks, skills for expertise.
-
-**Q: How do I know which agent to use?**
-When in doubt: `use kodelyth-advisor` — it will recommend the right one for your situation.
-
-**Q: Can I use multiple skills at once?**
-Yes. Load any combination of skills and Claude will use all of them.
-
-**Q: Do hooks cost me tokens?**
-Minimal. Most hooks are fast shell scripts that run outside Claude's context window.
-
-**Q: The command didn't do anything obvious — is it working?**
-Commands load context into the conversation. Claude will then follow the skill's guidance in its next response. Try asking a question related to the skill topic.
-
----
-
-## Quick Reference Card
-
-```
-NOT SURE WHERE TO START?    →  use kodelyth-advisor
-PLANNING A FEATURE?         →  use planner  or  /plan
-REVIEWING CODE?             →  use code-reviewer  or  /code-review
-DEBUGGING?                  →  use debug-detective  or  /smart-debug
-SECURITY CONCERN?           →  use security-reviewer
-TESTS NEEDED?               →  use tdd-guide  or  /tdd
-BUILD BROKEN?               →  use build-error-resolver  or  /build-fix
-UX REVIEW?                  →  use ux-reviewer
-LOAD LANGUAGE PATTERNS?     →  /python-patterns, /golang-patterns, etc.
-GENERAL CODE STANDARDS?     →  /coding-standards
-OBSERVABILITY DASHBOARD?    →  npx kodelyth-ecc dashboard  (localhost:5747)
-```
-
----
-
-> Powered by Kodelyth — you got this.

package/.gemini/skills/kotlin-coroutines-flows/SKILL.md

@@ -1,284 +0,0 @@
----
-name: kotlin-coroutines-flows
-description: Kotlin Coroutines and Flow patterns for Android and KMP — structured concurrency, Flow operators, StateFlow, error handling, and testing.
-origin: ECC
----
-
-# Kotlin Coroutines & Flows
-
-Patterns for structured concurrency, Flow-based reactive streams, and coroutine testing in Android and Kotlin Multiplatform projects.
-
-## When to Activate
-
-- Writing async code with Kotlin coroutines
-- Using Flow, StateFlow, or SharedFlow for reactive data
-- Handling concurrent operations (parallel loading, debounce, retry)
-- Testing coroutines and Flows
-- Managing coroutine scopes and cancellation
-
-## Structured Concurrency
-
-### Scope Hierarchy
-
-```
-Application
-  └── viewModelScope (ViewModel)
-        └── coroutineScope { } (structured child)
-              ├── async { } (concurrent task)
-              └── async { } (concurrent task)
-```
-
-Always use structured concurrency — never `GlobalScope`:
-
-```kotlin
-// BAD
-GlobalScope.launch { fetchData() }
-
-// GOOD — scoped to ViewModel lifecycle
-viewModelScope.launch { fetchData() }
-
-// GOOD — scoped to composable lifecycle
-LaunchedEffect(key) { fetchData() }
-```
-
-### Parallel Decomposition
-
-Use `coroutineScope` + `async` for parallel work:
-
-```kotlin
-suspend fun loadDashboard(): Dashboard = coroutineScope {
-    val items = async { itemRepository.getRecent() }
-    val stats = async { statsRepository.getToday() }
-    val profile = async { userRepository.getCurrent() }
-    Dashboard(
-        items = items.await(),
-        stats = stats.await(),
-        profile = profile.await()
-    )
-}
-```
-
-### SupervisorScope
-
-Use `supervisorScope` when child failures should not cancel siblings:
-
-```kotlin
-suspend fun syncAll() = supervisorScope {
-    launch { syncItems() }       // failure here won't cancel syncStats
-    launch { syncStats() }
-    launch { syncSettings() }
-}
-```
-
-## Flow Patterns
-
-### Cold Flow — One-Shot to Stream Conversion
-
-```kotlin
-fun observeItems(): Flow<List<Item>> = flow {
-    // Re-emits whenever the database changes
-    itemDao.observeAll()
-        .map { entities -> entities.map { it.toDomain() } }
-        .collect { emit(it) }
-}
-```
-
-### StateFlow for UI State
-
-```kotlin
-class DashboardViewModel(
-    observeProgress: ObserveUserProgressUseCase
-) : ViewModel() {
-    val progress: StateFlow<UserProgress> = observeProgress()
-        .stateIn(
-            scope = viewModelScope,
-            started = SharingStarted.WhileSubscribed(5_000),
-            initialValue = UserProgress.EMPTY
-        )
-}
-```
-
-`WhileSubscribed(5_000)` keeps the upstream active for 5 seconds after the last subscriber leaves — survives configuration changes without restarting.
-
-### Combining Multiple Flows
-
-```kotlin
-val uiState: StateFlow<HomeState> = combine(
-    itemRepository.observeItems(),
-    settingsRepository.observeTheme(),
-    userRepository.observeProfile()
-) { items, theme, profile ->
-    HomeState(items = items, theme = theme, profile = profile)
-}.stateIn(viewModelScope, SharingStarted.WhileSubscribed(5_000), HomeState())
-```
-
-### Flow Operators
-
-```kotlin
-// Debounce search input
-searchQuery
-    .debounce(300)
-    .distinctUntilChanged()
-    .flatMapLatest { query -> repository.search(query) }
-    .catch { emit(emptyList()) }
-    .collect { results -> _state.update { it.copy(results = results) } }
-
-// Retry with exponential backoff
-fun fetchWithRetry(): Flow<Data> = flow { emit(api.fetch()) }
-    .retryWhen { cause, attempt ->
-        if (cause is IOException && attempt < 3) {
-            delay(1000L * (1 shl attempt.toInt()))
-            true
-        } else {
-            false
-        }
-    }
-```
-
-### SharedFlow for One-Time Events
-
-```kotlin
-class ItemListViewModel : ViewModel() {
-    private val _effects = MutableSharedFlow<Effect>()
-    val effects: SharedFlow<Effect> = _effects.asSharedFlow()
-
-    sealed interface Effect {
-        data class ShowSnackbar(val message: String) : Effect
-        data class NavigateTo(val route: String) : Effect
-    }
-
-    private fun deleteItem(id: String) {
-        viewModelScope.launch {
-            repository.delete(id)
-            _effects.emit(Effect.ShowSnackbar("Item deleted"))
-        }
-    }
-}
-
-// Collect in Composable
-LaunchedEffect(Unit) {
-    viewModel.effects.collect { effect ->
-        when (effect) {
-            is Effect.ShowSnackbar -> snackbarHostState.showSnackbar(effect.message)
-            is Effect.NavigateTo -> navController.navigate(effect.route)
-        }
-    }
-}
-```
-
-## Dispatchers
-
-```kotlin
-// CPU-intensive work
-withContext(Dispatchers.Default) { parseJson(largePayload) }
-
-// IO-bound work
-withContext(Dispatchers.IO) { database.query() }
-
-// Main thread (UI) — default in viewModelScope
-withContext(Dispatchers.Main) { updateUi() }
-```
-
-In KMP, use `Dispatchers.Default` and `Dispatchers.Main` (available on all platforms). `Dispatchers.IO` is JVM/Android only — use `Dispatchers.Default` on other platforms or provide via DI.
-
-## Cancellation
-
-### Cooperative Cancellation
-
-Long-running loops must check for cancellation:
-
-```kotlin
-suspend fun processItems(items: List<Item>) = coroutineScope {
-    for (item in items) {
-        ensureActive()  // throws CancellationException if cancelled
-        process(item)
-    }
-}
-```
-
-### Cleanup with try/finally
-
-```kotlin
-viewModelScope.launch {
-    try {
-        _state.update { it.copy(isLoading = true) }
-        val data = repository.fetch()
-        _state.update { it.copy(data = data) }
-    } finally {
-        _state.update { it.copy(isLoading = false) }  // always runs, even on cancellation
-    }
-}
-```
-
-## Testing
-
-### Testing StateFlow with Turbine
-
-```kotlin
-@Test
-fun `search updates item list`() = runTest {
-    val fakeRepository = FakeItemRepository().apply { emit(testItems) }
-    val viewModel = ItemListViewModel(GetItemsUseCase(fakeRepository))
-
-    viewModel.state.test {
-        assertEquals(ItemListState(), awaitItem())  // initial
-
-        viewModel.onSearch("query")
-        val loading = awaitItem()
-        assertTrue(loading.isLoading)
-
-        val loaded = awaitItem()
-        assertFalse(loaded.isLoading)
-        assertEquals(1, loaded.items.size)
-    }
-}
-```
-
-### Testing with TestDispatcher
-
-```kotlin
-@Test
-fun `parallel load completes correctly`() = runTest {
-    val viewModel = DashboardViewModel(
-        itemRepo = FakeItemRepo(),
-        statsRepo = FakeStatsRepo()
-    )
-
-    viewModel.load()
-    advanceUntilIdle()
-
-    val state = viewModel.state.value
-    assertNotNull(state.items)
-    assertNotNull(state.stats)
-}
-```
-
-### Faking Flows
-
-```kotlin
-class FakeItemRepository : ItemRepository {
-    private val _items = MutableStateFlow<List<Item>>(emptyList())
-
-    override fun observeItems(): Flow<List<Item>> = _items
-
-    fun emit(items: List<Item>) { _items.value = items }
-
-    override suspend fun getItemsByCategory(category: String): Result<List<Item>> {
-        return Result.success(_items.value.filter { it.category == category })
-    }
-}
-```
-
-## Anti-Patterns to Avoid
-
-- Using `GlobalScope` — leaks coroutines, no structured cancellation
-- Collecting Flows in `init {}` without a scope — use `viewModelScope.launch`
-- Using `MutableStateFlow` with mutable collections — always use immutable copies: `_state.update { it.copy(list = it.list + newItem) }`
-- Catching `CancellationException` — let it propagate for proper cancellation
-- Using `flowOn(Dispatchers.Main)` to collect — collection dispatcher is the caller's dispatcher
-- Creating `Flow` in `@Composable` without `remember` — recreates the flow every recomposition
-
-## References
-
-See skill: `compose-multiplatform-patterns` for UI consumption of Flows.
-See skill: `android-clean-architecture` for where coroutines fit in layers.