mdrs-client-rust/AGENTS.md

Agents Guidelines

Project Overview

This project is a Rust command-line client for MDRS-based repositories.

• The binary entry point is src/main.rs
• CLI argument parsing is defined in src/cli.rs
• Command implementations live under src/commands/
• API access code lives under src/api/
• Shared domain types live under src/models/
• Login cache and runtime settings live under src/cache/ and src/settings.rs

Development Workflow

Cargo-first workflow

Prefer standard Cargo commands and existing project tooling over custom scripts or ad hoc edits.

Common commands:

• cargo fmt
• cargo test
• cargo build
• cargo run -- <args>

Formatting requirement

When you modify Rust code or any code that is formatted by the Rust toolchain, you must run cargo fmt before finishing the task.

Validation

Use the narrowest relevant validation for the change:

• documentation-only changes do not require Cargo validation
• for behavior changes, run the relevant Rust tests if they already exist
• if no targeted test exists, use the smallest existing Cargo command that meaningfully validates the modified area

Code Guidelines

Reuse project patterns

Before adding new code, inspect the existing command, API, and model modules and follow their established patterns.

In particular:

• keep CLI behavior consistent with the existing clap command structure
• prefer existing error handling patterns based on anyhow
• keep async behavior aligned with the current tokio-based implementation
• avoid duplicating logic that already exists in sibling command modules

Comments and documentation

All comments written inside source code must be in English.

This includes:

• line comments
• block comments
• doc comments

Documentation file language may follow the needs of the project, but source code comments must stay in English.

Planning and Review

Plan mode

When working in plan mode:

1. analyze the current codebase state first
2. write or update the implementation plan in the session plan file
3. require user review of the plan before starting implementation

Do not begin editing project files until the user has reviewed and approved the plan.

Git commits

Never run git commit without explicit user confirmation.

This requirement still applies after a plan has been reviewed or approved. Plan approval is not commit approval.

Git Commit Messages

Commit messages must always be written in English.

Follow the Conventional Commits format:

<type>(<scope>): <short description>

Use clear, imperative subjects without a trailing period.

Examples:

• feat(upload): add recursive directory support
• fix(login): handle expired cache gracefully
• docs(agents): add Rust project guidance

Practical Expectations for Agents

• make precise, minimal changes that fully solve the task
• read nearby modules before changing structure or introducing helpers
• prefer updating existing code paths over adding parallel implementations
• preserve current CLI semantics unless the task explicitly changes them
• surface uncertainties to the user instead of guessing on destructive actions