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: gate guided setup until 2.2 release (#2767)

haelyra9599b90f6b68
diff --git a/README.md b/README.md
index e16f44fc6..7f2678676 100644
--- a/README.md
+++ b/README.md
@@ -50,6 +50,20 @@
> [!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.
+## Install with Claude Code
+
+Run these commands inside Claude Code:
+
+```text
+/plugin marketplace add https://github.com/affaan-m/ECC
+/plugin install ecc@ecc
+```
+
+That installs ECC's skills, agents, commands, and plugin-managed hooks. If you choose this path, stop there. Do not also run a full manual install into Claude Code.
+
+> Guided package setup is coming in `ecc-universal` 2.2.0. Use the native
+> Claude plugin commands above while npm remains on 2.1.0.
+
<div align="center">
<table aria-label="ECC primary links">
@@ -129,17 +143,17 @@ Access to 68 agents, 286 skills, and 94 legacy command shims, plus hooks, rules,
## Install ECC
-> [!NOTE]
-> The guided commands below require `ecc-universal` 2.2.0 or newer. If npm
-> still resolves 2.1.0, use the provider-native instructions below until the
-> 2.2.0 package is published.
+> [!IMPORTANT]
+> Guided package setup is coming in `ecc-universal` 2.2.0. The current npm
+> release, 2.1.0, does not include the guided setup commands. Use the native
+> Claude plugin commands at the top of this README until 2.2.0 is published.
### Pick one path only (per harness)
You can use ECC with Claude Code, Codex, and other harnesses at the same time. Choose one install method for each harness:
-- **Recommended default:** run the guided Claude plugin setup with `npx ecc-universal setup`
-- **Recommended for multiple harnesses:** run `npx ecc-universal install --guided`
+- **Recommended today for Claude Code:** use the [native plugin commands above](#install-with-claude-code)
+- **Coming in release 2.2:** guided package setup for Claude Code, Codex, and Kimi Code; see the preview at the bottom of this install area
- **Works:** Claude Code plugin + Codex native plugin
- **Works:** Claude Code plugin + the legacy Codex sync flow
- **Avoid:** Claude Code plugin + full Claude manual install
@@ -151,69 +165,9 @@ If you already layered multiple installs and things look duplicated, skip straig
**Install trouble?** Open the short [install or runtime problem form](https://github.com/affaan-m/ECC/issues/new?template=install-problem.yml), or run `ecc feedback`. ECC never uploads diagnostics automatically.
-### Guided setup (recommended)
-
-For Claude Code plugin setup, updates, scope changes, and hook-profile changes:
-
-```bash
-npx ecc-universal setup
-```
-
-The same published package works with modern package runners:
-
-| Package runner | Guided setup command |
-|---|---|
-| npm / npx | `npx ecc-universal setup` |
-| pnpm | `pnpm dlx ecc-universal setup` |
-| Yarn 2+ | `yarn dlx ecc-universal setup` |
-| Bun | `bunx ecc-universal setup` |
-
-Yarn Classic 1 does not provide `yarn dlx`; use `npx`, install the package globally, or upgrade Yarn for a temporary one-shot run.
-
-The wizard inventories the official marketplace and every native Claude install scope before making changes, then installs, updates, or safely moves `ecc@ecc` to the scope you choose. Rerun the same command whenever you want to update ECC, change scope, or change its hook profile. This setup wizard currently configures the Claude Code plugin; use the multi-harness wizard below for Codex or Kimi Code.
-
-To configure more than one coding agent in one reviewed flow, use the multi-harness wizard:
-
-```bash
-npx ecc-universal install --guided
-```
-
-It lets you select any combination of Claude Code, Codex, and Kimi Code, shows each install channel and destination, preflights every selection before the first write, and asks for one final confirmation.
-
-| Harness | Guided install behavior |
-|---|---|
-| Claude Code | Native `ecc@ecc` plugin with one `user`, `project`, or `local` scope and an ECC hook profile |
-| Codex | Native Codex marketplace/plugin lifecycle; hook review and trust remain Codex-owned |
-| Kimi Code | Managed project files under `./.kimi-code`; ECC hooks, model/provider settings, and authentication are not configured |
-
-For automation, make every provider-specific choice explicit:
-
-```bash
-npx ecc-universal install --guided \
- --harness claude --harness codex --harness kimi \
- --claude-scope local --claude-hooks standard \
- --profile core --yes
-```
-
-Verify the native guided Codex path and managed Kimi path without writing first:
-
-```bash
-npx ecc-universal install --guided --harness codex --dry-run
-npx ecc-universal install --profile core --target kimi --dry-run
-```
-
-ECC also ships advanced managed adapters for `cursor`, `antigravity`, `gemini`, `opencode`, `codebuddy`, `joycode`, `qwen`, `zed`, `hermes`, and `openclaw`. Those targets still use their documented `ecc install --target ...` paths until each adapter has passed the guided collision, update, repair, and uninstall lifecycle matrix. Neither wizard silently installs into every detected harness.
-
-### Claude Code
-
-Use Claude Code's built-in marketplace commands only when you specifically want the native path or cannot run the package wizard:
-
-```text
-/plugin marketplace add https://github.com/affaan-m/ECC
-/plugin install ecc@ecc
-```
+### Claude Code details
-That installs ECC's skills, agents, commands, and plugin-managed hooks. Claude Code owns these built-in commands, including their errors when a marketplace, plugin, or conflicting scope already exists. ECC cannot intercept that parser. If either command reports an existing install or scope conflict, run `npx ecc-universal setup`; the ECC-owned flow inspects the current state and chooses install, update, or verified scope migration instead of blindly adding a duplicate.
+Claude Code owns these built-in commands, including their errors when a marketplace, plugin, or conflicting scope already exists. ECC cannot intercept that parser. If either native command reports an existing install or scope conflict, wait for the 2.2.0 guided setup or resolve the conflicting Claude plugin scope before retrying; do not layer a manual install on top.
After ECC is installed, `/ecc:configure-ecc` is the namespaced in-Claude reconfiguration skill. It delegates to the same safe setup flow, but it is available only after the plugin is installed and cannot replace Claude Code's built-in `/plugin` command during a first install.
@@ -343,8 +297,6 @@ Use this when you want ECC's rules, agents, commands, platform config, and core
```bash
./install.sh --profile minimal --target claude
-# or, without cloning first
-npx ecc-install --profile minimal --target claude
```
Windows:
@@ -378,7 +330,7 @@ Add the hook runtime later only if you want it:
Ask the packaged advisor which components match your work:
```bash
-npx ecc-universal consult "security reviews" --target claude
+node scripts/ecc.js consult "security reviews" --target claude
```
It returns matching components, related profiles, and preview/install commands. Use the preview command before installing if you want to inspect the exact file plan.
@@ -387,7 +339,7 @@ You can also install explicit skills or capabilities:
```bash
./install.sh --target claude --skills tdd-workflow,security-review
-npx ecc-universal install --profile minimal --target claude --with capability:machine-learning
+node scripts/ecc.js install --profile minimal --target claude --with capability:machine-learning
```
Manual component-by-component copying also works. Each component is fully independent:
@@ -556,7 +508,7 @@ Configure the endpoint with Kimi Code's <a href="https://moonshotai.github.io/ki
```bash
bash ./install.sh --target kimi --profile minimal
-npx ecc-universal doctor --target kimi
+node scripts/ecc.js doctor --target kimi
kimi
```
@@ -604,6 +556,75 @@ If you stacked methods, clean up in this order:
4. Reinstall once, using a single path.
</details>
+## Coming soon: guided setup in release 2.2
+
+> [!WARNING]
+> These ECC package-runner commands are not available in the current npm
+> release, 2.1.0. Do not run them until `ecc-universal` 2.2.0 is published.
+
+The earlier README description—**Recommended default:** run the guided Claude plugin setup—was published too soon. That recommendation is withdrawn until release 2.2.
+
+For Claude Code plugin setup, updates, scope changes, and hook-profile changes:
+
+```bash
+npx ecc-universal setup
+```
+
+Release 2.2 will support the same guided setup through modern package runners:
+
+| Package runner | Guided setup command |
+|---|---|
+| npm / npx | `npx ecc-universal setup` |
+| pnpm | `pnpm dlx ecc-universal setup` |
+| Yarn 2+ | `yarn dlx ecc-universal setup` |
+| Bun | `bunx ecc-universal setup` |
+
+Yarn Classic 1 does not provide `yarn dlx`; use `npx`, install the package globally, or upgrade Yarn for a temporary one-shot run after 2.2 is published.
+
+The wizard inventories the official marketplace and every native Claude install scope before making changes, then installs, updates, or safely moves `ecc@ecc` to the scope you choose. Rerun the same command whenever you want to update ECC, change scope, or change its hook profile. This setup wizard currently configures the Claude Code plugin; use the multi-harness wizard below for Codex or Kimi Code.
+
+To configure more than one coding agent in one reviewed flow, use the multi-harness wizard:
+
+```bash
+npx ecc-universal install --guided
+```
+
+It lets you select any combination of Claude Code, Codex, and Kimi Code, shows each install channel and destination, preflights every selection before the first write, and asks for one final confirmation.
+
+| Harness | Guided install behavior |
+|---|---|
+| Claude Code | Native `ecc@ecc` plugin with one `user`, `project`, or `local` scope and an ECC hook profile |
+| Codex | Native Codex marketplace/plugin lifecycle; hook review and trust remain Codex-owned |
+| Kimi Code | Managed project files under `./.kimi-code`; ECC hooks, model/provider settings, and authentication are not configured |
+
+For automation, make every provider-specific choice explicit:
+
+```bash
+npx ecc-universal install --guided \
+ --harness claude --harness codex --harness kimi \
+ --claude-scope local --claude-hooks standard \
+ --profile core --yes
+```
+
+Verify the native guided Codex path and managed Kimi path without writing first:
+
+```bash
+npx ecc-universal install --guided --harness codex --dry-run
+npx ecc-universal install --profile core --target kimi --dry-run
+```
+
+Additional package-name commands will also become available through the 2.2 alias:
+
+```bash
+npx ecc-universal consult "security reviews" --target claude
+npx ecc-universal install --profile minimal --target claude --with capability:machine-learning
+npx ecc-universal doctor --target kimi
+```
+
+Do not use `npx ecc-install --profile minimal --target claude`: `ecc-install` is a binary name inside `ecc-universal`, not a separately published npm package.
+
+ECC also ships advanced managed adapters for `cursor`, `antigravity`, `gemini`, `opencode`, `codebuddy`, `joycode`, `qwen`, `zed`, `hermes`, and `openclaw`. Those targets still use their documented `ecc install --target ...` paths until each adapter has passed the guided collision, update, repair, and uninstall lifecycle matrix. Neither wizard silently installs into every detected harness.
+
## Start Using ECC
Start with the workflow you need, not the full catalog.
@@ -1929,7 +1950,7 @@ Security references:
<details>
<summary><strong>ECC appears twice or hooks fire twice</strong></summary>
-The usual cause is installing the Claude plugin and then running `install.sh --profile full` or `npx ecc-install --profile full` on top of it.
+The usual cause is installing the Claude plugin and then running `./install.sh --profile full` on top of it.
1. Remove the Claude Code plugin install.
2. Run `node scripts/ecc.js uninstall --dry-run` from the ECC checkout.