# claude-code-team-kit

A drop-in starter for teams adopting Claude Code: a project guide (`CLAUDE.md`), two shared skills (`/review-pr`, `/release-notes`), a small MCP server with two tested tools, a safety hook, and a CI workflow. Zero runtime dependencies. Node 20+. MIT licensed.

> Built with AI tools, mainly Claude, under Julien Lerosty's supervision. He reviews and tests every delivery. The tests in this repo run offline and pass.

## What's in the box

| Path | What it is | Where it goes in your repo |
|---|---|---|
| `template/CLAUDE.template.md` | Project guide: commands, layout, conventions, working rules | `CLAUDE.md` (repo root) |
| `template/skills/review-pr/` | Skill: structured PR review with `file:line` findings | `.claude/skills/review-pr/` |
| `template/skills/release-notes/` | Skill: release notes from commits since the last tag | `.claude/skills/release-notes/` |
| `template/mcp.json` | Registers the MCP server | `.mcp.json` (repo root) |
| `src/mcp-server.js`, `src/tools.js` | stdio MCP server: `group_commits`, `scan_todos` | `src/` or any path (update `mcp.json`) |
| `hooks/guard-bash.mjs`, `hooks/settings.example.json` | PreToolUse hook that blocks force-push, `reset --hard`, `rm -rf /`, `curl \| sh` | `hooks/`; merge the JSON into `.claude/settings.json` |
| `.github/workflows/test.yml` | Runs the tests on Node 20 and 22 for every PR | `.github/workflows/` |
| `test/kit.test.js` | 8 tests covering the tools, the protocol and the hook | `test/` |

(The template files carry neutral names so they don't take effect inside this repo; copy them as shown.)

## Set it up in 15 minutes

**1. Copy the kit (2 min)** from this repo into your project:

```sh
KIT=/path/to/claude-code-team-kit
cp $KIT/template/CLAUDE.template.md  CLAUDE.md
mkdir -p .claude/skills src hooks test .github/workflows
cp -r $KIT/template/skills/*          .claude/skills/
cp $KIT/template/mcp.json             .mcp.json
cp $KIT/src/*.js                      src/
cp $KIT/hooks/guard-bash.mjs          hooks/
cp $KIT/.github/workflows/test.yml    .github/workflows/
cp $KIT/test/kit.test.js              test/
```

Your `package.json` needs `"type": "module"` and a `test` script (`node --test`). If your project is not Node, keep the server in a `tools/` folder and point `.mcp.json` at it.

**2. Fill in `CLAUDE.md` (5 min).** Replace every `[bracketed]` line with real facts: install, test, lint and run commands, the folder layout, your conventions. Keep it short; Claude reads it at the start of every session. The most valuable line is the test command, because it lets Claude verify its own work.

**3. Turn on the hook (2 min).** Merge `hooks/settings.example.json` into `.claude/settings.json`. The first entry blocks risky shell commands; the second runs your tests after every edit (delete it if your suite is slow).

**4. Start Claude Code and approve the MCP server (2 min).** Run `claude` in the project. It asks once whether to trust the `team-kit` server from `.mcp.json`. Run `/mcp` to confirm it is connected and lists two tools.

**5. Try the skills (3 min).**
- On a branch with changes: `/review-pr`. You get a summary and findings grouped as must-fix / should-consider / nice-to-have.
- After a few commits: `/release-notes`. Claude reads the commit subjects, calls `group_commits`, then rewrites them for readers.

**6. Commit it all (1 min).** `CLAUDE.md`, `.claude/skills/`, `.mcp.json`, `hooks/` and the workflow are meant to be shared: every teammate gets the same behavior after `git pull`. Keep personal tweaks in `.claude/settings.local.json`, which is not shared.

## Real output

Everything below was produced by running the code in this repo.

`group_commits` over five commit subjects (called through the MCP server on stdio):

```
### Breaking changes
- drop the v1 endpoint

### Features
- **api:** add retry with backoff
- drop the v1 endpoint

### Fixes
- handle empty CSV input

### Documentation
- explain setup

### Other
- bump deps
```

The hook, given `git push --force origin main`:

```
Force-push is blocked. Ask a human.      (exit code 2: the command does not run)
```

## The tools

- **`group_commits(subjects: string[])`** groups Conventional Commit subjects (`feat`, `fix`, `perf`, `refactor`, `docs`, `test`, `chore`) into Markdown. `!` marks a breaking change, which is listed first. Anything that doesn't parse goes under "Other" instead of being dropped.
- **`scan_todos(path?: string)`** lists `TODO`/`FIXME`/`HACK`/`XXX` comments with `file:line`. It cannot read outside the project root, skips `node_modules`, `.git` and build folders, and caps results at 200.

To add a tool, append an entry to `TOOLS` in `src/tools.js` (`name`, `description`, `inputSchema`, `run`) and add a test.

## Run the tests

```sh
npm test      # 8 tests, offline, no install step
```

## What I'd build for you

This kit is the generic version. For a team engagement I adapt it to your stack and workflow: a `CLAUDE.md` written from your actual repo, skills for your review checklist and release process, MCP tools wired to your internal systems (issue tracker, docs, deploy status), hooks matching your safety rules, permission settings, and a short walkthrough for the team.

## Honest limits

- The MCP server is a small hand-written implementation of the tools part of the protocol (initialize, tools/list, tools/call, ping). For servers with resources, prompts or auth, use the official MCP SDK.
- The skills and `CLAUDE.md` follow Claude Code's documented conventions, but the skills themselves were verified here only for structure (frontmatter and file layout), not by a live Claude session.
- The hook is a guard rail, not a security boundary; use Claude Code's permission settings for hard limits.

## License

MIT, see `LICENSE`.

## Hire me

I build small, tested automations like this one for clients.

- Upwork: https://www.upwork.com/freelancers/~011ec6fab9b610aea9

AI tools, mainly Claude, are used under my supervision; I review and test every delivery.