kodelyth-ecc 1.4.0 → 1.5.0

package/wiki/Hook-Reference.md

@@ -1,101 +1,196 @@
 # Hook Reference
 
-Hooks run automatically in the background after install. Zero configuration required.
+Hooks run automatically in the background. Zero configuration required after install.
 
 ---
 
-## How Hooks Work
-
-Hooks are lifecycle triggers that fire before or after Claude Code actions:
+## Hook Types
 
 | Type | When it fires |
-|------|--------------|
-| `PreToolUse` | Before a tool executes |
+|---|---|
+| `SessionStart` | At the beginning of every AI session |
+| `UserPromptSubmit` | Before the AI processes each message you type |
+| `PreToolUse` | Before a tool (Bash, Edit, Write, etc.) executes |
 | `PostToolUse` | After a tool executes |
-| `Stop` | When the session ends |
+| `Stop` | When the AI session ends |
+
+---
+
+## Memory Hooks (v1.4.0+)
+
+These three hooks form the self-learning memory system. All are async, non-blocking, and exit 0 on any error.
+
+### `hooks/memory/inject-start.js`
 
-Hooks never block the user — they run async and notify when relevant.
+**Type:** SessionStart  
+**Hook ID:** `kodelyth:session:start:memory-inject`
+
+Fires at the start of every session. Reads the session's working directory, searches your memory store for relevant past solutions, and injects them as `additionalContext` into the session before the first prompt.
+
+**What it injects:**
+- Your recent patterns and tag associations
+- Recent project-specific memories (last 3)
+- Query-relevant memories (scored by BM25, top 5)
+
+**Structure:** Stable prefix (patterns + recent project mems) → variable suffix (query-relevant). The stable prefix is designed to hit Anthropic's 5-minute prompt cache.
+
+**Behavior on empty memory:** Outputs nothing — doesn't inject an empty block.
 
 ---
 
-## Core Hooks (always active)
+### `hooks/memory/auto-recall.js`
+
+**Type:** UserPromptSubmit  
+**Hook ID:** `kodelyth:user-prompt:memory-auto-recall`
+
+Fires before the AI processes each message you type (Claude Code only — other platforms don't currently expose a `UserPromptSubmit` hook).
 
-| Hook | Trigger | What it does |
-|------|---------|-------------|
-| Session start | Session begins | Loads context from previous session |
-| Pre-commit | `git commit` | Catches `console.log`, secrets, bad commit messages |
-| Quality gate | After any file edit | Runs type checks + formatting |
-| Git push reminder | Before `git push` | Prompts for review |
-| Config protection | Config file edits | Blocks weakening linter/formatter settings |
-| Cost tracker | End of session | Logs token usage per session |
-| Desktop notify | Long task completes | macOS notification when Claude finishes |
-| MCP health check | Before MCP call | Validates MCP servers are reachable |
+**Smart skip filters:**
+- Empty prompt → skip
+- Trivial responses (`ok`, `yes`, `no`, `thanks`, `cool`, `done`, `great`, `got it`, `sure`, `k`) → skip
+- Agent/command invocations (`use X`, `@agent`, `/command`, `invoke X`) → skip
+- Prompts under 12 characters → skip
+- Fewer than 2 meaningful tokens after stop-word removal → skip
+
+**Repeat suppression:** Tracks which memory IDs were surfaced in the current session (`session-surfaced-<sessionId>.json`). Never surfaces the same memory twice in one session.
+
+**Threshold:** `MIN_SCORE = 1.0` (higher than session-start inject — auto-recall is selective).
+
+**Output format:** JSON with `additionalContext` (markdown block) and `meta` (source, session ID, recalled count).
 
 ---
 
-## Kodelyth Hooks (v1.1.0)
+### `hooks/memory/capture-stop.js`
 
-### `test-reminder`
+**Type:** Stop  
+**Hook ID:** `kodelyth:stop:memory-capture`
 
-**Trigger:** After any code file is edited without touching a test file
+Fires when the session ends. Finds the latest Claude session JSONL file, runs the heuristic extractor (`scripts/memory/extract.js`) over it, and writes learning candidates to `~/.kodelyth/memory/pending-review.jsonl`.
 
-**What it does:** Flags that tests may need to be written or updated
+**Important:** This hook NEVER auto-stores anything. It only extracts candidates. You review and confirm before anything enters the memory store.
 
+**What it extracts:** Looks for message pairs where the AI used `SUCCESS_PHRASES` (worked, fixed, resolved, solved) and `FAILURE_PHRASES` (failed, broken, error, doesn't work), plus explicit problem/solution structure. Scores candidates on length, specificity, and context quality.
+
+**Advisory output:** Prints a message to stderr like:
 ```
-[test-reminder] Code edited but no test file was touched.
-Consider: Does this change need test coverage?
+[kodelyth-memory] 2 learning candidate(s) pending review. Run /memory review-pending.
 ```
 
 ---
 
-### `smart-suggest`
+## Quality Gate Hooks (v1.1.0+)
+
+### `hooks/test-reminder`
+
+**Type:** PostToolUse — Edit, Write, MultiEdit  
+**Hook ID:** `kodelyth:post-tool:edit:test-reminder`
 
-**Trigger:** After each Claude Code response
+After editing a code file, checks if a corresponding test file was also touched in the session. If not, posts a non-blocking reminder box to stderr.
 
-**What it does:** Detects signals in the session and suggests the next logical agent
+**Language coverage:** `.ts`, `.tsx`, `.js`, `.jsx`, `.py`, `.go`, `.rs`, `.java`, `.rb`, `.php`
 
-Examples:
-- Sees a bug → suggests `debug-detective`
-- Sees API changes → suggests `api-guardian`
-- Sees frontend code → suggests `ux-reviewer`
-- Sees security-sensitive code → suggests `security-reviewer`
+**Timeout:** 5 seconds (async, never delays tool execution)
+
+**Disable:**
+```bash
+export ECC_DISABLED_HOOKS=kodelyth:test-reminder
+```
 
 ---
 
-### `branch-name-check`
+### `hooks/smart-suggest`
+
+**Type:** Stop  
+**Hook ID:** `kodelyth:stop:smart-suggest`
 
-**Trigger:** Before `git checkout -b` (creating a new branch)
+After each AI response, analyzes session signals and suggests the next logical agent. Eight detection rules:
 
-**What it does:** Blocks branches that don't follow the naming convention
+| Signal | Suggestion |
+|---|---|
+| Error keywords in response | → debug-detective |
+| "Looks good" / approval phrases | → code-reviewer |
+| Migration or upgrade terms | → migration-guide |
+| API endpoint changes | → api-guardian |
+| Performance concerns | → performance-optimizer |
+| Test failures | → tdd-guide |
+| Security-sensitive code | → security-reviewer |
+| Git operation just completed | → code-reviewer |
 
-**Valid patterns:**
+**Output:** Non-blocking advisory to stderr. Never interrupts the session.
+
+**Disable:**
+```bash
+export ECC_DISABLED_HOOKS=kodelyth:smart-suggest
 ```
-feat/add-user-auth
-fix/login-redirect-loop
+
+---
+
+### `hooks/branch-name-check`
+
+**Type:** PreToolUse — Bash  
+**Hook ID:** `kodelyth:pre-tool:bash:branch-name`
+
+Intercepts `git checkout -b` and `git switch -c` commands. Validates the branch name against:
+
+```
+^(feat|fix|chore|docs|refactor|test|perf|ci|hotfix|release|experiment|spike|wip)\/[a-z0-9][a-z0-9-._/]{1,60}$
+```
+
+Valid examples:
+```
+feat/add-stripe-webhooks
+fix/auth-token-expiry
 chore/update-dependencies
 refactor/extract-payment-service
-docs/api-reference-update
-test/coverage-auth-module
 ```
 
-**Blocked patterns:**
-```
-my-branch
-update
-wip
-temp123
-NEW_FEATURE
+**On violation:** Blocks with exit code 2, clear explanation, and valid examples shown.
+
+**Disable:**
+```bash
+export ECC_DISABLED_HOOKS=kodelyth:branch-name
 ```
 
 ---
 
-## Hook File Location
+## Hook Configuration
 
-After install:
+All hooks are registered in `~/.claude/hooks/hooks.json`. After install, it contains entries for all three memory hooks plus the quality gate hooks.
 
+**View registered hooks:**
+```bash
+cat ~/.claude/hooks/hooks.json
 ```
-~/.claude/hooks/hooks.json     ← Claude Code
-.agent/rules/                  ← Google Antigravity (rules-based, no hook engine)
+
+**Disable multiple hooks:**
+```bash
+export ECC_DISABLED_HOOKS=kodelyth:smart-suggest,kodelyth:test-reminder,kodelyth:branch-name
 ```
 
-Note: Google Antigravity does not have a hook execution engine. Hook behavior for Antigravity is approximated via always-on rules in `.agent/rules/kodelyth-always-on.md`.
+**Disable all ECC hooks:**
+```bash
+export ECC_DISABLED_HOOKS=kodelyth:all
+```
+
+---
+
+## Hook Safety Design
+
+All ECC hooks follow these rules:
+
+1. **Always exit 0** — hooks never block a session or tool execution due to an error
+2. **Timeout 5 seconds** — hooks that take longer are killed
+3. **Async only** — hooks run in background, never synchronously blocking tool execution
+4. **Stderr for advisories** — hook output goes to stderr, never stdout (which the AI reads)
+5. **Stdin for context** — hooks receive session context as JSON on stdin
+6. **No auto-modification** — hooks never modify files without explicit user confirmation
+
+---
+
+## Writing Custom Hooks
+
+Hook ID naming convention: `kodelyth:{phase}:{matcher}:{name}`
+
+Example phases: `session`, `user-prompt`, `pre-tool`, `post-tool`, `stop`
+
+See [CONTRIBUTING.md](https://github.com/sifxprime/kodelyth-ecc/blob/main/CONTRIBUTING.md) for the hook script template and all safety requirements.

package/wiki/Installation-Guide.md

@@ -2,125 +2,206 @@
 
 ---
 
-## Claude Code
+## Requirements
 
-### macOS / Linux (one-liner)
+- **Node.js 18+** (all install methods except manual git clone)
+- Any supported AI coding platform (see [Platform Support](Platform-Support))
+
+---
+
+## Method 1 — npx (Recommended)
+
+Runs from anywhere. No clone required.
 
 ```bash
-curl -fsSL https://raw.githubusercontent.com/sifxprime/kodelyth-ecc/main/install.sh | bash
+npx kodelyth-ecc
 ```
 
-### Or clone and install manually
+**With a specific target:**
 
 ```bash
-git clone https://github.com/sifxprime/kodelyth-ecc.git
-cd kodelyth-ecc
-./install.sh
+npx kodelyth-ecc --target windsurf-project
+npx kodelyth-ecc --target cursor-project
+npx kodelyth-ecc --target antigravity
 ```
 
-### Windows (PowerShell)
+**With a language profile:**
 
-```powershell
-git clone https://github.com/sifxprime/kodelyth-ecc.git
-cd kodelyth-ecc
-.\install.ps1
+```bash
+npx kodelyth-ecc --profile nextjs
+npx kodelyth-ecc --profile fullstack --target claude-home
 ```
 
-When complete, you will see:
+---
+
+## Method 2 — curl (macOS / Linux)
 
-```
-ARMED AND OPERATIONAL.
+```bash
+curl -fsSL https://raw.githubusercontent.com/sifxprime/kodelyth-ecc/main/install.sh | bash
 ```
 
-Agents are now available globally in every Claude Code session.
+**With options:**
+
+```bash
+curl -fsSL https://raw.githubusercontent.com/sifxprime/kodelyth-ecc/main/install.sh | bash -s -- --target windsurf-home
+curl -fsSL https://raw.githubusercontent.com/sifxprime/kodelyth-ecc/main/install.sh | bash -s -- --profile python-api
+```
 
 ---
 
-## Google Antigravity
+## Method 3 — PowerShell (Windows)
 
-```bash
-git clone https://github.com/sifxprime/kodelyth-ecc.git
-cd kodelyth-ecc
-./install.sh --target antigravity
+```powershell
+irm https://raw.githubusercontent.com/sifxprime/kodelyth-ecc/main/install.ps1 | iex
 ```
 
-This installs everything into your project's `.agent/` directory:
+**With options:**
 
+```powershell
+& ([scriptblock]::Create((irm https://raw.githubusercontent.com/sifxprime/kodelyth-ecc/main/install.ps1))) --target windsurf-project
 ```
-your-project/
-└── .agent/
-    ├── rules/       ← coding standards + always-on ECC behavior
-    ├── workflows/   ← 79 slash commands
-    └── skills/      ← all 53 agents
+
+---
+
+## Method 4 — GitHub (no npm registry)
+
+```bash
+npx github:sifxprime/kodelyth-ecc
 ```
 
-The file `.agent/rules/kodelyth-always-on.md` loads ECC behavior automatically every session — no prompt required.
+Use this if you prefer to pull directly from the repository without going through npm.
 
 ---
 
-## Other Platforms
+## Install Targets
+
+| Target | Installs to | Platform |
+|---|---|---|
+| `claude-home` | `~/.claude/` | Claude Code (global) |
+| `antigravity` | `~/.config/google-gemini/` | Google Antigravity |
+| `windsurf-project` | `.windsurf/` + `.windsurfrules` | Windsurf (project) |
+| `windsurf-home` | `~/.codeium/windsurf/` | Windsurf (global) |
+| `cursor-project` | `.cursor/` | Cursor (project) |
+| `codex-home` | `~/.codex/` | Codex CLI |
+| `opencode` | `~/.opencode/` | OpenCode |
 
-| Platform | Command |
-|----------|---------|
-| Cursor | `./install.sh --target cursor-project` |
-| Codex CLI | `./install.sh --target codex-home` |
-| OpenCode | `./install.sh --target opencode` |
+If you don't specify `--target`, the installer detects your platform and asks.
 
 ---
 
-## Install Profiles (Language Bundles)
+## Install Profiles
 
-Pre-built rule bundles for common stacks:
+Profiles add language-specific rule modules on top of the base install.
+
+| Profile | Languages added |
+|---|---|
+| `--profile nextjs` | TypeScript |
+| `--profile python-api` | Python |
+| `--profile fullstack` | TypeScript + Python + Go |
+| `--profile mobile` | Kotlin + Swift |
+| `--profile backend` | Go + Python + Java |
+
+---
+
+## What the Installer Does
+
+1. Detects or accepts target platform
+2. Creates target directory if it doesn't exist
+3. Copies agents, skills, commands, hooks, and rules
+4. Sets up memory hook entries in `hooks.json`
+5. Installs language modules if `--profile` is set
+6. Writes install state to `kodelyth-ecc-install-state.json`
+7. Prints confirmation with component counts
+
+---
+
+## After Install — Claude Code
+
+Verify the install:
+
+```bash
+ls ~/.claude/agents/ | wc -l         # should be 59+
+ls ~/.claude/hooks/memory/            # should show 3 hook files
+cat ~/.claude/hooks/hooks.json        # verify memory hooks are registered
+```
+
+Run tests:
 
 ```bash
-./install.sh --profile nextjs      # TypeScript + React + Next.js
-./install.sh --profile python-api  # Python + Django/FastAPI
-./install.sh --profile fullstack   # TypeScript + Python + Go
-./install.sh --profile mobile      # Kotlin + Swift
-./install.sh --profile backend     # Go + Python + Java
+cd /path/to/kodelyth-ecc && npm test  # 47 tests, all passing
 ```
 
 ---
 
-## After Install — First Steps
+## After Install — Windsurf
 
-### Claude Code
+For `windsurf-project`, a `.windsurfrules` file is generated in the current directory. Cascade loads this file automatically.
+
+For `windsurf-home`, rules are installed globally and apply to all projects.
+
+---
+
+## After Install — Antigravity
+
+Rules are flattened (no subdirectories) to match Antigravity's required format. The `.agent/` layout is generated:
 
 ```
-/kodelyth-quickstart
+.agent/rules/       → 16 rule files (flattened)
+.agent/workflows/   → 80 command workflows
+.agent/skills/      → 59 agent definitions
 ```
 
-This loads the plain-language getting-started guide.
+---
 
-### Google Antigravity
+## Memory System Setup
 
-Type in any project:
+The memory system activates automatically after install. On first session:
 
+1. `inject-start.js` runs but finds no memories yet — that's fine
+2. You do your work
+3. `capture-stop.js` runs at session end and extracts candidates to `~/.kodelyth/memory/pending-review.jsonl`
+4. Review candidates: `/memory review-pending` or `node scripts/memory/cli.js list`
+5. Confirm what to store: `/memory remember "title" --approach "..." --tags tag1,tag2`
+6. Future sessions inject and auto-recall what you stored
+
+**Override memory location:**
+
+```bash
+export KODELYTH_MEMORY_DIR=/path/to/your/memory
 ```
-/kodelyth-quickstart
-```
 
-Or just start working — kodelyth-always-on.md auto-loads ECC behavior every session.
+---
+
+## Updating
+
+Re-run the same install command. The installer is idempotent — existing files are overwritten with the latest version.
+
+```bash
+npx kodelyth-ecc@latest
+```
 
 ---
 
-## What Gets Installed
+## Uninstalling
 
-### Claude Code (`~/.claude/`)
+Remove the installed directories:
 
-| Source | Destination |
-|--------|------------|
-| `agents/` | `~/.claude/agents/` |
-| `skills/` | `~/.claude/skills/` |
-| `hooks/hooks.json` | `~/.claude/hooks/` |
-| `rules/` | `~/.claude/rules/` |
-| `commands/` | `~/.claude/commands/` |
+```bash
+# Claude Code
+rm -rf ~/.claude/agents ~/.claude/skills ~/.claude/commands ~/.claude/hooks/memory
+rm -f ~/.claude/rules/common/agent-intent-routing.md
+rm -f ~/.claude/rules/common/memory-protocol.md
 
-### Antigravity (`.agent/` in project root)
+# Memory data (separate — only remove if you want to clear memory)
+rm -rf ~/.kodelyth/memory/
+```
+
+---
+
+## CI / Non-interactive Environments
 
-| Source | Destination |
-|--------|------------|
-| `agents/` | `.agent/skills/` |
-| `commands/` | `.agent/workflows/` |
-| `rules/` | `.agent/rules/` |
-| Kodelyth skills (flattened) | `.agent/rules/` |
+The installer detects non-interactive environments (no `/dev/tty`) and auto-accepts defaults. Set `--target` explicitly to avoid prompts:
+
+```bash
+npx kodelyth-ecc --target claude-home --profile fullstack
+```