kodelyth-ecc 1.2.1 → 1.3.0

package/AGENTS.md

@@ -1,209 +1,129 @@
-# Kodelyth ECC — Agent Instructions
+# AGENTS.md
 
-A **production-grade AI coding plugin** — 50 specialized agents, 183 skills, 79 commands, and automated hook workflows. Enhanced and maintained by **Kodelyth**.
-
-**Version:** 1.1.0
+This file is read by AI agents (Cascade, Cursor, Codex, etc.) on every session. It tells them how to work in this repo and how to use the 58 specialist agents and 187 skills shipped with Kodelyth ECC.
 
 ---
 
-## Core Principles
+## Repo Identity
+
+**Kodelyth ECC** — a production-grade AI coding toolkit installed into your `~/.claude/`, `.windsurf/`, `.cursor/`, `~/.codex/`, `.agent/`, or `.opencode/` directory by `npx kodelyth-ecc`.
 
-1. **Agent-First** — Route work to the right specialist immediately
-2. **Test-Driven** — Write tests before implementation, 80%+ coverage required
-3. **Security-First** — Never compromise on security; validate all inputs
-4. **Immutability** — Always create new objects, never mutate existing ones
-5. **Plan Before Execute** — Plan complex features before writing code
-6. **Friendly by Default** — Guide clearly, respond to the person not just the problem
-7. **Debug to Root Cause** — Never guess at fixes; trace errors systematically
-8. **SVG Over Emoji** — Never use decorative emoji in responses or docs; use SVG badges and icons in rendered Markdown, plain Unicode symbols (✓ ✗) in terminal output only
-9. **Budget-First** — Default to the lightest model that solves the problem. Never escalate model tier or spawn additional agents unless the lighter option demonstrably fails. Every token costs money.
+This repo is the **source of truth** that ships those files. When working in this repo, you are editing the toolkit itself.
 
 ---
 
-## Kodelyth Exclusive Agents
+## How to Use the Toolkit (For End Users)
+
+The toolkit has two activation paths:
+
+### 1. Explicit invocation
+
+```
+use kodelyth-advisor
+@debug-detective
+invoke security-reviewer
+```
+
+### 2. Implicit (intent routing)
+
+The user describes their problem in plain language. You — the AI — read it, identify the right specialist, **announce the routing**, and **behave as that agent**.
+
+The full intent → agent mapping lives in `rules/common/agent-intent-routing.md` and is loaded automatically on every session. Memorize the priority tiers:
+
+| Tier | Theme |
+|---|---|
+| 1 | Crisis / emotional state (`kodelyth-advisor`, `pair-programmer`) |
+| 2 | Active pain — broken (`debug-detective`, `build-error-resolver`, `env-debugger`, `silent-failure-hunter`) |
+| 3 | Quality & review (`code-reviewer`, `security-reviewer`, `ux-reviewer`, `api-guardian`) |
+| 4 | Performance (`performance-optimizer`) |
+| 5 | Planning / architecture (`planner`, `architect`, `code-architect`, `migration-guide`) |
+| 6 | Testing (`tdd-guide`, `e2e-runner`, `pr-test-analyzer`, `flake-hunter`) |
+| 7 | Code hygiene (`refactor-cleaner`, `code-simplifier`, `type-design-analyzer`) |
+| 8 | Documentation (`doc-updater`, `docs-lookup`, `comment-analyzer`) |
+| 9 | Specialized (`seo-specialist`, `opensource-*`, `dependency-doctor`, `git-rescue`, `release-captain`) |
+| 10 | Multi-agent handoffs |
+
+### Routing format (mandatory)
+
+```
+→ Routing to <agent-name> (<one-line reason>)
+
+[response in that agent's persona]
+
+Tip: next time you can type "use <agent-name>" to invoke me directly.
+```
 
-| Agent | Purpose | When to Use |
-|---|---|---|
-| kodelyth-advisor | Master guide — picks the right tool for your situation | Not sure where to start |
-| debug-detective | Root cause analyst — never guesses, always traces | Bug that resists fixing |
-| ux-reviewer | UX + WCAG 2.1 AA reviewer — never touches design | After building any frontend |
-| api-guardian | API contract protector — catches breaking changes | Before any PR touching API routes |
-| pair-programmer | Live thinking partner — catches wrong approach before coding | Before implementing anything non-trivial |
-| migration-guide | Framework/language migration specialist | Upgrading any major dependency |
+Never silently switch personas. Always teach the user the explicit form.
 
 ---
 
-## All Available Agents
-
-### Guidance & Planning
-| Agent | Purpose | When to Use |
-|---|---|---|
-| kodelyth-advisor | Master engineering advisor | Any time you need direction |
-| planner | Implementation planning | Complex features, refactoring |
-| architect | System design and scalability | Architectural decisions |
-| code-architect | Feature architecture blueprints | New feature design |
-| chief-of-staff | Communication and workflow | Email, Slack, multi-channel ops |
-
-### Code Review
-| Agent | Purpose | When to Use |
-|---|---|---|
-| code-reviewer | General code quality | After writing or modifying code |
-| typescript-reviewer | TypeScript/JavaScript review | TS/JS projects |
-| python-reviewer | Python review | Python projects |
-| go-reviewer | Go review | Go projects |
-| rust-reviewer | Rust review | Rust projects |
-| java-reviewer | Java/Spring Boot review | Java projects |
-| kotlin-reviewer | Kotlin/Android/KMP review | Kotlin projects |
-| cpp-reviewer | C++ review | C++ projects |
-| csharp-reviewer | C#/.NET review | C# projects |
-| flutter-reviewer | Flutter/Dart review | Flutter projects |
-| database-reviewer | PostgreSQL/Supabase review | Schema and query design |
-| healthcare-reviewer | Clinical safety and PHI | Healthcare applications |
-
-### Build Error Resolution
-| Agent | Purpose | When to Use |
-|---|---|---|
-| build-error-resolver | General build errors | When build fails |
-| go-build-resolver | Go build errors | Go build failures |
-| rust-build-resolver | Rust/Cargo errors | Rust build failures |
-| java-build-resolver | Java/Maven/Gradle errors | Java build failures |
-| kotlin-build-resolver | Kotlin/Gradle errors | Kotlin build failures |
-| cpp-build-resolver | C++/CMake errors | C++ build failures |
-| dart-build-resolver | Dart/Flutter errors | Dart/Flutter failures |
-| pytorch-build-resolver | PyTorch/CUDA errors | ML training crashes |
-
-### Debugging
-| Agent | Purpose | When to Use |
-|---|---|---|
-| debug-detective | Root cause analysis | Any hard-to-find bug |
-| silent-failure-hunter | Find swallowed errors | Silent bugs, bad fallbacks |
-
-### Security
-| Agent | Purpose | When to Use |
-|---|---|---|
-| security-reviewer | Vulnerability detection | Before commits, sensitive code |
-
-### UX & Design
-| Agent | Purpose | When to Use |
-|---|---|---|
-| ux-reviewer | UX and accessibility review | After building any UI |
-
-### Code Quality
-| Agent | Purpose | When to Use |
-|---|---|---|
-| refactor-cleaner | Dead code cleanup | Code maintenance |
-| code-simplifier | Simplify for clarity | After complex changes |
-| performance-optimizer | Bottleneck analysis | When something is slow |
-| type-design-analyzer | Type design review | Type safety improvements |
-| comment-analyzer | Comment quality review | Documentation hygiene |
-| code-explorer | Codebase exploration | Understanding unfamiliar code |
-
-### Testing
-| Agent | Purpose | When to Use |
-|---|---|---|
-| tdd-guide | Test-driven development | New features, bug fixes |
-| e2e-runner | End-to-end Playwright tests | Critical user flows |
-| pr-test-analyzer | PR test coverage review | Before merging PRs |
-
-### Documentation
-| Agent | Purpose | When to Use |
-|---|---|---|
-| doc-updater | Documentation updates | Updating READMEs, codemaps |
-| docs-lookup | API docs via Context7 | Library/API questions |
-| seo-specialist | SEO audit and optimization | Web content and metadata |
-
-### Open Source
-| Agent | Purpose | When to Use |
-|---|---|---|
-| opensource-forker | Fork for open-sourcing | Strip secrets, clean history |
-| opensource-packager | Package for public release | README, setup, license |
-| opensource-sanitizer | Verify sanitization | Before public release |
-
-### Advanced Orchestration
-| Agent | Purpose | When to Use |
-|---|---|---|
-| loop-operator | Manage autonomous agent loops | Long-running agent tasks |
-| harness-optimizer | Tune harness config | Reliability and cost |
-| conversation-analyzer | Analyze transcripts for hooks | Hook configuration |
-| gan-planner | GAN spec expansion | GAN harness workflows |
-| gan-generator | GAN feature implementation | GAN harness workflows |
-| gan-evaluator | GAN evaluation via Playwright | GAN harness workflows |
+## Multi-Agent Chains
+
+Standard chains documented in `skills/agent-handoff/SKILL.md`:
+
+| Workflow | Chain |
+|---|---|
+| New feature | `pair-programmer` → `tdd-guide` → impl → `code-reviewer` → `security-reviewer` (if sensitive) |
+| Bug fix | `debug-detective` → `tdd-guide` (regression test) → `refactor-cleaner` (optional) |
+| Refactor | `code-explorer` → `refactor-cleaner` → `tdd-guide` → `code-reviewer` |
+| API change | `api-guardian` → `pair-programmer` → `tdd-guide` → `doc-updater` |
+| Migration | `migration-guide` → `pair-programmer` (per phase) → `pr-test-analyzer` |
+| Build broken | `build-error-resolver` → `dependency-doctor` (if dep) or `env-debugger` (if env) |
+| Flaky CI | `flake-hunter` → `tdd-guide` → `release-captain` (if it gates a release) |
+| Open-source | `opensource-forker` → `opensource-sanitizer` → `opensource-packager` → `release-captain` |
+| Git crisis | `git-rescue` → `release-captain` (if a release was midway) |
 
 ---
 
-## Key Skills (load with /skill-name)
-
-### Kodelyth Skills
-- `/kodelyth-quickstart` — Plain-language getting-started guide (**read this first**)
-- `/smart-debug` — 5-step systematic debugging framework
-
-### Language Patterns
-- `/typescript-patterns` — TypeScript + React + Next.js
-- `/python-patterns` — Python best practices
-- `/golang-patterns` — Go best practices
-- `/rust-patterns` — Rust best practices
-- `/kotlin-patterns` — Kotlin/Android patterns
-- `/springboot-patterns` — Java Spring Boot
-
-### Architecture & Backend
-- `/backend-patterns` — Service and repository layers
-- `/api-design` — REST API conventions
-- `/hexagonal-architecture` — Ports and adapters
-- `/postgres-patterns` — Database design and queries
-- `/docker-patterns` — Container patterns
-- `/deployment-patterns` — CI/CD and deployment
-
-### Testing
-- `/tdd-workflow` — TDD step by step
-- `/python-testing` — Python test patterns
-- `/golang-testing` — Go test patterns
-- `/e2e-testing` — End-to-end test patterns
-
-### Security
-- `/security-review` — Security audit guide
-- `/security-scan` — AgentShield vulnerability scan
-
-### Frontend
-- `/frontend-patterns` — React component patterns
-- `/nextjs-turbopack` — Next.js App Router patterns
-- `/coding-standards` — Universal baseline
+## When Working IN This Repo (Toolkit Development)
+
+When the user is editing this repo (the toolkit source itself):
+
+1. **Adding a new agent** — create `agents/<name>.md` AND update `rules/common/agent-intent-routing.md` with trigger patterns. Also update `README.md` agent count and category table.
+2. **Adding a new skill** — create `skills/<name>/SKILL.md`. If it's a routing/handoff/meta skill, link it from `skills/intent-routing/SKILL.md` or `skills/agent-handoff/SKILL.md`.
+3. **Changing install behavior** — update BOTH `install.sh` (mac/linux) AND `install.ps1` (Windows). Verify with `npm test`.
+4. **Bumping versions** — update BOTH `package.json` AND `VERSION`. Update `CHANGELOG.md`. Tag with `vX.Y.Z`.
+5. **Cross-platform changes** — test `node bin/kodelyth-ecc.js --help` and the install scripts on at least one platform.
 
 ---
 
-## Key Commands (/command)
+## Code Style for This Repo
 
-| Command | What it does |
-|---|---|
-| `/kodelyth-quickstart` | Getting started guide |
-| `/smart-debug` | Load debugging framework |
-| `/tdd` | Test-driven development workflow |
-| `/plan` | Implementation planning |
-| `/code-review` | Quality review |
-| `/build-fix` | Fix build errors |
-| `/e2e` | Generate and run E2E tests |
-| `/learn` | Extract patterns from session |
-| `/security-scan` | Run AgentShield security scan |
+- **Markdown** — sentence case, fenced code blocks with language tag, no emojis unless in social SVGs
+- **Bash** — POSIX-compatible where possible; macOS bash 3.2 is the floor
+- **PowerShell** — match feature parity with `install.sh`
+- **Node** — ES modules, Node 18+, no external runtime deps in `bin/` (use built-ins only)
 
 ---
 
-## Hooks (automatic — no action needed)
+## Tests
 
-| Hook | What it does |
-|---|---|
-| Session start | Loads previous context |
-| Pre-commit | Catches console.log, secrets, bad commit messages |
-| Quality gate | Runs type checks + formatting after edits |
-| Config protection | Blocks weakening linter/formatter configs |
-| Git push reminder | Prompts review before push |
-| MCP health check | Validates MCP servers before calling |
-| Cost tracker | Logs token usage per session |
-| Desktop notify | macOS notification on task complete |
+Run before any commit:
+
+```bash
+npm test
+```
+
+There are 38 tests covering hooks logic, file detection, and intent matching. Never weaken or skip tests; if behavior must change, update the test first.
 
 ---
 
-## Credits
+## What This Repo Does NOT Have
+
+- ❌ Cloud telemetry, analytics, dashboards (Lens was removed in v1.3.0 — it gave inaccurate cross-platform data)
+- ❌ Background daemons or auto-running servers
+- ❌ Required external services or accounts
+
+This is markdown + shell + a thin Node wrapper. Keep it that way.
+
+---
 
-Built on [Kodelyth ECC](https://github.com/sifxprime/kodelyth-ecc) by [@sifxprime](https://github.com/sifxprime).
-Enhanced by **Kodelyth** — v1.0.0.
+## Useful Slash Commands When Editing This Repo
 
-> Powered by Kodelyth
+```
+/kodelyth-quickstart    Read first if new
+/intent-routing         Understand the routing rule
+/agent-handoff          Understand chain protocol
+/skill-create           Generate a new skill
+/code-review            Review your changes before commit
+```

package/CHANGELOG.md

@@ -2,6 +2,38 @@
 
 All notable changes to Kodelyth ECC are documented here.
 
+## v1.3.0 — God-Tier Intent Routing + 5 New Agents (May 2026)
+
+### Removed
+- **Kodelyth Lens dashboard** — bundled local dashboard removed. Cloud-AI platforms (Windsurf, Antigravity, parts of Cursor) don't expose token/cost data locally, which led to inaccurate or hardcoded zeros. The toolkit is now leaner and only does what it can do honestly.
+- `dashboard/` folder, `scripts/agent-tracker-hook.js`, Lens auto-start logic in `install.sh`, Lens social SVGs
+
+### Added — God-Tier Intent Routing Rule
+- New `rules/common/agent-intent-routing.md` — auto-loaded on every session
+- 10 priority tiers (crisis → multi-agent chains)
+- 50+ trigger pattern groups across emotional state, error keywords, language hints, framework signals
+- Mandatory routing format: `→ Routing to <agent>` + persona switch + explicit-form teaching
+- Counter-patterns (when NOT to route) baked in
+- Documents standard chains for new feature, bug fix, refactor, migration, OSS prep, git crisis
+
+### Added — 5 New Specialist Agents
+- `dependency-doctor` — npm/pip/cargo/maven dep hell, CVE triage, lockfile diagnosis, safe upgrade plans
+- `git-rescue` — recovers broken git states (lost commits, bad rebases, force-pushes) without destroying history
+- `release-captain` — owns the release ritual (semver, changelog, tagging, publishing, rollback rehearsal)
+- `env-debugger` — "works on my machine" hunter (env vars, config layers, secrets, build-time vs runtime)
+- `flake-hunter` — flaky test stabilization with 6-class taxonomy and real fixes (never adds blind retries)
+
+### Added — 2 New Meta Skills
+- `skills/intent-routing/SKILL.md` — documents the routing system, priority tiers, trigger design rules
+- `skills/agent-handoff/SKILL.md` — standard multi-agent chain protocol with 10 documented chains
+
+### Updated
+- `README.md` — full rewrite emphasizing intent routing as the differentiator
+- `KODELYTH.md` — reflects v1.3.0 changes
+- `CLAUDE.md`, `AGENTS.md` — updated agent counts, intent routing guidance
+- `install.sh` — removed all Lens install/auto-start blocks
+- Counts: 58 agents (was 53), 187 skills (was 185), 79 commands, 15 rules (was 14)
+
 ## v1.2.0 — Lens Dashboard + Windsurf + npx (May 2026)
 
 ### Kodelyth Lens — AI Usage Dashboard

package/CLAUDE.md

@@ -1,90 +1,99 @@
 # CLAUDE.md
 
-This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+Guidance for Claude Code when working with this repository.
 
 ## Project Overview
 
-This is a **Claude Code plugin** - a collection of production-ready agents, skills, hooks, commands, rules, and MCP configurations. The project provides battle-tested workflows for software development using Claude Code.
+**Kodelyth ECC** — a production-grade AI coding toolkit:
 
-## Running Tests
-
-```bash
-# Run all tests
-node tests/run-all.js
+- **58 specialist agents** — debug-detective, code-reviewer, security-reviewer, etc.
+- **187 skills** — domain knowledge, patterns, testing, security, intent routing
+- **79 commands** — slash workflows (`/tdd`, `/plan`, `/code-review`, ...)
+- **15+ hooks** — automated quality gates and session memory
+- **15 rules** — always-on coding standards + the **god-tier intent routing rule**
 
-# Run individual test files
-node tests/lib/utils.test.js
-node tests/lib/package-manager.test.js
-node tests/hooks/hooks.test.js
-```
+Works with Claude Code, Windsurf, Cursor, Codex CLI, Antigravity, and OpenCode.
 
 ## Architecture
 
-The project is organized into several core components:
+```
+agents/      → Specialist subagents (planner, code-reviewer, debug-detective, ...)
+skills/      → Workflow + domain knowledge files (loadable via slash commands)
+commands/    → Slash commands users invoke directly
+hooks/       → Trigger-based automations (pre-commit, session memory, etc.)
+rules/       → Always-on guidelines including agent-intent-routing.md
+scripts/     → Cross-platform Node.js utilities for hooks and setup
+tests/       → Test suite for scripts and hooks
+```
+
+## Running Tests
 
-- **agents/** - Specialized subagents for delegation (planner, code-reviewer, tdd-guide, etc.)
-- **skills/** - Workflow definitions and domain knowledge (coding standards, patterns, testing)
-- **commands/** - Slash commands invoked by users (/tdd, /plan, /e2e, etc.)
-- **hooks/** - Trigger-based automations (session persistence, pre/post-tool hooks)
-- **rules/** - Always-follow guidelines (security, coding style, testing requirements)
-- **mcp-configs/** - MCP server configurations for external integrations
-- **scripts/** - Cross-platform Node.js utilities for hooks and setup
-- **tests/** - Test suite for scripts and utilities
+```bash
+npm test
+# or directly
+node tests/run-all.js
+```
 
-## Key Commands
+## Intent Routing (v1.3.0+)
 
-- `/tdd` - Test-driven development workflow
-- `/plan` - Implementation planning
-- `/e2e` - Generate and run E2E tests
-- `/code-review` - Quality review
-- `/build-fix` - Fix build errors
-- `/learn` - Extract patterns from sessions
-- `/skill-create` - Generate skills from git history
-- `/kodelyth-quickstart` - Friendly plain-language getting-started guide (Kodelyth)
-- `/smart-debug` - Systematic debugging methodology (Kodelyth)
+The toolkit ships with a god-tier intent routing rule (`rules/common/agent-intent-routing.md`) that auto-loads on every session. It maps user intent → specialist agent across 10 priority tiers.
 
-## Kodelyth Additions
+When a user message matches a routing pattern, you MUST:
 
-This is the **Kodelyth Enhanced Edition**. The following agents and skills were added:
+1. Acknowledge with `→ Routing to <agent>` (one line)
+2. Behave as that agent for the response
+3. Suggest the explicit form: `Tip: type "use <agent>"`
+4. Never silently route — transparency is mandatory
 
-| Type | Name | Purpose |
-|---|---|---|
-| Agent | `kodelyth-advisor` | Guides users to the right agent/skill for their task |
-| Agent | `debug-detective` | Traces bugs to root cause systematically, never guesses |
-| Agent | `ux-reviewer` | Reviews frontend for UX quality and WCAG 2.1 accessibility |
-| Skill | `kodelyth-quickstart` | Plain-language intro for new users |
-| Skill | `smart-debug` | Structured 5-step debugging framework |
+## Key Commands
 
-See [KODELYTH.md](KODELYTH.md) for full details.
+- `/kodelyth-quickstart` — friendly onboarding guide
+- `/smart-debug` — systematic debugging
+- `/tdd` — test-driven development workflow
+- `/plan` — implementation planning
+- `/code-review` — quality review
+- `/git-mastery` — git workflows + recovery patterns
+- `/observability` — logging, metrics, OpenTelemetry, SLOs
+
+## Specialist Agents (Pick the Right One)
+
+| Use case | Agent |
+|---|---|
+| Lost / overwhelmed | `kodelyth-advisor` |
+| Pre-implementation thinking | `pair-programmer` |
+| Bug with error or stack trace | `debug-detective` |
+| Bug with no error (silent fail) | `silent-failure-hunter` |
+| Build / compile / type errors | `build-error-resolver` (or language-specific build resolver) |
+| Slow code | `performance-optimizer` |
+| Security review | `security-reviewer` |
+| API contract check | `api-guardian` |
+| Frontend / a11y | `ux-reviewer` |
+| Framework upgrade | `migration-guide` |
+| npm/pip/cargo dep hell | `dependency-doctor` |
+| Broken git state | `git-rescue` |
+| Cut a release | `release-captain` |
+| "Works on my machine" | `env-debugger` |
+| Flaky tests | `flake-hunter` |
+| Tests / coverage | `tdd-guide` |
+| Refactor / cleanup | `refactor-cleaner` |
+| Open-source a project | `opensource-forker` (chain start) |
 
 ## Development Notes
 
-- Package manager detection: npm, pnpm, yarn, bun (configurable via `CLAUDE_PACKAGE_MANAGER` env var or project config)
-- Cross-platform: Windows, macOS, Linux support via Node.js scripts
-- Agent format: Markdown with YAML frontmatter (name, description, tools, model)
-- Skill format: Markdown with clear sections for when to use, how it works, examples
-- Skill placement: Curated in skills/; generated/imported under ~/.claude/skills/. See docs/SKILL-PLACEMENT-POLICY.md
+- Package manager detection: npm, pnpm, yarn, bun
+- Cross-platform: Windows (`install.ps1`), macOS / Linux (`install.sh`), or `npx` anywhere
+- Agent format: Markdown with YAML frontmatter (name, description, tools)
+- Skill format: Markdown with clear sections (description, when to use, how it works)
 - Hook format: JSON with matcher conditions and command/notification hooks
 
 ## Contributing
 
-Follow the formats in CONTRIBUTING.md:
-- Agents: Markdown with frontmatter (name, description, tools, model)
-- Skills: Clear sections (When to Use, How It Works, Examples)
-- Commands: Markdown with description frontmatter
-- Hooks: JSON with matcher and hooks array
-
-File naming: lowercase with hyphens (e.g., `python-reviewer.md`, `tdd-workflow.md`)
-
-## Skills
+When adding a new agent:
 
-Use the following skills when working on related files:
+1. Create `agents/<name>.md` with YAML frontmatter
+2. Add trigger patterns to `rules/common/agent-intent-routing.md` (so the router knows when to call you)
+3. If part of a chain, document the handoff in `skills/agent-handoff/SKILL.md`
 
-| File(s) | Skill |
-|---------|-------|
-| `README.md` | `/readme` |
-| `.github/workflows/*.yml` | `/ci-workflow` |
-| New users / onboarding | `/kodelyth-quickstart` |
-| Any debugging session | `/smart-debug` |
+See [CONTRIBUTING.md](CONTRIBUTING.md) for full templates.
 
-When spawning subagents, always pass conventions from the respective skill into the agent's prompt.
+File naming: lowercase with hyphens (e.g., `dependency-doctor.md`, `flake-hunter.md`).