[ymstar]

Summary

Add CONTRIBUTING.md — a comprehensive guide for contributors covering development setup, project architecture, testing conventions, commit message format, and PR workflow.

This branch is built on top of @andreinknv's work from PR #97 (docs/ADDING-A-LANGUAGE.md), whose commits are preserved with original authorship. The contributing guide references their cookbook in the "Adding a New Language" section.

Changes

File	Change
CONTRIBUTING.md	New contributing guide (~250 lines)
README.md	Add Contributing section referencing CONTRIBUTING.md and docs/ADDING-A-LANGUAGE.md
CLAUDE.md	Add pointer to CONTRIBUTING.md in House rules

What it covers

• Prerequisites and development setup
• Project structure overview
• Making changes (types, extractors, MCP, installer)
• Adding a new language (references docs/ADDING-A-LANGUAGE.md)
• Testing philosophy and conventions
• Commit message format (Conventional Commits)
• PR checklist and review process
• Issue reporting guidelines

Attribution

Based on @andreinknv's ADDING-A-LANGUAGE.md cookbook (cherry-picked with original commit authorship preserved). The upstream PR was closed without merging, so the cookbook content was incorporated by cherry-picking the original commits to retain proper git attribution.

[Yisus423]

A small correction to a pointer in #648, since this issue is where the documentation gap lives.

#648 opens with:

There's an /add-lang workflow and a contributor cookbook (see #97 / docs/ADDING-A-LANGUAGE.md).

The first half is accurate — /add-lang is .claude/skills/add-lang/SKILL.md and it works. The second half points at a file that does not exist on main and never has. #97, which added it, was closed during the late-April PR stack cleanup (#120, "not a judgment on the idea itself"), and docs/ADDING-A-LANGUAGE.md did not land with it — both of these print nothing:

$ git log --all --oneline -- docs/ADDING-A-LANGUAGE.md
$ git ls-tree origin/main docs/ADDING-A-LANGUAGE.md

So a contributor following the tracker today reads that sentence, looks for the cookbook, and hits a 404. The living guidance is the skill file. If a cookbook is still wanted under this issue, that pointer is worth updating either way.

While measuring the drift, three things in SKILL.md no longer match the code — probably worth folding into whatever happens here:

1. Step 4.1 says to add '**/*.<ext>' to DEFAULT_CONFIG.include because it is "the file-scan allowlist". There is no DEFAULT_CONFIG in src/types.ts; the allowlist is EXTENSION_MAP, reached through isSourceFile(), and there is no glob step at all. The wiring is three files, not four.
2. Step 9 asks for a ### Added CHANGELOG section. The live format is ### New Features / ### Fixes with user-facing notes, per the root AGENTS.md.
3. Step 8 says the A/B runs on opus. scripts/agent-eval/run-all.sh defaults to sonnet / --effort high, and docs/AGENTS.md fixes that as policy (Sonnet as the deliberate floor model).

Found while adding Nim support (#2463).

[ymstar]

@Yisus423 Thanks for the feedback! The PR has been rebased onto the latest main and reworked:

• Removed docs/ADDING-A-LANGUAGE.md entirely — it was cherry-picked from the closed PR docs: cookbook for adding a new language extractor #97 and never landed on main. All references now point to the /add-lang skill (.claude/skills/add-lang/SKILL.md), which is the living guidance on main.
• Updated for current repo state: installer targets (4 → 11), MCP single-source-of-truth note (issue CLAUDE.md instructions duplicate MCP server instructions — wastes tokens every turn #529), CHANGELOG format guidance (### New Features / ### Fixes), project structure.
• Single clean commit on top of latest upstream/main — only 3 files changed (CONTRIBUTING.md new, README.md +6 lines, AGENTS.md +1 line).

Would appreciate a re-review when you have a chance.

[colbymchenry]

Thanks, @ymstar! The commit format, test commands, bug-report checklist and /add-lang pointer from this guide are now in CONTRIBUTING.md via #3081, with credit, so I'm closing this one.