docs: close harness audit readiness gaps

This commit is contained in:
Affaan Mustafa 2026-05-11 20:15:37 -04:00 committed by Affaan Mustafa
parent b07432eac7
commit 20d862951f
15 changed files with 301 additions and 18 deletions

View File

@ -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",

View File

@ -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"

View File

@ -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.

View File

@ -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

View File

@ -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

View File

@ -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 |

View File

@ -160,7 +160,7 @@ Copy-Item -Recurse rules/typescript "$HOME/.claude/rules/"
/plugin list ecc@ecc
```
**完成!** 你现在可以使用 54 个代理、206 个技能和 69 个命令。
**完成!** 你现在可以使用 54 个代理、206 个技能和 70 个命令。
### multi-* 命令需要额外配置

View File

@ -205,6 +205,7 @@ commands:
- rust-test
- santa-loop
- save-session
- security-scan
- sessions
- setup-pm
- skill-create

92
commands/security-scan.md Normal file
View File

@ -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

View File

@ -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 实用工具

View File

@ -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 | 插件钩子 |

View File

@ -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.

View File

@ -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`

View File

@ -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
}
]
}

View File

@ -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)'
);