ECC Guide: A Reusable Agent Workflow System

Learn what ECC is, how to install it without duplication, how to copy rules safely, and how to combine its workflow ideas with Claude Code and Codex.

What ECC is

ECC targets Claude Code, Codex, Cursor, OpenCode, Gemini, Zed, and GitHub Copilot workflows. Its purpose is not to add more prompt text, but to standardise planning, memory, learning, safety, validation, and parallel execution around an agent harness.

When to use it

You regularly use Claude Code, Codex, Cursor, or OpenCode for complex development tasks.
You want agents to plan, verify, review, and retain useful project knowledge.
You need shared rules, skills, hooks, MCP settings, and slash commands.
You have seen context pollution, duplicate prompts, interrupted tasks, or unclear safety boundaries.

Choose an install path

decisiontext

Choose one installation path:
1. Claude Code users: /plugin marketplace add + /plugin install
2. Low-context rules only: minimal manual installation
3. Fine-grained modules, hooks, rules, and MCP: ECC CLI or manual install
4. Already installed: do not stack a full installer
5. Duplicate install: reset or uninstall first, then choose one path

The most common failure is installing the Claude plugin and then running a full installer over the same files. Select one path and inspect the plan before applying it.

Install the Claude plugin

claude-plugintext

# Run inside Claude Code, not in your shell
/plugin marketplace add https://github.com/affaan-m/ECC
/plugin install ecc@ecc
/plugin list ecc@ecc

Copy rules selectively

The plugin does not automatically distribute every rule. Copy the shared rules and the language rules that match the current project. Do not copy every rule just because it exists; rules consume context and change agent behaviour.

copy-rulesbash

git clone https://github.com/affaan-m/ECC.git
cd ECC
npm install

mkdir -p ~/.claude/rules/ecc
cp -R rules/common ~/.claude/rules/ecc/
cp -R rules/typescript ~/.claude/rules/ecc/

# For a Python project, add:
# cp -R rules/python ~/.claude/rules/ecc/

Manual installation

Use a manual install when the marketplace is unavailable or when you need tighter control. Start with minimal or core-without-hooks instead of the full profile.

installbash

# macOS / Linux
git clone https://github.com/affaan-m/ECC.git
cd ECC
npm install

# Low-context path without hooks
./install.sh --profile minimal --target claude

# Core profile without the hooks runtime
./install.sh --profile core --without baseline:hooks --target claude

Use the ideas with Codex

ECC is cross-harness in concept, but configuration directories and plugin mechanisms differ. Borrow the workflow patterns; do not copy Claude Code plugin files into Codex directories.

codex-usagetext

1. Use a GPT88 API-key profile for model calls, code generation, and refactoring
2. Use a ChatGPT OAuth profile for Codex plugins and official account capabilities
3. Install ECC in Claude Code as an agent-workflow reference layer
4. Borrow ECC rules, skills, and verification loops for Codex projects
5. Do not copy Claude Code plugin files into Codex configuration directories

For profile separation and plugin access, see the Codex OAuth guide.

Daily workflow

The most useful ECC idea is the plan - execute - verify - learn loop. Treat commands as part of an observable engineering process, not as a collection of shortcuts.

daily-workflowtext

1. Plan the task first
2. Execute through a verification loop
3. Preserve diff, tests, logs, screenshots, or benchmarks
4. Use security review flows for sensitive work
5. Use worktrees and parallelisation while controlling context pollution
6. Turn valuable lessons into rules, skills, or project documentation

Troubleshooting and uninstall

Duplicate plugin, full-installer, and manual-rule installs can create repeated commands, hooks, and conflicting behaviour. Stop reinstalling and preview cleanup first.

duplicate-fixbash

Stop reinstalling.
Remove the Claude Code plugin and unnecessary ~/.claude/rules/ecc/ directories.
Preview the cleanup:
node scripts/uninstall.js --dry-run

Then inspect the installation state:
node scripts/ecc.js list-installed
node scripts/ecc.js doctor
node scripts/ecc.js repair

Refer to the ECC repository for the current installer and reset details.