Contributing

Full source: .github/CONTRIBUTING.md in the repository. This page is a condensed pointer, always defer to the file in the repo if the two disagree.

Where to start

• Fix a bug: issues labeled good first issue are small and self-contained.
• Translate the README: translation happens on Crowdin, no code required. A PR is opened automatically once a language reaches 100 percent; never open a manual translation PR.
• Test on your platform: report what works and what does not on Windows or macOS.
• Add an agent or skill: look at existing files in agents/ and skills/ for the format; the CI validator explains structural issues.

Quick start

gh repo fork Fmarzochi/EGC --clone
cd EGC
git config core.hooksPath .githooks   # one-time: auto sign-off hook
git checkout -b feat/my-contribution
# make your change
npm ci
node tests/run-all.js
npm audit --audit-level=high
git add . && git commit -m "feat: add my-feature" && git push -u origin feat/my-contribution

DCO and CLA

Every commit needs a Signed-off-by line (Developer Certificate of Origin). Run git config core.hooksPath .githooks once per clone and the .githooks/prepare-commit-msg hook adds it automatically; you never need to type -s again. Every contributor also signs a CLA once, by replying to the CLA bot's comment on their first PR with the sign phrase the bot posts.

CI checks a PR must pass

Check	What it validates
CLA	First-time contributors have signed the CLA
DCO	Every commit has Signed-off-by
CI / test	node tests/run-all.js on Linux, macOS, Windows, Node 20 and 22, npm/yarn/bun
CI / lint	ESLint on scripts/, tests/ and the TypeScript of both MCP servers (mcp/servers/*/src/); markdownlint on all .md files in agents/, skills/, commands/, rules/
CI / validate	Structure validators for agents, hooks, skills, commands, install manifests, rules, unicode safety
CI / security	npm audit --audit-level=high
Dependency Review	Blocks dependencies with incompatible licenses or known CVEs
SonarCloud	Static analysis: code smells, bugs, security hotspots
CodeRabbit	AI code review
PR Size	Fails if the PR changes more than 150 code files

Other workflows in .github/workflows/ also run on pull requests: CodeQL, ClusterFuzzLite, coverage, Socket Security, OpenSSF Scorecard, and a PR text leak check.

First-time contributors from a fork need a maintainer to click "Approve and run" in the Actions tab before checks run; this is expected, do not close and reopen the PR.

Adding a skill

skills/your-skill-name/SKILL.md

---
name: your-skill-name
description: Brief description used for auto-activation.
origin: EGC
---

Checklist: focused on one domain, includes a "When to Activate" section, has copy-pasteable code examples, shows anti-patterns, stays under 500 lines (800 max), no sensitive data.

Adding an agent

agents/your-agent-name.md

---
name: your-agent-name
description: What this agent does and when the orchestrator should invoke it.
tools: ["Read", "Write", "Edit", "Bash", "Grep", "Glob"]
model: claude-sonnet-4-6
stack: ["*"]
---

Adding a hook

Hooks live in hooks/hooks.json and are implemented in scripts/hooks/. Event types: PreToolUse, PostToolUse, PostToolUseFailure, UserPromptSubmit, SessionStart, SessionEnd, PreCompact, Stop. The matcher must be specific, the hook must identify itself as [EGC Hook] in its output, and it must be tested locally before submission.

Adding a command

commands/your-command.md

---
description: Brief description shown in /help
---

Dependencies

Dependencies are added only when necessary, must use a permissive license (MIT, ISC, BSD, Apache-2.0, or equivalent), and must have active maintenance. All dependencies are obtained through npm and locked in package-lock.json.

PR title and description

Follow conventional commits: feat(runtime): ..., fix(hooks): ..., docs(governance): .... Include a summary of what architectural gap the PR fills, the component type, how you validated it, and the checklist from the PR template (CLA, DCO, tests, audit, markdownlint, file count, tested cross-platform if applicable).

Concurrent-access tests

Any change touching a file shared across concurrent EGC processes (the encryption key, state files, install-state, lockfiles under ~/.egc/) needs a concurrent-access regression test. See Security for why.

Build

npm ci
npm run build     # compiles the two MCP servers (TypeScript to build/)
node tests/run-all.js

Requires Node.js 20 or later.