kodelyth-ecc 1.4.0 → 1.5.0

package/wiki/Platform-Support.md

@@ -1,106 +1,186 @@
 # Platform Support
 
-Kodelyth ECC works across 5 AI coding platforms.
+Kodelyth ECC works across 6 AI coding platforms. Feature availability varies by platform.
 
 ---
 
-## Supported Platforms
-
-| Platform | Status | Install target |
-|----------|--------|----------------|
-| Claude Code | Full support | `--target claude-home` (default) |
-| Google Antigravity | Full support | `--target antigravity` |
-| Cursor | Full support | `--target cursor-project` |
-| Codex CLI | Full support | `--target codex-home` |
-| OpenCode | Full support | `--target opencode` |
+## Feature Matrix
+
+| Feature | Claude Code | Windsurf | Cursor | Codex CLI | Antigravity | OpenCode |
+|---|---|---|---|---|---|---|
+| Agents (59) | Full | Full | Full | Full | Full | Full |
+| Skills (188) | Full | Full | Full | Full | Full | Full |
+| Commands (80) | Full | Full | Full | Full | Full | Full |
+| Intent routing | Full | Full | Full | Full | Full | Full |
+| Rules (16) | Full | Full | Full | Full | Flattened | Full |
+| Memory inject (session start) | Full | Full | Full | Full | Full | Full |
+| Memory auto-recall (per prompt) | Full | — | — | — | — | — |
+| Memory capture (session JSONL) | Full | Partial | Partial | Partial | — | Partial |
+| Manual `/memory` commands | Full | Full | Full | Full | Full | Full |
+| Hook automation | Full | Limited | Limited | Limited | — | Limited |
 
 ---
 
 ## Claude Code
 
-**Full feature set.** All 53 agents, all 185 skills, all 79 commands, all 18+ hooks.
+**Install target:** `claude-home`
 
-Agents install to `~/.claude/agents/` and are available globally across all projects.
+```bash
+npx kodelyth-ecc --target claude-home
+```
 
-**Recommended model stack:**
+**Full feature set.** All 59 agents, 188 skills, 80 commands, all hooks including `UserPromptSubmit` auto-recall, full session JSONL access for memory capture, and complete rules.
 
-| Task complexity | Model |
-|----------------|-------|
-| Simple edits, docs, single-file fixes | Haiku |
-| Standard development, code review, features | Sonnet 4.6 |
-| Architectural decisions, complex debugging | Opus 4.6 |
+**Memory:** All three memory hooks fully operational. Auto-recall fires on every meaningful prompt.
 
----
+**Hooks:** All hooks including `UserPromptSubmit`, `PreToolUse`, `PostToolUse`, `SessionStart`, and `Stop` are supported.
 
-## Google Antigravity
+---
 
-**Full agent + command + always-on rules support.** No hook execution engine (hooks approximated via always-on rules).
+## Windsurf
 
-Installs into `.agent/` inside your project directory.
+**Install targets:** `windsurf-project` (per-project) or `windsurf-home` (global)
 
-**Approved model stack (Antigravity):**
+```bash
+npx kodelyth-ecc --target windsurf-project
+npx kodelyth-ecc --target windsurf-home
+```
 
-| Task | Model |
-|------|-------|
-| Code edits, formatting, simple tasks | Gemini 3.1 Pro (Low) |
-| Complex features, multi-file refactoring | Gemini 3.1 Pro (High) |
-| Agent behavior, reasoning-heavy tasks | Claude Sonnet 4.6 Thinking |
-| Maximum reasoning, architecture | Claude Opus 4.6 Thinking |
+The installer generates a `.windsurfrules` file that Cascade loads automatically.
 
-**Not recommended:** Gemini Flash (too weak for production coding tasks), GPT-OSS (not in approved stack).
+**Agents, skills, and commands:** Full.
 
-**After install:**
-```
-your-project/
-└── .agent/
-    ├── rules/kodelyth-always-on.md   ← auto-loaded every session
-    ├── rules/soul.md                  ← 9 core principles
-    ├── rules/agents.md                ← full agent roster
-    ├── skills/                        ← all 53 agents
-    └── workflows/                     ← all 79 commands
-```
+**Memory:** Session-start injection works. Manual `/memory` commands work. `UserPromptSubmit` auto-recall is not available — Windsurf does not expose a pre-prompt hook. Memory capture from session files works if session data is stored locally.
 
-The `kodelyth-always-on.md` file ensures ECC behavior loads automatically every session without any user prompt.
+**Hooks:** Windsurf's hook system is more limited than Claude Code's. Quality gate hooks (test-reminder, smart-suggest, branch-name-check) may not fire depending on Windsurf version.
 
 ---
 
 ## Cursor
 
-Installs rules and agents into `.cursorrules` / `.cursor/` in your project.
+**Install target:** `cursor-project`
 
 ```bash
-./install.sh --target cursor-project
+npx kodelyth-ecc --target cursor-project
 ```
 
+Installs to `.cursor/` in the current project directory.
+
+**Agents, skills, and commands:** Full.
+
+**Memory:** Session-start injection works. Manual `/memory` commands work. Auto-recall not available. Memory capture from local session files works.
+
+**Hooks:** Limited hook support. Check Cursor documentation for supported hook types.
+
 ---
 
 ## Codex CLI
 
-Installs to `~/.codex/` for global availability.
+**Install target:** `codex-home`
 
 ```bash
-./install.sh --target codex-home
+npx kodelyth-ecc --target codex-home
+```
+
+**Agents, skills, and commands:** Full.
+
+**Memory:** Session-start injection works. Manual memory commands work. Auto-recall not available. Memory capture from JSONL session logs works if Codex stores them locally.
+
+---
+
+## Google Antigravity
+
+**Install target:** `antigravity`
+
+```bash
+npx kodelyth-ecc --target antigravity
+```
+
+Antigravity requires flat rule directories (no subdirectories). The installer automatically flattens the rules structure.
+
+**Layout:**
+```
+.agent/rules/       → 16 rule files (flattened, no subdirs)
+.agent/workflows/   → 80 command workflows
+.agent/skills/      → 59 agent definitions
+```
+
+**Agents, skills, and commands:** Full.
+
+**Memory:** Session-start injection works (manual inject via `/memory inject`). Manual memory commands work. Antigravity stores sessions server-side — auto-extract from past sessions is not available. `UserPromptSubmit` auto-recall is not available.
+
+**Hooks:** Antigravity does not expose a hook system that ECC can use. Hook features are not available.
+
+**Environment variable:**
+```bash
+export ANTIGRAVITY_DIR=/path/to/.agent/
 ```
 
 ---
 
 ## OpenCode
 
-Installs to OpenCode's config directory.
+**Install target:** `opencode`
 
 ```bash
-./install.sh --target opencode
+npx kodelyth-ecc --target opencode
 ```
 
+**Agents, skills, and commands:** Full.
+
+**Memory:** Session-start injection works. Manual commands work. Auto-recall depends on whether OpenCode exposes a pre-prompt hook (check OpenCode version).
+
+---
+
+## Memory Capabilities By Platform
+
+| Capability | Claude Code | Others |
+|---|---|---|
+| Session-start inject | Full | Full |
+| Auto-recall per prompt | Yes (`UserPromptSubmit` hook) | No (hook not exposed) |
+| Manual recall | Yes (`/memory recall`) | Yes (`/memory recall`) |
+| Manual store | Yes (`/memory remember`) | Yes (`/memory remember`) |
+| Auto-extract from sessions | Yes (local JSONL) | Varies |
+| Pending review workflow | Yes | Yes (manual only) |
+| `KODELYTH_MEMORY_DIR` override | Yes | Yes |
+
+---
+
+## Multi-Platform Install
+
+You can install to multiple platforms simultaneously:
+
+```bash
+# Claude Code (primary)
+npx kodelyth-ecc --target claude-home
+
+# Windsurf (project)
+npx kodelyth-ecc --target windsurf-project
+
+# Cursor (project)
+npx kodelyth-ecc --target cursor-project
+```
+
+Memory is stored globally at `~/.kodelyth/memory/` and is shared across all platforms.
+
+---
+
+## Platform Detection
+
+The installer auto-detects installed platforms and suggests targets:
+
+- Claude Code: `~/.claude/` exists
+- Windsurf: `~/.codeium/windsurf/` or `.windsurf/` exists
+- Cursor: `~/.config/Cursor/` (Linux), `~/Library/Application Support/Cursor/` (macOS), or `%APPDATA%\Cursor\` (Windows)
+- Codex: `~/.codex/` exists
+- Antigravity: `ANTIGRAVITY_DIR` env var or `~/.config/google-gemini/` exists
+- OpenCode: `~/.opencode/` exists
+
 ---
 
-## Platform Comparison
+## Known Limitations
 
-| Feature | Claude Code | Antigravity | Cursor | Codex | OpenCode |
-|---------|------------|------------|--------|-------|---------|
-| Agents | 53 | 53 | 53 | 53 | 53 |
-| Skills | 185 | 185 (as rules) | 185 | 185 | 185 |
-| Commands | 79 | 79 | 79 | 79 | 79 |
-| Hooks | 18+ | Via rules | Partial | Partial | Partial |
-| Global install | Yes | Per-project | Per-project | Yes | Yes |
-| Always-on rules | Yes | Yes | Yes | Yes | Yes |
+- **Antigravity auto-recall:** Not available. Sessions are server-side.
+- **Windsurf `UserPromptSubmit`:** Not available in current Windsurf hook API.
+- **Cloud session extraction:** Platforms that store sessions server-side cannot be scraped for auto-extract. Use manual `/memory remember` instead.
+- **Hook consistency:** Hook behavior (test-reminder, smart-suggest, branch-name-check) is only fully reliable in Claude Code. Other platforms have varying hook support.

package/wiki/Skill-Reference.md

@@ -1,103 +1,210 @@
 # Skill Reference
 
-Skills are domain knowledge loaded into your session with a slash command. 185 skills total.
+Skills are domain knowledge and workflow definitions loaded into your session with a slash command. 188 skills total.
 
 ---
 
-## How to Load a Skill
+## How Skills Work
 
-```
-/skill-name
-```
+Skills are markdown files in `~/.claude/skills/`. When you invoke a slash command, the corresponding skill file is loaded into your session context. The AI then has access to the patterns, checklists, and domain knowledge defined in that skill.
 
-Example:
 ```
-/typescript-patterns
-/smart-debug
-/git-mastery
+/tdd              → loads skills/tdd-workflow.md
+/memory recall    → activates kodelyth-memory skill
+/smart-debug      → loads skills/smart-debug.md
 ```
 
-Skills remain active for the session and guide all agent behavior.
-
 ---
 
-## Kodelyth Skills (4 exclusive)
+## Kodelyth Exclusive Skills
+
+### `kodelyth-quickstart`
+**Command:** `/kodelyth-quickstart`
 
-### `/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 understood in under 10 minutes.
 
-Plain-language getting-started guide. Explains agents, skills, commands, and hooks in plain English. Read this first as a new user.
+**When to invoke:** First session, onboarding a new team member, after a long break.
 
-### `/smart-debug`
+---
+
+### `smart-debug`
+**Command:** `/smart-debug`
 
 5-step systematic debugging framework for any language:
+1. Characterize — what exactly is failing?
+2. Read the error — what does it actually say?
+3. Hypothesize — what could cause this?
+4. Evidence — prove or disprove each hypothesis
+5. Fix and verify — minimal change, confirm it's gone
+
+Includes language-specific tips for TypeScript/JS, Python, Go, SQL. Common bug pattern reference table by symptom. Rubber duck checklist for when you're stuck.
 
-1. **Characterize** — understand the symptom exactly
-2. **Read the error** — full stack trace, not just the last line
-3. **Hypothesize** — form 2-3 specific hypotheses
-4. **Gather evidence** — test hypotheses with minimal reproducers
-5. **Fix and verify** — fix one thing, verify, repeat
+**When to invoke:** Any debugging session, especially when stuck.
 
-Ends guess-and-check debugging permanently.
+---
 
-### `/git-mastery`
+### `kodelyth-memory`
+**Command:** `/memory`
 
-Trunk-based development, gitflow, Ship/Show/Ask decision framework. Interactive rebase, git bisect, worktrees, monorepo patterns, emergency recovery playbooks.
+Full self-learning memory system. Subcommands:
 
-### `/observability`
+| Command | What it does |
+|---|---|
+| `/memory recall <query>` | Search memory for relevant past solutions |
+| `/memory remember` | Manually capture a solution |
+| `/memory review-pending` | Review auto-extracted candidates |
+| `/memory forget <id>` | Soft-delete a memory entry |
+| `/memory stats` | Show memory counts by language, tag, project |
+| `/memory inject` | Preview what would be injected for current context |
 
-Structured logging (Pino/structlog), Four Golden Signals, OpenTelemetry with custom spans, SLOs/SLIs/error budgets, alerting rules, and correlation ID propagation.
+**When to invoke:** Start of a new session on a recurring problem type, after solving a hard problem worth preserving.
 
 ---
 
-## Language Pattern Skills
-
-| Command | What it loads |
-|---------|--------------|
-| `/typescript-patterns` | TypeScript + React + Next.js best practices |
-| `/python-patterns` | Python — PEP 8, type hints, async |
-| `/golang-patterns` | Go — idiomatic patterns, concurrency |
-| `/rust-patterns` | Rust — ownership, error handling, async |
-| `/java-patterns` | Java + Spring Boot patterns |
-| `/kotlin-patterns` | Kotlin + Coroutines + Compose |
-| `/cpp-patterns` | Modern C++ — RAII, smart pointers, templates |
-| `/postgres-patterns` | PostgreSQL — queries, indexes, schema |
-| `/docker-patterns` | Container patterns, multi-stage builds |
-| `/coding-standards` | Universal baseline — works any language |
+### `intent-routing`
+**Skill file:** `skills/intent-routing/SKILL.md`
+
+Documents the intent routing system. Explains the 10 priority tiers, how trigger patterns are evaluated, how to add new routing rules, and when NOT to route. Reference for contributors building new agents.
 
 ---
 
-## Testing Skills
+### `agent-handoff`
+**Skill file:** `skills/agent-handoff/SKILL.md`
+
+Standard multi-agent chain protocol. Documents 10 common chains:
 
-| Command | What it loads |
-|---------|--------------|
-| `/tdd-workflow` | Red-Green-Refactor, test naming, coverage |
-| `/e2e-patterns` | End-to-end test design patterns |
-| `/test-data-patterns` | Fixtures, factories, seeds |
+| Chain | Agents involved |
+|---|---|
+| New feature | planner → pair-programmer → tdd-guide → code-reviewer → security-reviewer |
+| Bug fix | debug-detective → tdd-guide → code-reviewer |
+| Refactor | refactor-cleaner → code-reviewer → tdd-guide |
+| Migration | migration-guide → tdd-guide → code-reviewer |
+| OSS prep | opensource-forker → opensource-sanitizer → opensource-packager |
+| Git crisis | git-rescue → code-reviewer |
+| Release | release-captain → security-reviewer |
+| Performance | performance-optimizer → code-reviewer |
+| API change | api-guardian → code-reviewer → security-reviewer |
+| Flaky tests | flake-hunter → tdd-guide |
 
 ---
 
-## Architecture Skills
+## Core Workflow Skills
+
+### `tdd-workflow`
+**Command:** `/tdd`
+
+Complete TDD methodology: RED → GREEN → REFACTOR → VERIFY. Framework selection per language. Test naming conventions. Coverage measurement. Integration with the `tdd-guide` agent.
+
+### `plan`
+**Command:** `/plan`
+
+Implementation planning workflow. PRD template, architecture template, task breakdown. Integration with the `planner` and `architect` agents.
+
+### `code-review`
+**Command:** `/code-review`
+
+Code review checklist and workflow. Severity levels, security triggers, when to block vs. warn. Integration with `code-reviewer` and language-specific reviewer agents.
+
+### `build-fix`
+**Command:** `/build-fix`
+
+Build error resolution workflow. Integration with `build-error-resolver` and language-specific build resolver agents.
+
+### `e2e`
+**Command:** `/e2e`
+
+End-to-end testing with Playwright. Test generation, test maintenance, quarantine workflow, artifact handling.
+
+### `git-mastery`
+**Command:** `/git-mastery`
 
-| Command | What it loads |
-|---------|--------------|
-| `/architecture-patterns` | Repository, CQRS, event sourcing |
-| `/api-design-patterns` | REST, versioning, error codes |
-| `/microservices-patterns` | Service mesh, circuit breaker, sagas |
+Git workflows. Trunk-based development vs gitflow. Interactive rebase. `git bisect`. Worktrees for parallel development. Monorepo patterns. Emergency recovery with reflog.
+
+### `observability`
+**Command:** `/observability`
+
+Structured logging (Pino for Node.js, structlog for Python). The three metric types: Counter, Gauge, Histogram. Four Golden Signals: latency, traffic, errors, saturation. OpenTelemetry with custom spans. SLOs, SLIs, error budgets. Health check endpoint patterns.
+
+---
+
+## Language Skills
+
+Each language has a dedicated skill covering coding style, testing, patterns, security, and hooks:
+
+| Skill | Languages |
+|---|---|
+| `typescript/coding-style` | TypeScript, JavaScript, React |
+| `typescript/testing` | TypeScript test patterns, Playwright |
+| `typescript/patterns` | API response format, Repository pattern, custom hooks |
+| `typescript/security` | Secret management, input validation |
+| `python/coding-style` | PEP 8, type hints, Pythonic idioms |
+| `python/testing` | pytest patterns, fixtures, mocking |
+| `python/patterns` | FastAPI patterns, async patterns |
+| `go/coding-style` | Idiomatic Go, error handling |
+| `go/testing` | Go test patterns, table-driven tests |
+| `rust/coding-style` | Ownership patterns, Result/Option usage |
+| `kotlin/coding-style` | Coroutines, Compose, clean architecture |
+| `java/coding-style` | Spring Boot patterns, JPA, async |
+
+---
+
+## Domain Skills
+
+### Security Skills
+- OWASP Top 10 checklist
+- Secret management patterns
+- Dependency CVE triage
+- Authentication patterns
+
+### Performance Skills
+- Profiling workflow
+- Memory leak detection
+- Bundle size optimization
+- Query optimization patterns
+- Core Web Vitals
+
+### Database Skills
+- Schema design patterns
+- Query optimization
+- Migration strategies
+- Supabase-specific patterns
 
 ---
 
-## Security Skills
+## Generated Skills
 
-| Command | What it loads |
-|---------|--------------|
-| `/security-checklist` | OWASP Top 10, secrets, input validation |
-| `/auth-patterns` | JWT, OAuth2, session management |
+Skills generated from your codebase or git history are stored in `~/.claude/skills/` (not the curated `skills/` directory). Generate them with:
+
+```bash
+/skill-create     → generates a skill from recent git activity
+/learn            → extracts patterns from the current session
+```
 
 ---
 
-## Skill Placement
+## Skill Placement Policy
+
+| Location | Content |
+|---|---|
+| `skills/` (repo) | Curated, versioned, high-quality skills — shipped with ECC |
+| `~/.claude/skills/` | Generated, imported, or personal skills — user's own |
+
+See `docs/SKILL-PLACEMENT-POLICY.md` for full guidelines.
+
+---
 
-- **Curated skills** live in `skills/` (committed to repo)
-- **Generated/imported skills** live in `~/.claude/skills/` (local only)
+## Invoking Any Skill
+
+```bash
+# List all available commands (which correspond to skills)
+/help
+
+# Invoke a specific skill
+/tdd
+/smart-debug
+/memory recall stripe webhook
+/observability
+/git-mastery
+```
 
-See `docs/SKILL-PLACEMENT-POLICY.md` for the full policy.
+Skills are markdown. You can read any skill file directly to understand what it teaches before invoking it.