affaan-m · AbhiramMandala · Aug 31, 2026 · Sep 8, 2026 · Sep 8, 2026
@@ -231,6 +231,10 @@ jobs:
         run: npm run command-registry:check
         continue-on-error: false
 
+      - name: Validate discovery index
+        run: npm run discovery:check
+        continue-on-error: false
+
       - name: Check unicode safety
         run: node scripts/ci/check-unicode-safety.js
         continue-on-error: false

@@ -0,0 +1,47 @@
+# Adopters
+
+Teams and projects that run ECC in real work. Seeing who else uses a tool is
+usually the last thing someone checks before adopting it, so this page is worth
+keeping current.
+
+Listing is opt-in and self-reported. Nobody is added without asking.
+
+## How to add yourself
+
+Open a pull request that adds one row to the table below, or use the
+[quick feedback form](https://github.com/affaan-m/ECC/issues/new?template=quick-feedback.yml)
+and say you want to be listed.
+
+One row, this shape:
+
+```markdown
+| Organisation or project | Harness | How ECC is used | Contact |
+```
+
+- **Harness** — Claude Code, Codex, Cursor, OpenCode, or several.
+- **How ECC is used** — one sentence. What it replaced is more useful than what it is.
+- **Contact** — a GitHub handle, or `—` if you would rather not.
+
+Only add an organisation you are authorised to speak for.
+
+## Adopters
+
+<!-- Add new rows at the end. Keep them alphabetical by first column. -->
+
+| Organisation or project | Harness | How ECC is used | Contact |
+| ----------------------- | ------- | --------------- | ------- |
+| _Your team could be first._ | | | |
+
+## Partners and sponsors
+
+Distinct from adopters: these organisations fund or partner with the project.
+They are listed in the [README](README.md) and in [SPONSORS.md](SPONSORS.md).
+Sponsorship is not an endorsement of production use, and production use is not
+sponsorship.
+
+## Case studies
+
+Longer write-ups of ECC in a real codebase. If you have published one, link it
+here in the same pull request that adds your row.
+
+- _None yet. If you write one, it will be linked from the README too._
@@ -0,0 +1,27 @@
+cff-version: 1.2.0
+title: "ECC: The Agent Harness Operating System"
+message: "If you use ECC in research, writing, or a derived tool, please cite it."
+type: software
+authors:
+  - family-names: Mustafa
+    given-names: Affaan
+    website: "https://x.com/affaan"
+repository-code: "https://github.com/affaan-m/ECC"
+url: "https://ecc.tools"
+abstract: >-
+  ECC is an MIT-licensed agent harness operating system for coding agents such
+  as Claude Code, Codex, Cursor, and OpenCode. It installs a repeatable
+  engineering loop - plan, test, implement, review, verify, remember, improve -
+  as skills, agents, commands, hooks, and rules, together with the AgentShield
+  scanner for prompts, hooks, MCP configuration, permissions, and secrets.
+keywords:
+  - ai-agents
+  - agent-harness
+  - claude-code
+  - developer-tools
+  - llm
+  - mcp
+  - software-engineering
+license: MIT
+version: 2.2.0
+date-released: "2026-08-28"
@@ -5,6 +5,7 @@ Thanks for wanting to contribute! This repo is a community resource for Claude C
 ## Table of Contents
 
 - [What We're Looking For](#what-were-looking-for)
+- [Your First Contribution](#your-first-contribution)
 - [Quick Start](#quick-start)
 - [Contributing Skills](#contributing-skills)
 - [Skill Adaptation Policy](#skill-adaptation-policy)
@@ -48,6 +49,33 @@ Slash commands that invoke useful workflows:
 
 ---
 
+## Your First Contribution
+
+You do not need to understand the whole repository to help. These are scoped so
+that reading one directory is enough.
+
+- **[good first issue](https://github.com/affaan-m/ECC/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22)** — scoped on purpose. Comment on one to claim it.
+- **A missing test.** Anything in `scripts/lib/` without a matching file in `tests/lib/` is fair game.
+- **A translation.** `docs/<locale>/` pages drift behind the English ones.
+- **An adopter row.** If you run ECC, add yourself to [ADOPTERS.md](ADOPTERS.md).
+- **A broken instruction.** If a step in the README failed for you, the fix to that step is a real contribution.
+
+### What to expect after you open a pull request
+
+- Triage within one business week: merged, changes requested, or closed with a
+  reason. Security reports are handled first and jump the queue.
+- Automated checks run first. A red build is the most common reason a review
+  stalls, so run `node tests/run-all.js` locally before pushing.
+- If a week passes with no response, comment on the thread. That is a useful
+  nudge, not noise.
+
+Questions that are not yet a pull request belong in
+[Q&A discussions](https://github.com/affaan-m/ECC/discussions/categories/q-a) or
+[Discord](https://discord.gg/36yGMHGFbR). See [SUPPORT.md](SUPPORT.md) for the
+full routing.
+
+---
+
 ## Quick Start
 
 ```bash

@@ -2,66 +2,30 @@
   <img src="assets/hero.png" alt="ECC - the agent harness operating system" width="100%" />
 </p>
 
-<p align="center">
-  <a href="https://www.star-history.com/affaan-m/ecc">
-    <picture>
-      <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/badge?repo=affaan-m/ECC&type=trending&theme=dark" />
-      <img src="https://api.star-history.com/badge?repo=affaan-m/ECC&type=trending" alt="GitHub Trending Repository of the Day" height="46" />
-    </picture>
-  </a>
-  <a href="https://www.star-history.com/affaan-m/ecc">
-    <picture>
-      <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/badge?repo=affaan-m/ECC&type=rank&theme=dark" />
-      <img src="https://api.star-history.com/badge?repo=affaan-m/ECC&type=rank" alt="Star History Global Rank" height="46" />
-    </picture>
-  </a>
-</p>
+# ECC
 
-<p align="center">
-  <strong>Language:</strong>
-  <a href="README.md">English</a> |
-  <a href="docs/pt-BR/README.md">Português (Brasil)</a> |
-  <a href="README.zh-CN.md">简体中文</a> |
-  <a href="docs/zh-TW/README.md">繁體中文</a> |
-  <a href="docs/ja-JP/README.md">日本語</a> |
-  <a href="docs/ko-KR/README.md">한국어</a> |
-  <a href="docs/tr/README.md">Türkçe</a> |
-  <a href="docs/ru/README.md">Русский</a> |
-  <a href="docs/vi-VN/README.md">Tiếng Việt</a> |
-  <a href="docs/th/README.md">ไทย</a> |
-  <a href="docs/de-DE/README.md">Deutsch</a> |
-  <a href="docs/es/README.md">Español</a> |
-  <a href="docs/uk-UA/README.md">Українська</a>
-</p>
+Your agent can write code, but ECC gives it a coordinated engineering system and toolbox: it plans before it builds, verifies changes with tests, reviews its own work from a fresh context, remembers what matters, and turns repeated wins into reusable skills and workflows.
 
-<p align="center">
-  <a href="https://discord.gg/36yGMHGFbR"><img src="https://img.shields.io/discord/1496644400590094540?logo=discord&logoColor=white&label=Discord&color=5865F2" alt="Discord" /></a>
-  <a href="https://ecc.tools"><img src="https://img.shields.io/badge/Website-ecc.tools-E07856?logo=googlechrome&logoColor=white" alt="Website" /></a>
-  <a href="https://github.com/apps/ecc-tools"><img src="https://img.shields.io/badge/GitHub%20App-ECC%20Tools-181717?logo=github&logoColor=white" alt="GitHub App" /></a>
-  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT license" /></a>
-</p>
+```text
+plan -> test -> implement -> review -> verify -> remember -> improve
+```
 
-<p align="center">
-  <a href="https://github.com/affaan-m/ECC/stargazers"><img src="https://img.shields.io/endpoint?url=https%3A%2F%2Fapi.ecc.tools%2Fbadge%2Fstars&style=flat" alt="Stars" /></a>
-  <a href="https://github.com/affaan-m/ECC/network/members"><img src="https://img.shields.io/endpoint?url=https%3A%2F%2Fapi.ecc.tools%2Fbadge%2Fforks&style=flat" alt="Forks" /></a>
-  <a href="https://github.com/affaan-m/ECC/graphs/contributors"><img src="https://img.shields.io/github/contributors/affaan-m/ECC?style=flat" alt="Contributors" /></a>
-  <a href="https://github.com/marketplace/ecc-tools"><img src="https://img.shields.io/endpoint?url=https%3A%2F%2Fapi.ecc.tools%2Fbadge%2Finstalls&logo=github" alt="GitHub App installs" /></a>
-</p>
+Instead of rebuilding that process in every prompt, you install it once and make it part of how your agent works.
 
-<p align="center">
-  <a href="https://www.npmjs.com/package/ecc-universal"><img src="https://img.shields.io/npm/dw/ecc-universal?label=ecc-universal&logo=npm" alt="ecc-universal npm downloads" /></a>
-  <a href="https://www.npmjs.com/package/ecc-agentshield"><img src="https://img.shields.io/npm/dw/ecc-agentshield?label=ecc-agentshield&logo=npm" alt="ecc-agentshield npm downloads" /></a>
-</p>
+> Optimize the context window. Persist everything else.
 
-<p align="center">
-  <img src="https://img.shields.io/badge/-Shell-4EAA25?logo=gnu-bash&logoColor=white" alt="Shell" />
-  <img src="https://img.shields.io/badge/-TypeScript-3178C6?logo=typescript&logoColor=white" alt="TypeScript" />
-  <img src="https://img.shields.io/badge/-Python-3776AB?logo=python&logoColor=white" alt="Python" />
-  <img src="https://img.shields.io/badge/-Go-00ADD8?logo=go&logoColor=white" alt="Go" />
-  <img src="https://img.shields.io/badge/-Java-ED8B00?logo=openjdk&logoColor=white" alt="Java" />
-  <img src="https://img.shields.io/badge/-Perl-39457E?logo=perl&logoColor=white" alt="Perl" />
-  <img src="https://img.shields.io/badge/-Markdown-000000?logo=markdown&logoColor=white" alt="Markdown" />
-</p>
+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 68 agents, 286 skills, and 94 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           |   68 agents | Planning, review, build repair, security, architecture, and domain work              |
+| Skills           |  286 skills | TDD, research, security, docs, frontend, data, ML, operations, and more              |
+| Commands         | 94 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                            |
+| AgentShield      |    Included | Scanning for prompts, hooks, MCP config, permissions, secrets, and agent files       |
 
 > [!WARNING]
 > **Official sources only.** Install ECC only from verified channels: the GitHub repository [github.com/affaan-m/ECC](https://github.com/affaan-m/ECC), the npm packages [`ecc-universal`](https://www.npmjs.com/package/ecc-universal) and [`ecc-agentshield`](https://www.npmjs.com/package/ecc-agentshield), the [GitHub App](https://github.com/apps/ecc-tools), the plugin slug `ecc@ecc`, and the project website [ecc.tools](https://ecc.tools). Third-party re-uploads and unofficial mirrors are not maintained or reviewed by the project and may contain malware.
@@ -96,6 +60,31 @@ The native path installs ECC's skills, agents, commands, and plugin-managed hook
 > Both paths install the same `ecc@ecc` plugin. Choose one and do not stack
 > another manual Claude install on top.
 
+**See it run:** the [shortform guide](the-shortform-guide.md) walks one real
+session end to end. The [longform guide](the-longform-guide.md) covers the whole
+system, and the [security guide](the-security-guide.md) covers AgentShield.
+
+<p align="center">
+  <strong>Shipping weekly.</strong>
+  <a href="https://github.com/affaan-m/ECC/subscription">Watch → Custom → Releases</a>
+  to get each release once, with no other notifications.
+  <a href="https://discord.gg/36yGMHGFbR">Discord</a> ·
+  <a href="https://ecc.tools">ecc.tools</a> ·
+  <a href="ROADMAP.md">Roadmap</a>
+</p>
+
+<p align="center">
+  <a href="https://www.star-history.com/affaan-m/ecc">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="assets/star-history-dark.svg" />
+      <img src="assets/star-history-light.svg" alt="ECC star history: first 40,000 stars, January 18 to February 7, 2026" width="100%" />
+    </picture>
+  </a>
+</p>
+
+<details>
+<summary>Sponsors, partners, and project links</summary>
+
 <div align="center">
 
 <table aria-label="ECC primary links">
@@ -146,42 +135,74 @@ The native path installs ECC's skills, agents, commands, and plugin-managed hook
 
 </div>
 
-<p align="center"><a href="#install-ecc">Jump to install ↓</a></p>
-
-# ECC
-
-Your agent can write code, but ECC gives it a coordinated engineering system and toolbox: it plans before it builds, verifies changes with tests, reviews its own work from a fresh context, remembers what matters, and turns repeated wins into reusable skills and workflows.
+</details>
 
-```text
-plan -> test -> implement -> review -> verify -> remember -> improve
-```
+<details>
+<summary>Badges, languages, and project stats</summary>
 
-Instead of rebuilding that process in every prompt, you install it once and make it part of how your agent works.
+<p align="center">
+  <a href="https://www.star-history.com/affaan-m/ecc">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/badge?repo=affaan-m/ECC&type=trending&theme=dark" />
+      <img src="https://api.star-history.com/badge?repo=affaan-m/ECC&type=trending" alt="GitHub Trending Repository of the Day" height="46" />
+    </picture>
+  </a>
+  <a href="https://www.star-history.com/affaan-m/ecc">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="https://api.star-history.com/badge?repo=affaan-m/ECC&type=rank&theme=dark" />
+      <img src="https://api.star-history.com/badge?repo=affaan-m/ECC&type=rank" alt="Star History Global Rank" height="46" />
+    </picture>
+  </a>
+</p>
 
-> Optimize the context window. Persist everything else.
+<p align="center">
+  <strong>Language:</strong>
+  <a href="README.md">English</a> |
+  <a href="docs/pt-BR/README.md">Português (Brasil)</a> |
+  <a href="README.zh-CN.md">简体中文</a> |
+  <a href="docs/zh-TW/README.md">繁體中文</a> |
+  <a href="docs/ja-JP/README.md">日本語</a> |
+  <a href="docs/ko-KR/README.md">한국어</a> |
+  <a href="docs/tr/README.md">Türkçe</a> |
+  <a href="docs/ru/README.md">Русский</a> |
+  <a href="docs/vi-VN/README.md">Tiếng Việt</a> |
+  <a href="docs/th/README.md">ไทย</a> |
+  <a href="docs/de-DE/README.md">Deutsch</a> |
+  <a href="docs/es/README.md">Español</a> |
+  <a href="docs/uk-UA/README.md">Українська</a>
+</p>
 
-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.
+<p align="center">
+  <a href="https://discord.gg/36yGMHGFbR"><img src="https://img.shields.io/discord/1496644400590094540?logo=discord&logoColor=white&label=Discord&color=5865F2" alt="Discord" /></a>
+  <a href="https://ecc.tools"><img src="https://img.shields.io/badge/Website-ecc.tools-E07856?logo=googlechrome&logoColor=white" alt="Website" /></a>
+  <a href="https://github.com/apps/ecc-tools"><img src="https://img.shields.io/badge/GitHub%20App-ECC%20Tools-181717?logo=github&logoColor=white" alt="GitHub App" /></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="MIT license" /></a>
+</p>
 
-Access to 68 agents, 286 skills, and 94 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.
+<p align="center">
+  <a href="https://github.com/affaan-m/ECC/stargazers"><img src="https://img.shields.io/endpoint?url=https%3A%2F%2Fapi.ecc.tools%2Fbadge%2Fstars&style=flat" alt="Stars" /></a>
+  <a href="https://github.com/affaan-m/ECC/network/members"><img src="https://img.shields.io/endpoint?url=https%3A%2F%2Fapi.ecc.tools%2Fbadge%2Fforks&style=flat" alt="Forks" /></a>
+  <a href="https://github.com/affaan-m/ECC/graphs/contributors"><img src="https://img.shields.io/github/contributors/affaan-m/ECC?style=flat" alt="Contributors" /></a>
+  <a href="https://github.com/marketplace/ecc-tools"><img src="https://img.shields.io/endpoint?url=https%3A%2F%2Fapi.ecc.tools%2Fbadge%2Finstalls&logo=github" alt="GitHub App installs" /></a>
+</p>
 
-| Included         |       Count | What it gives you                                                                    |
-| ---------------- | ----------: | ------------------------------------------------------------------------------------ |
-| Agents           |   68 agents | Planning, review, build repair, security, architecture, and domain work              |
-| Skills           |  286 skills | TDD, research, security, docs, frontend, data, ML, operations, and more              |
-| Commands         | 94 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                            |
-| AgentShield      |    Included | Scanning for prompts, hooks, MCP config, permissions, secrets, and agent files       |
+<p align="center">
+  <a href="https://www.npmjs.com/package/ecc-universal"><img src="https://img.shields.io/npm/dw/ecc-universal?label=ecc-universal&logo=npm" alt="ecc-universal npm downloads" /></a>
+  <a href="https://www.npmjs.com/package/ecc-agentshield"><img src="https://img.shields.io/npm/dw/ecc-agentshield?label=ecc-agentshield&logo=npm" alt="ecc-agentshield npm downloads" /></a>
+</p>
 
 <p align="center">
-  <a href="https://www.star-history.com/affaan-m/ecc">
-    <picture>
-      <source media="(prefers-color-scheme: dark)" srcset="assets/star-history-dark.svg" />
-      <img src="assets/star-history-light.svg" alt="ECC star history: first 40,000 stars, January 18 to February 7, 2026" width="100%" />
-    </picture>
-  </a>
+  <img src="https://img.shields.io/badge/-Shell-4EAA25?logo=gnu-bash&logoColor=white" alt="Shell" />
+  <img src="https://img.shields.io/badge/-TypeScript-3178C6?logo=typescript&logoColor=white" alt="TypeScript" />
+  <img src="https://img.shields.io/badge/-Python-3776AB?logo=python&logoColor=white" alt="Python" />
+  <img src="https://img.shields.io/badge/-Go-00ADD8?logo=go&logoColor=white" alt="Go" />
+  <img src="https://img.shields.io/badge/-Java-ED8B00?logo=openjdk&logoColor=white" alt="Java" />
+  <img src="https://img.shields.io/badge/-Perl-39457E?logo=perl&logoColor=white" alt="Perl" />
+  <img src="https://img.shields.io/badge/-Markdown-000000?logo=markdown&logoColor=white" alt="Markdown" />
 </p>
 
+</details>
+
 ## Install ECC
 
 > [!IMPORTANT]
@@ -2198,6 +2219,11 @@ The short version:
 - **Longform Guide (Advanced):** [The Longform Guide to ECC](https://x.com/affaan/status/2014040193557471352)
 - **Security Guide:** [Security Guide](./the-security-guide.md) | [Thread](https://x.com/affaan/status/2033263813387223421)
 - **Follow:** [@affaan](https://x.com/affaan)
+- **Getting help:** [SUPPORT.md](./SUPPORT.md)
+- **What ships next:** [ROADMAP.md](./ROADMAP.md)
+- **Who runs ECC:** [ADOPTERS.md](./ADOPTERS.md)
+- **Citing ECC:** [CITATION.cff](./CITATION.cff)
+- **Machine-readable catalog:** [llms.txt](./llms.txt) | [full catalog](./docs/discovery/llms-full.txt) | [JSON index](./docs/DISCOVERY-INDEX.json)
 
 ## License