From 1f8195b4209d86850887864b5e34f45f240c3133 Mon Sep 17 00:00:00 2001 From: "dolgolyov.alexei" Date: Tue, 23 Jun 2026 11:44:01 +0300 Subject: [PATCH] docs: rewrite ECC setup guide for v2.0.0 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. --- README.md | 6 +- ecc-setup-guide.md | 342 ++++++++++++++++++++++++--------------------- 2 files changed, 189 insertions(+), 159 deletions(-) diff --git a/README.md b/README.md index a38427d..2370752 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # Claude Code Facts -> Last updated: 2026-06-11 +> Last updated: 2026-06-23 A collection of interesting and useful facts, tips, tools, and guides for working with Claude and Claude Code. @@ -10,6 +10,10 @@ A collection of interesting and useful facts, tips, tools, and guides for workin MCP servers, skills, and plugins that extend Claude Code — including Context7 (library docs), AST Index, and vex (hybrid code search; summarized here with a link to its full reference). +### [Everything Claude Code (ECC) — Setup Guide](ecc-setup-guide.md) + +Step-by-step setup and update guide for ECC (Everything Claude Code) v2.0.0 — clone/install, the `ecc` selective-install CLI (profiles, `auto-update`, `doctor`/`repair`), the `skills/ecc/` namespaced layout, agent model tiers, Continuous Learning v2, and Windows gotchas. + ### [Gitea Release Workflow (Minimal)](gitea-release-workflow.md) Minimal Gitea Actions workflow: push a `v*` tag → create a Gitea release with optional `RELEASE_NOTES.md`. No builds, no artifacts — just a release entry. diff --git a/ecc-setup-guide.md b/ecc-setup-guide.md index 4da0b27..399843a 100644 --- a/ecc-setup-guide.md +++ b/ecc-setup-guide.md @@ -2,21 +2,21 @@ Step-by-step instructions for setting up ECC on a new machine. Can be followed manually or by Claude. -> **Staleness warning:** The Windows-specific fixes (gotchas 6–8) were documented against ECC as of early 2026. These bugs may have been fixed upstream — check the [ECC repository](https://github.com/affaan-m/everything-claude-code) for recent changes before applying the workarounds. +> **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 ); 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 + npm installed -- Git installed -- Claude Code CLI installed +- **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 +## Step 1 — Clone and install dependencies **Windows (PowerShell):** ```powershell -git clone https://github.com/affaan-m/everything-claude-code.git C:\Users\\everything-claude-code +git clone https://github.com/affaan-m/ECC.git C:\Users\\everything-claude-code cd C:\Users\\everything-claude-code npm install ``` @@ -24,79 +24,105 @@ npm install **macOS/Linux (Bash):** ```bash -git clone https://github.com/affaan-m/everything-claude-code.git ~/everything-claude-code +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 the installer **from inside the cloned repo**. +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: -**Windows (PowerShell):** +- `node scripts/ecc.js ` — most reliable, no PATH/npx ambiguity +- `npx ecc ` — works from inside the repo (the postinstall banner suggests this form) + +### Option A — Legacy language mode (simplest; matches older setups) ```powershell -.\install.ps1 -# Example: .\install.ps1 python typescript +node scripts/ecc.js python typescript # bare languages route to "install" ``` -**macOS/Linux (Bash):** +Equivalent compat scripts (auto-install deps, then delegate to the installer): -```bash -./install.sh -# Example: ./install.sh python typescript +```powershell +.\install.ps1 python typescript # Windows ``` -**Cross-platform (npm):** - ```bash -npx ecc-install +./install.sh python typescript # macOS/Linux ``` Available languages: `python`, `typescript`, `golang`, `swift`, `php`, `rust`, `cpp`, `csharp`, `java`, `kotlin`, `perl` -> **Note:** In legacy-compat mode the installer copies rules for ALL languages regardless of arguments. The extra rules are harmless — they sit in `~/.claude/rules//` and only load when relevant. +### Option B — Profile mode (v2.0.0, recommended for new installs) -### What gets installed - -All files go to `~/.claude/` (global, applies to all projects): - -| Category | Location | Examples | -| ---------- | ---------- | --------- | -| Rules | `~/.claude/rules/` | coding-style, testing, security (per language) | -| Agents | `~/.claude/agents/` | planner, architect, code-reviewer, tdd-guide, security-reviewer | -| Skills | `~/.claude/skills/` | python-patterns, tdd-workflow, e2e-testing, continuous-learning | -| Commands | `~/.claude/commands/` | `/plan`, `/tdd`, `/code-review`, `/verify`, `/learn` | -| Hooks | `~/.claude/hooks/` | auto-format, console-log check, cost tracker | - -## Step 3 — Add Bash tool to read-only agents - -Some agents (planner, architect) ship with only `Read, Grep, Glob` tools. To enable `ast-index` and other CLI tools, add `Bash` to their tool lists. - -Edit these files in `~/.claude/agents/`: - -- `planner.md` -- `architect.md` - -Change the frontmatter `tools` line from: - -```yaml -tools: ["Read", "Grep", "Glob"] +```powershell +node scripts/ecc.js install --profile developer --target claude ``` -To: +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 ` 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//` | **namespaced** under `ecc/` | +| Rules | `~/.claude/rules/ecc/` | **namespaced** under `ecc/` | +| Agents | `~/.claude/agents/.md` | flat — **overwrites** existing files of the same name | +| Commands | `~/.claude/commands/.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"] ``` -All other agents already have `Bash` in their tools list. +```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 -Add the following to `~/.claude/settings.json` (merge into existing `hooks` key if one exists): +Merge into `~/.claude/settings.json` (combine with any existing `hooks` key): ```json { @@ -105,166 +131,166 @@ Add the following to `~/.claude/settings.json` (merge into existing `hooks` key "matcher": "*", "hooks": [{ "type": "command", - "command": "~/.claude/skills/continuous-learning-v2/hooks/observe.sh" + "command": "~/.claude/skills/ecc/continuous-learning-v2/hooks/observe.sh" }] }], "PostToolUse": [{ "matcher": "*", "hooks": [{ "type": "command", - "command": "~/.claude/skills/continuous-learning-v2/hooks/observe.sh" + "command": "~/.claude/skills/ecc/continuous-learning-v2/hooks/observe.sh" }] }] } } ``` -### 4b. Create the directory structure +### 4b. Enable the observer (still ships disabled) -```bash -mkdir -p ~/.claude/homunculus/{instincts/{personal,inherited},evolved/{agents,skills,commands},projects} +`~/.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/continuous-learning-v2/hooks/observe.sh +ls ~/.claude/skills/ecc/continuous-learning-v2/hooks/observe.sh ``` -If missing, re-run the installer from Step 2. +If missing, re-run the installer (Step 2). ## Step 5 — Restart Claude Code -Hooks and new agents only take effect after restarting Claude Code. - -## Post-install verification - -Run these commands inside Claude Code to verify: - -| Command | Expected result | -| --------- | ---------------- | -| `/plan "test"` | Should invoke the planner agent | -| `/instinct-status` | Should show instinct status (empty on first run) | -| `/code-review` | Should invoke the code-reviewer agent | - -## Useful commands - -| Command | Purpose | -| --------- | --------- | -| `/plan` | Create implementation plan before coding | -| `/tdd` | Test-driven development workflow | -| `/code-review` | Review code for quality issues | -| `/verify` | Run verification loop | -| `/learn` | Manually extract patterns mid-session | -| `/instinct-status` | View learned instincts | -| `/evolve` | Cluster instincts into skills/commands/agents | -| `/promote` | Promote project instincts to global scope | -| `/projects` | List known projects and instinct counts | - -## Known gotchas - -1. **`/plugin` commands don't exist** — The ECC README references `/plugin marketplace add` and `/plugin install` but Claude Code has no such CLI commands. Use the `install.ps1` / `install.sh` script instead. - -2. **The `extraKnownMarketplaces` entry is cosmetic** — Adding ECC to `extraKnownMarketplaces` in `settings.json` does NOT enable it as a plugin and it will NOT appear in the enabled/disabled plugins list. The manual install is the actual installation method. - -3. **Windows: don't mix WSL and PowerShell** — If npm is installed on Windows, run everything in PowerShell with Windows paths (`C:\Users\...`). If using WSL, run everything in WSL with Linux paths (`~/...`). Mixing causes path resolution failures. - -4. **Windows paths in PowerShell** — Use `C:\Users\\...`, NOT `/c/Users/...` (that's Git Bash / WSL syntax). - -5. **Agent model selection** — Each agent `.md` file in `~/.claude/agents/` supports a `model` field in frontmatter. Options: `haiku` (fast/cheap), `sonnet` (balanced), `opus` (deep reasoning). Choose based on agent complexity needs. - -### Continuous Learning v2 — Windows fixes (critical) - -The observe hook ships with three bugs that silently prevent all observations on Windows: - -1. **`python3` is the Windows Store stub** — On Windows, `python3` resolves to the Microsoft Store redirect (`AppData/Local/Microsoft/WindowsApps/python3`) which returns exit code 49 instead of running Python. The hook's `resolve_python_cmd()` uses `command -v` which finds the stub. **Fix:** In both `~/.claude/skills/continuous-learning-v2/hooks/observe.sh` and `~/.claude/skills/continuous-learning-v2/scripts/detect-project.sh`, change `resolve_python_cmd()` to test execution (`"$candidate" -c "1"`) instead of just checking presence (`command -v`). - -2. **`claude-vscode` entrypoint rejected** — The hook's Layer 1 filter only allows `cli` and `sdk-ts` entrypoints. VS Code extension sets `CLAUDE_CODE_ENTRYPOINT=claude-vscode`, so every observation is silently skipped. **Fix:** Add `claude-vscode` to the allowed entrypoints case pattern in `observe.sh`. - -3. **Observer disabled by default** — `~/.claude/skills/continuous-learning-v2/config.json` ships with `"enabled": false`. **Fix:** Set `"enabled": true`. +Hooks and new/changed agents only take effect after a restart. ## Step 6 — Configure agent model tiers -ECC agents ship with `sonnet` as default. For better results, set thinking-heavy agents to `opus` and keep mechanical agents on cheaper models. +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.). -Edit the `model:` line in each agent's frontmatter in `~/.claude/agents/`: - -| Model | Agents | Rationale | -| ------- | -------- | ----------- | -| **opus** | code-reviewer, python-reviewer, typescript-reviewer, rust-reviewer, go-reviewer, java-reviewer, kotlin-reviewer, cpp-reviewer, flutter-reviewer, database-reviewer, security-reviewer, tdd-guide, planner, architect, chief-of-staff | Deep reasoning for code quality, security, architecture | -| **sonnet** | build-error-resolver, cpp-build-resolver, go-build-resolver, java-build-resolver, kotlin-build-resolver, rust-build-resolver, pytorch-build-resolver, e2e-runner, harness-optimizer, loop-operator, docs-lookup, refactor-cleaner | Mechanical tasks, error fixing | -| **haiku** | doc-updater | Lightweight docs work | - -To bulk-update reviewers and thinking-heavy agents to opus: +Bulk-apply with a glob so it covers current and future reviewers: ```bash -# From bash/git bash: -for f in ~/.claude/agents/{code,python,typescript,rust,go,java,kotlin,cpp,flutter,database,security}-reviewer.md ~/.claude/agents/tdd-guide.md; do - sed -i 's/^model: sonnet/model: opus/' "$f" +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 ``` -## Updating ECC +| 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 | -The installer overwrites all files in `~/.claude/`, so updating is straightforward — but custom changes (model tiers, hook fixes) will be lost. Back them up first. +> These overrides are intentional drift and will show up in `ecc doctor` as "drifted managed files" — that is expected, not an error. -### Update steps +## Post-install verification -**1. Pull the latest version:** - -**Windows (PowerShell):** - -```powershell -cd C:\Users\\everything-claude-code -git pull -npm install +```bash +node scripts/ecc.js list-installed # target, modules, source version +node scripts/ecc.js doctor # health: drift / missing files / version mismatch ``` -**macOS/Linux (Bash):** +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 | 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 `** instead — those genuinely make no changes. + +### Manual update (equivalent) ```bash cd ~/everything-claude-code git pull -npm install +npm install # if deps changed +node scripts/ecc.js install --target claude python typescript ``` -**2. Back up your customizations:** +### 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/`). v2.0.0 writes them under `~/.claude/skills/ecc/` 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 -# Save agent model overrides -grep -l 'model: opus' ~/.claude/agents/*.md > /tmp/ecc-opus-agents.txt - -# Save patched hook files -cp ~/.claude/skills/continuous-learning-v2/hooks/observe.sh /tmp/observe.sh.bak -cp ~/.claude/skills/continuous-learning-v2/scripts/detect-project.sh /tmp/detect-project.sh.bak -cp ~/.claude/skills/continuous-learning-v2/config.json /tmp/cl-config.json.bak +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 ``` -**3. Re-run the installer:** - -**Windows (PowerShell):** - -```powershell -.\install.ps1 python typescript -``` - -**macOS/Linux (Bash):** - -```bash -./install.sh python typescript -``` - -**4. Re-apply customizations:** - -- Re-apply agent model tiers (Step 6 above) -- Re-apply the three Windows hook fixes (gotchas 6–8 above) -- Re-enable observer in `config.json` (`"enabled": true`) -- Re-add `Bash` to planner and architect tools (Step 3 above) +Then confirm with `node scripts/ecc.js doctor` (expect `WARNING` only for your intentional model-tier overrides). ### Check current version ```bash -cat ~/.claude/plugin.json | grep version -# or from the repo: -cat ~/everything-claude-code/VERSION +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/`) are now `~/.claude/skills/ecc/`. 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\\...`, 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.