Contributing to System1-Omni

Review the README and architecture and integration contracts for the project's ownership boundaries and current implementation status before making changes.

Before implementation or a PR

Complete the human contributor-intent gate before implementation and before submitting a PR, including a draft. It records the human's outcome, highest-leverage variable, why the work moves it, customer and actual need, then whether a PR is needed at all. Reuse explicit traceable answers and ask only what is missing; wait rather than filling in answers for the contributor. Bug fixes need linked observed failure evidence. Keep private source material private. This contributor gate does not block independent read-only reviews or change automated review selection.

Adding a model

Keep model-specific preprocessing, execution and response formatting under src/models/<model>/; reusable hardware operations belong under src/backends/. Share serving infrastructure and extract shared model execution when multiple implementations need it.

Keep processors and batch adapters separate from the model's forward implementation, even when they live in the same model directory. The README's target architecture shares processing orchestration and scheduling across models. Native workers already reuse serial admission and dispatch; processing orchestration and GPU batching remain planned. Model executors own weights, forward passes, learned heads, and device state.

For native implementations, Rust owns host processing, scheduling, model orchestration, and backend bindings/dispatch. CUDA/Metal provide device operations used by models or processing modules. Document processor inputs, executor layouts and batch constraints, output reconstruction, and state/buffer lifetimes alongside the existing API and numerical contract. Keep current worker integration usable while further shared runtime components remain unimplemented.

All test bodies, test helpers and fixtures belong in the repository-level tests/ tree. Do not add inline test bodies or crate-local tests/ directories under src/. Register Rust integration tests with explicit [[test]] paths in the crate manifest. For tests of private items, only the #[cfg(test)] and external module-path wiring may remain in src/; the test implementation stays under root tests/. Existing tests under src/ do not change this rule for new contributions.

Document the model contract in src/models/<model>/README.md and setup, launch, example requests and validation in recipe/<model>/. Update the root README's supported-model status, recipe/README.md and the documentation navigation in mkdocs.yml. Update affected shared-component documentation when build or ABI requirements change, and state support and validation limits explicitly.

For agent-assisted implementation, use the add-new-model skill. For example:

Read .agents/skills/add-new-model/SKILL.md and use it to add support for this
model. Keep all tests under root tests/ and update the model docs and recipes.

Self-review before requesting review

Self-review your PR before marking it ready for review or requesting maintainer review. Open a draft PR if you want to share work in progress, and keep it in draft until the self-review is complete.

1. Read the full diff against the target branch, including tests and documentation. Fix issues you find and remove unrelated changes, unused code introduced by the PR, and unnecessary abstractions.
2. Check ownership against the architecture contracts: shared serving, independent processing and scheduling, model-specific adapters and execution, and hardware operations. Distinguish implemented layers from the target design and keep the scope focused on the PR's stated problem.
3. Run checks appropriate to the change. For Rust changes, use the commands below from the repository root; add or update tests when behavior changes. For documentation changes, check links, examples, and claims against the actual implementation.
4. Fill in the PR's purpose, test plan, and test results. Report the commands you ran, their results, and any checks you could not run with the reason. Support accuracy or performance claims with reproducible evidence, including the configuration and hardware used.
5. Re-read the PR description and complete the template's self-review checklist. Repeat the relevant checks after subsequent changes.

Choose validation by changed area

Use the current workflow files and component contracts as the source of truth. The matrix routes a change to relevant checks; it does not replace the full configured CI suite or establish branch-protection requirements. Run commands from the repository root and record the exact revision and environment.

Changed area	Fast feedback	Broader evidence / handoff
Documentation or review guidance	Check relative paths, heading anchors, examples and claims against current source.	Run the strict documentation build. No GPU benchmark is needed for documentation-only changes.
Rust workspace	Run the affected crate or test target, then the Rust CI checks.	Report pass, fail, ignored and unrun checks separately; CPU success does not establish CUDA or Metal support.
Frontend transport (src/frontend/)	cargo test -p omni-jev --test frontend --locked; include cargo test -p omni-jev --test forwarding_limits --test in_process --locked when those paths change.	Check request/response, failure and cancellation behavior against the frontend contract, then run Rust CI.
Native admission or execution interface (src/runtime/)	cargo test --locked -p omni-runtime	Check affected workers against the runtime contract and architecture invariants, then run Rust CI.
Benchmark tooling (benchmarks/, tests/benchmarks/)	Install benchmarks/requirements.txt; run python benchmarks/bench.py validate benchmarks/smoke.jsonl and python -m unittest discover -s tests/benchmarks -p 'test_*.py' -v.	Follow the benchmark protocol for performance claims. Tooling smoke tests are not model-quality or throughput measurements.
CUDA contract or backend tooling	Use the cuda-contract job's current commands and prerequisites in CI.	Text-based contract checks do not execute kernels. Changed native/device behavior needs the affected model recipe's hardware and numerical evidence.
Model processing, execution, batching or backend behavior	Select tests under root tests/ using the model's manifest, README and recipe.	Follow the architecture contracts, model/hardware coverage and model-specific validation recipe. Identify unsupported and untested configurations; arrange unavailable hardware checks with the maintainer.

The author supplies reproducible results and names any unresolved validation handoff. Maintainer review remains separate from author evidence. Do not claim merge authority or required-check settings from this matrix or passing CI alone. Before handing off, record the PR head, commands, results and evidence links, remaining blockers, and next action. Recheck evidence after a head change; same-head check reruns can also change the result. Report source inspection, personally executed tests and observed CI distinctly.

Rust CI checks

The Rust checks used by CI are:

cargo fmt --all --check
cargo clippy --workspace --locked --all-targets --features omni-laya/serve -- -D warnings
cargo test --workspace --locked --features omni-laya/serve
cargo build --workspace --release --locked --features omni-laya/serve

For an agent-assisted self-review, use the repository's precheck-pr skill. For example, ask your coding agent:

Read .agents/skills/precheck-pr/SKILL.md and use it to self-review my changes
before I mark this PR ready for review. Report findings and unverified checks.

The skill is optional; the self-review checklist applies to every contributor. A coding agent can help review the diff and identify issues, but contributors remain responsible for understanding the changes and verifying the results. Self-review helps maintainers focus on design and correctness; it does not replace maintainer review.

Documentation site

The site at https://thinkflowlab.github.io/system1-omni/ is built with MkDocs from the README, this guide, the frontend README and the Markdown files under recipe/ and docs/. mkdocs.yml sets the navigation and, in exclude_docs, the published files. Pages keep their repository paths, so write links as relative paths that work on GitHub; links to files that are not published go to GitHub. Put images in docs/assets/.

To run the check from the Docs workflow and preview the site, with Python 3.10 or later:

python3 -m venv .venv-docs
.venv-docs/bin/pip install -r docs/requirements.txt
.venv-docs/bin/mkdocs build --strict
.venv-docs/bin/mkdocs serve    # http://127.0.0.1:8001/system1-omni/