kodelyth-ecc 1.4.0 → 1.5.0

package/wiki/Agent-Reference.md

@@ -1,199 +1,397 @@
 # Agent Reference
 
-53 specialist agents — each one a decade-experienced engineer in a specific domain.
+59 specialist agents — each one a decade-experienced engineer in a specific domain.
 
 ---
 
-## Kodelyth Exclusive (6 agents)
+## How Agents Are Invoked
 
-These agents exist only in Kodelyth ECC.
-
-### `kodelyth-advisor` — The Master Guide
-
-Reads your situation, understands what you're struggling with, and gives you the exact tool or approach needed. No hand-holding, no noise — direct senior-grade direction.
+**Automatic (intent routing):** Most agents fire automatically from your message text. The routing rule analyzes 10 priority tiers and 50+ trigger patterns.
 
+**Explicit invocation:**
 ```
-use kodelyth-advisor
+use debug-detective
+@code-reviewer
+invoke security-reviewer
 ```
 
-Best for: "I don't know where to start", picking the right agent, unclear problems.
+**Explicit always works.** When in doubt, use it. Routing is an accelerant, not a replacement.
 
 ---
 
-### `debug-detective` — The Root Cause Hunter
+## Kodelyth Exclusive Agents
 
-Never guesses. Traces every bug to its exact origin through a structured hypothesis protocol. Binary search debug, git bisect, minimal reproducers, advanced tracing.
+These agents were designed and built specifically for this toolkit.
 
-```
-use debug-detective
-```
+### `kodelyth-advisor`
+
+Master engineering advisor. Reads your emotional state, feels what you're stuck on, and gives precise senior-grade direction. Knows every agent, skill, and command. Responds differently to frustration vs. excitement vs. confusion.
 
-Best for: Hard bugs, intermittent failures, "I've tried everything" situations.
+**When to use:** Lost, overwhelmed, don't know where to start, or need a second opinion on your approach.
+
+**Triggers:** "help me", "what should I", "I'm stuck", "don't know where to start", "overwhelmed"
 
 ---
 
-### `ux-reviewer` — The Interface Guardian
+### `debug-detective`
 
-Reviews frontend code for usability, interaction logic, and WCAG 2.1 AA accessibility. **Never touches design aesthetic** — only behavior.
+Systematic root-cause analyst. Never guesses. Never patches symptoms. Traces every bug to its exact origin through formal hypothesis protocol: CLAIM → EVIDENCE → TEST.
 
-```
-use ux-reviewer
-```
+**When to use:** Any bug with a stack trace, error message, or reproducible failure.
 
-Best for: Before shipping any frontend feature, accessibility audits.
+**Triggers:** "error", "bug", "crash", "exception", "undefined", "null", "traceback", "failing"
 
 ---
 
-### `api-guardian` — The Contract Protector
+### `ux-reviewer`
 
-Detects breaking API changes before they ship. Classifies every change as BREAKING / SAFE / WARN, generates consumer impact reports, enforces versioning and deprecation headers.
+Master UX and accessibility engineer. Explicitly never touches visual design. Focuses on interaction logic, error states, loading states, mobile/touch, keyboard navigation, and screen readers. Full WCAG 2.1 AA review with before/after code examples.
 
-```
-use api-guardian
-```
+**When to use:** Frontend code review, accessibility audit, interaction behavior analysis.
 
-Best for: API changes, version bumps, public endpoint modifications.
+**Triggers:** "UI", "UX", "accessibility", "a11y", "WCAG", "screen reader", "keyboard nav", "frontend"
 
 ---
 
-### `pair-programmer` — The Pre-Code Thinker
+### `kodelyth-memory`
 
-The engineer who sits next to you before you start coding. Catches the wrong approach, over-engineering, missed edge cases — before a single line is written.
+Self-learning memory manager. Captures problems and solutions from sessions. Recalls them via BM25 search when relevant. Manages the full memory lifecycle: capture → review → store → inject → recall.
 
-```
-use pair-programmer
-```
+**When to use:** Search past solutions, manually store a learning, review pending captures, manage the memory store.
 
-Best for: Before starting any feature, evaluating approaches.
+**Commands:** `/memory recall`, `/memory remember`, `/memory review-pending`, `/memory stats`, `/memory forget`
+
+**Triggers:** "remember when", "we solved this before", "past solution", "memory", "/memory"
 
 ---
 
-### `migration-guide` — The Migration Specialist
+## Debugging Agents
 
-Full migration playbooks: React 18→19, Next.js 12→15, Python 2→3, Node.js 14→22, TypeScript 4→5, Java 8→21. Phase by phase: audit → blast radius → phased plan → execute → validate.
+### `debug-detective`
+*(see Kodelyth Exclusive above)*
 
-```
-use migration-guide
-```
+### `silent-failure-hunter`
+
+Finds bugs that produce no error — swallowed exceptions, bad fallbacks, misleading success responses, missing error propagation. Reviews code for all the places errors go to die.
+
+**When to use:** "It's not crashing but it's wrong", missing data, unexpected behavior with no error.
+
+**Triggers:** "no error but", "silently", "swallow", "empty response", "missing data", "unexpected behavior"
+
+---
+
+## Security Agents
+
+### `security-reviewer`
+
+OWASP Top 10 specialist. Flags secrets in code, SQL injection risks, SSRF vectors, unsafe cryptography, XSS, CSRF, path traversal, and authentication bypasses. Runs after every security-sensitive change.
+
+**When to use:** Any change touching authentication, user input, database queries, file system operations, payments, or external API calls.
+
+**Triggers:** "auth", "password", "token", "API key", "SQL", "user input", "permission", "encrypt"
+
+---
+
+## Code Quality Agents
+
+### `code-reviewer`
+
+General quality reviewer. Checks readability, function size, file cohesion, nesting depth, error handling, hardcoded values, mutation patterns, and test coverage. Severity levels: CRITICAL / HIGH / MEDIUM / LOW.
+
+**When to use:** After writing or modifying any code, before committing.
+
+**Triggers:** "review", "check my code", "is this good", "look at this"
+
+### `typescript-reviewer`
 
-Best for: Framework upgrades, language version migrations.
+TypeScript/JavaScript specialist. Type safety, async correctness, `any` avoidance, Zod schema validation, React prop types, idiomatic patterns.
+
+**When to use:** TypeScript or JavaScript files.
+
+### `python-reviewer`
+
+PEP 8, type hints, Pythonic idioms, security, performance. Flask/Django/FastAPI patterns.
+
+**When to use:** Python files.
+
+### `go-reviewer`
+
+Idiomatic Go, error handling patterns, goroutine safety, interface design, performance.
+
+**When to use:** Go files.
+
+### `rust-reviewer`
+
+Ownership, lifetimes, unsafe usage, error handling with Result/Option, idiomatic patterns.
+
+**When to use:** Rust files.
+
+### `java-reviewer`
+
+Spring Boot architecture, JPA patterns, async with CompletableFuture, security.
+
+**When to use:** Java/Spring Boot files.
+
+### `kotlin-reviewer`
+
+Coroutine safety, Compose best practices, Android patterns, clean architecture violations.
+
+**When to use:** Kotlin/Android files.
+
+### `csharp-reviewer`
+
+.NET conventions, async/await patterns, nullable reference types, Entity Framework.
+
+**When to use:** C# files.
+
+### `flutter-reviewer`
+
+Flutter widget best practices, state management, Dart idioms, performance pitfalls.
+
+**When to use:** Flutter/Dart files.
+
+### `cpp-reviewer`
+
+Memory safety, modern C++ idioms, RAII, concurrency, template usage.
+
+**When to use:** C++ files.
 
 ---
 
-## Code Review (10 agents)
+## Planning Agents
+
+### `planner`
+
+Full implementation planner. Generates PRD, architecture, system design, tech doc, and task list before any code is written. Identifies dependencies and risks. Breaks work into phases.
+
+**When to use:** Any new feature or significant refactor.
+
+**Triggers:** "plan", "implement", "build", "create a feature", "refactor"
+
+### `pair-programmer`
+
+Pre-code thinking partner. Runs the "cost curve of bugs" check (thinking=0x, code review=6x, production=200x). Catches wrong abstractions, premature optimization, missing idempotency, over-engineering before a line is written.
+
+**When to use:** Before implementing anything significant.
+
+**Triggers:** "thinking about", "approach for", "design for", "before I write"
+
+### `architect`
+
+System design and scalability specialist. Evaluates trade-offs, recommends patterns, designs for the long term. Use for decisions that are hard to reverse.
 
-| Agent | Language / Domain |
-|-------|------------------|
-| `code-reviewer` | General — quality, patterns, best practices |
-| `typescript-reviewer` | TypeScript + JavaScript |
-| `python-reviewer` | Python — PEP 8, type hints, security |
-| `go-reviewer` | Go — idiomatic patterns, concurrency |
-| `rust-reviewer` | Rust — ownership, lifetimes, unsafe |
-| `java-reviewer` | Java + Spring Boot |
-| `kotlin-reviewer` | Kotlin + Android + KMP |
-| `cpp-reviewer` | C++ — memory safety, modern idioms |
-| `csharp-reviewer` | C# + .NET — async, nullable, security |
-| `flutter-reviewer` | Flutter + Dart — widget best practices |
+**When to use:** Architectural decisions, service boundaries, data modeling, scaling decisions.
 
 ---
 
-## Build Fixers (8 agents)
+## Testing Agents
 
-| Agent | Platform |
-|-------|---------|
-| `build-error-resolver` | TypeScript / general |
-| `go-build-resolver` | Go |
-| `rust-build-resolver` | Rust + Cargo |
-| `java-build-resolver` | Java + Maven + Gradle |
-| `kotlin-build-resolver` | Kotlin + Gradle |
-| `cpp-build-resolver` | C++ + CMake |
-| `dart-build-resolver` | Dart + Flutter |
-| `pytorch-build-resolver` | PyTorch + CUDA |
+### `tdd-guide`
+
+Test-Driven Development specialist. Enforces RED → GREEN → REFACTOR → VERIFY (80%+). Writes tests first. Never skips the failing-test step.
+
+**When to use:** New features, bug fixes, refactoring — whenever tests are involved.
+
+**Triggers:** "test", "coverage", "TDD", "write tests", "testing"
+
+### `e2e-runner`
+
+End-to-end testing with Playwright (preferred) or fallback. Generates, maintains, and runs E2E tests. Manages test journeys, quarantines flaky tests, uploads artifacts.
+
+**When to use:** Critical user flow testing, E2E suite setup or maintenance.
+
+### `flake-hunter`
+
+Flaky test stabilization. 6-class taxonomy: async timing, test isolation, environment dependency, external dependency, non-determinism, race conditions. Real fixes — never adds blind retries.
+
+**When to use:** Tests that fail intermittently, inconsistently, or "sometimes".
+
+**Triggers:** "flaky", "intermittent", "sometimes fails", "flakey", "unstable test"
+
+### `pr-test-analyzer`
+
+Reviews pull request test coverage quality. Checks behavioral coverage and real bug prevention, not just line count.
+
+**When to use:** Before merging PRs, when reviewing test suites.
 
 ---
 
-## Planning & Architecture (6 agents)
+## Build Error Agents
+
+### `build-error-resolver`
+
+TypeScript and JavaScript build error specialist. Fixes build failures with minimal diffs. Focuses on getting green quickly without architectural changes.
+
+**When to use:** Build failures, TypeScript errors, compilation errors in JS/TS.
+
+**Triggers:** "build failed", "TypeScript error", "compilation error", "tsc error"
+
+### `cpp-build-resolver`
+C++ build, CMake, linker, and template error specialist.
 
-| Agent | Purpose |
-|-------|---------|
-| `planner` | Feature implementation plans |
-| `architect` | System design, scalability decisions |
-| `code-architect` | Blueprints from existing codebase patterns |
-| `code-explorer` | Deep codebase analysis and dependency mapping |
-| `chief-of-staff` | Communication triage — email, Slack, LINE |
-| `pair-programmer` | Pre-code thinking partner |
+### `dart-build-resolver`
+Dart/Flutter build, `dart analyze` errors, pub dependency conflicts.
+
+### `go-build-resolver`
+Go build, vet, and linter failures.
+
+### `java-build-resolver`
+Java/Maven/Gradle build, compiler errors, dependency issues.
+
+### `kotlin-build-resolver`
+Kotlin/Gradle build and compiler errors.
+
+### `python-build-resolver` *(via build-error-resolver)*
+Handles Python import errors, syntax issues, pip conflicts.
+
+### `rust-build-resolver`
+Cargo build, borrow checker, and Cargo.toml failures.
+
+### `pytorch-build-resolver`
+PyTorch runtime, CUDA, tensor shape, and training errors.
 
 ---
 
-## Security (3 agents)
+## Infrastructure Agents
+
+### `git-rescue`
+
+Recovers broken git states: lost commits, bad rebases, accidental force-pushes, detached HEAD, corrupted history. Uses reflog, dangling commits, and surgical resets. Never destroys history.
+
+**When to use:** Any git state that feels unrecoverable.
+
+**Triggers:** "lost commit", "wrong branch", "rebase went wrong", "force push", "git mess"
+
+### `release-captain`
+
+Owns the full release ritual: semantic versioning decision, changelog generation, git tagging, npm/pypi/crates publish, rollback rehearsal. Covers hotfix, regular, and major release paths.
+
+**When to use:** Cutting any release.
+
+**Triggers:** "release", "publish", "tag", "semver", "version bump", "changelog"
+
+### `env-debugger`
+
+"Works on my machine" hunter. Traces environment variable mismatches, config layer conflicts, secrets misconfiguration, build-time vs runtime differences, Docker vs local discrepancies.
+
+**When to use:** Code that works locally but fails in staging, CI, or production.
 
-| Agent | Purpose |
-|-------|---------|
-| `security-reviewer` | OWASP Top 10, secrets, injection, SSRF |
-| `healthcare-reviewer` | HIPAA, PHI, clinical safety |
-| `api-guardian` | Breaking changes, versioning, contracts |
+**Triggers:** "works locally", "only in production", "environment variable", "docker"
+
+### `dependency-doctor`
+
+Dependency hell specialist for npm, pip, cargo, maven. CVE triage, lockfile diagnosis, safe upgrade plans, peer dependency conflicts, phantom dependency bugs.
+
+**When to use:** Dependency install failures, version conflicts, CVE alerts.
+
+**Triggers:** "dependency conflict", "CVE", "lockfile", "npm error", "peer dep", "pip install"
+
+### `database-reviewer`
+
+PostgreSQL specialist for query optimization, schema design, security, and performance. Incorporates Supabase best practices. Catches N+1 queries, missing indexes, unbounded queries.
+
+**When to use:** SQL queries, schema migrations, database performance issues.
 
 ---
 
-## Quality & Performance (5 agents)
+## Specialized Agents
+
+### `api-guardian`
+
+API contract protection. Classifies every change as BREAKING / SAFE / WARN. Consumer impact report with migration paths. Covers REST, GraphQL, gRPC, WebSocket.
+
+**When to use:** Any change to a public or internal API surface.
+
+**Triggers:** "API change", "breaking change", "endpoint", "contract", "versioning"
+
+### `migration-guide`
+
+Full migration playbooks for React 17/18→19, Next.js 12/13→15, Python 2→3, Node.js 14→22, TypeScript 4→5, Java 8→21. Phase 0 audit through Phase 4 validation. Incremental strategy — never "stop the world".
+
+**When to use:** Framework upgrades, language migrations, major dependency updates.
+
+**Triggers:** "upgrade", "migrate", "React 19", "Next.js", "Python 3", "Node upgrade"
+
+### `performance-optimizer`
+
+Performance analysis and optimization. Profiling, memory leak detection, render optimization, algorithmic improvements, bundle size reduction, query optimization.
+
+**When to use:** Slow code, high memory usage, poor Core Web Vitals, slow queries.
 
-| Agent | Purpose |
-|-------|---------|
-| `refactor-cleaner` | Dead code removal, knip, depcheck |
-| `code-simplifier` | Clarity and consistency |
-| `performance-optimizer` | Bottlenecks, bundle size, render perf |
-| `type-design-analyzer` | Type safety and invariant design |
-| `silent-failure-hunter` | Swallowed errors, bad fallbacks |
+**Triggers:** "slow", "performance", "memory leak", "bundle size", "optimize"
+
+### `refactor-cleaner`
+
+Dead code cleanup and consolidation. Runs knip, depcheck, ts-prune to identify unused exports, dependencies, and types. Safely removes dead code.
+
+**When to use:** Codebase cleanup, reducing bundle size, before major refactors.
+
+### `doc-updater`
+
+Documentation and codemap specialist. Updates `docs/CODEMAPS/`, READMEs, and guides after code changes.
+
+**When to use:** After significant code changes that need documentation updates.
+
+### `comment-analyzer`
+
+Analyzes code comments for accuracy, completeness, maintainability, and comment rot risk. Flags comments that lie about what the code does.
 
 ---
 
-## Testing (3 agents)
+## Open Source Pipeline Agents
+
+Three-stage pipeline for open-sourcing internal projects:
 
-| Agent | Purpose |
-|-------|---------|
-| `tdd-guide` | Write tests first, 80%+ coverage |
-| `e2e-runner` | E2E tests with Playwright |
-| `pr-test-analyzer` | PR test coverage review |
+### `opensource-forker`
+Stage 1: Copies files, strips secrets (20+ patterns), replaces internal references with placeholders, generates `.env.example`, cleans git history.
+
+### `opensource-sanitizer`
+Stage 2: Verifies the fork is fully sanitized. Scans for leaked secrets, PII, internal references. Generates PASS/FAIL/PASS-WITH-WARNINGS report.
+
+### `opensource-packager`
+Stage 3: Generates complete OSS packaging: `CLAUDE.md`, `setup.sh`, `README.md`, `LICENSE`, `CONTRIBUTING.md`, GitHub issue templates.
 
 ---
 
-## Documentation (3 agents)
+## Analysis Agents
+
+### `code-explorer`
+Deeply analyzes existing codebase features by tracing execution paths, mapping architecture layers, and documenting dependencies.
+
+### `code-architect`
+Designs feature architectures by analyzing existing codebase patterns and conventions. Provides implementation blueprints with files, interfaces, data flow, and build order.
 
-| Agent | Purpose |
-|-------|---------|
-| `doc-updater` | CODEMAPS, READMEs, guides |
-| `docs-lookup` | Context7 — library docs and API examples |
-| `comment-analyzer` | Comment accuracy and rot detection |
+### `code-simplifier`
+Simplifies and refines code for clarity, consistency, and maintainability. Focus on recently modified code unless instructed otherwise.
+
+### `type-design-analyzer`
+Analyzes type design for encapsulation, invariant expression, usefulness, and enforcement.
+
+### `seo-specialist`
+Technical SEO audits, on-page optimization, structured data, Core Web Vitals, sitemap and robots issues.
 
 ---
 
-## Open Source (3 agents)
+## Healthcare Agent
 
-| Agent | Purpose |
-|-------|---------|
-| `opensource-forker` | Fork and strip secrets for public release |
-| `opensource-sanitizer` | Verify fork is clean before release |
-| `opensource-packager` | CLAUDE.md, setup.sh, README, LICENSE, templates |
+### `healthcare-reviewer`
+Reviews healthcare application code for clinical safety, CDSS accuracy, PHI compliance, and medical data integrity. Specialized for EMR/EHR and clinical decision support.
 
 ---
 
-## Specialized (6 agents)
+## Meta Agents
+
+### `harness-optimizer`
+Analyzes and improves the local agent harness configuration for reliability, cost, and throughput.
+
+### `loop-operator`
+Operates autonomous agent loops, monitors progress, and intervenes safely when loops stall.
 
-| Agent | Purpose |
-|-------|---------|
-| `debug-detective` | Root cause hunting |
-| `ux-reviewer` | UX + accessibility |
-| `seo-specialist` | Technical SEO, Core Web Vitals, schema |
-| `database-reviewer` | PostgreSQL — queries, schema, Supabase |
-| `comment-analyzer` | Comment accuracy |
-| `kodelyth-advisor` | Master guide |
+### `kodelyth-advisor`
+*(see Kodelyth Exclusive above)*
 
 ---
 
-## GAN Harness (3 agents)
+## Full Agent Count
 
-| Agent | Purpose |
-|-------|---------|
-| `gan-planner` | Expand a prompt into a full product spec |
-| `gan-generator` | Implement features, iterate on feedback |
-| `gan-evaluator` | Test the live app via Playwright, score against rubric |
+59 agents across all categories. Use `kodelyth-advisor` if you're unsure which one to reach for — it knows the full roster and will point you in the right direction.