Contributing

The engine isn't public yet, so this page describes how contribution will work once it opens, not how to file a PR today. A few conventions will keep the contribution loop smooth.

Where to start

• CLAUDE.md in the repo for the developer guide (architecture, conventions, current state)
• docs/VISION.md for the product philosophy
• tests/ directory for ~500 tests that demonstrate intended behaviour

The workflow

1. Fork the repo, branch off main.
2. Write a failing test first when the change is behavioural. Soriku follows RCT discipline (Red, Commit, Green).
3. Keep the PR focused: one feature or fix per PR, not a grab bag.
4. Run python -m pytest tests/ -v before pushing.
5. Open the PR with the test plan in the description.

Engineering principles

• RCT discipline: failing test first, smallest possible commit, then make it green
• Determinism over cleverness: the router and benchmarks must be reproducible
• Measured, not claimed: capability changes need benchmark evidence
• Local-first: features that only work in cloud mode go behind a clear feature gate
• Honesty in errors: don't swallow exceptions, surface root causes
• Compact diffs: small PRs review and merge faster

Improving these docs

This site's docs are hand-written and pulled from the engine's internal reference material (API surface, persona definitions, config schema) as that material changes.

Security issues

Don't open public issues for security vulnerabilities. Mail security@atypisch.nl. Coordinated disclosure within 90 days.