diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..5051057 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,96 @@ +# Contributing to the Nexus + +## The Hard Rule + +**Every PR has a net addition limit of 10 lines.** + +Not a guideline. Not a target. A hard limit. + +If your change adds 40 lines, you find 30 lines to remove. If you +can't find lines to remove, your change is too big or you're +homebrewing something that already exists as a package. + +## Why + +The codebase must shrink or hold steady over time. New lines are +debt. The health metric is not features added — it's lines removed. + +This rule exists to enforce a philosophy: + +- **Import over invent.** If it exists in npm, pip, or another + module, use it. New code is a last resort. +- **Plug in the research.** The AI/ML ecosystem ships new + capabilities weekly. Wire them in. Don't reimplement them. +- **No builder trap.** Writing code feels productive. Shipping + the smallest possible change *is* productive. They are not + the same thing. +- **Removal is a first-class contribution.** A PR that deletes + 50 lines and the tests still pass is more valuable than one + that adds 50. + +## PR Requirements + +Every pull request must include: + +### 1. Net line diff within limit + +``` ++12 -8 = net +4 ✅ (under 10) ++40 -35 = net +5 ✅ (under 10) ++200 -0 = net +200 ❌ (rejected) ++200 -195 = net +5 ✅ (under 10) +``` + +### 2. Manual test plan + +Describe what you tested by hand. Not "it works" — specific +steps someone else can repeat: + +``` +## Test Plan +1. Started nexus_think.py with --model timmy:v0.1-q4 +2. Sent chat_message via WS: "Hello" +3. Verified agent_state changed to "thinking" +4. Verified chat_response returned within 30s +5. Checked experience.db — new row with perception + thought +``` + +### 3. Automated test results + +Paste the output of your test run. If no tests exist for the +code you're changing, write one — that counts toward your 10 +lines. + +``` +## Test Results +$ python -m pytest nexus/tests/ -v +test_perception_adapter.py::test_chat_message PASSED +test_perception_adapter.py::test_heartbeat_filtered PASSED +test_experience_store.py::test_record_and_recall PASSED +3 passed in 0.4s +``` + +## What This Means for Agents + +This rule applies to every contributor: human, Timmy, Claude, +Perplexity, Gemini, Kimi, Grok. No exceptions. + +An agent that can work within this constraint demonstrates +discipline, judgment, and the ability to find the smallest +change that solves the problem. An agent that can't is in +the builder trap. + +## Baseline + +As of 2026-03-25, the codebase is **4,462 lines** across all +source files. This number should go down, not up. + +## Exceptions + +The only exception is the initial commit of a new dependency's +config file (package.json, requirements.txt, etc.) that enables +importing existing work. Even then, prefer fewer dependencies +over more. + +There are no other exceptions. If the rule feels impossible, +the change is too big. Break it into smaller PRs.