The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.
docs: close harness audit readiness gaps
Affaan Mustafa20d862951f35
diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.jsonindex b4361d9b1..0daba52b3 100644--- a/.claude-plugin/marketplace.json+++ b/.claude-plugin/marketplace.json@@ -11,7 +11,7 @@{"name": "ecc","source": "./",- "description": "The most comprehensive Claude Code plugin — 54 agents, 206 skills, 69 legacy command shims, selective install profiles, and production-ready hooks for TDD, security scanning, code review, and continuous learning",+ "description": "The most comprehensive Claude Code plugin — 54 agents, 206 skills, 70 legacy command shims, selective install profiles, and production-ready hooks for TDD, security scanning, code review, and continuous learning","version": "2.0.0-rc.1","author": {"name": "Affaan Mustafa",diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.jsonindex 23d3170fe..36395c2fc 100644--- a/.claude-plugin/plugin.json+++ b/.claude-plugin/plugin.json@@ -1,7 +1,7 @@{"name": "ecc","version": "2.0.0-rc.1",- "description": "Battle-tested Claude Code plugin for engineering teams — 54 agents, 206 skills, 69 legacy command shims, production-ready hooks, and selective install workflows evolved through continuous real-world use",+ "description": "Battle-tested Claude Code plugin for engineering teams — 54 agents, 206 skills, 70 legacy command shims, production-ready hooks, and selective install workflows evolved through continuous real-world use","author": {"name": "Affaan Mustafa","url": "https://x.com/affaanmustafa"diff --git a/.opencode/commands/harness-audit.md b/.opencode/commands/harness-audit.mdindex 69382af06..108042ce9 100644--- a/.opencode/commands/harness-audit.md+++ b/.opencode/commands/harness-audit.md@@ -1,3 +1,7 @@+---+description: Run a deterministic repository harness audit and return a prioritized scorecard.+---+# Harness Audit CommandRun a deterministic repository harness audit and return a prioritized scorecard.diff --git a/.opencode/commands/security-scan.md b/.opencode/commands/security-scan.mdnew file mode 100644index 000000000..e916e57bf--- /dev/null+++ b/.opencode/commands/security-scan.md@@ -0,0 +1,92 @@+---+description: Run AgentShield against agent, hook, MCP, permission, and secret surfaces.+agent: everything-claude-code:security-reviewer+subtask: true+---++# Security Scan Command++Run AgentShield against the current project or a target path, then turn the findings into a prioritized remediation plan.++## Usage++`/security-scan [path] [--format text|json|markdown|html] [--min-severity low|medium|high|critical] [--fix]`++- `path` (optional): defaults to the current project. Use a `.claude/` path, a repo root, or a checked-in template directory.+- `--format`: output format. Use `json` for CI, `markdown` for handoffs, and `html` for standalone review reports.+- `--min-severity`: filters lower-priority findings.+- `--fix`: applies only AgentShield fixes explicitly marked as safe and auto-fixable.++## Deterministic Engine++Prefer the packaged scanner:++```bash+npx ecc-agentshield scan --path "${TARGET_PATH:-.}" --format text+```++For local AgentShield development, run from the AgentShield checkout:++```bash+npm run scan -- --path "${TARGET_PATH:-.}" --format text+```++Do not invent findings. Use AgentShield output as the source of truth and separate scanner facts from follow-up judgment.++## Review Checklist++1. Identify active runtime findings first:+ - hardcoded secrets+ - broad permissions+ - executable hooks+ - MCP servers with shell, filesystem, remote transport, or unpinned `npx`+ - agent prompts that handle untrusted content without defenses+2. Separate lower-confidence inventory:+ - docs examples+ - template examples+ - plugin manifests+ - project-local optional settings+3. For each critical or high finding, return:+ - file path+ - severity+ - runtime confidence+ - why it matters+ - exact remediation+ - whether it is safe to auto-fix+4. If `--fix` is requested, state the planned edits before applying fixes.+5. Re-run the scan after fixes and report the before/after score.++## Output Contract++Return:++1. Security grade and score.+2. Counts by severity and runtime confidence.+3. Critical/high findings with exact paths.+4. Lower-confidence findings grouped separately.+5. A remediation order.+6. Commands run and whether the scan was local, CI, or npx-backed.++## CI Pattern++Use AgentShield in GitHub Actions for enforced gates:++```yaml+- uses: affaan-m/agentshield@v1+ with:+ path: "."+ min-severity: "medium"+ fail-on-findings: true+```++## Links++- Skill: `skills/security-scan/SKILL.md`+- Agent: `agents/security-reviewer.md`+- Scanner: <https://github.com/affaan-m/agentshield>++## Arguments++$ARGUMENTS:+- optional target path+- optional AgentShield flagsdiff --git a/AGENTS.md b/AGENTS.mdindex 4e78a184d..78704a581 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 54 specialized agents, 206 skills, 69 commands, and automated hook workflows for software development.+This is a **production-ready AI coding plugin** providing 54 specialized agents, 206 skills, 70 commands, and automated hook workflows for software development.**Version:** 2.0.0-rc.1@@ -148,7 +148,7 @@ Troubleshoot failures: check test isolation → verify mocks → fix implementat```agents/ — 54 specialized subagentsskills/ — 206 workflow skills and domain knowledge-commands/ — 69 slash commands+commands/ — 70 slash commandshooks/ — Trigger-based automationsrules/ — Always-follow guidelines (common + per-language)scripts/ — Cross-platform Node.js utilitiesdiff --git a/README.md b/README.mdindex 4bf779c77..d2c40764f 100644--- a/README.md+++ b/README.md@@ -89,7 +89,7 @@ This repo is the raw code only. The guides explain everything.### v2.0.0-rc.1 — Surface Refresh, Operator Workflows, and ECC 2.0 Alpha (Apr 2026)- **Dashboard GUI** — New Tkinter-based desktop application (`ecc_dashboard.py` or `npm run dashboard`) with dark/light theme toggle, font customization, and project logo in header and taskbar.-- **Public surface synced to the live repo** — metadata, catalog counts, plugin manifests, and install-facing docs now match the actual OSS surface: 54 agents, 204 skills, and 69 legacy command shims.+- **Public surface synced to the live repo** — metadata, catalog counts, plugin manifests, and install-facing docs now match the actual OSS surface: 54 agents, 206 skills, and 70 legacy command shims.- **Operator and outbound workflow expansion** — `brand-voice`, `social-graph-ranker`, `connections-optimizer`, `customer-billing-ops`, `ecc-tools-cost-audit`, `google-workspace-ops`, `project-flow-ops`, and `workspace-surface-audit` round out the operator lane.- **Media and launch tooling** — `manim-video`, `remotion-video-creation`, and upgraded social publishing surfaces make technical explainers and launch content part of the same system.- **Framework and product surface growth** — `nestjs-patterns`, richer Codex/OpenCode install surfaces, and expanded cross-harness packaging keep the repo usable beyond Claude Code alone.@@ -358,7 +358,7 @@ If you stacked methods, clean up in this order:/plugin list ecc@ecc```-**That's it!** You now have access to 54 agents, 206 skills, and 69 legacy command shims.+**That's it!** You now have access to 54 agents, 206 skills, and 70 legacy command shims.### Dashboard GUI@@ -1350,7 +1350,7 @@ The configuration is automatically detected from `.opencode/opencode.json`.| Feature | Claude Code | OpenCode | Status ||---------|-------------|----------|--------|| Agents | PASS: 54 agents | PASS: 12 agents | **Claude Code leads** |-| Commands | PASS: 69 commands | PASS: 31 commands | **Claude Code leads** |+| Commands | PASS: 70 commands | PASS: 35 commands | **Claude Code leads** || Skills | PASS: 206 skills | PASS: 37 skills | **Claude Code leads** || Hooks | PASS: 8 event types | PASS: 11 events | **OpenCode has more!** || Rules | PASS: 29 rules | PASS: 13 instructions | **Claude Code leads** |@@ -1455,7 +1455,7 @@ ECC is the **first plugin to maximize every major AI coding tool**. Here's how e| Feature | Claude Code | Cursor IDE | Codex CLI | OpenCode ||---------|------------|------------|-----------|----------|| **Agents** | 54 | Shared (AGENTS.md) | Shared (AGENTS.md) | 12 |-| **Commands** | 69 | Shared | Instruction-based | 31 |+| **Commands** | 70 | Shared | Instruction-based | 35 || **Skills** | 206 | Shared | 10 (native format) | 37 || **Hook Events** | 8 types | 15 types | None yet | 11 types || **Hook Scripts** | 20+ scripts | 16 scripts (DRY adapter) | N/A | Plugin hooks |diff --git a/README.zh-CN.md b/README.zh-CN.mdindex 6c87bd218..4e20ab566 100644--- a/README.zh-CN.md+++ b/README.zh-CN.md@@ -160,7 +160,7 @@ Copy-Item -Recurse rules/typescript "$HOME/.claude/rules/"/plugin list ecc@ecc```-**完成!** 你现在可以使用 54 个代理、206 个技能和 69 个命令。+**完成!** 你现在可以使用 54 个代理、206 个技能和 70 个命令。### multi-* 命令需要额外配置diff --git a/agent.yaml b/agent.yamlindex 954fa5fcf..90c2bc161 100644--- a/agent.yaml+++ b/agent.yaml@@ -205,6 +205,7 @@ commands:- rust-test- santa-loop- save-session+ - security-scan- sessions- setup-pm- skill-creatediff --git a/commands/security-scan.md b/commands/security-scan.mdnew file mode 100644index 000000000..e916e57bf--- /dev/null+++ b/commands/security-scan.md@@ -0,0 +1,92 @@+---+description: Run AgentShield against agent, hook, MCP, permission, and secret surfaces.+agent: everything-claude-code:security-reviewer+subtask: true+---++# Security Scan Command++Run AgentShield against the current project or a target path, then turn the findings into a prioritized remediation plan.++## Usage++`/security-scan [path] [--format text|json|markdown|html] [--min-severity low|medium|high|critical] [--fix]`++- `path` (optional): defaults to the current project. Use a `.claude/` path, a repo root, or a checked-in template directory.+- `--format`: output format. Use `json` for CI, `markdown` for handoffs, and `html` for standalone review reports.+- `--min-severity`: filters lower-priority findings.+- `--fix`: applies only AgentShield fixes explicitly marked as safe and auto-fixable.++## Deterministic Engine++Prefer the packaged scanner:++```bash+npx ecc-agentshield scan --path "${TARGET_PATH:-.}" --format text+```++For local AgentShield development, run from the AgentShield checkout:++```bash+npm run scan -- --path "${TARGET_PATH:-.}" --format text+```++Do not invent findings. Use AgentShield output as the source of truth and separate scanner facts from follow-up judgment.++## Review Checklist++1. Identify active runtime findings first:+ - hardcoded secrets+ - broad permissions+ - executable hooks+ - MCP servers with shell, filesystem, remote transport, or unpinned `npx`+ - agent prompts that handle untrusted content without defenses+2. Separate lower-confidence inventory:+ - docs examples+ - template examples+ - plugin manifests+ - project-local optional settings+3. For each critical or high finding, return:+ - file path+ - severity+ - runtime confidence+ - why it matters+ - exact remediation+ - whether it is safe to auto-fix+4. If `--fix` is requested, state the planned edits before applying fixes.+5. Re-run the scan after fixes and report the before/after score.++## Output Contract++Return:++1. Security grade and score.+2. Counts by severity and runtime confidence.+3. Critical/high findings with exact paths.+4. Lower-confidence findings grouped separately.+5. A remediation order.+6. Commands run and whether the scan was local, CI, or npx-backed.++## CI Pattern++Use AgentShield in GitHub Actions for enforced gates:++```yaml+- uses: affaan-m/agentshield@v1+ with:+ path: "."+ min-severity: "medium"+ fail-on-findings: true+```++## Links++- Skill: `skills/security-scan/SKILL.md`+- Agent: `agents/security-reviewer.md`+- Scanner: <https://github.com/affaan-m/agentshield>++## Arguments++$ARGUMENTS:+- optional target path+- optional AgentShield flagsdiff --git a/docs/zh-CN/AGENTS.md b/docs/zh-CN/AGENTS.mdindex 3ed8af75c..3c52e1f64 100644--- a/docs/zh-CN/AGENTS.md+++ b/docs/zh-CN/AGENTS.md@@ -1,6 +1,6 @@# Everything Claude Code (ECC) — 智能体指令-这是一个**生产就绪的 AI 编码插件**,提供 54 个专业代理、206 项技能、69 条命令以及自动化钩子工作流,用于软件开发。+这是一个**生产就绪的 AI 编码插件**,提供 54 个专业代理、206 项技能、70 条命令以及自动化钩子工作流,用于软件开发。**版本:** 2.0.0-rc.1@@ -148,7 +148,7 @@```agents/ — 54 个专业子代理skills/ — 206 个工作流技能和领域知识-commands/ — 69 个斜杠命令+commands/ — 70 个斜杠命令hooks/ — 基于触发的自动化rules/ — 始终遵循的指导方针(通用 + 每种语言)scripts/ — 跨平台 Node.js 实用工具diff --git a/docs/zh-CN/README.md b/docs/zh-CN/README.mdindex e06194bd6..0d14909a4 100644--- a/docs/zh-CN/README.md+++ b/docs/zh-CN/README.md@@ -224,7 +224,7 @@ Copy-Item -Recurse rules/typescript "$HOME/.claude/rules/"/plugin list ecc@ecc```-**搞定!** 你现在可以使用 54 个智能体、206 项技能和 69 个命令了。+**搞定!** 你现在可以使用 54 个智能体、206 项技能和 70 个命令了。***@@ -1133,7 +1133,7 @@ opencode| 功能特性 | Claude Code | OpenCode | 状态 ||---------|-------------|----------|--------|| 智能体 | PASS: 54 个 | PASS: 12 个 | **Claude Code 领先** |-| 命令 | PASS: 69 个 | PASS: 31 个 | **Claude Code 领先** |+| 命令 | PASS: 70 个 | PASS: 35 个 | **Claude Code 领先** || 技能 | PASS: 206 项 | PASS: 37 项 | **Claude Code 领先** || 钩子 | PASS: 8 种事件类型 | PASS: 11 种事件 | **OpenCode 更多!** || 规则 | PASS: 29 条 | PASS: 13 条指令 | **Claude Code 领先** |@@ -1241,7 +1241,7 @@ ECC 是**第一个最大化利用每个主要 AI 编码工具的插件**。以| 功能特性 | Claude Code | Cursor IDE | Codex CLI | OpenCode ||---------|------------|------------|-----------|----------|| **智能体** | 54 | 共享 (AGENTS.md) | 共享 (AGENTS.md) | 12 |-| **命令** | 69 | 共享 | 基于指令 | 31 |+| **命令** | 70 | 共享 | 基于指令 | 35 || **技能** | 206 | 共享 | 10 (原生格式) | 37 || **钩子事件** | 8 种类型 | 15 种类型 | 暂无 | 11 种类型 || **钩子脚本** | 20+ 个脚本 | 16 个脚本 (DRY 适配器) | N/A | 插件钩子 |diff --git a/hooks/README.md b/hooks/README.mdindex ae8d568a2..db8b0e358 100644--- a/hooks/README.md+++ b/hooks/README.md@@ -16,6 +16,9 @@ User request → Claude picks a tool → PreToolUse hook runs → Tool executes## Hooks in This Plugin+Memory persistence lifecycle definitions live in `hooks/memory-persistence/`.+The executable hook graph remains `hooks/hooks.json`; the memory persistence directory is the stable contract for SessionStart, PreCompact, observation, activity tracking, and SessionEnd behavior.+## Installing These Hooks ManuallyFor Claude Code manual installs, do not paste the raw repo `hooks.json` into `~/.claude/settings.json` or copy it directly into `~/.claude/hooks/hooks.json`. The checked-in file is plugin/repo-oriented and is meant to be installed through the ECC installer or loaded as a plugin.diff --git a/hooks/memory-persistence/README.md b/hooks/memory-persistence/README.mdnew file mode 100644index 000000000..13c40c425--- /dev/null+++ b/hooks/memory-persistence/README.md@@ -0,0 +1,44 @@+# Memory Persistence Hooks++These lifecycle hook definitions document ECC's memory persistence contract for Claude Code plugin and manual installs.++The executable implementations live in `scripts/hooks/`:++- `session-start.js` loads bounded prior context, detects project state, and prepares session metadata.+- `pre-compact.js` captures state before context compaction.+- `session-end.js` persists session-end summaries when transcript metadata is available.+- `observe-runner.js` records tool-use observations for continuous learning.+- `session-activity-tracker.js` records tool usage and file activity for ECC2 status and observability.++The installed hook graph is still `hooks/hooks.json`. This directory is the stable, human-readable lifecycle definition surface referenced by the harness audit and longform docs.++## Lifecycle Contract++| Event | Hook | Purpose | Blocking |+|---|---|---|---|+| `SessionStart` | `session:start` | Load bounded prior context and project metadata | no |+| `PreCompact` | `pre:compact` | Save state before compaction | no |+| `PreToolUse` | `pre:observe:continuous-learning` | Capture tool intent for learning signals | no |+| `PostToolUse` | `post:observe:continuous-learning` | Capture tool result for learning signals | no |+| `PostToolUse` | `post:session-activity-tracker` | Record tool and file activity for ECC2 metrics | no |+| `Stop` | `stop:format-typecheck` | Batch quality gate after edits | yes on hook failure |+| `Stop` | `stop:check-console-log` | Audit modified files for debug logging | warn/error by hook output |++## Operator Expectations++- Keep persistence local by default.+- Avoid sending transcripts or tool traces to hosted services unless a user explicitly enables an integration.+- Bound context loaded at session start with `ECC_SESSION_START_MAX_CHARS`.+- Allow opt-out with `ECC_SESSION_START_CONTEXT=off`.+- Keep lifecycle hooks profile-gated through `ECC_HOOK_PROFILE` and `ECC_DISABLED_HOOKS`.++## Related Files++- `hooks/hooks.json`+- `hooks/README.md`+- `scripts/hooks/session-start.js`+- `scripts/hooks/pre-compact.js`+- `scripts/hooks/session-end.js`+- `scripts/hooks/observe-runner.js`+- `scripts/hooks/session-activity-tracker.js`+- `docs/architecture/observability-readiness.md`diff --git a/hooks/memory-persistence/hooks.json b/hooks/memory-persistence/hooks.jsonnew file mode 100644index 000000000..1260d8ebe--- /dev/null+++ b/hooks/memory-persistence/hooks.json@@ -0,0 +1,47 @@+{+ "description": "Reference lifecycle hook definitions for ECC memory persistence. The production hook graph is hooks/hooks.json.",+ "events": [+ {+ "event": "SessionStart",+ "id": "session:start",+ "script": "scripts/hooks/session-start-bootstrap.js",+ "purpose": "Load bounded prior context and detect project state at session start.",+ "blocking": false+ },+ {+ "event": "PreCompact",+ "id": "pre:compact",+ "script": "scripts/hooks/pre-compact.js",+ "purpose": "Persist session state before context compaction.",+ "blocking": false+ },+ {+ "event": "PreToolUse",+ "id": "pre:observe:continuous-learning",+ "script": "scripts/hooks/observe-runner.js",+ "purpose": "Record tool intent for continuous learning signals.",+ "blocking": false+ },+ {+ "event": "PostToolUse",+ "id": "post:observe:continuous-learning",+ "script": "scripts/hooks/observe-runner.js",+ "purpose": "Record tool results for continuous learning signals.",+ "blocking": false+ },+ {+ "event": "PostToolUse",+ "id": "post:session-activity-tracker",+ "script": "scripts/hooks/session-activity-tracker.js",+ "purpose": "Record per-session tool calls and file activity for ECC2 metrics.",+ "blocking": false+ },+ {+ "event": "SessionEnd",+ "id": "session:end",+ "script": "scripts/hooks/session-end.js",+ "purpose": "Persist session-end summaries when transcript metadata is available.",+ "blocking": false+ }+ ]+}diff --git a/scripts/ci/catalog.js b/scripts/ci/catalog.jsindex 3c86eb4eb..d0a94c133 100644--- a/scripts/ci/catalog.js+++ b/scripts/ci/catalog.js@@ -141,7 +141,7 @@ function parseReadmeExpectations(readmeContent) {},{category: 'commands',- regex: /^\|\s*(?:\*\*)?Commands(?:\*\*)?\s*\|\s*(\d+)\s*\|\s*Shared\s*\|\s*Instruction-based\s*\|\s*31\s*\|$/im,+ regex: /^\|\s*(?:\*\*)?Commands(?:\*\*)?\s*\|\s*(\d+)\s*\|\s*Shared\s*\|\s*Instruction-based\s*\|\s*\d+\s*\|$/im,source: 'README.md parity table'},{@@ -223,7 +223,7 @@ function parseZhDocsReadmeExpectations(readmeContent) {},{category: 'commands',- regex: /^\|\s*(?:\*\*)?命令(?:\*\*)?\s*\|\s*(\d+)\s*\|\s*共享\s*\|\s*基于指令\s*\|\s*31\s*\|$/im,+ regex: /^\|\s*(?:\*\*)?命令(?:\*\*)?\s*\|\s*(\d+)\s*\|\s*共享\s*\|\s*基于指令\s*\|\s*\d+\s*\|$/im,source: 'docs/zh-CN/README.md parity table'},{@@ -447,7 +447,7 @@ function syncEnglishReadme(content, catalog) {);nextContent = replaceOrThrow(nextContent,- /^(\|\s*(?:\*\*)?Commands(?:\*\*)?\s*\|\s*)(\d+)(\s*\|\s*Shared\s*\|\s*Instruction-based\s*\|\s*31\s*\|)$/im,+ /^(\|\s*(?:\*\*)?Commands(?:\*\*)?\s*\|\s*)(\d+)(\s*\|\s*Shared\s*\|\s*Instruction-based\s*\|\s*\d+\s*\|)$/im,(_, prefix, __, suffix) => `${prefix}${catalog.commands.count}${suffix}`,'README.md parity table (commands)');@@ -539,7 +539,7 @@ function syncZhDocsReadme(content, catalog) {);nextContent = replaceOrThrow(nextContent,- /^(\|\s*(?:\*\*)?命令(?:\*\*)?\s*\|\s*)(\d+)(\s*\|\s*共享\s*\|\s*基于指令\s*\|\s*31\s*\|)$/im,+ /^(\|\s*(?:\*\*)?命令(?:\*\*)?\s*\|\s*)(\d+)(\s*\|\s*共享\s*\|\s*基于指令\s*\|\s*\d+\s*\|)$/im,(_, prefix, __, suffix) => `${prefix}${catalog.commands.count}${suffix}`,'docs/zh-CN/README.md parity table (commands)');