How ECC Works

System Architecture

ECC is a configuration distribution system for AI agent harnesses. It is not a runtime library - it ships markdown files, JSON configs, and Node.js scripts that integrate into your existing Claude Code (or Cursor/Codex) setup.

Component Lifecycle

Install (npx ecc typescript)
  -> Manifest resolution (manifests/*.json)
  -> File copy (agents/, skills/, rules/, commands/, hooks/)
  -> SQLite state tracking (what was installed, when)

Selective Install Pipeline

The install system uses a manifest-driven approach:

1. Profile selection - User picks a language (e.g., typescript)
2. Manifest resolution - install-plan.js reads manifests/ to determine which artifacts to install
3. Dependency resolution - Common rules are always included; language-specific rules are added based on profile
4. File placement - install-apply.js copies files to ~/.claude/ directories
5. State tracking - SQLite database records what was installed for update/uninstall support

Cross-Harness Compatibility

ECC ships configs for multiple AI agent harnesses from the same repo:

Claude Code

Primary target. Full support for agents, skills, commands, hooks, rules, MCP.

Cursor

.cursor/skills/ and .cursor/rules/ subsets in Cursor-native format.

Codex

.agents/skills/ and .codex/ configs for OpenAI Codex harness.

OpenCode

.opencode/ plugin with commands, tools, and instructions.

Command-Agent Mapping

Commands are the user-facing layer; agents are the execution layer. Key mappings:

Command	Agent	Model
/code-review	code-reviewer	Opus
/tdd	tdd-guide	Sonnet
/plan	planner	Opus
/build-fix	build-error-resolver	Sonnet
/e2e	e2e-runner	Sonnet
/docs	docs-lookup	Haiku

Hook Architecture

Hooks are configured in ~/.claude/hooks.json and execute via Node.js scripts in scripts/hooks/.

Profiles control which hooks are active:

• minimal - Essential hooks only
• standard - Default set (recommended)
• strict - All hooks including extra validations

Environment variables ECC_HOOK_PROFILE and ECC_DISABLED_HOOKS provide fine-grained control.

Skill Evolution

ECC includes a foundation for self-improving skills:

1. Session recording - Session adapters capture structured data about skill usage
2. Pattern extraction - /learn command extracts reusable patterns
3. Skill updates - Extracted patterns feed back into skill definitions
4. Evaluation - /learn-eval validates that skill changes improve outcomes