docs: clarify install and uninstall paths#1555
Conversation
|
No actionable comments were generated in the recent review. 🎉 ℹ️ Recent review info⚙️ Run configurationConfiguration used: defaults Review profile: CHILL Plan: Pro Run ID: 📒 Files selected for processing (1)
✅ Files skipped from review due to trivial changes (1)
📝 WalkthroughWalkthroughREADME Quick Start is restructured to require a single installation choice, tighten rule-copy guidance to Changes
Estimated code review effort🎯 3 (Moderate) | ⏱️ ~22 minutes Possibly related PRs
Poem
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
Greptile SummaryThis PR clarifies the ECC installation documentation by surfacing a clear "Pick one path only" decision section, making the Claude Code plugin the recommended default, and adding a comprehensive "Reset / Uninstall ECC" section with repo-local Confidence Score: 5/5Safe to merge — documentation-only changes with no logic, no data path, and all referenced scripts verified present. All three files are documentation or test-only changes. Referenced scripts (scripts/ecc.js, scripts/uninstall.js) exist and support the documented flags. No prior P0/P1 findings remain open. The two concerns raised in earlier review threads (messaging contradiction and brittle test assertions) are P2 style issues that don't block merge. No files require special attention. Important Files Changed
Flowchart%%{init: {'theme': 'neutral'}}%%
flowchart TD
A[New ECC User] --> B{Pick one path only}
B -->|Recommended default| C[Plugin Install\n/plugin install]
B -->|Manual / fallback| D[./install.sh --profile full\nor npx ecc-install --profile full]
C --> E[Copy only needed rule folders\ne.g. rules/common + one lang pack]
D --> F[Stop — do NOT also run /plugin install]
E --> G[Using ECC]
F --> G
G --> H{Something broken?}
H -->|Plugin path| I[Remove plugin\n+ delete copied rule folders]
H -->|Manual path| J[node scripts/uninstall.js --dry-run\nthen node scripts/uninstall.js]
H -->|Stacked installs| K[1. Remove plugin\n2. Run uninstall from repo root\n3. Delete extra rule folders\n4. Reinstall once via single path]
J --> L[Or use lifecycle wrapper:\nnode scripts/ecc.js doctor\nnode scripts/ecc.js repair]
Reviews (2): Last reviewed commit: "docs: remove unicode safety violations f..." | Re-trigger Greptile |
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
| ### Step 1: Install the Plugin | ||
| ### Pick one path only | ||
|
|
||
| Most Claude Code users should use exactly one install path: |
There was a problem hiding this comment.
The new "Pick one path only" section calls the plugin the "Recommended default," but the NOTE immediately under ### Step 1 says the OSS installer is "still the most reliable path." A new user reading both paragraphs back-to-back gets conflicting guidance. Consider either removing "most reliable" from the NOTE or softening it to match the new framing (e.g., "the OSS installer is a reliable fallback if…").
| 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); |
There was a problem hiding this comment.
Every readme.includes(...) check pins a verbatim excerpt from the README. Any future copy-edit — even changing a single backtick or punctuation mark — will silently fail CI rather than signal an intentional documentation change. Since the guards are meant to prevent accidental removal of content rather than enforce exact phrasing, consider checking for a stable heading or a shorter canonical phrase (e.g. 'Reset / Uninstall ECC') and letting the prose around it evolve freely. The section-heading assertions already do this well; the multi-sentence prose assertions are the fragile ones.
Note: If this suggestion doesn't match your team's coding style, reply to this and let me know. I'll remember it for next time!
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 3
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@README.md`:
- Line 208: Update the manual-install rule-copy block and the later Installation
examples so they follow the guidance to copy only rules/common plus a single
language/framework pack instead of multiple language directories; locate the
paragraph that currently shows commands copying multiple rules/ directories and
replace those copy commands with a concise example that copies rules/common and
one pack (referencing rules/common and a single rules/<language> or
rules/<framework> directory), and apply the same change to the installation
example group mentioned (the Installation examples section that currently lists
multiple rules/ copies).
- Around line 262-288: Add an explicit “hook-only cleanup” branch to the Reset /
Uninstall ECC section: describe how to remove or disable installs performed with
the CLI flag --modules hooks-runtime (or the hooks-runtime module), including
using scripts/uninstall.js with a dry-run and actual run if applicable, and
document any extra manual steps (e.g., removing installed hook files or undoing
modifications) and the corresponding lifecycle wrapper commands (scripts/ecc.js
uninstall/doctor/repair) to verify state; reference the hooks-runtime module
name and the existing uninstall scripts so readers can follow the same dry-run
-> remove pattern as the full install instructions.
- Around line 170-182: The README currently contradicts itself by calling the
plugin the "Recommended default" (under "Pick one path only") while the "Step 1:
Install the Plugin (Recommended)" note then states the OSS installer is "still
the most reliable path"; update the text so the recommendation is consistent:
either change the "Step 1" note to state the plugin is the recommended
convenient option and remove or reword "most reliable path" to something like
"alternative" or "fallback" for the OSS installer, or else change the earlier
"Recommended default" to "Convenient default" so both the "Pick one path only"
section and the "Step 1: Install the Plugin (Recommended)" note consistently
refer to the plugin as the recommended/convenient path and the OSS installer as
an alternative/fallback; adjust the phrases around the headings "Pick one path
only" and "Step 1: Install the Plugin (Recommended)" accordingly.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: 68131e05-1065-485e-bcee-61bfe3829bb6
📒 Files selected for processing (2)
README.mdtests/scripts/install-readme-clarity.test.js
| ### 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. |
There was a problem hiding this comment.
Remove the “most reliable path” contradiction.
Line 174 names the plugin as the recommended default, but Line 182 says the OSS installer is “still the most reliable path.” That undercuts the new single-path decision guidance.
📝 Proposed wording
### 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.
+> NOTE: If your Claude Code build has trouble resolving self-hosted marketplace entries, use the [fully manual install](`#fully-manual-install-fallback`) instead of the plugin path. Do not use both.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@README.md` around lines 170 - 182, The README currently contradicts itself by
calling the plugin the "Recommended default" (under "Pick one path only") while
the "Step 1: Install the Plugin (Recommended)" note then states the OSS
installer is "still the most reliable path"; update the text so the
recommendation is consistent: either change the "Step 1" note to state the
plugin is the recommended convenient option and remove or reword "most reliable
path" to something like "alternative" or "fallback" for the OSS installer, or
else change the earlier "Recommended default" to "Convenient default" so both
the "Pick one path only" section and the "Step 1: Install the Plugin
(Recommended)" note consistently refer to the plugin as the
recommended/convenient path and the OSS installer as an alternative/fallback;
adjust the phrases around the headings "Pick one path only" and "Step 1: Install
the Plugin (Recommended)" accordingly.
| > 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. |
There was a problem hiding this comment.
Mirror the “don’t copy every rules directory” guidance in the later examples.
Line 208 tells users to start with rules/common plus one relevant pack, but the later Installation examples still show copying several language directories. Users landing there can still follow the older broad-copy pattern.
📝 Proposed direction
> cp -r everything-claude-code/rules/common ~/.claude/rules/
-> cp -r everything-claude-code/rules/typescript ~/.claude/rules/ # pick your stack
-> cp -r everything-claude-code/rules/python ~/.claude/rules/
-> cp -r everything-claude-code/rules/golang ~/.claude/rules/
-> cp -r everything-claude-code/rules/php ~/.claude/rules/
+> cp -r everything-claude-code/rules/typescript ~/.claude/rules/ # replace with the one pack you actually useApply the same pattern to the manual-install rule-copy block.
Also applies to: 745-784
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@README.md` at line 208, Update the manual-install rule-copy block and the
later Installation examples so they follow the guidance to copy only
rules/common plus a single language/framework pack instead of multiple language
directories; locate the paragraph that currently shows commands copying multiple
rules/ directories and replace those copy commands with a concise example that
copies rules/common and one pack (referencing rules/common and a single
rules/<language> or rules/<framework> directory), and apply the same change to
the installation example group mentioned (the Installation examples section that
currently lists multiple rules/ copies).
| ### 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. |
There was a problem hiding this comment.
Add a hook-only cleanup branch.
The reset section covers plugin and full manual installs, but users who installed only --modules hooks-runtime still need an explicit “remove/disable hook-only install” path.
📝 Proposed addition
- **Plugin path:** remove the plugin from Claude Code, then delete the specific rule folders you manually copied under `~/.claude/rules/`.
+- **Hook-only installs:** if you installed only `--modules hooks-runtime`, use the dry-run first; uninstall will be scoped to ECC-managed hook files recorded in install-state. To disable temporarily instead of removing, use `ECC_DISABLED_HOOKS` or `ECC_HOOK_PROFILE`.
- **Manual installer / CLI path:** from the repo root, preview removal first:🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@README.md` around lines 262 - 288, Add an explicit “hook-only cleanup” branch
to the Reset / Uninstall ECC section: describe how to remove or disable installs
performed with the CLI flag --modules hooks-runtime (or the hooks-runtime
module), including using scripts/uninstall.js with a dry-run and actual run if
applicable, and document any extra manual steps (e.g., removing installed hook
files or undoing modifications) and the corresponding lifecycle wrapper commands
(scripts/ecc.js uninstall/doctor/repair) to verify state; reference the
hooks-runtime module name and the existing uninstall scripts so readers can
follow the same dry-run -> remove pattern as the full install instructions.
|
ECC bundle files are already tracked in this repository. Skipping generation of another bundle PR. |
1 similar comment
|
ECC bundle files are already tracked in this repository. Skipping generation of another bundle PR. |
![cubic-dev-ai[bot]](https://avatars.githubusercontent.com/in/1082092?s=60&v=4){kind=small}
There was a problem hiding this comment.
1 issue found across 2 files
Prompt for AI agents (unresolved issues)
Check if these issues are valid — if so, understand the root cause of each and fix them. If appropriate, use sub-agents to investigate and fix each issue separately.
<file name="README.md">
<violation number="1" location="README.md:174">
P2: The new "Pick one path only" section names the plugin as the **Recommended default**, but the NOTE directly under `### Step 1` still says the OSS installer is "still the most reliable path." A first-time reader hitting both paragraphs back-to-back gets contradictory guidance. Either soften the NOTE to match the new framing (e.g., "the manual installer is a reliable fallback if…") or remove the "most reliable" claim.</violation>
</file>
Reply with feedback, questions, or to request a fix. Tag @cubic-dev-ai to re-run a review.
|
|
||
| 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. |
There was a problem hiding this comment.
P2: The new "Pick one path only" section names the plugin as the Recommended default, but the NOTE directly under ### Step 1 still says the OSS installer is "still the most reliable path." A first-time reader hitting both paragraphs back-to-back gets contradictory guidance. Either soften the NOTE to match the new framing (e.g., "the manual installer is a reliable fallback if…") or remove the "most reliable" claim.
Prompt for AI agents
Check if this issue is valid — if so, understand the root cause and fix it. At README.md, line 174:
<comment>The new "Pick one path only" section names the plugin as the **Recommended default**, but the NOTE directly under `### Step 1` still says the OSS installer is "still the most reliable path." A first-time reader hitting both paragraphs back-to-back gets contradictory guidance. Either soften the NOTE to match the new framing (e.g., "the manual installer is a reliable fallback if…") or remove the "most reliable" claim.</comment>
<file context>
@@ -167,7 +167,17 @@ See the full changelog in [Releases](https://github.com/affaan-m/everything-clau
+
+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.
</file context>
1 participant
Summary
Testing
Closes #1554
Refs #1487
Refs discussion #856
Summary by CodeRabbit
Documentation
Tests
Summary by cubic
Clarifies install paths in the README by making the Claude Code plugin the default, adding a manual fallback, and warning against stacked installs. Adds a clear Reset/Uninstall section with
node scripts/ecc.jscommands, tightens guidance to copy only neededrules/*, adds a regression test, and removes Unicode symbols from the hook addendum for safety.Written for commit 530088c. Summary will update on new commits.