Content
# OpenCode Global Configuration
<p align="center">
<strong>Everything Claude Code (ECC) v2.0.0</strong> — an enterprise-grade AI Skill Hub<br/>
providing <em>67 specialized agents, 271 skills, 92 commands, and automated hook workflows</em> for modern software development.
</p>
<p align="center">
<a href="LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License: MIT" /></a>
<a href="package.json"><img src="https://img.shields.io/badge/version-2.0.0-blue" alt="Version 2.0.0" /></a>
<a href="package.json"><img src="https://img.shields.io/badge/node-%3E%3D18-green" alt="Node >= 18" /></a>
<a href="https://github.com/affaan-m/ECC"><img src="https://img.shields.io/badge/ECC-v2.0.0-orange" alt="ECC v2.0.0" /></a>
<a href="SECURITY.md"><img src="https://img.shields.io/badge/security-supported-brightgreen" alt="Security Policy" /></a>
<a href="CODE_OF_CONDUCT.md"><img src="https://img.shields.io/badge/Contributor%20Covenant-2.0-4baaaa" alt="Contributor Covenant" /></a>
<a href="https://opencode.ai"><img src="https://img.shields.io/badge/OpenCode-ready-6366f1" alt="OpenCode Ready" /></a>
</p>
---
## Table of Contents
- [Vision & Goals](#vision--goals)
- [Key Features](#key-features)
- [Repository Structure](#repository-structure)
- [Quick Start](#quick-start)
- [Installation](#installation)
- [Configuration](#configuration)
- [Architecture](#architecture)
- [Core Capabilities](#core-capabilities)
- [Agents](#agents)
- [Skills](#skills)
- [Commands](#commands)
- [Rules](#rules)
- [Hooks](#hooks)
- [MCP Servers](#mcp-servers)
- [Usage Examples](#usage-examples)
- [AI Coding Environment Support](#ai-coding-environment-support)
- [Best Practices](#best-practices)
- [Security](#security)
- [Contributing](#contributing)
- [Versioning](#versioning)
- [Changelog](#changelog)
- [FAQ](#frequently-asked-questions)
- [Troubleshooting](#troubleshooting)
- [Support](#support)
- [Community](#community)
- [Attribution & Credits](#attribution--credits)
- [Roadmap](#roadmap)
- [License](#license)
---
## Vision & Goals
The **OpenCode Global Configuration** transforms your AI coding assistant into a production-grade development platform. Built on the Everything Claude Code (ECC) ecosystem, it provides battle-tested skills, agents, prompts, workflows, templates, and reusable automation — all pre-configured and ready to use.
### What Makes This Different
- **Agent-First Architecture** — 67 specialized AI sub-agents for every development phase
- **Test-Driven by Default** — 80%+ coverage enforced with automated verification
- **Security-First Design** — Input validation, secret scanning, and vulnerability audits built into the workflow
- **Cross-Harness Support** — Works with OpenCode, Claude Code, Codex CLI, Cursor, Gemini CLI, Qwen Code, and more
- **Community-Driven** — 1,630 marketplace skills from the open-source ecosystem
---
## Key Features
| Feature | Description |
|---------|-------------|
| **Specialized AI Agents** | 67 domain-expert agents for code review, TDD, security, architecture, build resolution, and more |
| **Canonical Skills** | 271 workflow skills — the definitive surface for AI-assisted development workflows |
| **Slash Commands** | 132 commands across root and plugin layers for quick workflow invocation |
| **Lifecycle Automation** | 28 hooks across 7 lifecycle events — PreToolUse, PostToolUse, Stop, SessionStart, and more |
| **Language Rules** | 113 per-language rule files across 22 categories (TypeScript, Python, Go, Rust, Swift, etc.) |
| **MCP Server Configs** | 18 enabled + 15 optional MCP server configurations for extended capabilities |
| **Marketplace Skills** | 1,630 community skills covering Azure, SaaS, security, blockchain, design, and more |
| **OpenCode Plugin** | Native plugin with 12 design/SEO/OpenSpec skills, 40 commands, 9 custom tools |
| **CI/CD Ready** | GitHub Actions, Dependabot, issue/PR templates, CODEOWNERS, and more |
---
## Repository Structure
```
opencode/
├── skills/ ← 271 ECC canonical workflow skills
│ ├── tdd-workflow/ — Test-driven development
│ ├── security-review/ — Security patterns & checklist
│ ├── coding-standards/ — Cross-project code conventions
│ ├── frontend-patterns/ — React, Next.js, state, performance
│ ├── backend-patterns/ — API design, database, caching
│ ├── el2e-testing/ — Playwright E2E testing patterns
│ └── ... — 265 more skills
│
├── commands/ ← 92 slash commands
│ ├── plan.md — Implementation planning
│ ├── code-review.md — Expert code review
│ ├── orch-add-feature.md — Orchestrated feature development
│ ├── orch-fix-defect.md — Orchestrated bug fixing
│ └── ... — 88 more commands
│
├── rules/ ← 22 language rule categories / 113 files
│ ├── common/ — 10 cross-cutting rules
│ ├── typescript/ — TS-specific conventions
│ ├── python/ — PEP 8, patterns, security, testing
│ ├── rust/ — Ownership, traits, concurrency
│ └── ... — 18 more languages
│
├── hooks/ ← Lifecycle automation
│ ├── hooks.json — 28 hooks across 7 events
│ └── memory-persistence/ — Cross-session state management
│
├── .agents/skills/ ← 1,630 community marketplace skills
├── .agents/plugins/ — Plugin marketplace manifest
│
├── .opencode/ ← OpenCode native plugin
│ ├── skills/ — 12 design/SEO/OpenSpec skills
│ ├── commands/ — 40 commands
│ ├── prompts/agents/ — 32 agent prompt templates
│ └── tools/ — 9 custom TypeScript tools
│
├── ECC/ ← Submodule: Core ECC engine
│ ├── agents/ — 67 specialized agent definitions
│ ├── skills/ — 271 skills (source of truth)
│ ├── commands/ — 92 commands (source of truth)
│ ├── hooks/ — Hook scripts and configs
│ ├── mcp-configs/ — 33 MCP server configurations
│ └── tests/ — ECC test suite
│
├── OpenSpec/ ← Submodule: Spec-driven development CLI
├── plugins/ponytail/ ← Submodule: Lazy dev mode
│
├── .github/ ← CI/CD, templates, dependabot
├── scripts/ ← validate, clean, install-hooks
│
├── README.md ← You are here
├── CONTRIBUTING.md ← How to contribute
├── SECURITY.md ← Security policy
├── CODE_OF_CONDUCT.md ← Community guidelines
├── LICENSE ← MIT License
├── CHANGELOG.md ← Release history
├── ROADMAP.md ← Future plans
├── SUPPORT.md ← Getting help
├── FAQ.md ← Frequently asked questions
├── GOVERNANCE.md ← Project governance
├── ACKNOWLEDGEMENTS.md ← Credits and attribution
├── AGENTS.md ← AI agent instructions
├── ATTRIBUTION.md ← Full credit trail
├── opencode.jsonc ← OpenCode configuration
├── package.json ← npm package definition
└── .editorconfig ← Cross-editor consistency
```
---
## Quick Start
```bash
# Clone with all submodules (includes ECC, OpenSpec, gstack, Ponytail)
git clone --recurse-submodules https://github.com/YOUR_ORG/opencode.git ~/.config/opencode
# Install dependencies
cd ~/.config/opencode && npm install
# Validate the installation
npm run validate
# Install hook automation
npm run install:hooks
```
Restart your AI coding environment. The configuration loads automatically on startup.
> **Lightweight Install:** Need only the core without marketplace skills? See [Installation Options](#installation).
---
## Installation
### Prerequisites
| Requirement | Minimum | Recommended |
|-------------|---------|-------------|
| **Node.js** | ≥ 18.0.0 | 20 LTS or 22 |
| **Git** | ≥ 2.30 | Latest stable |
| **npm** | ≥ 9.0 | Latest (bundled with Node) |
| **Disk Space** | ~1 GB (core only) | ~2 GB (full install) |
| **Shell** | Bash / Zsh / PowerShell 5.1+ | — |
#### Additional Platform-Specific Prerequisites
<details>
<summary><strong>Windows</strong></summary>
- Windows 10+ (64-bit) or Windows Server 2019+
- PowerShell 5.1 or PowerShell Core 7+
- [Git for Windows](https://git-scm.com/download/win) (includes Git Bash)
- [Node.js for Windows](https://nodejs.org/) (includes npm)
- Optional: Windows Terminal for best experience
</details>
<details>
<summary><strong>macOS</strong></summary>
- macOS 12 (Monterey) or later
- Xcode Command Line Tools: `xcode-select --install`
- Homebrew (recommended for package management)
</details>
<details>
<summary><strong>Linux</strong></summary>
- Ubuntu 20.04+, Debian 11+, Fedora 38+, or equivalent
- `build-essential` (Ubuntu/Debian) or `Development Tools` (Fedora)
- `curl` and `wget` for downloading tools
- `python3` (for some submodule tooling)
</details>
### Installation Instructions
#### Windows
```powershell
# 1. Install prerequisites (as Administrator)
winget install Git.Git
winget install OpenJS.NodeJS.LTS
# 2. Clone the repository
git clone --recurse-submodules https://github.com/YOUR_ORG/opencode.git $env:USERPROFILE\.config\opencode
# 3. Install dependencies
Set-Location "$env:USERPROFILE\.config\opencode"
npm install
# 4. Validate
npm run validate
# 5. Install hooks
npm run install:hooks
```
#### macOS
```bash
# 1. Install prerequisites
brew install git node
# 2. Clone the repository
git clone --recurse-submodules https://github.com/YOUR_ORG/opencode.git ~/.config/opencode
# 3. Install dependencies
cd ~/.config/opencode && npm install
# 4. Validate
npm run validate
# 5. Install hooks
npm run install:hooks
```
#### Linux
```bash
# 1. Install prerequisites (Ubuntu/Debian)
sudo apt update && sudo apt install -y git curl build-essential
curl -fsSL https://deb.nodesource.com/setup_20.x | sudo -E bash -
sudo apt install -y nodejs
# 1. Install prerequisites (Fedora)
sudo dnf install -y git curl gcc gcc-c++ make
curl -fsSL https://rpm.nodesource.com/setup_20.x | sudo bash -
sudo dnf install -y nodejs
# 2. Clone the repository
git clone --recurse-submodules https://github.com/YOUR_ORG/opencode.git ~/.config/opencode
# 3. Install dependencies
cd ~/.config/opencode && npm install
# 4. Validate
npm run validate
# 5. Install hooks
npm run install:hooks
```
### Installation Options
#### Full Install (Recommended)
Includes ECC, OpenSpec, gstack, Ponytail, and all 1,630 marketplace skills.
```bash
git clone --recurse-submodules <repo-url> ~/.config/opencode
cd ~/.config/opencode && npm install
```
**Disk space:** ~2 GB
#### Core-Only (Lightweight)
Core ECC + OpenCode plugin, no community marketplace skills.
```bash
git clone --recurse-submodules --filter=blob:none <repo-url> ~/.config/opencode
cd ~/.config/opencode
git sparse-checkout init --cone
git sparse-checkout set '/*' '!.agents/skills/'
npm install
```
**Disk space:** ~350 MB
#### Plugin-Only (Minimal)
Only the OpenCode plugin and core ECC. No submodules.
```bash
git clone --filter=blob:none --no-checkout <repo-url> ~/.config/opencode
cd ~/.config/opencode
git sparse-checkout init --cone
git sparse-checkout set '/*' '!.agents/' '!ECC/' '!OpenSpec/'
git checkout main
npm install --production
```
**Disk space:** ~100 MB
### Updating
```bash
cd ~/.config/opencode
git pull --recurse-submodules
npm install
npm run validate
```
### Uninstalling
#### Windows
```powershell
Remove-Item -Recurse -Force "$env:USERPROFILE\.config\opencode"
```
#### macOS / Linux
```bash
rm -rf ~/.config/opencode
```
### Verification
After installation, verify everything is working:
```bash
cd ~/.config/opencode
npm run validate # Validate repository integrity
node -e "require('./package.json'); console.log('OK')" # Check package
git submodule status # Verify submodules
```
---
## Configuration
### OpenCode Configuration (`opencode.jsonc`)
The `opencode.jsonc` file in the repository root configures the OpenCode plugin ecosystem:
- **Plugins:** `opencode-ponytail` (lazy development mode)
- **MCP Servers:** 18 enabled, 15 optional (see [MCP Servers](#mcp-servers) section)
- **Settings:** Permission rules, always-allow commands, model routing
### Required Environment Variables
| Variable | Purpose | Required |
|----------|---------|----------|
| `OPENAI_API_KEY` | OpenAI API for embeddings, chat | For AI features |
| `ANTHROPIC_API_KEY` | Anthropic API for Claude models | For Claude features |
| `GEMINI_API_KEY` | Google Gemini API | For Gemini features |
> **Note:** All API keys in MCP configurations are templates (`YOUR_*_HERE`). Replace with real values after installation. Never commit real credentials.
### Permission Configuration
Review and customize `opencode.jsonc` permissions for your environment:
```jsonc
{
"permissions": {
"allow": [
"Bash(npm test)",
"Bash(npm run lint)",
"Bash(npm run validate)"
],
"deny": [
"Bash(rm -rf /*)",
"Bash(git push --force)"
]
}
}
```
---
## Architecture
```mermaid
graph TD
subgraph "AI Coding Harness"
OC[OpenCode CLI]
CC[Claude Code]
CX[Codex CLI]
GC[Gemini CLI]
QC[Qwen Code]
AU[Aider]
GO[Goose]
AM[Amp]
CN[Continue]
end
subgraph "Plugin Layer"
PLUGIN[".opencode/ Plugin"]
PONY["plugins/ponytail<br/>Lazy Dev Mode"]
end
subgraph "ECC Core v2.0.0"
direction TB
A["67 Agents"]
S["271 Skills"]
C["92 Commands"]
H["28 Hooks"]
R["22 Rule Categories"]
M["33 MCP Servers"]
T["Test Suite<br/>80%+ Coverage"]
end
subgraph "Submodules"
EC["ECC/"]
OS["OpenSpec/"]
GS["gstack/"]
PT["ponytail/"]
end
subgraph "Community Ecosystem"
MK[".agents/skills/<br/>1,630 Marketplace Skills"]
AP[".agents/plugins/<br/>Plugin Registry"]
end
OC --> PLUGIN
CC --> PLUGIN
CX --> PLUGIN
GC --> PLUGIN
PLUGIN --> EC
OC --> PONY
EC --> A
EC --> S
EC --> C
EC --> H
EC --> R
EC --> M
EC --> T
EC --> MK
EC --> AP
EC --> OS
EC --> GS
EC --> PT
```
### How It Works
1. **Harness Layer** — Your AI coding environment (OpenCode, Claude Code, etc.) boots
2. **Plugin Layer** — `.opencode/` plugin auto-loads, registering skills, commands, and tools
3. **ECC Core** — Agents, skills, hooks, rules, and MCP servers activate through the plugin
4. **Community** — Marketplace skills are available on-demand for domain-specific tasks
5. **Submodules** — OpenSpec, gstack, and Ponytail extend functionality independently
---
## Core Capabilities
### Agents
67 specialized AI sub-agents covering every phase of the development lifecycle:
| Category | Count | Key Agents |
|----------|-------|------------|
| **Code Review** | 22 | TypeScript Reviewer, Python Reviewer, Go Reviewer, Rust Reviewer, Java/Kotlin Reviewer, C++ Reviewer, PHP Reviewer, Django Reviewer, F# Reviewer, ML Engineer Reviewer |
| **Build Resolution** | 12 | TypeScript/Go/Rust/Java/Kotlin/C++/Django/PyTorch Build Resolvers |
| **Architecture** | 5 | Architect, Database Reviewer, Network Architect, Healthcare Specialist, Homelab Specialist |
| **Operations** | 6 | Loop Operator, Harness Optimizer, E2E Runner, Cost Tracker |
| **Meta/Quality** | 10 | Planner, Spec Miner, Refactor Cleaner, Doc Updater, TDD Guide |
| **Security** | 3 | Security Reviewer, Security Bounty Hunter, Threat Modeler |
| **GAN Family** | 3 | Generator, Evaluator, Planner (GAN-style agent harness) |
| **Other** | 6 | SEO Specialist, Marketing Agent, Open-Source Pipeline |
### Skills
**271 canonical workflow skills** in the `skills/` directory — each is a self-contained `.md` file defining workflows, patterns, and domain knowledge.
<details>
<summary><strong>Top-Level Skill Categories</strong></summary>
| Category | Skills |
|----------|--------|
| **Development Workflows** | tdd-workflow, verification-loop, strategic-compact, benchmark-optimization-loop, code-tour |
| **Frontend** | frontend-patterns, frontend-a11y, frontend-design-direction, make-interfaces-feel-better, frontend-slides, motion-ui |
| **Backend** | backend-patterns, api-design, api-connector-builder, error-handling |
| **Security** | security-review, security-bounty-hunter, security-scan, hipaa-compliance, defi-amm-security |
| **Testing** | e2e-testing, browser-qa, canary-watch, react-testing, ai-regression-testing |
| **Agent Engineering** | agentic-engineering, agentic-os, autonomous-agent-harness, agent-architecture-audit, skill-comply |
| **Multi-Agent** | santa-method, team-builder, team-agent-orchestration, autonomous-loops, parallel-execution-optimizer |
| **AI/ML** | ml-adoption-playbook, mle-workflow, pytorch-patterns, embedding-strategies, llm-trading-agent-security |
| **Database** | postgres-patterns, mysql-patterns, redis-patterns, prisma-patterns, database-migrations |
| **Cloud/Infra** | docker-patterns, kubernetes-patterns, netmiko-ssh-automation, cisco-ios-patterns, network-config-validation |
| **Design** | design-system, frontend-design-direction, ui-demo, liquid-glass-design |
| **Documentation** | documentation-lookup, inherity-legacy-style, codebase-onboarding |
| **Enterprise** | healthcare-cdss-patterns, healthcare-emr-patterns, healthcare-phi-compliance, customs-trade-compliance, logistics-exception-management |
| **Finance/Crypto** | cost-tracking, cost-aware-llm-pipeline, evm-token-decimals, ito-basket-compare, ito-market-intelligence |
| **Toolchains** | vite-patterns, nextjs-turbopack, bun-runtime, flox-environments |
</details>
Full catalog: browse the `skills/` directory.
### Commands
**92 slash commands** in `commands/` plus **40 additional commands** in `.opencode/commands/`:
| Command | Purpose |
|---------|---------|
| `/plan` | Create structured implementation plans |
| `/code-review` | Expert code review with quality gates |
| `/tdd` | Test-driven development cycle (red-green-refactor) |
| `/build-fix` | Resolve build and type errors |
| `/e2e` | End-to-end Playwright testing |
| `/orchestrate` | Multi-agent workflow orchestration |
| `/orch-add-feature` | Full feature development pipeline |
| `/orch-fix-defect` | Bug fixing pipeline |
| `/orch-build-mvp` | Bootstrap a working MVP |
| `/orch-refine-code` | Behavior-preserving refactoring |
| `/pr` | Pull request creation with commit analysis |
| `/security-review` | Comprehensive security audit |
| `/verify` | Verification loop (build, lint, test, security) |
| `/skill-create` | Create new skills following best practices |
| `/harness-audit` | Audit agent harness for reliability |
| `/model-route` | Cost-aware model routing |
| `/learn` | Capture session knowledge |
Full catalog: `commands/` (92 commands).
### Rules
**22 rule categories, 113 files** — always-on coding standards for every language:
| Category | Files | Coverage |
|----------|-------|----------|
| `common/` | 10 | Agents, code review, coding style, git, hooks, patterns, performance, security, testing, workflow |
| `typescript/` | 5 | Coding style, hooks, patterns, security, testing |
| `python/` | 6 | Coding style, FastAPI, hooks, patterns, security, testing |
| `web/` | 7 | Coding style, design quality, hooks, patterns, performance, security, testing |
| `rust/` `go/` `java/` `kotlin/` `swift/` `cpp/` `csharp/` `dart/` `fsharp/` `ruby/` `php/` `perl/` | 5 each | Coding style, hooks, patterns, security, testing |
| `react/` `vue/` `angular/` `nuxt/` `arkts/` | 5 each | Coding style, hooks, patterns, security, testing |
### Hooks
**28 hooks across 7 lifecycle events** for automated workflow enforcement:
| Event | Hooks | Purpose |
|-------|-------|---------|
| `PreToolUse` | 8 | Bash safety dispatch, doc warnings, compact suggestions, context guards |
| `PostToolUse` | 12 | Quality gates, design checks, activity tracking, MCP monitoring |
| `Stop` | 7 | Format/typecheck, console.log check, session evaluation, cost tracking |
| `SessionStart` | 1 | Context restoration, package manager detection |
| `PreCompact` | 1 | State preservation before compaction |
| `SessionEnd` | 1 | Session lifecycle marker |
Configuration: `hooks/hooks.json`
### MCP Servers
**18 enabled + 15 optional** MCP server configurations:
<details>
<summary><strong>Enabled MCP Servers</strong></summary>
| Server | Purpose |
|--------|---------|
| `chrome-devtools` | Browser automation and debugging |
| `context7` | Documentation lookup via Context7 API |
| `magic` | Magic UI component registry |
| `playwright` | Cross-browser E2E testing |
| `memory` | Persistent knowledge graph |
| `sequential-thinking` | Structured problem solving |
| `token-optimizer` | Token usage and cost optimization |
| `parallel-search` | Web search and content extraction |
| `cloudflare-docs` | Cloudflare documentation |
| `laraplugins` | Laravel package discovery |
| `vercel` | Vercel deployment management |
| `clickhouse` | ClickHouse database queries |
</details>
Configuration: `opencode.jsonc` and `ECC/mcp-configs/`
---
## Usage Examples
### Example 1: Add a Feature with TDD
```
/tdd add-user-authentication
```
The TDD workflow guides you through:
1. Write user journeys
2. Generate test cases (RED)
3. Implement minimal code (GREEN)
4. Refactor and verify coverage (80%+)
### Example 2: Security Review Before Commit
```
/security-review
```
The security reviewer audits your changes for:
- Hardcoded secrets and API keys
- SQL injection and XSS vulnerabilities
- Input validation gaps
- Authentication/authorization issues
### Example 3: Fix a Build Error
```
/build-fix
```
The build error resolver:
1. Reads the error output
2. Analyzes root causes
3. Proposes minimal fixes
4. Verifies the build passes
### Example 4: End-to-End Testing
```
/e2e login-flow
```
The E2E runner:
1. Generates Playwright test script
2. Runs against your local dev server
3. Reports results with screenshots
### Example 5: Multi-Agent Workflow
```
/orchestrate build new-recipe-sharing-feature
```
The orchestrator dispatches:
- **Planner** — design the architecture
- **TDD Guide** — write tests first
- **Mason** — implement the code
- **Code Reviewer** — review quality
- **Luna** — verify correctness
---
## AI Coding Environment Support
This repository is primarily designed for **OpenCode**, but works with many AI coding environments:
| Environment | Support Level | Notes |
|-------------|---------------|-------|
| **OpenCode** | Native | Primary target — plugin auto-loads |
| **Claude Code** | Full | ECC was originally built for Claude Code |
| **Codex CLI** | Full | Compatible via ECC core |
| **Gemini CLI** | Full | Compatible via ECC core |
| **Cursor** | Partial | Skills and rules compatible |
| **Qwen Code** | Partial | Core ECC compatible |
| **Aider** | Partial | Skills usable as prompts |
| **Goose** | Partial | Skills and agents compatible |
| **Amp** | Partial | Skills usable as prompts |
| **Continue** | Partial | Skills and rules compatible |
### Setup for Other Environments
<details>
<summary><strong>Claude Code</strong></summary>
```bash
# Point Claude Code to the ECC configuration
export CLAUDE_CONFIG_DIR="$HOME/.config/opencode/ECC/.claude"
claude
```
</details>
<details>
<summary><strong>Codex CLI</strong></summary>
```bash
# Use ECC skills as Codex prompts
codex --config "$HOME/.config/opencode/ECC/.codex"
```
</details>
<details>
<summary><strong>Gemini CLI</strong></summary>
```bash
gemini --config "$HOME/.config/opencode/ECC/.gemini"
```
</details>
<details>
<summary><strong>Cursor</strong></summary>
Copy the rules to your project's `.cursor/rules/` directory:
```bash
cp -r ~/.config/opencode/rules/* .cursor/rules/
```
</details>
<details>
<summary><strong>Aider</strong></summary>
Use skills as aider conventions:
```bash
aider --read "~/.config/opencode/skills/coding-standards/SKILL.md"
```
</details>
---
## Best Practices
### For Developers
1. **Use `npm run validate` before committing** — catches structural issues early
2. **Follow conventional commits** — `feat:`, `fix:`, `docs:`, `refactor:`, `test:`, `chore:`
3. **Review hook output** — hooks catch quality issues automatically
4. **Keep skills focused** — one domain per skill, under 800 lines
5. **Leverage agents proactively** — let the planner and reviewer agents catch issues before you commit
### For AI Coding Agents
1. **Trust the hooks** — automated quality gates run on every tool use
2. **Use the agent catalog** — 67 specialists are available, delegate freely
3. **Follow TDD workflow** — write tests before implementation
4. **Verify before claiming done** — run `npm run validate` + the test suite
5. **Respect the agent hierarchy** — skills > commands for canonical workflows
---
## Security
See [SECURITY.md](SECURITY.md) for our full security policy.
**Key principles:**
- No hardcoded secrets — all credentials go through environment variables
- Input validation on all boundaries — use schema validation (Zod, Pydantic, etc.)
- Row-Level Security where applicable — database access scoped per user
- Regular dependency audits — `npm audit` integrated into CI
- Secret scanning — hooks detect accidental credential exposure
**Reporting vulnerabilities:** Use GitHub private vulnerability reporting or email `affaan@ecc.tools`. Never open a public issue for security vulnerabilities.
---
## Contributing
We welcome contributions! See [CONTRIBUTING.md](CONTRIBUTING.md) for detailed guidelines.
**Quick contribution flow:**
1. Fork and clone the repository
2. Create a branch: `git checkout -b feat/my-contribution`
3. Make changes following conventions
4. Run `npm run validate` and `npm test`
5. Submit a PR with the template
**What we accept:**
- New skills (under `skills/your-skill-name/SKILL.md`)
- Agent improvements (under `ECC/agents/`)
- Rule refinements (under `rules/`)
- Documentation fixes
- Hook configurations
- MCP server configs
---
## Versioning
This repository follows [Semantic Versioning](https://semver.org/) (SemVer 2.0.0):
- **Major** (X.0.0) — breaking changes to skill/agent/command APIs
- **Minor** (0.X.0) — new skills, agents, commands, features (backward-compatible)
- **Patch** (0.0.X) — bug fixes, documentation, configuration updates
Current version: **2.0.0**
---
## Changelog
See [CHANGELOG.md](CHANGELOG.md) for the full release history.
For detailed ECC changelog, see [ECC/CHANGELOG.md](ECC/CHANGELOG.md).
---
## Frequently Asked Questions
See [FAQ.md](FAQ.md) for the complete FAQ.
**Quick answers:**
<details>
<summary><strong>What's the difference between skills/ and commands/?</strong></summary>
Skills are the canonical workflow surface — comprehensive `.md` files with domain knowledge, patterns, and workflows. Commands are user-facing slash commands that invoke skills. Skills are where the knowledge lives; commands are how you access it.
</details>
<details>
<summary><strong>How do I create a new skill?</strong></summary>
Use `/skill-create` command or see [CONTRIBUTING.md](CONTRIBUTING.md). Place your skill at `skills/your-skill-name/SKILL.md` with YAML frontmatter including `name:`, `description:`, and `origin:` fields.
</details>
<details>
<summary><strong>Can I remove marketplace skills I don't need?</strong></summary>
Yes. Run a core-only install or manually delete from `.agents/skills/`. The core ECC skills (in `skills/`) are recommended to keep.
</details>
<details>
<summary><strong>How do I update to the latest version?</strong></summary>
```bash
cd ~/.config/opencode
git pull --recurse-submodules
npm install
npm run validate
```
</details>
---
## Troubleshooting
<details>
<summary><strong>Installation fails with submodule errors</strong></summary>
```bash
# Initialize submodules manually
git submodule update --init --recursive
# Or clone fresh with submodules
git clone --recurse-submodules <repo-url> ~/.config/opencode
```
</details>
<details>
<summary><strong>Validation fails after installation</strong></summary>
```bash
# Run validation with verbose output
npm run validate
# Common fixes:
npm install # Reinstall dependencies
git submodule update --init # Sync submodules
```
</details>
<details>
<summary><strong>Hooks aren't working</strong></summary>
```bash
# Reinstall hooks
npm run install:hooks
# Check hook configuration
cat hooks/hooks.json | grep -c '"type"'
```
</details>
<details>
<summary><strong>Node.js version too old</strong></summary>
```bash
# Check version
node -v
# Upgrade via nvm
nvm install 20
nvm use 20
# Or via your package manager
brew upgrade node # macOS
winget upgrade OpenJS.NodeJS.LTS # Windows
```
</details>
<details>
<summary><strong>MCP servers not connecting</strong></summary>
Check that required API keys are set as environment variables. MCP server configs use `YOUR_*_HERE` templates that must be replaced with real values.
</details>
---
## Support
See [SUPPORT.md](SUPPORT.md) for the complete support guide.
- **Documentation:** Start with this README and the [FAQ](FAQ.md)
- **Bugs:** Open a [GitHub Issue](https://github.com/YOUR_ORG/opencode/issues) using the bug report template
- **Feature Requests:** Use the [Feature Request template](https://github.com/YOUR_ORG/opencode/issues/new?template=feature_request.md)
- **Security Issues:** See [SECURITY.md](SECURITY.md) — do NOT open a public issue
- **Discussions:** GitHub Discussions (if enabled) or the ECC community
---
## Community
- **ECC Repository:** [github.com/affaan-m/ECC](https://github.com/affaan-m/ECC)
- **OpenCode:** [opencode.ai](https://opencode.ai)
- **OpenSpec:** [github.com/Fission-AI/OpenSpec](https://github.com/Fission-AI/OpenSpec)
---
## Attribution & Credits
This repository is built on the work of multiple open-source ecosystems. See [ATTRIBUTION.md](ATTRIBUTION.md) for the full credit trail and [ACKNOWLEDGEMENTS.md](ACKNOWLEDGEMENTS.md) for detailed credits.
### Core Components
| Component | Version | Author | Repository | License |
|-----------|---------|--------|------------|---------|
| **ECC** | v2.0.0 | Affaan Mustafa | [affaan-m/ECC](https://github.com/affaan-m/ECC) | MIT |
| **OpenSpec** | v1.4.1 | Fission AI | [Fission-AI/OpenSpec](https://github.com/Fission-AI/OpenSpec) | MIT |
| **gstack** | — | Garry Tan | [garrytan/gstack](https://github.com/garrytan/gstack) | MIT |
| **Ponytail** | v4.7.3 | Dietrich Gebert | [DietrichGebert/ponytail](https://github.com/DietrichGebert/ponytail) | MIT |
| **Community Skills** | — | 1,630 marketplace contributors | — | Various |
### Technology Acknowledgements
- **MCP Protocol** — [Anthropic](https://modelcontextprotocol.io)
- **OpenCode** — [opencode.ai](https://opencode.ai)
- **Playwright Skill** — [@lackeyjb](https://github.com/lackeyjb)
---
## Roadmap
See [ROADMAP.md](ROADMAP.md) for detailed future plans.
### Upcoming
- [ ] Expanded cross-harness support (more AI coding environments)
- [ ] Plugin marketplace with versioned releases
- [ ] Web dashboard for skill/agent/hook management
- [ ] Automated skill testing and CI validation
- [ ] Community skill review and quality scoring
- [ ] Multi-language documentation (zh-CN, ja, ko, pt-BR)
---
## License
MIT — See [LICENSE](LICENSE) for full text.
Copyright (c) 2026 Affaan Mustafa and contributors.
---
<p align="center">
<sub>Built with ❤️ by the open-source community. Maintained with the Everything Claude Code (ECC) ecosystem.</sub>
</p>
MCP Config
Below is the configuration for this MCP Server. You can copy it directly to Cursor or other MCP clients.
mcp.json
Connection Info
You Might Also Like
No recommendations available