kodelyth-ecc 1.2.0

package/README.md

@@ -0,0 +1,414 @@
+<div align="center">
+
+<img src="social/readme-hero.svg" alt="Kodelyth ECC — AI Agent Toolkit" width="900"/>
+
+[![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+![Claude Code](https://img.shields.io/badge/Claude%20Code-Ready-8A2BE2)
+![Antigravity](https://img.shields.io/badge/Antigravity-Ready-00ADD8)
+![Version](https://img.shields.io/badge/version-1.2.0-orange)
+![Agents](https://img.shields.io/badge/Agents-53-brightgreen)
+![Skills](https://img.shields.io/badge/Skills-185-brightgreen)
+
+</div>
+
+**Kodelyth ECC** is a battle-tested, production-ready AI coding toolkit — 53 specialist agents, 185 skills, 79 commands, automated quality gates, and a real-time usage dashboard built in. Built and maintained by **Kodelyth**.
+
+Works with **Claude Code**, **Google Antigravity**, **Cursor**, **Codex CLI**, and **OpenCode**.
+
+---
+
+## Install
+
+### Option 1 — npx (Node.js, any platform)
+
+Requires Node.js 18+. No `git` needed — npx downloads directly from GitHub.
+
+```bash
+npx github:sifxprime/kodelyth-ecc
+```
+
+Install for a specific platform:
+
+```bash
+npx github:sifxprime/kodelyth-ecc --target windsurf-project    # Windsurf (project)
+npx github:sifxprime/kodelyth-ecc --target windsurf-home       # Windsurf (global)
+npx github:sifxprime/kodelyth-ecc --target antigravity         # Google Antigravity
+npx github:sifxprime/kodelyth-ecc --target cursor-project      # Cursor IDE
+npx github:sifxprime/kodelyth-ecc --target codex-home          # Codex CLI
+npx github:sifxprime/kodelyth-ecc --target opencode            # OpenCode
+```
+
+> Node.js not installed? Download it from [nodejs.org](https://nodejs.org) — LTS version recommended.
+
+---
+
+### Option 2 — curl (macOS / Linux)
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/sifxprime/kodelyth-ecc/main/install.sh | bash
+```
+
+With a target:
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/sifxprime/kodelyth-ecc/main/install.sh | bash -s -- --target windsurf-project
+```
+
+---
+
+### Option 3 — clone and run (all platforms)
+
+```bash
+git clone https://github.com/sifxprime/kodelyth-ecc.git
+cd kodelyth-ecc
+
+# macOS / Linux
+./install.sh                             # Claude Code (default)
+./install.sh --target windsurf-project  # Windsurf
+./install.sh --target antigravity       # Google Antigravity
+
+# Windows
+.\install.ps1
+```
+
+---
+
+The installer automatically starts **Kodelyth Lens** and opens your browser when done (Claude Code target only).
+
+---
+
+## Kodelyth Lens — AI Usage Dashboard
+
+<img src="social/readme-lens.svg" alt="Kodelyth Lens Dashboard" width="900"/>
+
+**Kodelyth Lens** is a zero-dependency real-time dashboard included with every ECC install. It reads directly from your AI coding platform data files — no cloud, no account, no npm install.
+
+<img src="social/readme-savings.svg" alt="ECC Cost Savings" width="900"/>
+
+### What Lens tracks
+
+| Signal | How it works |
+|---|---|
+| Agent invocations | Explicit: `use <agent>`, `@agent`, `invoke agent` |
+| Agent intent | 12 intent categories — "bug" → debug-detective, "slow" → performance-optimizer |
+| Token usage | Reads session JSONL files per platform |
+| Cache savings | Cache read tokens cost 10% — ECC prompt structure maximizes hits |
+| Platform breakdown | Per-platform session count, tokens, and cost |
+| Cost comparison | Actual paid vs. estimated without-ECC cost |
+
+### Supported platforms
+
+| Platform | Data source | Sessions |
+|---|---|---|
+| Claude Code | `~/.claude/projects/**/*.jsonl` | Full local logs |
+| Codex CLI | `~/.codex/state_5.sqlite` | SQLite threads table |
+| Windsurf | `~/Library/Application Support/Windsurf/` | Cloud AI (server-side) |
+| Antigravity | `~/Library/Application Support/Antigravity/` | Cloud AI (server-side) |
+| Cursor | `~/.cursor/` | Local workspace data |
+| OpenCode | `~/.opencode/` | Local session files |
+
+Only installed platforms appear in the dashboard — nothing shown for platforms you don't have.
+
+### Manual start
+
+```bash
+node ~/.kodelyth/lens/server.js
+# → http://localhost:3456
+```
+
+### Environment overrides
+
+```bash
+CLAUDE_DIR=~/.claude          # Custom Claude Code data dir
+CURSOR_DIR=...                # Custom Cursor data dir
+WINDSURF_DIR=...              # Custom Windsurf data dir
+CODEX_DIR=~/.codex            # Custom Codex data dir
+OPENCODE_DIR=~/.opencode      # Custom OpenCode data dir
+ANTIGRAVITY_DIR=...           # Custom Antigravity data dir
+PORT=3456                     # Dashboard port (default: 3456)
+```
+
+---
+
+## What's Inside
+
+| Component | Count | Description |
+|---|---|---|
+| Agents | **53** | Specialist subagents — reviewers, planners, debuggers, architects |
+| Skills | **185** | Domain knowledge — patterns, testing, security, DevOps |
+| Commands | **79** | Slash command workflows (`/tdd`, `/plan`, `/code-review`, etc.) |
+| Hooks | **15+** | Automated lifecycle triggers — quality gates, session memory, cost tracking |
+| Rules | **12** | Language-specific coding standards |
+
+---
+
+## Agent Arsenal
+
+<img src="social/readme-agents.svg" alt="53 Specialist Agents" width="900"/>
+
+### Kodelyth Exclusives
+
+### `kodelyth-advisor` — The Master Guide
+A decade-seasoned principal engineer who reads your emotional state, understands what you're struggling with, and gives you the exact tool or approach needed. No hand-holding, no noise — direct senior-grade direction.
+
+```
+use kodelyth-advisor
+```
+
+### `debug-detective` — The Root Cause Hunter
+Never guesses. Traces every bug to its exact origin through a structured hypothesis protocol. Covers JS/TS, Python, Go, Rust, SQL — with advanced techniques like binary search debug, git bisect, and minimal reproducers.
+
+```
+use debug-detective
+```
+
+### `ux-reviewer` — The Interface Guardian
+Reviews frontend code for usability, interaction logic, and WCAG 2.1 AA accessibility. Never touches design aesthetic — only behavior. Catches what real users will feel before they feel it.
+
+```
+use ux-reviewer
+```
+
+### `api-guardian` — The API Contract Protector
+Detects breaking API changes before they ship. Classifies every change as BREAKING / SAFE / WARN, generates a consumer impact report, and enforces versioning, deprecation headers, and idempotency.
+
+```
+use api-guardian
+```
+
+### `pair-programmer` — The Pre-Code Thinking Partner
+The engineer who sits next to you before you start coding. Catches the wrong approach, over-engineered solutions, and missed edge cases — before a single line is written.
+
+```
+use pair-programmer
+```
+
+### `migration-guide` — The Framework Migration Specialist
+Full migration playbooks for 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.
+
+```
+use migration-guide
+```
+
+---
+
+### Agent Categories
+
+| Category | Agents |
+|---|---|
+| Guidance | `kodelyth-advisor`, `pair-programmer`, `planner`, `architect`, `code-architect`, `chief-of-staff`, `migration-guide` |
+| Code Review | `code-reviewer`, `typescript-reviewer`, `python-reviewer`, `go-reviewer`, `rust-reviewer`, `java-reviewer`, `kotlin-reviewer`, `cpp-reviewer`, `csharp-reviewer`, `flutter-reviewer` |
+| Build Fixing | `build-error-resolver`, `go-build-resolver`, `rust-build-resolver`, `java-build-resolver`, `kotlin-build-resolver`, `cpp-build-resolver`, `dart-build-resolver`, `pytorch-build-resolver` |
+| Debugging | `debug-detective`, `silent-failure-hunter` |
+| UX & Design | `ux-reviewer` |
+| Security | `security-reviewer`, `healthcare-reviewer`, `api-guardian` |
+| Quality | `refactor-cleaner`, `code-simplifier`, `performance-optimizer`, `type-design-analyzer` |
+| Testing | `tdd-guide`, `e2e-runner`, `pr-test-analyzer` |
+| Documentation | `doc-updater`, `docs-lookup`, `comment-analyzer` |
+| Open Source | `opensource-forker`, `opensource-packager`, `opensource-sanitizer` |
+
+---
+
+## How Agent Detection Works
+
+Agents activate in two ways — you do not always need to type `use agent-name`.
+
+**1. Explicit** — type it directly in your conversation:
+```
+use debug-detective
+@code-reviewer
+invoke security-reviewer
+```
+
+**2. Automatic intent detection** — Kodelyth Lens reads your prompts and infers which agent matches:
+
+| What you write | Agent triggered |
+|---|---|
+| "this bug won't fix", "I'm getting an error", "it's broken" | `debug-detective` |
+| "review this", "check my code", "LGTM?" | `code-reviewer` |
+| "it's slow", "taking too long", "optimize" | `performance-optimizer` |
+| "is this secure", "SQL injection", "auth" | `security-reviewer` |
+| "the build failed", "compile error", "type error" | `build-error-resolver` |
+| "write a test", "TDD", "coverage" | `tdd-guide` |
+| "the UI feels off", "accessibility", "WCAG" | `ux-reviewer` |
+| "plan this feature", "architecture", "design" | `planner` / `architect` |
+| "I'm not sure where to start", "what should I do" | `kodelyth-advisor` |
+| "refactor", "clean up", "dead code" | `refactor-cleaner` |
+| "document this", "add comments" | `doc-updater` |
+| "migrate", "upgrade framework", "breaking change" | `migration-guide` |
+
+Intent detection runs across all platforms — Claude Code, Windsurf, Cursor, Codex — anywhere Kodelyth Lens can read conversation logs. The dashboard shows both explicit and auto-detected agent activations in the leaderboard.
+
+---
+
+## Hooks — Always Running in Background
+
+Once installed, these hooks run automatically with zero configuration:
+
+| Hook | What it does |
+|---|---|
+| Session start | Loads context from previous session |
+| Pre-commit | Catches `console.log`, secrets, bad commit messages |
+| Quality gate | Runs type checks and formatting after edits |
+| Git push reminder | Prompts review before pushing |
+| Config protection | Blocks weakening of linter/formatter configs |
+| Cost tracker | Logs token usage per session |
+| Desktop notify | macOS notification when Claude finishes a long task |
+| MCP health check | Validates MCP servers before calling them |
+| Test reminder | Prompts to write tests when code is edited without tests |
+| Smart suggest | After each response, suggests the next logical agent |
+| Branch name check | Blocks git branches that don't match naming convention |
+
+---
+
+## Usage After Install
+
+### Start here (new users)
+```
+/kodelyth-quickstart
+```
+
+### Core workflows
+```bash
+use kodelyth-advisor      # Not sure what to do? Start here
+use pair-programmer       # Think through approach before writing code
+use planner               # Plan a feature before writing code
+use code-reviewer         # Review after writing code
+use debug-detective       # Trace a bug to its root cause
+use api-guardian          # Check API changes for breaking contracts
+use security-reviewer     # Review security-sensitive code
+use ux-reviewer           # Review frontend UX and accessibility
+use migration-guide       # Upgrading a framework or language version
+use tdd-guide             # Write tests the right way
+use performance-optimizer # Diagnose and fix slowness
+```
+
+### Load language patterns
+```bash
+/typescript-patterns    # TypeScript + React + Next.js
+/python-patterns        # Python best practices
+/golang-patterns        # Go best practices
+/postgres-patterns      # Database patterns
+/docker-patterns        # Container patterns
+/coding-standards       # Universal baseline
+```
+
+### Advanced skills
+```bash
+/git-mastery            # Trunk-based dev, rebase, bisect, monorepos
+/observability          # Structured logging, metrics, OpenTelemetry, SLOs
+/smart-debug            # Systematic debugging framework
+```
+
+---
+
+## What Gets Installed
+
+### Claude Code (`~/.claude/`)
+
+| Source | Destination | What it does |
+|---|---|---|
+| `agents/` | `~/.claude/agents/` | All 53 subagents available globally |
+| `skills/` | `~/.claude/skills/` | All 185 skills loadable via commands |
+| `hooks/hooks.json` | `~/.claude/hooks/` | Automated quality gates and session memory |
+| `rules/` | `~/.claude/rules/` | Always-on coding standards |
+| `commands/` | `~/.claude/commands/` | Slash commands (`/tdd`, `/plan`, etc.) |
+| `dashboard/` | `~/.kodelyth/lens/` | Kodelyth Lens usage dashboard |
+
+### Windsurf (project: `.windsurf/` · global: `~/.codeium/windsurf/`)
+
+| Source | Destination | Notes |
+|---|---|---|
+| `agents/` | `.windsurf/agents/` | Call with `use <agent-name>` in Cascade |
+| `skills/` | `.windsurf/skills/` | Domain knowledge, loadable via chat |
+| `rules/` | `.windsurf/rules/` | Flattened rule files |
+| `rules/common/` | `.windsurfrules` | Concatenated — Windsurf reads this automatically |
+
+The `.windsurfrules` file is auto-generated from all common rules and loaded by Windsurf Cascade on every session. No manual setup needed.
+
+### Codex CLI (`~/.codex/`)
+
+| Source | Destination | What it does |
+|---|---|---|
+| `agents/` | `~/.codex/agents/` | All 53 agents available globally |
+| `skills/` | `~/.codex/skills/` | All 185 skills loadable in chat |
+| `commands/` | `~/.codex/commands/` | Slash commands |
+| `rules/` | `~/.codex/rules/` | Coding standards (flattened) |
+
+### OpenCode (`.opencode/` in project root)
+
+| Source | Destination | What it does |
+|---|---|---|
+| `rules/` | `.opencode/rules/` | Coding standards (flattened) |
+
+### Antigravity (`.agent/` in project root)
+
+| Source | Destination |
+|---|---|
+| `agents/` | `.agent/skills/` |
+| `commands/` | `.agent/workflows/` |
+| `rules/` | `.agent/rules/` |
+
+---
+
+## Install Profiles — Language Bundles
+
+Works with any target:
+
+```bash
+# Claude Code
+./install.sh --profile nextjs
+npx github:sifxprime/kodelyth-ecc --profile nextjs
+
+# Windsurf
+npx github:sifxprime/kodelyth-ecc --target windsurf-project --profile nextjs
+
+# Antigravity
+npx github:sifxprime/kodelyth-ecc --target antigravity --profile python-api
+```
+
+Available profiles:
+
+| Profile | Includes |
+|---|---|
+| `nextjs` | TypeScript + React + Next.js rules |
+| `python-api` | Python + Django/FastAPI rules |
+| `fullstack` | TypeScript + Python + Go rules |
+| `mobile` | Kotlin + Swift rules |
+| `backend` | Go + Python + Java rules |
+
+Individual languages:
+```bash
+npx github:sifxprime/kodelyth-ecc typescript python golang rust java kotlin php swift cpp dart
+```
+
+---
+
+## Multi-Platform Support
+
+| Platform | Supported | Install target | What gets installed |
+|---|---|---|---|
+| Claude Code | Full | `claude-home` (default) | Agents, skills, commands, hooks, rules |
+| Windsurf | Full | `windsurf-project` / `windsurf-home` | Agents, skills, rules, `.windsurfrules` |
+| Google Antigravity | Full | `antigravity` | Agents → skills, commands → workflows, rules |
+| Cursor | Full | `cursor-project` | Rules, skills |
+| Codex CLI | Full | `codex-home` | Agents, skills, commands, rules |
+| OpenCode | Full | `opencode` | Rules |
+
+---
+
+## Contributing
+
+We welcome new agents, skills, and hooks that meet the **Kodelyth Standard** — specialist personas, model-agnostic, production-grade examples.
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for templates, checklists, and the full Kodelyth Standard.
+
+---
+
+<div align="center">
+
+Built and maintained by **Kodelyth** — [@sifxprime](https://github.com/sifxprime)
+
+Powered by **Kodelyth**.
+
+</div>

package/SECURITY.md

@@ -0,0 +1,77 @@
+# Security Policy
+
+## Supported Versions
+
+| Version | Supported |
+|---------|-----------|
+| 1.1.x   | Yes — active |
+| 1.0.x   | No — upgrade to 1.1.x |
+| < 1.0   | No |
+
+---
+
+## Reporting a Vulnerability
+
+**Do not open a public GitHub issue for security vulnerabilities.**
+
+Report privately via email:
+
+**sifxprime@kodelyth.com**
+
+Subject line: `[SECURITY] kodelyth-ecc — <short description>`
+
+### What to include
+
+- Description of the vulnerability
+- Steps to reproduce (minimal, clear)
+- Affected component (agent name, hook, install script, etc.)
+- Potential impact
+- Your suggested fix (optional but appreciated)
+
+---
+
+## Response Timeline
+
+| Stage | Timeline |
+|-------|----------|
+| Acknowledgement | Within 48 hours |
+| Initial assessment | Within 5 business days |
+| Fix or mitigation | Within 14 days for critical issues |
+| Public disclosure | After fix is released and users have time to update |
+
+---
+
+## Scope
+
+### In scope
+
+- Secrets or credentials embedded in any file in this repository
+- Install scripts (`install.sh`, `install.ps1`) that write malicious content to user machines
+- Hooks that could execute arbitrary code without user consent
+- Agent definitions that instruct the model to leak sensitive data
+
+### Out of scope
+
+- Vulnerabilities in Claude Code, Google Antigravity, or any AI platform itself
+- Social engineering attacks against end users
+- Issues that require physical access to the target machine
+
+---
+
+## Security Principles in This Project
+
+Kodelyth ECC follows these security practices:
+
+- No secrets, credentials, or API keys are stored anywhere in this repository
+- Install scripts only copy files to known user config directories (`~/.claude/`, `.agent/`)
+- Hooks run as PostToolUse/PreToolUse — they never auto-execute shell commands without user awareness
+- All hook scripts are plain Node.js with zero external npm dependencies
+- MIT license — fully auditable, no obfuscated code
+
+---
+
+## Credits
+
+Responsible disclosure is appreciated. Reporters who identify valid security issues will be credited in the release notes (unless you prefer to remain anonymous).
+
+Built and maintained by **Kodelyth** — [@sifxprime](https://github.com/sifxprime)

package/SOUL.md

@@ -0,0 +1,32 @@
+# Soul
+
+## Core Identity
+Kodelyth ECC (ECC) — **Kodelyth Enhanced Edition** — is a production-ready AI coding plugin with specialized agents, skills, commands, and automated hook workflows for software development. This edition adds smarter, friendlier tooling built for real developers building real products.
+
+## Core Principles
+1. **Agent-First** — route work to the right specialist as early as possible.
+2. **Test-Driven** — write or refresh tests before trusting implementation changes.
+3. **Security-First** — validate inputs, protect secrets, and keep safe defaults.
+4. **Immutability** — prefer explicit state transitions over mutation.
+5. **Plan Before Execute** — complex changes should be broken into deliberate phases.
+6. **Friendly by Default** — explain clearly, guide proactively, never leave the user guessing what to do next.
+7. **Debug to Root Cause** — never guess at fixes; trace errors systematically to their origin.
+8. **SVG Over Emoji** — never use decorative emoji in documentation, agent responses, or UI output. In rendered Markdown, use SVG badges and `<img>` icon tags. In terminal output, use plain Unicode symbols (✓ ✗ →) or no decoration at all. Emoji is a signal of low craft.
+9. **Budget-First** — every token and every agent invocation costs money. Default to the lightest model that solves the problem correctly. Never spawn a heavier model, longer context, or additional agent unless the lighter option demonstrably fails.
+
+## Personality
+- Warm and collaborative, not cold and mechanical
+- Direct and specific, not vague and verbose
+- Proactive — suggest what to do next, don't wait to be asked
+- Honest about uncertainty — say "I'm not sure" rather than guess
+- Celebrates progress and acknowledges good decisions
+
+## Agent Orchestration Philosophy
+ECC is designed so specialists are invoked proactively: planners for implementation strategy, reviewers for code quality, security reviewers for sensitive code, build resolvers when the toolchain breaks, and the **kodelyth-advisor** when you're not sure where to start.
+
+## Cross-Harness Vision
+This gitagent surface is an initial portability layer for ECC's shared identity, governance, and skill catalog. Native agents, commands, and hooks remain authoritative in the repository until full manifest coverage is added.
+
+---
+
+> Powered by **Kodelyth** — making AI tooling smarter, friendlier, and more productive.

package/VERSION

@@ -0,0 +1 @@
+1.2.0