From 708c265b4f8ad8b7f2c9afe85d00073644deec17 Mon Sep 17 00:00:00 2001
From: ispaydeu <31388982+ispaydeu@users.noreply.github.com>
Date: Tue, 10 Mar 2026 20:02:53 -0400
Subject: [PATCH 01/22] fix: read tool_response field in observe.sh (#377)

Claude Code sends tool output as `tool_response` in PostToolUse hook
payloads, but observe.sh only checked for `tool_output` and `output`.
This caused all observations to have empty output fields, making the
observer pipeline blind to tool results.

Adds `tool_response` as the primary field to check, with backward-
compatible fallback to the existing `tool_output` and `output` fields.
---
 skills/continuous-learning-v2/hooks/observe.sh | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/skills/continuous-learning-v2/hooks/observe.sh b/skills/continuous-learning-v2/hooks/observe.sh
index ea44386b..653d56a3 100755
--- a/skills/continuous-learning-v2/hooks/observe.sh
+++ b/skills/continuous-learning-v2/hooks/observe.sh
@@ -124,7 +124,7 @@ try:
     # Extract fields - Claude Code hook format
     tool_name = data.get("tool_name", data.get("tool", "unknown"))
     tool_input = data.get("tool_input", data.get("input", {}))
-    tool_output = data.get("tool_output", data.get("output", ""))
+    tool_output = data.get("tool_response", data.get("tool_output", data.get("output", "")))
     session_id = data.get("session_id", "unknown")
     tool_use_id = data.get("tool_use_id", "")
     cwd = data.get("cwd", "")

From 4de776341ee553144884fcac7945d2acb194568c Mon Sep 17 00:00:00 2001
From: Affaan Mustafa <affaan@dcube.ai>
Date: Tue, 10 Mar 2026 19:14:07 -0700
Subject: [PATCH 02/22] fix: handle null tool_response fallback

---
 .../continuous-learning-v2/hooks/observe.sh   |  4 +-
 tests/hooks/hooks.test.js                     | 60 +++++++++++++++++++
 2 files changed, 63 insertions(+), 1 deletion(-)

diff --git a/skills/continuous-learning-v2/hooks/observe.sh b/skills/continuous-learning-v2/hooks/observe.sh
index 653d56a3..33ec6f04 100755
--- a/skills/continuous-learning-v2/hooks/observe.sh
+++ b/skills/continuous-learning-v2/hooks/observe.sh
@@ -124,7 +124,9 @@ try:
     # Extract fields - Claude Code hook format
     tool_name = data.get("tool_name", data.get("tool", "unknown"))
     tool_input = data.get("tool_input", data.get("input", {}))
-    tool_output = data.get("tool_response", data.get("tool_output", data.get("output", "")))
+    tool_output = data.get("tool_response")
+    if tool_output is None:
+        tool_output = data.get("tool_output", data.get("output", ""))
     session_id = data.get("session_id", "unknown")
     tool_use_id = data.get("tool_use_id", "")
     cwd = data.get("cwd", "")
diff --git a/tests/hooks/hooks.test.js b/tests/hooks/hooks.test.js
index a5ecaaa0..e13e8193 100644
--- a/tests/hooks/hooks.test.js
+++ b/tests/hooks/hooks.test.js
@@ -63,6 +63,29 @@ function runScript(scriptPath, input = '', env = {}) {
   });
 }
 
+function runShellScript(scriptPath, args = [], input = '', env = {}, cwd = process.cwd()) {
+  return new Promise((resolve, reject) => {
+    const proc = spawn('bash', [scriptPath, ...args], {
+      cwd,
+      env: { ...process.env, ...env },
+      stdio: ['pipe', 'pipe', 'pipe']
+    });
+
+    let stdout = '';
+    let stderr = '';
+
+    if (input) {
+      proc.stdin.write(input);
+    }
+    proc.stdin.end();
+
+    proc.stdout.on('data', data => stdout += data);
+    proc.stderr.on('data', data => stderr += data);
+    proc.on('close', code => resolve({ code, stdout, stderr }));
+    proc.on('error', reject);
+  });
+}
+
 // Create a temporary test directory
 function createTestDir() {
   const testDir = path.join(os.tmpdir(), `hooks-test-${Date.now()}`);
@@ -1777,6 +1800,43 @@ async function runTests() {
     assert.ok(stdout.trim().length > 0, 'CLV2_PYTHON_CMD should export a resolved interpreter path');
   })) passed++; else failed++;
 
+  if (await asyncTest('observe.sh falls back to legacy output fields when tool_response is null', async () => {
+    const homeDir = createTestDir();
+    const projectDir = createTestDir();
+    const observePath = path.join(__dirname, '..', '..', 'skills', 'continuous-learning-v2', 'hooks', 'observe.sh');
+    const payload = JSON.stringify({
+      tool_name: 'Bash',
+      tool_input: { command: 'echo hello' },
+      tool_response: null,
+      tool_output: 'legacy output',
+      session_id: 'session-123',
+      cwd: projectDir
+    });
+
+    try {
+      const result = await runShellScript(observePath, ['post'], payload, {
+        HOME: homeDir,
+        CLAUDE_PROJECT_DIR: projectDir
+      }, projectDir);
+
+      assert.strictEqual(result.code, 0, `observe.sh should exit successfully, stderr: ${result.stderr}`);
+
+      const projectsDir = path.join(homeDir, '.claude', 'homunculus', 'projects');
+      const projectIds = fs.readdirSync(projectsDir);
+      assert.strictEqual(projectIds.length, 1, 'observe.sh should create one project-scoped observation directory');
+
+      const observationsPath = path.join(projectsDir, projectIds[0], 'observations.jsonl');
+      const observations = fs.readFileSync(observationsPath, 'utf8').trim().split('\n').filter(Boolean);
+      assert.ok(observations.length > 0, 'observe.sh should append at least one observation');
+
+      const observation = JSON.parse(observations[0]);
+      assert.strictEqual(observation.output, 'legacy output', 'observe.sh should fall back to legacy tool_output when tool_response is null');
+    } finally {
+      cleanupTestDir(homeDir);
+      cleanupTestDir(projectDir);
+    }
+  })) passed++; else failed++;
+
   if (await asyncTest('matches .tsx extension for type checking', async () => {
     const testDir = createTestDir();
     const testFile = path.join(testDir, 'component.tsx');

From b7bafb40cbfd7353cfff791bed68440e9855a303 Mon Sep 17 00:00:00 2001
From: Pangerkumzuk Longkumer <73515951+pangerlkr@users.noreply.github.com>
Date: Tue, 10 Mar 2026 16:56:43 +0530
Subject: [PATCH 03/22] docs: add comprehensive troubleshooting guide (fixes
 #326)

Added a comprehensive troubleshooting guide for the Everything Claude Code (ECC) plugin, covering common issues, symptoms, causes, and solutions.
---
 TROUBLESHOOTING.md | 391 +++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 391 insertions(+)
 create mode 100644 TROUBLESHOOTING.md

diff --git a/TROUBLESHOOTING.md b/TROUBLESHOOTING.md
new file mode 100644
index 00000000..d80e00c6
--- /dev/null
+++ b/TROUBLESHOOTING.md
@@ -0,0 +1,391 @@
+# Troubleshooting Guide
+
+Common issues and solutions for Everything Claude Code (ECC) plugin.
+
+## Table of Contents
+
+- [Memory & Context Issues](#memory--context-issues)
+- [Agent Harness Failures](#agent-harness-failures)
+- [Hook & Workflow Errors](#hook--workflow-errors)
+- [Installation & Setup](#installation--setup)
+- [Performance Issues](#performance-issues)
+
+---
+
+## Memory & Context Issues
+
+### Context Window Overflow
+
+**Symptom:** "Context too long" errors or incomplete responses
+
+**Causes:**
+- Large file uploads exceeding token limits
+- Accumulated conversation history
+- Multiple large tool outputs in single session
+
+**Solutions:**
+```bash
+# 1. Clear conversation history and start fresh
+# Use Claude Code: "New Chat" or Cmd/Ctrl+Shift+N
+
+# 2. Reduce file size before analysis
+head -n 100 large-file.log > sample.log
+
+# 3. Use streaming for large outputs
+cat large-file.txt | head -50
+
+# 4. Split tasks into smaller chunks
+# Instead of: "Analyze all 50 files"
+# Use: "Analyze files in src/components/ directory"
+```
+
+### Memory Persistence Failures
+
+**Symptom:** Agent doesn't remember previous context or observations
+
+**Causes:**
+- Disabled continuous-learning hooks
+- Corrupted observation files
+- Project detection failures
+
+**Solutions:**
+```bash
+# Check if observations are being recorded
+ls ~/.claude/homunculus/*/observations.jsonl
+
+# View recent observations
+tail -20 ~/.claude/homunculus/$(basename $PWD)/observations.jsonl
+
+# Reset observations if corrupted
+rm ~/.claude/homunculus/$(basename $PWD)/observations.jsonl
+
+# Verify hooks are enabled
+grep -r "observe" ~/.claude/settings.json
+```
+
+---
+
+## Agent Harness Failures
+
+### Agent Not Found
+
+**Symptom:** "Agent not loaded" or "Unknown agent" errors
+
+**Causes:**
+- Plugin not installed correctly
+- Agent path misconfiguration
+- Marketplace vs manual install mismatch
+
+**Solutions:**
+```bash
+# Check plugin installation
+ls ~/.claude/plugins/cache/
+
+# Verify agent exists (marketplace install)
+ls ~/.claude/plugins/cache/*/agents/
+
+# For manual install, agents should be in:
+ls ~/.claude/agents/  # Custom agents only
+
+# Reload plugin
+# Claude Code → Settings → Extensions → Reload
+```
+
+### Workflow Execution Hangs
+
+**Symptom:** Agent starts but never completes
+
+**Causes:**
+- Infinite loops in agent logic
+- Blocked on user input
+- Network timeout waiting for API
+
+**Solutions:**
+```bash
+# 1. Check for stuck processes
+ps aux | grep claude
+
+# 2. Enable debug mode
+export CLAUDE_DEBUG=1
+
+# 3. Set shorter timeouts
+export CLAUDE_TIMEOUT=30
+
+# 4. Check network connectivity
+curl -I https://api.anthropic.com
+```
+
+### Tool Use Errors
+
+**Symptom:** "Tool execution failed" or permission denied
+
+**Causes:**
+- Missing dependencies (npm, python, etc.)
+- Insufficient file permissions
+- Path not found
+
+**Solutions:**
+```bash
+# Verify required tools are installed
+which node python3 npm git
+
+# Fix permissions on hook scripts
+chmod +x ~/.claude/plugins/cache/*/hooks/*.sh
+chmod +x ~/.claude/plugins/cache/*/skills/*/hooks/*.sh
+
+# Check PATH includes necessary binaries
+echo $PATH
+```
+
+---
+
+## Hook & Workflow Errors
+
+### Hooks Not Firing
+
+**Symptom:** Pre/post hooks don't execute
+
+**Causes:**
+- Hooks not registered in settings.json
+- Invalid hook syntax
+- Hook script not executable
+
+**Solutions:**
+```bash
+# Check hooks are registered
+cat ~/.claude/settings.json | grep -A 10 '"hooks"'
+
+# Verify hook files exist and are executable
+ls -la ~/.claude/plugins/cache/*/hooks/
+
+# Test hook manually
+bash ~/.claude/plugins/cache/*/hooks/pre-bash.sh <<< '{"command":"echo test"}'
+
+# Re-register hooks (if using plugin)
+# Disable and re-enable plugin in Claude Code settings
+```
+
+### Python/Node Version Mismatches
+
+**Symptom:** "python3 not found" or "node: command not found"
+
+**Causes:**
+- Missing Python/Node installation
+- PATH not configured
+- Wrong Python version (Windows)
+
+**Solutions:**
+```bash
+# Install Python 3 (if missing)
+# macOS: brew install python3
+# Ubuntu: sudo apt install python3
+# Windows: Download from python.org
+
+# Install Node.js (if missing)
+# macOS: brew install node
+# Ubuntu: sudo apt install nodejs npm
+# Windows: Download from nodejs.org
+
+# Verify installations
+python3 --version
+node --version
+npm --version
+
+# Windows: Ensure python (not python3) works
+python --version
+```
+
+### Dev Server Blocker False Positives
+
+**Symptom:** Hook blocks legitimate commands mentioning "dev"
+
+**Causes:**
+- Heredoc content triggering pattern match
+- Non-dev commands with "dev" in arguments
+
+**Solutions:**
+```bash
+# This is fixed in v1.8.0+ (PR #371)
+# Upgrade plugin to latest version
+
+# Workaround: Wrap dev servers in tmux
+tmux new-session -d -s dev "npm run dev"
+tmux attach -t dev
+
+# Disable hook temporarily if needed
+# Edit ~/.claude/settings.json and remove pre-bash hook
+```
+
+---
+
+## Installation & Setup
+
+### Plugin Not Loading
+
+**Symptom:** Plugin features unavailable after install
+
+**Causes:**
+- Marketplace cache not updated
+- Claude Code version incompatibility
+- Corrupted plugin files
+
+**Solutions:**
+```bash
+# Clear plugin cache
+rm -rf ~/.claude/plugins/cache/*
+
+# Reinstall from marketplace
+# Claude Code → Extensions → Everything Claude Code → Uninstall
+# Then reinstall from marketplace
+
+# Check Claude Code version
+claude --version
+# Requires Claude Code 2.0+
+
+# Manual install (if marketplace fails)
+git clone https://github.com/affaan-m/everything-claude-code.git
+cp -r everything-claude-code ~/.claude/plugins/ecc
+```
+
+### Package Manager Detection Fails
+
+**Symptom:** Wrong package manager used (npm instead of pnpm)
+
+**Causes:**
+- No lock file present
+- CLAUDE_PACKAGE_MANAGER not set
+- Multiple lock files confusing detection
+
+**Solutions:**
+```bash
+# Set preferred package manager globally
+export CLAUDE_PACKAGE_MANAGER=pnpm
+# Add to ~/.bashrc or ~/.zshrc
+
+# Or set per-project
+echo '{"packageManager": "pnpm"}' > .claude/package-manager.json
+
+# Or use package.json field
+npm pkg set packageManager="pnpm@8.15.0"
+
+# Remove conflicting lock files
+rm package-lock.json  # If using pnpm/yarn/bun
+```
+
+---
+
+## Performance Issues
+
+### Slow Response Times
+
+**Symptom:** Agent takes 30+ seconds to respond
+
+**Causes:**
+- Large observation files
+- Too many active hooks
+- Network latency to API
+
+**Solutions:**
+```bash
+# Archive old observations
+find ~/.claude/homunculus -name "observations.jsonl" -size +10M -delete
+
+# Disable unused hooks temporarily
+# Edit ~/.claude/settings.json
+
+# Use local caching
+# Enable Redis for semantic search caching
+```
+
+### High CPU Usage
+
+**Symptom:** Claude Code consuming 100% CPU
+
+**Causes:**
+- Infinite observation loops
+- File watching on large directories
+- Memory leaks in hooks
+
+**Solutions:**
+```bash
+# Check for runaway processes
+top -o cpu | grep claude
+
+# Disable continuous learning temporarily
+touch ~/.claude/homunculus/disabled
+
+# Restart Claude Code
+# Cmd/Ctrl+Q then reopen
+
+# Check observation file size
+du -sh ~/.claude/homunculus/*/
+```
+
+---
+
+## Common Error Messages
+
+### "EACCES: permission denied"
+
+```bash
+# Fix hook permissions
+find ~/.claude/plugins -name "*.sh" -exec chmod +x {} \;
+
+# Fix observation directory permissions
+chmod -R 755 ~/.claude/homunculus
+```
+
+### "MODULE_NOT_FOUND"
+
+```bash
+# Install plugin dependencies
+cd ~/.claude/plugins/cache/everything-claude-code
+npm install
+
+# Or for manual install
+cd ~/.claude/plugins/ecc
+npm install
+```
+
+### "spawn UNKNOWN"
+
+```bash
+# Windows-specific: Ensure scripts use correct line endings
+# Convert CRLF to LF
+find ~/.claude/plugins -name "*.sh" -exec dos2unix {} \;
+
+# Or install dos2unix
+# macOS: brew install dos2unix
+# Ubuntu: sudo apt install dos2unix
+```
+
+---
+
+## Getting Help
+
+ If you're still experiencing issues:
+
+1. **Check GitHub Issues**: [github.com/affaan-m/everything-claude-code/issues](https://github.com/affaan-m/everything-claude-code/issues)
+2. **Enable Debug Logging**:
+   ```bash
+   export CLAUDE_DEBUG=1
+   export CLAUDE_LOG_LEVEL=debug
+   ```
+3. **Collect Diagnostic Info**:
+   ```bash
+   claude --version
+   node --version
+   python3 --version
+   echo $CLAUDE_PACKAGE_MANAGER
+   ls -la ~/.claude/plugins/cache/
+   ```
+4. **Open an Issue**: Include debug logs, error messages, and diagnostic info
+
+---
+
+## Related Documentation
+
+- [README.md](./README.md) - Installation and features
+- [CONTRIBUTING.md](./CONTRIBUTING.md) - Development guidelines
+- [docs/](./docs/) - Detailed documentation
+- [examples/](./examples/) - Usage examples

From 5644415767ee692809dd3ae2f9bc929b70f16865 Mon Sep 17 00:00:00 2001
From: Affaan Mustafa <affaan@dcube.ai>
Date: Tue, 10 Mar 2026 19:14:07 -0700
Subject: [PATCH 04/22] docs: tighten troubleshooting safety guidance

---
 TROUBLESHOOTING.md | 61 ++++++++++++++++++++++++++++++++++------------
 1 file changed, 46 insertions(+), 15 deletions(-)

diff --git a/TROUBLESHOOTING.md b/TROUBLESHOOTING.md
index d80e00c6..57ffa2e4 100644
--- a/TROUBLESHOOTING.md
+++ b/TROUBLESHOOTING.md
@@ -9,6 +9,8 @@ Common issues and solutions for Everything Claude Code (ECC) plugin.
 - [Hook & Workflow Errors](#hook--workflow-errors)
 - [Installation & Setup](#installation--setup)
 - [Performance Issues](#performance-issues)
+- [Common Error Messages](#common-error-messages)
+- [Getting Help](#getting-help)
 
 ---
 
@@ -32,7 +34,7 @@ Common issues and solutions for Everything Claude Code (ECC) plugin.
 head -n 100 large-file.log > sample.log
 
 # 3. Use streaming for large outputs
-cat large-file.txt | head -50
+head -n 50 large-file.txt
 
 # 4. Split tasks into smaller chunks
 # Instead of: "Analyze all 50 files"
@@ -51,13 +53,28 @@ cat large-file.txt | head -50
 **Solutions:**
 ```bash
 # Check if observations are being recorded
-ls ~/.claude/homunculus/*/observations.jsonl
+ls ~/.claude/homunculus/projects/*/observations.jsonl
 
-# View recent observations
-tail -20 ~/.claude/homunculus/$(basename $PWD)/observations.jsonl
+# Find the current project's hash id
+python3 - <<'PY'
+import json, os
+registry_path = os.path.expanduser("~/.claude/homunculus/projects.json")
+with open(registry_path) as f:
+    registry = json.load(f)
+for project_id, meta in registry.items():
+    if meta.get("root") == os.getcwd():
+        print(project_id)
+        break
+else:
+    raise SystemExit("Project hash not found in ~/.claude/homunculus/projects.json")
+PY
 
-# Reset observations if corrupted
-rm ~/.claude/homunculus/$(basename $PWD)/observations.jsonl
+# View recent observations for that project
+tail -20 ~/.claude/homunculus/projects/<project-hash>/observations.jsonl
+
+# Back up a corrupted observations file before recreating it
+mv ~/.claude/homunculus/projects/<project-hash>/observations.jsonl \
+  ~/.claude/homunculus/projects/<project-hash>/observations.jsonl.bak.$(date +%Y%m%d-%H%M%S)
 
 # Verify hooks are enabled
 grep -r "observe" ~/.claude/settings.json
@@ -153,7 +170,7 @@ echo $PATH
 **Solutions:**
 ```bash
 # Check hooks are registered
-cat ~/.claude/settings.json | grep -A 10 '"hooks"'
+grep -A 10 '"hooks"' ~/.claude/settings.json
 
 # Verify hook files exist and are executable
 ls -la ~/.claude/plugins/cache/*/hooks/
@@ -231,8 +248,12 @@ tmux attach -t dev
 
 **Solutions:**
 ```bash
-# Clear plugin cache
-rm -rf ~/.claude/plugins/cache/*
+# Inspect the plugin cache before changing it
+ls -la ~/.claude/plugins/cache/
+
+# Back up the plugin cache instead of deleting it in place
+mv ~/.claude/plugins/cache ~/.claude/plugins/cache.backup.$(date +%Y%m%d-%H%M%S)
+mkdir -p ~/.claude/plugins/cache
 
 # Reinstall from marketplace
 # Claude Code → Extensions → Everything Claude Code → Uninstall
@@ -268,7 +289,9 @@ echo '{"packageManager": "pnpm"}' > .claude/package-manager.json
 # Or use package.json field
 npm pkg set packageManager="pnpm@8.15.0"
 
-# Remove conflicting lock files
+# Warning: removing lock files can change installed dependency versions.
+# Commit or back up the lock file first, then run a fresh install and re-run CI.
+# Only do this when intentionally switching package managers.
 rm package-lock.json  # If using pnpm/yarn/bun
 ```
 
@@ -287,14 +310,22 @@ rm package-lock.json  # If using pnpm/yarn/bun
 
 **Solutions:**
 ```bash
-# Archive old observations
-find ~/.claude/homunculus -name "observations.jsonl" -size +10M -delete
+# Archive large observations instead of deleting them
+archive_dir="$HOME/.claude/homunculus/archive/$(date +%Y%m%d)"
+mkdir -p "$archive_dir"
+find ~/.claude/homunculus/projects -name "observations.jsonl" -size +10M -exec sh -c '
+  for file do
+    base=$(basename "$(dirname "$file")")
+    gzip -c "$file" > "'"$archive_dir"'/${base}-observations.jsonl.gz"
+    : > "$file"
+  done
+' sh {} +
 
 # Disable unused hooks temporarily
 # Edit ~/.claude/settings.json
 
-# Use local caching
-# Enable Redis for semantic search caching
+# Keep active observation files small
+# Large archives should live under ~/.claude/homunculus/archive/
 ```
 
 ### High CPU Usage
@@ -332,7 +363,7 @@ du -sh ~/.claude/homunculus/*/
 find ~/.claude/plugins -name "*.sh" -exec chmod +x {} \;
 
 # Fix observation directory permissions
-chmod -R 755 ~/.claude/homunculus
+chmod -R u+rwX,go+rX ~/.claude/homunculus
 ```
 
 ### "MODULE_NOT_FOUND"

From 678ee7dc32f458adbd4fbcd9c25aa85eed46d5e9 Mon Sep 17 00:00:00 2001
From: ant <dev@antbotlab.com>
Date: Tue, 10 Mar 2026 23:19:09 +0800
Subject: [PATCH 05/22] feat(skills): add blueprint skill for multi-session
 construction planning

---
 skills/blueprint/SKILL.md | 69 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 69 insertions(+)
 create mode 100644 skills/blueprint/SKILL.md

diff --git a/skills/blueprint/SKILL.md b/skills/blueprint/SKILL.md
new file mode 100644
index 00000000..c8326f71
--- /dev/null
+++ b/skills/blueprint/SKILL.md
@@ -0,0 +1,69 @@
+---
+name: blueprint
+description: >-
+  Turn a one-line objective into a step-by-step construction plan for
+  multi-session, multi-agent engineering projects. Each step has a
+  self-contained context brief so a fresh agent can execute it cold.
+  Includes adversarial review gate, dependency graph, parallel step
+  detection, anti-pattern catalog, and plan mutation protocol.
+  TRIGGER when: user requests a plan, blueprint, or roadmap for a
+  complex multi-PR task, or describes work that needs multiple sessions.
+  DO NOT TRIGGER when: task is completable in a single PR or fewer
+  than 3 tool calls, or user says "just do it".
+origin: community
+---
+
+# Blueprint — Construction Plan Generator
+
+Turn a one-line objective into a step-by-step construction plan that any coding agent can execute cold.
+
+```
+/blueprint myapp "migrate database to PostgreSQL"
+```
+
+## What You Get
+
+A Markdown plan file in `plans/` where every step is independently executable — a fresh agent in a new session can pick up any step without reading prior steps or conversation history:
+
+- **Steps** — each one-PR sized, with task list, rollback strategy, verification commands, and exit criteria
+- **Dependency graph** — which steps can run in parallel, which must be serial
+- **Design decisions** — rationale for key choices, locked against re-litigation
+- **Invariants** — properties verified after every step
+- **Progress log** — single source of truth for execution state across sessions
+- **Review log** — findings from an adversarial review gate
+
+## Installation
+
+```bash
+mkdir -p ~/.claude/skills
+git clone https://github.com/antbotlab/blueprint.git ~/.claude/skills/blueprint
+```
+
+## Usage
+
+```
+/blueprint <project> <objective>
+```
+
+## Key Features
+
+**Cold-start execution** — Every step includes a self-contained context brief. No prior context needed.
+
+**Adversarial review gate** — Every plan is reviewed by a strongest-model sub-agent (e.g., Opus) against a checklist covering completeness, dependency correctness, and anti-pattern detection.
+
+**Branch/PR/CI workflow** — Built into every step. Detects git/gh availability and degrades gracefully to direct mode when absent.
+
+**Parallel step detection** — Dependency graph identifies steps with no shared files or output dependencies.
+
+**Zero runtime risk** — Pure markdown skill. No hooks, no shell scripts, no executable code. No attack surface.
+
+**Plan mutation protocol** — Steps can be split, inserted, skipped, reordered, or abandoned with formal protocols and audit trail.
+
+## Requirements
+
+- Claude Code (for `/blueprint` slash command)
+- Git + GitHub CLI (optional — enables full branch/PR/CI workflow; Blueprint detects absence and auto-switches to direct mode)
+
+## Source
+
+[github.com/antbotlab/blueprint](https://github.com/antbotlab/blueprint) — MIT License

From f809bdd049339eb03a726842c9f1ada0ce0b1dbc Mon Sep 17 00:00:00 2001
From: ant <dev@antbotlab.com>
Date: Tue, 10 Mar 2026 23:55:23 +0800
Subject: [PATCH 06/22] fix(skills): address review feedback on blueprint skill

- Pin installation to specific commit hash (full SHA) to mitigate
  supply-chain risk (cubic-dev-ai feedback)
- Add "When to Use", "How It Works", "Examples" sections to match
  repo skill format conventions (coderabbitai feedback)
- Add review-before-update instructions for safe version upgrades
- Emphasize zero-runtime-risk: pure Markdown, no executable code
---
 skills/blueprint/SKILL.md | 78 ++++++++++++++++++++++++++-------------
 1 file changed, 53 insertions(+), 25 deletions(-)

diff --git a/skills/blueprint/SKILL.md b/skills/blueprint/SKILL.md
index c8326f71..4a927d5a 100644
--- a/skills/blueprint/SKILL.md
+++ b/skills/blueprint/SKILL.md
@@ -17,47 +17,75 @@ origin: community
 
 Turn a one-line objective into a step-by-step construction plan that any coding agent can execute cold.
 
+## When to Use
+
+- Breaking a large feature into multiple PRs with clear dependency order
+- Planning a refactor or migration that spans multiple sessions
+- Coordinating parallel workstreams across sub-agents
+- Any task where context loss between sessions would cause rework
+
+**Do not use** for tasks completable in a single PR, fewer than 3 tool calls, or when the user says "just do it."
+
+## How It Works
+
+Blueprint runs a 5-phase pipeline:
+
+1. **Research** — Pre-flight checks (git, gh auth, remote, default branch), then reads project structure, existing plans, and memory files to gather context.
+2. **Design** — Breaks the objective into one-PR-sized steps (3–12 typical). Assigns dependency edges, parallel/serial ordering, model tier (strongest vs default), and rollback strategy per step.
+3. **Draft** — Writes a self-contained Markdown plan file to `plans/`. Every step includes a context brief, task list, verification commands, and exit criteria — so a fresh agent can execute any step without reading prior steps.
+4. **Review** — Delegates adversarial review to a strongest-model sub-agent (e.g., Opus) against a checklist and anti-pattern catalog. Fixes all critical findings before finalizing.
+5. **Register** — Saves the plan, updates memory index, and presents the step count and parallelism summary to the user.
+
+Blueprint detects git/gh availability automatically. With git + GitHub CLI, it generates full branch/PR/CI workflow plans. Without them, it switches to direct mode (edit-in-place, no branches).
+
+## Examples
+
+### Basic usage
+
 ```
 /blueprint myapp "migrate database to PostgreSQL"
 ```
 
-## What You Get
+Produces `plans/myapp-migrate-database-to-postgresql.md` with steps like:
+- Step 1: Add PostgreSQL driver and connection config
+- Step 2: Create migration scripts for each table
+- Step 3: Update repository layer to use new driver
+- Step 4: Add integration tests against PostgreSQL
+- Step 5: Remove old database code and config
 
-A Markdown plan file in `plans/` where every step is independently executable — a fresh agent in a new session can pick up any step without reading prior steps or conversation history:
+### Multi-agent project
 
-- **Steps** — each one-PR sized, with task list, rollback strategy, verification commands, and exit criteria
-- **Dependency graph** — which steps can run in parallel, which must be serial
-- **Design decisions** — rationale for key choices, locked against re-litigation
-- **Invariants** — properties verified after every step
-- **Progress log** — single source of truth for execution state across sessions
-- **Review log** — findings from an adversarial review gate
+```
+/blueprint chatbot "extract LLM providers into a plugin system"
+```
+
+Produces a plan with parallel steps where possible (e.g., "implement Anthropic plugin" and "implement OpenAI plugin" run in parallel after the plugin interface step is done), model tier assignments (strongest for the interface design step, default for implementation), and invariants verified after every step (e.g., "all existing tests pass", "no provider imports in core").
+
+## Key Features
+
+- **Cold-start execution** — Every step includes a self-contained context brief. No prior context needed.
+- **Adversarial review gate** — Every plan is reviewed by a strongest-model sub-agent against a checklist covering completeness, dependency correctness, and anti-pattern detection.
+- **Branch/PR/CI workflow** — Built into every step. Degrades gracefully to direct mode when git/gh is absent.
+- **Parallel step detection** — Dependency graph identifies steps with no shared files or output dependencies.
+- **Plan mutation protocol** — Steps can be split, inserted, skipped, reordered, or abandoned with formal protocols and audit trail.
+- **Zero runtime risk** — Pure Markdown skill. The entire repository contains only `.md` files — no hooks, no shell scripts, no executable code, no `package.json`, no build step. Nothing runs on install or invocation beyond Claude Code's native Markdown skill loader.
 
 ## Installation
 
 ```bash
 mkdir -p ~/.claude/skills
 git clone https://github.com/antbotlab/blueprint.git ~/.claude/skills/blueprint
+cd ~/.claude/skills/blueprint
+git checkout e6508e9258c763b67a9486af34de84d1e3b5cc74  # pin to reviewed version
 ```
 
-## Usage
+To update later, review the [changelog](https://github.com/antbotlab/blueprint/blob/main/CHANGELOG.md) before pulling:
 
+```bash
+cd ~/.claude/skills/blueprint
+git log --oneline HEAD..origin/main  # review new commits
+git pull
 ```
-/blueprint <project> <objective>
-```
-
-## Key Features
-
-**Cold-start execution** — Every step includes a self-contained context brief. No prior context needed.
-
-**Adversarial review gate** — Every plan is reviewed by a strongest-model sub-agent (e.g., Opus) against a checklist covering completeness, dependency correctness, and anti-pattern detection.
-
-**Branch/PR/CI workflow** — Built into every step. Detects git/gh availability and degrades gracefully to direct mode when absent.
-
-**Parallel step detection** — Dependency graph identifies steps with no shared files or output dependencies.
-
-**Zero runtime risk** — Pure markdown skill. No hooks, no shell scripts, no executable code. No attack surface.
-
-**Plan mutation protocol** — Steps can be split, inserted, skipped, reordered, or abandoned with formal protocols and audit trail.
 
 ## Requirements
 

From 13fe21c5b7bd12625fbab94eba8f4d5d715490f0 Mon Sep 17 00:00:00 2001
From: ant <dev@antbotlab.com>
Date: Wed, 11 Mar 2026 06:00:01 +0800
Subject: [PATCH 07/22] fix: add git fetch and use pinned checkout for update
 flow

Address review feedback:
- Add missing `git fetch origin` before comparing commits
- Replace `git pull` with `git checkout <sha>` for deterministic updates
---
 skills/blueprint/SKILL.md | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/skills/blueprint/SKILL.md b/skills/blueprint/SKILL.md
index 4a927d5a..27882a20 100644
--- a/skills/blueprint/SKILL.md
+++ b/skills/blueprint/SKILL.md
@@ -83,8 +83,9 @@ To update later, review the [changelog](https://github.com/antbotlab/blueprint/b
 
 ```bash
 cd ~/.claude/skills/blueprint
+git fetch origin
 git log --oneline HEAD..origin/main  # review new commits
-git pull
+git checkout <new-commit-sha>        # pin to a specific reviewed commit
 ```
 
 ## Requirements

From 205fa728094c4268f073f83fbc3392a89aa35c1a Mon Sep 17 00:00:00 2001
From: Affaan Mustafa <affaan@dcube.ai>
Date: Tue, 10 Mar 2026 19:14:33 -0700
Subject: [PATCH 08/22] docs: align blueprint skill with ECC install flow

---
 skills/blueprint/SKILL.md | 22 ++++++++++++----------
 1 file changed, 12 insertions(+), 10 deletions(-)

diff --git a/skills/blueprint/SKILL.md b/skills/blueprint/SKILL.md
index 27882a20..69135cc7 100644
--- a/skills/blueprint/SKILL.md
+++ b/skills/blueprint/SKILL.md
@@ -72,20 +72,22 @@ Produces a plan with parallel steps where possible (e.g., "implement Anthropic p
 
 ## Installation
 
+This skill ships with Everything Claude Code. No separate installation is needed when ECC is installed.
+
 ```bash
-mkdir -p ~/.claude/skills
-git clone https://github.com/antbotlab/blueprint.git ~/.claude/skills/blueprint
-cd ~/.claude/skills/blueprint
-git checkout e6508e9258c763b67a9486af34de84d1e3b5cc74  # pin to reviewed version
+# Verify the skill is present in your ECC checkout
+ls ~/.claude/plugins/ecc/skills/blueprint/SKILL.md
 ```
 
-To update later, review the [changelog](https://github.com/antbotlab/blueprint/blob/main/CHANGELOG.md) before pulling:
+If you are vendoring only this skill outside the full ECC install, copy the reviewed file from this repository into `~/.claude/skills/blueprint/SKILL.md` and keep it pinned to a reviewed ECC commit.
+
+To update later, review the ECC diff before updating:
 
 ```bash
-cd ~/.claude/skills/blueprint
-git fetch origin
-git log --oneline HEAD..origin/main  # review new commits
-git checkout <new-commit-sha>        # pin to a specific reviewed commit
+cd /path/to/everything-claude-code
+git fetch origin main
+git log --oneline HEAD..origin/main       # review new commits before updating
+git checkout <reviewed-full-sha>          # pin to a specific reviewed commit
 ```
 
 ## Requirements
@@ -95,4 +97,4 @@ git checkout <new-commit-sha>        # pin to a specific reviewed commit
 
 ## Source
 
-[github.com/antbotlab/blueprint](https://github.com/antbotlab/blueprint) — MIT License
+Inspired by [github.com/antbotlab/blueprint](https://github.com/antbotlab/blueprint) — upstream project and reference design.

From 7c82aebc76d66240c41be1449c682966924e0f3e Mon Sep 17 00:00:00 2001
From: Affaan Mustafa <affaan@dcube.ai>
Date: Tue, 10 Mar 2026 19:21:13 -0700
Subject: [PATCH 09/22] docs: tighten blueprint install guidance

---
 skills/blueprint/SKILL.md | 17 +++++++++++------
 1 file changed, 11 insertions(+), 6 deletions(-)

diff --git a/skills/blueprint/SKILL.md b/skills/blueprint/SKILL.md
index 69135cc7..1851c9a8 100644
--- a/skills/blueprint/SKILL.md
+++ b/skills/blueprint/SKILL.md
@@ -74,12 +74,13 @@ Produces a plan with parallel steps where possible (e.g., "implement Anthropic p
 
 This skill ships with Everything Claude Code. No separate installation is needed when ECC is installed.
 
-```bash
-# Verify the skill is present in your ECC checkout
-ls ~/.claude/plugins/ecc/skills/blueprint/SKILL.md
-```
+### Full ECC install
 
-If you are vendoring only this skill outside the full ECC install, copy the reviewed file from this repository into `~/.claude/skills/blueprint/SKILL.md` and keep it pinned to a reviewed ECC commit.
+If you are working from the ECC repository checkout, verify the skill is present with:
+
+```bash
+test -f skills/blueprint/SKILL.md
+```
 
 To update later, review the ECC diff before updating:
 
@@ -90,6 +91,10 @@ git log --oneline HEAD..origin/main       # review new commits before updating
 git checkout <reviewed-full-sha>          # pin to a specific reviewed commit
 ```
 
+### Vendored standalone install
+
+If you are vendoring only this skill outside the full ECC install, copy the reviewed file from the ECC repository into `~/.claude/skills/blueprint/SKILL.md`. Vendored copies do not have a git remote, so update them by re-copying the file from a reviewed ECC commit rather than running `git pull`.
+
 ## Requirements
 
 - Claude Code (for `/blueprint` slash command)
@@ -97,4 +102,4 @@ git checkout <reviewed-full-sha>          # pin to a specific reviewed commit
 
 ## Source
 
-Inspired by [github.com/antbotlab/blueprint](https://github.com/antbotlab/blueprint) — upstream project and reference design.
+Inspired by antbotlab/blueprint — upstream project and reference design.

From 77f38955b3bf01cdab61ee2a6347fd4b976b8f48 Mon Sep 17 00:00:00 2001
From: Affaan Mustafa <affaan@dcube.ai>
Date: Tue, 10 Mar 2026 19:22:37 -0700
Subject: [PATCH 10/22] fix: refresh codex config and docs

---
 .codex/AGENTS.md                   | 16 +++++-
 .codex/agents/docs-researcher.toml |  9 ++++
 .codex/agents/explorer.toml        |  9 ++++
 .codex/agents/reviewer.toml        |  9 ++++
 .codex/config.toml                 | 83 ++++++++++++++++++------------
 README.md                          | 35 ++++++++++---
 6 files changed, 119 insertions(+), 42 deletions(-)
 create mode 100644 .codex/agents/docs-researcher.toml
 create mode 100644 .codex/agents/explorer.toml
 create mode 100644 .codex/agents/reviewer.toml

diff --git a/.codex/AGENTS.md b/.codex/AGENTS.md
index 03730594..6de01b1e 100644
--- a/.codex/AGENTS.md
+++ b/.codex/AGENTS.md
@@ -39,6 +39,20 @@ Available skills:
 
 Configure in `~/.codex/config.toml` under `[mcp_servers]`. See `.codex/config.toml` for reference configuration with GitHub, Context7, Memory, and Sequential Thinking servers.
 
+## Multi-Agent Support
+
+Codex now supports multi-agent workflows behind the experimental `features.multi_agent` flag.
+
+- Enable it in `.codex/config.toml` with `[features] multi_agent = true`
+- Define project-local roles under `[agents.<name>]`
+- Point each role at a TOML layer under `.codex/agents/`
+- Use `/agent` inside Codex CLI to inspect and steer child agents
+
+Sample role configs in this repo:
+- `.codex/agents/explorer.toml` — read-only evidence gathering
+- `.codex/agents/reviewer.toml` — correctness/security review
+- `.codex/agents/docs-researcher.toml` — API and release-note verification
+
 ## Key Differences from Claude Code
 
 | Feature | Claude Code | Codex CLI |
@@ -47,7 +61,7 @@ Configure in `~/.codex/config.toml` under `[mcp_servers]`. See `.codex/config.to
 | Context file | CLAUDE.md + AGENTS.md | AGENTS.md only |
 | Skills | Skills loaded via plugin | `.agents/skills/` directory |
 | Commands | `/slash` commands | Instruction-based |
-| Agents | Subagent Task tool | Single agent model |
+| Agents | Subagent Task tool | Multi-agent via `/agent` and `[agents.<name>]` roles |
 | Security | Hook-based enforcement | Instruction + sandbox |
 | MCP | Full support | Command-based only |
 
diff --git a/.codex/agents/docs-researcher.toml b/.codex/agents/docs-researcher.toml
new file mode 100644
index 00000000..f8bd48dd
--- /dev/null
+++ b/.codex/agents/docs-researcher.toml
@@ -0,0 +1,9 @@
+model = "gpt-5.4"
+model_reasoning_effort = "medium"
+sandbox_mode = "read-only"
+
+developer_instructions = """
+Verify APIs, framework behavior, and release-note claims against primary documentation before changes land.
+Cite the exact docs or file paths that support each claim.
+Do not invent undocumented behavior.
+"""
diff --git a/.codex/agents/explorer.toml b/.codex/agents/explorer.toml
new file mode 100644
index 00000000..af7c1965
--- /dev/null
+++ b/.codex/agents/explorer.toml
@@ -0,0 +1,9 @@
+model = "o4-mini"
+model_reasoning_effort = "medium"
+sandbox_mode = "read-only"
+
+developer_instructions = """
+Stay in exploration mode.
+Trace the real execution path, cite files and symbols, and avoid proposing fixes unless the parent agent asks for them.
+Prefer targeted search and file reads over broad scans.
+"""
diff --git a/.codex/agents/reviewer.toml b/.codex/agents/reviewer.toml
new file mode 100644
index 00000000..269c5e49
--- /dev/null
+++ b/.codex/agents/reviewer.toml
@@ -0,0 +1,9 @@
+model = "gpt-5.4"
+model_reasoning_effort = "high"
+sandbox_mode = "read-only"
+
+developer_instructions = """
+Review like an owner.
+Prioritize correctness, security, behavioral regressions, and missing tests.
+Lead with concrete findings and avoid style-only feedback unless it hides a real bug.
+"""
diff --git a/.codex/config.toml b/.codex/config.toml
index 87d9747a..c60224ac 100644
--- a/.codex/config.toml
+++ b/.codex/config.toml
@@ -1,42 +1,37 @@
-# Everything Claude Code (ECC) — Codex CLI Reference Configuration
+#:schema https://developers.openai.com/codex/config-schema.json
+
+# Everything Claude Code (ECC) — Codex Reference Configuration
 #
-# Copy this file to ~/.codex/config.toml to apply globally.
-# Or keep it in your project root for project-level config.
+# Copy this file to ~/.codex/config.toml for global defaults, or keep it in
+# the project root as .codex/config.toml for project-local settings.
 #
-# Docs: https://github.com/openai/codex
+# Official docs:
+# - https://developers.openai.com/codex/config-reference
+# - https://developers.openai.com/codex/multi-agent
 
 # Model selection
 model = "o4-mini"
 model_provider = "openai"
 
-# Permissions
-[permissions]
-# "untrusted" = no writes, "on-request" = ask per action, "never" = full auto
+# Top-level runtime settings (current Codex schema)
 approval_policy = "on-request"
-# "off", "workspace-read", "workspace-write", "danger-full-access"
 sandbox_mode = "workspace-write"
+web_search = "live"
 
-# Notifications (macOS)
-[notify]
-command = "terminal-notifier -title 'Codex ECC' -message 'Task completed!' -sound default"
-on_complete = true
+# External notifications receive a JSON payload on stdin.
+notify = [
+  "terminal-notifier",
+  "-title", "Codex ECC",
+  "-message", "Task completed!",
+  "-sound", "default",
+]
 
-# History - persistent instructions applied to every session
-[history]
-# These are prepended to every conversation
-persistent_instructions = """
-Follow ECC principles:
-1. Test-Driven Development (TDD) - write tests first, 80%+ coverage required
-2. Immutability - always create new objects, never mutate
-3. Security-First - validate all inputs, no hardcoded secrets
-4. Conventional commits: feat|fix|refactor|docs|test|chore|perf|ci: description
-5. File organization: many small files (200-400 lines, 800 max)
-6. Error handling: handle at every level, never swallow errors
-7. Input validation: schema-based validation at system boundaries
-"""
+# Prefer AGENTS.md and project-local .codex/AGENTS.md for instructions.
+# model_instructions_file replaces built-in instructions instead of AGENTS.md,
+# so leave it unset unless you intentionally want a single override file.
+# model_instructions_file = "/absolute/path/to/instructions.md"
 
-# MCP Servers
-# Codex supports command-based MCP servers
+# MCP servers
 [mcp_servers.github]
 command = "npx"
 args = ["-y", "@modelcontextprotocol/server-github"]
@@ -62,19 +57,41 @@ args = ["-y", "@modelcontextprotocol/server-sequential-thinking"]
 # command = "npx"
 # args = ["-y", "firecrawl-mcp"]
 #
-# [mcp_servers.railway]
+# [mcp_servers.cloudflare]
 # command = "npx"
-# args = ["-y", "@anthropic/railway-mcp"]
+# args = ["-y", "@cloudflare/mcp-server-cloudflare"]
 
-# Features
 [features]
-web_search_request = true
+# Codex multi-agent support is experimental as of March 2026.
+multi_agent = true
 
-# Profiles — switch with CODEX_PROFILE=<name>
+# Profiles — switch with `codex -p <name>`
 [profiles.strict]
 approval_policy = "on-request"
-sandbox_mode = "workspace-read"
+sandbox_mode = "read-only"
+web_search = "cached"
 
 [profiles.yolo]
 approval_policy = "never"
 sandbox_mode = "workspace-write"
+web_search = "live"
+
+# Optional project-local multi-agent roles.
+# Keep these commented in global config, because config_file paths are resolved
+# relative to the config.toml file and must exist at load time.
+#
+# [agents]
+# max_threads = 6
+# max_depth = 1
+#
+# [agents.explorer]
+# description = "Read-only codebase explorer for gathering evidence before changes are proposed."
+# config_file = "agents/explorer.toml"
+#
+# [agents.reviewer]
+# description = "PR reviewer focused on correctness, security, and missing tests."
+# config_file = "agents/reviewer.toml"
+#
+# [agents.docs_researcher]
+# description = "Documentation specialist that verifies APIs, framework behavior, and release notes."
+# config_file = "agents/docs-researcher.toml"
diff --git a/README.md b/README.md
index 09267ca5..25d6c091 100644
--- a/README.md
+++ b/README.md
@@ -893,27 +893,29 @@ ECC provides **first-class Codex support** for both the macOS app and CLI, with
 ### Quick Start (Codex App + CLI)
 
 ```bash
-# Copy the reference config to your home directory
-cp .codex/config.toml ~/.codex/config.toml
-
-# Run Codex CLI in the repo — AGENTS.md is auto-detected
+# Run Codex CLI in the repo — AGENTS.md and .codex/ are auto-detected
 codex
+
+# Optional: copy the global-safe defaults to your home directory
+cp .codex/config.toml ~/.codex/config.toml
 ```
 
 Codex macOS app:
 - Open this repository as your workspace.
 - The root `AGENTS.md` is auto-detected.
-- Optional: copy `.codex/config.toml` to `~/.codex/config.toml` for CLI/app behavior consistency.
+- `.codex/config.toml` and `.codex/agents/*.toml` work best when kept project-local.
+- Optional: copy `.codex/config.toml` to `~/.codex/config.toml` for global defaults; keep the multi-agent role files project-local unless you also copy `.codex/agents/`.
 
 ### What's Included
 
 | Component | Count | Details |
 |-----------|-------|---------|
-| Config | 1 | `.codex/config.toml` — model, permissions, MCP servers, persistent instructions |
+| Config | 1 | `.codex/config.toml` — top-level approvals/sandbox/web_search, MCP servers, notifications, profiles |
 | AGENTS.md | 2 | Root (universal) + `.codex/AGENTS.md` (Codex-specific supplement) |
 | Skills | 16 | `.agents/skills/` — SKILL.md + agents/openai.yaml per skill |
 | MCP Servers | 4 | GitHub, Context7, Memory, Sequential Thinking (command-based) |
 | Profiles | 2 | `strict` (read-only sandbox) and `yolo` (full auto-approve) |
+| Agent Roles | 3 | `.codex/agents/` — explorer, reviewer, docs-researcher |
 
 ### Skills
 
@@ -940,7 +942,24 @@ Skills at `.agents/skills/` are auto-loaded by Codex:
 
 ### Key Limitation
 
-Codex does **not yet provide Claude-style hook execution parity**. ECC enforcement there is instruction-based via `AGENTS.md` and `persistent_instructions`, plus sandbox permissions.
+Codex does **not yet provide Claude-style hook execution parity**. ECC enforcement there is instruction-based via `AGENTS.md`, optional `model_instructions_file` overrides, and sandbox/approval settings.
+
+### Multi-Agent Support
+
+Current Codex builds support experimental multi-agent workflows.
+
+- Enable `features.multi_agent = true` in `.codex/config.toml`
+- Define roles under `[agents.<name>]`
+- Point each role at a file under `.codex/agents/`
+- Use `/agent` in the CLI to inspect or steer child agents
+
+ECC ships three sample role configs:
+
+| Role | Purpose |
+|------|---------|
+| `explorer` | Read-only codebase evidence gathering before edits |
+| `reviewer` | Correctness, security, and missing-test review |
+| `docs_researcher` | Documentation and API verification before release/docs changes |
 
 ---
 
@@ -1090,7 +1109,7 @@ ECC is the **first plugin to maximize every major AI coding tool**. Here's how e
 - **AGENTS.md** at root is the universal cross-tool file (read by all 4 tools)
 - **DRY adapter pattern** lets Cursor reuse Claude Code's hook scripts without duplication
 - **Skills format** (SKILL.md with YAML frontmatter) works across Claude Code, Codex, and OpenCode
-- Codex's lack of hooks is compensated by `persistent_instructions` and sandbox permissions
+- Codex's lack of hooks is compensated by `AGENTS.md`, optional `model_instructions_file` overrides, and sandbox permissions
 
 ---
 

From 65cb240e881661ce5acbede2d846227134e3ba3f Mon Sep 17 00:00:00 2001
From: "ecc-tools[bot]" <257055122+ecc-tools[bot]@users.noreply.github.com>
Date: Sat, 7 Mar 2026 14:48:04 -0800
Subject: [PATCH 11/22] feat: add everything-claude-code skill (#335)

* feat: add everything-claude-code skill generated by ECC Tools

* feat: add everything-claude-code instincts for continuous learning

---------

Co-authored-by: ecc-tools[bot] <257055122+ecc-tools[bot]@users.noreply.github.com>
---
 .../everything-claude-code-instincts.yaml     | 649 ++++++++++++++++++
 .../skills/everything-claude-code/SKILL.md    | 215 ++++++
 2 files changed, 864 insertions(+)
 create mode 100644 .claude/homunculus/instincts/inherited/everything-claude-code-instincts.yaml
 create mode 100644 .claude/skills/everything-claude-code/SKILL.md

diff --git a/.claude/homunculus/instincts/inherited/everything-claude-code-instincts.yaml b/.claude/homunculus/instincts/inherited/everything-claude-code-instincts.yaml
new file mode 100644
index 00000000..5639c86e
--- /dev/null
+++ b/.claude/homunculus/instincts/inherited/everything-claude-code-instincts.yaml
@@ -0,0 +1,649 @@
+# Instincts generated from https://github.com/affaan-m/everything-claude-code
+# Generated: 2026-03-04T22:56:16.069Z
+# Version: 2.0
+
+---
+id: everything-claude-code-commit-length
+trigger: "when writing a commit message"
+confidence: 0.6
+domain: git
+source: repo-analysis
+source_repo: https://github.com/affaan-m/everything-claude-code
+---
+
+# Everything Claude Code Commit Length
+
+## Action
+
+Write moderate-length commit messages (~50 characters)
+
+## Evidence
+
+- Average commit message length: 70 chars
+- Based on 200 commits
+
+---
+id: everything-claude-code-naming-files
+trigger: "when creating a new file"
+confidence: 0.8
+domain: code-style
+source: repo-analysis
+source_repo: https://github.com/affaan-m/everything-claude-code
+---
+
+# Everything Claude Code Naming Files
+
+## Action
+
+Use camelCase naming convention
+
+## Evidence
+
+- Analyzed file naming patterns in repository
+- Dominant pattern: camelCase
+
+---
+id: everything-claude-code-export-style
+trigger: "when exporting from a module"
+confidence: 0.7
+domain: code-style
+source: repo-analysis
+source_repo: https://github.com/affaan-m/everything-claude-code
+---
+
+# Everything Claude Code Export Style
+
+## Action
+
+Prefer mixed exports
+
+## Evidence
+
+- Export pattern analysis
+- Dominant style: mixed
+
+---
+id: everything-claude-code-test-separate
+trigger: "when writing tests"
+confidence: 0.8
+domain: testing
+source: repo-analysis
+source_repo: https://github.com/affaan-m/everything-claude-code
+---
+
+# Everything Claude Code Test Separate
+
+## Action
+
+Place tests in the tests/ or __tests__/ directory, mirroring src structure
+
+## Evidence
+
+- Separate test directory pattern detected
+- Tests live in dedicated test folders
+
+---
+id: everything-claude-code-test-framework
+trigger: "when writing tests"
+confidence: 0.9
+domain: testing
+source: repo-analysis
+source_repo: https://github.com/affaan-m/everything-claude-code
+---
+
+# Everything Claude Code Test Framework
+
+## Action
+
+Use unknown as the test framework
+
+## Evidence
+
+- Test framework detected: unknown
+- File pattern: *.test.js
+
+---
+id: everything-claude-code-test-naming
+trigger: "when creating a test file"
+confidence: 0.85
+domain: testing
+source: repo-analysis
+source_repo: https://github.com/affaan-m/everything-claude-code
+---
+
+# Everything Claude Code Test Naming
+
+## Action
+
+Name test files using the pattern: *.test.js
+
+## Evidence
+
+- File pattern: *.test.js
+- Consistent across test files
+
+---
+id: everything-claude-code-test-types
+trigger: "when planning tests for a feature"
+confidence: 0.7
+domain: testing
+source: repo-analysis
+source_repo: https://github.com/affaan-m/everything-claude-code
+---
+
+# Everything Claude Code Test Types
+
+## Action
+
+Write unit, integration tests to match project standards
+
+## Evidence
+
+- Test types detected: unit, integration
+- Coverage config: yes
+
+---
+id: everything-claude-code-workflow-database-migration
+trigger: "when modifying the database schema or adding tables"
+confidence: 0.65
+domain: workflow
+source: repo-analysis
+source_repo: https://github.com/affaan-m/everything-claude-code
+---
+
+# Everything Claude Code Workflow Database Migration
+
+## Action
+
+Follow the database-migration workflow:
+1. Create migration file
+2. Update schema definitions
+3. Generate/update types
+
+## Evidence
+
+- Workflow detected from commit patterns
+- Frequency: ~3x per month
+- Files: migrations/*
+
+---
+id: everything-claude-code-workflow-feature-development
+trigger: "when implementing a new feature"
+confidence: 0.9
+domain: workflow
+source: repo-analysis
+source_repo: https://github.com/affaan-m/everything-claude-code
+---
+
+# Everything Claude Code Workflow Feature Development
+
+## Action
+
+Follow the feature-development workflow:
+1. Add feature implementation
+2. Add tests for feature
+3. Update documentation
+
+## Evidence
+
+- Workflow detected from commit patterns
+- Frequency: ~14x per month
+- Files: .opencode/*, .opencode/plugins/*, .opencode/tools/*
+
+---
+id: everything-claude-code-workflow-multi-language-documentation-sync
+trigger: "when doing multi language documentation sync"
+confidence: 0.9
+domain: workflow
+source: repo-analysis
+source_repo: https://github.com/affaan-m/everything-claude-code
+---
+
+# Everything Claude Code Workflow Multi Language Documentation Sync
+
+## Action
+
+Follow the multi-language-documentation-sync workflow:
+1. Update English documentation
+2. Translate changes to zh-CN
+3. Translate changes to zh-TW
+4. Translate changes to ja-JP
+5. Update cross-references
+
+## Evidence
+
+- Workflow detected from commit patterns
+- Frequency: ~10x per month
+- Files: README.md, docs/zh-CN/*.md, docs/zh-TW/*.md
+
+---
+id: everything-claude-code-workflow-cross-platform-harness-sync
+trigger: "when doing cross platform harness sync"
+confidence: 0.9
+domain: workflow
+source: repo-analysis
+source_repo: https://github.com/affaan-m/everything-claude-code
+---
+
+# Everything Claude Code Workflow Cross Platform Harness Sync
+
+## Action
+
+Follow the cross-platform-harness-sync workflow:
+1. Update main platform files
+2. Port to .cursor/ directory
+3. Port to .codex/ directory
+4. Port to .opencode/ directory
+5. Update platform-specific configs
+
+## Evidence
+
+- Workflow detected from commit patterns
+- Frequency: ~8x per month
+- Files: .cursor/*, .codex/*, .opencode/*
+
+---
+id: everything-claude-code-workflow-skill-addition-workflow
+trigger: "when doing skill addition workflow"
+confidence: 0.8
+domain: workflow
+source: repo-analysis
+source_repo: https://github.com/affaan-m/everything-claude-code
+---
+
+# Everything Claude Code Workflow Skill Addition Workflow
+
+## Action
+
+Follow the skill-addition-workflow workflow:
+1. Create main skill SKILL.md
+2. Add to README.md
+3. Port to .cursor/skills/
+4. Port to .agents/skills/ with openai.yaml
+5. Update package.json
+6. Add translations if needed
+
+## Evidence
+
+- Workflow detected from commit patterns
+- Frequency: ~6x per month
+- Files: skills/*/SKILL.md, README.md, .cursor/skills/*/SKILL.md
+
+---
+id: everything-claude-code-workflow-version-release-workflow
+trigger: "when doing version release workflow"
+confidence: 0.65
+domain: workflow
+source: repo-analysis
+source_repo: https://github.com/affaan-m/everything-claude-code
+---
+
+# Everything Claude Code Workflow Version Release Workflow
+
+## Action
+
+Follow the version-release-workflow workflow:
+1. Update package.json version
+2. Update .claude-plugin/ manifests
+3. Update .opencode/package.json
+4. Update README version references
+5. Update CHANGELOG.md
+
+## Evidence
+
+- Workflow detected from commit patterns
+- Frequency: ~3x per month
+- Files: package.json, .claude-plugin/plugin.json, .claude-plugin/marketplace.json
+
+---
+id: everything-claude-code-workflow-hook-system-updates
+trigger: "when doing hook system updates"
+confidence: 0.7
+domain: workflow
+source: repo-analysis
+source_repo: https://github.com/affaan-m/everything-claude-code
+---
+
+# Everything Claude Code Workflow Hook System Updates
+
+## Action
+
+Follow the hook-system-updates workflow:
+1. Update hooks/hooks.json
+2. Create/update hook scripts
+3. Port to .cursor/hooks/
+4. Update tests/hooks/ or tests/integration/
+5. Update hook documentation
+
+## Evidence
+
+- Workflow detected from commit patterns
+- Frequency: ~4x per month
+- Files: hooks/hooks.json, scripts/hooks/*.js, .cursor/hooks/*.js
+
+---
+id: everything-claude-code-workflow-continuous-learning-updates
+trigger: "when doing continuous learning updates"
+confidence: 0.75
+domain: workflow
+source: repo-analysis
+source_repo: https://github.com/affaan-m/everything-claude-code
+---
+
+# Everything Claude Code Workflow Continuous Learning Updates
+
+## Action
+
+Follow the continuous-learning-updates workflow:
+1. Update main continuous-learning-v2 skill
+2. Update observer scripts
+3. Port to platform-specific directories
+4. Update translations
+5. Update related commands
+
+## Evidence
+
+- Workflow detected from commit patterns
+- Frequency: ~5x per month
+- Files: skills/continuous-learning-v2/*, .cursor/skills/continuous-learning-v2/*, commands/evolve.md
+
+---
+id: everything-claude-code-camel-case-files
+trigger: "When creating new JavaScript files"
+confidence: 0.85
+domain: code-style
+source: repo-analysis
+source_repo: affaan-m/everything-claude-code
+---
+
+# Everything Claude Code Camel Case Files
+
+## Action
+
+Use camelCase naming convention
+
+## Evidence
+
+- Consistent camelCase pattern in codeStyle analysis
+- Files follow camelCase in folderStructure
+
+---
+id: everything-claude-code-pascal-case-classes
+trigger: "When defining JavaScript classes"
+confidence: 0.85
+domain: code-style
+source: repo-analysis
+source_repo: affaan-m/everything-claude-code
+---
+
+# Everything Claude Code Pascal Case Classes
+
+## Action
+
+Use PascalCase naming convention
+
+## Evidence
+
+- PascalCase classes specified in namingConventions
+- Consistent pattern across codebase
+
+---
+id: everything-claude-code-screaming-snake-constants
+trigger: "When defining constants"
+confidence: 0.85
+domain: code-style
+source: repo-analysis
+source_repo: affaan-m/everything-claude-code
+---
+
+# Everything Claude Code Screaming Snake Constants
+
+## Action
+
+Use SCREAMING_SNAKE_CASE naming convention
+
+## Evidence
+
+- SCREAMING_SNAKE_CASE constants in namingConventions
+- Standard JavaScript practice
+
+---
+id: everything-claude-code-try-catch-errors
+trigger: "When handling potential errors"
+confidence: 0.8
+domain: code-style
+source: repo-analysis
+source_repo: affaan-m/everything-claude-code
+---
+
+# Everything Claude Code Try Catch Errors
+
+## Action
+
+Use try-catch blocks for error handling
+
+## Evidence
+
+- try-catch style specified in errorHandling
+- No custom error classes or global handlers detected
+
+---
+id: everything-claude-code-unit-integration-tests
+trigger: "When writing tests"
+confidence: 0.8
+domain: testing
+source: repo-analysis
+source_repo: affaan-m/everything-claude-code
+---
+
+# Everything Claude Code Unit Integration Tests
+
+## Action
+
+Create both unit and integration tests using *.test.js pattern
+
+## Evidence
+
+- testTypes include unit and integration
+- filePattern shows *.test.js convention
+
+---
+id: everything-claude-code-conventional-commits
+trigger: "When making commits"
+confidence: 0.9
+domain: git
+source: repo-analysis
+source_repo: affaan-m/everything-claude-code
+---
+
+# Everything Claude Code Conventional Commits
+
+## Action
+
+Use conventional commit format with prefixes: feat, fix, docs, chore, test, refactor
+
+## Evidence
+
+- All commit examples follow conventional format
+- Consistent prefixes across commit history
+
+---
+id: everything-claude-code-70-char-commit-length
+trigger: "When writing commit messages"
+confidence: 0.75
+domain: git
+source: repo-analysis
+source_repo: affaan-m/everything-claude-code
+---
+
+# Everything Claude Code 70 Char Commit Length
+
+## Action
+
+Keep commit messages around 70 characters average length
+
+## Evidence
+
+- averageLength shows 70 characters
+- Commit examples align with this pattern
+
+---
+id: everything-claude-code-multilang-docs-sync
+trigger: "When updating core documentation or features"
+confidence: 0.95
+domain: workflow
+source: repo-analysis
+source_repo: affaan-m/everything-claude-code
+---
+
+# Everything Claude Code Multilang Docs Sync
+
+## Action
+
+Update English first, then translate to zh-CN, zh-TW, ja-JP and update cross-references
+
+## Evidence
+
+- multi-language-documentation-sync workflow frequency ~10x/month
+- Clear pattern in filesInvolved across language directories
+
+---
+id: everything-claude-code-cross-platform-sync
+trigger: "When adding new features or updating platform configurations"
+confidence: 0.9
+domain: workflow
+source: repo-analysis
+source_repo: affaan-m/everything-claude-code
+---
+
+# Everything Claude Code Cross Platform Sync
+
+## Action
+
+Port changes to .cursor/, .codex/, .opencode/, and .agents/ directories
+
+## Evidence
+
+- cross-platform-harness-sync workflow frequency ~8x/month
+- Multiple platform directories in architecture
+
+---
+id: everything-claude-code-skill-structure
+trigger: "When adding a new skill or capability"
+confidence: 0.88
+domain: workflow
+source: repo-analysis
+source_repo: affaan-m/everything-claude-code
+---
+
+# Everything Claude Code Skill Structure
+
+## Action
+
+Create SKILL.md in main skills/, port to platform-specific directories, update README.md and package.json
+
+## Evidence
+
+- skill-addition-workflow frequency ~6x/month
+- Consistent skill structure across platforms
+
+---
+id: everything-claude-code-version-release-sync
+trigger: "When preparing a new release"
+confidence: 0.85
+domain: workflow
+source: repo-analysis
+source_repo: affaan-m/everything-claude-code
+---
+
+# Everything Claude Code Version Release Sync
+
+## Action
+
+Update all package.json files, plugin manifests, README version references, and CHANGELOG.md
+
+## Evidence
+
+- version-release-workflow frequency ~3x/month
+- Multiple package.json files in different directories
+
+---
+id: everything-claude-code-hook-system-testing
+trigger: "When modifying hook behavior or adding new hooks"
+confidence: 0.82
+domain: workflow
+source: repo-analysis
+source_repo: affaan-m/everything-claude-code
+---
+
+# Everything Claude Code Hook System Testing
+
+## Action
+
+Update hooks.json, create/update scripts, port to .cursor/, and update corresponding tests
+
+## Evidence
+
+- hook-system-updates workflow frequency ~4x/month
+- hooks/ and tests/ directories in architecture
+
+---
+id: everything-claude-code-learning-system-updates
+trigger: "When enhancing continuous learning capabilities"
+confidence: 0.87
+domain: workflow
+source: repo-analysis
+source_repo: affaan-m/everything-claude-code
+---
+
+# Everything Claude Code Learning System Updates
+
+## Action
+
+Update main continuous-learning-v2 skill, port to platforms, update translations and related commands
+
+## Evidence
+
+- continuous-learning-updates workflow frequency ~5x/month
+- commands/evolve.md and instinct-*.md files referenced
+
+---
+id: everything-claude-code-hybrid-module-organization
+trigger: "When organizing code modules"
+confidence: 0.75
+domain: architecture
+source: repo-analysis
+source_repo: affaan-m/everything-claude-code
+---
+
+# Everything Claude Code Hybrid Module Organization
+
+## Action
+
+Use hybrid module organization with separate test location
+
+## Evidence
+
+- moduleOrganization: hybrid
+- testLocation: separate in architecture analysis
+
+---
+id: everything-claude-code-mixed-import-export
+trigger: "When writing import/export statements"
+confidence: 0.7
+domain: code-style
+source: repo-analysis
+source_repo: affaan-m/everything-claude-code
+---
+
+# Everything Claude Code Mixed Import Export
+
+## Action
+
+Use mixed import and export styles as appropriate for the context
+
+## Evidence
+
+- importStyle: mixed and exportStyle: mixed in codeStyle
+- Flexible approach across codebase
+
diff --git a/.claude/skills/everything-claude-code/SKILL.md b/.claude/skills/everything-claude-code/SKILL.md
new file mode 100644
index 00000000..92111818
--- /dev/null
+++ b/.claude/skills/everything-claude-code/SKILL.md
@@ -0,0 +1,215 @@
+# everything-claude-code Development Patterns
+
+> Auto-generated skill from repository analysis
+
+## Overview
+
+This skill teaches the development patterns for the everything-claude-code repository - a comprehensive multi-platform AI coding assistant system. The codebase maintains compatibility across multiple AI platforms (Claude, Cursor, Codex, OpenCode) while supporting internationalization across four languages (English, Chinese Simplified/Traditional, Japanese). The system focuses on skill-based architecture, continuous learning capabilities, and cross-platform synchronization.
+
+## Coding Conventions
+
+### File Naming
+- Use **camelCase** for JavaScript files
+- Use **kebab-case** for directories and skill names
+- Test files follow pattern: `*.test.js`
+
+```javascript
+// File structure examples
+skills/continuousLearningV2/SKILL.md
+tests/hooks/hookManager.test.js
+scripts/platformSync.js
+```
+
+### Import/Export Style
+- Mixed import styles (both CommonJS and ES modules supported)
+- Mixed export styles based on platform compatibility
+
+```javascript
+// CommonJS style
+const hookManager = require('./hookManager');
+module.exports = { syncPlatforms };
+
+// ES module style  
+import { translateDocs } from './translationUtils.js';
+export { processSkills };
+```
+
+### Commit Conventions
+- Use conventional commit prefixes: `feat:`, `fix:`, `test:`, `chore:`, `docs:`
+- Keep commit messages under 70 characters
+- Be descriptive about cross-platform impacts
+
+```bash
+feat: add multi-language skill sync workflow
+fix: resolve cursor platform hook integration
+docs: update zh-CN translation for continuous learning
+```
+
+## Workflows
+
+### Multi-Language Documentation Sync
+**Trigger:** When core documentation or features are updated  
+**Command:** `/sync-docs`
+
+1. Update English documentation in root README.md or skill files
+2. Identify sections that need translation updates
+3. Update Chinese Simplified (`docs/zh-CN/*.md`)
+4. Update Traditional Chinese (`docs/zh-TW/*.md`) 
+5. Update Japanese (`docs/ja-JP/*.md`)
+6. Verify cross-references and links work across all languages
+7. Test that skill descriptions match across platforms
+
+```markdown
+<!-- Example translation structure -->
+# English: skills/example/SKILL.md
+# Chinese: docs/zh-CN/skills/example/SKILL.md  
+# Japanese: docs/ja-JP/skills/example/SKILL.md
+```
+
+### Cross-Platform Harness Sync
+**Trigger:** When adding new features or updating platform configurations  
+**Command:** `/sync-platforms`
+
+1. Update main platform files in root directory
+2. Port changes to `.cursor/` directory for Cursor IDE
+3. Port changes to `.codex/` directory for Codex integration
+4. Port changes to `.opencode/` directory for OpenCode platform
+5. Update platform-specific configuration files
+6. Test that each platform can load and execute the changes
+7. Verify skill compatibility across all platforms
+
+```javascript
+// Platform-specific config example
+// .cursor/package.json
+{
+  "name": "everything-claude-code-cursor",
+  "platform": "cursor"
+}
+
+// .opencode/package.json  
+{
+  "name": "everything-claude-code-opencode",
+  "platform": "opencode"
+}
+```
+
+### Skill Addition Workflow
+**Trigger:** When adding a new skill or capability  
+**Command:** `/add-skill`
+
+1. Create main skill directory: `skills/{skillName}/`
+2. Write comprehensive `SKILL.md` with examples and usage
+3. Add skill reference to root `README.md`
+4. Port skill to `.cursor/skills/{skillName}/SKILL.md`
+5. Port to `.agents/skills/{skillName}/` with `openai.yaml`
+6. Update `package.json` with new skill metadata
+7. Add translations for skill name and description
+8. Test skill loading across all platforms
+
+```yaml
+# .agents/skills/example/openai.yaml
+name: example-skill
+description: Example skill for demonstration
+version: 1.0.0
+compatibility: ["openai", "claude", "cursor"]
+```
+
+### Version Release Workflow  
+**Trigger:** When preparing a new release  
+**Command:** `/release`
+
+1. Update version in root `package.json`
+2. Update `.claude-plugin/plugin.json` manifest version
+3. Update `.claude-plugin/marketplace.json` with release notes
+4. Update `.opencode/package.json` version to match
+5. Update version references in `README.md`
+6. Update `CHANGELOG.md` with new features and fixes
+7. Create git tag and push release
+8. Verify plugin compatibility across platforms
+
+```json
+// package.json version sync
+{
+  "version": "2.1.0",
+  "name": "everything-claude-code"
+}
+```
+
+### Hook System Updates
+**Trigger:** When modifying hook behavior or adding new hooks  
+**Command:** `/update-hooks`
+
+1. Update `hooks/hooks.json` with new hook definitions
+2. Create or modify hook scripts in `scripts/hooks/`
+3. Port hook implementations to `.cursor/hooks/`
+4. Update tests in `tests/hooks/` or `tests/integration/`
+5. Update hook documentation in `hooks/README.md`
+6. Test hook execution across different trigger scenarios
+7. Verify platform-specific hook behaviors
+
+```json
+// hooks/hooks.json example
+{
+  "pre-commit": {
+    "script": "scripts/hooks/preCommit.js",
+    "platforms": ["cursor", "opencode"],
+    "enabled": true
+  }
+}
+```
+
+### Continuous Learning Updates
+**Trigger:** When enhancing the continuous learning capabilities  
+**Command:** `/update-learning`
+
+1. Update main `skills/continuous-learning-v2/` skill files
+2. Modify observer scripts for better learning detection  
+3. Port updates to platform-specific skill directories
+4. Update translation files for learning prompts
+5. Update related commands in `commands/evolve.md`
+6. Update instinct commands (`commands/instinct-*.md`)
+7. Test learning feedback loops across platforms
+
+```javascript
+// Learning observer example
+class LearningObserver {
+  observePatterns() {
+    // Detect coding patterns
+    // Update skill knowledge
+    // Sync across platforms
+  }
+}
+```
+
+## Testing Patterns
+
+Tests follow the `*.test.js` pattern and focus on:
+- Cross-platform compatibility verification
+- Multi-language content validation  
+- Hook execution testing
+- Skill loading and execution
+
+```javascript
+// Example test structure
+describe('Platform Sync', () => {
+  test('should sync skills across all platforms', () => {
+    const platforms = ['cursor', 'opencode', 'codex'];
+    platforms.forEach(platform => {
+      expect(skillExists(platform, 'continuous-learning-v2')).toBe(true);
+    });
+  });
+});
+```
+
+## Commands
+
+| Command | Purpose |
+|---------|---------|
+| `/sync-docs` | Synchronize documentation across all language versions |
+| `/sync-platforms` | Port changes across AI coding platforms |
+| `/add-skill` | Add new skill with full cross-platform support |
+| `/release` | Prepare and publish new version release |
+| `/update-hooks` | Modify hook system and test integration |
+| `/update-learning` | Enhance continuous learning capabilities |
+| `/test-platforms` | Run compatibility tests across all platforms |
+| `/translate` | Generate translations for new content |
\ No newline at end of file

From c883289abba987981f52989b000d093f4d5f415d Mon Sep 17 00:00:00 2001
From: Affaan Mustafa <affaan@dcube.ai>
Date: Tue, 10 Mar 2026 19:36:12 -0700
Subject: [PATCH 12/22] fix: curate everything-claude-code skill output

---
 .../everything-claude-code-instincts.yaml     | 655 +++---------------
 .../skills/everything-claude-code/SKILL.md    | 280 +++-----
 2 files changed, 165 insertions(+), 770 deletions(-)

diff --git a/.claude/homunculus/instincts/inherited/everything-claude-code-instincts.yaml b/.claude/homunculus/instincts/inherited/everything-claude-code-instincts.yaml
index 5639c86e..7818dff1 100644
--- a/.claude/homunculus/instincts/inherited/everything-claude-code-instincts.yaml
+++ b/.claude/homunculus/instincts/inherited/everything-claude-code-instincts.yaml
@@ -1,458 +1,12 @@
-# Instincts generated from https://github.com/affaan-m/everything-claude-code
-# Generated: 2026-03-04T22:56:16.069Z
-# Version: 2.0
-
----
-id: everything-claude-code-commit-length
-trigger: "when writing a commit message"
-confidence: 0.6
-domain: git
-source: repo-analysis
-source_repo: https://github.com/affaan-m/everything-claude-code
----
-
-# Everything Claude Code Commit Length
-
-## Action
-
-Write moderate-length commit messages (~50 characters)
-
-## Evidence
-
-- Average commit message length: 70 chars
-- Based on 200 commits
-
----
-id: everything-claude-code-naming-files
-trigger: "when creating a new file"
-confidence: 0.8
-domain: code-style
-source: repo-analysis
-source_repo: https://github.com/affaan-m/everything-claude-code
----
-
-# Everything Claude Code Naming Files
-
-## Action
-
-Use camelCase naming convention
-
-## Evidence
-
-- Analyzed file naming patterns in repository
-- Dominant pattern: camelCase
-
----
-id: everything-claude-code-export-style
-trigger: "when exporting from a module"
-confidence: 0.7
-domain: code-style
-source: repo-analysis
-source_repo: https://github.com/affaan-m/everything-claude-code
----
-
-# Everything Claude Code Export Style
-
-## Action
-
-Prefer mixed exports
-
-## Evidence
-
-- Export pattern analysis
-- Dominant style: mixed
-
----
-id: everything-claude-code-test-separate
-trigger: "when writing tests"
-confidence: 0.8
-domain: testing
-source: repo-analysis
-source_repo: https://github.com/affaan-m/everything-claude-code
----
-
-# Everything Claude Code Test Separate
-
-## Action
-
-Place tests in the tests/ or __tests__/ directory, mirroring src structure
-
-## Evidence
-
-- Separate test directory pattern detected
-- Tests live in dedicated test folders
-
----
-id: everything-claude-code-test-framework
-trigger: "when writing tests"
-confidence: 0.9
-domain: testing
-source: repo-analysis
-source_repo: https://github.com/affaan-m/everything-claude-code
----
-
-# Everything Claude Code Test Framework
-
-## Action
-
-Use unknown as the test framework
-
-## Evidence
-
-- Test framework detected: unknown
-- File pattern: *.test.js
-
----
-id: everything-claude-code-test-naming
-trigger: "when creating a test file"
-confidence: 0.85
-domain: testing
-source: repo-analysis
-source_repo: https://github.com/affaan-m/everything-claude-code
----
-
-# Everything Claude Code Test Naming
-
-## Action
-
-Name test files using the pattern: *.test.js
-
-## Evidence
-
-- File pattern: *.test.js
-- Consistent across test files
-
----
-id: everything-claude-code-test-types
-trigger: "when planning tests for a feature"
-confidence: 0.7
-domain: testing
-source: repo-analysis
-source_repo: https://github.com/affaan-m/everything-claude-code
----
-
-# Everything Claude Code Test Types
-
-## Action
-
-Write unit, integration tests to match project standards
-
-## Evidence
-
-- Test types detected: unit, integration
-- Coverage config: yes
-
----
-id: everything-claude-code-workflow-database-migration
-trigger: "when modifying the database schema or adding tables"
-confidence: 0.65
-domain: workflow
-source: repo-analysis
-source_repo: https://github.com/affaan-m/everything-claude-code
----
-
-# Everything Claude Code Workflow Database Migration
-
-## Action
-
-Follow the database-migration workflow:
-1. Create migration file
-2. Update schema definitions
-3. Generate/update types
-
-## Evidence
-
-- Workflow detected from commit patterns
-- Frequency: ~3x per month
-- Files: migrations/*
-
----
-id: everything-claude-code-workflow-feature-development
-trigger: "when implementing a new feature"
-confidence: 0.9
-domain: workflow
-source: repo-analysis
-source_repo: https://github.com/affaan-m/everything-claude-code
----
-
-# Everything Claude Code Workflow Feature Development
-
-## Action
-
-Follow the feature-development workflow:
-1. Add feature implementation
-2. Add tests for feature
-3. Update documentation
-
-## Evidence
-
-- Workflow detected from commit patterns
-- Frequency: ~14x per month
-- Files: .opencode/*, .opencode/plugins/*, .opencode/tools/*
-
----
-id: everything-claude-code-workflow-multi-language-documentation-sync
-trigger: "when doing multi language documentation sync"
-confidence: 0.9
-domain: workflow
-source: repo-analysis
-source_repo: https://github.com/affaan-m/everything-claude-code
----
-
-# Everything Claude Code Workflow Multi Language Documentation Sync
-
-## Action
-
-Follow the multi-language-documentation-sync workflow:
-1. Update English documentation
-2. Translate changes to zh-CN
-3. Translate changes to zh-TW
-4. Translate changes to ja-JP
-5. Update cross-references
-
-## Evidence
-
-- Workflow detected from commit patterns
-- Frequency: ~10x per month
-- Files: README.md, docs/zh-CN/*.md, docs/zh-TW/*.md
-
----
-id: everything-claude-code-workflow-cross-platform-harness-sync
-trigger: "when doing cross platform harness sync"
-confidence: 0.9
-domain: workflow
-source: repo-analysis
-source_repo: https://github.com/affaan-m/everything-claude-code
----
-
-# Everything Claude Code Workflow Cross Platform Harness Sync
-
-## Action
-
-Follow the cross-platform-harness-sync workflow:
-1. Update main platform files
-2. Port to .cursor/ directory
-3. Port to .codex/ directory
-4. Port to .opencode/ directory
-5. Update platform-specific configs
-
-## Evidence
-
-- Workflow detected from commit patterns
-- Frequency: ~8x per month
-- Files: .cursor/*, .codex/*, .opencode/*
-
----
-id: everything-claude-code-workflow-skill-addition-workflow
-trigger: "when doing skill addition workflow"
-confidence: 0.8
-domain: workflow
-source: repo-analysis
-source_repo: https://github.com/affaan-m/everything-claude-code
----
-
-# Everything Claude Code Workflow Skill Addition Workflow
-
-## Action
-
-Follow the skill-addition-workflow workflow:
-1. Create main skill SKILL.md
-2. Add to README.md
-3. Port to .cursor/skills/
-4. Port to .agents/skills/ with openai.yaml
-5. Update package.json
-6. Add translations if needed
-
-## Evidence
-
-- Workflow detected from commit patterns
-- Frequency: ~6x per month
-- Files: skills/*/SKILL.md, README.md, .cursor/skills/*/SKILL.md
-
----
-id: everything-claude-code-workflow-version-release-workflow
-trigger: "when doing version release workflow"
-confidence: 0.65
-domain: workflow
-source: repo-analysis
-source_repo: https://github.com/affaan-m/everything-claude-code
----
-
-# Everything Claude Code Workflow Version Release Workflow
-
-## Action
-
-Follow the version-release-workflow workflow:
-1. Update package.json version
-2. Update .claude-plugin/ manifests
-3. Update .opencode/package.json
-4. Update README version references
-5. Update CHANGELOG.md
-
-## Evidence
-
-- Workflow detected from commit patterns
-- Frequency: ~3x per month
-- Files: package.json, .claude-plugin/plugin.json, .claude-plugin/marketplace.json
-
----
-id: everything-claude-code-workflow-hook-system-updates
-trigger: "when doing hook system updates"
-confidence: 0.7
-domain: workflow
-source: repo-analysis
-source_repo: https://github.com/affaan-m/everything-claude-code
----
-
-# Everything Claude Code Workflow Hook System Updates
-
-## Action
-
-Follow the hook-system-updates workflow:
-1. Update hooks/hooks.json
-2. Create/update hook scripts
-3. Port to .cursor/hooks/
-4. Update tests/hooks/ or tests/integration/
-5. Update hook documentation
-
-## Evidence
-
-- Workflow detected from commit patterns
-- Frequency: ~4x per month
-- Files: hooks/hooks.json, scripts/hooks/*.js, .cursor/hooks/*.js
-
----
-id: everything-claude-code-workflow-continuous-learning-updates
-trigger: "when doing continuous learning updates"
-confidence: 0.75
-domain: workflow
-source: repo-analysis
-source_repo: https://github.com/affaan-m/everything-claude-code
----
-
-# Everything Claude Code Workflow Continuous Learning Updates
-
-## Action
-
-Follow the continuous-learning-updates workflow:
-1. Update main continuous-learning-v2 skill
-2. Update observer scripts
-3. Port to platform-specific directories
-4. Update translations
-5. Update related commands
-
-## Evidence
-
-- Workflow detected from commit patterns
-- Frequency: ~5x per month
-- Files: skills/continuous-learning-v2/*, .cursor/skills/continuous-learning-v2/*, commands/evolve.md
-
----
-id: everything-claude-code-camel-case-files
-trigger: "When creating new JavaScript files"
-confidence: 0.85
-domain: code-style
-source: repo-analysis
-source_repo: affaan-m/everything-claude-code
----
-
-# Everything Claude Code Camel Case Files
-
-## Action
-
-Use camelCase naming convention
-
-## Evidence
-
-- Consistent camelCase pattern in codeStyle analysis
-- Files follow camelCase in folderStructure
-
----
-id: everything-claude-code-pascal-case-classes
-trigger: "When defining JavaScript classes"
-confidence: 0.85
-domain: code-style
-source: repo-analysis
-source_repo: affaan-m/everything-claude-code
----
-
-# Everything Claude Code Pascal Case Classes
-
-## Action
-
-Use PascalCase naming convention
-
-## Evidence
-
-- PascalCase classes specified in namingConventions
-- Consistent pattern across codebase
-
----
-id: everything-claude-code-screaming-snake-constants
-trigger: "When defining constants"
-confidence: 0.85
-domain: code-style
-source: repo-analysis
-source_repo: affaan-m/everything-claude-code
----
-
-# Everything Claude Code Screaming Snake Constants
-
-## Action
-
-Use SCREAMING_SNAKE_CASE naming convention
-
-## Evidence
-
-- SCREAMING_SNAKE_CASE constants in namingConventions
-- Standard JavaScript practice
-
----
-id: everything-claude-code-try-catch-errors
-trigger: "When handling potential errors"
-confidence: 0.8
-domain: code-style
-source: repo-analysis
-source_repo: affaan-m/everything-claude-code
----
-
-# Everything Claude Code Try Catch Errors
-
-## Action
-
-Use try-catch blocks for error handling
-
-## Evidence
-
-- try-catch style specified in errorHandling
-- No custom error classes or global handlers detected
-
----
-id: everything-claude-code-unit-integration-tests
-trigger: "When writing tests"
-confidence: 0.8
-domain: testing
-source: repo-analysis
-source_repo: affaan-m/everything-claude-code
----
-
-# Everything Claude Code Unit Integration Tests
-
-## Action
-
-Create both unit and integration tests using *.test.js pattern
-
-## Evidence
-
-- testTypes include unit and integration
-- filePattern shows *.test.js convention
+# Curated instincts for affaan-m/everything-claude-code
+# Import with: /instinct-import .claude/homunculus/instincts/inherited/everything-claude-code-instincts.yaml
 
 ---
 id: everything-claude-code-conventional-commits
-trigger: "When making commits"
+trigger: "when making a commit in everything-claude-code"
 confidence: 0.9
 domain: git
-source: repo-analysis
+source: repo-curation
 source_repo: affaan-m/everything-claude-code
 ---
 
@@ -460,59 +14,99 @@ source_repo: affaan-m/everything-claude-code
 
 ## Action
 
-Use conventional commit format with prefixes: feat, fix, docs, chore, test, refactor
+Use conventional commit prefixes such as `feat:`, `fix:`, `docs:`, `test:`, `chore:`, and `refactor:`.
 
 ## Evidence
 
-- All commit examples follow conventional format
-- Consistent prefixes across commit history
+- Mainline history consistently uses conventional commit subjects.
+- Release and changelog automation expect readable commit categorization.
 
 ---
-id: everything-claude-code-70-char-commit-length
-trigger: "When writing commit messages"
-confidence: 0.75
+id: everything-claude-code-commit-length
+trigger: "when writing a commit subject in everything-claude-code"
+confidence: 0.8
 domain: git
-source: repo-analysis
+source: repo-curation
 source_repo: affaan-m/everything-claude-code
 ---
 
-# Everything Claude Code 70 Char Commit Length
+# Everything Claude Code Commit Length
 
 ## Action
 
-Keep commit messages around 70 characters average length
+Keep commit subjects concise and close to the repository norm of about 70 characters.
 
 ## Evidence
 
-- averageLength shows 70 characters
-- Commit examples align with this pattern
+- Recent history clusters around ~70 characters, not ~50.
+- Short, descriptive subjects read well in release notes and PR summaries.
 
 ---
-id: everything-claude-code-multilang-docs-sync
-trigger: "When updating core documentation or features"
-confidence: 0.95
+id: everything-claude-code-js-file-naming
+trigger: "when creating a new JavaScript or TypeScript module in everything-claude-code"
+confidence: 0.85
+domain: code-style
+source: repo-curation
+source_repo: affaan-m/everything-claude-code
+---
+
+# Everything Claude Code JS File Naming
+
+## Action
+
+Prefer camelCase for JavaScript and TypeScript module filenames, and keep skill or command directories in kebab-case.
+
+## Evidence
+
+- `scripts/` and test helpers mostly use camelCase module names.
+- `skills/` and `commands/` directories use kebab-case consistently.
+
+---
+id: everything-claude-code-test-runner
+trigger: "when adding or updating tests in everything-claude-code"
+confidence: 0.9
+domain: testing
+source: repo-curation
+source_repo: affaan-m/everything-claude-code
+---
+
+# Everything Claude Code Test Runner
+
+## Action
+
+Use the repository's existing Node-based test flow: targeted `*.test.js` files first, then `node tests/run-all.js` or `npm test` for broader verification.
+
+## Evidence
+
+- The repo uses `tests/run-all.js` as the central test orchestrator.
+- Test files follow the `*.test.js` naming pattern across hook, CI, and integration coverage.
+
+---
+id: everything-claude-code-hooks-change-set
+trigger: "when modifying hooks or hook-adjacent behavior in everything-claude-code"
+confidence: 0.88
 domain: workflow
-source: repo-analysis
+source: repo-curation
 source_repo: affaan-m/everything-claude-code
 ---
 
-# Everything Claude Code Multilang Docs Sync
+# Everything Claude Code Hooks Change Set
 
 ## Action
 
-Update English first, then translate to zh-CN, zh-TW, ja-JP and update cross-references
+Update the hook script, its configuration, its tests, and its user-facing documentation together.
 
 ## Evidence
 
-- multi-language-documentation-sync workflow frequency ~10x/month
-- Clear pattern in filesInvolved across language directories
+- Hook fixes routinely span `hooks/hooks.json`, `scripts/hooks/`, `tests/hooks/`, `tests/integration/`, and `hooks/README.md`.
+- Partial hook changes are a common source of regressions and stale docs.
 
 ---
 id: everything-claude-code-cross-platform-sync
-trigger: "When adding new features or updating platform configurations"
+trigger: "when shipping a user-visible feature across ECC surfaces"
 confidence: 0.9
 domain: workflow
-source: repo-analysis
+source: repo-curation
 source_repo: affaan-m/everything-claude-code
 ---
 
@@ -520,130 +114,49 @@ source_repo: affaan-m/everything-claude-code
 
 ## Action
 
-Port changes to .cursor/, .codex/, .opencode/, and .agents/ directories
+Treat the root repo as the source of truth, then mirror shipped changes to `.cursor/`, `.codex/`, `.opencode/`, and `.agents/` only where the feature actually exists.
 
 ## Evidence
 
-- cross-platform-harness-sync workflow frequency ~8x/month
-- Multiple platform directories in architecture
+- ECC maintains multiple harness-specific surfaces with overlapping but not identical files.
+- The safest workflow is root-first followed by explicit parity updates.
 
 ---
-id: everything-claude-code-skill-structure
-trigger: "When adding a new skill or capability"
-confidence: 0.88
+id: everything-claude-code-release-sync
+trigger: "when preparing a release for everything-claude-code"
+confidence: 0.86
 domain: workflow
-source: repo-analysis
+source: repo-curation
 source_repo: affaan-m/everything-claude-code
 ---
 
-# Everything Claude Code Skill Structure
+# Everything Claude Code Release Sync
 
 ## Action
 
-Create SKILL.md in main skills/, port to platform-specific directories, update README.md and package.json
+Keep package versions, plugin manifests, and release-facing docs synchronized before publishing.
 
 ## Evidence
 
-- skill-addition-workflow frequency ~6x/month
-- Consistent skill structure across platforms
+- Release work spans `package.json`, `.claude-plugin/*`, `.opencode/package.json`, and release-note content.
+- Version drift causes broken update paths and confusing install surfaces.
 
 ---
-id: everything-claude-code-version-release-sync
-trigger: "When preparing a new release"
-confidence: 0.85
+id: everything-claude-code-learning-curation
+trigger: "when importing or evolving instincts for everything-claude-code"
+confidence: 0.84
 domain: workflow
-source: repo-analysis
+source: repo-curation
 source_repo: affaan-m/everything-claude-code
 ---
 
-# Everything Claude Code Version Release Sync
+# Everything Claude Code Learning Curation
 
 ## Action
 
-Update all package.json files, plugin manifests, README version references, and CHANGELOG.md
+Prefer a small set of accurate instincts over bulk-generated, duplicated, or contradictory instincts.
 
 ## Evidence
 
-- version-release-workflow frequency ~3x/month
-- Multiple package.json files in different directories
-
----
-id: everything-claude-code-hook-system-testing
-trigger: "When modifying hook behavior or adding new hooks"
-confidence: 0.82
-domain: workflow
-source: repo-analysis
-source_repo: affaan-m/everything-claude-code
----
-
-# Everything Claude Code Hook System Testing
-
-## Action
-
-Update hooks.json, create/update scripts, port to .cursor/, and update corresponding tests
-
-## Evidence
-
-- hook-system-updates workflow frequency ~4x/month
-- hooks/ and tests/ directories in architecture
-
----
-id: everything-claude-code-learning-system-updates
-trigger: "When enhancing continuous learning capabilities"
-confidence: 0.87
-domain: workflow
-source: repo-analysis
-source_repo: affaan-m/everything-claude-code
----
-
-# Everything Claude Code Learning System Updates
-
-## Action
-
-Update main continuous-learning-v2 skill, port to platforms, update translations and related commands
-
-## Evidence
-
-- continuous-learning-updates workflow frequency ~5x/month
-- commands/evolve.md and instinct-*.md files referenced
-
----
-id: everything-claude-code-hybrid-module-organization
-trigger: "When organizing code modules"
-confidence: 0.75
-domain: architecture
-source: repo-analysis
-source_repo: affaan-m/everything-claude-code
----
-
-# Everything Claude Code Hybrid Module Organization
-
-## Action
-
-Use hybrid module organization with separate test location
-
-## Evidence
-
-- moduleOrganization: hybrid
-- testLocation: separate in architecture analysis
-
----
-id: everything-claude-code-mixed-import-export
-trigger: "When writing import/export statements"
-confidence: 0.7
-domain: code-style
-source: repo-analysis
-source_repo: affaan-m/everything-claude-code
----
-
-# Everything Claude Code Mixed Import Export
-
-## Action
-
-Use mixed import and export styles as appropriate for the context
-
-## Evidence
-
-- importStyle: mixed and exportStyle: mixed in codeStyle
-- Flexible approach across codebase
-
+- Auto-generated instinct dumps can duplicate rules, widen triggers too far, or preserve placeholder detector output.
+- Curated instincts are easier to import, audit, and trust during continuous-learning workflows.
diff --git a/.claude/skills/everything-claude-code/SKILL.md b/.claude/skills/everything-claude-code/SKILL.md
index 92111818..83da0161 100644
--- a/.claude/skills/everything-claude-code/SKILL.md
+++ b/.claude/skills/everything-claude-code/SKILL.md
@@ -1,215 +1,97 @@
-# everything-claude-code Development Patterns
+# Everything Claude Code
 
-> Auto-generated skill from repository analysis
+Use this skill when working inside the `everything-claude-code` repository and you need repo-specific guidance instead of generic coding advice.
 
-## Overview
+Optional companion instincts live at `.claude/homunculus/instincts/inherited/everything-claude-code-instincts.yaml` for teams using `continuous-learning-v2`.
 
-This skill teaches the development patterns for the everything-claude-code repository - a comprehensive multi-platform AI coding assistant system. The codebase maintains compatibility across multiple AI platforms (Claude, Cursor, Codex, OpenCode) while supporting internationalization across four languages (English, Chinese Simplified/Traditional, Japanese). The system focuses on skill-based architecture, continuous learning capabilities, and cross-platform synchronization.
+## When to Use
 
-## Coding Conventions
+Activate this skill when the task touches one or more of these areas:
+- cross-platform parity across Claude Code, Cursor, Codex, and OpenCode
+- hook scripts, hook docs, or hook tests
+- skills, commands, agents, or rules that must stay synchronized across surfaces
+- release work such as version bumps, changelog updates, or plugin metadata updates
+- continuous-learning or instinct workflows inside this repository
 
-### File Naming
-- Use **camelCase** for JavaScript files
-- Use **kebab-case** for directories and skill names
-- Test files follow pattern: `*.test.js`
+## How It Works
 
-```javascript
-// File structure examples
-skills/continuousLearningV2/SKILL.md
-tests/hooks/hookManager.test.js
-scripts/platformSync.js
+### 1. Follow the repo's development contract
+
+- Use conventional commits such as `feat:`, `fix:`, `docs:`, `test:`, `chore:`.
+- Keep commit subjects concise and close to the repo norm of about 70 characters.
+- Prefer camelCase for JavaScript and TypeScript module filenames.
+- Use kebab-case for skill directories and command filenames.
+- Keep test files on the existing `*.test.js` pattern.
+
+### 2. Treat the root repo as the source of truth
+
+Start from the root implementation, then mirror changes where they are intentionally shipped.
+
+Typical mirror targets:
+- `.cursor/`
+- `.codex/`
+- `.opencode/`
+- `.agents/`
+
+Do not assume every `.claude/` artifact needs a cross-platform copy. Only mirror files that are part of the shipped multi-platform surface.
+
+### 3. Update hooks with tests and docs together
+
+When changing hook behavior:
+1. update `hooks/hooks.json` or the relevant script in `scripts/hooks/`
+2. update matching tests in `tests/hooks/` or `tests/integration/`
+3. update `hooks/README.md` if behavior or configuration changed
+4. verify parity for `.cursor/hooks/` and `.opencode/plugins/` when applicable
+
+### 4. Keep release metadata in sync
+
+When preparing a release, verify the same version is reflected anywhere it is surfaced:
+- `package.json`
+- `.claude-plugin/plugin.json`
+- `.claude-plugin/marketplace.json`
+- `.opencode/package.json`
+- release notes or changelog entries when the release process expects them
+
+### 5. Be explicit about continuous-learning changes
+
+If the task touches `skills/continuous-learning-v2/` or imported instincts:
+- prefer accurate, low-noise instincts over auto-generated bulk output
+- keep instinct files importable by `instinct-cli.py`
+- remove duplicated or contradictory instincts instead of layering more guidance on top
+
+## Examples
+
+### Naming examples
+
+```text
+skills/continuous-learning-v2/SKILL.md
+commands/update-docs.md
+scripts/hooks/session-start.js
+tests/hooks/hooks.test.js
 ```
 
-### Import/Export Style
-- Mixed import styles (both CommonJS and ES modules supported)
-- Mixed export styles based on platform compatibility
+### Commit examples
 
-```javascript
-// CommonJS style
-const hookManager = require('./hookManager');
-module.exports = { syncPlatforms };
-
-// ES module style  
-import { translateDocs } from './translationUtils.js';
-export { processSkills };
+```text
+fix: harden session summary extraction on Stop hook
+docs: align Codex config examples with current schema
+test: cover Windows formatter fallback behavior
 ```
 
-### Commit Conventions
-- Use conventional commit prefixes: `feat:`, `fix:`, `test:`, `chore:`, `docs:`
-- Keep commit messages under 70 characters
-- Be descriptive about cross-platform impacts
+### Skill update checklist
 
-```bash
-feat: add multi-language skill sync workflow
-fix: resolve cursor platform hook integration
-docs: update zh-CN translation for continuous learning
+```text
+1. Update the root skill or command.
+2. Mirror it only where that surface is shipped.
+3. Run targeted tests first, then the broader suite if behavior changed.
+4. Review docs and release notes for user-visible changes.
 ```
 
-## Workflows
+### Release checklist
 
-### Multi-Language Documentation Sync
-**Trigger:** When core documentation or features are updated  
-**Command:** `/sync-docs`
-
-1. Update English documentation in root README.md or skill files
-2. Identify sections that need translation updates
-3. Update Chinese Simplified (`docs/zh-CN/*.md`)
-4. Update Traditional Chinese (`docs/zh-TW/*.md`) 
-5. Update Japanese (`docs/ja-JP/*.md`)
-6. Verify cross-references and links work across all languages
-7. Test that skill descriptions match across platforms
-
-```markdown
-<!-- Example translation structure -->
-# English: skills/example/SKILL.md
-# Chinese: docs/zh-CN/skills/example/SKILL.md  
-# Japanese: docs/ja-JP/skills/example/SKILL.md
+```text
+1. Bump package and plugin versions.
+2. Run npm test.
+3. Verify platform-specific manifests.
+4. Publish the release notes with a human-readable summary.
 ```
-
-### Cross-Platform Harness Sync
-**Trigger:** When adding new features or updating platform configurations  
-**Command:** `/sync-platforms`
-
-1. Update main platform files in root directory
-2. Port changes to `.cursor/` directory for Cursor IDE
-3. Port changes to `.codex/` directory for Codex integration
-4. Port changes to `.opencode/` directory for OpenCode platform
-5. Update platform-specific configuration files
-6. Test that each platform can load and execute the changes
-7. Verify skill compatibility across all platforms
-
-```javascript
-// Platform-specific config example
-// .cursor/package.json
-{
-  "name": "everything-claude-code-cursor",
-  "platform": "cursor"
-}
-
-// .opencode/package.json  
-{
-  "name": "everything-claude-code-opencode",
-  "platform": "opencode"
-}
-```
-
-### Skill Addition Workflow
-**Trigger:** When adding a new skill or capability  
-**Command:** `/add-skill`
-
-1. Create main skill directory: `skills/{skillName}/`
-2. Write comprehensive `SKILL.md` with examples and usage
-3. Add skill reference to root `README.md`
-4. Port skill to `.cursor/skills/{skillName}/SKILL.md`
-5. Port to `.agents/skills/{skillName}/` with `openai.yaml`
-6. Update `package.json` with new skill metadata
-7. Add translations for skill name and description
-8. Test skill loading across all platforms
-
-```yaml
-# .agents/skills/example/openai.yaml
-name: example-skill
-description: Example skill for demonstration
-version: 1.0.0
-compatibility: ["openai", "claude", "cursor"]
-```
-
-### Version Release Workflow  
-**Trigger:** When preparing a new release  
-**Command:** `/release`
-
-1. Update version in root `package.json`
-2. Update `.claude-plugin/plugin.json` manifest version
-3. Update `.claude-plugin/marketplace.json` with release notes
-4. Update `.opencode/package.json` version to match
-5. Update version references in `README.md`
-6. Update `CHANGELOG.md` with new features and fixes
-7. Create git tag and push release
-8. Verify plugin compatibility across platforms
-
-```json
-// package.json version sync
-{
-  "version": "2.1.0",
-  "name": "everything-claude-code"
-}
-```
-
-### Hook System Updates
-**Trigger:** When modifying hook behavior or adding new hooks  
-**Command:** `/update-hooks`
-
-1. Update `hooks/hooks.json` with new hook definitions
-2. Create or modify hook scripts in `scripts/hooks/`
-3. Port hook implementations to `.cursor/hooks/`
-4. Update tests in `tests/hooks/` or `tests/integration/`
-5. Update hook documentation in `hooks/README.md`
-6. Test hook execution across different trigger scenarios
-7. Verify platform-specific hook behaviors
-
-```json
-// hooks/hooks.json example
-{
-  "pre-commit": {
-    "script": "scripts/hooks/preCommit.js",
-    "platforms": ["cursor", "opencode"],
-    "enabled": true
-  }
-}
-```
-
-### Continuous Learning Updates
-**Trigger:** When enhancing the continuous learning capabilities  
-**Command:** `/update-learning`
-
-1. Update main `skills/continuous-learning-v2/` skill files
-2. Modify observer scripts for better learning detection  
-3. Port updates to platform-specific skill directories
-4. Update translation files for learning prompts
-5. Update related commands in `commands/evolve.md`
-6. Update instinct commands (`commands/instinct-*.md`)
-7. Test learning feedback loops across platforms
-
-```javascript
-// Learning observer example
-class LearningObserver {
-  observePatterns() {
-    // Detect coding patterns
-    // Update skill knowledge
-    // Sync across platforms
-  }
-}
-```
-
-## Testing Patterns
-
-Tests follow the `*.test.js` pattern and focus on:
-- Cross-platform compatibility verification
-- Multi-language content validation  
-- Hook execution testing
-- Skill loading and execution
-
-```javascript
-// Example test structure
-describe('Platform Sync', () => {
-  test('should sync skills across all platforms', () => {
-    const platforms = ['cursor', 'opencode', 'codex'];
-    platforms.forEach(platform => {
-      expect(skillExists(platform, 'continuous-learning-v2')).toBe(true);
-    });
-  });
-});
-```
-
-## Commands
-
-| Command | Purpose |
-|---------|---------|
-| `/sync-docs` | Synchronize documentation across all language versions |
-| `/sync-platforms` | Port changes across AI coding platforms |
-| `/add-skill` | Add new skill with full cross-platform support |
-| `/release` | Prepare and publish new version release |
-| `/update-hooks` | Modify hook system and test integration |
-| `/update-learning` | Enhance continuous learning capabilities |
-| `/test-platforms` | Run compatibility tests across all platforms |
-| `/translate` | Generate translations for new content |
\ No newline at end of file

From a50349181a19967beecdc617d32b26fc88053fc6 Mon Sep 17 00:00:00 2001
From: kinshukdutta <kinshuk.dutta@tanium.com>
Date: Mon, 9 Mar 2026 15:05:17 -0400
Subject: [PATCH 13/22] =?UTF-8?q?feat:=20architecture=20improvements=20?=
 =?UTF-8?q?=E2=80=94=20test=20discovery,=20hooks=20schema,=20catalog,=20co?=
 =?UTF-8?q?mmand=20map,=20coverage,=20cross-harness=20docs?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

- AGENTS.md: sync skills count to 65+
- tests/run-all.js: glob-based test discovery for *.test.js
- scripts/ci/validate-hooks.js: validate hooks.json with ajv + schemas/hooks.schema.json
- schemas/hooks.schema.json: hookItem.type enum command|notification
- scripts/ci/catalog.js: catalog agents, commands, skills (--json | --md)
- docs/COMMAND-AGENT-MAP.md: command → agent/skill map
- docs/ARCHITECTURE-IMPROVEMENTS.md: improvement recommendations
- package.json: ajv, c8 devDeps; npm run coverage
- CONTRIBUTING.md: Cross-Harness and Translations section
- .gitignore: coverage/

Made-with: Cursor
---
 .gitignore                        |   1 +
 AGENTS.md                         |  10 +-
 CONTRIBUTING.md                   |  24 +
 docs/ARCHITECTURE-IMPROVEMENTS.md | 146 +++++
 docs/COMMAND-AGENT-MAP.md         |  61 ++
 package-lock.json                 | 907 +++++++++++++++++++++++++++++-
 package.json                      |   5 +-
 schemas/hooks.schema.json         |  13 +-
 scripts/ci/catalog.js             |  71 +++
 scripts/ci/validate-hooks.js      |  18 +-
 tests/run-all.js                  |  34 +-
 11 files changed, 1247 insertions(+), 43 deletions(-)
 create mode 100644 docs/ARCHITECTURE-IMPROVEMENTS.md
 create mode 100644 docs/COMMAND-AGENT-MAP.md
 create mode 100644 scripts/ci/catalog.js

diff --git a/.gitignore b/.gitignore
index 007765b7..7e37f0fd 100644
--- a/.gitignore
+++ b/.gitignore
@@ -23,6 +23,7 @@ node_modules/
 
 # Build output
 dist/
+coverage/
 
 # Python
 __pycache__/
diff --git a/AGENTS.md b/AGENTS.md
index 52e96fab..3c0ada3b 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -1,6 +1,6 @@
 # Everything Claude Code (ECC) — Agent Instructions
 
-This is a **production-ready AI coding plugin** providing 13 specialized agents, 50+ skills, 33 commands, and automated hook workflows for software development.
+This is a **production-ready AI coding plugin** providing 16 specialized agents, 65+ skills, 40 commands, and automated hook workflows for software development.
 
 ## Core Principles
 
@@ -27,6 +27,9 @@ This is a **production-ready AI coding plugin** providing 13 specialized agents,
 | go-build-resolver | Go build errors | Go build failures |
 | database-reviewer | PostgreSQL/Supabase specialist | Schema design, query optimization |
 | python-reviewer | Python code review | Python projects |
+| chief-of-staff | Communication triage and drafts | Multi-channel email, Slack, LINE, Messenger |
+| loop-operator | Autonomous loop execution | Run loops safely, monitor stalls, intervene |
+| harness-optimizer | Harness config tuning | Reliability, cost, throughput |
 
 ## Agent Orchestration
 
@@ -36,6 +39,9 @@ Use agents proactively without user prompt:
 - Bug fix or new feature → **tdd-guide**
 - Architectural decision → **architect**
 - Security-sensitive code → **security-reviewer**
+- Multi-channel communication triage → **chief-of-staff**
+- Autonomous loops / loop monitoring → **loop-operator**
+- Harness config reliability and cost → **harness-optimizer**
 
 Use parallel execution for independent operations — launch multiple agents simultaneously.
 
@@ -123,7 +129,7 @@ Troubleshoot failures: check test isolation → verify mocks → fix implementat
 
 ```
 agents/          — 13 specialized subagents
-skills/          — 50+ workflow skills and domain knowledge
+skills/          — 65+ workflow skills and domain knowledge
 commands/        — 33 slash commands
 hooks/           — Trigger-based automations
 rules/           — Always-follow guidelines (common + per-language)
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index d7a6a664..61b0f92b 100644
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -10,6 +10,7 @@ Thanks for wanting to contribute! This repo is a community resource for Claude C
 - [Contributing Agents](#contributing-agents)
 - [Contributing Hooks](#contributing-hooks)
 - [Contributing Commands](#contributing-commands)
+- [Cross-Harness and Translations](#cross-harness-and-translations)
 - [Pull Request Process](#pull-request-process)
 
 ---
@@ -348,6 +349,29 @@ What the user receives.
 
 ---
 
+## Cross-Harness and Translations
+
+### Skill subsets (Codex and Cursor)
+
+ECC ships skill subsets for other harnesses:
+
+- **Codex:** `.agents/skills/` — skills listed in `agents/openai.yaml` are loaded by Codex.
+- **Cursor:** `.cursor/skills/` — a subset of skills is bundled for Cursor.
+
+When you **add a new skill** that should be available on Codex or Cursor:
+
+1. Add the skill under `skills/your-skill-name/` as usual.
+2. If it should be available on **Codex**, add it to `.agents/skills/` (copy the skill directory or add a reference) and ensure it is referenced in `agents/openai.yaml` if required.
+3. If it should be available on **Cursor**, add it under `.cursor/skills/` per Cursor's layout.
+
+Check existing skills in those directories for the expected structure. Keeping these subsets in sync is manual; mention in your PR if you updated them.
+
+### Translations
+
+Translations live under `docs/` (e.g. `docs/zh-CN`, `docs/zh-TW`, `docs/ja-JP`). If you change agents, commands, or skills that are translated, consider updating the corresponding translation files or opening an issue so maintainers or translators can update them.
+
+---
+
 ## Pull Request Process
 
 ### 1. PR Title Format
diff --git a/docs/ARCHITECTURE-IMPROVEMENTS.md b/docs/ARCHITECTURE-IMPROVEMENTS.md
new file mode 100644
index 00000000..f8a5e605
--- /dev/null
+++ b/docs/ARCHITECTURE-IMPROVEMENTS.md
@@ -0,0 +1,146 @@
+# Architecture Improvement Recommendations
+
+This document captures architect-level improvements for the Everything Claude Code (ECC) project. It is written from the perspective of a Claude Code coding architect aiming to improve maintainability, consistency, and long-term quality.
+
+---
+
+## 1. Documentation and Single Source of Truth
+
+### 1.1 Agent / Command / Skill Count Sync
+
+**Issue:** AGENTS.md states "13 specialized agents, 50+ skills, 33 commands" while the repo has **16 agents**, **65+ skills**, and **40 commands**. README and other docs also vary. This causes confusion for contributors and users.
+
+**Recommendation:**
+
+- **Single source of truth:** Derive counts (and optionally tables) from the filesystem or a small manifest. Options:
+  - **Option A:** Add a script (e.g. `scripts/ci/catalog.js`) that scans `agents/*.md`, `commands/*.md`, and `skills/*/SKILL.md` and outputs JSON/Markdown. CI and docs can consume this.
+  - **Option B:** Maintain one `docs/catalog.json` (or YAML) that lists agents, commands, and skills with metadata; scripts and docs read from it. Requires discipline to update on add/remove.
+- **Short-term:** Manually sync AGENTS.md, README.md, and CLAUDE.md with actual counts and list any new agents (e.g. chief-of-staff, loop-operator, harness-optimizer) in the agent table.
+
+**Impact:** High — affects first impression and contributor trust.
+
+---
+
+### 1.2 Command → Agent / Skill Map
+
+**Issue:** There is no single machine- or human-readable map of "which command uses which agent(s) or skill(s)." This lives in README tables and individual command `.md` files, which can drift.
+
+**Recommendation:**
+
+- Add a **command registry** (e.g. in `docs/` or as frontmatter in command files) that lists for each command: name, description, primary agent(s), skills referenced. Can be generated from command file content or maintained by hand.
+- Expose a "map" in docs (e.g. `docs/COMMAND-AGENT-MAP.md`) or in the generated catalog for discoverability and for tooling (e.g. "which commands use tdd-guide?").
+
+**Impact:** Medium — improves discoverability and refactoring safety.
+
+---
+
+## 2. Testing and Quality
+
+### 2.1 Test Discovery vs Hardcoded List
+
+**Issue:** `tests/run-all.js` uses a **hardcoded list** of test files. New test files are not run unless someone updates `run-all.js`, so coverage can be incomplete by omission.
+
+**Recommendation:**
+
+- **Glob-based discovery:** Discover test files by pattern (e.g. `**/*.test.js` under `tests/`) and run them, with an optional allowlist/denylist for special cases. This makes new tests automatically part of the suite.
+- Keep a single entry point (`tests/run-all.js`) that runs discovered tests and aggregates results.
+
+**Impact:** High — prevents regression where new tests exist but are never executed.
+
+---
+
+### 2.2 Test Coverage Metrics
+
+**Issue:** There is no coverage tool (e.g. nyc/c8/istanbul). The project cannot assert "80%+ coverage" for its own scripts; coverage is implicit.
+
+**Recommendation:**
+
+- Introduce a coverage tool for Node scripts (e.g. `c8` or `nyc`) and run it in CI. Start with a baseline (e.g. 60%) and raise over time; or at least report coverage in CI without failing so the team can see trends.
+- Focus on `scripts/` (lib + hooks + ci) as the primary target; exclude one-off scripts if needed.
+
+**Impact:** Medium — aligns the project with its own AGENTS.md guidance (80%+ coverage) and surfaces untested paths.
+
+---
+
+## 3. Schema and Validation
+
+### 3.1 Use Hooks JSON Schema in CI
+
+**Issue:** `schemas/hooks.schema.json` exists and defines the hook configuration shape, but `scripts/ci/validate-hooks.js` does **not** use it. Validation is duplicated (VALID_EVENTS, structure) and can drift from the schema.
+
+**Recommendation:**
+
+- Use a JSON Schema validator (e.g. `ajv`) in `validate-hooks.js` to validate `hooks/hooks.json` against `schemas/hooks.schema.json`. Keep the validator as the single source of truth for structure; retain only hook-specific checks (e.g. inline JS syntax) in the script.
+- Ensures schema and validator stay in sync and allows IDE/editor validation via `$schema` in hooks.json.
+
+**Impact:** Medium — reduces drift and improves contributor experience when editing hooks.
+
+---
+
+## 4. Cross-Harness and i18n
+
+### 4.1 Skill/Agent Subset Sync (.agents/skills, .cursor/skills)
+
+**Issue:** `.agents/skills/` (Codex) and `.cursor/skills/` are subsets of `skills/`. Adding or removing a skill in the main repo requires manually updating these subsets, which can be forgotten.
+
+**Recommendation:**
+
+- Document in CONTRIBUTING.md that adding a skill may require updating `.agents/skills` and `.cursor/skills` (and how to do it).
+- Optionally: a CI check or script that compares `skills/` to the subsets and fails or warns if a skill is in one set but not the other when it should be (e.g. by convention or by a small manifest).
+
+**Impact:** Low–Medium — reduces cross-harness drift.
+
+---
+
+### 4.2 Translation Drift (docs/ zh-CN, zh-TW, ja-JP)
+
+**Issue:** Translations in `docs/` duplicate agents, commands, skills. As the English source evolves, translations can become outdated without clear process or tooling.
+
+**Recommendation:**
+
+- Document a **translation process:** when to update (e.g. on release), who owns each locale, and how to detect stale content (e.g. diff file lists or key sections).
+- Consider: translation status file (e.g. `docs/i18n-status.md`) or CI that checks translation file existence/timestamps and warns if English was updated more recently than a translation.
+- Long-term: consider extraction/placeholder format (e.g. i18n keys) so translations reference the same structure as the English source.
+
+**Impact:** Medium — improves experience for non-English users and reduces confusion from outdated translations.
+
+---
+
+## 5. Hooks and Scripts
+
+### 5.1 Hook Runtime Consistency
+
+**Issue:** Most hooks invoke Node scripts via `run-with-flags.js`; one path uses `run-with-flags-shell.sh` + `observe.sh`. The mixed runtime is documented but could be simplified over time.
+
+**Recommendation:**
+
+- Prefer Node for new hooks when possible (cross-platform, single runtime). If shell is required, document why and keep the surface small.
+- Ensure `ECC_HOOK_PROFILE` and `ECC_DISABLED_HOOKS` are respected in all code paths (including shell) so behavior is consistent.
+
+**Impact:** Low — maintains current design; improves if more hooks migrate to Node.
+
+---
+
+## 6. Summary Table
+
+| Area              | Improvement                          | Priority | Effort  |
+|-------------------|--------------------------------------|----------|---------|
+| Doc sync          | Sync AGENTS.md/README counts & table | High     | Low     |
+| Single source     | Catalog script or manifest           | High     | Medium  |
+| Test discovery    | Glob-based test runner               | High     | Low     |
+| Coverage          | Add c8/nyc and CI coverage           | Medium   | Medium  |
+| Hook schema in CI | Validate hooks.json via schema       | Medium   | Low     |
+| Command map       | Command → agent/skill registry       | Medium   | Medium  |
+| Subset sync       | Document/CI for .agents/.cursor       | Low–Med  | Low–Med |
+| Translations      | Process + stale detection             | Medium   | Medium  |
+| Hook runtime      | Prefer Node; document shell use       | Low      | Low     |
+
+---
+
+## 7. Quick Wins (Immediate)
+
+1. **Update AGENTS.md:** Set agent count to 16; add chief-of-staff, loop-operator, harness-optimizer to the agent table; align skill/command counts with repo.
+2. **Test discovery:** Change `run-all.js` to discover `**/*.test.js` under `tests/` (with optional allowlist) so new tests are always run.
+3. **Wire hooks schema:** In `validate-hooks.js`, validate `hooks/hooks.json` against `schemas/hooks.schema.json` using ajv (or similar) and keep only hook-specific checks in the script.
+
+These three can be done in one or two sessions and materially improve consistency and reliability.
diff --git a/docs/COMMAND-AGENT-MAP.md b/docs/COMMAND-AGENT-MAP.md
new file mode 100644
index 00000000..d5e462de
--- /dev/null
+++ b/docs/COMMAND-AGENT-MAP.md
@@ -0,0 +1,61 @@
+# Command → Agent / Skill Map
+
+This document lists each slash command and the primary agent(s) or skills it invokes. Use it to discover which commands use which agents and to keep refactoring consistent.
+
+| Command | Primary agent(s) | Notes |
+|---------|------------------|--------|
+| `/plan` | planner | Implementation planning before code |
+| `/tdd` | tdd-guide | Test-driven development |
+| `/code-review` | code-reviewer | Quality and security review |
+| `/build-fix` | build-error-resolver | Fix build/type errors |
+| `/e2e` | e2e-runner | Playwright E2E tests |
+| `/refactor-clean` | refactor-cleaner | Dead code removal |
+| `/update-docs` | doc-updater | Documentation sync |
+| `/update-codemaps` | doc-updater | Codemaps / architecture docs |
+| `/go-review` | go-reviewer | Go code review |
+| `/go-test` | tdd-guide | Go TDD workflow |
+| `/go-build` | go-build-resolver | Fix Go build errors |
+| `/python-review` | python-reviewer | Python code review |
+| `/harness-audit` | — | Harness scorecard (no single agent) |
+| `/loop-start` | loop-operator | Start autonomous loop |
+| `/loop-status` | loop-operator | Inspect loop status |
+| `/quality-gate` | — | Quality pipeline (hook-like) |
+| `/model-route` | — | Model recommendation (no agent) |
+| `/orchestrate` | planner, tdd-guide, code-reviewer, security-reviewer, architect | Multi-agent handoff |
+| `/multi-plan` | architect (Codex/Gemini prompts) | Multi-model planning |
+| `/multi-execute` | architect / frontend prompts | Multi-model execution |
+| `/multi-backend` | architect | Backend multi-service |
+| `/multi-frontend` | architect | Frontend multi-service |
+| `/multi-workflow` | architect | General multi-service |
+| `/learn` | — | continuous-learning skill, instincts |
+| `/learn-eval` | — | continuous-learning-v2, evaluate then save |
+| `/instinct-status` | — | continuous-learning-v2 |
+| `/instinct-import` | — | continuous-learning-v2 |
+| `/instinct-export` | — | continuous-learning-v2 |
+| `/evolve` | — | continuous-learning-v2, cluster instincts |
+| `/promote` | — | continuous-learning-v2 |
+| `/projects` | — | continuous-learning-v2 |
+| `/skill-create` | — | skill-create-output script, git history |
+| `/checkpoint` | — | verification-loop skill |
+| `/verify` | — | verification-loop skill |
+| `/eval` | — | eval-harness skill |
+| `/test-coverage` | — | Coverage analysis |
+| `/sessions` | — | Session history |
+| `/setup-pm` | — | Package manager setup script |
+| `/claw` | — | NanoClaw CLI (scripts/claw.js) |
+| `/pm2` | — | PM2 service lifecycle |
+| `/security-scan` | security-reviewer (skill) | AgentShield via security-scan skill |
+
+## Skills referenced by commands
+
+- **continuous-learning**, **continuous-learning-v2**: `/learn`, `/learn-eval`, `/instinct-*`, `/evolve`, `/promote`, `/projects`
+- **verification-loop**: `/checkpoint`, `/verify`
+- **eval-harness**: `/eval`
+- **security-scan**: `/security-scan` (runs AgentShield)
+- **strategic-compact**: suggested at compaction points (hooks)
+
+## How to use this map
+
+- **Discoverability:** Find which command triggers which agent (e.g. “use `/code-review` for code-reviewer”).
+- **Refactoring:** When renaming or removing an agent, search this doc and the command files for references.
+- **CI/docs:** The catalog script (`node scripts/ci/catalog.js`) outputs agent/command/skill counts; this map complements it with command–agent relationships.
diff --git a/package-lock.json b/package-lock.json
index 5034650c..7658be1b 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -14,6 +14,8 @@
       },
       "devDependencies": {
         "@eslint/js": "^9.39.2",
+        "ajv": "^8.17.0",
+        "c8": "^10.1.2",
         "eslint": "^9.39.2",
         "globals": "^17.1.0",
         "markdownlint-cli": "^0.47.0"
@@ -22,6 +24,16 @@
         "node": ">=18"
       }
     },
+    "node_modules/@bcoe/v8-coverage": {
+      "version": "1.0.2",
+      "resolved": "https://registry.npmjs.org/@bcoe/v8-coverage/-/v8-coverage-1.0.2.tgz",
+      "integrity": "sha512-6zABk/ECA/QYSCQ1NGiVwwbQerUCZ+TQbp64Q3AgmfNvurHH0j8TtXa1qbShXA6qqkpAj4V5W8pP6mLe1mcMqA==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=18"
+      }
+    },
     "node_modules/@eslint-community/eslint-utils": {
       "version": "4.9.1",
       "resolved": "https://registry.npmjs.org/@eslint-community/eslint-utils/-/eslint-utils-4.9.1.tgz",
@@ -129,6 +141,23 @@
         "url": "https://opencollective.com/eslint"
       }
     },
+    "node_modules/@eslint/eslintrc/node_modules/ajv": {
+      "version": "6.14.0",
+      "resolved": "https://registry.npmjs.org/ajv/-/ajv-6.14.0.tgz",
+      "integrity": "sha512-IWrosm/yrn43eiKqkfkHis7QioDleaXQHdDVPKg0FSwwd/DuvyX79TZnFOnYpB7dcsFAMmtFztZuXPDvSePkFw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "fast-deep-equal": "^3.1.1",
+        "fast-json-stable-stringify": "^2.0.0",
+        "json-schema-traverse": "^0.4.1",
+        "uri-js": "^4.2.2"
+      },
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/epoberezkin"
+      }
+    },
     "node_modules/@eslint/eslintrc/node_modules/globals": {
       "version": "14.0.0",
       "resolved": "https://registry.npmjs.org/globals/-/globals-14.0.0.tgz",
@@ -142,6 +171,13 @@
         "url": "https://github.com/sponsors/sindresorhus"
       }
     },
+    "node_modules/@eslint/eslintrc/node_modules/json-schema-traverse": {
+      "version": "0.4.1",
+      "resolved": "https://registry.npmjs.org/json-schema-traverse/-/json-schema-traverse-0.4.1.tgz",
+      "integrity": "sha512-xbbCH5dCYU5T8LcEhhuh7HJ88HXuW3qsI3Y0zOZFKfZEHcpWiHU/Jxzk629Brsab/mMiHQti9wMP+845RPe3Vg==",
+      "dev": true,
+      "license": "MIT"
+    },
     "node_modules/@eslint/js": {
       "version": "9.39.2",
       "resolved": "https://registry.npmjs.org/@eslint/js/-/js-9.39.2.tgz",
@@ -254,6 +290,98 @@
         "node": "20 || >=22"
       }
     },
+    "node_modules/@isaacs/cliui": {
+      "version": "8.0.2",
+      "resolved": "https://registry.npmjs.org/@isaacs/cliui/-/cliui-8.0.2.tgz",
+      "integrity": "sha512-O8jcjabXaleOG9DQ0+ARXWZBTfnP4WNAqzuiJK7ll44AmxGKv/J2M4TPjxjY3znBCfvBXFzucm1twdyFybFqEA==",
+      "dev": true,
+      "license": "ISC",
+      "dependencies": {
+        "string-width": "^5.1.2",
+        "string-width-cjs": "npm:string-width@^4.2.0",
+        "strip-ansi": "^7.0.1",
+        "strip-ansi-cjs": "npm:strip-ansi@^6.0.1",
+        "wrap-ansi": "^8.1.0",
+        "wrap-ansi-cjs": "npm:wrap-ansi@^7.0.0"
+      },
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/@isaacs/cliui/node_modules/emoji-regex": {
+      "version": "9.2.2",
+      "resolved": "https://registry.npmjs.org/emoji-regex/-/emoji-regex-9.2.2.tgz",
+      "integrity": "sha512-L18DaJsXSUk2+42pv8mLs5jJT2hqFkFE4j21wOmgbUqsZ2hL72NsUU785g9RXgo3s0ZNgVl42TiHp3ZtOv/Vyg==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/@isaacs/cliui/node_modules/string-width": {
+      "version": "5.1.2",
+      "resolved": "https://registry.npmjs.org/string-width/-/string-width-5.1.2.tgz",
+      "integrity": "sha512-HnLOCR3vjcY8beoNLtcjZ5/nxn2afmME6lhrDrebokqMap+XbeW8n9TXpPDOqdGK5qcI3oT0GKTW6wC7EMiVqA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "eastasianwidth": "^0.2.0",
+        "emoji-regex": "^9.2.2",
+        "strip-ansi": "^7.0.1"
+      },
+      "engines": {
+        "node": ">=12"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
+    "node_modules/@istanbuljs/schema": {
+      "version": "0.1.3",
+      "resolved": "https://registry.npmjs.org/@istanbuljs/schema/-/schema-0.1.3.tgz",
+      "integrity": "sha512-ZXRY4jNvVgSVQ8DL3LTcakaAtXwTVUxE81hslsyD2AtoXW/wVob10HkOJ1X/pAlcI7D+2YoZKg5do8G/w6RYgA==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/@jridgewell/resolve-uri": {
+      "version": "3.1.2",
+      "resolved": "https://registry.npmjs.org/@jridgewell/resolve-uri/-/resolve-uri-3.1.2.tgz",
+      "integrity": "sha512-bRISgCIjP20/tbWSPWMEi54QVPRZExkuD9lJL+UIxUKtwVJA8wW1Trb1jMs1RFXo1CBTNZ/5hpC9QvmKWdopKw==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=6.0.0"
+      }
+    },
+    "node_modules/@jridgewell/sourcemap-codec": {
+      "version": "1.5.5",
+      "resolved": "https://registry.npmjs.org/@jridgewell/sourcemap-codec/-/sourcemap-codec-1.5.5.tgz",
+      "integrity": "sha512-cYQ9310grqxueWbl+WuIUIaiUaDcj7WOq5fVhEljNVgRfOUhY9fy2zTvfoqWsnebh8Sl70VScFbICvJnLKB0Og==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/@jridgewell/trace-mapping": {
+      "version": "0.3.31",
+      "resolved": "https://registry.npmjs.org/@jridgewell/trace-mapping/-/trace-mapping-0.3.31.tgz",
+      "integrity": "sha512-zzNR+SdQSDJzc8joaeP8QQoCQr8NuYx2dIIytl1QeBEZHJ9uW6hebsrYgbz8hJwUQao3TWCMtmfV8Nu1twOLAw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "@jridgewell/resolve-uri": "^3.1.0",
+        "@jridgewell/sourcemap-codec": "^1.4.14"
+      }
+    },
+    "node_modules/@pkgjs/parseargs": {
+      "version": "0.11.0",
+      "resolved": "https://registry.npmjs.org/@pkgjs/parseargs/-/parseargs-0.11.0.tgz",
+      "integrity": "sha512-+1VkjdD0QBLPodGrJUeqarH8VAIvQODIbwh9XpP5Syisf7YoQgsJKPNFoqqLQlu+VQ/tVSshMR6loPMn8U+dPg==",
+      "dev": true,
+      "license": "MIT",
+      "optional": true,
+      "engines": {
+        "node": ">=14"
+      }
+    },
     "node_modules/@types/debug": {
       "version": "4.1.12",
       "resolved": "https://registry.npmjs.org/@types/debug/-/debug-4.1.12.tgz",
@@ -271,6 +399,13 @@
       "dev": true,
       "license": "MIT"
     },
+    "node_modules/@types/istanbul-lib-coverage": {
+      "version": "2.0.6",
+      "resolved": "https://registry.npmjs.org/@types/istanbul-lib-coverage/-/istanbul-lib-coverage-2.0.6.tgz",
+      "integrity": "sha512-2QF/t/auWm0lsy8XtKVPG19v3sSOQlJe/YHZgfjb/KBBHOGSV+J2q/S671rcq9uTBrLAXmZpqJiaQbMT+zNU1w==",
+      "dev": true,
+      "license": "MIT"
+    },
     "node_modules/@types/json-schema": {
       "version": "7.0.15",
       "resolved": "https://registry.npmjs.org/@types/json-schema/-/json-schema-7.0.15.tgz",
@@ -305,7 +440,6 @@
       "integrity": "sha512-NZyJarBfL7nWwIq+FDL6Zp/yHEhePMNnnJ0y3qfieCrmNvYct8uvtiV41UvlSe6apAfk0fY1FbWx+NwfmpvtTg==",
       "dev": true,
       "license": "MIT",
-      "peer": true,
       "bin": {
         "acorn": "bin/acorn"
       },
@@ -324,16 +458,16 @@
       }
     },
     "node_modules/ajv": {
-      "version": "6.12.6",
-      "resolved": "https://registry.npmjs.org/ajv/-/ajv-6.12.6.tgz",
-      "integrity": "sha512-j3fVLgvTo527anyYyJOGTYJbG+vnnQYvE0m5mmkc1TK+nxAppkCLMIL0aZ4dblVCNoGShhm+kzE4ZUykBoMg4g==",
+      "version": "8.18.0",
+      "resolved": "https://registry.npmjs.org/ajv/-/ajv-8.18.0.tgz",
+      "integrity": "sha512-PlXPeEWMXMZ7sPYOHqmDyCJzcfNrUr3fGNKtezX14ykXOEIvyK81d+qydx89KY5O71FKMPaQ2vBfBFI5NHR63A==",
       "dev": true,
       "license": "MIT",
       "dependencies": {
-        "fast-deep-equal": "^3.1.1",
-        "fast-json-stable-stringify": "^2.0.0",
-        "json-schema-traverse": "^0.4.1",
-        "uri-js": "^4.2.2"
+        "fast-deep-equal": "^3.1.3",
+        "fast-uri": "^3.0.1",
+        "json-schema-traverse": "^1.0.0",
+        "require-from-string": "^2.0.2"
       },
       "funding": {
         "type": "github",
@@ -394,6 +528,40 @@
         "concat-map": "0.0.1"
       }
     },
+    "node_modules/c8": {
+      "version": "10.1.3",
+      "resolved": "https://registry.npmjs.org/c8/-/c8-10.1.3.tgz",
+      "integrity": "sha512-LvcyrOAaOnrrlMpW22n690PUvxiq4Uf9WMhQwNJ9vgagkL/ph1+D4uvjvDA5XCbykrc0sx+ay6pVi9YZ1GnhyA==",
+      "dev": true,
+      "license": "ISC",
+      "dependencies": {
+        "@bcoe/v8-coverage": "^1.0.1",
+        "@istanbuljs/schema": "^0.1.3",
+        "find-up": "^5.0.0",
+        "foreground-child": "^3.1.1",
+        "istanbul-lib-coverage": "^3.2.0",
+        "istanbul-lib-report": "^3.0.1",
+        "istanbul-reports": "^3.1.6",
+        "test-exclude": "^7.0.1",
+        "v8-to-istanbul": "^9.0.0",
+        "yargs": "^17.7.2",
+        "yargs-parser": "^21.1.1"
+      },
+      "bin": {
+        "c8": "bin/c8.js"
+      },
+      "engines": {
+        "node": ">=18"
+      },
+      "peerDependencies": {
+        "monocart-coverage-reports": "^2"
+      },
+      "peerDependenciesMeta": {
+        "monocart-coverage-reports": {
+          "optional": true
+        }
+      }
+    },
     "node_modules/callsites": {
       "version": "3.1.0",
       "resolved": "https://registry.npmjs.org/callsites/-/callsites-3.1.0.tgz",
@@ -454,6 +622,77 @@
         "url": "https://github.com/sponsors/wooorm"
       }
     },
+    "node_modules/cliui": {
+      "version": "8.0.1",
+      "resolved": "https://registry.npmjs.org/cliui/-/cliui-8.0.1.tgz",
+      "integrity": "sha512-BSeNnyus75C4//NQ9gQt1/csTXyo/8Sb+afLAkzAptFuMsod9HFokGNudZpi/oQV73hnVK+sR+5PVRMd+Dr7YQ==",
+      "dev": true,
+      "license": "ISC",
+      "dependencies": {
+        "string-width": "^4.2.0",
+        "strip-ansi": "^6.0.1",
+        "wrap-ansi": "^7.0.0"
+      },
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/cliui/node_modules/ansi-regex": {
+      "version": "5.0.1",
+      "resolved": "https://registry.npmjs.org/ansi-regex/-/ansi-regex-5.0.1.tgz",
+      "integrity": "sha512-quJQXlTSUGL2LH9SUXo8VwsY4soanhgo6LNSm84E1LBcE8s3O0wpdiRzyR9z/ZZJMlMWv37qOOb9pdJlMUEKFQ==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/cliui/node_modules/string-width": {
+      "version": "4.2.3",
+      "resolved": "https://registry.npmjs.org/string-width/-/string-width-4.2.3.tgz",
+      "integrity": "sha512-wKyQRQpjJ0sIp62ErSZdGsjMJWsap5oRNihHhu6G7JVO/9jIB6UyevL+tXuOqrng8j/cxKTWyWUwvSTriiZz/g==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "emoji-regex": "^8.0.0",
+        "is-fullwidth-code-point": "^3.0.0",
+        "strip-ansi": "^6.0.1"
+      },
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/cliui/node_modules/strip-ansi": {
+      "version": "6.0.1",
+      "resolved": "https://registry.npmjs.org/strip-ansi/-/strip-ansi-6.0.1.tgz",
+      "integrity": "sha512-Y38VPSHcqkFrCpFnQ9vuSXmquuv5oXOKpGeT6aGrr3o3Gc9AlVa6JBfUSOCnbxGGZF+/0ooI7KrPuUSztUdU5A==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "ansi-regex": "^5.0.1"
+      },
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/cliui/node_modules/wrap-ansi": {
+      "version": "7.0.0",
+      "resolved": "https://registry.npmjs.org/wrap-ansi/-/wrap-ansi-7.0.0.tgz",
+      "integrity": "sha512-YVGIj2kamLSTxw6NsZjoBxfSwsn0ycdesmc4p+Q21c5zPuZ1pl+NfxVdxPtdHvmNVOQ6XSYG4AUtyt/Fi7D16Q==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "ansi-styles": "^4.0.0",
+        "string-width": "^4.1.0",
+        "strip-ansi": "^6.0.0"
+      },
+      "engines": {
+        "node": ">=10"
+      },
+      "funding": {
+        "url": "https://github.com/chalk/wrap-ansi?sponsor=1"
+      }
+    },
     "node_modules/color-convert": {
       "version": "2.0.1",
       "resolved": "https://registry.npmjs.org/color-convert/-/color-convert-2.0.1.tgz",
@@ -491,6 +730,13 @@
       "dev": true,
       "license": "MIT"
     },
+    "node_modules/convert-source-map": {
+      "version": "2.0.0",
+      "resolved": "https://registry.npmjs.org/convert-source-map/-/convert-source-map-2.0.0.tgz",
+      "integrity": "sha512-Kvp459HrV2FEJ1CAsi1Ku+MY3kasH19TFykTz2xWmMeq6bk2NU3XXvfJ+Q61m0xktWwt+1HSYf3JZsTms3aRJg==",
+      "dev": true,
+      "license": "MIT"
+    },
     "node_modules/cross-spawn": {
       "version": "7.0.6",
       "resolved": "https://registry.npmjs.org/cross-spawn/-/cross-spawn-7.0.6.tgz",
@@ -579,6 +825,20 @@
         "url": "https://github.com/sponsors/wooorm"
       }
     },
+    "node_modules/eastasianwidth": {
+      "version": "0.2.0",
+      "resolved": "https://registry.npmjs.org/eastasianwidth/-/eastasianwidth-0.2.0.tgz",
+      "integrity": "sha512-I88TYZWc9XiYHRQ4/3c5rjjfgkjhLyW2luGIheGERbNQ6OY7yTybanSpDXZa8y7VUP9YmDcYa+eyq4ca7iLqWA==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/emoji-regex": {
+      "version": "8.0.0",
+      "resolved": "https://registry.npmjs.org/emoji-regex/-/emoji-regex-8.0.0.tgz",
+      "integrity": "sha512-MSjYzcWNOA0ewAHpz0MxpYFvwg6yjy1NG3xteoqz644VCo/RPgnr1/GGt+ic3iJTzQ8Eu3TdM14SawnVUmGE6A==",
+      "dev": true,
+      "license": "MIT"
+    },
     "node_modules/entities": {
       "version": "4.5.0",
       "resolved": "https://registry.npmjs.org/entities/-/entities-4.5.0.tgz",
@@ -592,6 +852,16 @@
         "url": "https://github.com/fb55/entities?sponsor=1"
       }
     },
+    "node_modules/escalade": {
+      "version": "3.2.0",
+      "resolved": "https://registry.npmjs.org/escalade/-/escalade-3.2.0.tgz",
+      "integrity": "sha512-WUj2qlxaQtO4g6Pq5c29GTcWGDyd8itL8zTlipgECz3JesAiiOKotd8JU6otB3PACgG6xkJUyVhboMS+bje/jA==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=6"
+      }
+    },
     "node_modules/escape-string-regexp": {
       "version": "4.0.0",
       "resolved": "https://registry.npmjs.org/escape-string-regexp/-/escape-string-regexp-4.0.0.tgz",
@@ -611,7 +881,6 @@
       "integrity": "sha512-LEyamqS7W5HB3ujJyvi0HQK/dtVINZvd5mAAp9eT5S/ujByGjiZLCzPcHVzuXbpJDJF/cxwHlfceVUDZ2lnSTw==",
       "dev": true,
       "license": "MIT",
-      "peer": true,
       "dependencies": {
         "@eslint-community/eslint-utils": "^4.8.0",
         "@eslint-community/regexpp": "^4.12.1",
@@ -696,6 +965,30 @@
         "url": "https://opencollective.com/eslint"
       }
     },
+    "node_modules/eslint/node_modules/ajv": {
+      "version": "6.14.0",
+      "resolved": "https://registry.npmjs.org/ajv/-/ajv-6.14.0.tgz",
+      "integrity": "sha512-IWrosm/yrn43eiKqkfkHis7QioDleaXQHdDVPKg0FSwwd/DuvyX79TZnFOnYpB7dcsFAMmtFztZuXPDvSePkFw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "fast-deep-equal": "^3.1.1",
+        "fast-json-stable-stringify": "^2.0.0",
+        "json-schema-traverse": "^0.4.1",
+        "uri-js": "^4.2.2"
+      },
+      "funding": {
+        "type": "github",
+        "url": "https://github.com/sponsors/epoberezkin"
+      }
+    },
+    "node_modules/eslint/node_modules/json-schema-traverse": {
+      "version": "0.4.1",
+      "resolved": "https://registry.npmjs.org/json-schema-traverse/-/json-schema-traverse-0.4.1.tgz",
+      "integrity": "sha512-xbbCH5dCYU5T8LcEhhuh7HJ88HXuW3qsI3Y0zOZFKfZEHcpWiHU/Jxzk629Brsab/mMiHQti9wMP+845RPe3Vg==",
+      "dev": true,
+      "license": "MIT"
+    },
     "node_modules/espree": {
       "version": "10.4.0",
       "resolved": "https://registry.npmjs.org/espree/-/espree-10.4.0.tgz",
@@ -781,6 +1074,23 @@
       "dev": true,
       "license": "MIT"
     },
+    "node_modules/fast-uri": {
+      "version": "3.1.0",
+      "resolved": "https://registry.npmjs.org/fast-uri/-/fast-uri-3.1.0.tgz",
+      "integrity": "sha512-iPeeDKJSWf4IEOasVVrknXpaBV0IApz/gp7S2bb7Z4Lljbl2MGJRqInZiUrQwV16cpzw/D3S5j5Julj/gT52AA==",
+      "dev": true,
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/fastify"
+        },
+        {
+          "type": "opencollective",
+          "url": "https://opencollective.com/fastify"
+        }
+      ],
+      "license": "BSD-3-Clause"
+    },
     "node_modules/fdir": {
       "version": "6.5.0",
       "resolved": "https://registry.npmjs.org/fdir/-/fdir-6.5.0.tgz",
@@ -850,6 +1160,33 @@
       "dev": true,
       "license": "ISC"
     },
+    "node_modules/foreground-child": {
+      "version": "3.3.1",
+      "resolved": "https://registry.npmjs.org/foreground-child/-/foreground-child-3.3.1.tgz",
+      "integrity": "sha512-gIXjKqtFuWEgzFRJA9WCQeSJLZDjgJUOMCMzxtvFq/37KojM1BFGufqsCy0r4qSQmYLsZYMeyRqzIWOMup03sw==",
+      "dev": true,
+      "license": "ISC",
+      "dependencies": {
+        "cross-spawn": "^7.0.6",
+        "signal-exit": "^4.0.1"
+      },
+      "engines": {
+        "node": ">=14"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/isaacs"
+      }
+    },
+    "node_modules/get-caller-file": {
+      "version": "2.0.5",
+      "resolved": "https://registry.npmjs.org/get-caller-file/-/get-caller-file-2.0.5.tgz",
+      "integrity": "sha512-DyFP3BM/3YHTQOCUL/w0OZHR0lpKeGrxotcHWcqNEdnltqFwXVfhEBQ94eIo34AfQpo0rGki4cyIiftY06h2Fg==",
+      "dev": true,
+      "license": "ISC",
+      "engines": {
+        "node": "6.* || 8.* || >= 10.*"
+      }
+    },
     "node_modules/get-east-asian-width": {
       "version": "1.4.0",
       "resolved": "https://registry.npmjs.org/get-east-asian-width/-/get-east-asian-width-1.4.0.tgz",
@@ -863,6 +1200,28 @@
         "url": "https://github.com/sponsors/sindresorhus"
       }
     },
+    "node_modules/glob": {
+      "version": "10.5.0",
+      "resolved": "https://registry.npmjs.org/glob/-/glob-10.5.0.tgz",
+      "integrity": "sha512-DfXN8DfhJ7NH3Oe7cFmu3NCu1wKbkReJ8TorzSAFbSKrlNaQSKfIzqYqVY8zlbs2NLBbWpRiU52GX2PbaBVNkg==",
+      "deprecated": "Old versions of glob are not supported, and contain widely publicized security vulnerabilities, which have been fixed in the current version. Please update. Support for old versions may be purchased (at exorbitant rates) by contacting i@izs.me",
+      "dev": true,
+      "license": "ISC",
+      "dependencies": {
+        "foreground-child": "^3.1.0",
+        "jackspeak": "^3.1.2",
+        "minimatch": "^9.0.4",
+        "minipass": "^7.1.2",
+        "package-json-from-dist": "^1.0.0",
+        "path-scurry": "^1.11.1"
+      },
+      "bin": {
+        "glob": "dist/esm/bin.mjs"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/isaacs"
+      }
+    },
     "node_modules/glob-parent": {
       "version": "6.0.2",
       "resolved": "https://registry.npmjs.org/glob-parent/-/glob-parent-6.0.2.tgz",
@@ -876,6 +1235,32 @@
         "node": ">=10.13.0"
       }
     },
+    "node_modules/glob/node_modules/brace-expansion": {
+      "version": "2.0.2",
+      "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-2.0.2.tgz",
+      "integrity": "sha512-Jt0vHyM+jmUBqojB7E1NIYadt0vI0Qxjxd2TErW94wDz+E2LAm5vKMXXwg6ZZBTHPuUlDgQHKXvjGBdfcF1ZDQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "balanced-match": "^1.0.0"
+      }
+    },
+    "node_modules/glob/node_modules/minimatch": {
+      "version": "9.0.9",
+      "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-9.0.9.tgz",
+      "integrity": "sha512-OBwBN9AL4dqmETlpS2zasx+vTeWclWzkblfZk7KTA5j3jeOONz/tRCnZomUyvNg83wL5Zv9Ss6HMJXAgL8R2Yg==",
+      "dev": true,
+      "license": "ISC",
+      "dependencies": {
+        "brace-expansion": "^2.0.2"
+      },
+      "engines": {
+        "node": ">=16 || 14 >=14.17"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/isaacs"
+      }
+    },
     "node_modules/globals": {
       "version": "17.1.0",
       "resolved": "https://registry.npmjs.org/globals/-/globals-17.1.0.tgz",
@@ -899,6 +1284,13 @@
         "node": ">=8"
       }
     },
+    "node_modules/html-escaper": {
+      "version": "2.0.2",
+      "resolved": "https://registry.npmjs.org/html-escaper/-/html-escaper-2.0.2.tgz",
+      "integrity": "sha512-H2iMtd0I4Mt5eYiapRdIDjp+XzelXQ0tFE4JS7YFwFevXXMmOp9myNrUvCg0D6ws8iqkRPBfKHgbwig1SmlLfg==",
+      "dev": true,
+      "license": "MIT"
+    },
     "node_modules/ignore": {
       "version": "5.3.2",
       "resolved": "https://registry.npmjs.org/ignore/-/ignore-5.3.2.tgz",
@@ -993,6 +1385,16 @@
         "node": ">=0.10.0"
       }
     },
+    "node_modules/is-fullwidth-code-point": {
+      "version": "3.0.0",
+      "resolved": "https://registry.npmjs.org/is-fullwidth-code-point/-/is-fullwidth-code-point-3.0.0.tgz",
+      "integrity": "sha512-zymm5+u+sCsSWyD9qNaejV3DFvhCKclKdizYaJUuHA83RLjb7nSuGnddCHGv0hk+KY7BMAlsWeK4Ueg6EV6XQg==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=8"
+      }
+    },
     "node_modules/is-glob": {
       "version": "4.0.3",
       "resolved": "https://registry.npmjs.org/is-glob/-/is-glob-4.0.3.tgz",
@@ -1024,6 +1426,61 @@
       "dev": true,
       "license": "ISC"
     },
+    "node_modules/istanbul-lib-coverage": {
+      "version": "3.2.2",
+      "resolved": "https://registry.npmjs.org/istanbul-lib-coverage/-/istanbul-lib-coverage-3.2.2.tgz",
+      "integrity": "sha512-O8dpsF+r0WV/8MNRKfnmrtCWhuKjxrq2w+jpzBL5UZKTi2LeVWnWOmWRxFlesJONmc+wLAGvKQZEOanko0LFTg==",
+      "dev": true,
+      "license": "BSD-3-Clause",
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/istanbul-lib-report": {
+      "version": "3.0.1",
+      "resolved": "https://registry.npmjs.org/istanbul-lib-report/-/istanbul-lib-report-3.0.1.tgz",
+      "integrity": "sha512-GCfE1mtsHGOELCU8e/Z7YWzpmybrx/+dSTfLrvY8qRmaY6zXTKWn6WQIjaAFw069icm6GVMNkgu0NzI4iPZUNw==",
+      "dev": true,
+      "license": "BSD-3-Clause",
+      "dependencies": {
+        "istanbul-lib-coverage": "^3.0.0",
+        "make-dir": "^4.0.0",
+        "supports-color": "^7.1.0"
+      },
+      "engines": {
+        "node": ">=10"
+      }
+    },
+    "node_modules/istanbul-reports": {
+      "version": "3.2.0",
+      "resolved": "https://registry.npmjs.org/istanbul-reports/-/istanbul-reports-3.2.0.tgz",
+      "integrity": "sha512-HGYWWS/ehqTV3xN10i23tkPkpH46MLCIMFNCaaKNavAXTF1RkqxawEPtnjnGZ6XKSInBKkiOA5BKS+aZiY3AvA==",
+      "dev": true,
+      "license": "BSD-3-Clause",
+      "dependencies": {
+        "html-escaper": "^2.0.0",
+        "istanbul-lib-report": "^3.0.0"
+      },
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/jackspeak": {
+      "version": "3.4.3",
+      "resolved": "https://registry.npmjs.org/jackspeak/-/jackspeak-3.4.3.tgz",
+      "integrity": "sha512-OGlZQpz2yfahA/Rd1Y8Cd9SIEsqvXkLVoSw/cgwhnhFMDbsQFeZYoJJ7bIZBS9BcamUW96asq/npPWugM+RQBw==",
+      "dev": true,
+      "license": "BlueOak-1.0.0",
+      "dependencies": {
+        "@isaacs/cliui": "^8.0.2"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/isaacs"
+      },
+      "optionalDependencies": {
+        "@pkgjs/parseargs": "^0.11.0"
+      }
+    },
     "node_modules/js-yaml": {
       "version": "4.1.1",
       "resolved": "https://registry.npmjs.org/js-yaml/-/js-yaml-4.1.1.tgz",
@@ -1045,9 +1502,9 @@
       "license": "MIT"
     },
     "node_modules/json-schema-traverse": {
-      "version": "0.4.1",
-      "resolved": "https://registry.npmjs.org/json-schema-traverse/-/json-schema-traverse-0.4.1.tgz",
-      "integrity": "sha512-xbbCH5dCYU5T8LcEhhuh7HJ88HXuW3qsI3Y0zOZFKfZEHcpWiHU/Jxzk629Brsab/mMiHQti9wMP+845RPe3Vg==",
+      "version": "1.0.0",
+      "resolved": "https://registry.npmjs.org/json-schema-traverse/-/json-schema-traverse-1.0.0.tgz",
+      "integrity": "sha512-NM8/P9n3XjXhIZn1lLhkFaACTOURQXjWhV4BA/RnOv8xvgqtqpAX9IO4mRQxSx1Rlo4tqzeqb0sOlruaOy3dug==",
       "dev": true,
       "license": "MIT"
     },
@@ -1159,6 +1616,29 @@
       "dev": true,
       "license": "MIT"
     },
+    "node_modules/lru-cache": {
+      "version": "10.4.3",
+      "resolved": "https://registry.npmjs.org/lru-cache/-/lru-cache-10.4.3.tgz",
+      "integrity": "sha512-JNAzZcXrCt42VGLuYz0zfAzDfAvJWW6AfYlDBQyDV5DClI2m5sAmK+OIO7s59XfsRsWHp02jAJrRadPRGTt6SQ==",
+      "dev": true,
+      "license": "ISC"
+    },
+    "node_modules/make-dir": {
+      "version": "4.0.0",
+      "resolved": "https://registry.npmjs.org/make-dir/-/make-dir-4.0.0.tgz",
+      "integrity": "sha512-hXdUTZYIVOt1Ex//jAQi+wTZZpUpwBj/0QsOzqegb3rGMMeJiSEu5xLHnYfBrRV4RH2+OCSOO95Is/7x1WJ4bw==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "semver": "^7.5.3"
+      },
+      "engines": {
+        "node": ">=10"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
     "node_modules/markdown-it": {
       "version": "14.1.0",
       "resolved": "https://registry.npmjs.org/markdown-it/-/markdown-it-14.1.0.tgz",
@@ -1820,6 +2300,16 @@
         "url": "https://github.com/sponsors/ljharb"
       }
     },
+    "node_modules/minipass": {
+      "version": "7.1.3",
+      "resolved": "https://registry.npmjs.org/minipass/-/minipass-7.1.3.tgz",
+      "integrity": "sha512-tEBHqDnIoM/1rXME1zgka9g6Q2lcoCkxHLuc7ODJ5BxbP5d4c2Z5cGgtXAku59200Cx7diuHTOYfSBD8n6mm8A==",
+      "dev": true,
+      "license": "BlueOak-1.0.0",
+      "engines": {
+        "node": ">=16 || 14 >=14.17"
+      }
+    },
     "node_modules/ms": {
       "version": "2.1.3",
       "resolved": "https://registry.npmjs.org/ms/-/ms-2.1.3.tgz",
@@ -1884,6 +2374,13 @@
         "url": "https://github.com/sponsors/sindresorhus"
       }
     },
+    "node_modules/package-json-from-dist": {
+      "version": "1.0.1",
+      "resolved": "https://registry.npmjs.org/package-json-from-dist/-/package-json-from-dist-1.0.1.tgz",
+      "integrity": "sha512-UEZIS3/by4OC8vL3P2dTXRETpebLI2NiI5vIrjaD/5UtrkFX/tNbwjTSRAGC/+7CAo2pIcBaRgWmcBBHcsaCIw==",
+      "dev": true,
+      "license": "BlueOak-1.0.0"
+    },
     "node_modules/parent-module": {
       "version": "1.0.1",
       "resolved": "https://registry.npmjs.org/parent-module/-/parent-module-1.0.1.tgz",
@@ -1937,13 +2434,29 @@
         "node": ">=8"
       }
     },
+    "node_modules/path-scurry": {
+      "version": "1.11.1",
+      "resolved": "https://registry.npmjs.org/path-scurry/-/path-scurry-1.11.1.tgz",
+      "integrity": "sha512-Xa4Nw17FS9ApQFJ9umLiJS4orGjm7ZzwUrwamcGQuHSzDyth9boKDaycYdDcZDuqYATXw4HFXgaqWTctW/v1HA==",
+      "dev": true,
+      "license": "BlueOak-1.0.0",
+      "dependencies": {
+        "lru-cache": "^10.2.0",
+        "minipass": "^5.0.0 || ^6.0.2 || ^7.0.0"
+      },
+      "engines": {
+        "node": ">=16 || 14 >=14.18"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/isaacs"
+      }
+    },
     "node_modules/picomatch": {
       "version": "4.0.3",
       "resolved": "https://registry.npmjs.org/picomatch/-/picomatch-4.0.3.tgz",
       "integrity": "sha512-5gTmgEY/sqK6gFXLIsQNH19lWb4ebPDLA4SdLP7dsWkIXHWlG66oPuVvXSGFPppYZz8ZDZq0dYYrbHfBCVUb1Q==",
       "dev": true,
       "license": "MIT",
-      "peer": true,
       "engines": {
         "node": ">=12"
       },
@@ -1981,6 +2494,26 @@
         "node": ">=6"
       }
     },
+    "node_modules/require-directory": {
+      "version": "2.1.1",
+      "resolved": "https://registry.npmjs.org/require-directory/-/require-directory-2.1.1.tgz",
+      "integrity": "sha512-fGxEI7+wsG9xrvdjsrlmL22OMTTiHRwAMroiEeMgq8gzoLC/PQr7RsRDSTLUg/bZAZtF+TVIkHc6/4RIKrui+Q==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=0.10.0"
+      }
+    },
+    "node_modules/require-from-string": {
+      "version": "2.0.2",
+      "resolved": "https://registry.npmjs.org/require-from-string/-/require-from-string-2.0.2.tgz",
+      "integrity": "sha512-Xf0nWe6RseziFMu+Ap9biiUbmplq6S9/p+7w7YXP/JBHhrUDDUhwa+vANyubuqfZWTveU//DYVGsDG7RKL/vEw==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=0.10.0"
+      }
+    },
     "node_modules/resolve-from": {
       "version": "4.0.0",
       "resolved": "https://registry.npmjs.org/resolve-from/-/resolve-from-4.0.0.tgz",
@@ -2007,6 +2540,19 @@
         "run-con": "cli.js"
       }
     },
+    "node_modules/semver": {
+      "version": "7.7.4",
+      "resolved": "https://registry.npmjs.org/semver/-/semver-7.7.4.tgz",
+      "integrity": "sha512-vFKC2IEtQnVhpT78h1Yp8wzwrf8CM+MzKMHGJZfBtzhZNycRFnXsHk6E5TxIkkMsgNS7mdX3AGB7x2QM2di4lA==",
+      "dev": true,
+      "license": "ISC",
+      "bin": {
+        "semver": "bin/semver.js"
+      },
+      "engines": {
+        "node": ">=10"
+      }
+    },
     "node_modules/shebang-command": {
       "version": "2.0.0",
       "resolved": "https://registry.npmjs.org/shebang-command/-/shebang-command-2.0.0.tgz",
@@ -2030,6 +2576,19 @@
         "node": ">=8"
       }
     },
+    "node_modules/signal-exit": {
+      "version": "4.1.0",
+      "resolved": "https://registry.npmjs.org/signal-exit/-/signal-exit-4.1.0.tgz",
+      "integrity": "sha512-bzyZ1e88w9O1iNJbKnOlvYTrWPDl46O1bG0D3XInv+9tkPrxrN8jUUTiFlDkkmKWgn1M6CfIA13SuGqOa9Korw==",
+      "dev": true,
+      "license": "ISC",
+      "engines": {
+        "node": ">=14"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/isaacs"
+      }
+    },
     "node_modules/smol-toml": {
       "version": "1.5.2",
       "resolved": "https://registry.npmjs.org/smol-toml/-/smol-toml-1.5.2.tgz",
@@ -2060,6 +2619,45 @@
         "url": "https://github.com/sponsors/sindresorhus"
       }
     },
+    "node_modules/string-width-cjs": {
+      "name": "string-width",
+      "version": "4.2.3",
+      "resolved": "https://registry.npmjs.org/string-width/-/string-width-4.2.3.tgz",
+      "integrity": "sha512-wKyQRQpjJ0sIp62ErSZdGsjMJWsap5oRNihHhu6G7JVO/9jIB6UyevL+tXuOqrng8j/cxKTWyWUwvSTriiZz/g==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "emoji-regex": "^8.0.0",
+        "is-fullwidth-code-point": "^3.0.0",
+        "strip-ansi": "^6.0.1"
+      },
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/string-width-cjs/node_modules/ansi-regex": {
+      "version": "5.0.1",
+      "resolved": "https://registry.npmjs.org/ansi-regex/-/ansi-regex-5.0.1.tgz",
+      "integrity": "sha512-quJQXlTSUGL2LH9SUXo8VwsY4soanhgo6LNSm84E1LBcE8s3O0wpdiRzyR9z/ZZJMlMWv37qOOb9pdJlMUEKFQ==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/string-width-cjs/node_modules/strip-ansi": {
+      "version": "6.0.1",
+      "resolved": "https://registry.npmjs.org/strip-ansi/-/strip-ansi-6.0.1.tgz",
+      "integrity": "sha512-Y38VPSHcqkFrCpFnQ9vuSXmquuv5oXOKpGeT6aGrr3o3Gc9AlVa6JBfUSOCnbxGGZF+/0ooI7KrPuUSztUdU5A==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "ansi-regex": "^5.0.1"
+      },
+      "engines": {
+        "node": ">=8"
+      }
+    },
     "node_modules/strip-ansi": {
       "version": "7.1.2",
       "resolved": "https://registry.npmjs.org/strip-ansi/-/strip-ansi-7.1.2.tgz",
@@ -2076,6 +2674,30 @@
         "url": "https://github.com/chalk/strip-ansi?sponsor=1"
       }
     },
+    "node_modules/strip-ansi-cjs": {
+      "name": "strip-ansi",
+      "version": "6.0.1",
+      "resolved": "https://registry.npmjs.org/strip-ansi/-/strip-ansi-6.0.1.tgz",
+      "integrity": "sha512-Y38VPSHcqkFrCpFnQ9vuSXmquuv5oXOKpGeT6aGrr3o3Gc9AlVa6JBfUSOCnbxGGZF+/0ooI7KrPuUSztUdU5A==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "ansi-regex": "^5.0.1"
+      },
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/strip-ansi-cjs/node_modules/ansi-regex": {
+      "version": "5.0.1",
+      "resolved": "https://registry.npmjs.org/ansi-regex/-/ansi-regex-5.0.1.tgz",
+      "integrity": "sha512-quJQXlTSUGL2LH9SUXo8VwsY4soanhgo6LNSm84E1LBcE8s3O0wpdiRzyR9z/ZZJMlMWv37qOOb9pdJlMUEKFQ==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=8"
+      }
+    },
     "node_modules/strip-json-comments": {
       "version": "3.1.1",
       "resolved": "https://registry.npmjs.org/strip-json-comments/-/strip-json-comments-3.1.1.tgz",
@@ -2102,6 +2724,60 @@
         "node": ">=8"
       }
     },
+    "node_modules/test-exclude": {
+      "version": "7.0.2",
+      "resolved": "https://registry.npmjs.org/test-exclude/-/test-exclude-7.0.2.tgz",
+      "integrity": "sha512-u9E6A+ZDYdp7a4WnarkXPZOx8Ilz46+kby6p1yZ8zsGTz9gYa6FIS7lj2oezzNKmtdyyJNNmmXDppga5GB7kSw==",
+      "dev": true,
+      "license": "ISC",
+      "dependencies": {
+        "@istanbuljs/schema": "^0.1.2",
+        "glob": "^10.4.1",
+        "minimatch": "^10.2.2"
+      },
+      "engines": {
+        "node": ">=18"
+      }
+    },
+    "node_modules/test-exclude/node_modules/balanced-match": {
+      "version": "4.0.4",
+      "resolved": "https://registry.npmjs.org/balanced-match/-/balanced-match-4.0.4.tgz",
+      "integrity": "sha512-BLrgEcRTwX2o6gGxGOCNyMvGSp35YofuYzw9h1IMTRmKqttAZZVU67bdb9Pr2vUHA8+j3i2tJfjO6C6+4myGTA==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": "18 || 20 || >=22"
+      }
+    },
+    "node_modules/test-exclude/node_modules/brace-expansion": {
+      "version": "5.0.4",
+      "resolved": "https://registry.npmjs.org/brace-expansion/-/brace-expansion-5.0.4.tgz",
+      "integrity": "sha512-h+DEnpVvxmfVefa4jFbCf5HdH5YMDXRsmKflpf1pILZWRFlTbJpxeU55nJl4Smt5HQaGzg1o6RHFPJaOqnmBDg==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "balanced-match": "^4.0.2"
+      },
+      "engines": {
+        "node": "18 || 20 || >=22"
+      }
+    },
+    "node_modules/test-exclude/node_modules/minimatch": {
+      "version": "10.2.4",
+      "resolved": "https://registry.npmjs.org/minimatch/-/minimatch-10.2.4.tgz",
+      "integrity": "sha512-oRjTw/97aTBN0RHbYCdtF1MQfvusSIBQM0IZEgzl6426+8jSC0nF1a/GmnVLpfB9yyr6g6FTqWqiZVbxrtaCIg==",
+      "dev": true,
+      "license": "BlueOak-1.0.0",
+      "dependencies": {
+        "brace-expansion": "^5.0.2"
+      },
+      "engines": {
+        "node": "18 || 20 || >=22"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/isaacs"
+      }
+    },
     "node_modules/tinyglobby": {
       "version": "0.2.15",
       "resolved": "https://registry.npmjs.org/tinyglobby/-/tinyglobby-0.2.15.tgz",
@@ -2149,6 +2825,21 @@
         "punycode": "^2.1.0"
       }
     },
+    "node_modules/v8-to-istanbul": {
+      "version": "9.3.0",
+      "resolved": "https://registry.npmjs.org/v8-to-istanbul/-/v8-to-istanbul-9.3.0.tgz",
+      "integrity": "sha512-kiGUalWN+rgBJ/1OHZsBtU4rXZOfj/7rKQxULKlIzwzQSvMJUUNgPwJEEh7gU6xEVxC0ahoOBvN2YI8GH6FNgA==",
+      "dev": true,
+      "license": "ISC",
+      "dependencies": {
+        "@jridgewell/trace-mapping": "^0.3.12",
+        "@types/istanbul-lib-coverage": "^2.0.1",
+        "convert-source-map": "^2.0.0"
+      },
+      "engines": {
+        "node": ">=10.12.0"
+      }
+    },
     "node_modules/which": {
       "version": "2.0.2",
       "resolved": "https://registry.npmjs.org/which/-/which-2.0.2.tgz",
@@ -2175,6 +2866,196 @@
         "node": ">=0.10.0"
       }
     },
+    "node_modules/wrap-ansi": {
+      "version": "8.1.0",
+      "resolved": "https://registry.npmjs.org/wrap-ansi/-/wrap-ansi-8.1.0.tgz",
+      "integrity": "sha512-si7QWI6zUMq56bESFvagtmzMdGOtoxfR+Sez11Mobfc7tm+VkUckk9bW2UeffTGVUbOksxmSw0AA2gs8g71NCQ==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "ansi-styles": "^6.1.0",
+        "string-width": "^5.0.1",
+        "strip-ansi": "^7.0.1"
+      },
+      "engines": {
+        "node": ">=12"
+      },
+      "funding": {
+        "url": "https://github.com/chalk/wrap-ansi?sponsor=1"
+      }
+    },
+    "node_modules/wrap-ansi-cjs": {
+      "name": "wrap-ansi",
+      "version": "7.0.0",
+      "resolved": "https://registry.npmjs.org/wrap-ansi/-/wrap-ansi-7.0.0.tgz",
+      "integrity": "sha512-YVGIj2kamLSTxw6NsZjoBxfSwsn0ycdesmc4p+Q21c5zPuZ1pl+NfxVdxPtdHvmNVOQ6XSYG4AUtyt/Fi7D16Q==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "ansi-styles": "^4.0.0",
+        "string-width": "^4.1.0",
+        "strip-ansi": "^6.0.0"
+      },
+      "engines": {
+        "node": ">=10"
+      },
+      "funding": {
+        "url": "https://github.com/chalk/wrap-ansi?sponsor=1"
+      }
+    },
+    "node_modules/wrap-ansi-cjs/node_modules/ansi-regex": {
+      "version": "5.0.1",
+      "resolved": "https://registry.npmjs.org/ansi-regex/-/ansi-regex-5.0.1.tgz",
+      "integrity": "sha512-quJQXlTSUGL2LH9SUXo8VwsY4soanhgo6LNSm84E1LBcE8s3O0wpdiRzyR9z/ZZJMlMWv37qOOb9pdJlMUEKFQ==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/wrap-ansi-cjs/node_modules/string-width": {
+      "version": "4.2.3",
+      "resolved": "https://registry.npmjs.org/string-width/-/string-width-4.2.3.tgz",
+      "integrity": "sha512-wKyQRQpjJ0sIp62ErSZdGsjMJWsap5oRNihHhu6G7JVO/9jIB6UyevL+tXuOqrng8j/cxKTWyWUwvSTriiZz/g==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "emoji-regex": "^8.0.0",
+        "is-fullwidth-code-point": "^3.0.0",
+        "strip-ansi": "^6.0.1"
+      },
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/wrap-ansi-cjs/node_modules/strip-ansi": {
+      "version": "6.0.1",
+      "resolved": "https://registry.npmjs.org/strip-ansi/-/strip-ansi-6.0.1.tgz",
+      "integrity": "sha512-Y38VPSHcqkFrCpFnQ9vuSXmquuv5oXOKpGeT6aGrr3o3Gc9AlVa6JBfUSOCnbxGGZF+/0ooI7KrPuUSztUdU5A==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "ansi-regex": "^5.0.1"
+      },
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/wrap-ansi/node_modules/ansi-styles": {
+      "version": "6.2.3",
+      "resolved": "https://registry.npmjs.org/ansi-styles/-/ansi-styles-6.2.3.tgz",
+      "integrity": "sha512-4Dj6M28JB+oAH8kFkTLUo+a2jwOFkuqb3yucU0CANcRRUbxS0cP0nZYCGjcc3BNXwRIsUVmDGgzawme7zvJHvg==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=12"
+      },
+      "funding": {
+        "url": "https://github.com/chalk/ansi-styles?sponsor=1"
+      }
+    },
+    "node_modules/wrap-ansi/node_modules/emoji-regex": {
+      "version": "9.2.2",
+      "resolved": "https://registry.npmjs.org/emoji-regex/-/emoji-regex-9.2.2.tgz",
+      "integrity": "sha512-L18DaJsXSUk2+42pv8mLs5jJT2hqFkFE4j21wOmgbUqsZ2hL72NsUU785g9RXgo3s0ZNgVl42TiHp3ZtOv/Vyg==",
+      "dev": true,
+      "license": "MIT"
+    },
+    "node_modules/wrap-ansi/node_modules/string-width": {
+      "version": "5.1.2",
+      "resolved": "https://registry.npmjs.org/string-width/-/string-width-5.1.2.tgz",
+      "integrity": "sha512-HnLOCR3vjcY8beoNLtcjZ5/nxn2afmME6lhrDrebokqMap+XbeW8n9TXpPDOqdGK5qcI3oT0GKTW6wC7EMiVqA==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "eastasianwidth": "^0.2.0",
+        "emoji-regex": "^9.2.2",
+        "strip-ansi": "^7.0.1"
+      },
+      "engines": {
+        "node": ">=12"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/sindresorhus"
+      }
+    },
+    "node_modules/y18n": {
+      "version": "5.0.8",
+      "resolved": "https://registry.npmjs.org/y18n/-/y18n-5.0.8.tgz",
+      "integrity": "sha512-0pfFzegeDWJHJIAmTLRP2DwHjdF5s7jo9tuztdQxAhINCdvS+3nGINqPd00AphqJR/0LhANUS6/+7SCb98YOfA==",
+      "dev": true,
+      "license": "ISC",
+      "engines": {
+        "node": ">=10"
+      }
+    },
+    "node_modules/yargs": {
+      "version": "17.7.2",
+      "resolved": "https://registry.npmjs.org/yargs/-/yargs-17.7.2.tgz",
+      "integrity": "sha512-7dSzzRQ++CKnNI/krKnYRV7JKKPUXMEh61soaHKg9mrWEhzFWhFnxPxGl+69cD1Ou63C13NUPCnmIcrvqCuM6w==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "cliui": "^8.0.1",
+        "escalade": "^3.1.1",
+        "get-caller-file": "^2.0.5",
+        "require-directory": "^2.1.1",
+        "string-width": "^4.2.3",
+        "y18n": "^5.0.5",
+        "yargs-parser": "^21.1.1"
+      },
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/yargs-parser": {
+      "version": "21.1.1",
+      "resolved": "https://registry.npmjs.org/yargs-parser/-/yargs-parser-21.1.1.tgz",
+      "integrity": "sha512-tVpsJW7DdjecAiFpbIB1e3qxIQsE6NoPc5/eTdrbbIC4h0LVsWhnoa3g+m2HclBIujHzsxZ4VJVA+GUuc2/LBw==",
+      "dev": true,
+      "license": "ISC",
+      "engines": {
+        "node": ">=12"
+      }
+    },
+    "node_modules/yargs/node_modules/ansi-regex": {
+      "version": "5.0.1",
+      "resolved": "https://registry.npmjs.org/ansi-regex/-/ansi-regex-5.0.1.tgz",
+      "integrity": "sha512-quJQXlTSUGL2LH9SUXo8VwsY4soanhgo6LNSm84E1LBcE8s3O0wpdiRzyR9z/ZZJMlMWv37qOOb9pdJlMUEKFQ==",
+      "dev": true,
+      "license": "MIT",
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/yargs/node_modules/string-width": {
+      "version": "4.2.3",
+      "resolved": "https://registry.npmjs.org/string-width/-/string-width-4.2.3.tgz",
+      "integrity": "sha512-wKyQRQpjJ0sIp62ErSZdGsjMJWsap5oRNihHhu6G7JVO/9jIB6UyevL+tXuOqrng8j/cxKTWyWUwvSTriiZz/g==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "emoji-regex": "^8.0.0",
+        "is-fullwidth-code-point": "^3.0.0",
+        "strip-ansi": "^6.0.1"
+      },
+      "engines": {
+        "node": ">=8"
+      }
+    },
+    "node_modules/yargs/node_modules/strip-ansi": {
+      "version": "6.0.1",
+      "resolved": "https://registry.npmjs.org/strip-ansi/-/strip-ansi-6.0.1.tgz",
+      "integrity": "sha512-Y38VPSHcqkFrCpFnQ9vuSXmquuv5oXOKpGeT6aGrr3o3Gc9AlVa6JBfUSOCnbxGGZF+/0ooI7KrPuUSztUdU5A==",
+      "dev": true,
+      "license": "MIT",
+      "dependencies": {
+        "ansi-regex": "^5.0.1"
+      },
+      "engines": {
+        "node": ">=8"
+      }
+    },
     "node_modules/yocto-queue": {
       "version": "0.1.0",
       "resolved": "https://registry.npmjs.org/yocto-queue/-/yocto-queue-0.1.0.tgz",
diff --git a/package.json b/package.json
index 685ec79e..65054448 100644
--- a/package.json
+++ b/package.json
@@ -83,10 +83,13 @@
     "postinstall": "echo '\\n  ecc-universal installed!\\n  Run: npx ecc-install typescript\\n  Docs: https://github.com/affaan-m/everything-claude-code\\n'",
     "lint": "eslint . && markdownlint '**/*.md' --ignore node_modules",
     "claw": "node scripts/claw.js",
-    "test": "node scripts/ci/validate-agents.js && node scripts/ci/validate-commands.js && node scripts/ci/validate-rules.js && node scripts/ci/validate-skills.js && node scripts/ci/validate-hooks.js && node scripts/ci/validate-no-personal-paths.js && node tests/run-all.js"
+    "test": "node scripts/ci/validate-agents.js && node scripts/ci/validate-commands.js && node scripts/ci/validate-rules.js && node scripts/ci/validate-skills.js && node scripts/ci/validate-hooks.js && node scripts/ci/validate-no-personal-paths.js && node tests/run-all.js",
+    "coverage": "c8 --all --include='scripts/**/*.js' --reporter=text --reporter=lcov node tests/run-all.js"
   },
   "devDependencies": {
     "@eslint/js": "^9.39.2",
+    "ajv": "^8.17.0",
+    "c8": "^10.1.2",
     "eslint": "^9.39.2",
     "globals": "^17.1.0",
     "markdownlint-cli": "^0.47.0"
diff --git a/schemas/hooks.schema.json b/schemas/hooks.schema.json
index cd58cfb1..3aa2ba1f 100644
--- a/schemas/hooks.schema.json
+++ b/schemas/hooks.schema.json
@@ -12,17 +12,8 @@
       "properties": {
         "type": {
           "type": "string",
-          "enum": [
-            "PreToolUse",
-            "PostToolUse",
-            "PreCompact",
-            "SessionStart",
-            "SessionEnd",
-            "Stop",
-            "Notification",
-            "SubagentStop"
-          ],
-          "description": "Hook event type that triggers this hook"
+          "enum": ["command", "notification"],
+          "description": "Hook action type (command or notification)"
         },
         "command": {
           "oneOf": [
diff --git a/scripts/ci/catalog.js b/scripts/ci/catalog.js
new file mode 100644
index 00000000..1e279445
--- /dev/null
+++ b/scripts/ci/catalog.js
@@ -0,0 +1,71 @@
+#!/usr/bin/env node
+/**
+ * Catalog agents, commands, and skills from the repo.
+ * Outputs JSON with counts and lists for CI/docs sync.
+ *
+ * Usage: node scripts/ci/catalog.js [--json|--md]
+ * Default: --json to stdout
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const ROOT = path.join(__dirname, '../..');
+const AGENTS_DIR = path.join(ROOT, 'agents');
+const COMMANDS_DIR = path.join(ROOT, 'commands');
+const SKILLS_DIR = path.join(ROOT, 'skills');
+
+function listAgents() {
+  if (!fs.existsSync(AGENTS_DIR)) return [];
+  return fs.readdirSync(AGENTS_DIR)
+    .filter(f => f.endsWith('.md'))
+    .map(f => f.slice(0, -3))
+    .sort();
+}
+
+function listCommands() {
+  if (!fs.existsSync(COMMANDS_DIR)) return [];
+  return fs.readdirSync(COMMANDS_DIR)
+    .filter(f => f.endsWith('.md'))
+    .map(f => f.slice(0, -3))
+    .sort();
+}
+
+function listSkills() {
+  if (!fs.existsSync(SKILLS_DIR)) return [];
+  const entries = fs.readdirSync(SKILLS_DIR, { withFileTypes: true });
+  return entries
+    .filter(e => e.isDirectory() && fs.existsSync(path.join(SKILLS_DIR, e.name, 'SKILL.md')))
+    .map(e => e.name)
+    .sort();
+}
+
+function run() {
+  const agents = listAgents();
+  const commands = listCommands();
+  const skills = listSkills();
+
+  const catalog = {
+    agents: { count: agents.length, list: agents },
+    commands: { count: commands.length, list: commands },
+    skills: { count: skills.length, list: skills }
+  };
+
+  const format = process.argv[2] === '--md' ? 'md' : 'json';
+  if (format === 'md') {
+    console.log('# ECC Catalog (generated)\n');
+    console.log(`- **Agents:** ${catalog.agents.count}`);
+    console.log(`- **Commands:** ${catalog.commands.count}`);
+    console.log(`- **Skills:** ${catalog.skills.count}\n`);
+    console.log('## Agents\n');
+    catalog.agents.list.forEach(a => console.log(`- ${a}`));
+    console.log('\n## Commands\n');
+    catalog.commands.list.forEach(c => console.log(`- ${c}`));
+    console.log('\n## Skills\n');
+    catalog.skills.list.forEach(s => console.log(`- ${s}`));
+  } else {
+    console.log(JSON.stringify(catalog, null, 2));
+  }
+}
+
+run();
diff --git a/scripts/ci/validate-hooks.js b/scripts/ci/validate-hooks.js
index 0b335232..7dd5ebee 100644
--- a/scripts/ci/validate-hooks.js
+++ b/scripts/ci/validate-hooks.js
@@ -1,13 +1,15 @@
 #!/usr/bin/env node
 /**
- * Validate hooks.json schema
+ * Validate hooks.json schema and hook entry rules.
  */
 
 const fs = require('fs');
 const path = require('path');
 const vm = require('vm');
+const Ajv = require('ajv');
 
 const HOOKS_FILE = path.join(__dirname, '../../hooks/hooks.json');
+const HOOKS_SCHEMA_PATH = path.join(__dirname, '../../schemas/hooks.schema.json');
 const VALID_EVENTS = ['PreToolUse', 'PostToolUse', 'PreCompact', 'SessionStart', 'SessionEnd', 'Stop', 'Notification', 'SubagentStop'];
 
 /**
@@ -67,6 +69,20 @@ function validateHooks() {
     process.exit(1);
   }
 
+  // Validate against JSON schema
+  if (fs.existsSync(HOOKS_SCHEMA_PATH)) {
+    const schema = JSON.parse(fs.readFileSync(HOOKS_SCHEMA_PATH, 'utf-8'));
+    const ajv = new Ajv({ allErrors: true });
+    const validate = ajv.compile(schema);
+    const valid = validate(data);
+    if (!valid) {
+      for (const err of validate.errors) {
+        console.error(`ERROR: hooks.json schema: ${err.instancePath || '/'} ${err.message}`);
+      }
+      process.exit(1);
+    }
+  }
+
   // Support both object format { hooks: {...} } and array format
   const hooks = data.hooks || data;
   let hasErrors = false;
diff --git a/tests/run-all.js b/tests/run-all.js
index 54d8c212..25d44666 100644
--- a/tests/run-all.js
+++ b/tests/run-all.js
@@ -10,21 +10,25 @@ const path = require('path');
 const fs = require('fs');
 
 const testsDir = __dirname;
-const testFiles = [
-  'lib/utils.test.js',
-  'lib/package-manager.test.js',
-  'lib/session-manager.test.js',
-  'lib/session-aliases.test.js',
-  'lib/project-detect.test.js',
-  'hooks/hooks.test.js',
-  'hooks/evaluate-session.test.js',
-  'hooks/suggest-compact.test.js',
-  'integration/hooks.test.js',
-  'ci/validators.test.js',
-  'scripts/claw.test.js',
-  'scripts/setup-package-manager.test.js',
-  'scripts/skill-create-output.test.js'
-];
+
+/**
+ * Discover all *.test.js files under testsDir (relative paths for stable output order).
+ */
+function discoverTestFiles(dir, baseDir = dir, acc = []) {
+  const entries = fs.readdirSync(dir, { withFileTypes: true });
+  for (const e of entries) {
+    const full = path.join(dir, e.name);
+    const rel = path.relative(baseDir, full);
+    if (e.isDirectory()) {
+      discoverTestFiles(full, baseDir, acc);
+    } else if (e.isFile() && e.name.endsWith('.test.js')) {
+      acc.push(rel);
+    }
+  }
+  return acc.sort();
+}
+
+const testFiles = discoverTestFiles(testsDir);
 
 const BOX_W = 58; // inner width between ║ delimiters
 const boxLine = (s) => `║${s.padEnd(BOX_W)}║`;

From 770505191003c21bab81272931e17654b4de3a15 Mon Sep 17 00:00:00 2001
From: Affaan Mustafa <affaan@dcube.ai>
Date: Tue, 10 Mar 2026 19:31:02 -0700
Subject: [PATCH 14/22] fix: align architecture tooling with current hooks docs

---
 AGENTS.md                    |   2 +-
 package.json                 |   2 +-
 schemas/hooks.schema.json    | 131 +++++++++++++++++++++++++++++++----
 scripts/ci/catalog.js        |  44 +++++++-----
 scripts/ci/validate-hooks.js | 115 ++++++++++++++++++++++++------
 tests/ci/validators.test.js  |  29 +++++++-
 tests/hooks/hooks.test.js    |   1 +
 tests/run-all.js             |  11 +++
 8 files changed, 282 insertions(+), 53 deletions(-)

diff --git a/AGENTS.md b/AGENTS.md
index 3c0ada3b..8e9e9fd1 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -130,7 +130,7 @@ Troubleshoot failures: check test isolation → verify mocks → fix implementat
 ```
 agents/          — 13 specialized subagents
 skills/          — 65+ workflow skills and domain knowledge
-commands/        — 33 slash commands
+commands/        — 40 slash commands
 hooks/           — Trigger-based automations
 rules/           — Always-follow guidelines (common + per-language)
 scripts/         — Cross-platform Node.js utilities
diff --git a/package.json b/package.json
index 65054448..1acb0444 100644
--- a/package.json
+++ b/package.json
@@ -84,7 +84,7 @@
     "lint": "eslint . && markdownlint '**/*.md' --ignore node_modules",
     "claw": "node scripts/claw.js",
     "test": "node scripts/ci/validate-agents.js && node scripts/ci/validate-commands.js && node scripts/ci/validate-rules.js && node scripts/ci/validate-skills.js && node scripts/ci/validate-hooks.js && node scripts/ci/validate-no-personal-paths.js && node tests/run-all.js",
-    "coverage": "c8 --all --include='scripts/**/*.js' --reporter=text --reporter=lcov node tests/run-all.js"
+    "coverage": "c8 --all --include=\"scripts/**/*.js\" --check-coverage --lines 80 --functions 80 --branches 80 --statements 80 --reporter=text --reporter=lcov node tests/run-all.js"
   },
   "devDependencies": {
     "@eslint/js": "^9.39.2",
diff --git a/schemas/hooks.schema.json b/schemas/hooks.schema.json
index 3aa2ba1f..4d119297 100644
--- a/schemas/hooks.schema.json
+++ b/schemas/hooks.schema.json
@@ -1,9 +1,17 @@
 {
   "$schema": "http://json-schema.org/draft-07/schema#",
   "title": "Claude Code Hooks Configuration",
-  "description": "Configuration for Claude Code hooks. Event types are validated at runtime and must be one of: PreToolUse, PostToolUse, PreCompact, SessionStart, SessionEnd, Stop, Notification, SubagentStop",
+  "description": "Configuration for Claude Code hooks. Supports current Claude Code hook events and hook action types.",
   "$defs": {
-    "hookItem": {
+    "stringArray": {
+      "type": "array",
+      "items": {
+        "type": "string",
+        "minLength": 1
+      },
+      "minItems": 1
+    },
+    "commandHookItem": {
       "type": "object",
       "required": [
         "type",
@@ -12,19 +20,17 @@
       "properties": {
         "type": {
           "type": "string",
-          "enum": ["command", "notification"],
-          "description": "Hook action type (command or notification)"
+          "const": "command",
+          "description": "Run a local command"
         },
         "command": {
           "oneOf": [
             {
-              "type": "string"
+              "type": "string",
+              "minLength": 1
             },
             {
-              "type": "array",
-              "items": {
-                "type": "string"
-              }
+              "$ref": "#/$defs/stringArray"
             }
           ]
         },
@@ -37,17 +43,94 @@
           "minimum": 0,
           "description": "Timeout in seconds for async hooks"
         }
-      }
+      },
+      "additionalProperties": true
+    },
+    "httpHookItem": {
+      "type": "object",
+      "required": [
+        "type",
+        "url"
+      ],
+      "properties": {
+        "type": {
+          "type": "string",
+          "const": "http"
+        },
+        "url": {
+          "type": "string",
+          "minLength": 1
+        },
+        "headers": {
+          "type": "object",
+          "additionalProperties": {
+            "type": "string"
+          }
+        },
+        "allowedEnvVars": {
+          "$ref": "#/$defs/stringArray"
+        },
+        "timeout": {
+          "type": "number",
+          "minimum": 0
+        }
+      },
+      "additionalProperties": true
+    },
+    "promptHookItem": {
+      "type": "object",
+      "required": [
+        "type",
+        "prompt"
+      ],
+      "properties": {
+        "type": {
+          "type": "string",
+          "enum": ["prompt", "agent"]
+        },
+        "prompt": {
+          "type": "string",
+          "minLength": 1
+        },
+        "model": {
+          "type": "string",
+          "minLength": 1
+        },
+        "timeout": {
+          "type": "number",
+          "minimum": 0
+        }
+      },
+      "additionalProperties": true
+    },
+    "hookItem": {
+      "oneOf": [
+        {
+          "$ref": "#/$defs/commandHookItem"
+        },
+        {
+          "$ref": "#/$defs/httpHookItem"
+        },
+        {
+          "$ref": "#/$defs/promptHookItem"
+        }
+      ]
     },
     "matcherEntry": {
       "type": "object",
       "required": [
-        "matcher",
         "hooks"
       ],
       "properties": {
         "matcher": {
-          "type": "string"
+          "oneOf": [
+            {
+              "type": "string"
+            },
+            {
+              "type": "object"
+            }
+          ]
         },
         "hooks": {
           "type": "array",
@@ -70,6 +153,28 @@
         },
         "hooks": {
           "type": "object",
+          "propertyNames": {
+            "enum": [
+              "SessionStart",
+              "UserPromptSubmit",
+              "PreToolUse",
+              "PermissionRequest",
+              "PostToolUse",
+              "PostToolUseFailure",
+              "Notification",
+              "SubagentStart",
+              "Stop",
+              "SubagentStop",
+              "PreCompact",
+              "InstructionsLoaded",
+              "TeammateIdle",
+              "TaskCompleted",
+              "ConfigChange",
+              "WorktreeCreate",
+              "WorktreeRemove",
+              "SessionEnd"
+            ]
+          },
           "additionalProperties": {
             "type": "array",
             "items": {
@@ -89,4 +194,4 @@
       }
     }
   ]
-}
\ No newline at end of file
+}
diff --git a/scripts/ci/catalog.js b/scripts/ci/catalog.js
index 1e279445..02a71e78 100644
--- a/scripts/ci/catalog.js
+++ b/scripts/ci/catalog.js
@@ -17,27 +17,39 @@ const SKILLS_DIR = path.join(ROOT, 'skills');
 
 function listAgents() {
   if (!fs.existsSync(AGENTS_DIR)) return [];
-  return fs.readdirSync(AGENTS_DIR)
-    .filter(f => f.endsWith('.md'))
-    .map(f => f.slice(0, -3))
-    .sort();
+  try {
+    return fs.readdirSync(AGENTS_DIR)
+      .filter(f => f.endsWith('.md'))
+      .map(f => f.slice(0, -3))
+      .sort();
+  } catch (error) {
+    throw new Error(`Failed to read agents directory (${AGENTS_DIR}): ${error.message}`);
+  }
 }
 
 function listCommands() {
   if (!fs.existsSync(COMMANDS_DIR)) return [];
-  return fs.readdirSync(COMMANDS_DIR)
-    .filter(f => f.endsWith('.md'))
-    .map(f => f.slice(0, -3))
-    .sort();
+  try {
+    return fs.readdirSync(COMMANDS_DIR)
+      .filter(f => f.endsWith('.md'))
+      .map(f => f.slice(0, -3))
+      .sort();
+  } catch (error) {
+    throw new Error(`Failed to read commands directory (${COMMANDS_DIR}): ${error.message}`);
+  }
 }
 
 function listSkills() {
   if (!fs.existsSync(SKILLS_DIR)) return [];
-  const entries = fs.readdirSync(SKILLS_DIR, { withFileTypes: true });
-  return entries
-    .filter(e => e.isDirectory() && fs.existsSync(path.join(SKILLS_DIR, e.name, 'SKILL.md')))
-    .map(e => e.name)
-    .sort();
+  try {
+    const entries = fs.readdirSync(SKILLS_DIR, { withFileTypes: true });
+    return entries
+      .filter(e => e.isDirectory() && fs.existsSync(path.join(SKILLS_DIR, e.name, 'SKILL.md')))
+      .map(e => e.name)
+      .sort();
+  } catch (error) {
+    throw new Error(`Failed to read skills directory (${SKILLS_DIR}): ${error.message}`);
+  }
 }
 
 function run() {
@@ -58,11 +70,11 @@ function run() {
     console.log(`- **Commands:** ${catalog.commands.count}`);
     console.log(`- **Skills:** ${catalog.skills.count}\n`);
     console.log('## Agents\n');
-    catalog.agents.list.forEach(a => console.log(`- ${a}`));
+    catalog.agents.list.forEach(a => { console.log(`- ${a}`); });
     console.log('\n## Commands\n');
-    catalog.commands.list.forEach(c => console.log(`- ${c}`));
+    catalog.commands.list.forEach(c => { console.log(`- ${c}`); });
     console.log('\n## Skills\n');
-    catalog.skills.list.forEach(s => console.log(`- ${s}`));
+    catalog.skills.list.forEach(s => { console.log(`- ${s}`); });
   } else {
     console.log(JSON.stringify(catalog, null, 2));
   }
diff --git a/scripts/ci/validate-hooks.js b/scripts/ci/validate-hooks.js
index 7dd5ebee..b4e440d9 100644
--- a/scripts/ci/validate-hooks.js
+++ b/scripts/ci/validate-hooks.js
@@ -10,7 +10,36 @@ const Ajv = require('ajv');
 
 const HOOKS_FILE = path.join(__dirname, '../../hooks/hooks.json');
 const HOOKS_SCHEMA_PATH = path.join(__dirname, '../../schemas/hooks.schema.json');
-const VALID_EVENTS = ['PreToolUse', 'PostToolUse', 'PreCompact', 'SessionStart', 'SessionEnd', 'Stop', 'Notification', 'SubagentStop'];
+const VALID_EVENTS = [
+  'SessionStart',
+  'UserPromptSubmit',
+  'PreToolUse',
+  'PermissionRequest',
+  'PostToolUse',
+  'PostToolUseFailure',
+  'Notification',
+  'SubagentStart',
+  'Stop',
+  'SubagentStop',
+  'PreCompact',
+  'InstructionsLoaded',
+  'TeammateIdle',
+  'TaskCompleted',
+  'ConfigChange',
+  'WorktreeCreate',
+  'WorktreeRemove',
+  'SessionEnd',
+];
+const VALID_HOOK_TYPES = ['command', 'http', 'prompt', 'agent'];
+const EVENTS_WITHOUT_MATCHER = new Set(['UserPromptSubmit', 'Notification', 'Stop', 'SubagentStop']);
+
+function isNonEmptyString(value) {
+  return typeof value === 'string' && value.trim().length > 0;
+}
+
+function isNonEmptyStringArray(value) {
+  return Array.isArray(value) && value.length > 0 && value.every(item => isNonEmptyString(item));
+}
 
 /**
  * Validate a single hook entry has required fields and valid inline JS
@@ -24,32 +53,72 @@ function validateHookEntry(hook, label) {
   if (!hook.type || typeof hook.type !== 'string') {
     console.error(`ERROR: ${label} missing or invalid 'type' field`);
     hasErrors = true;
-  }
-
-  // Validate optional async and timeout fields
-  if ('async' in hook && typeof hook.async !== 'boolean') {
-    console.error(`ERROR: ${label} 'async' must be a boolean`);
+  } else if (!VALID_HOOK_TYPES.includes(hook.type)) {
+    console.error(`ERROR: ${label} has unsupported hook type '${hook.type}'`);
     hasErrors = true;
   }
+
   if ('timeout' in hook && (typeof hook.timeout !== 'number' || hook.timeout < 0)) {
     console.error(`ERROR: ${label} 'timeout' must be a non-negative number`);
     hasErrors = true;
   }
 
-  if (!hook.command || (typeof hook.command !== 'string' && !Array.isArray(hook.command)) || (typeof hook.command === 'string' && !hook.command.trim()) || (Array.isArray(hook.command) && (hook.command.length === 0 || !hook.command.every(s => typeof s === 'string' && s.length > 0)))) {
-    console.error(`ERROR: ${label} missing or invalid 'command' field`);
-    hasErrors = true;
-  } else if (typeof hook.command === 'string') {
-    // Validate inline JS syntax in node -e commands
-    const nodeEMatch = hook.command.match(/^node -e "(.*)"$/s);
-    if (nodeEMatch) {
-      try {
-        new vm.Script(nodeEMatch[1].replace(/\\\\/g, '\\').replace(/\\"/g, '"').replace(/\\n/g, '\n').replace(/\\t/g, '\t'));
-      } catch (syntaxErr) {
-        console.error(`ERROR: ${label} has invalid inline JS: ${syntaxErr.message}`);
-        hasErrors = true;
+  if (hook.type === 'command') {
+    if ('async' in hook && typeof hook.async !== 'boolean') {
+      console.error(`ERROR: ${label} 'async' must be a boolean`);
+      hasErrors = true;
+    }
+
+    if (!isNonEmptyString(hook.command) && !isNonEmptyStringArray(hook.command)) {
+      console.error(`ERROR: ${label} missing or invalid 'command' field`);
+      hasErrors = true;
+    } else if (typeof hook.command === 'string') {
+      const nodeEMatch = hook.command.match(/^node -e "(.*)"$/s);
+      if (nodeEMatch) {
+        try {
+          new vm.Script(nodeEMatch[1].replace(/\\\\/g, '\\').replace(/\\"/g, '"').replace(/\\n/g, '\n').replace(/\\t/g, '\t'));
+        } catch (syntaxErr) {
+          console.error(`ERROR: ${label} has invalid inline JS: ${syntaxErr.message}`);
+          hasErrors = true;
+        }
       }
     }
+
+    return hasErrors;
+  }
+
+  if ('async' in hook) {
+    console.error(`ERROR: ${label} 'async' is only supported for command hooks`);
+    hasErrors = true;
+  }
+
+  if (hook.type === 'http') {
+    if (!isNonEmptyString(hook.url)) {
+      console.error(`ERROR: ${label} missing or invalid 'url' field`);
+      hasErrors = true;
+    }
+
+    if ('headers' in hook && (typeof hook.headers !== 'object' || hook.headers === null || Array.isArray(hook.headers) || !Object.values(hook.headers).every(value => typeof value === 'string'))) {
+      console.error(`ERROR: ${label} 'headers' must be an object with string values`);
+      hasErrors = true;
+    }
+
+    if ('allowedEnvVars' in hook && (!Array.isArray(hook.allowedEnvVars) || !hook.allowedEnvVars.every(value => isNonEmptyString(value)))) {
+      console.error(`ERROR: ${label} 'allowedEnvVars' must be an array of strings`);
+      hasErrors = true;
+    }
+
+    return hasErrors;
+  }
+
+  if (!isNonEmptyString(hook.prompt)) {
+    console.error(`ERROR: ${label} missing or invalid 'prompt' field`);
+    hasErrors = true;
+  }
+
+  if ('model' in hook && !isNonEmptyString(hook.model)) {
+    console.error(`ERROR: ${label} 'model' must be a non-empty string`);
+    hasErrors = true;
   }
 
   return hasErrors;
@@ -110,9 +179,12 @@ function validateHooks() {
           hasErrors = true;
           continue;
         }
-        if (!matcher.matcher) {
+        if (!('matcher' in matcher) && !EVENTS_WITHOUT_MATCHER.has(eventType)) {
           console.error(`ERROR: ${eventType}[${i}] missing 'matcher' field`);
           hasErrors = true;
+        } else if ('matcher' in matcher && typeof matcher.matcher !== 'string' && (typeof matcher.matcher !== 'object' || matcher.matcher === null)) {
+          console.error(`ERROR: ${eventType}[${i}] has invalid 'matcher' field`);
+          hasErrors = true;
         }
         if (!matcher.hooks || !Array.isArray(matcher.hooks)) {
           console.error(`ERROR: ${eventType}[${i}] missing 'hooks' array`);
@@ -132,9 +204,12 @@ function validateHooks() {
     // Array format (legacy)
     for (let i = 0; i < hooks.length; i++) {
       const hook = hooks[i];
-      if (!hook.matcher) {
+      if (!('matcher' in hook)) {
         console.error(`ERROR: Hook ${i} missing 'matcher' field`);
         hasErrors = true;
+      } else if (typeof hook.matcher !== 'string' && (typeof hook.matcher !== 'object' || hook.matcher === null)) {
+        console.error(`ERROR: Hook ${i} has invalid 'matcher' field`);
+        hasErrors = true;
       }
       if (!hook.hooks || !Array.isArray(hook.hooks)) {
         console.error(`ERROR: Hook ${i} missing 'hooks' array`);
diff --git a/tests/ci/validators.test.js b/tests/ci/validators.test.js
index 6077a389..f016a538 100644
--- a/tests/ci/validators.test.js
+++ b/tests/ci/validators.test.js
@@ -1927,7 +1927,7 @@ function runTests() {
       PreToolUse: [{
         matcher: 'Write',
         hooks: [{
-          type: 'intercept',
+          type: 'command',
           command: 'echo test',
           async: 'yes'  // Should be boolean, not string
         }]
@@ -1947,7 +1947,7 @@ function runTests() {
       PostToolUse: [{
         matcher: 'Edit',
         hooks: [{
-          type: 'intercept',
+          type: 'command',
           command: 'echo test',
           timeout: -5  // Must be non-negative
         }]
@@ -2105,6 +2105,31 @@ function runTests() {
     cleanupTestDir(testDir);
   })) passed++; else failed++;
 
+  console.log('\nRound 82b: validate-hooks (current official events and hook types):');
+
+  if (test('accepts UserPromptSubmit with omitted matcher and prompt/http/agent hooks', () => {
+    const testDir = createTestDir();
+    const hooksJson = JSON.stringify({
+      hooks: {
+        UserPromptSubmit: [
+          {
+            hooks: [
+              { type: 'prompt', prompt: 'Summarize the request.' },
+              { type: 'agent', prompt: 'Review for security issues.', model: 'gpt-5.4' },
+              { type: 'http', url: 'https://example.com/hooks', headers: { Authorization: 'Bearer token' } }
+            ]
+          }
+        ]
+      }
+    });
+    const hooksFile = path.join(testDir, 'hooks.json');
+    fs.writeFileSync(hooksFile, hooksJson);
+
+    const result = runValidatorWithDir('validate-hooks', 'HOOKS_FILE', hooksFile);
+    assert.strictEqual(result.code, 0, 'Should accept current official hook event/type combinations');
+    cleanupTestDir(testDir);
+  })) passed++; else failed++;
+
   // ── Round 83: validate-agents whitespace-only field, validate-skills empty SKILL.md ──
 
   console.log('\nRound 83: validate-agents (whitespace-only frontmatter field value):');
diff --git a/tests/hooks/hooks.test.js b/tests/hooks/hooks.test.js
index e13e8193..5610ed37 100644
--- a/tests/hooks/hooks.test.js
+++ b/tests/hooks/hooks.test.js
@@ -2561,6 +2561,7 @@ async function runTests() {
     assert.ok(!runAllSource.includes('execSync'), 'Should not use execSync');
     // Verify it shows stderr
     assert.ok(runAllSource.includes('stderr'), 'Should handle stderr output');
+    assert.ok(runAllSource.includes('result.status !== 0'), 'Should treat non-zero child exits as failures');
   })) passed++; else failed++;
 
   // ── Round 32: post-edit-typecheck special characters & check-console-log ──
diff --git a/tests/run-all.js b/tests/run-all.js
index 25d44666..399de5a7 100644
--- a/tests/run-all.js
+++ b/tests/run-all.js
@@ -71,6 +71,17 @@ for (const testFile of testFiles) {
 
   if (passedMatch) totalPassed += parseInt(passedMatch[1], 10);
   if (failedMatch) totalFailed += parseInt(failedMatch[1], 10);
+
+  if (result.error) {
+    console.log(`✗ ${testFile} failed to start: ${result.error.message}`);
+    totalFailed += failedMatch ? 0 : 1;
+    continue;
+  }
+
+  if (result.status !== 0) {
+    console.log(`✗ ${testFile} exited with status ${result.status}`);
+    totalFailed += failedMatch ? 0 : 1;
+  }
 }
 
 totalTests = totalPassed + totalFailed;

From 327c2e97d8bd5a59fe5b9b83a150f6e20893a5fa Mon Sep 17 00:00:00 2001
From: Jason Davey <jasonrdavey@gmail.com>
Date: Mon, 9 Mar 2026 14:41:46 -0400
Subject: [PATCH 15/22] feat: enhance TypeScript coding style guidelines with
 detailed examples and best practices esp interfaces and types

---
 rules/typescript/coding-style.md | 154 ++++++++++++++++++++++++++++---
 1 file changed, 141 insertions(+), 13 deletions(-)

diff --git a/rules/typescript/coding-style.md b/rules/typescript/coding-style.md
index db62a9bc..582c4033 100644
--- a/rules/typescript/coding-style.md
+++ b/rules/typescript/coding-style.md
@@ -9,19 +9,128 @@ paths:
 
 > This file extends [common/coding-style.md](../common/coding-style.md) with TypeScript/JavaScript specific content.
 
+## Types and Interfaces
+
+Use types to make public APIs, shared models, and component props explicit, readable, and reusable.
+
+### Public APIs
+
+- Add parameter and return types to exported functions, shared utilities, and public class methods
+- Let TypeScript infer obvious local variable types
+- Extract repeated inline object shapes into named types or interfaces
+
+```typescript
+// WRONG: Exported function without explicit types
+export function formatUser(user) {
+  return `${user.firstName} ${user.lastName}`
+}
+
+// CORRECT: Explicit types on public APIs
+interface User {
+  firstName: string
+  lastName: string
+}
+
+export function formatUser(user: User): string {
+  return `${user.firstName} ${user.lastName}`
+}
+```
+
+### Interfaces vs. Type Aliases
+
+- Use `interface` for object shapes that may be extended or implemented
+- Use `type` for unions, intersections, tuples, mapped types, and utility types
+- Prefer string literal unions over `enum` unless an `enum` is required for interoperability
+
+```typescript
+interface User {
+  id: string
+  email: string
+}
+
+type UserRole = 'admin' | 'member'
+type UserWithRole = User & {
+  role: UserRole
+}
+```
+
+### Avoid `any`
+
+- Avoid `any` in application code
+- Use `unknown` for external or untrusted input, then narrow it safely
+- Use generics when a value's type depends on the caller
+
+```typescript
+// WRONG: any removes type safety
+function getErrorMessage(error: any) {
+  return error.message
+}
+
+// CORRECT: unknown forces safe narrowing
+function getErrorMessage(error: unknown): string {
+  if (error instanceof Error) {
+    return error.message
+  }
+
+  return 'Unknown error'
+}
+```
+
+### React Props
+
+- Define component props with a named `interface` or `type`
+- Type callback props explicitly
+- Do not use `React.FC` unless there is a specific reason to do so
+
+```typescript
+interface User {
+  id: string
+  email: string
+}
+
+interface UserCardProps {
+  user: User
+  onSelect: (id: string) => void
+}
+
+function UserCard({ user, onSelect }: UserCardProps) {
+  return <button onClick={() => onSelect(user.id)}>{user.email}</button>
+}
+```
+
+### JavaScript Files
+
+- In `.js` and `.jsx` files, use JSDoc when types improve clarity and a TypeScript migration is not practical
+- Keep JSDoc aligned with runtime behavior
+
+```javascript
+/**
+ * @param {{ firstName: string, lastName: string }} user
+ * @returns {string}
+ */
+export function formatUser(user) {
+  return `${user.firstName} ${user.lastName}`
+}
+```
+
 ## Immutability
 
 Use spread operator for immutable updates:
 
 ```typescript
+interface User {
+  id: string
+  name: string
+}
+
 // WRONG: Mutation
-function updateUser(user, name) {
-  user.name = name  // MUTATION!
+function updateUser(user: User, name: string): User {
+  user.name = name // MUTATION!
   return user
 }
 
 // CORRECT: Immutability
-function updateUser(user, name) {
+function updateUser(user: Readonly<User>, name: string): User {
   return {
     ...user,
     name
@@ -31,31 +140,50 @@ function updateUser(user, name) {
 
 ## Error Handling
 
-Use async/await with try-catch:
+Use async/await with try-catch and narrow unknown errors safely:
 
 ```typescript
-try {
-  const result = await riskyOperation()
-  return result
-} catch (error) {
-  console.error('Operation failed:', error)
-  throw new Error('Detailed user-friendly message')
+interface User {
+  id: string
+  email: string
+}
+
+declare function riskyOperation(userId: string): Promise<User>
+
+function getErrorMessage(error: unknown): string {
+  if (error instanceof Error) {
+    return error.message
+  }
+
+  return 'Unexpected error'
+}
+
+async function loadUser(userId: string): Promise<User> {
+  try {
+    const result = await riskyOperation(userId)
+    return result
+  } catch (error: unknown) {
+    console.error('Operation failed:', error)
+    throw new Error(getErrorMessage(error))
+  }
 }
 ```
 
 ## Input Validation
 
-Use Zod for schema-based validation:
+Use Zod for schema-based validation and infer types from the schema:
 
 ```typescript
 import { z } from 'zod'
 
-const schema = z.object({
+const userSchema = z.object({
   email: z.string().email(),
   age: z.number().int().min(0).max(150)
 })
 
-const validated = schema.parse(input)
+type UserInput = z.infer<typeof userSchema>
+
+const validated: UserInput = userSchema.parse(input)
 ```
 
 ## Console.log

From b0a6847007c280ae36db78ba4b2c1e250de8b980 Mon Sep 17 00:00:00 2001
From: Affaan Mustafa <affaan@dcube.ai>
Date: Tue, 10 Mar 2026 19:34:10 -0700
Subject: [PATCH 16/22] docs: align TypeScript error handling examples

---
 rules/typescript/coding-style.md | 10 ++++++++--
 1 file changed, 8 insertions(+), 2 deletions(-)

diff --git a/rules/typescript/coding-style.md b/rules/typescript/coding-style.md
index 582c4033..090c0a17 100644
--- a/rules/typescript/coding-style.md
+++ b/rules/typescript/coding-style.md
@@ -72,7 +72,7 @@ function getErrorMessage(error: unknown): string {
     return error.message
   }
 
-  return 'Unknown error'
+  return 'Unexpected error'
 }
 ```
 
@@ -158,12 +158,18 @@ function getErrorMessage(error: unknown): string {
   return 'Unexpected error'
 }
 
+const logger = {
+  error: (message: string, error: unknown) => {
+    // Replace with your production logger (for example, pino or winston).
+  }
+}
+
 async function loadUser(userId: string): Promise<User> {
   try {
     const result = await riskyOperation(userId)
     return result
   } catch (error: unknown) {
-    console.error('Operation failed:', error)
+    logger.error('Operation failed', error)
     throw new Error(getErrorMessage(error))
   }
 }

From 4fa817cd7d5b2562cf2a25b24abd549a4c439191 Mon Sep 17 00:00:00 2001
From: Affaan Mustafa <affaan@dcube.ai>
Date: Tue, 10 Mar 2026 20:13:05 -0700
Subject: [PATCH 17/22] ci: install validation deps for hook checks

---
 .github/workflows/ci.yml                | 3 +++
 .github/workflows/reusable-validate.yml | 3 +++
 package-lock.json                       | 2 +-
 package.json                            | 2 +-
 4 files changed, 8 insertions(+), 2 deletions(-)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index e4d61e29..7498eee2 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -156,6 +156,9 @@ jobs:
         with:
           node-version: '20.x'
 
+      - name: Install validation dependencies
+        run: npm ci --ignore-scripts
+
       - name: Validate agents
         run: node scripts/ci/validate-agents.js
         continue-on-error: false
diff --git a/.github/workflows/reusable-validate.yml b/.github/workflows/reusable-validate.yml
index 1d0da8f1..27b483de 100644
--- a/.github/workflows/reusable-validate.yml
+++ b/.github/workflows/reusable-validate.yml
@@ -24,6 +24,9 @@ jobs:
         with:
           node-version: ${{ inputs.node-version }}
 
+      - name: Install validation dependencies
+        run: npm ci --ignore-scripts
+
       - name: Validate agents
         run: node scripts/ci/validate-agents.js
 
diff --git a/package-lock.json b/package-lock.json
index 7658be1b..0ad4a637 100644
--- a/package-lock.json
+++ b/package-lock.json
@@ -14,7 +14,7 @@
       },
       "devDependencies": {
         "@eslint/js": "^9.39.2",
-        "ajv": "^8.17.0",
+        "ajv": "^8.18.0",
         "c8": "^10.1.2",
         "eslint": "^9.39.2",
         "globals": "^17.1.0",
diff --git a/package.json b/package.json
index 1acb0444..352d41fc 100644
--- a/package.json
+++ b/package.json
@@ -88,7 +88,7 @@
   },
   "devDependencies": {
     "@eslint/js": "^9.39.2",
-    "ajv": "^8.17.0",
+    "ajv": "^8.18.0",
     "c8": "^10.1.2",
     "eslint": "^9.39.2",
     "globals": "^17.1.0",

From 32e11b8701d451dba4ba4b35d5d38017a95fb143 Mon Sep 17 00:00:00 2001
From: Tatsuya Shimomoto <shimo4228@gmail.com>
Date: Sun, 8 Mar 2026 19:35:28 +0900
Subject: [PATCH 18/22] feat(commands): improve learn-eval with checklist-based
 holistic verdict

Replace the 5-dimension numeric scoring rubric with a checklist + holistic
verdict system (Save / Improve then Save / Absorb into [X] / Drop).

Key improvements:
- Explicit pre-save checklist: grep skills/ for duplicates, check MEMORY.md,
  consider appending to existing skills, confirm reusability
- 4-way verdict instead of binary save/don't-save: adds "Absorb into [X]"
  to prevent skill file proliferation, and "Improve then Save" for iterative
  refinement
- Verdict-specific confirmation flows tailored to each outcome
- Design rationale explaining why holistic judgment outperforms numeric
  scoring with modern frontier models
---
 commands/learn-eval.md | 78 +++++++++++++++++++++++++++---------------
 1 file changed, 51 insertions(+), 27 deletions(-)

diff --git a/commands/learn-eval.md b/commands/learn-eval.md
index 18d8853c..6f38894a 100644
--- a/commands/learn-eval.md
+++ b/commands/learn-eval.md
@@ -1,10 +1,10 @@
 ---
-description: Extract reusable patterns from the session, self-evaluate quality before saving, and determine the right save location (Global vs Project).
+description: "Extract reusable patterns from the session, self-evaluate quality before saving, and determine the right save location (Global vs Project)."
 ---
 
 # /learn-eval - Extract, Evaluate, then Save
 
-Extends `/learn` with a quality gate and save-location decision before writing any skill file.
+Extends `/learn` with a quality gate, save-location decision, and knowledge-placement awareness before writing any skill file.
 
 ## What to Extract
 
@@ -51,36 +51,60 @@ origin: auto-extracted
 [Trigger conditions]
 ```
 
-5. **Self-evaluate before saving** using this rubric:
+5. **Quality gate — Checklist + Holistic verdict**
 
-   | Dimension | 1 | 3 | 5 |
-   |-----------|---|---|---|
-   | Specificity | Abstract principles only, no code examples | Representative code example present | Rich examples covering all usage patterns |
-   | Actionability | Unclear what to do | Main steps are understandable | Immediately actionable, edge cases covered |
-   | Scope Fit | Too broad or too narrow | Mostly appropriate, some boundary ambiguity | Name, trigger, and content perfectly aligned |
-   | Non-redundancy | Nearly identical to another skill | Some overlap but unique perspective exists | Completely unique value |
-   | Coverage | Covers only a fraction of the target task | Main cases covered, common variants missing | Main cases, edge cases, and pitfalls covered |
+   #### 5a. Required checklist (verify by actually reading files)
 
-   - Score each dimension 1–5
-   - If any dimension scores 1–2, improve the draft and re-score until all dimensions are ≥ 3
-   - Show the user the scores table and the final draft
+   Execute **all** of the following before evaluating the draft:
 
-6. Ask user to confirm:
-   - Show: proposed save path + scores table + final draft
-   - Wait for explicit confirmation before writing
+   - [ ] Grep `~/.claude/skills/` by keyword to check for content overlap
+   - [ ] Check MEMORY.md (both project and global) for overlap
+   - [ ] Consider whether appending to an existing skill would suffice
+   - [ ] Confirm this is a reusable pattern, not a one-off fix
 
-7. Save to the determined location
+   #### 5b. Holistic verdict
 
-## Output Format for Step 5 (scores table)
+   Synthesize the checklist results and draft quality, then choose **one** of the following:
 
-| Dimension | Score | Rationale |
-|-----------|-------|-----------|
-| Specificity | N/5 | ... |
-| Actionability | N/5 | ... |
-| Scope Fit | N/5 | ... |
-| Non-redundancy | N/5 | ... |
-| Coverage | N/5 | ... |
-| **Total** | **N/25** | |
+   | Verdict | Meaning | Next Action |
+   |---------|---------|-------------|
+   | **Save** | Unique, specific, well-scoped | Proceed to Step 6 |
+   | **Improve then Save** | Valuable but needs refinement | List improvements → revise → re-evaluate (once) |
+   | **Absorb into [X]** | Should be appended to an existing skill | Show target skill and additions → Step 6 |
+   | **Drop** | Trivial, redundant, or too abstract | Explain reasoning and stop |
+
+   **Guideline dimensions** (informing the verdict, not scored):
+
+   - **Specificity & Actionability**: Contains code examples or commands that are immediately usable
+   - **Scope Fit**: Name, trigger conditions, and content are aligned and focused on a single pattern
+   - **Uniqueness**: Provides value not covered by existing skills (informed by checklist results)
+   - **Reusability**: Realistic trigger scenarios exist in future sessions
+
+6. **Verdict-specific confirmation flow**
+
+   - **Save**: Present save path + checklist results + 1-line verdict rationale + full draft → save after user confirmation
+   - **Absorb into [X]**: Present target path + additions (diff format) + checklist results + verdict rationale → append after user confirmation
+   - **Drop**: Show checklist results + reasoning only (no confirmation needed)
+
+7. Save / Absorb to the determined location
+
+## Output Format for Step 5
+
+```
+### Checklist
+- [x] skills/ grep: no overlap (or: overlap found → details)
+- [x] MEMORY.md: no overlap (or: overlap found → details)
+- [x] Existing skill append: new file appropriate (or: should append to [X])
+- [x] Reusability: confirmed (or: one-off → Drop)
+
+### Verdict: Save / Improve then Save / Absorb into [X] / Drop
+
+**Rationale:** (1-2 sentences explaining the verdict)
+```
+
+## Design Rationale
+
+This version replaces the previous 5-dimension numeric scoring rubric (Specificity, Actionability, Scope Fit, Non-redundancy, Coverage scored 1-5) with a checklist-based holistic verdict system. Modern frontier models (Opus 4.6+) have strong contextual judgment — forcing rich qualitative signals into numeric scores loses nuance and can produce misleading totals. The holistic approach lets the model weigh all factors naturally, producing more accurate save/drop decisions while the explicit checklist ensures no critical check is skipped.
 
 ## Notes
 
@@ -88,4 +112,4 @@ origin: auto-extracted
 - Don't extract one-time issues (specific API outages, etc.)
 - Focus on patterns that will save time in future sessions
 - Keep skills focused — one pattern per skill
-- If Coverage score is low, add related variants before saving
+- When the verdict is Absorb, append to the existing skill rather than creating a new file

From 5929db9b231ebe98109f26abd322a143a48afc30 Mon Sep 17 00:00:00 2001
From: Tatsuya Shimomoto <shimo4228@gmail.com>
Date: Sun, 8 Mar 2026 21:04:38 +0900
Subject: [PATCH 19/22] fix: resolve markdownlint MD001 heading level violation

Change h4 (####) to h3 (###) for sub-steps 5a and 5b to comply with
heading increment rule (headings must increment by one level at a time).
---
 commands/learn-eval.md | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/commands/learn-eval.md b/commands/learn-eval.md
index 6f38894a..53b7bf58 100644
--- a/commands/learn-eval.md
+++ b/commands/learn-eval.md
@@ -53,7 +53,7 @@ origin: auto-extracted
 
 5. **Quality gate — Checklist + Holistic verdict**
 
-   #### 5a. Required checklist (verify by actually reading files)
+   ### 5a. Required checklist (verify by actually reading files)
 
    Execute **all** of the following before evaluating the draft:
 
@@ -62,7 +62,7 @@ origin: auto-extracted
    - [ ] Consider whether appending to an existing skill would suffice
    - [ ] Confirm this is a reusable pattern, not a one-off fix
 
-   #### 5b. Holistic verdict
+   ### 5b. Holistic verdict
 
    Synthesize the checklist results and draft quality, then choose **one** of the following:
 

From 973be02aa6f620fc848cd95ef8c0715199525a1b Mon Sep 17 00:00:00 2001
From: Affaan Mustafa <affaan@dcube.ai>
Date: Tue, 10 Mar 2026 20:08:20 -0700
Subject: [PATCH 20/22] docs: clarify learn-eval verdict flow

---
 commands/learn-eval.md | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/commands/learn-eval.md b/commands/learn-eval.md
index 53b7bf58..b98fcf4f 100644
--- a/commands/learn-eval.md
+++ b/commands/learn-eval.md
@@ -57,7 +57,7 @@ origin: auto-extracted
 
    Execute **all** of the following before evaluating the draft:
 
-   - [ ] Grep `~/.claude/skills/` by keyword to check for content overlap
+   - [ ] Grep `~/.claude/skills/` and relevant project `.claude/skills/` files by keyword to check for content overlap
    - [ ] Check MEMORY.md (both project and global) for overlap
    - [ ] Consider whether appending to an existing skill would suffice
    - [ ] Confirm this is a reusable pattern, not a one-off fix
@@ -82,6 +82,7 @@ origin: auto-extracted
 
 6. **Verdict-specific confirmation flow**
 
+   - **Improve then Save**: Present the required improvements + revised draft + updated checklist/verdict after one re-evaluation; if the revised verdict is **Save**, save after user confirmation, otherwise follow the new verdict
    - **Save**: Present save path + checklist results + 1-line verdict rationale + full draft → save after user confirmation
    - **Absorb into [X]**: Present target path + additions (diff format) + checklist results + verdict rationale → append after user confirmation
    - **Drop**: Show checklist results + reasoning only (no confirmation needed)

From 02d754ba675f15e1a56d76b62c97d820e615fecc Mon Sep 17 00:00:00 2001
From: Tatsuya Shimomoto <shimo4228@gmail.com>
Date: Sun, 8 Mar 2026 21:02:14 +0900
Subject: [PATCH 21/22] fix: use general-purpose agent instead of Explore for
 skill-stocktake evaluation
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

The Explore agent is a "Fast agent" optimized for codebase exploration,
not deep reasoning. The skill-stocktake V4 design requires holistic AI
judgment (actionability, scope fit, uniqueness, currency) which needs
the full reasoning capability of the conversation's main model.

Additionally, the Agent tool has no `model` parameter — specifying
`model: opus` was silently ignored, causing the evaluation to run on
the lightweight Explore model. This resulted in all skills receiving
"Keep" verdicts without genuine critical analysis.

Changing to `general-purpose` agent ensures evaluation runs on the
conversation's main model (e.g., Opus 4.6), enabling the holistic
judgment that V4 was designed for.
---
 skills/skill-stocktake/SKILL.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/skills/skill-stocktake/SKILL.md b/skills/skill-stocktake/SKILL.md
index 03bc497b..9d86b4db 100644
--- a/skills/skill-stocktake/SKILL.md
+++ b/skills/skill-stocktake/SKILL.md
@@ -74,7 +74,7 @@ Scanning:
 
 ### Phase 2 — Quality Evaluation
 
-Launch a Task tool subagent (**Explore agent, model: opus**) with the full inventory and checklist.
+Launch an Agent tool subagent (**general-purpose agent**) with the full inventory and checklist.
 The subagent reads each skill, applies the checklist, and returns per-skill JSON:
 
 `{ "verdict": "Keep"|"Improve"|"Update"|"Retire"|"Merge into [X]", "reason": "..." }`

From 0c2954565dce632053c068131bbdd9d20807dd0c Mon Sep 17 00:00:00 2001
From: Affaan Mustafa <affaan@dcube.ai>
Date: Tue, 10 Mar 2026 20:08:20 -0700
Subject: [PATCH 22/22] docs: add skill-stocktake agent invocation example

---
 skills/skill-stocktake/SKILL.md | 19 ++++++++++++++++++-
 1 file changed, 18 insertions(+), 1 deletion(-)

diff --git a/skills/skill-stocktake/SKILL.md b/skills/skill-stocktake/SKILL.md
index 9d86b4db..7ae77c27 100644
--- a/skills/skill-stocktake/SKILL.md
+++ b/skills/skill-stocktake/SKILL.md
@@ -74,7 +74,24 @@ Scanning:
 
 ### Phase 2 — Quality Evaluation
 
-Launch an Agent tool subagent (**general-purpose agent**) with the full inventory and checklist.
+Launch an Agent tool subagent (**general-purpose agent**) with the full inventory and checklist:
+
+```text
+Agent(
+  subagent_type="general-purpose",
+  prompt="
+Evaluate the following skill inventory against the checklist.
+
+[INVENTORY]
+
+[CHECKLIST]
+
+Return JSON for each skill:
+{ \"verdict\": \"Keep\"|\"Improve\"|\"Update\"|\"Retire\"|\"Merge into [X]\", \"reason\": \"...\" }
+"
+)
+```
+
 The subagent reads each skill, applies the checklist, and returns per-skill JSON:
 
 `{ "verdict": "Keep"|"Improve"|"Update"|"Retire"|"Merge into [X]", "reason": "..." }`