kodelyth-ecc 1.2.0

package/rules/common/performance.md

@@ -0,0 +1,178 @@
+# Performance & Cost Optimization
+
+## Budget-First Principle (CRITICAL)
+
+**Every token costs money. Every agent invocation costs money. Treat both as finite resources.**
+
+Match the model to the task complexity. Do not default to the heaviest model — that wastes money. Do not default to the lightest model on complex work — that wastes time and produces worse output. Pick the right tier for the actual task in front of you.
+
+---
+
+## Model Selection by Platform
+
+### Claude Code (Anthropic Models)
+
+| Tier | Model | Task Examples |
+|---|---|---|
+| **Trivial** | Claude Haiku | Rename, format, autocomplete, write a single test, update a comment |
+| **Standard** | Claude Sonnet 4.6 | Build a component, write an API route, debug a bug, refactor a module — **most real coding work** |
+| **Maximum** | Claude Opus 4.6 | Architect a system, plan a large migration, analyze cross-cutting security issues, hardest problems |
+
+**Most sessions run on Sonnet 4.6.** Haiku is for genuinely trivial edits. Opus 4.6 is for decisions that would take a senior engineer an hour of deep thinking.
+
+---
+
+### Google Antigravity — Approved Model Stack
+
+The approved stack is 4 models. **Gemini 3 Flash and GPT-OSS 120B are not used** — they are insufficient for production-grade, multi-language, 300B-scale work.
+
+| Tier | Model | Task Examples |
+|---|---|---|
+| **Standard** | Gemini 3.1 Pro (Low) | Build components, write API routes, server actions, debug rendering issues, write tests, everyday refactoring — **most real coding work** |
+| **Complex** | Gemini 3.1 Pro (High) | Deep multi-file reasoning, architecture decisions, hard bugs spanning many files, security audits, migration planning |
+| **Claude Standard** | Claude Sonnet 4.6 (Thinking) | When Claude agent behavior is needed, extended thinking on difficult problems, complex agent orchestration |
+| **Claude Maximum** | Claude Opus 4.6 (Thinking) | Hardest architectural decisions, maximum reasoning — use when Pro (High) and Sonnet both fall short |
+
+**Do not use:**
+- Gemini 3 Flash — insufficient depth for production work
+- GPT-OSS 120B (Medium) — not part of the Kodelyth ECC stack
+
+---
+
+### Antigravity Task Mapping — Any Language, Any Scale
+
+| What you are doing | Right model |
+|---|---|
+| Building a React/Next.js component | Gemini 3.1 Pro (Low) |
+| Writing an API route or server action | Gemini 3.1 Pro (Low) |
+| Writing tests | Gemini 3.1 Pro (Low) |
+| Debugging a rendering or logic bug | Gemini 3.1 Pro (Low) |
+| Go service implementation | Gemini 3.1 Pro (Low) |
+| Python API endpoint | Gemini 3.1 Pro (Low) |
+| Kotlin Android feature | Gemini 3.1 Pro (Low) |
+| Rust systems code | Gemini 3.1 Pro (Low) |
+| Java Spring Boot service | Gemini 3.1 Pro (Low) |
+| Hard bug spanning 8+ files | Gemini 3.1 Pro (High) |
+| Auth system architecture | Gemini 3.1 Pro (High) |
+| Security audit across codebase | Gemini 3.1 Pro (High) |
+| Cross-service debugging | Gemini 3.1 Pro (High) |
+| Database schema and query design | Gemini 3.1 Pro (High) |
+| Migration planning (framework, language) | Gemini 3.1 Pro (High) |
+| Deep agent reasoning needed | Claude Sonnet 4.6 (Thinking) |
+| Complex multi-agent orchestration | Claude Sonnet 4.6 (Thinking) |
+| Hardest architectural decisions | Claude Opus 4.6 (Thinking) |
+| Problem that Pro (High) could not solve | Claude Opus 4.6 (Thinking) |
+
+**Gemini 3.1 Pro (High) vs (Low) — choose High when:**
+- Task spans 10+ files and requires cross-file reasoning
+- A bug has resisted Pro (Low)'s analysis
+- Security or compliance audit needs full codebase context
+- Architecture decision has significant long-term trade-offs
+- Migration involves complex dependency trees across the project
+
+**Claude Sonnet 4.6 (Thinking) — choose when:**
+- You need Claude-specific agent behaviors from ECC
+- The problem requires extended thinking beyond Gemini's reasoning
+- You are orchestrating multiple agents and need deep coordination logic
+
+**Claude Opus 4.6 (Thinking) — last resort:**
+- Only when Gemini 3.1 Pro (High) and Claude Sonnet 4.6 have both been tried and fallen short
+- Maximum reasoning on the hardest architectural problems
+- Never open with Opus on a task Pro (Low) can handle
+
+---
+
+## Token Efficiency Rules
+
+### Keep Context Lean
+
+- Read only the function or section needed — never feed entire files when a targeted read works
+- Summarize long conversations before continuing deep sessions (`/compact` in Claude Code)
+- Avoid the last 20% of the context window for large operations — start a fresh session instead
+- Clear context between unrelated tasks — stale context adds noise and cost
+
+### Low-Context Tasks — safe at any point in a session
+
+- Single-file edits
+- Standalone utility creation
+- Documentation updates
+- Simple bug fixes
+- Writing a test for a function that already exists
+
+### High-Context Tasks — start fresh or compact first
+
+- Large-scale refactoring across many files
+- Feature implementation spanning multiple modules
+- Debugging complex multi-service interactions
+- Any task requiring reading 10+ files simultaneously
+
+---
+
+## Agent Invocation Cost Discipline
+
+- **Don't spawn agents for trivial tasks** — a one-liner fix does not need a code-reviewer agent
+- **Batch related changes** before invoking a reviewer — review once after a logical unit of work, not after every single edit
+- **Use `async: true` for all non-blocking hooks** — never let a hook add latency to tool execution (Claude Code)
+- **Set hook timeouts aggressively** — hooks must complete in under 5 seconds; anything longer gets killed
+- **Disable hooks you don't use** (Claude Code):
+  ```bash
+  export ECC_DISABLED_HOOKS=kodelyth:smart-suggest,kodelyth:test-reminder
+  ```
+
+---
+
+## Thinking Mode — Use Surgically
+
+Claude Sonnet 4.6 (Thinking) and Claude Opus 4.6 (Thinking) reserve large token budgets for internal reasoning. Gemini 3.1 Pro (High) activates deep reasoning mode. Both are expensive. Use deliberately.
+
+**Enable thinking / Pro (High) for:**
+- Architectural decisions with significant trade-offs
+- Security analysis of sensitive code paths
+- Debugging that has resisted standard analysis
+- Migration planning across a large, complex codebase
+
+**Stay on Pro (Low) for:**
+- Routine code generation
+- Documentation and comment updates
+- Standard refactoring with a clear path
+- Any task where the answer is immediately obvious from context
+
+**Claude Code — cap thinking budget to control cost:**
+```bash
+export MAX_THINKING_TOKENS=5000
+
+# Toggle extended thinking: Option+T (macOS) / Alt+T (Windows/Linux)
+```
+
+**Antigravity — select at model picker:**
+- Gemini 3.1 Pro (Low) = fast, capable, handles most work
+- Gemini 3.1 Pro (High) = deep reasoning mode, costs more
+- Claude Sonnet 4.6 (Thinking) = Claude agent behavior + thinking
+- Claude Opus 4.6 (Thinking) = maximum, last resort
+
+---
+
+## Cost Tracking (Claude Code)
+
+The cost-tracker hook logs token usage per session to `~/.claude/logs/token-usage.jsonl`.
+
+```bash
+# Top 10 most expensive sessions
+cat ~/.claude/logs/token-usage.jsonl | jq -s 'sort_by(.tokens) | reverse | .[0:10]'
+
+# Average tokens per session
+cat ~/.claude/logs/token-usage.jsonl | jq -s '[.[].tokens] | add / length'
+```
+
+High-cost sessions signal one of three problems: wrong model selection, poor context hygiene, or over-spawning agents. Fix the habit, not just the session.
+
+---
+
+## Build Troubleshooting
+
+Build errors are pattern-matching tasks, not deep reasoning tasks.
+
+1. Use **build-error-resolver** agent — Pro (Low) or Sonnet tier, not Opus
+2. Feed the exact error message, not the entire build log
+3. Fix one error at a time
+4. Verify after each fix before continuing

package/rules/common/security.md

@@ -0,0 +1,29 @@
+# Security Guidelines
+
+## Mandatory Security Checks
+
+Before ANY commit:
+- [ ] No hardcoded secrets (API keys, passwords, tokens)
+- [ ] All user inputs validated
+- [ ] SQL injection prevention (parameterized queries)
+- [ ] XSS prevention (sanitized HTML)
+- [ ] CSRF protection enabled
+- [ ] Authentication/authorization verified
+- [ ] Rate limiting on all endpoints
+- [ ] Error messages don't leak sensitive data
+
+## Secret Management
+
+- NEVER hardcode secrets in source code
+- ALWAYS use environment variables or a secret manager
+- Validate that required secrets are present at startup
+- Rotate any secrets that may have been exposed
+
+## Security Response Protocol
+
+If security issue found:
+1. STOP immediately
+2. Use **security-reviewer** agent
+3. Fix CRITICAL issues before continuing
+4. Rotate any exposed secrets
+5. Review entire codebase for similar issues

package/rules/common/testing.md

@@ -0,0 +1,57 @@
+# Testing Requirements
+
+## Minimum Test Coverage: 80%
+
+Test Types (ALL required):
+1. **Unit Tests** - Individual functions, utilities, components
+2. **Integration Tests** - API endpoints, database operations
+3. **E2E Tests** - Critical user flows (framework chosen per language)
+
+## Test-Driven Development
+
+MANDATORY workflow:
+1. Write test first (RED)
+2. Run test - it should FAIL
+3. Write minimal implementation (GREEN)
+4. Run test - it should PASS
+5. Refactor (IMPROVE)
+6. Verify coverage (80%+)
+
+## Troubleshooting Test Failures
+
+1. Use **tdd-guide** agent
+2. Check test isolation
+3. Verify mocks are correct
+4. Fix implementation, not tests (unless tests are wrong)
+
+## Agent Support
+
+- **tdd-guide** - Use PROACTIVELY for new features, enforces write-tests-first
+
+## Test Structure (AAA Pattern)
+
+Prefer Arrange-Act-Assert structure for tests:
+
+```typescript
+test('calculates similarity correctly', () => {
+  // Arrange
+  const vector1 = [1, 0, 0]
+  const vector2 = [0, 1, 0]
+
+  // Act
+  const similarity = calculateCosineSimilarity(vector1, vector2)
+
+  // Assert
+  expect(similarity).toBe(0)
+})
+```
+
+### Test Naming
+
+Use descriptive names that explain the behavior under test:
+
+```typescript
+test('returns empty array when no markets match query', () => {})
+test('throws error when API key is missing', () => {})
+test('falls back to substring search when Redis is unavailable', () => {})
+```

package/rules/cpp/coding-style.md

@@ -0,0 +1,44 @@
+---
+paths:
+  - "**/*.cpp"
+  - "**/*.hpp"
+  - "**/*.cc"
+  - "**/*.hh"
+  - "**/*.cxx"
+  - "**/*.h"
+  - "**/CMakeLists.txt"
+---
+# C++ Coding Style
+
+> This file extends [common/coding-style.md](../common/coding-style.md) with C++ specific content.
+
+## Modern C++ (C++17/20/23)
+
+- Prefer **modern C++ features** over C-style constructs
+- Use `auto` when the type is obvious from context
+- Use `constexpr` for compile-time constants
+- Use structured bindings: `auto [key, value] = map_entry;`
+
+## Resource Management
+
+- **RAII everywhere** — no manual `new`/`delete`
+- Use `std::unique_ptr` for exclusive ownership
+- Use `std::shared_ptr` only when shared ownership is truly needed
+- Use `std::make_unique` / `std::make_shared` over raw `new`
+
+## Naming Conventions
+
+- Types/Classes: `PascalCase`
+- Functions/Methods: `snake_case` or `camelCase` (follow project convention)
+- Constants: `kPascalCase` or `UPPER_SNAKE_CASE`
+- Namespaces: `lowercase`
+- Member variables: `snake_case_` (trailing underscore) or `m_` prefix
+
+## Formatting
+
+- Use **clang-format** — no style debates
+- Run `clang-format -i <file>` before committing
+
+## Reference
+
+See skill: `cpp-coding-standards` for comprehensive C++ coding standards and guidelines.

package/rules/cpp/hooks.md

@@ -0,0 +1,39 @@
+---
+paths:
+  - "**/*.cpp"
+  - "**/*.hpp"
+  - "**/*.cc"
+  - "**/*.hh"
+  - "**/*.cxx"
+  - "**/*.h"
+  - "**/CMakeLists.txt"
+---
+# C++ Hooks
+
+> This file extends [common/hooks.md](../common/hooks.md) with C++ specific content.
+
+## Build Hooks
+
+Run these checks before committing C++ changes:
+
+```bash
+# Format check
+clang-format --dry-run --Werror src/*.cpp src/*.hpp
+
+# Static analysis
+clang-tidy src/*.cpp -- -std=c++17
+
+# Build
+cmake --build build
+
+# Tests
+ctest --test-dir build --output-on-failure
+```
+
+## Recommended CI Pipeline
+
+1. **clang-format** — formatting check
+2. **clang-tidy** — static analysis
+3. **cppcheck** — additional analysis
+4. **cmake build** — compilation
+5. **ctest** — test execution with sanitizers

package/rules/cpp/patterns.md

@@ -0,0 +1,51 @@
+---
+paths:
+  - "**/*.cpp"
+  - "**/*.hpp"
+  - "**/*.cc"
+  - "**/*.hh"
+  - "**/*.cxx"
+  - "**/*.h"
+  - "**/CMakeLists.txt"
+---
+# C++ Patterns
+
+> This file extends [common/patterns.md](../common/patterns.md) with C++ specific content.
+
+## RAII (Resource Acquisition Is Initialization)
+
+Tie resource lifetime to object lifetime:
+
+```cpp
+class FileHandle {
+public:
+    explicit FileHandle(const std::string& path) : file_(std::fopen(path.c_str(), "r")) {}
+    ~FileHandle() { if (file_) std::fclose(file_); }
+    FileHandle(const FileHandle&) = delete;
+    FileHandle& operator=(const FileHandle&) = delete;
+private:
+    std::FILE* file_;
+};
+```
+
+## Rule of Five/Zero
+
+- **Rule of Zero**: Prefer classes that need no custom destructor, copy/move constructors, or assignments
+- **Rule of Five**: If you define any of destructor/copy-ctor/copy-assign/move-ctor/move-assign, define all five
+
+## Value Semantics
+
+- Pass small/trivial types by value
+- Pass large types by `const&`
+- Return by value (rely on RVO/NRVO)
+- Use move semantics for sink parameters
+
+## Error Handling
+
+- Use exceptions for exceptional conditions
+- Use `std::optional` for values that may not exist
+- Use `std::expected` (C++23) or result types for expected failures
+
+## Reference
+
+See skill: `cpp-coding-standards` for comprehensive C++ patterns and anti-patterns.

package/rules/cpp/security.md

@@ -0,0 +1,51 @@
+---
+paths:
+  - "**/*.cpp"
+  - "**/*.hpp"
+  - "**/*.cc"
+  - "**/*.hh"
+  - "**/*.cxx"
+  - "**/*.h"
+  - "**/CMakeLists.txt"
+---
+# C++ Security
+
+> This file extends [common/security.md](../common/security.md) with C++ specific content.
+
+## Memory Safety
+
+- Never use raw `new`/`delete` — use smart pointers
+- Never use C-style arrays — use `std::array` or `std::vector`
+- Never use `malloc`/`free` — use C++ allocation
+- Avoid `reinterpret_cast` unless absolutely necessary
+
+## Buffer Overflows
+
+- Use `std::string` over `char*`
+- Use `.at()` for bounds-checked access when safety matters
+- Never use `strcpy`, `strcat`, `sprintf` — use `std::string` or `fmt::format`
+
+## Undefined Behavior
+
+- Always initialize variables
+- Avoid signed integer overflow
+- Never dereference null or dangling pointers
+- Use sanitizers in CI:
+  ```bash
+  cmake -DCMAKE_CXX_FLAGS="-fsanitize=address,undefined" ..
+  ```
+
+## Static Analysis
+
+- Use **clang-tidy** for automated checks:
+  ```bash
+  clang-tidy --checks='*' src/*.cpp
+  ```
+- Use **cppcheck** for additional analysis:
+  ```bash
+  cppcheck --enable=all src/
+  ```
+
+## Reference
+
+See skill: `cpp-coding-standards` for detailed security guidelines.

package/rules/cpp/testing.md

@@ -0,0 +1,44 @@
+---
+paths:
+  - "**/*.cpp"
+  - "**/*.hpp"
+  - "**/*.cc"
+  - "**/*.hh"
+  - "**/*.cxx"
+  - "**/*.h"
+  - "**/CMakeLists.txt"
+---
+# C++ Testing
+
+> This file extends [common/testing.md](../common/testing.md) with C++ specific content.
+
+## Framework
+
+Use **GoogleTest** (gtest/gmock) with **CMake/CTest**.
+
+## Running Tests
+
+```bash
+cmake --build build && ctest --test-dir build --output-on-failure
+```
+
+## Coverage
+
+```bash
+cmake -DCMAKE_CXX_FLAGS="--coverage" -DCMAKE_EXE_LINKER_FLAGS="--coverage" ..
+cmake --build .
+ctest --output-on-failure
+lcov --capture --directory . --output-file coverage.info
+```
+
+## Sanitizers
+
+Always run tests with sanitizers in CI:
+
+```bash
+cmake -DCMAKE_CXX_FLAGS="-fsanitize=address,undefined" ..
+```
+
+## Reference
+
+See skill: `cpp-testing` for detailed C++ testing patterns, TDD workflow, and GoogleTest/GMock usage.

package/rules/csharp/coding-style.md

@@ -0,0 +1,72 @@
+---
+paths:
+  - "**/*.cs"
+  - "**/*.csx"
+---
+# C# Coding Style
+
+> This file extends [common/coding-style.md](../common/coding-style.md) with C#-specific content.
+
+## Standards
+
+- Follow current .NET conventions and enable nullable reference types
+- Prefer explicit access modifiers on public and internal APIs
+- Keep files aligned with the primary type they define
+
+## Types and Models
+
+- Prefer `record` or `record struct` for immutable value-like models
+- Use `class` for entities or types with identity and lifecycle
+- Use `interface` for service boundaries and abstractions
+- Avoid `dynamic` in application code; prefer generics or explicit models
+
+```csharp
+public sealed record UserDto(Guid Id, string Email);
+
+public interface IUserRepository
+{
+    Task<UserDto?> FindByIdAsync(Guid id, CancellationToken cancellationToken);
+}
+```
+
+## Immutability
+
+- Prefer `init` setters, constructor parameters, and immutable collections for shared state
+- Do not mutate input models in-place when producing updated state
+
+```csharp
+public sealed record UserProfile(string Name, string Email);
+
+public static UserProfile Rename(UserProfile profile, string name) =>
+    profile with { Name = name };
+```
+
+## Async and Error Handling
+
+- Prefer `async`/`await` over blocking calls like `.Result` or `.Wait()`
+- Pass `CancellationToken` through public async APIs
+- Throw specific exceptions and log with structured properties
+
+```csharp
+public async Task<Order> LoadOrderAsync(
+    Guid orderId,
+    CancellationToken cancellationToken)
+{
+    try
+    {
+        return await repository.FindAsync(orderId, cancellationToken)
+            ?? throw new InvalidOperationException($"Order {orderId} was not found.");
+    }
+    catch (Exception ex)
+    {
+        logger.LogError(ex, "Failed to load order {OrderId}", orderId);
+        throw;
+    }
+}
+```
+
+## Formatting
+
+- Use `dotnet format` for formatting and analyzer fixes
+- Keep `using` directives organized and remove unused imports
+- Prefer expression-bodied members only when they stay readable

package/rules/csharp/hooks.md

@@ -0,0 +1,25 @@
+---
+paths:
+  - "**/*.cs"
+  - "**/*.csx"
+  - "**/*.csproj"
+  - "**/*.sln"
+  - "**/Directory.Build.props"
+  - "**/Directory.Build.targets"
+---
+# C# Hooks
+
+> This file extends [common/hooks.md](../common/hooks.md) with C#-specific content.
+
+## PostToolUse Hooks
+
+Configure in `~/.claude/settings.json`:
+
+- **dotnet format**: Auto-format edited C# files and apply analyzer fixes
+- **dotnet build**: Verify the solution or project still compiles after edits
+- **dotnet test --no-build**: Re-run the nearest relevant test project after behavior changes
+
+## Stop Hooks
+
+- Run a final `dotnet build` before ending a session with broad C# changes
+- Warn on modified `appsettings*.json` files so secrets do not get committed

package/rules/csharp/patterns.md

@@ -0,0 +1,50 @@
+---
+paths:
+  - "**/*.cs"
+  - "**/*.csx"
+---
+# C# Patterns
+
+> This file extends [common/patterns.md](../common/patterns.md) with C#-specific content.
+
+## API Response Pattern
+
+```csharp
+public sealed record ApiResponse<T>(
+    bool Success,
+    T? Data = default,
+    string? Error = null,
+    object? Meta = null);
+```
+
+## Repository Pattern
+
+```csharp
+public interface IRepository<T>
+{
+    Task<IReadOnlyList<T>> FindAllAsync(CancellationToken cancellationToken);
+    Task<T?> FindByIdAsync(Guid id, CancellationToken cancellationToken);
+    Task<T> CreateAsync(T entity, CancellationToken cancellationToken);
+    Task<T> UpdateAsync(T entity, CancellationToken cancellationToken);
+    Task DeleteAsync(Guid id, CancellationToken cancellationToken);
+}
+```
+
+## Options Pattern
+
+Use strongly typed options for config instead of reading raw strings throughout the codebase.
+
+```csharp
+public sealed class PaymentsOptions
+{
+    public const string SectionName = "Payments";
+    public required string BaseUrl { get; init; }
+    public required string ApiKeySecretName { get; init; }
+}
+```
+
+## Dependency Injection
+
+- Depend on interfaces at service boundaries
+- Keep constructors focused; if a service needs too many dependencies, split responsibilities
+- Register lifetimes intentionally: singleton for stateless/shared services, scoped for request data, transient for lightweight pure workers