mirror of
https://github.com/affaan-m/ECC.git
synced 2026-10-18 22:13:45 +02:00
Merge PR #3447: add bounded brownfield audit with project-owned decisions
This commit is contained in:
haelyra
@@ -11,7 +11,7 @@
|
||||
{
|
||||
"name": "ecc",
|
||||
"source": "./",
|
||||
"description": "Harness-native ECC operator layer - 71 agents, 302 skills, 95 legacy command shims, reusable hooks, rules, selective install profiles, and production-ready workflows for Claude Code, Codex, OpenCode, Cursor, and related agent harnesses",
|
||||
"description": "Harness-native ECC operator layer - 71 agents, 303 skills, 95 legacy command shims, reusable hooks, rules, selective install profiles, and production-ready workflows for Claude Code, Codex, OpenCode, Cursor, and related agent harnesses",
|
||||
"version": "2.2.3",
|
||||
"author": {
|
||||
"name": "Affaan Mustafa",
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
{
|
||||
"name": "ecc",
|
||||
"version": "2.2.3",
|
||||
"description": "Harness-native ECC plugin for engineering teams - 71 agents, 302 skills, 95 legacy command shims, reusable hooks, rules, MCP conventions, and operator workflows for Claude Code plus adjacent agent harnesses",
|
||||
"description": "Harness-native ECC plugin for engineering teams - 71 agents, 303 skills, 95 legacy command shims, reusable hooks, rules, MCP conventions, and operator workflows for Claude Code plus adjacent agent harnesses",
|
||||
"author": {
|
||||
"name": "Affaan Mustafa",
|
||||
"url": "https://x.com/affaanmustafa"
|
||||
|
||||
+1
-1
@@ -4,7 +4,7 @@ This file provides Gemini CLI with the baseline ECC workflow, review standards,
|
||||
|
||||
## Overview
|
||||
|
||||
ECC is a cross-harness coding system with 71 specialized agents, 302 skills, and 95 commands.
|
||||
ECC is a cross-harness coding system with 71 specialized agents, 303 skills, and 95 commands.
|
||||
|
||||
Gemini support is currently focused on a strong project-local instruction layer via `.gemini/GEMINI.md`, plus the shared MCP catalog and package-manager setup assets shipped by the installer.
|
||||
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# ECC — Agent Instructions
|
||||
|
||||
This is a **production-ready AI coding plugin** providing 71 specialized agents, 302 skills, 95 commands, and automated hook workflows for software development.
|
||||
This is a **production-ready AI coding plugin** providing 71 specialized agents, 303 skills, 95 commands, and automated hook workflows for software development.
|
||||
|
||||
**Version:** 2.2.3
|
||||
|
||||
@@ -202,7 +202,7 @@ Troubleshoot failures: check test isolation → verify mocks → fix implementat
|
||||
|
||||
```
|
||||
agents/ — 71 specialized subagents
|
||||
skills/ — 302 workflow skills and domain knowledge
|
||||
skills/ — 303 workflow skills and domain knowledge
|
||||
commands/ — 95 slash commands
|
||||
hooks/ — Trigger-based automations
|
||||
rules/ — Always-follow guidelines (common + per-language)
|
||||
|
||||
@@ -141,12 +141,12 @@ Instead of rebuilding that process in every prompt, you install it once and make
|
||||
|
||||
ECC is MIT-licensed open source. It works best with Claude Code today, has a supported Codex sync path, and provides capability-limited adapters for Cursor, OpenCode, Gemini, Zed, GitHub Copilot, Antigravity, Qwen, and other harnesses. See the [support status matrix](#platform-support) before assuming feature parity.
|
||||
|
||||
Access to 71 agents, 302 skills, and 95 legacy command shims, plus hooks, rules, memory, continuous learning, and AgentShield security scanning. The agents are specialized for planning, review, build repair, security, architecture, and domain work.
|
||||
Access to 71 agents, 303 skills, and 95 legacy command shims, plus hooks, rules, memory, continuous learning, and AgentShield security scanning. The agents are specialized for planning, review, build repair, security, architecture, and domain work.
|
||||
|
||||
| Included | Count | What it gives you |
|
||||
| ---------------- | ----------: | ------------------------------------------------------------------------------------ |
|
||||
| Agents | 71 agents | Planning, review, build repair, security, architecture, and domain work |
|
||||
| Skills | 302 skills | TDD, research, security, docs, frontend, data, ML, operations, and more |
|
||||
| Skills | 303 skills | TDD, research, security, docs, frontend, data, ML, operations, and more |
|
||||
| Commands | 95 commands | Convenient entry points while ECC moves to a skills-first surface |
|
||||
| Hooks and memory | Runtime | Enforcement, session summaries, continuous learning, instincts, and context controls |
|
||||
| Rules | Selective | Always-loaded standards you choose by language or project |
|
||||
@@ -828,7 +828,7 @@ Stable graduation of the 2.0 line: control-pane substrate, worktree lifecycle se
|
||||
```text
|
||||
ECC/
|
||||
|-- agents/ # 71 specialized subagents for delegation
|
||||
|-- skills/ # 302 reusable workflows loaded on demand
|
||||
|-- skills/ # 303 reusable workflows loaded on demand
|
||||
|-- commands/ # 95 maintained slash-command shims
|
||||
|-- rules/ # opt-in common and language standards
|
||||
|-- hooks/ # runtime automation and enforcement
|
||||
|
||||
+1
-1
@@ -200,7 +200,7 @@ Copy-Item -Recurse rules/typescript "$HOME/.claude/rules/"
|
||||
/plugin list ecc@ecc
|
||||
```
|
||||
|
||||
**完成！** 你现在可以使用 71 个代理、302 个技能和 95 个命令。
|
||||
**完成！** 你现在可以使用 71 个代理、303 个技能和 95 个命令。
|
||||
|
||||
### multi-* 命令需要额外配置
|
||||
|
||||
|
||||
@@ -1,7 +1,7 @@
|
||||
# Soul
|
||||
|
||||
## Core Identity
|
||||
ECC is a production-ready AI coding plugin with 71 specialized agents, 302 skills, 95 commands, and automated hook workflows for software development.
|
||||
ECC is a production-ready AI coding plugin with 71 specialized agents, 303 skills, 95 commands, and automated hook workflows for software development.
|
||||
|
||||
## Core Principles
|
||||
1. **Agent-First** — route work to the right specialist as early as possible.
|
||||
|
||||
@@ -34,6 +34,7 @@ skills:
|
||||
- claude-devfleet
|
||||
- click-path-audit
|
||||
- clickhouse-io
|
||||
- brownfield-retrospective
|
||||
- codebase-onboarding
|
||||
- coding-standards
|
||||
- compose-multiplatform-patterns
|
||||
|
||||
@@ -1,6 +1,6 @@
|
||||
# ECC — 智能体指令
|
||||
|
||||
这是一个**生产就绪的 AI 编码插件**，提供 71 个专业代理、302 项技能、95 条命令以及自动化钩子工作流，用于软件开发。
|
||||
这是一个**生产就绪的 AI 编码插件**，提供 71 个专业代理、303 项技能、95 条命令以及自动化钩子工作流，用于软件开发。
|
||||
|
||||
**版本:** 2.2.3
|
||||
|
||||
@@ -147,7 +147,7 @@
|
||||
|
||||
```
|
||||
agents/ — 71 个专业子代理
|
||||
skills/ — 302 个工作流技能和领域知识
|
||||
skills/ — 303 个工作流技能和领域知识
|
||||
commands/ — 95 个斜杠命令
|
||||
hooks/ — 基于触发的自动化
|
||||
rules/ — 始终遵循的指导方针（通用 + 每种语言）
|
||||
|
||||
@@ -264,7 +264,7 @@ Copy-Item -Recurse rules/typescript "$HOME/.claude/rules/"
|
||||
/plugin list ecc@ecc
|
||||
```
|
||||
|
||||
**搞定！** 你现在可以使用 71 个智能体、302 项技能和 95 个命令了。
|
||||
**搞定！** 你现在可以使用 71 个智能体、303 项技能和 95 个命令了。
|
||||
|
||||
***
|
||||
|
||||
@@ -1178,7 +1178,7 @@ opencode
|
||||
|---------|---------------|----------|--------|
|
||||
| 智能体 | PASS: 71 个 | PASS: 12 个 | **Claude Code 领先** |
|
||||
| 命令 | PASS: 95 个 | PASS: 35 个 | **Claude Code 领先** |
|
||||
| 技能 | PASS: 302 项 | PASS: 37 项 | **Claude Code 领先** |
|
||||
| 技能 | PASS: 303 项 | PASS: 37 项 | **Claude Code 领先** |
|
||||
| 钩子 | PASS: 8 种事件类型 | PASS: 11 种事件 | **OpenCode 更多！** |
|
||||
| 规则 | PASS: 29 条 | PASS: 13 条指令 | **Claude Code 领先** |
|
||||
| MCP 服务器 | PASS: 14 个 | PASS: 完整 | **完全对等** |
|
||||
@@ -1286,7 +1286,7 @@ ECC 是**第一个最大化利用每个主要 AI 编码工具的插件**。以
|
||||
|---------|-----------------------|------------|-----------|----------|
|
||||
| **智能体** | 71 | 共享 (AGENTS.md) | 共享 (AGENTS.md) | 12 |
|
||||
| **命令** | 95 | 共享 | 基于指令 | 35 |
|
||||
| **技能** | 302 | 共享 | 10 (原生格式) | 37 |
|
||||
| **技能** | 303 | 共享 | 10 (原生格式) | 37 |
|
||||
| **钩子事件** | 8 种类型 | 15 种类型 | SessionStart（1 种类型） | 11 种类型 |
|
||||
| **钩子脚本** | 20+ 个脚本 | 16 个脚本 (DRY 适配器) | 1 个 SessionStart 引导脚本 | 插件钩子 |
|
||||
| **规则** | 34 (通用 + 语言) | 34 (YAML 前页) | 基于指令 | 13 条指令 |
|
||||
|
||||
File diff suppressed because one or more lines are too long
@@ -377,6 +377,7 @@
|
||||
"skills/windows-desktop-e2e",
|
||||
"skills/agent-self-evaluation",
|
||||
"skills/architecture-decision-records",
|
||||
"skills/brownfield-retrospective",
|
||||
"skills/browser-qa",
|
||||
"skills/ck",
|
||||
"skills/click-path-audit",
|
||||
|
||||
+3
-2
@@ -474,7 +474,8 @@
|
||||
"!**/*.pyo",
|
||||
"!**/*.pyd",
|
||||
"!**/.pytest_cache/**",
|
||||
"skills/conventional-commit-review/"
|
||||
"skills/conventional-commit-review/",
|
||||
"skills/brownfield-retrospective/"
|
||||
],
|
||||
"bin": {
|
||||
"ecc": "scripts/ecc.js",
|
||||
@@ -485,7 +486,7 @@
|
||||
"ecc-universal": "scripts/ecc.js"
|
||||
},
|
||||
"scripts": {
|
||||
"welcome": "echo '\\n ecc-universal installed!\\n Run: ecc typescript\\n Compat: ecc-install typescript\\n Docs: https://github.com/affaan-m/ECC\\n Run or self-host any open-source model.\\n Compute: Itô is the preferred compute sponsor — https://compute.itomarkets.com\\n Any GPU provider works. This sponsorship link is passive: it does not invoke an RFQ, reserve capacity, provision compute, or configure serving.\\n Separately, the opt-in ecc ito find bridge invokes the explicitly configured canonical Itô CLI and submits a live authenticated RFQ; it does not reserve capacity.\\n Managed inference through Itô is not live yet.\\n'",
|
||||
"welcome": "echo '\\n ecc-universal installed!\\n Run: ecc typescript\\n Compat: ecc-install typescript\\n Docs: https://github.com/affaan-m/ECC\\n Run or self-host any open-source model.\\n Compute: It\u00f4 is the preferred compute sponsor \u2014 https://compute.itomarkets.com\\n Any GPU provider works. This sponsorship link is passive: it does not invoke an RFQ, reserve capacity, provision compute, or configure serving.\\n Separately, the opt-in ecc ito find bridge invokes the explicitly configured canonical It\u00f4 CLI and submits a live authenticated RFQ; it does not reserve capacity.\\n Managed inference through It\u00f4 is not live yet.\\n'",
|
||||
"catalog:check": "node scripts/ci/catalog.js --text",
|
||||
"context-profiles:check": "node scripts/ci/validate-context-profiles.js",
|
||||
"catalog:sync": "node scripts/ci/catalog.js --write --text",
|
||||
|
||||
@@ -0,0 +1,177 @@
|
||||
---
|
||||
name: brownfield-retrospective
|
||||
description: Run the ECC engineering process retroactively against an existing project slice. Audit current state, reconstruct past decisions, produce a four-axis gap register (thinking, coding practice, missing features, technology selection), then execute fixes forward through the plan-TDD-review pipeline. Use when adopting ECC mid-project, taking over an inherited codebase, or asking what was missed and what would have been built differently from day one.
|
||||
metadata:
|
||||
origin: ECC
|
||||
---
|
||||
|
||||
# Brownfield Retrospective
|
||||
|
||||
Run ECC's engineering process retroactively against a project that was built without it. Pick any slice of an existing codebase, audit what exists, reconstruct how it got there, extract a four-axis gap register, then execute the fixes forward through the standard ECC pipeline.
|
||||
|
||||
The workflow is slice-first: no whole-repo onboarding is required before it is useful, and every phase is re-enterable from a durable artifact on disk. Start in the middle, work backwards, then move forward.
|
||||
|
||||
## When to Activate
|
||||
|
||||
- Adopting ECC in a repository that already exists and is already shaped
|
||||
- User asks to "audit my existing project", "retro this codebase", or "what did we miss?"
|
||||
- Taking over, inheriting, or returning to a codebase after a long gap
|
||||
- User asks "why is it like this?" followed by "should it stay like this?"
|
||||
- A module, feature, or service needs a rethink before the next feature lands on top of it
|
||||
- Deciding whether a legacy area should be fixed forward, rewritten, or left documented as-is
|
||||
|
||||
## When Not to Use
|
||||
|
||||
- Greenfield work with no existing code — use `planner` and `tdd-workflow` directly
|
||||
- Onboarding to spec-driven development without the redesign loop — the `spec-miner` agent does that on its own
|
||||
- A launch go/no-go production-readiness pass — use `production-audit`
|
||||
- Security-only sweeps — use `security-review`
|
||||
- Team process retrospectives (sprint ceremonies) — this audits a codebase, not people
|
||||
|
||||
## The Working Set
|
||||
|
||||
All artifacts are written inside the audited project, under `docs/retro/<slice>/`:
|
||||
|
||||
| File | Phase | Purpose |
|
||||
|------|-------|---------|
|
||||
| `gap-register.md` | 0-6 | The state machine — perimeter, `Current phase:` marker, and rows. The only file required to resume mid-stream. |
|
||||
| `baseline-audit.md` | 1 | Reviewer findings, test/CI snapshot, TODO inventory. |
|
||||
| `reconstructed-spec.md` | 2 | What the code actually does today (Requirements + Invariants). |
|
||||
| `target-design.md` | 4 | Target shape for the slice and the fix sequence. |
|
||||
|
||||
Backfilled decisions go to `docs/adr/` per the `architecture-decision-records` skill. If the project uses OpenSpec, `reconstructed-spec.md` may instead be `openspec/specs/<capability>/spec.md` produced by `spec-miner`.
|
||||
|
||||
## How It Works
|
||||
|
||||
### Phase 0 — Pick the Entry Point
|
||||
|
||||
Start from what the user cares about today. Do not map the whole repo first.
|
||||
|
||||
Any of these is a valid slice:
|
||||
|
||||
| User signal | Slice |
|
||||
|-------------|-------|
|
||||
| Names a directory, module, or service | That path plus its direct callers |
|
||||
| Names a feature or user flow | The files that implement it, traced from the entry point |
|
||||
| Names a bug, incident, or pain point | The code that produced it plus one level of call chain |
|
||||
| Names a dependency or tech choice | Everything that touches it |
|
||||
| Names nothing | The 2-3 hottest paths by churn — propose them and let the user pick |
|
||||
|
||||
Record the perimeter at the top of `gap-register.md` before anything else: paths in scope, entry points, callers, blast radius. Budget the slice at roughly 15 files or 2,000 lines; if the user's pick is bigger, cut it into named sub-slices and register each as its own row of work. A slice too big to audit in one session is a slice that never finishes. Keep a `Current phase:` marker beside the perimeter and advance it each time a phase completes.
|
||||
|
||||
### Phase 1 — Present-State Audit
|
||||
|
||||
Establish what exists now, with evidence. Do not fix anything yet.
|
||||
|
||||
1. Recon the slice: manifest and framework fingerprint, entry points, test layout, CI checks (borrow the recon steps from `codebase-onboarding`, scoped to the perimeter).
|
||||
2. Run the reviewers that match the stack, in parallel where possible. Every finding must carry a `file:line` pointer:
|
||||
- The language reviewer for the stack (`typescript-reviewer`, `python-reviewer`, `go-reviewer`, ...)
|
||||
- `security-reviewer`
|
||||
- `silent-failure-hunter` for swallowed errors
|
||||
- `type-design-analyzer` where invariants are encoded in types
|
||||
- `performance-optimizer` only if the slice is on a hot path
|
||||
3. Snapshot the current state: test count and coverage, lint/CI status, `TODO`/`FIXME`/`HACK` inventory inside the perimeter.
|
||||
|
||||
Write everything to `baseline-audit.md`. Findings that get fixed during this phase corrupt the baseline — hold them for the register.
|
||||
|
||||
### Phase 2 — Backward Reconstruction
|
||||
|
||||
Work backwards from the present state to the decisions that produced it.
|
||||
|
||||
1. Mine the behavioral spec: run `spec-miner` against the slice. Its Requirements (WHEN → THEN) and Invariants become `reconstructed-spec.md` — the baseline truth for Phase 5 tests.
|
||||
2. Git archaeology on the perimeter:
|
||||
- `git log --oneline -- <slice>` for directory history; use `--follow` only with a single file path — age, authors, cadence
|
||||
- Largest and most reverted commits — where the design changed under pressure
|
||||
- Churn hotspots — files changed far more often than neighbors
|
||||
- Dead ends — branches or scaffolding that never shipped
|
||||
3. Decision inventory: list the significant decisions frozen into the code (stack and framework choices, data model, boundaries, error strategy, state management). Check each against `docs/adr/`, README, and comments. Every decision with no written record is itself a pre-existing thinking gap — record it in Phase 3, do not silently backfill it here.
|
||||
4. Where behavior is opaque, use `code-explorer` to trace execution paths before guessing at intent.
|
||||
|
||||
### Phase 3 — Gap Analysis (Four Axes)
|
||||
|
||||
Convert the audit and reconstruction into register rows. One axis per class of gap:
|
||||
|
||||
| Axis | Question | Sources |
|
||||
|------|-----------|---------|
|
||||
| Thinking | What was decided but never recorded? Which invariants live only in code? | Decision inventory, reconstructed spec |
|
||||
| Coding practice | Where does the code diverge from how ECC would have written it? | Phase 1 findings, the `rules/` pack for the language, spec items with no test anchor |
|
||||
| Missing features | What would a day-one build have included that this slice never got? | Boundary input validation, observability, rate limiting, idempotency, migrations plus rollback, a11y, i18n, user docs, CI gates |
|
||||
| Technology selection | Is the chosen tech fighting the codebase? Outdated, duplicated, risky, or missing? | Dependency inventory, git archaeology, recon |
|
||||
|
||||
Register format (the table is the skill's durable output):
|
||||
|
||||
```markdown
|
||||
| ID | Axis | Gap | Evidence | Forward fix | Severity | Effort | Status |
|
||||
|----|------|-----|----------|-------------|----------|--------|--------|
|
||||
| G-001 | practice | Errors swallowed in retry loop | src/api/retry.ts:42 | Propagate + map at boundary | P1 | S | open |
|
||||
```
|
||||
|
||||
- Severity: `P0` security exposure or data loss, `P1` correctness, `P2` practice and observability, `P3` selection and cleanup.
|
||||
- Effort: `S` under a session, `M` a few sessions, `L` needs its own plan.
|
||||
- Status: `open`, `in-progress`, `done`, `wont-fix`.
|
||||
- Every row needs an evidence pointer. A gap you cannot point at is an opinion.
|
||||
|
||||
### Phase 4 — Redesign / Rethink
|
||||
|
||||
Turn the register into a sequenced plan. Follow the project's existing task and approval authority. Keep the register as audit evidence linked to that system; do not create competing canonical task state. Confirm scope and obtain project-required approval before a rewrite, technology replacement, migration, or other material change.
|
||||
|
||||
1. Run `architect` or `code-architect` over the `P0` and `P1` rows to produce `target-design.md`: target shape for the slice, the fix sequence, and an explicit "what does not change" list to protect working behavior.
|
||||
2. Backfill retro-ADRs for every undocumented decision from Phase 2. Mark them as reconstructed (`status: proposed (reconstructed)`, date of the retro, note the original decision predates the record). Separate observed history from inferred intent, and have the project owner confirm a decision before marking it accepted. Never present a backfilled ADR as if it were written at decision time.
|
||||
3. Triage every register row into one of: `fix-forward` (repair in place), `rewrite` (replace the slice), `leave-documented` (wont-fix). A `wont-fix` must record its reason in the register — a wont-fix with a reason closes the thinking gap; a silent one reopens it.
|
||||
4. Sequence the backlog: `P0` first, then interleave quick wins with larger repairs to keep momentum.
|
||||
|
||||
### Phase 5 — Forward Execution
|
||||
|
||||
Work the register through the standard ECC pipeline, one row per session as a baseline pace:
|
||||
|
||||
```text
|
||||
planner (scope the row)
|
||||
→ tdd-guide (failing test first — for a legacy gap the first test
|
||||
usually encodes the missing invariant from reconstructed-spec.md)
|
||||
→ implement
|
||||
→ code-reviewer
|
||||
→ security-reviewer (if the row touches input, auth, or data)
|
||||
→ doc-updater + ADR (if the decision changed)
|
||||
→ conventional commit
|
||||
→ mark the register row done
|
||||
```
|
||||
|
||||
- Update `gap-register.md` statuses as rows close; the register is the durable state, not the conversation.
|
||||
- On session boundaries, hand off through the project's memory mechanism (`unified-memory`, context carriers) so the next session resumes from the register alone.
|
||||
|
||||
### Phase 6 — Closure and Re-Audit
|
||||
|
||||
When every row is `done` or `wont-fix`:
|
||||
|
||||
1. Re-run the Phase 1 audit over the same perimeter.
|
||||
2. Diff against `baseline-audit.md` and verify with `verification-loop` — the gaps claimed closed must stay closed.
|
||||
3. Record the delta (findings then, findings now, rows closed, rows deferred) at the bottom of `gap-register.md`.
|
||||
4. Anything that resurfaced becomes a new row, not a failure — the register is a loop, not a one-shot.
|
||||
|
||||
## Resuming Mid-Stream
|
||||
|
||||
Any session can start in the middle. Read `docs/retro/<slice>/gap-register.md` first:
|
||||
|
||||
- Register exists with a row `in-progress` → Phase 5, finish that row.
|
||||
- Register exists with at least one row, all rows closed → Phase 6.
|
||||
- Register exists, rows open, none in progress → resume at the `Current phase:` marker (Phase 3 register awaiting triage, or Phase 4 backlog awaiting its first row).
|
||||
- No register, but `baseline-audit.md` exists → Phase 2.
|
||||
- No artifacts at all → Phase 0 with the user.
|
||||
|
||||
## Anti-Patterns
|
||||
|
||||
- Auditing the whole repo before any slice — the workflow is slice-first by design.
|
||||
- Fixing code during Phases 1-3 — audit phases produce the register; edits mid-audit corrupt the baseline.
|
||||
- Register rows without evidence pointers.
|
||||
- `wont-fix` without a recorded reason.
|
||||
- Presenting backfilled ADRs as contemporaneous records.
|
||||
- Skipping the Phase 6 re-audit — closure is verified, not declared.
|
||||
|
||||
## Related Skills
|
||||
|
||||
- `codebase-onboarding` — recon baseline for Phase 1
|
||||
- `architecture-decision-records` — retro-ADR backfill in Phase 4
|
||||
- `tdd-workflow` — Phase 5 execution discipline
|
||||
- `verification-loop` — Phase 6 closure
|
||||
- `production-audit` — launch-readiness lens (complementary, later)
|
||||
- `security-review` — security-only requests
|
||||
Reference in New Issue
Block a user