alexei.dolgolyov
1f8195b420
Rewrite ecc-setup-guide.md for ECC v2.0.0: the new `ecc` selective-install CLI (profiles, auto-update, doctor/repair/plan/catalog/consult), the skills/ecc + rules/ecc namespaced layout, updated install/model-tier and Continuous-Learning-v2 sections, and the `--dry-run auto-update` footgun (it performs a real install). Note 2 of 3 Windows CL-v2 bugs are now fixed upstream. Index the guide in README.md and bump the Last updated date.
297 lines
13 KiB
Markdown
297 lines
13 KiB
Markdown
# Everything Claude Code (ECC) — Setup Guide
|
||
|
||
Step-by-step instructions for setting up ECC on a new machine. Can be followed manually or by Claude.
|
||
|
||
> **Version note:** Written and verified against **ECC v2.0.0** (2026-06-23). v2.0.0 is a major rewrite: a new `ecc` selective-install CLI, a `skills/ecc/` + `rules/ecc/` namespaced layout, a SQLite/JSON install-state with `doctor`/`repair`/`auto-update`, and ~67 agents / 271 skills in the catalog. The GitHub repo was renamed from `affaan-m/everything-claude-code` to **`affaan-m/ECC`** (homepage <https://ecc.tools>); the old URL still redirects. Re-check the [repository](https://github.com/affaan-m/ECC) before relying on any version-specific detail below.
|
||
|
||
## Prerequisites
|
||
|
||
- **Node.js ≥ 18** + npm (v2.0.0 declares `packageManager: yarn@4`, but `npm install` still works; `install.ps1`/`install.sh` auto-install deps for you)
|
||
- Git
|
||
- Claude Code CLI
|
||
- PowerShell (Windows) or Bash (macOS/Linux)
|
||
|
||
## Step 1 — Clone and install dependencies
|
||
|
||
**Windows (PowerShell):**
|
||
|
||
```powershell
|
||
git clone https://github.com/affaan-m/ECC.git C:\Users\<USERNAME>\everything-claude-code
|
||
cd C:\Users\<USERNAME>\everything-claude-code
|
||
npm install
|
||
```
|
||
|
||
**macOS/Linux (Bash):**
|
||
|
||
```bash
|
||
git clone https://github.com/affaan-m/ECC.git ~/everything-claude-code
|
||
cd ~/everything-claude-code
|
||
npm install
|
||
```
|
||
|
||
> The clone directory name is your choice (`everything-claude-code` keeps older paths/scripts working). Runtime deps are small (`sql.js`, `ajv`, `@iarna/toml`). If you prefer the declared toolchain, `corepack enable && corepack yarn install` also works. You can skip `npm install` entirely if you use `install.ps1`/`install.sh` in Step 2 — they install deps automatically when `node_modules` is missing.
|
||
|
||
## Step 2 — Run the installer
|
||
|
||
Run **from inside the cloned repo**. v2.0.0 ships a real CLI (`scripts/ecc.js`, also exposed as the `ecc` bin). Two equivalent ways to invoke it:
|
||
|
||
- `node scripts/ecc.js <command>` — most reliable, no PATH/npx ambiguity
|
||
- `npx ecc <command>` — works from inside the repo (the postinstall banner suggests this form)
|
||
|
||
### Option A — Legacy language mode (simplest; matches older setups)
|
||
|
||
```powershell
|
||
node scripts/ecc.js python typescript # bare languages route to "install"
|
||
```
|
||
|
||
Equivalent compat scripts (auto-install deps, then delegate to the installer):
|
||
|
||
```powershell
|
||
.\install.ps1 python typescript # Windows
|
||
```
|
||
|
||
```bash
|
||
./install.sh python typescript # macOS/Linux
|
||
```
|
||
|
||
Available languages: `python`, `typescript`, `golang`, `swift`, `php`, `rust`, `cpp`, `csharp`, `java`, `kotlin`, `perl`
|
||
|
||
### Option B — Profile mode (v2.0.0, recommended for new installs)
|
||
|
||
```powershell
|
||
node scripts/ecc.js install --profile developer --target claude
|
||
```
|
||
|
||
Profiles (`node scripts/ecc.js catalog profiles` for the live list):
|
||
|
||
| Profile | Modules | Use |
|
||
| --------- | --------- | ----- |
|
||
| `minimal` | 5 | Low-context: rules, agents, commands, platform configs, quality — **no hook runtime** |
|
||
| `core` | 6 | Harness baseline with commands, hooks, platform configs, quality |
|
||
| `developer` | 9 | **Default engineering profile** for most users |
|
||
| `security` | 7 | Security-heavy, baseline runtime + security guidance |
|
||
| `research` | 9 | Research/content: investigation, synthesis, publishing |
|
||
| `full` | 23 | Everything currently classified |
|
||
| `opencode` | 3 | OpenCode target (excludes hooks-runtime) |
|
||
|
||
Not sure what you need? `node scripts/ecc.js consult "security reviews and python"` recommends components/profiles from a natural-language query, and `node scripts/ecc.js catalog components --family language` lists installable components.
|
||
|
||
> **Selective install caveat:** Profiles/languages only install the **selected modules'** skills. The full catalog is ~271 skills; a `developer`/language install lands ~70–80 under `~/.claude/skills/ecc/`. Add more later with `--modules <id>` or a broader profile — they are additive.
|
||
|
||
### What gets installed (v2.0.0 layout)
|
||
|
||
All files go to `~/.claude/` (global, applies to all projects). **v2.0.0 namespaces skills and rules under `ecc/`; agents and commands stay flat** (legacy-compat):
|
||
|
||
| Category | Location | Notes |
|
||
| ---------- | ---------- | ------- |
|
||
| Skills | `~/.claude/skills/ecc/<name>/` | **namespaced** under `ecc/` |
|
||
| Rules | `~/.claude/rules/ecc/` | **namespaced** under `ecc/` |
|
||
| Agents | `~/.claude/agents/<name>.md` | flat — **overwrites** existing files of the same name |
|
||
| Commands | `~/.claude/commands/<name>.md` | flat |
|
||
| Hooks | `~/.claude/hooks/` | reusable hook scripts |
|
||
| ECC runtime | `~/.claude/scripts/` | `lib/`, `hooks/` used by the CLI (new in v2.0.0) |
|
||
| Cross-harness | `~/.claude/.agents/` | shared agent/skill surface for Codex/Cursor/etc. (new) |
|
||
|
||
`settings.json` and `.claude.json` are **not** touched by the installer — your hooks config and MCP server registrations are safe.
|
||
|
||
The install records state in `~/.claude/ecc/install-state.json` (queryable with `ecc list-installed`).
|
||
|
||
## Step 3 — Add Bash to read-only agents (still required in v2.0.0)
|
||
|
||
`planner` and `architect` ship with only `Read, Grep, Glob`. To let them use `ast-index`/`vex` and other CLI tools, add `Bash`. Edit the frontmatter `tools:` line in `~/.claude/agents/planner.md` and `~/.claude/agents/architect.md`:
|
||
|
||
```yaml
|
||
# from
|
||
tools: ["Read", "Grep", "Glob"]
|
||
# to
|
||
tools: ["Read", "Grep", "Glob", "Bash"]
|
||
```
|
||
|
||
```bash
|
||
# Bash one-liner:
|
||
for a in planner architect; do
|
||
sed -i 's/^tools: \["Read", "Grep", "Glob"\]$/tools: ["Read", "Grep", "Glob", "Bash"]/' ~/.claude/agents/$a.md
|
||
done
|
||
```
|
||
|
||
All other agents already include `Bash`.
|
||
|
||
## Step 4 — Configure Continuous Learning v2
|
||
|
||
In v2.0.0 CL-v2 lives at **`~/.claude/skills/ecc/continuous-learning-v2/`**.
|
||
|
||
### 4a. Add observation hooks
|
||
|
||
Merge into `~/.claude/settings.json` (combine with any existing `hooks` key):
|
||
|
||
```json
|
||
{
|
||
"hooks": {
|
||
"PreToolUse": [{
|
||
"matcher": "*",
|
||
"hooks": [{
|
||
"type": "command",
|
||
"command": "~/.claude/skills/ecc/continuous-learning-v2/hooks/observe.sh"
|
||
}]
|
||
}],
|
||
"PostToolUse": [{
|
||
"matcher": "*",
|
||
"hooks": [{
|
||
"type": "command",
|
||
"command": "~/.claude/skills/ecc/continuous-learning-v2/hooks/observe.sh"
|
||
}]
|
||
}]
|
||
}
|
||
}
|
||
```
|
||
|
||
### 4b. Enable the observer (still ships disabled)
|
||
|
||
`~/.claude/skills/ecc/continuous-learning-v2/config.json` ships with `"enabled": false`. Set it to `true`:
|
||
|
||
```json
|
||
{ "enabled": true }
|
||
```
|
||
|
||
> **Windows note:** The two historical Windows-only observer bugs are **fixed in v2.0.0** — `observe.sh` now detects the `python3` Microsoft Store stub (`_is_windows_app_installer_stub`) and allows the `claude-vscode`/`claude-desktop` entrypoints. The only manual step left is flipping `enabled` to `true` above. The `~/.claude/homunculus/` instinct store is auto-created/managed by CL-v2 (no manual `mkdir` needed).
|
||
|
||
### 4c. Verify the observe script exists
|
||
|
||
```bash
|
||
ls ~/.claude/skills/ecc/continuous-learning-v2/hooks/observe.sh
|
||
```
|
||
|
||
If missing, re-run the installer (Step 2).
|
||
|
||
## Step 5 — Restart Claude Code
|
||
|
||
Hooks and new/changed agents only take effect after a restart.
|
||
|
||
## Step 6 — Configure agent model tiers
|
||
|
||
ECC agents mostly default to `sonnet` (a few ship `opus` already — e.g. `architect`, `chief-of-staff`, `planner`). Policy: **reviewers and thinking-heavy agents → `opus`; build/error resolvers and mechanical agents → `sonnet`; lightweight doc agents → `haiku`.** This applies to the v2.0.0 reviewer additions too (`csharp-`, `react-`, `vue-`, `fastapi-`, `django-`, `swift-`, `php-`, `fsharp-`, `mle-`, `healthcare-reviewer`, etc.).
|
||
|
||
Bulk-apply with a glob so it covers current and future reviewers:
|
||
|
||
```bash
|
||
cd ~/.claude/agents
|
||
# Every *-reviewer agent -> opus
|
||
for f in *-reviewer.md; do sed -i 's/^model: sonnet$/model: opus/' "$f"; done
|
||
# Thinking-heavy non-reviewer agents -> opus
|
||
for f in planner architect tdd-guide chief-of-staff code-architect performance-optimizer; do
|
||
[ -f "$f.md" ] && sed -i 's/^model: sonnet$/model: opus/' "$f.md"
|
||
done
|
||
```
|
||
|
||
| Tier | Agents (examples) | Rationale |
|
||
| ------- | -------- | ----------- |
|
||
| **opus** | all `*-reviewer`, `tdd-guide`, `planner`, `architect`, `code-architect`, `security-reviewer`, `chief-of-staff`, `performance-optimizer` | Deep reasoning: code quality, security, architecture |
|
||
| **sonnet** | `*-build-resolver`, `e2e-runner`, `refactor-cleaner`, `docs-lookup`, `harness-optimizer` | Mechanical fixes, error resolution |
|
||
| **haiku** | `doc-updater` | Lightweight docs work |
|
||
|
||
> These overrides are intentional drift and will show up in `ecc doctor` as "drifted managed files" — that is expected, not an error.
|
||
|
||
## Post-install verification
|
||
|
||
```bash
|
||
node scripts/ecc.js list-installed # target, modules, source version
|
||
node scripts/ecc.js doctor # health: drift / missing files / version mismatch
|
||
```
|
||
|
||
Inside Claude Code:
|
||
|
||
| Command | Expected result |
|
||
| --------- | ---------------- |
|
||
| `/plan "test"` | Invokes the planner agent |
|
||
| `/code-review` | Invokes the code-reviewer agent |
|
||
| `/instinct-status` | Shows instinct status (empty on first run) |
|
||
|
||
## Useful commands
|
||
|
||
**ECC CLI** (`node scripts/ecc.js <command>`):
|
||
|
||
| Command | Purpose |
|
||
| --------- | --------- |
|
||
| `install` | Install content (`--profile`, `--target`, or bare languages) |
|
||
| `auto-update` | **Pull latest + reinstall** managed targets in one step |
|
||
| `doctor` | Diagnose drift / missing / version mismatch |
|
||
| `repair` | Restore drifted or missing managed files (`--dry-run` to preview) |
|
||
| `plan` | Preview a resolved install plan (safe, read-only) |
|
||
| `catalog` | Discover profiles and components |
|
||
| `consult` | Recommend components/profiles from a NL query |
|
||
| `list-installed` | Inspect install-state |
|
||
| `uninstall` | Remove ECC-managed files (`--dry-run` to preview) |
|
||
| `status` | SQLite state-store summary |
|
||
|
||
**Slash commands** (in Claude Code): `/plan`, `/tdd`, `/code-review`, `/verify`, `/learn`, `/instinct-status`, `/evolve`, `/promote`, `/projects`.
|
||
|
||
## Updating ECC
|
||
|
||
### One-command update (v2.0.0)
|
||
|
||
```bash
|
||
cd ~/everything-claude-code
|
||
node scripts/ecc.js auto-update
|
||
```
|
||
|
||
`auto-update` runs `git fetch --prune` + `git pull --ff-only`, then reinstalls every managed target using its recorded install request.
|
||
|
||
> ⚠️ **Footgun — `--dry-run auto-update` is NOT a dry run.** The global `--dry-run` flag is **not** honored by `auto-update`: it still pulls and performs a **real reinstall** (the flag does not propagate into the child install process). To preview an update safely, use **`node scripts/ecc.js plan`** or **`node scripts/ecc.js install --dry-run --target claude <languages>`** instead — those genuinely make no changes.
|
||
|
||
### Manual update (equivalent)
|
||
|
||
```bash
|
||
cd ~/everything-claude-code
|
||
git pull
|
||
npm install # if deps changed
|
||
node scripts/ecc.js install --target claude python typescript
|
||
```
|
||
|
||
### After any update — re-apply customizations
|
||
|
||
A reinstall **overwrites flat agents**, so these are lost and must be re-applied:
|
||
|
||
1. **Agent model tiers** (Step 6) — reviewers/thinking-heavy back to `opus`.
|
||
2. **`Bash` on `planner` + `architect`** (Step 3).
|
||
3. **`"enabled": true`** in CL-v2 `config.json` (Step 4b) if you use the observer.
|
||
|
||
Skills and rules live under `ecc/` and are replaced in place, so they need no manual fix-up.
|
||
|
||
### Migrating from a pre-2.0 (flat) install
|
||
|
||
Old installs put skills/rules **flat** (`~/.claude/skills/<name>`). v2.0.0 writes them under `~/.claude/skills/ecc/<name>` and **does not delete the old flat copies**, leaving stale duplicates. After updating, remove only the flat skills that now exist under `ecc/` (preserves your own skills and any ECC skill whose module wasn't reinstalled):
|
||
|
||
```bash
|
||
cd ~/.claude/skills
|
||
comm -12 \
|
||
<(ls -d */ | grep -vx 'ecc/' | xargs -n1 basename | sort) \
|
||
<(ls -d ecc/*/ | xargs -n1 basename | sort) \
|
||
| while read s; do rm -rf "./$s"; done
|
||
```
|
||
|
||
Then confirm with `node scripts/ecc.js doctor` (expect `WARNING` only for your intentional model-tier overrides).
|
||
|
||
### Check current version
|
||
|
||
```bash
|
||
node scripts/ecc.js list-installed # "Source version: X" + recorded modules
|
||
node scripts/ecc.js doctor # flags repo-version mismatch
|
||
cat ~/everything-claude-code/VERSION # repo version on disk
|
||
```
|
||
|
||
## Known gotchas
|
||
|
||
1. **`--dry-run auto-update` performs a real install** — see the Updating section. Preview with `ecc plan` / `ecc install --dry-run` instead.
|
||
|
||
2. **v2.0.0 namespaces skills/rules under `ecc/`** but keeps agents/commands flat. Paths in older notes (`~/.claude/skills/<name>`) are now `~/.claude/skills/ecc/<name>`. Updating from a flat install leaves orphan duplicates (see migration cleanup above).
|
||
|
||
3. **Reinstalls overwrite flat agents** — agent model tiers and the `planner`/`architect` Bash addition must be re-applied after every update.
|
||
|
||
4. **`/plugin` install path is unreliable** — although v2.0.0 ships plugin/marketplace metadata, the selective-install CLI (`ecc install` / `install.ps1`) is the dependable full-install method. Don't rely on `/plugin marketplace add` / `/plugin install`.
|
||
|
||
5. **Windows: don't mix WSL and PowerShell** — pick one. PowerShell → Windows paths (`C:\Users\...`); WSL → Linux paths (`~/...`). Mixing breaks path resolution.
|
||
|
||
6. **Windows paths in PowerShell** — use `C:\Users\<USERNAME>\...`, not `/c/Users/...` (that's Git Bash / WSL syntax).
|
||
|
||
7. **`npm install` vs yarn** — v2.0.0 declares `packageManager: yarn@4` and ships `yarn.lock`, but also a `package-lock.json`; `npm install` works. If you want the declared toolchain use `corepack yarn install`. Don't commit lockfile churn back to the clone.
|