# Contributing to ritalin
Three-step contribution process.
## 1. Open an issue first
If you're touching the gate logic, scope contract format, or evidence ledger, open an issue describing what you want to change and why. These are load-bearing — we'd rather discuss before you write code.
For docs, examples, and new patterns, skip this step. Just open the PR.
## 2. Build and test
```bash
git clone https://github.com/paperfoot/ritalin-cli
cd ritalin
cargo build
cargo test
```
Smoke test the binary against the canonical workflow:
```bash
mkdir /tmp/ritalin-test && cd /tmp/ritalin-test
~/Projects/ritalin/target/debug/ritalin init --outcome "test"
~/Projects/ritalin/target/debug/ritalin add "must pass" --proof "true"
~/Projects/ritalin/target/debug/ritalin prove O-001
~/Projects/ritalin/target/debug/ritalin gate
# Should print PASS, exit 0, and remove .task-incomplete
```
## 3. Open the PR
- Keep PRs focused. One change per PR.
- Match the existing code style. Run `cargo fmt`.
- If you add a command, update `agent_info.rs` AND `SKILL.md`. The capability manifest is a contract.
- Sign-off optional, license is MIT.
## Design rules
These exist to keep ritalin small and load-bearing:
- **Append-only ledgers stay append-only.** No "edit" or "delete" commands. Mistakes are amended with new entries.
- **The binary stays lean.** ritalin composes with the ecosystem (`search`, `gh`, `engram`, etc.) via proof commands. Don't build network capabilities, memory, or search into the binary. Shell out.
- **The skill is the leverage.** The SKILL.md teaches agents how to reason. The binary enforces the contract. Most improvements to agent quality come from improving the skill, not adding commands.
- **Keep `agent-info` honest.** Every command listed there must be routable. Drift is a P0 bug.
- **Semantic exit codes only.** 0-4. No custom codes. The contract comes from [agent-cli-framework](https://github.com/paperfoot/agent-cli-framework).
- **Two output shapes max.** JSON envelope on pipes, coloured human on TTY. Stop hook decisions are the only exception.
## Releasing (maintainers)
1. Bump `version` in `Cargo.toml` and commit (`chore: bump to X.Y.Z`).
2. Tag and push: `git tag vX.Y.Z && git push origin main vX.Y.Z`.
3. The Release workflow builds the four target binaries, publishes to crates.io, and bumps `Formula/ritalin.rb` in [199-biotechnologies/homebrew-tap](https://github.com/199-biotechnologies/homebrew-tap). The cross-repo push uses the `HOMEBREW_TAP_DEPLOY_KEY` secret — an SSH deploy key whose public half is registered (write-enabled) on the tap. It's already configured; if it's ever rotated, generate a new `ed25519` keypair, add the public half to the tap's deploy keys with write access, and store the private half as the secret. Without the secret the job emits a warning and the formula must be bumped by hand.
A release isn't done until GitHub Releases, crates.io, **and** the tap serve the same version. A stale channel ships a binary that contradicts `SKILL.md` — the exact doc/build drift this tool exists to catch.
## Areas that need help
- **Proof templates** — pre-built proof commands for the `research_grounded`, `code_referenced`, and `model_current` obligation kinds that compose with ecosystem CLIs
- **Diff compiler** — `ritalin compile` to infer obligations from `git diff` against a `patterns.yaml`
- **Structured reasoning templates** — seed files for common reasoning patterns (hypothesis-driven, decomposition, grounding-first)
- **Benchmark suite** — measure whether ritalin actually improves agent output quality on SWE-bench, GPQA, ARC-AGI 3, and real-world tasks
- **Pattern library** — seed `patterns.yaml` rules for common stacks (Next.js, Rails, FastAPI, etc.)
- **Cadence governor** — `ritalin orient` as a periodic re-anchor for long sessions
## Code of conduct
Be kind. Disagree with the code, not the person. If something feels off, open an issue and we'll work it out.