Skill-Hub

# 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"> _{Built with ❤️ by the open-source community. Maintained with the Everything Claude Code (ECC) ecosystem.} </p>