From 20d862951f356fdf143759bca6b92f02474c7525 Mon Sep 17 00:00:00 2001 From: Affaan Mustafa Date: Mon, 11 May 2026 20:15:37 -0400 Subject: [PATCH] docs: close harness audit readiness gaps --- .claude-plugin/marketplace.json | 2 +- .claude-plugin/plugin.json | 2 +- .opencode/commands/harness-audit.md | 4 ++ .opencode/commands/security-scan.md | 92 +++++++++++++++++++++++++++++ AGENTS.md | 4 +- README.md | 8 +-- README.zh-CN.md | 2 +- agent.yaml | 1 + commands/security-scan.md | 92 +++++++++++++++++++++++++++++ docs/zh-CN/AGENTS.md | 4 +- docs/zh-CN/README.md | 6 +- hooks/README.md | 3 + hooks/memory-persistence/README.md | 44 ++++++++++++++ hooks/memory-persistence/hooks.json | 47 +++++++++++++++ scripts/ci/catalog.js | 8 +-- 15 files changed, 301 insertions(+), 18 deletions(-) create mode 100644 .opencode/commands/security-scan.md create mode 100644 commands/security-scan.md create mode 100644 hooks/memory-persistence/README.md create mode 100644 hooks/memory-persistence/hooks.json diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index b4361d9b..0daba52b 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 23d3170f..36395c2f 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 69382af0..108042ce 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 00000000..e916e57b --- /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: + +## Arguments + +$ARGUMENTS: +- optional target path +- optional AgentShield flags diff --git a/AGENTS.md b/AGENTS.md index 4e78a184..78704a58 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 4bf779c7..d2c40764 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 6c87bd21..4e20ab56 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 954fa5fc..90c2bc16 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 00000000..e916e57b --- /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: + +## Arguments + +$ARGUMENTS: +- optional target path +- optional AgentShield flags diff --git a/docs/zh-CN/AGENTS.md b/docs/zh-CN/AGENTS.md index 3ed8af75..3c52e1f6 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 e06194bd..0d14909a 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 ae8d568a..db8b0e35 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 00000000..13c40c42 --- /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 00000000..1260d8eb --- /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 3c86eb4e..d0a94c13 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)' );