# Contributing to devcoach ## Quick start Requires **Node.js ≥ 24** (devcoach uses the embedded `node:sqlite`); `.node-version` pins 26, which is what CI tests alongside 24. ```bash git clone https://github.com/UltimaPhoenix/dev-coach && cd dev-coach npm install npm run dev -- mcp # run the MCP server from source (tsx) npm run dev -- ui # run the web dashboard from source ``` ## Before every commit ```bash npm run lint # Biome check (auto-fix: npm run format) npm run typecheck # TypeScript npm run test:cov # Vitest — coverage thresholds: 92% lines, 95% functions, 91% statements, 76% branches ``` All three must pass before opening a PR. ## Architecture rules See [CLAUDE.md](CLAUDE.md) for the full project structure, stack, and conventions. The critical ones: - `core/` must never import from `mcp/`, `cli/`, or `web/` - Every DB access must be wrapped in try/catch — never crash the MCP server - Paths always derived from `os.homedir()/.devcoach`, never hardcoded — the only overrides are the `DEVCOACH_DIR` env var (sandboxing) and `DEVCOACH_CLAUDE_DIR`/`CLAUDE_CONFIG_DIR` (where the onboarding scan looks for Claude Code's history) - `assets/` is the tracked source of truth (SKILL.md + web static) — edit there, not in `dist/`. `plugin/skills/` and `gemini-extension/skills/` are synced mirrors: never edit them directly, run `npm run plugin:sync` (tests assert byte-identity with `assets/`; it also pins the plugin, Gemini-extension and `server.json` versions to `package.json`) ## Submitting a PR 1. Fork the repo and create a branch from `develop` — the integration branch. `main` only ever receives releases (CI fast-forwards it when a release is cut), so it is always the last published version; a hotfix for the released version branches from `main` and is merged back into `develop` 2. Make your changes and confirm all checks pass 3. Open a PR against `develop` with a clear description of *what* and *why* — and **state any change you made to existing behaviour**. Every merge into `develop` publishes a canary (`npx -y devcoach@next`, docs at `/next/`); releases are cut from `develop` by the maintainer 4. Sign the **[Contributor License Agreement](CLA.md)** — the CLA Assistant bot comments on your PR with a one-line phrase to post; signing is required before merge Keep PRs focused. A change that fixes a bug and adds a feature should be two PRs. ## Licensing & the CLA devcoach is licensed under **AGPL-3.0**. No commercial license is offered today; if one is ever granted for a closed-source use, the maintainer must hold the right to relicense *every* contribution — so every contributor signs a lightweight [Contributor License Agreement](CLA.md) once: you confirm you have the right to contribute and you grant the maintainer the right to license your contribution under **both** AGPL and commercial terms. The [CLA Assistant](.github/workflows/cla.yml) bot handles this automatically on your first PR. See also: [Code of Conduct](CODE_OF_CONDUCT.md) · [Security policy](SECURITY.md) · [License](LICENSE). ## Testing with the MCP inspector ```bash npm run build npx @modelcontextprotocol/inspector node dist/bin.js mcp ``` ## Sandbox mode (keeps your real `~/.devcoach` safe) ```bash DEVCOACH_DIR=$(mktemp -d) node dist/bin.js stats # relocates coaching.db + the notebook + hook.log HOME=$(mktemp -d) npm run dev -- mcp # or sandbox the whole home dir ``` ## Building the Claude Desktop extension ```bash npm run mcpb # → dist-mcpb/devcoach-.mcpb npm run mcpb:sign # self-sign (shows as unverified publisher) ```