# affaan-m/everything-claude-code architecture

> Architecture diagram of the GitHub repository affaan-m/everything-claude-code, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-05-10). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/affaan-m/everything-claude-code
- Repository: https://github.com/affaan-m/everything-claude-code

## Overview

1. **What this repo is**
   - This is a cross-harness configuration and automation platform for AI coding tools, not a product app. Its core job is to package and deploy “agent harness” behavior: agents, skills, commands, hooks, rules, MCP configs, and install scripts for Claude Code, Cursor, Codex, OpenCode, Gemini, and related environments.

2. **Primary surface layers**
   - The repo is organized around four user-facing surfaces:
     - `agents/` for specialized subagents
     - `skills/` for reusable workflows and domain knowledge
     - `commands/` plus `legacy-command-shims/` for slash-command compatibility
     - `rules/` for always-on guidance, split into common and language-specific packs
   - These are the main architectural building blocks an installation copies or mounts into a target harness.

3. **Installation and packaging pipeline**
   - The installation system is manifest-driven and target-aware. `manifests/`, `schemas/`, and `scripts/lib/install-*` define what gets installed, where it lands, and how updates/uninstalls are tracked.
   - `install.sh`, `install.ps1`, and `scripts/ecc.js` are the main entry points for applying those manifests to different targets.
   - The repo also carries plugin metadata in `.claude-plugin/`, `.codex-plugin/`, `.opencode/`, and `.cursor/` so the same content can be projected into each tool’s native config shape.

4. **Runtime orchestration and hooks**
   - Behavior enforcement happens through `hooks/` and `scripts/hooks/`, which implement session lifecycle, edit-time checks, formatting, typecheck triggers, security checks, and compaction suggestions.
   - The flow is event-driven: harness event → hook dispatcher/adaptor → shared script logic → side effects such as warnings, formatting, audits, or session-state capture.
   - Cursor is a notable special case: `.cursor/hooks/adapter.js` translates Cursor’s event payloads into the shared hook runtime, so the same enforcement logic can be reused across harnesses.

5. **Session, memory, and continuous learning**
   - The repo has a session-management subsystem centered in `scripts/lib/session-*`, `scripts/lib/state-store`, and related CLI commands like `/sessions`, `/instinct-*`, and `/learn-*`.
   - Data flow here is: session events and observations → store/adapters → state store / instinct artifacts → later reuse through skills or prompts.
   - The newer “continuous-learning-v2” path is more structured and confidence-based, while the older `continuous-learning/` path remains as a legacy Stop-hook pattern extractor.

6. **Tooling and model-agnostic workflows**
   - `skills/` contains the repository’s actual workflow logic: TDD, verification loops, security review, deep research, content generation, market research, and many language/framework-specific patterns.
   - `commands/` mainly preserve command-first compatibility; the README explicitly positions skills as the canonical workflow surface.
   - Agent routing is intentionally model- and harness-agnostic at the repo level; the same skill/agent content is adapted into Claude Code, Codex, OpenCode, and Cursor-specific formats as needed.

7. **MCP and external integrations**
   - `mcp-configs/` and `scripts/lib/mcp-config.js` manage bundled Model Context Protocol server definitions.
   - The repo treats MCPs as optional context-expanding dependencies, with explicit guidance to keep the set small to avoid token bloat.
   - The main external services materially shaping architecture are Claude Code, Anthropic marketplace/plugin distribution, GitHub Marketplace, Context7, Exa, Playwright, Supabase, and other MCP-backed services referenced in configs and docs.

8. **Cross-harness adapters and targets**
   - Different harnesses receive different projections of the same canonical content:
     - Claude Code: plugin/install + hooks + commands + skills + rules
     - Cursor: `.cursor/` layout with hook adapter and YAML rules
     - Codex: `AGENTS.md`, `.codex/`, and sync scripts
     - OpenCode: `.opencode/` plugin/instruction surface
   - The architecture is therefore “canonical source, multiple deploy targets,” not separate implementations per tool.

9. **Stateful operational tooling**
   - `scripts/lib/orchestration-*`, `scripts/orchestrate-*`, `scripts/loop-*`, and `commands/multi-*` support multi-agent and multi-worktree workflows.
   - These features connect planning, execution, and verification across several parallel contexts, often using tmux/worktrees or external workflow runtimes such as `ccg-workflow`.
   - This is the repo’s concurrency/orchestration layer, distinct from the simpler single-session commands.

10. **ECC 2.0 alpha control plane**
   - `ecc2/` is a separate Rust prototype for a local control plane. Its modules split into config, comms, notifications, observability, session management, TUI, and worktree handling.
   - The visible runtime commands in the README suggest a future daemon-oriented architecture: dashboard, start, sessions, status, stop, resume, daemon.
   - The Rust tree is currently an alpha alongside the main Node/Python tooling, not a replacement for it.

11. **Dashboard and operator UI**
   - `ecc_dashboard.py` provides a Tkinter desktop dashboard for browsing agents, skills, commands, rules, and settings.
   - This is a read/inspect/operator interface rather than the core execution engine; it visualizes the same catalog and install surface exposed elsewhere in the repo.

12. **Quality gates and CI**
   - The test suite under `tests/` is broad and architecture-relevant: it validates manifests, hooks, install behavior, command docs, plugin surfaces, and cross-tool compatibility.
   - GitHub Actions in `.github/workflows/` enforce release, validation, and maintenance workflows; the scripts under `scripts/ci/` are the main static and structural gates.
   - In practice, the CI layer protects the repo’s central invariant: every declared surface must remain installable, discoverable, and consistent across harness targets.

13. **Documentation as a delivery surface**
   - The repo’s docs are not incidental; they are part of the product architecture. `README.md`, `docs/`, multilingual translations, release notes, and architecture guides explain how the install/runtime surfaces should behave.
   - Many docs describe target-specific behavior and installation constraints, especially around plugin limitations, rules copying, hook duplication, and cross-harness parity.
   - For a diagram, treat documentation as the control plane for configuration and adoption, not just reference material.

Main entry points: [`scripts/hooks`](https://github.com/affaan-m/everything-claude-code/tree/main/scripts/hooks) (Hooks runtime), [`skills`](https://github.com/affaan-m/everything-claude-code/tree/main/skills) (Skills), [`commands`](https://github.com/affaan-m/everything-claude-code/tree/main/commands) (Commands), [`tests`](https://github.com/affaan-m/everything-claude-code/tree/main/tests) (CI tests)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_g1["Canonical content"]
  node_agents_root["Agents<br/>catalog"]
  node_skills_root["Skills<br/>catalog"]
  node_commands_root["Commands<br/>surface"]
  node_rules_root["Rules<br/>policy"]
end

subgraph group_g2["Packaging"]
  node_manifests["Manifests<br/>install spec"]
  node_schemas["Schemas<br/>validation"]
  node_install_scripts["Install scripts<br/>installer"]
  node_install_entry["Install entry<br/>cli<br/>[install.sh]"]
  node_ecc_entry["ECC CLI<br/>[ecc.js]"]
end

subgraph group_g3["Runtime control"]
  node_hooks_runtime["Hooks runtime<br/>event runtime"]
  node_cursor_adapter["Cursor adapter<br/>[adapter.js]"]
  node_session_learning[("Session learning<br/>stateful loop<br/>[index.js]")]
end

subgraph group_g4["Deploy targets"]
  node_mcp_configs["MCP configs<br/>integration config<br/>[mcp-servers.json]"]
  node_claude_plugin["Claude plugin<br/>target bundle<br/>[plugin.json]"]
  node_cursor_surface["Cursor surface<br/>target bundle<br/>[hooks.json]"]
  node_codex_surface["Codex surface<br/>target bundle<br/>[AGENTS.md]"]
  node_opencode_surface["OpenCode surface<br/>target bundle<br/>[opencode.json]"]
end

subgraph group_g5["Operations"]
  node_orchestration["Orchestration<br/>coordination"]
  node_ecc2["ECC2<br/>rust prototype<br/>[main.rs]"]
  node_dashboard["Dashboard<br/>ui<br/>[ecc_dashboard.py]"]
end

subgraph group_g6["Quality and docs"]
  node_ci_tests["CI tests<br/>validation suite"]
  node_github_workflows["Workflows<br/>ci<br/>[ci.yml]"]
  node_docs["Docs<br/>documentation"]
end

node_repo["Repo<br/>platform"]

node_repo -->|"contains"| node_agents_root
node_repo -->|"contains"| node_skills_root
node_repo -->|"contains"| node_commands_root
node_repo -->|"contains"| node_rules_root
node_repo -->|"drives"| node_manifests
node_repo -->|"defines"| node_schemas
node_manifests -->|"consumed by"| node_install_scripts
node_install_entry -->|"invokes"| node_install_scripts
node_ecc_entry -->|"invokes"| node_install_scripts
node_hooks_runtime -->|"captures"| node_session_learning
node_cursor_adapter -->|"adapts into"| node_hooks_runtime
node_mcp_configs -->|"augments"| node_hooks_runtime
node_agents_root -->|"projects to"| node_claude_plugin
node_skills_root -->|"projects to"| node_claude_plugin
node_commands_root -->|"projects to"| node_claude_plugin
node_rules_root -->|"projects to"| node_cursor_surface
node_skills_root -->|"projects to"| node_cursor_surface
node_commands_root -->|"projects to"| node_codex_surface
node_skills_root -->|"projects to"| node_opencode_surface
node_commands_root -->|"projects to"| node_opencode_surface
node_orchestration -->|"coordinates"| node_hooks_runtime
node_orchestration -.->|"aligns with"| node_ecc2
node_dashboard -->|"inspects"| node_agents_root
node_dashboard -->|"inspects"| node_skills_root
node_ci_tests -->|"validates"| node_manifests
node_ci_tests -->|"validates"| node_hooks_runtime
node_ci_tests -->|"validates"| node_claude_plugin
node_github_workflows -->|"runs"| node_ci_tests
node_docs -->|"documents"| node_install_entry
node_docs -->|"documents"| node_hooks_runtime
node_docs -->|"documents"| node_session_learning

click node_agents_root "https://github.com/affaan-m/everything-claude-code/tree/main/agents"
click node_skills_root "https://github.com/affaan-m/everything-claude-code/tree/main/skills"
click node_commands_root "https://github.com/affaan-m/everything-claude-code/tree/main/commands"
click node_rules_root "https://github.com/affaan-m/everything-claude-code/tree/main/rules"
click node_manifests "https://github.com/affaan-m/everything-claude-code/tree/main/manifests"
click node_schemas "https://github.com/affaan-m/everything-claude-code/tree/main/schemas"
click node_install_scripts "https://github.com/affaan-m/everything-claude-code/blob/main/scripts/lib/install-executor.js"
click node_install_entry "https://github.com/affaan-m/everything-claude-code/blob/main/install.sh"
click node_ecc_entry "https://github.com/affaan-m/everything-claude-code/blob/main/scripts/ecc.js"
click node_hooks_runtime "https://github.com/affaan-m/everything-claude-code/tree/main/scripts/hooks"
click node_cursor_adapter "https://github.com/affaan-m/everything-claude-code/blob/main/.cursor/hooks/adapter.js"
click node_session_learning "https://github.com/affaan-m/everything-claude-code/blob/main/scripts/lib/state-store/index.js"
click node_mcp_configs "https://github.com/affaan-m/everything-claude-code/blob/main/mcp-configs/mcp-servers.json"
click node_claude_plugin "https://github.com/affaan-m/everything-claude-code/blob/main/.claude-plugin/plugin.json"
click node_cursor_surface "https://github.com/affaan-m/everything-claude-code/blob/main/.cursor/hooks.json"
click node_codex_surface "https://github.com/affaan-m/everything-claude-code/blob/main/.codex/AGENTS.md"
click node_opencode_surface "https://github.com/affaan-m/everything-claude-code/blob/main/.opencode/opencode.json"
click node_orchestration "https://github.com/affaan-m/everything-claude-code/blob/main/scripts/lib/orchestration-session.js"
click node_ecc2 "https://github.com/affaan-m/everything-claude-code/blob/main/ecc2/src/main.rs"
click node_dashboard "https://github.com/affaan-m/everything-claude-code/blob/main/ecc_dashboard.py"
click node_ci_tests "https://github.com/affaan-m/everything-claude-code/tree/main/tests"
click node_github_workflows "https://github.com/affaan-m/everything-claude-code/blob/main/.github/workflows/ci.yml"
click node_docs "https://github.com/affaan-m/everything-claude-code/tree/main/docs"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_agents_root,node_skills_root,node_commands_root,node_rules_root toneBlue
class node_manifests,node_schemas,node_install_scripts,node_install_entry,node_ecc_entry toneAmber
class node_hooks_runtime,node_cursor_adapter,node_session_learning toneMint
class node_mcp_configs,node_claude_plugin,node_cursor_surface,node_codex_surface,node_opencode_surface toneRose
class node_orchestration,node_ecc2,node_dashboard toneIndigo
class node_ci_tests,node_github_workflows,node_docs toneTeal
class node_repo toneNeutral
```

## Components

### Canonical content

The source catalog of reusable agent behavior and guidance.

- [Agents](https://github.com/affaan-m/everything-claude-code/tree/main/agents): catalog · Canonical agent definitions and marketplace metadata. · `agents`
- [Skills](https://github.com/affaan-m/everything-claude-code/tree/main/skills): catalog · Canonical workflow and domain skill pack. · `skills`
- [Commands](https://github.com/affaan-m/everything-claude-code/tree/main/commands): surface · Slash-command compatibility surface and multi-tool workflows. · `commands`
- [Rules](https://github.com/affaan-m/everything-claude-code/tree/main/rules): policy · Always-on guidance packs split by common and language-specific rules. · `rules`

### Packaging

Manifest-driven installation and target projection.

- [Manifests](https://github.com/affaan-m/everything-claude-code/tree/main/manifests): install spec · Component, module, and profile install definitions. · `manifests`
- [Schemas](https://github.com/affaan-m/everything-claude-code/tree/main/schemas): validation · JSON schema contracts for install, hooks, plugins, and state. · `schemas`
- [Install scripts](https://github.com/affaan-m/everything-claude-code/blob/main/scripts/lib/install-executor.js): installer · Core install executor, lifecycle, and target resolution logic. · `scripts/lib/install-executor.js`
- [Install entry](https://github.com/affaan-m/everything-claude-code/blob/main/install.sh): cli · Primary shell entry points for applying manifests. · `install.sh`
- [ECC CLI](https://github.com/affaan-m/everything-claude-code/blob/main/scripts/ecc.js): cli · Node entry point for install, orchestration, and state operations. · `scripts/ecc.js`

### Runtime control

Hooks, session state, and learning loops that enforce behavior.

- [Hooks runtime](https://github.com/affaan-m/everything-claude-code/tree/main/scripts/hooks): event runtime · Dispatcher and shared hook logic for edit, shell, session, and compaction events. · `scripts/hooks`
- [Cursor adapter](https://github.com/affaan-m/everything-claude-code/blob/main/.cursor/hooks/adapter.js): adapter · Translates Cursor hook payloads into the shared hook runtime. · `.cursor/hooks/adapter.js`
- [Session learning](https://github.com/affaan-m/everything-claude-code/blob/main/scripts/lib/state-store/index.js): stateful loop · Session adapters, state store, instincts, and continuous learning artifacts. · `scripts/lib/state-store/index.js`

### Deploy targets

Tool-specific projections of the same canonical content.

- [MCP configs](https://github.com/affaan-m/everything-claude-code/blob/main/mcp-configs/mcp-servers.json): integration config · Bundled MCP server definitions and merge logic. · `mcp-configs/mcp-servers.json`
- [Claude plugin](https://github.com/affaan-m/everything-claude-code/blob/main/.claude-plugin/plugin.json): target bundle · Claude Code plugin and harness projection surface. · `.claude-plugin/plugin.json`
- [Cursor surface](https://github.com/affaan-m/everything-claude-code/blob/main/.cursor/hooks.json): target bundle · Cursor rules, skills, and hooks projection surface. · `.cursor/hooks.json`
- [Codex surface](https://github.com/affaan-m/everything-claude-code/blob/main/.codex/AGENTS.md): target bundle · Codex AGENTS and config projection surface. · `.codex/AGENTS.md`
- [OpenCode surface](https://github.com/affaan-m/everything-claude-code/blob/main/.opencode/opencode.json): target bundle · OpenCode commands, prompts, tools, and plugin projection surface. · `.opencode/opencode.json`

### Operations

Multi-session orchestration and alpha control-plane runtime.

- [Orchestration](https://github.com/affaan-m/everything-claude-code/blob/main/scripts/lib/orchestration-session.js): coordination · Multi-agent, multi-worktree, and loop-based execution helpers. · `scripts/lib/orchestration-session.js`
- [ECC2](https://github.com/affaan-m/everything-claude-code/blob/main/ecc2/src/main.rs): rust prototype · Alpha Rust control plane for daemon, session, TUI, and worktree management. · `ecc2/src/main.rs`
- [Dashboard](https://github.com/affaan-m/everything-claude-code/blob/main/ecc_dashboard.py): ui · Desktop/operator view over catalog, install, and settings. · `ecc_dashboard.py`

### Quality and docs

Validation, CI, and documentation that govern the platform.

- [CI tests](https://github.com/affaan-m/everything-claude-code/tree/main/tests): validation suite · Architecture-relevant tests for manifests, hooks, install, and cross-tool parity. · `tests`
- [Workflows](https://github.com/affaan-m/everything-claude-code/blob/main/.github/workflows/ci.yml): ci · GitHub Actions gates for validation, release, and maintenance. · `.github/workflows/ci.yml`
- [Docs](https://github.com/affaan-m/everything-claude-code/tree/main/docs): documentation · Primary and localized docs that specify behavior, limits, and adoption. · `docs`

### Other components

- **Repo**: platform · Cross-harness agent configuration and automation platform.

## Connections

- Repo → Agents: contains · Canonical agent catalog.
- Repo → Skills: contains · Canonical skill catalog.
- Repo → Commands: contains · Command compatibility surface.
- Repo → Rules: contains · Always-on guidance packs.
- Repo → Manifests: drives · Manifest-driven install planning.
- Repo → Schemas: defines · Contracts for install and runtime artifacts.
- Manifests → Install scripts: consumed by · Installer executes manifest definitions.
- Install entry → Install scripts: invokes · Shell entry applies install logic.
- ECC CLI → Install scripts: invokes · Node entry reuses installer core.
- Hooks runtime → Session learning: captures · Hooks feed session and instinct state.
- Cursor adapter → Hooks runtime: adapts into · Cursor-specific event payload translation.
- MCP configs → Hooks runtime: augments · MCP health and execution hooks.
- Agents → Claude plugin: projects to · Claude Code plugin surface.
- Skills → Claude plugin: projects to · Claude Code skill packaging.
- Commands → Claude plugin: projects to · Claude Code command surface.
- Rules → Cursor surface: projects to · Cursor rule packs and files.
- Skills → Cursor surface: projects to · Cursor skill projection.
- Commands → Codex surface: projects to · Codex AGENTS and config surface.
- Skills → OpenCode surface: projects to · OpenCode skill prompts and commands.
- Commands → OpenCode surface: projects to · OpenCode command surface.
- Orchestration → Hooks runtime: coordinates · Loop and workflow helpers trigger hook-backed checks.
- Orchestration → ECC2: aligns with · Future daemon-oriented control plane.
- Dashboard → Agents: inspects · Catalog browsing UI.
- Dashboard → Skills: inspects · Skill browsing UI.
- CI tests → Manifests: validates · Install manifest correctness.
- CI tests → Hooks runtime: validates · Hook behavior and parity.
- CI tests → Claude plugin: validates · Plugin surface integrity.
- Workflows → CI tests: runs · Repository automation gates.
- Docs → Install entry: documents · Installation and target behavior.
- Docs → Hooks runtime: documents · Hook contracts and limitations.
- Docs → Session learning: documents · Session and learning workflows.
