kodelyth-ecc 1.2.0

package/AGENTS.md

@@ -0,0 +1,209 @@
+# Kodelyth ECC — Agent Instructions
+
+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
+
+---
+
+## Core Principles
+
+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.
+
+---
+
+## Kodelyth Exclusive Agents
+
+| 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 |
+
+---
+
+## 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 |
+
+---
+
+## 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
+
+---
+
+## Key Commands (/command)
+
+| 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 |
+
+---
+
+## Hooks (automatic — no action needed)
+
+| 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 |
+
+---
+
+## Credits
+
+Built on [Kodelyth ECC](https://github.com/sifxprime/kodelyth-ecc) by [@sifxprime](https://github.com/sifxprime).
+Enhanced by **Kodelyth** — v1.0.0.
+
+> Powered by Kodelyth

package/CHANGELOG.md

@@ -0,0 +1,236 @@
+# Changelog
+
+All notable changes to Kodelyth ECC are documented here.
+
+## v1.2.0 — Lens Dashboard + Windsurf + npx (May 2026)
+
+### Kodelyth Lens — AI Usage Dashboard
+- Zero-dependency real-time dashboard tracking 6 platforms: Claude Code, Cursor, Windsurf, Codex CLI, OpenCode, Antigravity
+- Agent leaderboard — ranked by usage with intent detection across 12 categories, 50+ patterns
+- ECC savings banner — shows actual cost vs. estimated without-ECC, cache hit rate, % reduction
+- 30-day cost chart, today vs. all-time stats, session table
+- Light theme, sticky header, auto-refresh every 60 seconds
+- Only shows installed platforms — non-installed platforms hidden
+- Dynamic subtitle lists detected platform names after first load
+
+### Platform Readers
+- **Claude Code reader** — full JSONL session parsing, lastDate field for today filter, hook tracking merge
+- **Codex CLI reader** — SQLite via `sqlite3 -json` mode, COALESCE for optional columns, lastDate field
+- **Windsurf reader** — workspaceStorage + Cascade files, lastDate field, sort comparator fixed
+- **Cursor reader** — workspaceStorage + chat files, lastDate field, sort comparator fixed
+- **OpenCode reader** — JSONL/JSON session files, lastDate field, tokens.total fixed (was including cacheRead)
+- **Antigravity reader** — ECC project detection, cross-platform path resolution (macOS/Windows/Linux)
+
+### Install Improvements
+- `npx github:sifxprime/kodelyth-ecc` — install from any machine with Node.js 18+
+- `--target windsurf-project` — installs to `.windsurf/` + generates `.windsurfrules` auto-loaded by Cascade
+- `--target windsurf-home` — installs to `~/.codeium/windsurf/` globally
+- Non-interactive install — auto-accepts in CI/Docker environments without `/dev/tty`
+- `go` argument normalized to `golang` (rules dir is `rules/golang/`)
+- Agent/skill counts corrected to 53/185 in all install targets
+- `WINDSURFRULES_DEST` initialized to empty string to prevent `set -u` crash
+
+### Bug Fixes
+- `claude-code-guide` removed from ECC_AGENTS (agent file does not exist — invocations were silently failing)
+- `conversation-analyzer` added to ECC_AGENTS (agent file exists, was untracked)
+- `buildAgentLeaderboard` sessions counter fixed — now counts unique sessions via Set, not invocations
+- Windsurf removed from CLOUD_AI_PLATFORMS — it has local files; only Antigravity is truly cloud-AI
+- Path traversal protection added to Lens static file server
+- OpenCode added to server.js startup tracking message
+- Linux Cursor path (`~/.config/Cursor/`) added to platform detector
+- Unused `PLATFORM` constant removed from platform-detector.js
+- Dead `src` variable replaced with intent tooltip in renderSessions
+
+### Content
+- README: intent detection table, ANTIGRAVITY_DIR env var, Codex/OpenCode install tables, npx instructions
+- KODELYTH.md: fully updated with all v1.1.0 and v1.2.0 additions
+- Dashboard version badge updated to v1.2
+
+---
+
+## v1.1.0 — Full Enhancement Release (April 2026)
+
+### New Agents (3)
+
+#### `api-guardian`
+- API contract protection specialist — detects breaking changes before they ship
+- Classifies every change: BREAKING (block), SAFE (additive), WARN (design issues)
+- Consumer impact report: number of affected clients, migration path, deprecation timeline
+- Enforces: versioning strategy, `Deprecation` headers, idempotency keys, machine-readable error codes, `X-RateLimit-*` headers
+- Covers REST, GraphQL, gRPC, WebSocket contracts
+- Model-agnostic
+
+#### `pair-programmer`
+- Pre-code thinking partner — catches the wrong approach before a line is written
+- "Cost curve of bugs: thinking=0x, code review=6x, production=200x"
+- Pre-implementation checklist: correctness, scale, simplicity, testability, reversibility
+- Wrong approach detection: premature optimization, over-engineering, wrong abstraction, missing idempotency
+- Push-back patterns: when to simplify, when to split, when to use an existing library
+- Model-agnostic
+
+#### `migration-guide`
+- Full migration playbooks: 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 → Phase 1: blast radius map → Phase 2: phased plan → Phase 3: execute → Phase 4: validate
+- Dependency conflict resolution for npm, pip, Gradle
+- Incremental migration strategy — never "stop the world"
+- Model-agnostic
+
+### New Skills (2)
+
+#### `git-mastery`
+- Trunk-based development vs gitflow vs GitHub Flow — decision framework
+- Ship/Show/Ask branching philosophy
+- Interactive rebase: squash, fixup, split, reorder commits
+- `git bisect` for regression hunting
+- Worktrees for parallel feature development
+- Monorepo patterns, branch protection rules
+- Emergency recovery: dangling commits, reflog, `git stash`
+
+#### `observability`
+- Structured logging with Pino (Node.js) and structlog (Python) — before/after examples
+- Three metric types: Counter, Gauge, Histogram — with naming conventions
+- Four Golden Signals: latency, traffic, errors, saturation
+- OpenTelemetry setup with custom spans and baggage propagation
+- Correlation ID propagation across services
+- SLOs, SLIs, SLAs, error budgets
+- Health check endpoint patterns (`/health`, `/ready`, `/live`)
+- Alerting rules (latency p99, error rate, saturation)
+
+### New Hooks (3)
+
+#### `test-reminder` (PostToolUse — Edit/Write/MultiEdit)
+- Detects when a code file is edited but no corresponding test file was touched
+- Posts a non-blocking reminder box to stderr
+- Language-aware: covers `.ts`, `.tsx`, `.js`, `.py`, `.go`, `.rs`, `.java`, `.rb`, `.php`
+- Respects `ECC_DISABLED_HOOKS=kodelyth:test-reminder` env var
+- Async, timeout 5s — never delays tool execution
+
+#### `smart-suggest` (Stop hook)
+- After each Claude response, detects session signals and suggests the next logical agent
+- 8 detection rules: errors → debug-detective, "looks good" → code-reviewer, migration terms → migration-guide, API changes → api-guardian, slow performance → performance-optimizer, etc.
+- Non-blocking, outputs to stderr
+- Respects `ECC_DISABLED_HOOKS=kodelyth:smart-suggest`
+
+#### `branch-name-check` (PreToolUse — Bash)
+- Intercepts `git checkout -b` and `git switch -c` commands
+- Enforces pattern: `^(feat|fix|chore|docs|refactor|test|perf|ci|hotfix|release|experiment|spike|wip)\/[a-z0-9][a-z0-9-._/]{1,60}$`
+- Blocks with exit code 2, clear explanation, and valid examples
+- Respects `ECC_DISABLED_HOOKS=kodelyth:branch-name`
+
+### Install Profiles
+
+Added `--profile` flag to `install.sh` and `install.ps1`:
+
+| Profile | Languages installed |
+|---|---|
+| `--profile nextjs` | TypeScript |
+| `--profile python-api` | Python |
+| `--profile fullstack` | TypeScript + Python + Go |
+| `--profile mobile` | Kotlin + Swift |
+| `--profile backend` | Go + Python + Java |
+
+### CONTRIBUTING.md
+
+Full contribution guide with:
+- Kodelyth Standard definition (GOD-level persona requirements)
+- Agent template with required sections (persona, tools, output format, Kodelyth footer)
+- Skill template with quality standards
+- Hook script template with all safety requirements
+- Hook ID naming convention: `kodelyth:{phase}:{matcher}:{name}`
+- Branch naming and PR description templates
+- "What we want / don't want" guidance
+
+### Other
+
+- VERSION bumped: `1.0.0` → `1.1.0`
+- AGENTS.md updated: api-guardian, pair-programmer, migration-guide added to Kodelyth Exclusive section
+- README.md updated: all new agents, skills, hooks, install profiles, Contributing section
+- `.agent/skills/` synced: all 3 new agents copied to Antigravity pre-built layout
+- Badge count updated: Skills 183 → 185
+
+---
+
+## v1.0.0 — Initial Release (April 2026)
+
+### Foundation
+- Initial public release of Kodelyth ECC
+- Full multi-platform support: Claude Code, Google Antigravity, Cursor, Codex, OpenCode
+
+### Kodelyth Exclusive Agents (3 new)
+
+#### `kodelyth-advisor`
+- Master engineering advisor with decade-level experience persona
+- Reads user emotional state and responds to the *person* first, then the problem
+- Knows every agent, skill, and command — gives direct, confident tool recommendations
+- Responds differently to frustration, confusion, excitement — never robotic
+- Model-agnostic — works with any Claude model
+
+#### `debug-detective`
+- Systematic root-cause analyst — never guesses, never patches symptoms
+- Formal hypothesis protocol: CLAIM → EVIDENCE → TEST
+- Advanced debugging patterns: binary search debug, git bisect, minimal reproducer, chaos testing
+- Deep language patterns for TypeScript/JS, Python, Go, SQL
+- Model-agnostic — works with any Claude model
+
+#### `ux-reviewer`
+- Master UX and accessibility engineer
+- Explicitly never touches visual design/aesthetics — only interaction behavior
+- Full WCAG 2.1 AA review with real before/after code examples
+- Covers: interaction logic, error states, loading states, mobile/touch, keyboard navigation, screen readers
+- Model-agnostic — works with any Claude model
+
+### Kodelyth Exclusive Skills (2 new)
+
+#### `kodelyth-quickstart`
+- Plain-language getting-started guide for new users
+- Explains agents, skills, commands, and hooks without jargon
+- Quick-reference card covering every major workflow
+- Designed to be read in under 10 minutes
+
+#### `smart-debug`
+- 5-step systematic debugging framework for any language
+- Step 1: Characterize — Step 2: Read the error — Step 3: Hypothesize — Step 4: Evidence — Step 5: Fix and verify
+- Language-specific tips for TypeScript/JS, Python, Go, SQL
+- Common bug pattern reference table by symptom
+- Rubber duck checklist for when you're stuck
+
+### Core Enhancements
+
+#### SOUL.md — Enhanced Identity
+- Added 2 new core principles: "Friendly by Default" and "Debug to Root Cause"
+- Added explicit Personality section — warm, direct, proactive, honest
+- Added Kodelyth brand identity throughout
+
+#### CLAUDE.md — Updated Reference
+- Added Kodelyth additions table
+- Added new commands reference for `/kodelyth-quickstart` and `/smart-debug`
+- Updated skill-to-file mapping
+
+#### README.md — Kodelyth Branded
+- "Kodelyth Enhanced Edition" section with full feature table
+- Original repo credits maintained
+
+### Installer
+
+#### `install.sh` (macOS/Linux)
+- Supports 5 targets: `claude-home`, `antigravity`, `cursor-project`, `codex-home`, `opencode`
+- Automatic language module installation
+- Smart flattening for targets that require flat rule directories (Antigravity, Cursor)
+- Install state tracking via `kodelyth-ecc-install-state.json`
+- ASCII banner and colored output
+
+#### `install.ps1` (Windows PowerShell)
+- Full feature parity with `install.sh`
+- Supports all 5 targets
+- Same install state tracking
+
+### Antigravity Pre-built Layout
+- `.agent/rules/` — 12 rule files (flattened for Antigravity)
+- `.agent/workflows/` — 79 command workflows
+- `.agent/skills/` — all 50 agents
+
+---
+
+---
+
+> Powered by Kodelyth — [github.com/sifxprime/kodelyth-ecc](https://github.com/sifxprime/kodelyth-ecc)

package/CLAUDE.md

@@ -0,0 +1,90 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in 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.
+
+## Running Tests
+
+```bash
+# Run all tests
+node tests/run-all.js
+
+# Run individual test files
+node tests/lib/utils.test.js
+node tests/lib/package-manager.test.js
+node tests/hooks/hooks.test.js
+```
+
+## Architecture
+
+The project is organized into several core components:
+
+- **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
+
+## Key Commands
+
+- `/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)
+
+## Kodelyth Additions
+
+This is the **Kodelyth Enhanced Edition**. The following agents and skills were added:
+
+| 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 |
+
+See [KODELYTH.md](KODELYTH.md) for full details.
+
+## 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
+- 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
+
+Use the following skills when working on related files:
+
+| File(s) | Skill |
+|---------|-------|
+| `README.md` | `/readme` |
+| `.github/workflows/*.yml` | `/ci-workflow` |
+| New users / onboarding | `/kodelyth-quickstart` |
+| Any debugging session | `/smart-debug` |
+
+When spawning subagents, always pass conventions from the respective skill into the agent's prompt.