kimi-wire: Instructions file for Codex

kimi-wire Agent Guide

This file contains agent-level conventions for the kimi-wire crate — a standalone Rust library for the Kimi Code CLI Wire Protocol.

Contents

• Meta Principle
• Behavioral Guidelines
• Library Contract Rules
• Rust Safety Rules
• Error Handling Doctrine
• Wire Protocol Compatibility
• Build & Test
• Clippy Lint Policy
• Editing Rules

Meta Principle

Before applying any rule or refactor, ask: what problem does this solve? A newtype, a refactor, or an abstraction is justified only if it prevents a concrete bug, clarifies an invariant, or removes a footgun. If the answer is "it looks better" — revert. Decoration is not engineering.

Behavioral Guidelines

• State assumptions explicitly. If uncertain, ask before implementing.
• Minimum code. No speculative abstractions. No features beyond the request. If you write 200 lines and it could be 50, rewrite.
• Surgical changes only. Touch only what you must. Match existing style. Remove imports/variables made unused by your changes; don't delete pre-existing dead code unless asked.
• Goal-driven execution. Every task needs verifiable success criteria and a brief plan (Step → verify: check).
• Prefer ? over unwrap/expect even in tests where it keeps the test readable.

Library Contract Rules (Hard Constraints)

These rules protect the crate's most fragile contracts: the public API surface, serde correctness, and Wire protocol compatibility.

1. Public API is opt-in. Prefer pub(crate). New pub items require a concrete external caller or a paved-path rationale, plus a test.
2. Protocol facts must not go stale. If event names, request names, or method parameters change, update README.md, CHANGELOG.md, and tests in the same change set.
3. Serde roundtrip is a hard contract. Any change to Event, Request, ContentPart, DisplayBlock, or method params/result types must include a serde roundtrip test. The envelope format ({"type":"...","payload":{...}}) must be preserved.
4. Dependencies are architecture changes. No new crate without a rationale: why std/local code is not enough, transitive impact, MSRV, license, and feature-flag consequences. Small helper crates are rejected by default.
5. Refactors isolate mechanics from behavior. File moves, splits, renames, and formatting-only changes must be separate from semantic changes whenever practical.
6. MSRV is 1.80. Do not use language or std features introduced after Rust 1.80.