Skip to content

armgit / ECC

Public Imported from GitHub
0

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.json
index 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.json
index 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.md
index 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 Command
Run a deterministic repository harness audit and return a prioritized scorecard.
diff --git a/.opencode/commands/security-scan.md b/.opencode/commands/security-scan.md
new file mode 100644
index 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 flags
diff --git a/AGENTS.md b/AGENTS.md
index 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 subagents
skills/ — 206 workflow skills and domain knowledge
-commands/ — 69 slash commands
+commands/ — 70 slash commands
hooks/ — Trigger-based automations
rules/ — Always-follow guidelines (common + per-language)
scripts/ — Cross-platform Node.js utilities
diff --git a/README.md b/README.md
index 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.md
index 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.yaml
index 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-create
diff --git a/commands/security-scan.md b/commands/security-scan.md
new file mode 100644
index 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 flags
diff --git a/docs/zh-CN/AGENTS.md b/docs/zh-CN/AGENTS.md
index 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.md
index 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.md
index 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 Manually
For 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.md
new file mode 100644
index 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.json
new file mode 100644
index 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.js
index 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)'
);