Contributing Guide

Relevant source files

The following files were used as context for generating this wiki page:

• CONTRIBUTING.md
• CODE_OF_CONDUCT.md
• AGENTS.md
• src/AGENTS.md
• wiki/AGENTS.md
• ARCHITECTURE.md
• blueprints/provider/_generic.md

This guide outlines the standards, technical requirements, and workflows for contributing to shunt, a Claude Code LLM gateway. As an early-stage project, it prioritizes architectural consistency, protocol fidelity, and strict adherence to established engineering specs.

Contributors are expected to follow the development lifecycle, ensuring that all code remains focused, well-tested, and synchronized with the Architecture and documentation.

Sources: CONTRIBUTING.md:1-6, AGENTS.md:1-2

Development Environment

shunt is a Rust project built on the 2021 edition. Development requires a stable Rust toolchain and Cargo.

Core Commands

Action	Command
Build Project	cargo build
Run Gateway	cargo run -- run
Validate Config	cargo run -- check
Check Formatting	cargo fmt --all --check
Run Lints	cargo clippy --all-targets --all-features -- -D warnings
Run Tests	cargo test --all-features --workspace

Sources: CONTRIBUTING.md:8-13, AGENTS.md:6-15, src/AGENTS.md:6-14

Local Build Optimization

Contributors can optionally use sccache to speed up local compilations. To enable this, set RUSTC_WRAPPER=sccache in the environment or via a local .cargo/config.toml. For maximum benefit across branch switches, disabling incremental compilation (CARGO_INCREMENTAL=0) is recommended as it conflicts with sccache caching.

Sources: CONTRIBUTING.md:20-41

Workflow and Standards

Contribution Lifecycle

The project follows a specific workflow to maintain high code quality and architectural integrity.

The diagram shows the standard progression from initial research to CI validation.
Sources: CONTRIBUTING.md:15-18, AGENTS.md:33-51, blueprints/provider/_generic.md:99-105

Code Style Guidelines

• Language: All code, comments, and documentation must be in English.
• File Size: Individual source files should ideally remain under 500 lines. Modules should be split as they grow beyond this limit.
• Commits: Use Conventional Commits (e.g., feat:, fix:, docs:).
• GitHub Actions: Third-party actions must be pinned to a full 40-character commit SHA.

Sources: CONTRIBUTING.md:46-48, CONTRIBUTING.md:52-53, AGENTS.md:33-35, AGENTS.md:58-59

Architectural Invariants

Contributors must respect the following core principles when modifying the gateway:

1. Preserve Streaming: Upstream SSE responses must never be buffered unless the client specifically requested non-streaming output.
2. Error Shaping: Gateway-owned errors must follow the Anthropic error shape (using the ShuntError or UpstreamError types).
3. Table-Driven Configuration: New providers and models should be added via configuration tables (TOML/YAML) rather than hardcoded logic.
4. Security Boundaries: Never weaken credential origin checks or commit secrets.

Sources: ARCHITECTURE.md:104-122, blueprints/provider/_generic.md:69-75

Implementing New Providers

Adding a new provider protocol requires a systematic approach to ensure it integrates with the existing adapter system.

Integration Strategy

The sequence illustrates the touchpoints for a new provider implementation.
Sources: blueprints/provider/_generic.md:19-33, ARCHITECTURE.md:46-60

Decision Tree: Adapter vs. Preset

Before implementing a new adapter, contributors should check if the provider fits an existing "kind":

• anthropic: Uses Anthropic Messages API and SSE format.
• responses: Uses OpenAI Responses API.
• cursor: Uses Cursor ConnectRPC/protobuf.

If the protocol is compatible, only a configuration preset is required. A new adapter is only necessary if wire evidence proves existing protocols cannot represent the provider.

Sources: blueprints/provider/_generic.md:19-29, ARCHITECTURE.md:88-100

Testing Requirements

Every PR must include focused test coverage. Modifications to existing behavior require updating tests rather than weakening them.

• Unit Tests: Place in-module using #[cfg(test)].
• Integration Tests: Located in tests/, covering protocol translation, auth, and gateway endpoints.
• Mocking: Use wiremock for upstream provider simulation.
• Coverage: Aim for >80% coverage for new code.

Sources: ARCHITECTURE.md:143-150, AGENTS.md:62-63, blueprints/provider/_generic.md:80-92

Documentation Maintenance

Code and documentation must remain synchronized. A PR that changes observable behavior must update:

1. README.md: For capability or supported provider changes.
2. docs/: Relevant engineering specs or milestone notes.
3. site/: User-facing documentation (Nimbus/Astro).
4. wiki/: While wiki/ is generated and should not be hand-edited, it must be regenerated if source materials change.

Sources: AGENTS.md:38-51, wiki/AGENTS.md:18-22, blueprints/provider/_generic.md:112-118

Ethical Standards

Participation is governed by the project's Code of Conduct. We pledge to provide a harassment-free experience for everyone. Contributors are expected to demonstrate empathy, accept constructive feedback, and focus on what is best for the community.

Sources: CODE_OF_CONDUCT.md:3-13