kodelyth-ecc 1.2.2 → 1.4.0

package/agents/release-captain.md

@@ -0,0 +1,190 @@
+---
+name: release-captain
+description: >
+  Owns the release ritual end-to-end — semver decisions, changelog
+  generation, version bumping, tagging, release notes, deploy gates,
+  rollback rehearsal, and post-release verification. Catches the silly
+  mistakes that turn a routine release into a Sunday outage.
+  Use before cutting any new version, or when a release went sideways.
+tools: ["Read", "Grep", "Glob", "Bash"]
+---
+
+You are the Release Captain — the engineer who has shipped thousands of releases without a bad one. You know that the difference between a calm release and a fire is the **30 minutes of preparation no one wants to do**. You do them.
+
+## Who You Are
+
+- You believe **a release is a contract with users** — versioning, notes, and deprecations are not paperwork, they are the contract
+- You **never** let a release ship without (1) a working rollback path, (2) a smoke check, and (3) someone awake to watch
+- You read the diff before tagging — every time
+- You write changelog entries the user will actually thank you for, not autogenerated noise
+
+## Core Axiom
+
+> Releases don't fail at deploy time. They fail at planning time. We just notice at deploy time.
+
+## Pre-Release Protocol
+
+### Phase 1 — Determine the version bump
+
+Read the diff since last tag. Classify each change:
+
+| Change category | Bump |
+|---|---|
+| API / public function removed or signature changed | **MAJOR** |
+| Required config field added | **MAJOR** |
+| New feature, fully backwards-compatible | **MINOR** |
+| New optional config field | **MINOR** |
+| Bug fix, perf, doc, internal refactor | **PATCH** |
+| Security fix | **PATCH** (or backport across MINORs) |
+
+Be **strict** about MAJOR. Most teams under-call breaking changes and lose user trust.
+
+### Phase 2 — Generate the changelog
+
+Group entries by category, in this order:
+
+```markdown
+## [1.4.0] — 2026-05-06
+
+### Breaking
+- ...
+
+### Added
+- ...
+
+### Changed
+- ...
+
+### Fixed
+- ...
+
+### Security
+- ...
+
+### Deprecated
+- ...
+```
+
+Each entry: **one sentence, user perspective, link to PR or commit**. No "refactored internals". If users can't see it, it doesn't go in the changelog (move to commit history).
+
+### Phase 3 — Pre-flight checks
+
+```bash
+# 1. Working tree clean
+git status
+
+# 2. Tests pass
+<test command>
+
+# 3. Lint / type-check
+<lint command>
+
+# 4. Build artifact
+<build command>
+
+# 5. Verify built artifact runs
+<smoke check>
+
+# 6. Confirm version isn't already published
+<registry check, e.g. npm view <pkg> versions>
+```
+
+If any one fails: **stop**. Do not bump version, do not tag, do not push.
+
+### Phase 4 — Bump, tag, push
+
+```bash
+# Bump (one source of truth — package.json OR VERSION file, not both diverging)
+<bump command>
+
+# Sync sibling files
+<update VERSION, README badge, install scripts that hardcode version>
+
+# Commit
+git add -A
+git commit -m "chore: release v1.4.0"
+
+# Tag (annotated, not lightweight)
+git tag -a v1.4.0 -m "v1.4.0 — <one-line summary>"
+
+# Push commit + tag
+git push origin <branch>
+git push origin v1.4.0
+```
+
+### Phase 5 — Publish
+
+Match the registry:
+
+| Stack | Command |
+|---|---|
+| npm | `npm publish --access public --otp <code>` |
+| PyPI | `python -m build && twine upload dist/*` |
+| crates.io | `cargo publish` |
+| Maven Central | `./gradlew publish` |
+| Homebrew tap | update formula → push tap repo |
+| GitHub Release | `gh release create v1.4.0 -F CHANGELOG.md` |
+
+### Phase 6 — Post-release verification
+
+```bash
+# 1. Registry shows new version
+<registry check>
+
+# 2. Fresh install works (clean machine, ideally CI)
+<install command in clean env>
+
+# 3. Smoke test the install
+<smoke command>
+
+# 4. Tagged build matches what was published (sha or digest comparison)
+```
+
+### Phase 7 — Document the rollback
+
+Even if the release is clean, write down **how to undo it** before you stop watching:
+
+```
+ROLLBACK PLAN — v1.4.0
+======================
+If 1.4.0 misbehaves:
+  npm install <pkg>@1.3.x
+  Server: redeploy git tag v1.3.x
+  DB: no migrations in this release, no rollback needed there
+
+Remove broken version from registry (last resort, time-limited):
+  npm deprecate <pkg>@1.4.0 "rolled back due to <reason>"
+```
+
+## Operating Rules
+
+- Never publish from a dirty working tree
+- Never publish without a tag — and never push tags before commits
+- Never bump major and ship in the same hour — give it sleep time
+- Never publish on Friday afternoons or before holidays unless it's a security fix
+- Never let "a small extra change" sneak in between the bump commit and the tag
+- Always make the changelog the **user's first read after upgrading**
+
+## Output Format
+
+```
+→ Release Captain on the bridge.
+
+Current version:   1.3.0
+Proposed version:  1.3.1 (PATCH)
+Reason:            6 fixes, 0 breaking changes, 0 new features
+Risk:              LOW
+
+Pre-flight checklist:
+  [ ] Tests passing
+  [ ] Build clean
+  [ ] CHANGELOG drafted
+  [ ] Version bumped in <files>
+  [ ] Tag prepared
+
+Rollback plan:     <one line>
+
+Ready? (y/N)
+```
+
+You ship calm releases. You leave a paper trail. The next on-call will thank you.

package/bin/kodelyth-ecc.js

@@ -1,13 +1,16 @@
 #!/usr/bin/env node
 // Kodelyth ECC — npx entry point
-// Usage:
-//   npx github:sifxprime/kodelyth-ecc                           # Claude Code (default)
-//   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
+// Usage (from npm — recommended):
+//   npx kodelyth-ecc                            # Claude Code (default)
+//   npx kodelyth-ecc --target windsurf-project  # Windsurf (project)
+//   npx kodelyth-ecc --target windsurf-home     # Windsurf (global)
+//   npx kodelyth-ecc --target antigravity       # Google Antigravity
+//   npx kodelyth-ecc --target cursor-project    # Cursor IDE
+//   npx kodelyth-ecc --target codex-home        # Codex CLI
+//   npx kodelyth-ecc --target opencode          # OpenCode
+//
+// Usage (from GitHub — latest commit):
+//   npx github:sifxprime/kodelyth-ecc
 
 'use strict';
 
@@ -26,7 +29,7 @@ if (args.includes('--help') || args.includes('-h')) {
   Kodelyth ECC — AI Coding Toolkit installer
 
   Usage:
-    npx github:sifxprime/kodelyth-ecc [--target TARGET] [--profile PROFILE] [languages...]
+    npx kodelyth-ecc [--target TARGET] [--profile PROFILE] [languages...]
 
   Targets:
     claude-home          Claude Code — global install (default)
@@ -38,10 +41,13 @@ if (args.includes('--help') || args.includes('-h')) {
     opencode             OpenCode — project install (.opencode/)
 
   Examples:
+    npx kodelyth-ecc
+    npx kodelyth-ecc --target windsurf-project
+    npx kodelyth-ecc --target antigravity --profile nextjs
+    npx kodelyth-ecc --target claude-home typescript python
+
+    # Always-latest unreleased commit:
     npx github:sifxprime/kodelyth-ecc
-    npx github:sifxprime/kodelyth-ecc --target windsurf-project
-    npx github:sifxprime/kodelyth-ecc --target antigravity --profile nextjs
-    npx github:sifxprime/kodelyth-ecc --target claude-home typescript python
 
   Flags:
     --help, -h       Show this help

package/commands/memory.md

@@ -0,0 +1,62 @@
+---
+description: Manage local Kodelyth Memory — recall, capture, review, and curate what your AI knows about you
+---
+
+# /memory
+
+Local self-learning memory. Everything stays on this machine.
+
+## Subcommands
+
+### `/memory`
+Show storage stats and the 5 most recent memories for this project.
+
+### `/memory recall <query>`
+Search memory for `<query>` using BM25 keyword + tag retrieval. Surfaces the top 5 relevant matches.
+
+Example:
+```
+/memory recall stripe webhook signature
+```
+
+### `/memory remember "<title>"`
+Capture a new memory. The agent will:
+1. Ask for the approach (what worked) and any gotchas
+2. Auto-extract tags and language from the conversation
+3. Show you the proposed memory
+4. Store only after you confirm
+
+### `/memory review-pending`
+Show the queue of candidate memories extracted automatically by the Stop hook from your last session. Confirm each one to store, or skip.
+
+### `/memory forget <id>`
+Mark a memory deleted. It's a soft-delete (the row stays in the log marked `deleted: true`) so you can recover it by editing `~/.kodelyth/memory/memories.jsonl`.
+
+### `/memory list`
+Show all stored memories — id, date, language, problem, tags.
+
+### `/memory rebuild`
+Rebuild the BM25 index from `memories.jsonl`. Run this if search results look stale or if you've manually edited the log.
+
+### `/memory inject [--query <text>]`
+Print the cache-friendly context block that the SessionStart hook would inject. Useful for debugging what your AI sees about you.
+
+## Implementation
+
+This command delegates to:
+```bash
+node ~/.claude/scripts/memory/cli.js <subcommand> [args]
+```
+
+Or invoke the agent directly:
+```
+use kodelyth-memory
+```
+
+## Storage location
+
+`~/.kodelyth/memory/` (override with `KODELYTH_MEMORY_DIR` env var)
+
+- `memories.jsonl` — the source of truth
+- `index.json` — BM25 inverted index
+- `pending-review.jsonl` — Stop-hook candidates awaiting confirmation

package/hooks/hooks.json

@@ -163,6 +163,19 @@
         ],
         "description": "Load previous context and detect package manager on new session",
         "id": "session:start"
+      },
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/memory/inject-start.js\"",
+            "async": true,
+            "timeout": 5
+          }
+        ],
+        "description": "Kodelyth Memory: inject relevant past memories as cache-friendly context",
+        "id": "kodelyth:session:start:memory-inject"
       }
     ],
     "PostToolUse": [
@@ -325,6 +338,19 @@
         "description": "Kodelyth: Suggest the next logical agent or command after each response based on what just happened",
         "id": "kodelyth:stop:smart-suggest"
       },
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "node \"${CLAUDE_PLUGIN_ROOT}/hooks/memory/capture-stop.js\"",
+            "async": true,
+            "timeout": 10
+          }
+        ],
+        "description": "Kodelyth Memory: extract memory candidates from session and queue for review (never auto-stores)",
+        "id": "kodelyth:stop:memory-capture"
+      },
       {
         "matcher": "*",
         "hooks": [

package/hooks/memory/capture-stop.js

@@ -0,0 +1,88 @@
+#!/usr/bin/env node
+// =============================================================================
+// Kodelyth ECC — Memory Capture Hook (Stop)
+//
+// Runs at the end of a Claude Code session. Locates the session JSONL,
+// extracts memory candidates, writes them to a review queue at:
+//   ~/.kodelyth/memory/pending-review.jsonl
+//
+// Candidates are NEVER auto-stored. The user reviews via:
+//   /memory review-pending
+// or:
+//   node scripts/memory/cli.js list-pending
+// =============================================================================
+
+'use strict';
+
+const fs   = require('fs');
+const os   = require('os');
+const path = require('path');
+
+let payload = '';
+process.stdin.setEncoding('utf8');
+process.stdin.on('data', chunk => { payload += chunk; });
+process.stdin.on('end', main);
+setTimeout(() => { if (!process.stdin.readableEnded) main(); }, 100);
+
+function main() {
+  try {
+    const data = payload ? JSON.parse(payload) : {};
+    const sessionJsonl = data.session_path
+      || data.transcript_path
+      || findLatestClaudeSession(data.cwd || process.cwd());
+
+    if (!sessionJsonl || !fs.existsSync(sessionJsonl)) {
+      process.exit(0);
+    }
+
+    const { extractCandidates } = require(path.join(__dirname, '..', '..', 'scripts', 'memory', 'extract'));
+    const candidates = extractCandidates(sessionJsonl);
+    if (candidates.length === 0) {
+      process.exit(0);
+    }
+
+    const dir = process.env.KODELYTH_MEMORY_DIR
+      || path.join(os.homedir(), '.kodelyth', 'memory');
+    if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+
+    const queueFile = path.join(dir, 'pending-review.jsonl');
+    const sessionId = data.session_id || path.basename(sessionJsonl, '.jsonl');
+
+    const lines = candidates.map(c => JSON.stringify({
+      ...c,
+      session_id: sessionId,
+      project_path: data.cwd || process.cwd(),
+      queued_at: new Date().toISOString(),
+    }));
+
+    fs.appendFileSync(queueFile, lines.join('\n') + '\n');
+
+    // Emit advisory message so user sees something happened
+    process.stdout.write(JSON.stringify({
+      message: `Kodelyth Memory: ${candidates.length} candidate(s) queued for review. Run "/memory review-pending" to confirm.`,
+    }));
+    process.exit(0);
+  } catch (err) {
+    process.stderr.write(`kodelyth-memory capture: ${err.message}\n`);
+    process.exit(0);
+  }
+}
+
+function findLatestClaudeSession(cwd) {
+  try {
+    const projectsDir = path.join(os.homedir(), '.claude', 'projects');
+    if (!fs.existsSync(projectsDir)) return null;
+    // Project dirs are encoded paths
+    const encoded = '-' + cwd.replace(/\//g, '-');
+    const matches = fs.readdirSync(projectsDir).filter(d => d.endsWith(encoded.slice(-30)));
+    if (matches.length === 0) return null;
+    const projectDir = path.join(projectsDir, matches[0]);
+    const sessions = fs.readdirSync(projectDir)
+      .filter(f => f.endsWith('.jsonl'))
+      .map(f => ({ f, mtime: fs.statSync(path.join(projectDir, f)).mtimeMs }))
+      .sort((a, b) => b.mtime - a.mtime);
+    return sessions[0] ? path.join(projectDir, sessions[0].f) : null;
+  } catch {
+    return null;
+  }
+}

package/hooks/memory/inject-start.js

@@ -0,0 +1,60 @@
+#!/usr/bin/env node
+// =============================================================================
+// Kodelyth ECC — Memory Inject Hook (SessionStart)
+//
+// Runs at the start of every Claude Code session. Reads the project root
+// from the hook payload (or cwd fallback), builds the memory context block,
+// and emits it as additional system context.
+//
+// Hook contract: prints JSON to stdout that Claude Code will merge into
+// the session's system context. Exits 0 even on error — never block a
+// session because memory is unavailable.
+// =============================================================================
+
+'use strict';
+
+const path = require('path');
+
+let payload = {};
+try {
+  let raw = '';
+  process.stdin.setEncoding('utf8');
+  process.stdin.on('data', chunk => { raw += chunk; });
+  process.stdin.on('end', () => {
+    try { payload = raw ? JSON.parse(raw) : {}; } catch { payload = {}; }
+    main();
+  });
+  // Fallback: if stdin closes immediately (no piped input), proceed
+  setTimeout(() => { if (!process.stdin.readableEnded) main(); }, 100);
+} catch {
+  main();
+}
+
+function main() {
+  try {
+    const projectRoot = payload.cwd || payload.project_root || process.cwd();
+    const { buildContextBlock } = require(path.join(__dirname, '..', '..', 'scripts', 'memory', 'inject'));
+
+    const block = buildContextBlock({ projectRoot });
+    if (!block || !block.text) {
+      process.exit(0);
+    }
+
+    // Emit as additional context — non-blocking, advisory
+    const output = {
+      additionalContext: block.text,
+      meta: {
+        source: 'kodelyth-memory',
+        memoryCount: block.memoryCount,
+        projectMemoryCount: block.projectMemoryCount,
+        patternCount: block.patternCount,
+      },
+    };
+    process.stdout.write(JSON.stringify(output));
+    process.exit(0);
+  } catch (err) {
+    // Never crash a session because memory hook failed — log to stderr and continue
+    process.stderr.write(`kodelyth-memory inject: ${err.message}\n`);
+    process.exit(0);
+  }
+}

package/install.ps1

@@ -21,7 +21,7 @@ $ErrorActionPreference = "Stop"
 # ── Banner ────────────────────────────────────────────────────────────────────
 Write-Host ""
 Write-Host "  Kodelyth ECC — Production-grade AI coding agent toolkit" -ForegroundColor Cyan
-Write-Host "  53 agents · 185 skills · 79 commands · 18+ hooks" -ForegroundColor Gray
+Write-Host "  59 agents · 188 skills · 80 commands · 18+ hooks · intent routing · local memory" -ForegroundColor Gray
 Write-Host ""
 
 $ScriptDir = Split-Path -Parent $MyInvocation.MyCommand.Path
@@ -131,8 +131,8 @@ Write-Host "Installing components..." -ForegroundColor Bold
 
 switch ($Target) {
     "claude-home" {
-        Install-Dir  "$ScriptDir\agents"   $AgentsDest   "Agents   (53)"
-        Install-Dir  "$ScriptDir\skills"   $SkillsDest   "Skills   (185)"
+        Install-Dir  "$ScriptDir\agents"   $AgentsDest   "Agents   (58)"
+        Install-Dir  "$ScriptDir\skills"   $SkillsDest   "Skills   (187)"
         Install-Dir  "$ScriptDir\commands" $CommandsDest "Commands (79)"
 
         # Hooks
@@ -162,8 +162,8 @@ switch ($Target) {
         Write-Host "  [OK] CLAUDE.md + SOUL.md" -ForegroundColor Green
     }
     { $_ -in "windsurf-project","windsurf-home" } {
-        Install-Dir  "$ScriptDir\agents"   $AgentsDest "Agents   (53)"
-        Install-Dir  "$ScriptDir\skills"   $SkillsDest "Skills   (185)"
+        Install-Dir  "$ScriptDir\agents"   $AgentsDest "Agents   (58)"
+        Install-Dir  "$ScriptDir\skills"   $SkillsDest "Skills   (187)"
         Install-Flat "$ScriptDir\rules"    $RulesDest  "Rules"
 
         # Generate .windsurfrules from all common rules
@@ -176,17 +176,17 @@ switch ($Target) {
         }
     }
     "antigravity" {
-        Install-Dir  "$ScriptDir\agents"   $AgentsDest   "Agents -> skills (53)"
+        Install-Dir  "$ScriptDir\agents"   $AgentsDest   "Agents -> skills (58)"
         Install-Dir  "$ScriptDir\commands" $CommandsDest "Commands -> workflows (79)"
         Install-Flat "$ScriptDir\rules"    $RulesDest    "Rules"
     }
     "cursor-project" {
         Install-Flat "$ScriptDir\rules"    $RulesDest  "Rules"
-        Install-Dir  "$ScriptDir\skills"   $SkillsDest "Skills (185)"
+        Install-Dir  "$ScriptDir\skills"   $SkillsDest "Skills (187)"
     }
     "codex-home" {
-        Install-Dir  "$ScriptDir\agents"   $AgentsDest   "Agents   (53)"
-        Install-Dir  "$ScriptDir\skills"   $SkillsDest   "Skills   (185)"
+        Install-Dir  "$ScriptDir\agents"   $AgentsDest   "Agents   (58)"
+        Install-Dir  "$ScriptDir\skills"   $SkillsDest   "Skills   (187)"
         Install-Dir  "$ScriptDir\commands" $CommandsDest "Commands (79)"
         Install-Flat "$ScriptDir\rules"    $RulesDest    "Rules"
     }
@@ -219,11 +219,30 @@ switch ($Target) {
         Write-Host "  2. Type: /kodelyth-quickstart"
         Write-Host "  3. Or:   use kodelyth-advisor"
     }
+    { $_ -in "windsurf-project","windsurf-home" } {
+        Write-Host "  1. Open the project in Windsurf"
+        Write-Host "  2. Cascade auto-loads .windsurfrules on every session"
+        Write-Host "  3. Try:  use kodelyth-advisor"
+    }
+    "cursor-project" {
+        Write-Host "  1. Open the project in Cursor"
+        Write-Host "  2. Rules and skills are now active in chat"
+        Write-Host "  3. Try:  use kodelyth-advisor"
+    }
+    "codex-home" {
+        Write-Host "  1. Restart Codex CLI (codex)"
+        Write-Host "  2. All 59 agents and 188 skills are now available"
+        Write-Host "  3. Try:  use kodelyth-advisor"
+    }
     "antigravity" {
         Write-Host "  1. Open your project in Antigravity"
         Write-Host "  2. Agents are available as Skills"
         Write-Host "  3. Commands are available as Workflows"
     }
+    "opencode" {
+        Write-Host "  1. Open the project in OpenCode"
+        Write-Host "  2. Rules in .opencode/rules/ are now loaded"
+    }
     default {
         Write-Host "  1. Restart your AI coding agent"
         Write-Host "  2. Agents, skills, and rules are now active"