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: clarify install and uninstall paths

Affaan Mustafa177b8f31da1f
diff --git a/README.md b/README.md
index d5c65da67..9005dbca2 100644
--- a/README.md
+++ b/README.md
@@ -167,7 +167,17 @@ See the full changelog in [Releases](https://github.com/affaan-m/everything-clau
Get up and running in under 2 minutes:
-### Step 1: Install the Plugin
+### Pick one path only
+
+Most Claude Code users should use exactly one install path:
+
+- **Recommended default:** install the Claude Code plugin, then copy only the rule folders you actually want.
+- **Use the manual installer only if** you want finer-grained control, want to avoid the plugin path entirely, or your Claude Code build has trouble resolving the self-hosted marketplace entry.
+- **Do not stack install methods.** The most common broken setup is: `/plugin install` first, then `install.sh --profile full` or `npx ecc-install --profile full` afterward.
+
+If you already layered multiple installs and things look duplicated, skip straight to [Reset / Uninstall ECC](#reset--uninstall-ecc).
+
+### Step 1: Install the Plugin (Recommended)
> NOTE: The plugin is convenient, but the OSS installer below is still the most reliable path if your Claude Code build has trouble resolving self-hosted marketplace entries.
@@ -195,9 +205,11 @@ This is intentional. Anthropic marketplace/plugin installs are keyed by a canoni
>
> If you already installed ECC via `/plugin install`, **do not run `./install.sh --profile full`, `.\install.ps1 --profile full`, or `npx ecc-install --profile full` afterward**. The plugin already loads ECC skills, commands, and hooks. Running the full installer after a plugin install copies those same surfaces into your user directories and can create duplicate skills plus duplicate runtime behavior.
>
-> For plugin installs, manually copy only the `rules/` directories you want. Use the full installer only when you are doing a fully manual ECC install instead of the plugin path.
+> For plugin installs, manually copy only the `rules/` directories you want. Start with `rules/common` plus one language or framework pack you actually use. Do not copy every rules directory unless you explicitly want all of that context in Claude.
>
-> If your local Claude setup was wiped or reset, that does not mean you need to repurchase ECC. Start with `ecc list-installed`, then run `ecc doctor` and `ecc repair` before reinstalling anything. That usually restores ECC-managed files without rebuilding your setup. If the problem is account or marketplace access for ECC Tools, handle billing/account recovery separately.
+> Use the full installer only when you are doing a fully manual ECC install instead of the plugin path.
+>
+> If your local Claude setup was wiped or reset, that does not mean you need to repurchase ECC. Start with `node scripts/ecc.js list-installed`, then run `node scripts/ecc.js doctor` and `node scripts/ecc.js repair` before reinstalling anything. That usually restores ECC-managed files without rebuilding your setup. If the problem is account or marketplace access for ECC Tools, handle billing/account recovery separately.
```bash
# Clone the repo first
@@ -231,6 +243,57 @@ Copy-Item -Recurse rules/typescript "$HOME/.claude/rules/"
For manual install instructions see the README in the `rules/` folder. When copying rules manually, copy the whole language directory (for example `rules/common` or `rules/golang`), not the files inside it, so relative references keep working and filenames do not collide.
+### Fully manual install (Fallback)
+
+Use this only if you are intentionally skipping the plugin path:
+
+```bash
+./install.sh --profile full
+```
+
+```powershell
+.\install.ps1 --profile full
+# or
+npx ecc-install --profile full
+```
+
+If you choose this path, stop there. Do not also run `/plugin install`.
+
+### Reset / Uninstall ECC
+
+If ECC feels duplicated, intrusive, or broken, do not keep reinstalling it on top of itself.
+
+- **Plugin path:** remove the plugin from Claude Code, then delete the specific rule folders you manually copied under `~/.claude/rules/`.
+- **Manual installer / CLI path:** from the repo root, preview removal first:
+
+```bash
+node scripts/uninstall.js --dry-run
+```
+
+Then remove ECC-managed files:
+
+```bash
+node scripts/uninstall.js
+```
+
+You can also use the lifecycle wrapper:
+
+```bash
+node scripts/ecc.js list-installed
+node scripts/ecc.js doctor
+node scripts/ecc.js repair
+node scripts/ecc.js uninstall --dry-run
+```
+
+ECC only removes files recorded in its install-state. It will not delete unrelated files it did not install.
+
+If you stacked methods, clean up in this order:
+
+1. Remove the Claude Code plugin install.
+2. Run the ECC uninstall command from the repo root to remove install-state-managed files.
+3. Delete any extra rule folders you copied manually and no longer want.
+4. Reinstall once, using a single path.
+
### Step 3: Start Using
```bash
diff --git a/tests/scripts/install-readme-clarity.test.js b/tests/scripts/install-readme-clarity.test.js
new file mode 100644
index 000000000..a6029edaa
--- /dev/null
+++ b/tests/scripts/install-readme-clarity.test.js
@@ -0,0 +1,88 @@
+/**
+ * Regression coverage for install/uninstall clarity in README.md.
+ */
+
+const assert = require('assert');
+const fs = require('fs');
+const path = require('path');
+
+const README = path.join(__dirname, '..', '..', 'README.md');
+
+function test(name, fn) {
+ try {
+ fn();
+ console.log(` \u2713 ${name}`);
+ return true;
+ } catch (error) {
+ console.log(` \u2717 ${name}`);
+ console.log(` Error: ${error.message}`);
+ return false;
+ }
+}
+
+function runTests() {
+ console.log('\n=== Testing install README clarity ===\n');
+
+ let passed = 0;
+ let failed = 0;
+
+ const readme = fs.readFileSync(README, 'utf8');
+
+ if (test('README marks one default path and warns against stacked installs', () => {
+ assert.ok(
+ readme.includes('### Pick one path only'),
+ 'README should surface a top-level install decision section'
+ );
+ assert.ok(
+ readme.includes('**Recommended default:** install the Claude Code plugin'),
+ 'README should name the recommended default install path'
+ );
+ assert.ok(
+ readme.includes('**Do not stack install methods.**'),
+ 'README should explicitly warn against stacking install methods'
+ );
+ assert.ok(
+ readme.includes('If you choose this path, stop there. Do not also run `/plugin install`.'),
+ 'README should tell manual-install users not to continue layering installs'
+ );
+ })) passed++; else failed++;
+
+ if (test('README documents reset and uninstall flow', () => {
+ assert.ok(
+ readme.includes('### Reset / Uninstall ECC'),
+ 'README should have a visible reset/uninstall section'
+ );
+ assert.ok(
+ readme.includes('node scripts/uninstall.js --dry-run'),
+ 'README should document dry-run uninstall'
+ );
+ assert.ok(
+ readme.includes('node scripts/ecc.js list-installed'),
+ 'README should document install-state inspection before reinstalling'
+ );
+ assert.ok(
+ readme.includes('node scripts/ecc.js doctor'),
+ 'README should document doctor before reinstalling'
+ );
+ assert.ok(
+ readme.includes('ECC only removes files recorded in its install-state.'),
+ 'README should explain uninstall safety boundaries'
+ );
+ })) passed++; else failed++;
+
+ if (test('README explains plugin-path cleanup and rules scoping', () => {
+ assert.ok(
+ readme.includes('remove the plugin from Claude Code'),
+ 'README should tell plugin users how to start cleanup'
+ );
+ assert.ok(
+ readme.includes('Start with `rules/common` plus one language or framework pack you actually use.'),
+ 'README should steer users away from copying every rules directory'
+ );
+ })) passed++; else failed++;
+
+ console.log(`\nResults: Passed: ${passed}, Failed: ${failed}`);
+ process.exit(failed > 0 ? 1 : 0);
+}
+
+runTests();